@bitfab/sdk 0.33.6 → 0.34.0

package/dist/index.d.cts

@@ -70,7 +70,21 @@ interface DbSnapshotRef {
  */
 declare class BitfabError extends Error {
     readonly url?: string | undefined;
-    constructor(message: string, url?: string | undefined);
+    /**
+     * HTTP status the request failed with, when it failed with one. The
+     * transport's retry policy needs the code itself (retry 408/425/429/5xx,
+     * never a 4xx the server will reject again), which a formatted message
+     * cannot supply. Absent for network failures and non-HTTP errors.
+     */
+    readonly status?: number | undefined;
+    constructor(message: string, url?: string | undefined, 
+    /**
+     * HTTP status the request failed with, when it failed with one. The
+     * transport's retry policy needs the code itself (retry 408/425/429/5xx,
+     * never a 4xx the server will reject again), which a formatted message
+     * cannot supply. Absent for network failures and non-HTTP errors.
+     */
+    status?: number | undefined);
 }
 
 /**
@@ -196,6 +210,15 @@ interface DbBranchLease {
      */
     region?: string;
 }
+/**
+ * Wire shape of the caller's `ReplayOptions.dbBranch`, sent to
+ * `/api/sdk/replay/start` and applied per lease.
+ */
+interface DbBranchSettings {
+    minCu?: number;
+    maxCu?: number;
+    warmupSql?: string;
+}
 /**
  * Pre-built lookup table of historical span outputs.
  * Keys are `${traceFunctionKey}:${spanName}:${callIndex}` so that repeated
@@ -248,17 +271,6 @@ interface ReplayContext {
      * must also set this.
      */
     dbSnapshotAccessed?: boolean;
-    /**
-     * Collector for the replay item's trace-persistence work. When present,
-     * the root span's send path pushes a promise that resolves only after
-     * every span upload AND the trace completion have been sent (registered
-     * synchronously at send time, so the replay runner can await it after
-     * the wrapped fn resolves). This is what lets replay guarantee traces
-     * are persisted server-side before `completeReplay` builds the
-     * trace-ID mapping. Absent outside replay, where sends stay
-     * fire-and-forget.
-     */
-    pendingPersistence?: Promise<unknown>[];
 }
 
 /**
@@ -266,16 +278,23 @@ interface ReplayContext {
  *
  * This module provides:
  * - HttpClient class for making API requests
- * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
+ * - awaitOnExit helper so deferred span work still gates process exit
  */
 
 /**
- * Wait for all pending fire-and-forget operations (spans, traces) to complete.
- * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.
+ * Wait for pending fire-and-forget requests AND every live span transport to
+ * deliver, within one total deadline. Useful in tests and scripts to ensure all
+ * data has been sent before asserting or exiting.
+ *
+ * Returns `false` when delivery failed or the deadline expired, so a caller
+ * that depends on persistence (replay does) can react instead of assuming a
+ * drained queue means the server has the data. When delivery goes through a
+ * Collector, `true` means the Collector accepted the spans; it is not proof
+ * that Bitfab committed them.
  *
- * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+ * @param timeoutMs - Maximum total time to wait in milliseconds (default: 5000)
  */
-declare function flushTraces(timeoutMs?: number): Promise<void>;
+declare function flushTraces(timeoutMs?: number): Promise<boolean>;
 /**
  * How the API key is supplied internally: either a literal string or a
  * function resolved each time the key is needed (at request/send time). The
@@ -284,6 +303,11 @@ declare function flushTraces(timeoutMs?: number): Promise<void>;
  * case) is still picked up.
  */
 type ApiKeyInput = string | (() => string | undefined);
