feat: TypeScript telemetry client SDK v0.1.0

Standalone npm package (@mosaicstack/telemetry-client) for reporting task-completion telemetry and querying predictions from the Mosaic Stack Telemetry server. - TelemetryClient with setInterval-based background flush - EventQueue (bounded FIFO array) - BatchSubmitter with native fetch, exponential backoff, Retry-After - PredictionCache (Map + TTL) - EventBuilder with auto-generated event_id/timestamp - Zero runtime dependencies (Node 18+ native APIs) - 43 tests, 86% branch coverage Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 23:25:31 -06:00
commit 177720e523
26 changed files with 5643 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,113 @@
+# @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