### Install OpenRouter Kit using npm, yarn, or pnpm

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

This snippet shows the commands to install the openrouter-kit library using different package managers. It is a prerequisite for using the library.

```bash
npm install openrouter-kit
# or
yarn add openrouter-kit
# or
pnpm add openrouter-kit
```

--------------------------------

### Initialize OpenRouterClient with Configuration

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

Illustrates the initialization of the OpenRouter client with a configuration object. Key settings include the API key, model, history adapter, and debugging preferences. This setup is crucial for establishing a connection and defining client behavior.

```javascript
const client = new OpenRouterClient({
  apiKey: "YOUR_OPENROUTER_API_KEY",
  model: "mix/lmsys/vicuna-7b-v1.5",
  historyAdapter: new MemoryHistoryStorage(),
  debug: true
});
```

--------------------------------

### Generate Simple Response with OpenRouterClient in TypeScript

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

This example demonstrates how to initialize the OpenRouterClient and make a simple chat request to an LLM. It shows how to specify the model, temperature, and handle the response, including model usage and token counts. Error handling is also included. Ensure OPENROUTER_API_KEY is set in your environment.

```typescript
// simple-chat.ts
import { OpenRouterClient } from 'openrouter-kit';

// Initialize the client with your API key
const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: "x-ai/grok-4-fast" // Default model for all calls
});

async function main() {
  console.log('Sending a simple request...');
  try {
    const result = await client.chat({
      prompt: 'Write a short greeting for a README.',
      model: 'openai/gpt-4o-mini', // Override the model for this call
      temperature: 0.7,
    });

    console.log('--- Result ---');
    console.log('Model Response:', result.content);
    console.log('Model Used:', result.model);
    console.log('Tokens Used:', result.usage);
  } catch (error: any) {
    console.error("Error:", error.message);
  } finally {
    await client.destroy();
  }
}

main();

```

--------------------------------

### JavaScript Function Calling with Detailed Tool Execution Reports

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

This JavaScript example illustrates how to define and use tools (functions) with the OpenRouter client. It emphasizes retrieving detailed reports for each tool call, including success/error status, execution duration, and parsed arguments. The example includes mock data and asynchronous tool execution for simulating external API calls. Requires the 'openrouter-kit' package and an OPENROUTER_API_KEY environment variable.

```javascript
// tools-example.js (CommonJS)
const { OpenRouterClient } = require("openrouter-kit");

// --- Example Data (replace with your real sources) ---
const users = [ { id: "user_1001", nick: "alice" }, { id: "user_1002", nick: "bob" } ];
const messages = [ { id: "msg_101", userId: "user_1001", content: "Hi from alice!" }, { id: "msg_102", userId: "user_1002", content: "Hi from bob!" } ];
// ---

// --- Tool Definitions ---
const userTools = [
  {
    type: "function",
    function: {
      name: "getUserIdByNick",
      description: "Gets the user ID by their nickname",
      parameters: { type: "object", properties: { nick: { type: "string" } }, required: ["nick"] },
    },
    execute: async (args) => {
      console.log(`[Tool Execute: getUserIdByNick] Args: ${JSON.stringify(args)}`);
      const user = users.find(u => u.nick.toLowerCase() === args.nick.toLowerCase());
      // Simulate slight delay
      await new Promise(res => setTimeout(res, 50));
      return user ? { userId: user.id, found: true } : { userId: null, found: false };
    }
  },
  {
    type: "function",
    function: {
      name: "getUserMessages",
      description: "Gets all messages for a user by their ID",
      parameters: { type: "object", properties: { userId: { type: "string" } }, required: ["userId"] },
    },
    execute: async (args) => {
      console.log(`[Tool Execute: getUserMessages] Args: ${JSON.stringify(args)}`);
      const userMessages = messages.filter(m => m.userId === args.userId);
      // Simulate slight delay
      await new Promise(res => setTimeout(res, 100));
      return { messages: userMessages, count: userMessages.length, found: userMessages.length > 0 };
    }
  }
];
// ---

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || "sk-or-v1-...",
  model: "x-ai/grok-4-fast", // Model that supports tools
});

async function main() {
  try {
    const promptAlice = "Find all messages from user alice.";
    console.log(`\nPrompt: "${promptAlice}"`);
    const resultAlice = await client.chat({
      prompt: promptAlice,
      tools: userTools,
      temperature: 0.5,
      includeToolResultInReport: true // <-- Request full call details
    });
    console.log(`Response:\n${resultAlice.content}`);
    console.log(`(Total Tool Calls: ${resultAlice.toolCallsCount})`);

    // --- Display Tool Call Details ---
    if (resultAlice.toolCalls && resultAlice.toolCalls.length > 0) {
        console.log("\n--- Tool Call Details ---");
        resultAlice.toolCalls.forEach((call, index) => {
            console.log(`Call ${index + 1}:`);
            console.log(`  Tool Name: ${call.toolName}`);
            console.log(`  Status: ${call.status}`);
            console.log(`  Duration: ${call.durationMs}ms`);
            if (call.status === 'success') {
                 // Display result because includeToolResultInReport: true
                 console.log(`  Result:`, call.result);
            } else if (call.error) {
                 console.log(`  Error: ${call.error.message} (Type: ${call.error.type})`);
            }
            console.log(`  Arguments (Parsed):`, call.parsedArgs);
            console.log("-------------------------");
        });
    }
    // ---

  } catch (error) {
    console.error("\n--- Error ---");
    console.error(error);
  } finally {
    await client.destroy();
  }
}

main();

```

