TypeScript SDK

@llmrelai/sdk is the native TypeScript client for the Relai gateway. It supports chat completions, multi-region routing, per-user metering, and direct access to Relai-specific resources.

Installation

npm install @llmrelai/sdk

Quick Start

import Relai from "@llmrelai/sdk";

const relai = new Relai({ apiKey: process.env.RELAI_API_KEY! });

const response = await relai.chat.completions.create({
  model: "reasoning/cheapest",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);

Multi-Region Support

Regional Keys

For strict data residency, use a separate key per region. Each request is routed to the matching regional gateway.

const relai = new Relai({
  keys: {
    eu: process.env.RELAI_KEY_EU!,
    us: process.env.RELAI_KEY_US!,
  },
});

await relai.chat.completions.create(
  { model: "reasoning/cheapest", messages: [/* ... */] },
  { region: "eu" }
);

Global Keys

A single global key (relai_sk_gbl_<region>_live_…) works across both regions. Per-call routing controls which gateway runs the request; billing always settles in the key's home region.

const relai = new Relai({
  apiKey: process.env.RELAI_GLOBAL_KEY!,
});

await relai.chat.completions.create(
  { model: "reasoning/cheapest", messages: [/* ... */] },
  { region: "eu" }
);

See Regions & Key Scopes for the full residency model.

Per-User Metering

await relai.users.create({
  external_id: "user_123",
  monthly_quota_dollars: 10.0,
  daily_quota_dollars: 1.0,
  alert_threshold: 0.8,
});

const response = await relai.chat.completions.create({
  model: "reasoning/cheapest",
  messages: [/* ... */],
  user: "user_123",
});

if (response.relai?.warnings) {
  for (const warning of response.relai.warnings) {
    console.log(`${warning.code}: ${warning.message}`);
  }
}

See Per-User Limits for the full quota model.

Streaming

const stream = await relai.chat.completions.create(
  {
    model: "reasoning/cheapest",
    messages: [/* ... */],
    stream: true,
  },
  {
    onWarning: (warning) => {
      console.log(`Warning: ${warning.message}`);
    },
  }
);

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

Native Resources

// Balance
const balance = await relai.balance.get();

// Usage
const usage = await relai.usage.list({
  from: "2024-01-01T00:00:00Z",
  to: "2024-01-31T23:59:59Z",
});

// Keys
const keys = await relai.keys.list();
const newKey = await relai.keys.create({
  name: "Production Key",
  scope: "regional",
});

// Org settings
await relai.orgs.settings.update("my-org", {
  default_user_monthly_quota_dollars: 50.0,
});

// Billing ledger
const ledger = await relai.billing.ledger.list({ limit: 10 });

Error Handling

import {
  AuthenticationError,
  InsufficientBalanceError,
  EndUserQuotaExceededError,
  RateLimitError,
} from "@llmrelai/sdk";

try {
  await relai.chat.completions.create({/* ... */});
} catch (error) {
  if (error instanceof AuthenticationError) {
    // invalid API key
  } else if (error instanceof InsufficientBalanceError) {
    // top up credits
  } else if (error instanceof EndUserQuotaExceededError) {
    // user exceeded quota
  } else if (error instanceof RateLimitError) {
    // back off and retry
  }
}

See Errors for the full taxonomy.

Constructor Options

Resources

• npm: @llmrelai/sdk
• Vercel AI SDK Provider
• API Reference