docs(#1): SDK integration guide, API reference, and CI pipeline

- Rewrite README with quick start, config table, prediction usage, API version note - Add docs/integration-guide.md with Next.js and Node.js examples, env-specific config, error handling patterns, batch behavior, and API version compatibility - Add docs/api-reference.md with full reference for all exported classes, methods, types, and enums - Add .woodpecker.yml with quality gates (lint, typecheck, format, security audit, test with coverage) and npm publish to Gitea registry - Add AGENTS.md and update CLAUDE.md with project conventions Fixes #1 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-14 22:38:19 -06:00
parent 177720e523
commit 231a799a46
6 changed files with 1303 additions and 52 deletions
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -0,0 +1,602 @@
+# 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).