# API Reference

Complete reference for all classes, methods, types, and enums exported by `@mosaicstack/telemetry-client`.

**SDK version:** 0.1.0
**Targets:** Mosaic Telemetry API v1, event schema version `1.0`

---

## TelemetryClient

Main entry point. Queues task-completion events for background batch submission and provides access to cached predictions.

```typescript
import { TelemetryClient } from '@mosaicstack/telemetry-client';
```

### Constructor

```typescript
new TelemetryClient(config: TelemetryConfig)
```

Creates a new client instance. Does **not** start background submission — call `start()` to begin.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `eventBuilder` | `EventBuilder` | Builder for constructing `TaskCompletionEvent` objects |
| `queueSize` | `number` | Number of events currently in the queue |
| `isRunning` | `boolean` | Whether background submission is active |

### Methods

#### `start(): void`

Start background batch submission via `setInterval`. Idempotent — calling `start()` multiple times has no effect.

#### `stop(): Promise<void>`

Stop background submission and flush all remaining events. Idempotent. Returns a promise that resolves when the final flush completes.

#### `track(event: TaskCompletionEvent): void`

Queue an event for batch submission. **Never throws** — all errors are caught and routed to the `onError` callback.

When `enabled` is `false`, this method returns immediately without queuing.

When the queue is at capacity (`maxQueueSize`), the oldest event is evicted to make room.

#### `getPrediction(query: PredictionQuery): PredictionResponse | null`

Get a cached prediction for the given query dimensions. Returns `null` if no prediction is cached or the cache entry has expired.

#### `refreshPredictions(queries: PredictionQuery[]): Promise<void>`

Fetch predictions from the server via `POST /v1/predictions/batch` and store them in the local cache. The predictions endpoint is public — no authentication required.

Accepts up to 50 queries per call (server limit).

---

## EventBuilder

Convenience builder that auto-fills `event_id`, `timestamp`, `instance_id`, and `schema_version`.

```typescript
import { EventBuilder } from '@mosaicstack/telemetry-client';
```

Access via `client.eventBuilder` — you don't normally construct this directly.

### Methods

#### `build(params: EventBuilderParams): TaskCompletionEvent`

Build a complete `TaskCompletionEvent` from the given parameters.

Auto-generated fields:
- `event_id` — `crypto.randomUUID()`
- `timestamp` — `new Date().toISOString()`
- `instance_id` — from client config
- `schema_version` — `"1.0"`

---

## EventQueue

Bounded FIFO queue for telemetry events. Used internally by `TelemetryClient`.

```typescript
import { EventQueue } from '@mosaicstack/telemetry-client';
```

### Constructor

```typescript
new EventQueue(maxSize: number)
```

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `size` | `number` | Current number of events in the queue |
| `isEmpty` | `boolean` | Whether the queue is empty |

### Methods

#### `enqueue(event: TaskCompletionEvent): void`

Add an event. Evicts the oldest event if at capacity.

#### `drain(maxItems: number): TaskCompletionEvent[]`

Remove and return up to `maxItems` events from the front.

#### `prepend(events: TaskCompletionEvent[]): void`

Prepend events back to the front (used for re-enqueue on submission failure). Respects `maxSize` — excess events are dropped.

---

## BatchSubmitter

Handles HTTP submission of event batches with retry logic.

```typescript
import { BatchSubmitter } from '@mosaicstack/telemetry-client';
```

### Methods

#### `submit(events: TaskCompletionEvent[]): Promise<SubmitResult>`

Submit a batch to `POST /v1/events/batch`. Retries with exponential backoff (1s base, 60s max, with jitter) on transient failures. Respects the server's `Retry-After` header on HTTP 429.

In dry-run mode, returns a synthetic success response without making HTTP calls.

---

## PredictionCache

In-memory TTL cache for prediction responses.

```typescript
import { PredictionCache } from '@mosaicstack/telemetry-client';
```

### Constructor

```typescript
new PredictionCache(ttlMs: number)
```

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `size` | `number` | Number of entries in cache (may include expired entries) |

### Methods

#### `get(query: PredictionQuery): PredictionResponse | null`

Retrieve a cached prediction. Returns `null` if not cached or expired (expired entries are lazily deleted).

#### `set(query: PredictionQuery, response: PredictionResponse): void`

Store a prediction with TTL.

#### `clear(): void`

Clear all cached predictions.

---

## Configuration Types

### TelemetryConfig

User-facing configuration passed to the `TelemetryClient` constructor.