--------------------------------

### JavaScript: Execute Functions with Tools using OpenRouter Client

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

Demonstrates how to define tools with JSON Schema validation and execute them automatically based on model decisions using the OpenRouterClient. It includes examples for a weather tool and a calculator tool, showcasing how to process tool calls and their results.

```javascript
const { OpenRouterClient } = require('openrouter-kit');

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: 'x-ai/grok-4-fast'
});

const weatherTool = {
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get current weather information for a city',
    parameters: {
      type: 'object',
      properties: {
        city: { type: 'string', description: 'City name' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' }
      },
      required: ['city']
    }
  },
  execute: async (args, context) => {
    console.log(`[Tool] Fetching weather for ${args.city}...`);
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 100));
    return {
      city: args.city,
      temperature: 22,
      unit: args.unit || 'celsius',
      condition: 'Sunny',
      humidity: 65
    };
  }
};

const calculatorTool = {
  type: 'function',
  function: {
    name: 'calculate',
    description: 'Perform mathematical calculations',
    parameters: {
      type: 'object',
      properties: {
        operation: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] },
        a: { type: 'number' },
        b: { type: 'number' }
      },
      required: ['operation', 'a', 'b']
    }
  },
  execute: async (args) => {
    const { operation, a, b } = args;
    const operations = {
      add: a + b,
      subtract: a - b,
      multiply: a * b,
      divide: b !== 0 ? a / b : null
    };
    const result = operations[operation];
    if (result === null) throw new Error('Division by zero');
    return result;
  }
};

async function toolExample() {
  try {
    const result = await client.chat({
      prompt: 'What is the weather in London? Also calculate 15 * 7',
      tools: [weatherTool, calculatorTool],
      temperature: 0.5,
      includeToolResultInReport: true
    });

    console.log('Response:', result.content);
    console.log('Tool Calls Made:', result.toolCallsCount);

    // Access detailed tool call information
    if (result.toolCalls && result.toolCalls.length > 0) {
      console.log('\n=== Tool Call Details ===');
      result.toolCalls.forEach((call, idx) => {
        console.log(`\nCall ${idx + 1}:`);
        console.log('  Tool:', call.toolName);
        console.log('  Status:', call.status);
        console.log('  Duration:', `${call.durationMs}ms`);
        console.log('  Arguments:', call.parsedArgs);
        if (call.status === 'success') {
          console.log('  Result:', call.result);
        } else if (call.error) {
          console.log('  Error:', call.error.message);
        }
      });
    }
  } catch (error) {
    console.error('Error:', error.message);
  } finally {
    await client.destroy();
  }
}

toolExample();

```

--------------------------------

### Configure Model and Provider Routing Strategies

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

This example demonstrates how to configure routing for models and providers. You can specify fallback models globally or per request, and control provider selection using default configurations or per-request options. The configuration allows setting the order of providers, enabling/disabling fallbacks, ignoring specific providers, requiring parameter support, filtering by data policy or quantization, and sorting.

```typescript
import { OpenRouterClient, OpenRouterConfig, OpenRouterRequestOptions, ProviderRouting } from 'openrouter';

// Example global configuration for routing
const globalConfig: OpenRouterConfig = {
  apiKey: 'YOUR_API_KEY',
  modelFallbacks: ['openai/gpt-3.5-turbo', 'google/gemini-pro'],
  defaultProviderRouting: {
    order: ['openai', 'anthropic', 'google'],
    allow_fallbacks: true,
    ignore: ['provider-to-ignore'],
    require_parameters: ['temperature', 'top_p'],
    data_collection: ['opt_in', 'opt_out'],
    quantizations: ['8bit', '4bit'],
    sort: 'latency'
  }
};

const client = new OpenRouterClient(globalConfig);

async function makeRequestWithSpecificRouting() {
  const requestOptions: OpenRouterRequestOptions = {
    model: 'openai/gpt-4o-mini', // Specific model for this request
    models: ['openai/gpt-4o-mini', 'openai/gpt-4'], // Request-specific model fallbacks
    provider: 'openai', // Force a specific provider
    providerRouting: {
      order: ['openai', 'togetherai'],
      allow_fallbacks: false,
      ignore: ['provider-to-ignore-for-this-request'],
      require_parameters: ['temperature'],
      data_collection: ['opt_in'],
      quantizations: ['4bit'],
      sort: 'quality'
    }
  };

  try {
    const result = await client.chat.completions.create({
      ...requestOptions,
      messages: [{ role: 'user', content: 'Tell me a joke.' }]
    });
    console.log('Response with specific routing:', result.content);
  } catch (error) {
    console.error('Error during routed request:', error);
  }
}

makeRequestWithSpecificRouting();

```

