@llmrelai/sdk

TypeScript SDK for the Relai LLM gateway with multi-region support.

Installation

npm install @llmrelai/sdk

Quick Start

import Relai from "@llmrelai/sdk";

// Single API key (simplest setup)
const relai = new Relai({ apiKey: process.env.RELAI_KEY! });

// Chat completion
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 (Purist Approach)

For organizations requiring strict data residency, use separate accounts and keys per region:

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

// Route EU customer requests to EU region
const euResponse = await relai.chat.completions.create(
  { model: "reasoning/cheapest", messages: [...] },
  { region: "eu" }
);

// Route US customer requests to US region
const usResponse = await relai.chat.completions.create(
  { model: "reasoning/cheapest", messages: [...] },
  { region: "us" }
);

Global Keys (Pragmatist Approach)

Use a single global key with per-call routing:

const relai = new Relai({
  apiKey: process.env.RELAI_GLOBAL_KEY!, // relai_sk_gbl_<region>_live_...
});

// Route to specific regions for dispatch
await relai.chat.completions.create(
  { model: "reasoning/cheapest", messages: [...] },
  { region: "eu" } // Request dispatched from EU gateway
);

Per-User Metering

Track usage per end-user:

// Create or update an end user
await relai.users.create({
  external_id: "user_123",
  monthly_quota_dollars: 10.0,
  daily_quota_dollars: 1.0,
  alert_threshold: 0.8,
});

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

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

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

Access Relai-specific APIs:

// Balance
const balance = await relai.balance.get();
console.log(`Credits: $${balance.credits_dollars}`);

// Usage statistics
const usage = await relai.usage.list({
  from: "2024-01-01T00:00:00Z",
  to: "2024-01-31T23:59:59Z",
});
console.log(`Total requests: ${usage.total_requests}`);

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

// Organization settings
const settings = await relai.orgs.settings.get("my-org");
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) {
    console.error("Invalid API key");
  } else if (error instanceof InsufficientBalanceError) {
    console.error("Add credits to continue");
  } else if (error instanceof EndUserQuotaExceededError) {
    console.error(`User exceeded ${error.period} quota`);
  } else if (error instanceof RateLimitError) {
    console.error("Too many requests, retry later");
  }
}

API Reference

Constructor Options

| Option | Type | Description | |--------|------|-------------| | apiKey | string | Single API key | | keys | { eu?: string, us?: string } | Multi-region keys | | defaultRegion | "eu" \| "us" | Default region for requests | | baseURL | string | Override gateway URL | | timeout | number | Request timeout (ms) | | maxRetries | number | Max retry attempts |

Request Options

| Option | Type | Description | |--------|------|-------------| | region | "eu" \| "us" | Target region | | signal | AbortSignal | Cancellation signal | | headers | Record<string, string> | Additional headers |

License

MIT