mosaic/telemetry-client-js
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
develop
telemetry-client-js/docs/api-reference.md
Jason Woltje 231a799a46
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Details
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

603 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).
Reference in New Issue View Git Blame Copy Permalink