TypeScript SDK

The orakle npm package — typed pricing jobs over SSE, with streaming callbacks and AbortSignal support.

Published as orakle on npm. Ships ESM and CJS. Requires Node.js 22+ (uses the global fetch and AbortController) and works in modern browsers.

Install

pnpm add orakle

npm install orakle

priceCheck

Submits a job, opens the SSE stream, and resolves with the final result. Rejects with an OrakleError of kind: "job_failed" on a failed event.

const result = await orakle.priceCheck({
  request_type: "nl",
  query: "iPhone 15 Pro 256GB unlocked mint",
  geography: "US",
});

console.log(result.fused_distribution.quantiles);
// { "0.05": 740, "0.1": 780, "0.25": 820, "0.5": 870, "0.75": 920, "0.9": 960, "0.95": 1010 }

geography is one of "US" | "GB" | "CA" | "AU" | "AE" and is optional. webhook_url is also accepted on both request shapes.

priceCheckStream

Yields every JobEvent as it arrives — stage, partial, then a terminal completed or failed — and ends after the terminal event.

for await (const event of orakle.priceCheckStream({
  request_type: "nl",
  query: "PS5 Disc Edition",
})) {
  if (event.event_type === "stage") {
    console.log(event.stage, event.message);
  }
  if (event.event_type === "completed") {
    console.log(event.result.fused_distribution.quantiles);
  }
  if (event.event_type === "failed") {
    console.error(event.code, event.message);
  }
}

priceCheckStream does not throw on a failed event — it yields it and returns. It still throws on transport, timeout, and HTTP errors.

Options

Both methods take an optional second argument:

Prop

Type

const result = await orakle.priceCheck(
  { request_type: "nl", query: "MacBook Air M3 16GB" },
  {
    timeoutSec: 300,
    onProgress: (e) => console.log(`[${e.stage}] ${e.message}`),
    onPartial: (e) => renderPlaceholder(e.result.product_profile),
  },
);

Cancellation

Pass an AbortSignal to cancel an in-flight job. The promise rejects with the signal's abort reason — a plain DOMException, distinct from the SDK's own OrakleError of kind: "timeout".

const controller = new AbortController();
setTimeout(() => controller.abort(), 10_000);

try {
  await orakle.priceCheck(
    { request_type: "nl", query: "..." },
    { signal: controller.signal },
  );
} catch (err) {
  if (err instanceof DOMException && err.name === "AbortError") {
    console.log("Cancelled by caller");
  }
}

Every SDK failure is a single OrakleError class carrying a kind literal and optional per-kind fields. Branch with the exported predicates — they narrow status, code, timeoutSec, and cause without casts.

`kind`	Predicate	When	Extra fields
`http`	`isHttpError(err)`	Non-2xx HTTP response — the job never started.	`status`, `code`
`job_failed`	`isJobFailedError(err)`	Job was accepted but failed in the pipeline (`failed` SSE).	`code`
`timeout`	`isTimeoutError(err)`	The job exceeded the effective timeout.	`timeoutSec`
`connection`	`isConnectionError(err)`	Network, DNS, or transport failure.	`cause`
`config`	`isConfigError(err)`	Caller misconfigured the client (bad `baseUrl`, bad byte cap).	—
`protocol`	`isProtocolError(err)`	Server/transport violated the SSE contract.	—

import {
  OrakleError,
  isHttpError,
  isJobFailedError,
  isTimeoutError,
  isConnectionError,
  isConfigError,
  isProtocolError,
} from "orakle";

try {
  await orakle.priceCheck({ request_type: "nl", query: "..." });
} catch (err) {
  if (!(err instanceof OrakleError)) throw err;
  // Predicates (not `switch (err.kind)`) so `status`, `code`, `timeoutSec`, and
  // `cause` narrow to non-optional inside each branch without `!` or `as`.
  if (isHttpError(err)) console.error(err.code, err.status);
  else if (isJobFailedError(err)) console.error(err.code);
  else if (isTimeoutError(err)) console.error(err.timeoutSec);
  else if (isConnectionError(err)) console.error(err.cause);
  else if (isConfigError(err) || isProtocolError(err)) console.error(err.message);
}

The http and job_failed kinds share the same ErrorCode taxonomy: invalid_request, auth_required, rate_limited, job_not_found, insufficient_data, internal_error, service_unavailable.

The raw API and MCP surfaces use the same public error-code taxonomy.

Result shape

priceCheck resolves with a PriceCheckResult:

Prop

Type

The SSE primitive createSSEStream is also exported for server-side proxies that re-emit a sanitized stream to the browser.