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:

``bash
@openrouter-monorepo/sdk-devtools-typescript
`

Usage

$3

`typescript
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.

$3

`typescript
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

$3

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

$3

`json
{
"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)