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
// ✅ REQUIRED - especially in CLI/tests
await client.flush();
// or globally:
await flushAll();
Domain Objects Don't Do HTTP
// ✅ GOOD - domain objects enqueue, not HTTP
trace.update({ metadata: { key: 'value' } }); // Enqueues update
trace.end(); // Enqueues update
// ❌ BAD - don't call REST directly from domain
Never Leak rest_api
// ✅ GOOD - export from public API
export { Opik, track, flushAll } from 'opik';
// ❌ BAD - don't expose generated clients
import { 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