```typescript
import type { TelemetryConfig } from '@mosaicstack/telemetry-client';
```

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `serverUrl` | `string` | Yes | — | Telemetry API base URL (e.g., `"https://tel-api.mosaicstack.dev"`) |
| `apiKey` | `string` | Yes | — | Bearer token for `POST /v1/events/batch` authentication |
| `instanceId` | `string` | Yes | — | UUID identifying this Mosaic Stack instance |
| `enabled` | `boolean` | No | `true` | When `false`, `track()` is a no-op |
| `submitIntervalMs` | `number` | No | `300_000` | Background flush interval in ms (5 min) |
| `maxQueueSize` | `number` | No | `1000` | Maximum events held in queue before FIFO eviction |
| `batchSize` | `number` | No | `100` | Events per batch (server max: 100) |
| `requestTimeoutMs` | `number` | No | `10_000` | HTTP request timeout in ms |
| `predictionCacheTtlMs` | `number` | No | `21_600_000` | Prediction cache TTL in ms (6 hours) |
| `dryRun` | `boolean` | No | `false` | Simulate submissions without HTTP calls |
| `maxRetries` | `number` | No | `3` | Retry attempts on transient failure |
| `onError` | `(error: Error) => void` | No | silent | Callback invoked on errors |

### ResolvedConfig

Internal configuration with all defaults applied. All fields are required (non-optional).

```typescript
import type { ResolvedConfig } from '@mosaicstack/telemetry-client';
```

### resolveConfig

```typescript
import { resolveConfig } from '@mosaicstack/telemetry-client';

function resolveConfig(config: TelemetryConfig): ResolvedConfig
```

Apply defaults to a `TelemetryConfig`, producing a `ResolvedConfig`. Strips trailing slashes from `serverUrl`.

---

## Event Types

### EventBuilderParams

Parameters accepted by `EventBuilder.build()`. Excludes auto-generated fields (`event_id`, `timestamp`, `instance_id`, `schema_version`).

```typescript
import type { EventBuilderParams } from '@mosaicstack/telemetry-client';
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `task_duration_ms` | `number` | Yes | Wall-clock time in ms (0–86,400,000) |
| `task_type` | `TaskType` | Yes | Category of work performed |
| `complexity` | `Complexity` | Yes | Task complexity level |
| `harness` | `Harness` | Yes | Coding tool / execution environment |
| `model` | `string` | Yes | Model identifier (1–100 chars) |
| `provider` | `Provider` | Yes | LLM provider |
| `estimated_input_tokens` | `number` | Yes | Pre-task input token estimate (0–10,000,000) |
| `estimated_output_tokens` | `number` | Yes | Pre-task output token estimate (0–10,000,000) |
| `actual_input_tokens` | `number` | Yes | Actual input tokens consumed (0–10,000,000) |
| `actual_output_tokens` | `number` | Yes | Actual output tokens generated (0–10,000,000) |
| `estimated_cost_usd_micros` | `number` | Yes | Estimated cost in microdollars (0–100,000,000) |
| `actual_cost_usd_micros` | `number` | Yes | Actual cost in microdollars (0–100,000,000) |
| `quality_gate_passed` | `boolean` | Yes | Whether all quality gates passed |
| `quality_gates_run` | `QualityGate[]` | Yes | Gates that were executed |
| `quality_gates_failed` | `QualityGate[]` | Yes | Gates that failed |
| `context_compactions` | `number` | Yes | Context compaction count (0–100) |
| `context_rotations` | `number` | Yes | Context rotation count (0–50) |
| `context_utilization_final` | `number` | Yes | Final context utilization ratio (0.0–1.0) |
| `outcome` | `Outcome` | Yes | Task result |
| `retry_count` | `number` | Yes | Number of retries (0–20) |
| `language` | `string \| null` | No | Primary programming language (max 30 chars) |
| `repo_size_category` | `RepoSizeCategory \| null` | No | Repository size bucket |

### TaskCompletionEvent

Full event object submitted to the server. Extends `EventBuilderParams` with auto-generated identity fields.

```typescript
import type { TaskCompletionEvent } from '@mosaicstack/telemetry-client';
```

Additional fields (auto-generated by `EventBuilder`):

| Field | Type | Description |
|-------|------|-------------|
| `instance_id` | `string` | UUID identifying the submitting instance |
| `event_id` | `string` | Unique UUID for deduplication |
| `schema_version` | `string` | Always `"1.0"` |
| `timestamp` | `string` | ISO 8601 datetime |

---

## Prediction Types

### PredictionQuery

Query parameters for fetching a prediction.

```typescript
import type { PredictionQuery } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `task_type` | `TaskType` | Task type to predict for |
| `model` | `string` | Model identifier |
| `provider` | `Provider` | LLM provider |
| `complexity` | `Complexity` | Complexity level |

### PredictionResponse

Response from the predictions endpoint.

