TypeScript SDK

The official TypeScript SDK for Routeplane. Routeplane is a subclass of the official openai client, so you point your existing OpenAI code at the gateway, change nothing else, and get multi-provider fallback, sovereign routing, and FinOps attribution for free. A zero-dependency core client is available when you don't want the openai peer. Requires Node.js 18+ (native fetch).

typescriptnpm

npm i @routeplane/sdk        # openai is an optional peer dependency

The 30-second version

Construct a Routeplane client with your gateway key and default routing, then use the OpenAI API exactly as you do today.

typescriptRouteplane client

import { Routeplane } from '@routeplane/sdk';

const client = new Routeplane({
  apiKey: process.env.ROUTEPLANE_API_KEY!, // rp_...
  provider: 'openai,anthropic',            // try OpenAI, fall back to Anthropic
  residency: 'IN',                         // keep regulated data in-region
  useCase: 'support-bot',                  // FinOps cost attribution
});

// Exactly the OpenAI SDK you already know:
const completion = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Say hello in one word.' }],
});
console.log(completion.choices[0]?.message.content);

Per-request steering and metadata

createChatCompletion takes the OpenAI body plus a typed options object of x-routeplane-* steering, and returns the completion with a decoded routeplane metadata block — which provider actually served it, the cache disposition, and more.

typescriptcreateChatCompletion

const withMeta = await client.createChatCompletion(
  { model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Ping' }] },
  { strategy: 'cost', idempotencyKey: 'ping-1' },
);

console.log(withMeta.routeplane.provider); // which provider actually served it
console.log(withMeta.routeplane.cache);    // 'hit' | 'miss' | 'bypass'

Streaming with metadata

createChatCompletionStream returns the OpenAI chunk stream plus the decoded routeplane metadata, which arrives on the response headers before the first chunk.

typescriptcreateChatCompletionStream

const { stream, routeplane } = await client.createChatCompletionStream({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Explain sovereign routing' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

console.log(`\nServed by: ${routeplane.provider}`);

Zero-dependency core client

If you don't want the openai peer dependency, import the core client and the typed header builder from @routeplane/sdk/core. This is also what the CLI and MCP server are built on.

typescript@routeplane/sdk/core

import { RouteplaneCoreClient, createHeaders } from '@routeplane/sdk/core';

const core = new RouteplaneCoreClient({ apiKey: process.env.ROUTEPLANE_API_KEY! });

// The non-OpenAI surfaces — typed namespaces:
const status = await core.status.get();
const logs = await core.logs.list({ limit: 10 });
const usage = await core.finops.usage();
const rendered = await core.prompts.render('welcome-v2', { name: 'Rohit' });
await core.cache.purge();

// Build the x-routeplane-* headers yourself for any transport:
const headers = createHeaders({ provider: 'gemini', strategy: 'latency', residency: 'IN' });

Core resource namespaces

The core client exposes the surfaces OpenAI clients don't know about:

Namespace	What it covers
`core.prompts`	Fetch, render, and complete stored prompt templates.
`core.logs`	Recent request logs.
`core.analytics`	Recent usage analytics events.
`core.finops`	FinOps usage over a date range.
`core.cache`	Cache stats and purge.
`core.feedback`	Attach quality scores to prior requests.
`core.status`	Gateway health and per-provider circuit state.
`core.residency`	Sovereign-routing decisions and ledger.
`core.models`	The gateway model catalog.
`core.providers`	Custom OpenAI-compatible providers.

The `createHeaders` builder with any client

createHeaders() returns a plain header map, so it drops into anything that forwards headers to the OpenAI API — including the stock openai client and framework providers, without adopting the Routeplane subclass.

typescriptstock openai + createHeaders

import OpenAI from 'openai';
import { createHeaders } from '@routeplane/sdk/core';

const client = new OpenAI({
  apiKey: 'rp_your_gateway_key',
  baseURL: 'https://api.routeplane.ai/v1',
  defaultHeaders: {
    'x-routeplane-api-key': 'rp_your_gateway_key',
    ...createHeaders({ provider: 'anthropic,openai', strategy: 'cost' }),
  },
});

Vercel AI SDK

The createHeaders builder returns a plain header map, so it drops straight into the @ai-sdk/openai provider's headers option — every request routed through it carries your gateway steering.

typescript@ai-sdk/openai

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
import { createHeaders } from '@routeplane/sdk/core';

const rp = createOpenAI({
  apiKey: 'rp_your_gateway_key',
  baseURL: 'https://api.routeplane.ai/v1',
  headers: createHeaders({ provider: 'anthropic', strategy: 'cost' }),
});

const { text } = await generateText({
  model: rp('gpt-4o'),
  prompt: 'What is data residency?',
});

Package entry points

Import	Gives you
`@routeplane/sdk`	The `Routeplane` drop-in OpenAI subclass (needs the `openai` peer).
`@routeplane/sdk/core`	`RouteplaneCoreClient` + `createHeaders` — zero dependencies.
`@routeplane/sdk/openai`	The OpenAI-integration layer on its own.