O'Route TypeScript SDK

13 AI models, one API, auto-optimized routing. 100% Anthropic /messages API compatible.

Quick Start (3 minutes)

1. Install

npm install oroute-sdk

2. Get your API key

Sign up at oroute.itshin.com and copy your API key from the API Keys page.

3. Send your first request

import { ORoute } from 'oroute-sdk';

const client = new ORoute({ apiKey: 'or-your-api-key' });

// Non-streaming
const msg = await client.messages.create({
  model: 'auto',          // auto-routes to the best model
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain quantum computing in one sentence.' }],
});
console.log(msg.content[0].text);
console.log('Model used:', msg.model);

// Streaming
const stream = await client.messages.stream({
  model: 'auto',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a haiku about TypeScript.' }],
});
for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
    process.stdout.write(event.delta.text);
  }
}

// Track session usage
console.log(client.getUsage()); // { requests: 2, tokens: 312, cost: 0.004 }

That's it. O'Route automatically selects the best AI model (Claude, GPT, Gemini, DeepSeek, Qwen) based on your prompt complexity, target speed, and cost.

Installation

npm install oroute-sdk

Quick Start (3 lines)

import { ORoute } from 'oroute-sdk';

const client = new ORoute({ apiKey: 'or-your-api-key' });

const message = await client.messages.create({
  model: 'auto',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }],
});

console.log(message.content[0].text);

That's it. O'Route automatically selects the best AI model (Claude, GPT, Gemini, DeepSeek, Qwen) based on your prompt.

Streaming

const stream = await client.messages.stream({
  model: 'auto',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a haiku about TypeScript.' }],
});

for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
    process.stdout.write(event.delta.text);
  }
}

Tool Use

const message = await client.messages.create({
  model: 'auto',
  max_tokens: 1024,
  tools: [
    {
      name: 'get_weather',
      description: 'Get current weather for a location',
      input_schema: {
        type: 'object',
        properties: {
          location: { type: 'string', description: 'City and state, e.g. "San Francisco, CA"' },
        },
        required: ['location'],
      },
    },
  ],
  messages: [{ role: 'user', content: 'What is the weather in San Francisco?' }],
});

if (message.stop_reason === 'tool_use') {
  const toolUse = message.content.find((block) => block.type === 'tool_use');
  console.log(`Tool: ${toolUse.name}, Input:`, toolUse.input);
}

Migration from Anthropic SDK

O'Route is a drop-in replacement. Change 2 lines:

// Before (Anthropic SDK)                    // After (O'Route SDK)
import Anthropic from '@anthropic-ai/sdk';   import { ORoute } from 'oroute-sdk';
const client = new Anthropic();              const client = new ORoute({ apiKey: 'or-...' });

// Everything else stays the same
const msg = await client.messages.create({
  model: 'claude-sonnet-4-20250514',         // or use 'auto' for smart routing
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});

| Feature | Anthropic SDK | O'Route SDK | |---------|--------------|-------------| | messages.create() | Yes | Yes (identical) | | messages.stream() | Yes | Yes (identical) | | Tool use | Yes | Yes (identical) | | Vision / images | Yes | Yes (identical) | | System prompts | Yes | Yes (identical) | | Error classes | Yes | Yes (identical names) | | Auto model selection | No | Yes (model: 'auto') | | Routing modes | No | Yes (mode: 'quality_first') | | Multi-provider | No | Yes (13 models) |

Configuration

const client = new ORoute({
  // Required
  apiKey: 'or-your-api-key',

  // Optional
  baseURL: 'https://api.oroute.itshin.com',  // Custom API endpoint
  maxRetries: 3,                               // Max retry attempts (default: 3)
  timeout: 60000,                              // Request timeout in ms (default: 60s)
  defaultMode: 'balanced',                     // Default routing mode
});

Routing Modes

| Mode | Description | |------|-------------| | balanced | Best mix of quality, speed, and cost (default) | | quality_first | Prefer the highest-quality model | | speed_first | Prefer the fastest model | | cost_first | Prefer the cheapest model |

// Per-request mode override
const msg = await client.messages.create({
  model: 'auto',
  max_tokens: 1024,
  mode: 'cost_first',
  messages: [{ role: 'user', content: 'Simple question' }],
});

Error Handling

import { ORoute, AuthenticationError, RateLimitError, BadRequestError } from 'oroute-sdk';

try {
  const msg = await client.messages.create({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401 — Invalid API key
    console.error('Auth failed:', error.message);
  } else if (error instanceof RateLimitError) {
    // 429 — Rate limited (auto-retried, this fires after all retries exhausted)
    console.error('Rate limited. Retry after:', error.retryAfterMs, 'ms');
  } else if (error instanceof BadRequestError) {
    // 400 — Invalid request parameters
    console.error('Bad request:', error.message);
  }
}

All error classes:

| Class | Status | When | |-------|--------|------| | AuthenticationError | 401 | Invalid or missing API key | | BadRequestError | 400 | Invalid request parameters | | PermissionDeniedError | 403 | Insufficient permissions | | NotFoundError | 404 | Model or resource not found | | RateLimitError | 429 | Rate limit exceeded | | InternalServerError | 500 | Server error |

Every error exposes: status, message, code, requestId, headers.

Retry Behavior

The SDK automatically retries on transient failures:

| Error | Retries | Backoff | |-------|---------|---------| | 429 Rate Limit | Up to maxRetries | Exponential: 1s, 2s, 4s... (max 30s) | | 500/502/503 | Up to maxRetries | Exponential: 1s, 2s, 4s... (max 30s) | | Timeout | Once | 1s | | 400/401/403/404 | None | N/A |

The Retry-After header is respected when present.

Routing Metadata

Every response includes O'Route routing metadata:

const msg = await client.messages.create({ model: 'auto', ... });

console.log(msg.oroute);
// {
//   actual_model: 'gpt-4o',
//   routing_mode: 'balanced',
//   complexity: 'simple',
//   latency_ms: 420,
//   estimated_cost_usd: 0.002,
// }

TypeScript

Full type definitions included. All Anthropic message types are available:

import type {
  MessageCreateParams,
  MessageResponse,
  ContentBlock,
  TextBlock,
  ToolUseBlock,
  StreamEvent,
  Usage,
} from 'oroute-sdk';

Performance

O'Route routing adds <15ms overhead to each request. The SDK itself adds <5ms (serialization, header parsing, retry logic). Total end-to-end overhead is negligible compared to typical LLM inference times of 500ms-30s.

| Component | Overhead | |-----------|----------| | SDK (serialize + parse) | <5ms | | O'Route routing decision | <15ms | | Provider inference | 500ms - 30s |

API Stability

As of v1.0.0, the O'Route SDK follows Semantic Versioning:

• Patch (1.0.x): Bug fixes, no API changes
• Minor (1.x.0): New features, backward-compatible
• Major (x.0.0): Breaking changes (with migration guide)

The following APIs are stable and will not change without a major version bump:

• ORoute constructor and configuration options
• client.messages.create() — parameters and response shape
• client.messages.stream() — event types and iteration protocol
• All error classes (AuthenticationError, RateLimitError, etc.)
• Type exports (MessageCreateParams, MessageResponse, etc.)

TypeScript Support

Full IntelliSense support in VS Code, WebStorm, and other TypeScript-aware editors.

All types are bundled with the package — no need for separate @types/ installs.

Links

• Developer Docs
• API Reference
• Error Guide
• GitHub

License

MIT