# @mosaicstack/telemetry-client

TypeScript client SDK for [Mosaic Stack Telemetry](https://tel.mosaicstack.dev). Reports task-completion metrics from AI coding harnesses and queries crowd-sourced predictions.

**Zero runtime dependencies** — uses native `fetch`, `crypto.randomUUID()`, and `setInterval`.

## Installation

```bash
npm install @mosaicstack/telemetry-client
```

## Quick Start

```typescript
import { TelemetryClient, TaskType, Complexity, Harness, Provider, Outcome } from '@mosaicstack/telemetry-client';

const client = new TelemetryClient({
  serverUrl: 'https://tel.mosaicstack.dev',
  apiKey: 'your-64-char-hex-api-key',
  instanceId: 'your-instance-uuid',
});

client.start();

// Build and track an event
const event = client.eventBuilder.build({
  task_duration_ms: 45000,
  task_type: TaskType.IMPLEMENTATION,
  complexity: Complexity.MEDIUM,
  harness: Harness.CLAUDE_CODE,
  model: 'claude-sonnet-4-5-20250929',
  provider: Provider.ANTHROPIC,
  estimated_input_tokens: 5000,
  estimated_output_tokens: 2000,
  actual_input_tokens: 5500,
  actual_output_tokens: 2200,
  estimated_cost_usd_micros: 30000,
  actual_cost_usd_micros: 33000,
  quality_gate_passed: true,
  quality_gates_run: [],
  quality_gates_failed: [],
  context_compactions: 0,
  context_rotations: 0,
  context_utilization_final: 0.4,
  outcome: Outcome.SUCCESS,
  retry_count: 0,
});

client.track(event);

// When shutting down
await client.stop();
```

## Querying Predictions

```typescript
const query = {
  task_type: TaskType.IMPLEMENTATION,
  model: 'claude-sonnet-4-5-20250929',
  provider: Provider.ANTHROPIC,
  complexity: Complexity.MEDIUM,
};

// Fetch from server and cache locally
await client.refreshPredictions([query]);

// Get cached prediction (returns null if not cached)
const prediction = client.getPrediction(query);
if (prediction?.prediction) {
  console.log('Median input tokens:', prediction.prediction.input_tokens.median);
  console.log('Median cost (microdollars):', prediction.prediction.cost_usd_micros.median);
}
```

## Configuration

```typescript
const client = new TelemetryClient({
  serverUrl: 'https://tel.mosaicstack.dev',  // Required
  apiKey: 'your-api-key',                     // Required (64-char hex)
  instanceId: 'your-uuid',                    // Required

  // Optional
  enabled: true,                  // Set false to disable (track() becomes no-op)
  submitIntervalMs: 300_000,      // Background flush interval (default: 5 min)
  maxQueueSize: 1000,             // Max queued events (default: 1000, FIFO eviction)
  batchSize: 100,                 // Events per batch (default/max: 100)
  requestTimeoutMs: 10_000,       // HTTP timeout (default: 10s)
  predictionCacheTtlMs: 21_600_000, // Prediction cache TTL (default: 6 hours)
  dryRun: false,                  // Log events instead of sending
  maxRetries: 3,                  // Retry attempts on failure
  onError: (err) => console.error(err),  // Error callback
});
```

## Dry-Run Mode

For testing without sending data:

```typescript
const client = new TelemetryClient({
  serverUrl: 'https://tel.mosaicstack.dev',
  apiKey: 'test-key',
  instanceId: 'test-uuid',
  dryRun: true,
});
```

## License

MPL-2.0