--------------------------------

### Send Chat Request with History Management in TypeScript

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

Demonstrates sending chat messages using the OpenRouterClient, with automatic conversation history tracking per user. It includes handling API metadata, cost information, and potential errors. The example requires the 'openrouter-kit' package and uses a MemoryHistoryStorage adapter.

```typescript
import { OpenRouterClient, MemoryHistoryStorage } from 'openrouter-kit';

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: 'openai/gpt-4o-mini',
  historyAdapter: new MemoryHistoryStorage(),
  enableCostTracking: true
});

async function conversationExample() {
  try {
    const userId = 'user-123';

    // First message - establishes context
    const response1 = await client.chat({
      user: userId,
      prompt: 'My name is Alice and I love Python programming.',
      temperature: 0.7
    });
    console.log('Bot:', response1.content);
    console.log('Cost:', response1.cost ? `$${response1.cost.toFixed(8)}` : 'N/A');
    console.log('Tokens:', response1.usage);

    // Second message - uses stored history automatically
    const response2 = await client.chat({
      user: userId,
      prompt: 'What programming language did I mention?',
      temperature: 0.7
    });
    console.log('Bot:', response2.content);
    console.log('Duration:', `${response2.durationMs}ms`);

  } catch (error) {
    console.error('Error:', error.message);
    if (error.code) console.error('Code:', error.code);
  } finally {
    await client.destroy();
  }
}

conversationExample();
```

--------------------------------

### Stream Chat with Tool Execution - JavaScript

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

Streams chat responses chunk-by-chunk, enabling real-time output and supporting automatic tool execution. It uses `openrouter-kit` with a `MemoryHistoryStorage` and provides callbacks for handling stream events, tool calls, and errors. The example defines a `search_web` tool for external information retrieval.

```javascript
const { OpenRouterClient, MemoryHistoryStorage } = require('openrouter-kit');

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: 'x-ai/grok-4-fast',
  historyAdapter: new MemoryHistoryStorage(),
  enableCostTracking: true
});

const searchTool = {
  type: 'function',
  function: {
    name: 'search_web',
    description: 'Search the web for current information',
    parameters: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query' }
      },
      required: ['query']
    }
  },
  execute: async (args) => {
    await new Promise(resolve => setTimeout(resolve, 500));
    return {
      query: args.query,
      results: [
        { title: 'Result 1', snippet: 'Information about ' + args.query },
        { title: 'Result 2', snippet: 'More details on ' + args.query }
      ]
    };
  }
};

async function streamingExample() {
  try {
    console.log('Starting stream...\n');

    const result = await client.chatStream({
      prompt: 'Search for recent AI developments and write a summary',
      user: 'stream-user-1',
      tools: [searchTool],
      temperature: 0.7,
      streamCallbacks: {
        onContent: (content) => {
          // Print each content chunk as it arrives
          process.stdout.write(content);
        },
        onToolCallExecuting: (toolName, args) => {
          console.log(`\n\n[Tool Executing] ${toolName}`, args);
        },
        onToolCallResult: (toolName, result) => {
          console.log(`[Tool Result] ${toolName}:`, result);
          console.log('\nContinuing stream...\n');
        },
        onComplete: (fullContent, usage, toolCalls) => {
          console.log('\n\n=== Stream Complete ===');
          console.log('Total tokens:', usage?.total_tokens);
          console.log('Tools called:', toolCalls?.length || 0);
        },
        onError: (error) => {
          console.error('\nStream error:', error.message);
        }
      }
    });

    console.log('\n\nFinal result cost:', result.cost ? `$${result.cost.toFixed(6)}` : 'N/A');
    console.log('Duration:', `${result.durationMs}ms`);
    console.log('Model:', result.model);

  } catch (error) {
    console.error('Error:', error.message);
  } finally {
    await client.destroy();
  }
}

streamingExample();

```

--------------------------------

### Configure Reasoning Tokens for LLM Thought Processes

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

This example shows how to configure reasoning tokens to influence the LLM's thought process. By passing a `reasoning` object in the `client.chat()` options, you can specify the effort level ('low', 'medium', 'high'), the maximum number of tokens for reasoning, and whether to exclude the reasoning from the final response. If not excluded, the reasoning steps will be available in `ChatCompletionResult.reasoning`.

```typescript
import { OpenRouterClient } from 'openrouter';

const client = new OpenRouterClient({ apiKey: 'YOUR_API_KEY' });

async function requestWithReasoning() {
  try {
    // Request with reasoning included in the response
    const resultWithReasoning = await client.chat.completions.create({
      model: 'openai/gpt-4o-mini',
      messages: [{ role: 'user', content: 'Explain the concept of recursion.' }],
      reasoning: {
        effort: 'high',
        max_tokens: 200,
        exclude: false // Reasoning will be included in the response
      }
    });
    console.log('Response with reasoning:', resultWithReasoning.content);
    console.log('Reasoning steps:', resultWithReasoning.reasoning);

    // Request with reasoning excluded from the response
    const resultWithoutReasoning = await client.chat.completions.create({
      model: 'openai/gpt-4o-mini',
      messages: [{ role: 'user', content: 'Summarize the main points of quantum physics.' }],
      reasoning: {
        effort: 'medium',
        max_tokens: 150,
        exclude: true // Reasoning will NOT be included in the response
      }
    });
    console.log('Response without reasoning:', resultWithoutReasoning.content);
    // resultWithoutReasoning.reasoning will be undefined or empty

  } catch (error) {
    console.error('An error occurred during reasoning request:', error);
  }
}

requestWithReasoning();

```

