@openrouter/devtools

OpenRouter SDK Devtools (TypeScript)

Development-only telemetry capture for OpenRouter TypeScript SDK.

Features

• 📊 Capture chat completions and responses API calls
• 💾 Store telemetry in local JSON file (.devtools/openrouter-generations.json)
• 🔔 Notify local devtools server of changes
• 🛡️ Production-safe (throws error if used in production)
• 🚀 Zero impact on SDK performance (async, non-blocking)

Installation

Already installed as part of the monorepo:

@openrouter-monorepo/sdk-devtools-typescript

Usage

Simple - Pass directly to SDK

import { createOpenRouterDevtools } from '@openrouter-monorepo/sdk-devtools-typescript';
import { OpenRouter } from '@openrouter/sdk';

const sdk = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  hooks: createOpenRouterDevtools()
});

That's it! The devtools will automatically capture all SDK requests and responses.

Custom Configuration

const sdk = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
  hooks: createOpenRouterDevtools({
    storagePath: '.custom-path/generations.json', // Default: '.devtools/openrouter-generations.json'
    serverUrl: 'http://localhost:5000/api/notify',  // Default: 'http://localhost:4983/api/notify'
  })
});

Data Format

Run Object

{
  "id": "1702345678901-abc123",
  "started_at": "2024-12-11T10:30:00.000Z",
  "operation": "chat",
  "model": "openai/gpt-4",
  "status": "success",
  "steps": [...]
}

Step Object

{
  "run_id": "1702345678901-abc123",
  "step_number": 1,
  "type": "chat",
  "started_at": "2024-12-11T10:30:00.000Z",
  "completed_at": "2024-12-11T10:30:02.500Z",
  "request": {
    "model": "openai/gpt-4",
    "messages": [...],
    "parameters": {...}
  },
  "response": {
    "content": "Hello!",
    "usage": {
      "prompt_tokens": 10,
      "completion_tokens": 2,
      "total_tokens": 12
    },
    "provider": "openai",
    "model": "gpt-4-0613"
  },
  "duration_ms": 2500
}

Captured Operations

• sendChatCompletionRequest - Chat completions API
• createResponses - Responses API

All other SDK operations are ignored.

Environment Safety

Throws error if NODE_ENV === 'production':

Error: OpenRouter devtools cannot be used in production.
Remove devtools initialization or use environment-based conditional initialization.

Storage Location

Default: .devtools/openrouter-generations.json

• Auto-creates directory if missing
• Loads existing data on init
• Debounced writes (500ms)
• Flushes on process exit (SIGINT, SIGTERM, exit)

Server Notification

Sends POST to http://localhost:4983/api/notify when data changes.

• Fire-and-forget (non-blocking)
• Silently ignores errors (server not running is OK)

Error Handling

Devtools failures never break SDK operations:

• Storage errors: Logged, continue without persistence
• Hook errors: Logged, request/response unchanged
• Server errors: Silently ignored

License

Apache-2.0 (same as OpenRouter SDK)