```typescript
import type { PredictionResponse } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `prediction` | `PredictionData \| null` | Prediction data, or `null` if no data available |
| `metadata` | `PredictionMetadata` | Sample size, confidence, fallback info |

### PredictionData

Statistical prediction for a dimension combination.

```typescript
import type { PredictionData } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `input_tokens` | `TokenDistribution` | Input token distribution (p10/p25/median/p75/p90) |
| `output_tokens` | `TokenDistribution` | Output token distribution |
| `cost_usd_micros` | `Record<string, number>` | Cost stats — `{ median: number }` |
| `duration_ms` | `Record<string, number>` | Duration stats — `{ median: number }` |
| `correction_factors` | `CorrectionFactors` | Actual-to-estimated token ratios |
| `quality` | `QualityPrediction` | Quality gate pass rate and success rate |

### TokenDistribution

Percentile distribution of token counts.

```typescript
import type { TokenDistribution } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `p10` | `number` | 10th percentile |
| `p25` | `number` | 25th percentile |
| `median` | `number` | 50th percentile (median) |
| `p75` | `number` | 75th percentile |
| `p90` | `number` | 90th percentile |

### CorrectionFactors

Ratio of actual to estimated tokens. Values >1.0 mean estimates tend to be too low.

```typescript
import type { CorrectionFactors } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `input` | `number` | Actual / estimated input tokens |
| `output` | `number` | Actual / estimated output tokens |

### QualityPrediction

Predicted quality gate and success rates.

```typescript
import type { QualityPrediction } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `gate_pass_rate` | `number` | Fraction of events where all quality gates pass (0.0–1.0) |
| `success_rate` | `number` | Fraction of events with `outcome: "success"` (0.0–1.0) |

### PredictionMetadata

Metadata about a prediction response.

```typescript
import type { PredictionMetadata } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `sample_size` | `number` | Number of events used to compute this prediction |
| `fallback_level` | `number` | 0 = exact match, 1+ = dimensions dropped, -1 = no data |
| `confidence` | `'none' \| 'low' \| 'medium' \| 'high'` | Confidence level |
| `last_updated` | `string \| null` | ISO 8601 timestamp of last computation |
| `dimensions_matched` | `Record<string, string \| null> \| null` | Matched dimensions (`null` values indicate fallback) |
| `fallback_note` | `string \| null` | Human-readable fallback explanation |
| `cache_hit` | `boolean` | Whether served from server-side cache |

**Confidence level criteria:**

| Level | Criteria |
|-------|----------|
| `none` | No data available. `prediction` is `null`. |
| `low` | Sample size < 30 or fallback was applied |
| `medium` | Sample size 30–99, exact match |
| `high` | Sample size >= 100, exact match |

---

## Batch Types

### BatchEventRequest

Request body for `POST /v1/events/batch`.

```typescript
import type { BatchEventRequest } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `events` | `TaskCompletionEvent[]` | 1–100 events to submit |

### BatchEventResponse

Response from `POST /v1/events/batch`.

```typescript
import type { BatchEventResponse } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `accepted` | `number` | Count of accepted events |
| `rejected` | `number` | Count of rejected events |
| `results` | `BatchEventResult[]` | Per-event result details |

### BatchEventResult

Per-event result within a batch response.

```typescript
import type { BatchEventResult } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `event_id` | `string` | The event's UUID |
| `status` | `'accepted' \| 'rejected'` | Whether the event was accepted |
| `error` | `string \| null` | Error message if rejected |

### SubmitResult

Internal result type from `BatchSubmitter.submit()`.

```typescript
import type { SubmitResult } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | `boolean` | Whether the submission succeeded |
| `response` | `BatchEventResponse \| undefined` | Server response (on success) |
| `retryAfterMs` | `number \| undefined` | Retry delay from 429 response |
| `error` | `Error \| undefined` | Error details (on failure) |

### BatchPredictionRequest

Request body for `POST /v1/predictions/batch`.