--------------------------------

### Configuring History Management with MemoryStorage

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

To enable automatic dialog history management, configure the historyAdapter with an implementation of IHistoryStorage. This example uses MemoryHistoryStorage for in-memory storage.

```typescript
import { OpenRouterClient, MemoryHistoryStorage } from 'openrouter-kit';

const client = new OpenRouterClient({
  // ... other configurations
  historyAdapter: new MemoryHistoryStorage()
});

```

--------------------------------

### Configure Proxy for Network Requests

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

This example shows how to configure a network proxy for the OpenRouter client. The `proxy` option can be set either as a URL string or as an object with host, port, and optional authentication credentials. This is essential for environments where direct network access is restricted and requests must be routed through a proxy server.

```typescript
import { OpenRouterClient } from 'openrouter';

// Option 1: Configure proxy using a URL string
const clientWithUrlProxy = new OpenRouterClient({
  apiKey: 'YOUR_API_KEY',
  proxy: 'http://user:password@your-proxy.com:8080'
});

console.log('Client configured with URL proxy.');

// Option 2: Configure proxy using an object
const clientWithObjectProxy = new OpenRouterClient({
  apiKey: 'YOUR_API_KEY',
  proxy: {
    host: 'your-proxy.com',
    port: 8080,
    user: 'user',
    pass: 'password'
  }
});

console.log('Client configured with object proxy.');

// Example usage (the client will now use the configured proxy for all requests)
async function makeRequestViaProxy() {
  try {
    const result = await clientWithObjectProxy.chat.completions.create({
      model: 'openai/gpt-4o-mini',
      messages: [{ role: 'user', content: 'Hello via proxy!' }]
    });
    console.log('Response via proxy:', result.content);
  } catch (error) {
    console.error('Error making request via proxy:', error);
  }
}

// makeRequestViaProxy(); // Uncomment to test

```

--------------------------------

### Track Conversation Costs and Usage with TypeScript

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

This snippet demonstrates how to use the OpenRouter client in TypeScript to track conversation costs and token usage. It initializes the client with cost tracking enabled and defines initial model prices. The example generates a series of chat messages for a user, then retrieves and logs detailed statistics including total API calls, cost, token usage, usage by model, finish reasons, cost over time, and token distribution. It also retrieves and displays the user's OpenRouter credit balance. Error handling and client destruction are included.

```typescript
import { OpenRouterClient, MemoryHistoryStorage } from 'openrouter-kit';

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: 'openai/gpt-4o-mini',
  historyAdapter: new MemoryHistoryStorage(),
  enableCostTracking: true,
  initialModelPrices: {
    'openai/gpt-4o-mini': {
      id: 'openai/gpt-4o-mini',
      promptCostPerMillion: 150,
      completionCostPerMillion: 600
    }
  }
});

async function analyticsExample() {
  try {
    const userId = 'analytics-user';

    // Generate some conversation history
    await client.chat({
      user: userId,
      prompt: 'Tell me about TypeScript.',
      temperature: 0.7
    });

    await client.chat({
      user: userId,
      prompt: 'What are its main advantages?',
      temperature: 0.7
    });

    await client.chat({
      user: userId,
      prompt: 'How does it compare to JavaScript?',
      temperature: 0.7
    });

    // Get history analyzer
    const analyzer = client.getHistoryAnalyzer();
    const historyKey = `user:${userId}`;

    // Get comprehensive statistics
    const stats = await analyzer.getStats(historyKey);
    console.log('\n=== Conversation Statistics ===');
    console.log('Total API calls:', stats.totalApiCalls);
    console.log('Total cost:', `$${stats.totalCost.toFixed(6)}`);
    console.log('Total tokens:', stats.totalUsage.total_tokens);
    console.log('Prompt tokens:', stats.totalUsage.prompt_tokens);
    console.log('Completion tokens:', stats.totalUsage.completion_tokens);

    console.log('\n=== Usage by Model ===');
    Object.entries(stats.usageByModel).forEach(([model, usage]) => {
      console.log(`${model}`:);
      console.log(`  Tokens: ${usage.total_tokens}`);
      console.log(`  Cost: $${(stats.costByModel[model] || 0).toFixed(6)}`);
    });

    console.log('\n=== Finish Reasons ===');
    Object.entries(stats.finishReasonCounts).forEach(([reason, count]) => {
      console.log(`${reason}: ${count}`);
    });

    // Get cost over time (hourly granularity)
    const costOverTime = await analyzer.getCostOverTime(historyKey, 'hour');
    console.log('\n=== Cost Over Time (Hourly) ===');
    costOverTime.forEach(point => {
      const date = new Date(point.timestamp).toLocaleString();
      console.log(`${date}: $${point.value.toFixed(6)}`);
    });

    // Get token usage by model
    const tokensByModel = await analyzer.getTokenUsageByModel(historyKey);
    console.log('\n=== Token Distribution ===');
    tokensByModel.forEach(point => {
      console.log(`${point.timestamp}: ${point.value} tokens`);
    });

    // Get credit balance from OpenRouter
    const balance = await client.getCreditBalance();
    console.log('\n=== OpenRouter Account ===');
    console.log('Total credits:', balance.total_credits);
    console.log('Total usage:', balance.total_usage);
    console.log('Remaining:', balance.total_credits - balance.total_usage);

  } catch (error) {
    console.error('Error:', error.message);
  } finally {
    await client.destroy();
  }
}

analyticsExample();

```

