TypeScript SDK

@roadie/sdk is the first-party TypeScript SDK for the Roadie data plane. It is isomorphic — it runs on Node 20+, browsers, and React Native / Expo over the WHATWG fetch + streams standard — and ships with zero runtime dependencies. It wraps the data plane with typed errors, automatic retries, idempotency, timeouts, and streaming.

Prefer to keep your existing OpenAI code? Point the official OpenAI SDK at Roadie instead — see Using OpenAI SDKs. Both hit the same gateway.

Install

npm i @roadie/sdk

Roadie is pre-1.0 (0.x); changes inside /v1 are additive.

Authentication

The client is constructed in exactly one of two modes — supplying both, or neither, throws a RoadieConfigurationError.

import { Roadie } from '@roadie/sdk';

// Trusted backend only. Reads the rd_sk_… secret key from the environment.
const roadie = new Roadie({ apiKey: process.env.ROADIE_KEY! });

import { Roadie } from '@roadie/sdk';

// Browser / React Native. The SDK caches + refreshes the short-lived token.
const roadie = new Roadie({
  tokenProvider: async () => (await fetch('/api/roadie-token')).text(),
});

A secret key (rd_sk_…) grants full access to your project’s data plane. Constructing the client with one in a browser-like environment (where window is defined) throws immediately — pass dangerouslyAllowBrowser: true only if you are certain the code runs server-side. Client apps must authenticate with a tokenProvider; see Client tokens and Authentication.

Client options

Both modes accept these options (plus exactly one of apiKey / tokenProvider):

Option	Type	Default	Notes
`baseUrl`	`string`	Data-plane base URL — set only for a self-hosted or regional gateway.
`maxRetries`	`number`	`2`	Max automatic retries for transient, pre-first-byte failures.
`timeoutMs`	`number`	none	Default per-request deadline; a per-call `timeoutMs` overrides it.
`user`	`EndUser`	none	Default end-user identity, applied when a call omits `user`.
`metadata`	`Record<string, string>`	none	Default metadata, shallow-merged under each call’s `metadata`.
`fetch`	`FetchLike`	global `fetch`	Custom fetch (tests, proxies, non-standard runtimes).
`dangerouslyAllowBrowser`	`boolean`	`false`	Opt out of the browser secret-key guard. Trusted server code only.

Quickstart

roadie.chat.create returns the normalized response — the assistant message, finish_reason, token usage, an estimated cost, and the gateway requestId.

const res = await roadie.chat.create({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'system', content: 'You are a concise assistant.' },
    { role: 'user', content: 'In one sentence, what is Roadie?' },
  ],
  user: { id: 'user_42', plan: 'pro' },
});

const text = res.message.content.map((part) => part.text).join('');
console.log(text, res.usage, res.cost?.estimated_usd, res.requestId);

model accepts an explicit provider/model id (like openai/gpt-4o) or a project alias you configure (like smart) that fails over across providers. See Models, aliases & fallback.

Method surface

Every resource method accepts a trailing options object with signal?: AbortSignal and timeoutMs?: number (streaming also accepts framing?: 'sse' | 'ndjson').

Method	Returns	Purpose
`roadie.chat.create(params, options?)`	`UnifiedChatResponse & ResponseMetadata`	Non-streaming completion (`POST /v1/chat`).
`roadie.chat.stream(params, options?)`	`ChatStream`	Streaming completion; an async-iterable of stream events.
`roadie.embeddings.create(params, options?)`	`UnifiedEmbeddingResponse & ResponseMetadata`	Embeddings (`POST /v1/embeddings`).
`roadie.feedback.submit(params, options?)`	`FeedbackResult`	Thumbs-up/down on a prior response (`POST /v1/feedback`).

ChatParams is a chat request minus stream: model, messages, and the optional temperature, max_output_tokens, response_format, tools, tool_choice, user, metadata, and provider_options. EmbeddingsParams is model, input (a string or string array), and the optional dimensions, user, metadata, provider_options.

Response metadata

Every result carries the gateway requestId and a rateLimit snapshot as non-enumerable properties, so JSON.stringify(res) still yields exactly the wire body:

res.requestId;              // string | undefined  (X-Request-Id)
res.rateLimit;              // { limit?, remaining?, reset? } | undefined  (X-RateLimit-*)

Streaming

roadie.chat.stream(...) returns a ChatStream synchronously; the HTTP connection is opened lazily on the first for await step. Iterate the unified frames — content_delta carries incremental text and the terminal message_end carries the final usage and cost:

const stream = roadie.chat.stream(
  { model: 'openai/gpt-4o', messages },
  { timeoutMs: 60_000 },
);

for await (const event of stream) {
  if (event.type === 'content_delta') process.stdout.write(event.delta);
  else if (event.type === 'message_end') console.log('\n', event.usage, event.cost);
}

stream.requestId;           // populated once iteration connects

