TypeScript SDK

Architecture

• Layered, non-blocking by default
• Data buffered and flushed async to backend
• Node >= 18, ESM + CJS builds

Layer Flow

Public API → OpikClient → Domain (Trace/Span) → BatchQueues → REST Client → Backend

Critical Gotchas

• When changing dependencies or minimum versions, update and verify version references in README.md and integration README files in the same PR.

Flush Before Exit

typescript
1// ✅ REQUIRED - especially in CLI/tests
2await client.flush();
3// or globally:
4await flushAll();

Domain Objects Don't Do HTTP

typescript
1// ✅ GOOD - domain objects enqueue, not HTTP
2trace.update({ metadata: { key: 'value' } }); // Enqueues update
3trace.end();  // Enqueues update
4
5// ❌ BAD - don't call REST directly from domain

Never Leak rest_api

typescript
1// ✅ GOOD - export from public API
2export { Opik, track, flushAll } from 'opik';
3
4// ❌ BAD - don't expose generated clients
5import { TracesApi } from 'opik/rest_api';  // Internal!

Batching Semantics

• Updates wait for pending creates
• Deletes wait for creates and updates
• flush() flushes all queues in order
• Debounce window configurable via OpikConfig

Error Handling

• HTTP failures: OpikApiError, OpikApiTimeoutError
• 404s translate to domain errors: DatasetNotFoundError, ExperimentNotFoundError
• Never swallow errors, include context in logs

Integration Guidelines

• Integrations wrap public API only
• Keep adapters thin, non-blocking
• Provide flush() escape hatch if needed

Reference Files

• testing.md - Vitest patterns, mocking, flush timing