--------------------------------

### Configure JWT Auth, RBAC, and Rate Limiting with TypeScript

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

This TypeScript snippet demonstrates how to configure JWT authentication, role-based access control (RBAC), and rate limiting for tool execution using the OpenRouterClient. It includes setting default security policies, defining user roles with specific tool permissions and rate limits, and configuring tool-level access control. The example also shows how to create an access token for a user and make an authenticated chat request.

```typescript
import { OpenRouterClient, MemoryHistoryStorage } from 'openrouter-kit';

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: 'x-ai/grok-4-fast',
  historyAdapter: new MemoryHistoryStorage(),
  security: {
    defaultPolicy: 'deny-all',
    requireAuthentication: true,
    userAuthentication: {
      type: 'jwt',
      jwtSecret: process.env.JWT_SECRET || 'your-secret-key-here'
    },
    roles: {
      roles: {
        admin: {
          allowedTools: '*',
          rateLimits: {
            default: { limit: 100, period: 'minute' }
          }
        },
        user: {
          allowedTools: ['get_weather', 'calculate'],
          rateLimits: {
            get_weather: { limit: 10, period: 'minute' },
            calculate: { limit: 20, period: 'minute' }
          }
        }
      }
    },
    toolAccess: {
      get_weather: {
        allow: true,
        roles: ['user', 'admin'],
        rateLimit: { limit: 10, period: 'minute' }
      },
      admin_action: {
        allow: true,
        roles: ['admin'],
        rateLimit: { limit: 5, period: 'hour' }
      }
    },
    dangerousArguments: {
      auditOnlyMode: false,
      globalPatterns: [
        /drop\s+table/i,
        /delete\s+from/i,
        /<script>/i,
        /javascript:/i
      ]
    }
  }
});

const weatherTool = {
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get weather information',
    parameters: {
      type: 'object',
      properties: {
        city: { type: 'string' }
      },
      required: ['city']
    }
  },
  execute: async (args, context) => {
    console.log('User:', context?.userInfo?.userId || 'anonymous');
    return { city: args.city, temperature: 20, condition: 'Clear' };
  },
  security: {
    requiredRole: 'user',
    rateLimit: { limit: 10, period: 'minute' }
  }
};

async function securityExample() {
  try {
    // Create access token for user
    const userInfo = {
      userId: 'user-456',
      role: 'user',
      scopes: ['weather:read']
    };
    const accessToken = client.createAccessToken(userInfo, '1h');
    console.log('Created access token for user:', userInfo.userId);

    // Make authenticated request
    const result = await client.chat({
      prompt: 'What is the weather in Paris?',
      tools: [weatherTool],
      accessToken: accessToken,
      temperature: 0.5
    });

    console.log('Response:', result.content);
    console.log('Tool calls:', result.toolCallsCount);

  } catch (error) {
    console.error('Security error:', error.message);
    if (error.code) console.error('Error code:', error.code);
    if (error.statusCode) console.error('Status:', error.statusCode);
  } finally {
    await client.destroy();
  }
}

securityExample();

```

--------------------------------

### Maintain Dialog Context with History Management in TypeScript

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

This example illustrates how to manage conversation history using the `MemoryHistoryStorage` and passing a `userId`. The library automatically loads and saves the conversation history, including metadata like API call costs. This is crucial for maintaining context in multi-turn dialogues. Ensure OPENROUTER_API_KEY is set in your environment.

```typescript
// dialog-chat.ts
import { OpenRouterClient, MemoryHistoryStorage } from 'openrouter-kit';

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  // Use MemoryHistoryStorage to store history in memory
  historyAdapter: new MemoryHistoryStorage(),
  enableCostTracking: true, // Enable cost calculation (saved in metadata)
  model: "x-ai/grok-4-fast",
  debug: false,
});

const userId = 'dialog-user-123'; // Unique ID for the user

async function runDialog() {
  try {
    // First message
    console.log(`[${userId}] You: Hi! Remember, my favorite color is blue.`);
    const result1 = await client.chat({
      user: userId, // <-- Pass the user ID for automatic history management
      prompt: 'Hi! Remember, my favorite color is blue.',
    });
    console.log(`[${userId}] Bot: ${result1.content}`);
    console.log(`(Cost: $${result1.cost?.toFixed(8) || 'N/A'})`);

    // Second message (model should remember the context)
    console.log(`