```typescript
import type { BatchPredictionRequest } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `queries` | `PredictionQuery[]` | 1–50 prediction queries |

### BatchPredictionResponse

Response from `POST /v1/predictions/batch`.

```typescript
import type { BatchPredictionResponse } from '@mosaicstack/telemetry-client';
```

| Field | Type | Description |
|-------|------|-------------|
| `results` | `PredictionResponse[]` | One response per query, in request order |

---

## Enums

All enums use string values matching the server's API contract.

### TaskType

```typescript
import { TaskType } from '@mosaicstack/telemetry-client';
```

| Member | Value | Description |
|--------|-------|-------------|
| `PLANNING` | `"planning"` | Architecture design, task breakdown |
| `IMPLEMENTATION` | `"implementation"` | Writing new code |
| `CODE_REVIEW` | `"code_review"` | Reviewing existing code |
| `TESTING` | `"testing"` | Writing or running tests |
| `DEBUGGING` | `"debugging"` | Investigating and fixing bugs |
| `REFACTORING` | `"refactoring"` | Restructuring existing code |
| `DOCUMENTATION` | `"documentation"` | Writing docs, comments, READMEs |
| `CONFIGURATION` | `"configuration"` | Config files, CI/CD, infrastructure |
| `SECURITY_AUDIT` | `"security_audit"` | Security review, vulnerability analysis |
| `UNKNOWN` | `"unknown"` | Unclassified task type (fallback) |

### Complexity

```typescript
import { Complexity } from '@mosaicstack/telemetry-client';
```

| Member | Value | Description | Typical Token Budget |
|--------|-------|-------------|---------------------|
| `LOW` | `"low"` | Simple fixes, typos, config changes | 50,000 |
| `MEDIUM` | `"medium"` | Standard features, moderate logic | 150,000 |
| `HIGH` | `"high"` | Complex features, multi-file changes | 350,000 |
| `CRITICAL` | `"critical"` | Major refactoring, architectural changes | 750,000 |

### Harness

```typescript
import { Harness } from '@mosaicstack/telemetry-client';
```

| Member | Value | Description |
|--------|-------|-------------|
| `CLAUDE_CODE` | `"claude_code"` | Anthropic Claude Code CLI |
| `OPENCODE` | `"opencode"` | OpenCode CLI |
| `KILO_CODE` | `"kilo_code"` | Kilo Code VS Code extension |
| `AIDER` | `"aider"` | Aider AI pair programming |
| `API_DIRECT` | `"api_direct"` | Direct API calls (no harness) |
| `OLLAMA_LOCAL` | `"ollama_local"` | Ollama local inference |
| `CUSTOM` | `"custom"` | Custom or unrecognized harness |
| `UNKNOWN` | `"unknown"` | Harness not reported |

### Provider

```typescript
import { Provider } from '@mosaicstack/telemetry-client';
```

| Member | Value | Description |
|--------|-------|-------------|
| `ANTHROPIC` | `"anthropic"` | Anthropic (Claude models) |
| `OPENAI` | `"openai"` | OpenAI (GPT models) |
| `OPENROUTER` | `"openrouter"` | OpenRouter (multi-provider routing) |
| `OLLAMA` | `"ollama"` | Ollama (local/self-hosted) |
| `GOOGLE` | `"google"` | Google (Gemini models) |
| `MISTRAL` | `"mistral"` | Mistral AI |
| `CUSTOM` | `"custom"` | Custom or unrecognized provider |
| `UNKNOWN` | `"unknown"` | Provider not reported |

### QualityGate

```typescript
import { QualityGate } from '@mosaicstack/telemetry-client';
```

| Member | Value | Description |
|--------|-------|-------------|
| `BUILD` | `"build"` | Code compiles/builds successfully |
| `LINT` | `"lint"` | Linter passes with no errors |
| `TEST` | `"test"` | Unit/integration tests pass |
| `COVERAGE` | `"coverage"` | Code coverage meets threshold (85%) |
| `TYPECHECK` | `"typecheck"` | Type checker passes |
| `SECURITY` | `"security"` | Security scan passes |

### Outcome

```typescript
import { Outcome } from '@mosaicstack/telemetry-client';
```

| Member | Value | Description |
|--------|-------|-------------|
| `SUCCESS` | `"success"` | Task completed, all quality gates passed |
| `FAILURE` | `"failure"` | Task failed after all retries |
| `PARTIAL` | `"partial"` | Task partially completed (some gates passed) |
| `TIMEOUT` | `"timeout"` | Task exceeded time or token budget |

### RepoSizeCategory

```typescript
import { RepoSizeCategory } from '@mosaicstack/telemetry-client';
```

| Member | Value | Approximate LOC | Description |
|--------|-------|-----------------|-------------|
| `TINY` | `"tiny"` | < 1,000 | Scripts, single-file projects |
| `SMALL` | `"small"` | 1,000–10,000 | Small libraries, tools |
| `MEDIUM` | `"medium"` | 10,000–100,000 | Standard applications |
| `LARGE` | `"large"` | 100,000–1,000,000 | Large applications, monorepos |
| `HUGE` | `"huge"` | > 1,000,000 | Enterprise codebases |

---

## Server API Endpoints Used

The SDK communicates with these Mosaic Telemetry API v1 endpoints:

| SDK Method | HTTP Endpoint | Auth Required |
|------------|---------------|---------------|
| `flush()` (internal) | `POST /v1/events/batch` | Yes (Bearer token) |
| `refreshPredictions()` | `POST /v1/predictions/batch` | No (public) |

For the full server API specification, see the [Mosaic Telemetry API Reference](https://tel-api.mosaicstack.dev/v1/docs).