Frame types are message_start, content_delta, tool_call_delta, usage, message_end, and a terminal error frame for a mid-stream failure (nothing follows it). Cancel a stream (or any call) with an AbortSignal; breaking out of the loop closes the socket. NDJSON framing is available via { framing: 'ndjson' }. See Streaming.

Feedback

roadie.feedback.submit rates a prior response by its gateway requestId:

await roadie.feedback.submit({ requestId: res.requestId!, rating: 'up', comment: 'Great answer.' });

rating is 'up' or 'down'. (The endpoint also accepts a 1–5 numeric score, but the SDK deliberately exposes only thumbs.)

Client tokens

Client apps never hold a secret key. Supply a tokenProvider — a () => string | Promise<string> the SDK caches and refreshes (at 80% of the token’s TTL, single-flighting concurrent refreshes).

Path A (backend mint). Your backend mints a client token; the app fetches it. The provider is just the fetch: tokenProvider: async () => (await fetch('/api/roadie-token')).text().
Path B (federated identity, no backend). Exchange your existing IdP token (Firebase, Auth0, Supabase, Cognito, …) plus your publishable key for a client token with the federatedTokenProvider helper:

import { Roadie, federatedTokenProvider } from '@roadie/sdk';

const roadie = new Roadie({
  tokenProvider: federatedTokenProvider({
    publishableKey: 'rd_pk_prod_…',
    getIdentityToken: () => auth.currentUser!.getIdToken(),
    baseUrl: 'https://gateway.roadie.paroaria.ai',
    // ttlSeconds is optional; the gateway clamps to ≤ 3600.
  }),
});

TokenManager and the TokenProvider type are exported for advanced cases. See Client tokens and the zero-backend federated identity tutorial.

Error handling

Every failure is a RoadieError subclass carrying a stable code, the requestId, the HTTP status, and (for rate limits) retryAfter. Branch on the class, or use isRoadieError(err) and read err.type / err.code.

import {
  RateLimitError,
  QuotaError,
  BudgetError,
  AuthenticationError,
  isRoadieError,
} from '@roadie/sdk';

try {
  const res = await roadie.chat.create({ model: 'openai/gpt-4o', messages });
} catch (err) {
  if (err instanceof RateLimitError) {
    // Transient: back off and retry after err.retryAfter seconds.
  } else if (err instanceof QuotaError) {
    // A usage window is exhausted — surface a "limit reached" state.
  } else if (err instanceof BudgetError) {
    // The spend budget cap was hit (HTTP 402).
  } else if (err instanceof AuthenticationError) {
    // The key/token is missing, wrong, or revoked.
  } else if (isRoadieError(err)) {
    console.error(err.type, err.code, err.requestId);
  }
}

Envelope-mapped classes (one per gateway error type): InvalidRequestError, AuthenticationError, PermissionError, NotFoundError, RateLimitError, QuotaError, BudgetError, ProviderError, IdempotencyError, InternalError. Client-side classes: APIConnectionError, APIConnectionTimeoutError (the request exceeded its timeoutMs), APIUserAbortError (the caller aborted via its own AbortSignal), and RoadieConfigurationError. The SDK already retries transient failures (network errors, 429, 5xx) before they reach you, honoring Retry-After, and reuses one auto Idempotency-Key across those retries so a retried create is de-duplicated by the gateway. See Errors & retries and the full error reference.

Not included

This SDK is a focused client for the data-plane runtime surface. It intentionally does not cover:

Model catalog — there is no roadie.models.list. Aliases and provider/model ids resolve server-side; browse the catalog via the raw GET /v1/models endpoint or the Python SDK.
Request cancellation endpoint — there is no cancel method. Abort an in-flight request client-side with an AbortSignal.
Images — no image resource. Generate images through the OpenAI-compatible surface (or RoadieKit on iOS).
Backend client-token minting (Path A) — there is no roadie.client_tokens.create. Mint tokens from your backend with the Python SDK or POST /v1/client-tokens; this SDK covers the Path-B exchange via federatedTokenProvider.
Control-plane management (projects, keys, budgets). That is the separate management API.

Next steps

Node quickstart

A 10-minute server integration, every snippet run in CI.

Next.js quickstart

Wrap the SDK in a server-side route.

Client tokens

Authenticate browser and mobile apps safely.

Error reference

Every error type and code, with how to handle each.

Get started

Core concepts

Guides

SDKs

TypeScript SDK

Install

Authentication

Client options

Quickstart

Method surface

Response metadata

Streaming

Feedback

Client tokens

Error handling

Not included

Next steps

Node quickstart

Next.js quickstart

Client tokens

Error reference

​Install

​Authentication

​Client options

​Quickstart

​Method surface

​Response metadata

​Streaming

​Feedback

​Client tokens

​Error handling

​Not included

​Next steps

Node quickstart

Next.js quickstart

Client tokens

Error reference

Install

Authentication

Client options

Quickstart

Method surface

Response metadata

Streaming

Feedback

Client tokens

Error handling

Not included

Next steps