+interface HttpClientConfig {
+    apiKey?: ApiKeyInput;
+    serviceUrl: string;
+    timeout?: number;
+}
 type SpanOccurrence = "first" | "last" | number;
 type SpanLookup = {
     id: string;
@@ -310,6 +334,163 @@ interface CapturedSpan {
     startedAt: string | null;
     endedAt: string | null;
 }
+/**
+ * HTTP client for Bitfab API requests.
+ *
+ * Provides methods for different API endpoints with proper error handling,
+ * timeouts, and authentication.
+ */
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly serviceUrl;
+    private readonly timeout;
+    private traceTransport;
+    private readonly deferredWork;
+    private closed;
+    private closing;
+    constructor(config: HttpClientConfig);
+    /**
+     * Resolve the API key at the moment it is needed (request time), invoking
+     * the function form if one was supplied. Never read at construction.
+     */
+    private resolveApiKey;
+    /**
+     * This client's span transport, built on first use.
+     *
+     * Lazy on purpose: a client that never sends a span must never start a batch
+     * worker. Every framework integration created from a `Bitfab` client shares
+     * the owning client's `HttpClient`, so handlers reuse this one worker instead
+     * of each spinning up their own.
+     */
+    private getTraceTransport;
+    /**
+     * Track deferred span work so this client's own lifecycle waits for it, and
+     * so the process-wide flush and exit hook do too.
+     */
+    trackDeferred<T>(promise: Promise<T>): Promise<T>;
+    /**
+     * Settle only THIS client's deferred span work. Scoped deliberately: the
+     * global set can contain another client's long-running finalize, and
+     * attributing its timeout here would fail a client whose own work succeeded.
+     */
+    settleDeferredWork(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Wait for spans queued by this client to be delivered, within one deadline.
+     * Returns false on delivery failure or timeout.
+     */
+    waitForPendingRequests(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Flush and permanently close this client's tracing transport. Idempotent:
+     * a second call joins the first rather than tearing down a pipeline the
+     * first call already owns.
+     */
+    close(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Make an HTTP request to the Bitfab API. Defaults to POST; pass
+     * `options.method` to use a different verb (e.g. "PATCH").
+     *
+     * @param endpoint - The API endpoint (without base URL)
+     * @param payload - The request body
+     * @param options - Optional request options
+     * @returns The parsed JSON response
+     * @throws {BitfabError} If the request fails
+     */
+    request<T>(endpoint: string, payload: Record<string, unknown>, options?: {
+        timeout?: number;
+        method?: "POST" | "PATCH" | "PUT";
+    }): Promise<T>;
+    /**
+     * Look up a function by name.
+     * Blocks until complete - needed for function execution.
+     */
+    lookupFunction<T>(name: string): Promise<T>;
+    getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
+    private get;
+    /**
+     * Queue an internal trace (from local BAML execution via `call()`) onto this
+     * client's batching transport. `functionId` moves into the payload because
+     * the OTLP carrier has no path to carry it.
+     */
+    sendInternalTrace(functionId: string, payload: Record<string, unknown>): void;
+    /**
+     * Queue an external span (from withSpan wrapper or OpenAI tracing) onto this
+     * client's batching transport. Fire-and-forget: the transport owns delivery,
+     * so callers await `flushTraces()` or `close()` rather than a per-span
+     * promise.
+     */
+    sendExternalSpan(payload: Record<string, unknown>): void;
+    /**
+     * Queue an external trace completion (from OpenAI tracing) onto this
+     * client's batching transport. Fire-and-forget for the same reason as
+     * {@link HttpClient.sendExternalSpan}; replay confirms persistence with the
+     * server-authoritative barrier in `replay.ts`, not by awaiting this call.
+     */
+    sendExternalTrace(payload: Record<string, unknown>): void;
+    /**
+     * Partial update of an existing trace identified by its Bitfab trace ID.
+     * Used by the detached `client.getTrace(id)` handle.
+     *
+     * Blocking, like the other trace-API calls: it resolves once the server has
+     * applied the change and rejects if the server refused it. A patch targets a
+     * trace that is already closed, so there is no batch for it to ride along
+     * with and no later signal that would reveal a silent failure.
+     */
+    patchTrace(traceId: string, payload: {
+        appendContexts?: Record<string, unknown>[];
+        mergeMetadata?: Record<string, unknown>;
+        setSessionId?: string;
+    }): Promise<void>;
+    /**
+     * Start a replay session by fetching historical traces.
+     * Blocking call - creates a test run and returns lightweight item references.
+     */
+    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetId?: string, graderIds?: string[], dbBranchSettings?: DbBranchSettings): Promise<StartReplayResponse>;
+    /**
+     * Fetch an external span by ID.
+     * Blocking GET request.
+     */
+    getExternalSpan(spanId: string): Promise<ExternalSpanResponse>;
+    /**
+     * Fetch the span tree for a root span.
+     * Blocking GET request.
+     *
+     * Pass `includeOutputs: false` for a payload-free tree (structure +
+     * `externalSpanId` only), so recorded outputs are fetched lazily per mocked
+     * span instead of all up front. Omit it (default eager) for `mock: "all"`.
+     */
+    getSpanTree(externalSpanId: string, options?: {
+        includeOutputs?: boolean;
+    }): Promise<SpanTreeResponse>;
+    /**
+     * Read which of a replay run's traces the server has fully persisted.
+     *
+     * With `expectedSpanCounts`, a trace appears in the response only once it
+     * has a final status AND at least that many persisted spans, which is what
+     * makes this a real barrier rather than a "the row exists" check.
+     */
+    getReplayStatus(testRunId: string, expectedSpanCounts: Record<string, number>): Promise<ReplayStatusResponse>;
+    /**
+     * Mark a replay test run as completed.
+     * Blocking call.
+     */
+    completeReplay(testRunId: string): Promise<CompleteReplayResponse>;
+    /**
+     * Ask the server to materialize a per-trace DB branch lease from a
+     * captured `dbSnapshotRef`. Blocking - the resolver creates a Neon
+     * snapshot + preview branch and polls operations to readiness, which
+     * can take seconds.
+     */
+    resolveDbBranchLease(testRunId: string, traceId: string, dbBranchSettings?: DbBranchSettings): Promise<{
+        dbSnapshotRef: DbSnapshotRef | null;
+        lease: DbBranchLease | null;
+        leaseError: {
+            code: string;
+            message: string;
+        } | null;
+    }>;
+    /** Release a previously-resolved DB branch by deleting its Neon branch. Idempotent server-side. */
+    releaseDbBranchLease(neonBranchId: string): Promise<void>;
+}
 interface TokenUsage {
     input: number | null;
     output: number | null;
@@ -328,6 +509,112 @@ interface CodeChangeFile {
     before: string;
     after: string;
 }
+interface StartReplayResponse {
+    testRunId: string;
+    testRunUrl: string;
+    items: Array<{
+        /** Bitfab trace ID of the original (historical) trace being replayed. */
+        originalTraceId?: string;
+        /** External span ID the recorded inputs were read from (the original root span). */
+        originalSpanId?: string;
+        /** @deprecated alias for `originalTraceId`; the only key emitted by servers that predate the rename. */
+        sourceTraceId: string;
+        /** @deprecated alias for `originalSpanId`; the only key emitted by servers that predate the rename. */
+        sourceSpanId: string;
+        durationMs: number | null;
+        tokens: TokenUsage | null;
+        model: string | null;
+        /**
+         * The DB snapshot ref captured by the SDK at trace open. Surfaced so
+         * the SDK can pass it to the lease-resolver step (or report when no
+         * snapshot was captured for this trace).
+         */
+        dbSnapshotRef?: DbSnapshotRef;
+        /**
+         * Populated once the server-side resolver has materialized a per-item
+         * branch from `dbSnapshotRef`. The SDK exposes this to customer code
+         * via `getCurrentReplayBranch()`. Absent until the resolver lands.
+         */
+        dbBranchLease?: DbBranchLease;
+        /**
+         * Why the branch could not be resolved, when one was requested and the
+         * attempt failed. Distinct from both fields being absent, which means the
+         * trace carried no snapshot ref so nothing was attempted.
+         */
+        dbBranchLeaseError?: {
+            code: string;
+            message: string;
+        };
+    }>;
+}
+interface ExternalSpanResponse {
+    id: string;
+    externalTraceId: string;
+    rawData: {
+        span_data: {
+            input: unknown;
+            output: unknown;
+            input_meta?: unknown;
+            output_meta?: unknown;
+            input_serialized?: {
+                json: unknown;
+                meta: unknown;
+            };
+            output_serialized?: {
+                json: unknown;
+                meta: unknown;
+            };
+        };
+    };
+}
+interface ReplayStatusResponse {
+    /**
+     * Local replay trace id -> server trace row id, for the traces the server
+     * considers fully persisted. Traces still short of their expected span count
+     * are simply absent.
+     */
+    traceIds?: Record<string, string>;
+}
+interface CompleteReplayResponse {
+    id: string;
+    status: string;
+    traceIds?: Record<string, string>;
+    /**
+     * Per-replay-trace token usage, keyed by the server trace id (the values of
+     * `traceIds`). Aggregated server-side from the freshly-uploaded replay spans,
+     * so it's the REPLAYED run's tokens (the same source Studio reads), not the
+     * original trace's. The SDK maps each item onto this to set
+     * `ReplayItem.tokens`. Absent on servers that predate this field.
+     */
+    tokens?: Record<string, TokenUsage | null>;
+    /**
+     * Number of traces the server has persisted for this test run at
+     * completion time. Lets the SDK distinguish "uploads failed" from
+     * "server never saw them" when the trace-ID mapping is incomplete.
+     */
+    traceCount?: number;
+}
+interface SpanTreeNode {
+    /** Upstream platform span id. Stable structural identity; NOT the row id. */
+    sourceSpanId: string;
+    /**
+     * The `externalSpans` row id, accepted by {@link HttpClient.getExternalSpan}.
+     * Distinct from `sourceSpanId`; used to lazily fetch this node's output when
+     * the tree was fetched with `includeOutputs: false`. Optional so trees from
+     * older servers (which omit it) still deserialize.
+     */
+    externalSpanId?: string;
+    traceFunctionKey: string;
+    spanName: string;
+    type: string;
+    /** Omitted when the tree was fetched payload-free (`includeOutputs: false`). */
+    output?: unknown;
+    outputMeta?: unknown;
+    children: SpanTreeNode[];
+}
+interface SpanTreeResponse {
+    root: SpanTreeNode;
+}
 
 /**
  * Claude Agent SDK handler for Bitfab tracing.
@@ -375,6 +662,7 @@ interface ActiveSpanContext$2 {
  */
 declare class BitfabClaudeAgentHandler {
     private readonly httpClient;
+    private readonly ownsHttpClient;
     private readonly traceFunctionKey;
     private readonly getActiveSpanContext;
     private runToSpan;
@@ -401,7 +689,20 @@ declare class BitfabClaudeAgentHandler {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext$2 | null;
+        /**
+         * The owning `Bitfab` client's HTTP client. Supplied by
+         * `getClaudeAgentHandler()` so this handler shares that client's single
+         * span-transport worker instead of starting a second one.
+         * @internal
+         */
+        _httpClient?: HttpClient;
     });
+    /**
+     * Flush and release the span transport this handler started. A no-op when
+     * the handler borrowed a `Bitfab` client's HTTP client: that client's
+     * `close()` owns the worker's lifetime.
+     */
+    close(timeoutMs?: number): Promise<boolean>;
     private ensureTrace;
     private getParentId;
     private maybeStartRootSpan;
@@ -620,6 +921,7 @@ declare class BitfabLangGraphCallbackHandler {
     ignoreRetriever: boolean;
     ignoreCustomEvent: boolean;
     private readonly httpClient;
+    private readonly ownsHttpClient;
     private readonly traceFunctionKey;
     private readonly getActiveSpanContext;
     private runToSpan;
@@ -630,7 +932,20 @@ declare class BitfabLangGraphCallbackHandler {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext$1 | null;
+        /**
+         * The owning `Bitfab` client's HTTP client. Supplied by
+         * `getLangGraphCallbackHandler()` so this handler shares that client's
+         * single span-transport worker instead of starting a second one.
+         * @internal
+         */
+        _httpClient?: HttpClient;
     });
+    /**
+     * Flush and release the span transport this handler started. A no-op when
+     * the handler borrowed a `Bitfab` client's HTTP client: that client's
+     * `close()` owns the worker's lifetime.
+     */
+    close(timeoutMs?: number): Promise<boolean>;
     private startSpan;
     private completeSpan;
     private sendSpan;
@@ -1163,6 +1478,7 @@ interface TracingProcessor {
  */
 declare class BitfabOpenAITracingProcessor implements TracingProcessor {
     private readonly httpClient;
+    private readonly ownsHttpClient;
     private activeTraces;
     private readonly getActiveSpanContext;
     private activeSpanMappings;
@@ -1178,7 +1494,20 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext | null;
+        /**
+         * The owning `Bitfab` client's HTTP client. Supplied by
+         * `getOpenAiTracingProcessor()` so this processor shares that client's
+         * single span-transport worker instead of starting a second one.
+         * @internal
+         */
+        _httpClient?: HttpClient;
     });
+    /**
+     * Flush and release the span transport this processor started. A no-op when
+     * the processor borrowed a `Bitfab` client's HTTP client: that client's
+     * `close()` owns the worker's lifetime.
+     */
+    close(timeoutMs?: number): Promise<boolean>;
     /**
      * Called when a trace is started.
      * If there's an active withSpan context, the trace ID is remapped to the
@@ -1208,7 +1537,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
     /**
      * Called when the trace processor is shutting down.
      */
-    shutdown(_timeout?: number): Promise<void>;
+    shutdown(timeout?: number): Promise<void>;
     /**
      * Send trace to Bitfab API (fire-and-forget).
      * When traceIdOverride is provided, the trace ID is remapped to link
@@ -1289,21 +1618,23 @@ interface DetachedTrace {
      * Append a context entry to this trace. Each call adds one entry to the
      * server-side contexts array; existing entries are preserved.
      *
-     * Returns a promise that the caller may await for confirmation, or ignore
-     * to fire-and-forget. The pending request is tracked so `flushTraces()`
-     * waits for it.
+     * Resolves once the server has applied the change and REJECTS if the server
+     * refused it. A detached patch targets an already-closed trace, so it rides
+     * no batch and no later signal would reveal a silent failure - the caller is
+     * the only one who can react.
      */
-    addContext(context: Record<string, unknown>): Promise<unknown>;
+    addContext(context: Record<string, unknown>): Promise<void>;
     /**
      * Merge metadata into this trace. Server-side shallow-merges the new keys
      * into the existing metadata object; existing keys are preserved unless
-     * overwritten by the new values.
+     * overwritten by the new values. Rejects if the server refused the update.
      */
-    setMetadata(metadata: Record<string, unknown>): Promise<unknown>;
+    setMetadata(metadata: Record<string, unknown>): Promise<void>;
     /**
      * Set the sessionId for this trace. Replaces any existing sessionId.
+     * Rejects if the server refused the update.
      */
-    setSessionId(sessionId: string): Promise<unknown>;
+    setSessionId(sessionId: string): Promise<void>;
 }
 /**
  * A handle to the current active trace, allowing trace-level context to be set.
@@ -1508,6 +1839,21 @@ declare class Bitfab {
      * @param config - Configuration options for the client
      */
     constructor(config: BitfabConfig);
+    /**
+     * Flush and permanently close this client's tracing resources: its pending
+     * requests and the single span-transport worker shared by its decorators and
+     * framework handlers.
+     *
+     * Resolves `false` when delivery failed or the deadline expired. Long-lived
+     * processes never need this (the transport batches in the background and the
+     * exit hook drains it); scripts and tests that want a hard guarantee should
+     * await it.
+     *
+     * Deliberately not a `Symbol.asyncDispose` method: the SDK targets runtimes
+     * where that symbol may be absent, and a computed key on a missing symbol
+     * throws at class-definition time, taking the whole SDK down on load.
+     */
+    close(timeoutMs?: number): Promise<boolean>;
     /**
      * Resolve the API key lazily, the first time a span actually needs it.
      *
@@ -1780,13 +2126,13 @@ declare class Bitfab {
     /**
      * Send trace completion when a root span ends.
      * Internal method to record trace completion with end time.
-     * Fire-and-forget - sends to externalTraces endpoint via httpClient.
+     * Queued on the client's span transport; delivery is the transport's job.
      */
     private sendTraceCompletion;
     /**
      * Send a wrapper span from function execution.
      * Internal method to record spans when using withSpan.
-     * Fire-and-forget - sends to externalSpans endpoint via httpClient.
+     * Queued on the client's span transport; delivery is the transport's job.
      */
     private sendWrapperSpan;
     /**
@@ -1983,7 +2329,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.33.6";
+declare const __version__ = "0.34.0";
 
 /**
  * Constants for the Bitfab SDK.