[${userId}] You: What is my favorite color?`);
    const result2 = await client.chat({
      user: userId, // <-- Same user ID
      prompt: 'What is my favorite color?',
    });
    console.log(`[${userId}] Bot: ${result2.content}`);
    console.log(`(Cost: $${result2.cost?.toFixed(8) || 'N/A'})`);

  } catch (error: any) {
    console.error(`
--- Error ---`);
    console.error(`Message: ${error.message}`);
    if (error.code) console.error(`Error Code: ${error.code}`);
  } finally {
    console.log('
Ending dialog...');
    await client.destroy();
  }
}

runDialog();

```

--------------------------------

### Configure Response Format for Structured Outputs

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

This snippet demonstrates how to request structured JSON output from LLM models. You can configure the `responseFormat` globally or per request, specifying either a general `json_object` or a `json_schema` for strict validation. The example includes handling potential parsing errors based on the `strictJsonParsing` setting. Note the compatibility warning: using `responseFormat` and `tools` simultaneously might not be supported by all models.

```typescript
import { OpenRouterClient, OpenRouterConfig, OpenRouterRequestOptions } from 'openrouter';

// Example global configuration for JSON object output
const globalConfig: OpenRouterConfig = {
  apiKey: 'YOUR_API_KEY',
  responseFormat: { type: 'json_object' },
  strictJsonParsing: true // Enforce strict JSON parsing
};

const client = new OpenRouterClient(globalConfig);

async function requestJsonResponseObject() {
  try {
    // Request a JSON object response
    const result = await client.chat.completions.create({
      model: 'openai/gpt-4o-mini',
      messages: [{ role: 'user', content: 'Provide a JSON object with user details: name and age.' }]
      // Uses global responseFormat: { type: 'json_object' }
    });
    console.log('JSON object response:', JSON.parse(result.content!));
  } catch (error) {
    console.error('Error requesting JSON object:', error);
  }
}

// Example request-specific configuration for JSON schema output
const requestOptions: OpenRouterRequestOptions = {
  model: 'openai/gpt-4o-mini',
  responseFormat: {
    type: 'json_schema',
    json_schema: {
      name: 'product',
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: 'Name of the product' },
          price: { type: 'number', description: 'Price of the product' },
          inStock: { type: 'boolean', description: 'Availability status' }
        },
        required: ['name', 'price']
      },
      description: 'Schema for product information'
    }
  },
  strictJsonParsing: false // Allow less strict parsing for this request
};

async function requestJsonSchema() {
  try {
    const result = await client.chat.completions.create({
      ...requestOptions,
      messages: [{ role: 'user', content: 'Describe a laptop with its price and stock status.' }]
    });
    console.log('JSON schema response:', JSON.parse(result.content!));
  } catch (error) {
    console.error('Error requesting JSON schema:', error);
  }
}

// Call the functions to see the output
requestJsonResponseObject();
requestJsonSchema();

```

--------------------------------

### Initialize OpenRouterClient

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

Initializes a client instance with API key and optional configurations for history, security, and cost tracking.

```APIDOC
## Initialize OpenRouterClient

### Description
Create a client instance with API key and optional configuration for history management, security, and cost tracking.

### Method
Constructor

### Endpoint
N/A (Client Initialization)

### Parameters
#### Constructor Parameters
- **apiKey** (string) - Required - Your OpenRouter API key.
- **model** (string) - Required - The LLM model to use (e.g., 'x-ai/grok-4-fast').
- **historyAdapter** (object) - Optional - An adapter for managing conversation history (e.g., `new MemoryHistoryStorage()`).
- **enableCostTracking** (boolean) - Optional - Enables tracking of API call costs. Defaults to `false`.
- **debug** (boolean) - Optional - Enables debug logging. Defaults to `false`.
- **maxToolCalls** (number) - Optional - Maximum number of tool calls allowed per request. Defaults to `10`.
- **strictJsonParsing** (boolean) - Optional - Enforces strict JSON parsing for responses. Defaults to `false`.

### Request Example
```typescript
import { OpenRouterClient, MemoryHistoryStorage } from 'openrouter-kit';

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: 'x-ai/grok-4-fast',
  historyAdapter: new MemoryHistoryStorage(),
  enableCostTracking: true,
  debug: false,
  maxToolCalls: 10,
  strictJsonParsing: false
});
```

### Response
N/A (Client is initialized and ready for requests)
```

--------------------------------

### JSON Response Format with Schema Validation - TypeScript

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

Requests structured JSON output from the chat API with strict schema validation, ensuring predictable data parsing. This TypeScript example defines a user profile schema and uses the `responseFormat` option with `json_schema` to guide the model's output. It demonstrates accessing parsed JSON fields directly from the response.

