typescript-sdk

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

1. Zainstaluj SDK TypeScript dla Opik w swoim projekcie Node.js (wymagana wersja >= 18). Upewnij się, że Twoje środowisko obsługuje zarówno moduły ESM jak i CommonJS.

2. Zaimportuj publiczny interfejs API z pakietu 'opik' — używaj eksportowanych funkcji takich jak Opik, track i flushAll. Nigdy nie importuj wewnętrznych klientów REST (rest_api) bezpośrednio.

3. Utwórz instancję OpikClient i skonfiguruj okno debounce'a poprzez OpikConfig zgodnie z potrzebami Twojej aplikacji. Architektura warstw będzie automatycznie obsługiwać buforowanie i asynchroniczne wysyłanie danych.

4. Używaj obiektów domenowych (Trace, Span) do enqueue'owania operacji — nie wywołuj REST API bezpośrednio z kodu domenowego. Obiekty domenowe automatycznie enqueue'ują aktualizacje i zamknięcia.

5. Przed wyjściem aplikacji (szczególnie w CLI i testach) jawnie wywołaj await client.flush() lub globalnie await flushAll(), aby upewnić się, że wszystkie zakolejkowane operacje zostaną wysłane do backendu. Semantyka batchowania gwarantuje, że aktualizacje czekają na tworzenie, a usuwania czekają na aktualizacje.

6. Obsługuj błędy HTTP za pomocą dedykowanych typów wyjątków (OpikApiError, OpikApiTimeoutError) i tłumaczeń 404 na błędy domenowe (DatasetNotFoundError, ExperimentNotFoundError). Zawsze loguj kontekst błędu zamiast go pomijać.