telemetry-client-js/docs/api-reference.md

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.

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

Constructor

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.

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.

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

Constructor

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.

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.

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

Constructor

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.

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).

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

resolveConfig

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

BatchEventResponse

Response from POST /v1/events/batch.

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.

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().

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.

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

Field	Type	Description
queries	PredictionQuery[]	1–50 prediction queries

BatchPredictionResponse

Response from POST /v1/predictions/batch.

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

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

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

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

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

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

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

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.