```typescript
import { OpenRouterClient } from 'openrouter-kit';

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: 'openai/gpt-4o-mini'
});

const userProfileSchema = {
  type: 'object',
  properties: {
    name: { type: 'string', description: 'Full name' },
    age: { type: 'number', description: 'Age in years', minimum: 0 },
    occupation: { type: 'string', description: 'Current occupation' },
    skills: {
      type: 'array',
      description: 'List of professional skills',
      items: { type: 'string' }
    },
    yearsOfExperience: { type: 'number', minimum: 0 }
  },
  required: ['name', 'age', 'occupation', 'skills']
};

async function jsonSchemaExample() {
  try {
    const result = await client.chat({
      prompt: 'Create a profile for a software engineer named Bob, age 35, with 10 years experience in Python, JavaScript, and Docker.',
      temperature: 0.3,
      responseFormat: {
        type: 'json_schema',
        json_schema: {
          name: 'user_profile',
          schema: userProfileSchema,
          strict: true
        }
      }
    });

    console.log('Response type:', typeof result.content);
    console.log('Structured data:', JSON.stringify(result.content, null, 2));

    // Access structured fields directly
    if (result.content && typeof result.content === 'object') {
      console.log('\nParsed fields:');
      console.log('  Name:', result.content.name);
      console.log('  Age:', result.content.age);
      console.log('  Skills:', result.content.skills.join(', '));
      console.log('  Experience:', result.content.yearsOfExperience, 'years');
    }

  } catch (error) {
    console.error('Error:', error.message);
    if (error.details) console.error('Details:', error.details);
  } finally {
    await client.destroy();
  }
}

jsonSchemaExample();

```

--------------------------------

### Initialize OpenRouterClient with TypeScript

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

Creates an instance of the OpenRouterClient, configuring API keys, models, history management, cost tracking, and other settings. It requires the 'openrouter-kit' package and optionally uses environment variables for API keys.

```typescript
import { OpenRouterClient, MemoryHistoryStorage } from 'openrouter-kit';

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: 'x-ai/grok-4-fast',
  historyAdapter: new MemoryHistoryStorage(),
  enableCostTracking: true,
  debug: false,
  maxToolCalls: 10,
  strictJsonParsing: false
});

// Client is now ready for chat requests
// Use client.chat() for regular requests
// Use client.chatStream() for streaming responses
// Call client.destroy() when done to cleanup resources
```

--------------------------------

### Extend OpenRouterKit with Plugins and Middleware (TypeScript)

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

Demonstrates how to create custom plugins and middleware for the OpenRouterClient to add features like logging and analytics. Plugins are initialized with the client and can register middleware to intercept requests and responses. Dependencies include 'openrouter-kit'.

```typescript
import { OpenRouterClient, OpenRouterPlugin, MiddlewareContext } from 'openrouter-kit';

// Custom logging plugin
const loggingPlugin: OpenRouterPlugin = {
  async init(client) {
    console.log('Logging plugin initialized');

    client.useMiddleware(async (ctx: MiddlewareContext, next) => {
      const startTime = Date.now();
      console.log('[Middleware] Request started:', {
        prompt: ctx.request.options.prompt?.substring(0, 50),
        model: ctx.request.options.model,
        user: ctx.request.options.user
      });

      await next();

      const duration = Date.now() - startTime;
      console.log('[Middleware] Request completed:', {
        duration: `${duration}ms`,
        cost: ctx.response?.result?.cost,
        tokens: ctx.response?.result?.usage?.total_tokens
      });
    });
  },
  async destroy() {
    console.log('Logging plugin destroyed');
  }
};

// Custom analytics plugin
const analyticsPlugin: OpenRouterPlugin = {
  async init(client) {
    console.log('Analytics plugin initialized');

    client.on('error', (error) => {
      console.error('[Analytics] Error tracked:', {
        code: error.code,
        message: error.message,
        timestamp: new Date().toISOString()
      });
    });

    client.useMiddleware(async (ctx, next) => {
      await next();

      if (ctx.response?.result) {
        // Track successful requests
        console.log('[Analytics] Success tracked:', {
          model: ctx.response.result.model,
          tokens: ctx.response.result.usage?.total_tokens,
          cost: ctx.response.result.cost,
          toolCalls: ctx.response.result.toolCallsCount
        });
      }
    });
  }
};

async function pluginExample() {
  const client = new OpenRouterClient({
    apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
    model: 'openai/gpt-4o-mini',
    enableCostTracking: true
  });

  try {
    // Register plugins
    await client.use(loggingPlugin);
    await client.use(analyticsPlugin);

    // Make requests - plugins will intercept
    const result = await client.chat({
      prompt: 'Explain middleware in 2 sentences',
      temperature: 0.7
    });

    console.log('\nResponse:', result.content);

  } catch (error) {
    console.error('Error:', error.message);
  } finally {
    await client.destroy();
  }
}

pluginExample();

```

--------------------------------

### Plugins and Middleware

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

Information on extending OpenRouter client functionality using plugins and middleware.

