# Typescript Sdk

> TypeScript SDK patterns for Opik. Use when working in sdks/typescript. Use when this capability is needed.

- Skill: `tomevault-io/typescript-sdk` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/typescript-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/typescript-sdk/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/comet-ml) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->