# 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

### Simple - Pass directly to SDK

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

### Custom Configuration

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

### Run Object

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

### Step Object

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