@orsa.dev/sdk

Official TypeScript SDK for Orsa.dev — web data extraction & brand intelligence.

Install

npm install @orsa.dev/sdk
# or
bun add @orsa.dev/sdk
# or
pnpm add @orsa.dev/sdk

Requires Node ≥ 18 (native fetch). Ships ESM + CJS + TypeScript types.

Quick start

import Orsa from '@orsa.dev/sdk';

const client = new Orsa({ apiKey: process.env.ORSA_API_KEY! });

// Brand intelligence
const brand = await client.brand.retrieve({ domain: 'stripe.com' });
console.log(brand.title);              // "Stripe"
console.log(brand.colors[0]);          // { hex: "#635BFF", name: "Iris" }
console.log(brand.logos[0]?.url);      // logo URL

// Web scraping
const page = await client.web.scrape({ url: 'https://stripe.com/docs' });
console.log(page.markdown);

// AI extraction
const ans = await client.ai.query({
  domain: 'stripe.com',
  dataToExtract: 'Return pricing plans as a JSON array.',
});
console.log(ans.result);

Every method returns the unwrapped response payload — you don't need to reach into .data yourself.

Configuration

new Orsa({
  apiKey: 'or_live_...',           // required
  baseUrl: 'https://api.orsa.dev', // override for self-hosted or staging
  timeout: 30_000,                  // per-request timeout in ms (default 30s)
  maxRetries: 3,                    // retry on 429/5xx and connection errors
  userAgent: 'my-app/1.0',          // appended after the SDK identifier
});

Each method also accepts a per-call RequestOptions:

const ac = new AbortController();
await client.brand.retrieve({ domain: 'stripe.com' }, {
  signal: ac.signal,
  timeout: 5_000,
  headers: { 'x-correlation-id': 'abc' },
});

Resources

client.brand

| Method | Endpoint | Returns | |---|---|---| | retrieve({ domain, refresh? }) | GET /v1/brand/retrieve | BrandContextDev (arrays + *_legacy mirrors) | | retrieveByDomain({ domain }) | GET /v1/brand/retrieve-by-domain | Brand (legacy dict shape) | | retrieveByName({ name }) | GET /v1/brand/retrieve-by-name | BrandSearchResult (top + candidates) | | retrieveByEmail({ email }) | GET /v1/brand/retrieve-by-email | Brand | | retrieveByTicker({ ticker }) | GET /v1/brand/retrieve-by-ticker | Brand | | retrieveByISIN({ isin }) | GET /v1/brand/retrieve-by-isin | Brand | | retrieveSimplified({ domain }) | GET /v1/brand/retrieve-simplified | SimplifiedBrand | | screenshot({ domain }) | GET /v1/brand/screenshot | Screenshot (inline base64 PNG) | | styleguide({ domain }) | GET /v1/brand/styleguide | Styleguide (W3C-DTCG tokens + DESIGN.md) | | fonts({ domain }) | GET /v1/brand/fonts | FontsResult | | naics({ domain }) | GET /v1/brand/naics | NaicsResult (industries array) | | transactionIdentifier({ transactionInfo }) | GET /v1/brand/transaction-identifier | TransactionIdentifierResult |

client.web

| Method | Endpoint | Returns | |---|---|---| | scrape({ url, mode?, jsRendering? }) | GET /v1/web/scrape/template | ScrapeResult (markdown | html | text based on mode) | | scrapeImages({ url }) | GET /v1/web/scrape/images | ScrapeImagesResult (with role classification) | | scrapeSitemap({ domain }) | GET /v1/web/scrape/sitemap | ScrapeSitemapResult (urls + path-grouped buckets) |

client.ai

| Method | Endpoint | Returns | |---|---|---| | query({ domain, dataToExtract }) | POST /v1/brand/ai/query | AIQueryResult (free-form string result) | | products({ domain }) | GET /v1/brand/ai/products | AIProductsResult (tool-use enforced schema) |

Errors

All errors extend OrsaError:

import {
  OrsaError,           // base class
  OrsaAPIError,        // 4xx/5xx response after retries — has `.status`, `.errorCode`, `.requestId`
  OrsaTimeoutError,    // request exceeded the timeout / was aborted
  OrsaConnectionError, // network failure after retries
} from '@orsa.dev/sdk';

try {
  await client.brand.retrieve({ domain: 'stripe.com' });
} catch (err) {
  if (err instanceof OrsaAPIError && err.status === 404) {
    console.log('No brand cached yet');
  } else if (err instanceof OrsaTimeoutError) {
    console.log('Took too long');
  } else {
    throw err;
  }
}

Retries are automatic for 429, 500, 502, 503 and connection errors (exponential backoff, honors Retry-After). 4xx errors throw immediately without retry.

Documentation

Full API reference: docs.orsa.dev/api-reference Get an API key: orsa.dev/dashboard/api-keys

License

MIT — © Orsa