# Typescript Sdk

> TypeScript SDK patterns for Opik. Use when working in sdks/typescript.

- Skill: `comet-ml/typescript-sdk` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add comet-ml/typescript-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comet-ml/typescript-sdk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: comet-ml (https://skillmd.com/u/comet-ml)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/comet-ml/typescript-sdk

---


# 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
// ✅ REQUIRED - especially in CLI/tests
await client.flush();
// or globally:
await flushAll();
```

### Domain Objects Don't Do HTTP
```typescript
// ✅ 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
```typescript
// ✅ 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](testing.md) - Vitest patterns, mocking, flush timing