```APIDOC
## Plugins and Middleware

### Plugins
Plugins are modules designed to extend the capabilities of the OpenRouter client. They can be registered using the `client.use(plugin)` method. Plugins are capable of initializing services, replacing core managers (like security or cost tracking), and injecting middleware functions.

### Middleware
Middleware functions are executed sequentially for every `client.chat()` call. They provide an opportunity to modify the request context (`ctx.request`), the response context (`ctx.response`), or to perform side effects such as logging or auditing before the request is processed or the response is returned. Middleware is registered using the `client.useMiddleware(fn)` method.
```

--------------------------------

### OpenRouterClient Configuration

Source: https://github.com/mmeerrkkaa/openrouter-kit/blob/main/README.md

Details on how to configure the OpenRouterClient with various options, including API keys, endpoint settings, and history management.

```APIDOC
## OpenRouterClient Configuration (`OpenRouterConfig`)

When creating the client (`new OpenRouterClient(config)`), a configuration object is passed. Key fields:

*   **`apiKey`** (string) - Required - Your OpenRouter API key.
*   **`apiEndpoint?`** (string) - Optional - URL endpoint for chat completions.
*   **`apiBaseUrl?`** (string) - Optional - Base URL for auxiliary endpoints (e.g., `/models`, `/auth/key`). Defaults to `https://openrouter.ai/api/v1`.
*   **`model?`** (string) - Optional - Default model for requests (e.g., `"x-ai/grok-4-fast"`).
*   **`debug?`** (boolean) - Optional - Enable detailed logging (default: `false`).
*   **`proxy?`** (string | object | null) - Optional - HTTP/HTTPS proxy settings.
*   **`referer?`** (string) - Optional - Value for the `HTTP-Referer` header.
*   **`title?`** (string) - Optional - Value for the `X-Title` header.
*   **`axiosConfig?`** (object) - Optional - Additional configuration for Axios.
*   **`historyAdapter?`** (IHistoryStorage) - Required - An instance of a history storage adapter (e.g., `new MemoryHistoryStorage()`).
*   **`historyTtl?`** (number) - Optional - Time-to-live (TTL) for entries in the `UnifiedHistoryManager` cache (in milliseconds).
*   **`historyCleanupInterval?`** (number) - Optional - Interval for cleaning expired entries from the `UnifiedHistoryManager` cache (in milliseconds).
*   **`defaultProviderRouting?`** (ProviderRoutingConfig) - Optional - Default provider routing rules.
*   **`modelFallbacks?`** (string[]) - Optional - Default list of fallback models.
*   **`responseFormat?`** (ResponseFormat | null) - Optional - Default response format.
*   **`maxToolCalls?`** (number) - Optional - Maximum number of tool call cycles per `chat()` call (default: 10).
*   **`strictJsonParsing?`** (boolean) - Optional - Throw an error on invalid JSON in response (if JSON format requested)? (default: `false`, returns `null`).
*   **`security?`** (SecurityConfig) - Optional - Configuration for the security module.
*   **`enableCostTracking?`** (boolean) - Optional - Enable cost tracking (default: `false`).
*   **`priceRefreshIntervalMs?`** (number) - Optional - Interval for refreshing model prices (default: 6 hours).
*   **`initialModelPrices?`** (object) - Optional - Initial model prices to avoid the first price request.

*Deprecated fields:* `historyStorage`, `chatsFolder`, `maxHistoryEntries`, `historyAutoSave`, `enableReasoning`, `webSearch`.
```

--------------------------------

### Implement Disk-Based History Storage with OpenRouterKit (TypeScript)

Source: https://context7.com/mmeerrkkaa/openrouter-kit/llms.txt

Shows how to configure the OpenRouterClient to use a disk-based storage adapter for conversation history, ensuring persistence across application restarts. This requires 'openrouter-kit' and Node.js 'path' module. The adapter takes a directory path for storing history files.

```typescript
import { OpenRouterClient, DiskHistoryStorage } from 'openrouter-kit';
import path from 'path';

const historyPath = path.join(__dirname, 'chat-history');

const client = new OpenRouterClient({
  apiKey: process.env.OPENROUTER_API_KEY || 'sk-or-v1-...',
  model: 'x-ai/grok-4-fast',
  historyAdapter: new DiskHistoryStorage({
    directory: historyPath,
    prettify: true
  }),
  enableCostTracking: true
});

async function diskStorageExample() {
  try {
    const userId = 'persistent-user';

    // Conversation persists to disk automatically
    const response = await client.chat({
      user: userId,
      prompt: 'Remember that my favorite framework is React.',
      temperature: 0.7
    });
    console.log('Bot:', response.content);

    // Even after restarting the application, history is preserved
    const response2 = await client.chat({
      user: userId,
      prompt: 'What framework did I mention?',
      temperature: 0.7
    });
    console.log('Bot:', response2.content);

    // List all history keys stored on disk
    const historyManager = client.getHistoryManager();
    const keys = await historyManager.listKeys();
    console.log('\nStored conversation keys:', keys);

    // Cleanup specific user history if needed
    // await historyManager.deleteHistory(`user:${userId}`);

  } catch (error) {
    console.error('Error:', error.message);
  } finally {
    await client.destroy();
  }
}

diskStorageExample();

```