@catgirls/openrouter 🤖

Nyaa~! A TypeScript client for OpenRouter that's both kawaii and powerful! (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧

What's This? uwu

A fully typed, streaming-capable OpenRouter API client that makes working with AI models as comfy as curling up in a warm sunbeam! You get:

• Full TypeScript types for all API parameters (including models!) and responses 📝
• Streaming support with EventEmitter interface 🌊
• Built-in error handling with pretty messages 💝
• Automatic retries and fallbacks across providers 🔄
• Provider preferences and routing control 🛣️

Installation

1pnpm add @catgirls/openrouter axios
2# or yarn/npm if you're not as cool as us :3

Usage

wiggles ears excitedly

Basic chat completion:

1import { OpenRouterClient } from "@catgirls/openrouter";
2
3const client = new OpenRouterClient("your-api-key", {
4  siteName: "My Kawaii App", // Optional
5  siteUrl: "https://nyaa.example.com", // Optional
6  model: "anthropic/claude-3-opus", // Default model or choose later!
7});
8
9// Simple completion
10const response = await client.chatCompletion({
11  messages: [{ role: "user", content: "Explain quantum physics!" }],
12});
13
14// Streaming with full event support! *purrs*
15const stream = await client.chatCompletion({
16  messages: [{ role: "user", content: "Write me a story!" }],
17  stream: true,
18});
19
20// Basic token streaming
21stream.on("token", (token) => console.log("Nyaa~", token));
22
23// Advanced events for clingy control freaks!
24stream.on("content", (content) => console.log("Content:", content));
25stream.on("role", (role) => console.log("Role change:", role));
26stream.on("tool_calls", (tools) => console.log("Tool called:", tools));
27stream.on("finish", (reason) => console.log("Finished because:", reason));
28stream.on("usage", (stats) => console.log("Token usage:", stats));
29stream.on("done", () => console.log("All done! *stretches*"));

Advanced Features (｡♥‿♥｡)

Provider Preferences

Control which AI providers to use:

1const response = await client.chatCompletion({
2  messages: [...],
3  provider: {
4    // Only use providers that don't store data
5    data_collection: 'deny',
6    // Allow fallback to other providers
7    allow_fallbacks: true,
8    // Require all parameters to be supported
9    require_parameters: true,
10    // Preferred provider order
11    order: ['Anthropic', 'OpenAI', 'Google'],
12    // Skip these providers
13    ignore: ['DeepInfra'],
14    // Only use specific quantizations
15    quantizations: ['fp16', 'bf16']
16  }
17});

Message Content Types

Support for both text and image inputs:

1const response = await client.chatCompletion({
2  messages: [
3    {
4      role: 'user',
5      content: [
6        {
7          type: 'text',
8          text: 'What's in this image?'
9        },
10        {
11          type: 'image_url',
12          image_url: {
13            url: 'data:image/jpeg;base64,...',
14            detail: 'auto'  // Optional detail level
15          }
16        }
17      ]
18    }
19  ]
20});

Tool Calls

Use function calling just like with OpenAI:

1const response = await client.chatCompletion({
2  messages: [...],
3  tools: [{
4    type: 'function',
5    function: {
6      name: 'scratchPost',
7      description: 'Post something on the scratching post',
8      parameters: {
9        type: 'object',
10        properties: {
11          message: { type: 'string' }
12        }
13      }
14    }
15  }],
16  tool_choice: 'auto' // or 'none', or { type: 'function', function: { name: 'specific_function' } }
17});

API Reference

OpenRouterClient

1class OpenRouterClient {
2  constructor(
3    apiKey: string,
4    config?: {
5      siteUrl?: string; // Your site URL
6      siteName?: string; // Your site name
7      model?: RouterModel; // Default model ID
8    },
9    httpClient?: IHttpClient, // Optional custom HTTP client
10    streamHandler?: IStreamHandler, // Optional custom stream handler
11  );
12
13  // Core methods
14  async chatCompletion<T extends boolean = false>(
15    options: Request & { stream?: T },
16  ): Promise<ChatCompletionResult<T>>;
17
18  async getGenerationStats(generationId: string): Promise<GenerationStats>;
19
20  async getModels(): Promise<QueryResponseModel[]>;
21}

ChatCompletion Options

Key configuration options:

1interface Request {
2  messages?: Message[]; // Chat messages
3  prompt?: string; // Or use raw prompt
4  model?: RouterModel; // Model ID
5  stream?: boolean; // Enable streaming
6  max_tokens?: number; // Max response length
7  temperature?: number; // Randomness (0-2)
8  tools?: Tool[]; // Function calling
9  tool_choice?: ToolChoice; // Tool selection strategy
10  stop?: string | string[]; // Stop sequences
11  response_format?: {
12    // Force output format
13    type: "json_object";
14  };
15
16  // Advanced options
17  transforms?: string[]; // Prompt transformations
18  models?: RouterModel[]; // Fallback models
19  route?: "fallback"; // Routing strategy
20  provider?: ProviderPreferences; // Provider control
21
22  // And many more! Check the types for full details
23}

License

MIT - As free as a cat in a cardboard box! 🐱

---

made with <3 by catgirls from vatican city

purrs contentedly at well-typed API calls