@bitfab/sdk 0.28.10 → 0.29.0

package/dist/{chunk-SK4TNXRC.js → chunk-2M5AWVVQ.js}

@@ -6,14 +6,15 @@ import {
   getReplayContext,
   isAsyncStorageInitDone,
   randomUuid,
+  resolveMockValue,
   serializeValue,
   toJsonSafe,
   toJsonSafeReport,
   warnOnce
-} from "./chunk-5E4BUIYA.js";
+} from "./chunk-V3XORTWI.js";
 
 // src/version.generated.ts
-var __version__ = "0.28.10";
+var __version__ = "0.29.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -249,6 +250,50 @@ var HttpClient = class {
   async lookupFunction(name) {
     return this.request("/api/sdk/functions/lookup", { name });
   }
+  async getTraceSpan(traceId, lookup) {
+    const searchParams = new URLSearchParams();
+    if (lookup.id !== void 0) {
+      searchParams.set("id", lookup.id);
+    } else {
+      searchParams.set("name", lookup.name);
+      searchParams.set("occurrence", String(lookup.occurrence ?? "last"));
+    }
+    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}/span?${searchParams.toString()}`;
+    const response = await this.get(endpoint);
+    return response.span;
+  }
+  async get(endpoint) {
+    const url = `${this.serviceUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new BitfabError(
+          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof BitfabError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BitfabError(`Request timed out after ${this.timeout}ms`);
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * Send an internal trace (from BAML execution).
    * Fire-and-forget with awaitOnExit - doesn't block the caller.
@@ -305,12 +350,12 @@ var HttpClient = class {
     });
   }
   /**
-   * Partial update of an existing external trace identified by sourceTraceId.
+   * Partial update of an existing trace identified by its Bitfab trace ID.
    * Used by the detached `client.getTrace(id)` handle. Fire-and-forget;
    * returns a tracked promise that callers may optionally await.
    */
-  patchTrace(sourceTraceId, payload) {
-    const endpoint = `/api/sdk/externalTraces/${encodeURIComponent(sourceTraceId)}`;
+  patchTrace(traceId, payload) {
+    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}`;
     return awaitOnExit(
       this.request(endpoint, payload, { method: "PATCH" })
     ).catch((error) => {
@@ -394,9 +439,14 @@ var HttpClient = class {
   /**
    * 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"`.
    */
-  async getSpanTree(externalSpanId) {
-    const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}`;
+  async getSpanTree(externalSpanId, options) {
+    const query = options?.includeOutputs === false ? "?includeOutputs=false" : "";
+    const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}${query}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 3e4);
     try {
@@ -644,6 +694,7 @@ var BitfabClaudeAgentHandler = class {
     const traceId = this.ensureTrace();
     const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
+      id: randomUuid(),
       spanId,
       traceId,
       parentId: parentId ?? null,
@@ -707,6 +758,8 @@ var BitfabClaudeAgentHandler = class {
       rawSpan.parent_id = spanInfo.parentId;
     }
     const payload = {
+      id: spanInfo.id,
+      traceId: spanInfo.traceId,
       type: "sdk-function",
       source: "typescript-sdk-claude-agent-sdk",
       traceFunctionKey: this.traceFunctionKey,
@@ -736,6 +789,7 @@ var BitfabClaudeAgentHandler = class {
       externalTrace.metadata = metadata;
     }
     const traceData = {
+      id: traceId,
       type: "sdk-function",
       source: "typescript-sdk-claude-agent-sdk",
       traceFunctionKey: this.traceFunctionKey,
@@ -1004,6 +1058,7 @@ var BitfabClaudeAgentHandler = class {
     }
     Object.assign(llmContext, this.currentLlmUsage);
     const spanInfo = {
+      id: randomUuid(),
       spanId,
       traceId,
       parentId,
@@ -1644,6 +1699,7 @@ var BitfabLangGraphCallbackHandler = class {
     const contexts = Object.keys(lgMetadata).length > 0 ? [lgMetadata] : [];
     const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
+      id: randomUuid(),
       spanId: runId,
       traceId: invocation.traceId,
       rootRunId: invocation.rootRunId,
@@ -1722,6 +1778,8 @@ var BitfabLangGraphCallbackHandler = class {
       rawSpan.parent_id = spanInfo.parentId;
     }
     const payload = {
+      id: spanInfo.id,
+      traceId: spanInfo.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -1737,6 +1795,7 @@ var BitfabLangGraphCallbackHandler = class {
   sendTraceCompletion(rootSpan, activeContext) {
     const completed = activeContext === null;
     const traceData = {
+      id: rootSpan.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -1756,6 +1815,7 @@ var BitfabLangGraphCallbackHandler = class {
   }
   sendTraceStart(rootSpan) {
     const traceData = {
+      id: rootSpan.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2115,6 +2175,7 @@ var BitfabOpenAITracingProcessor = class {
   constructor(config) {
     this.activeTraces = {};
     this.activeSpanMappings = {};
+    this.canonicalTraceIds = {};
     this.httpClient = new HttpClient({
       apiKey: config.apiKey,
       serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
@@ -2122,6 +2183,15 @@ var BitfabOpenAITracingProcessor = class {
     });
     this.getActiveSpanContext = config.getActiveSpanContext ?? null;
   }
+  getCanonicalTraceId(sourceTraceId) {
+    const existing = this.canonicalTraceIds[sourceTraceId];
+    if (existing) {
+      return existing;
+    }
+    const created = randomUuid();
+    this.canonicalTraceIds[sourceTraceId] = created;
+    return created;
+  }
   /**
    * Called when a trace is started.
    * If there's an active withSpan context, the trace ID is remapped to the
@@ -2133,7 +2203,12 @@ var BitfabOpenAITracingProcessor = class {
     if (activeContext) {
       this.activeSpanMappings[trace.traceId] = activeContext;
     }
-    this.sendTrace(trace, activeContext ? { id: activeContext.traceId } : {});
+    const canonicalTraceId = activeContext?.traceId ?? this.getCanonicalTraceId(trace.traceId);
+    this.canonicalTraceIds[trace.traceId] = canonicalTraceId;
+    this.sendTrace(trace, {
+      id: canonicalTraceId,
+      sourceTraceId: activeContext?.traceId
+    });
   }
   /**
    * Called when a trace is ended.
@@ -2142,11 +2217,13 @@ var BitfabOpenAITracingProcessor = class {
    */
   async onTraceEnd(trace) {
     const mapping = this.activeSpanMappings[trace.traceId];
-    this.sendTrace(
-      trace,
-      mapping ? { id: mapping.traceId } : { completed: true }
-    );
+    this.sendTrace(trace, {
+      completed: mapping === void 0,
+      id: mapping?.traceId ?? this.getCanonicalTraceId(trace.traceId),
+      sourceTraceId: mapping?.traceId
+    });
     delete this.activeSpanMappings[trace.traceId];
+    delete this.canonicalTraceIds[trace.traceId];
     delete this.activeTraces[trace.traceId];
   }
   /**
@@ -2176,22 +2253,25 @@ var BitfabOpenAITracingProcessor = class {
   async shutdown(_timeout) {
     this.activeTraces = {};
     this.activeSpanMappings = {};
+    this.canonicalTraceIds = {};
   }
   /**
    * Send trace to Bitfab API (fire-and-forget).
    * When traceIdOverride is provided, the trace ID is remapped to link
    * the OpenAI trace into an outer withSpan trace.
    */
-  sendTrace(trace, overrides = {}) {
+  sendTrace(trace, options = {}) {
     try {
-      const { completed, ...traceOverrides } = overrides;
       const traceData = trace.toJSON();
-      Object.assign(traceData, traceOverrides);
+      if (options.sourceTraceId) {
+        traceData.id = options.sourceTraceId;
+      }
       this.httpClient.sendExternalTrace({
+        ...options.id && { id: options.id },
         type: "openai",
         source: "typescript-sdk-openai-tracing",
         externalTrace: traceData,
-        completed: completed ?? false
+        completed: options.completed ?? false
       });
     } catch {
     }
@@ -2277,6 +2357,7 @@ var BitfabOpenAITracingProcessor = class {
    */
   buildSpanPayload(serializedSpan, errors) {
     const payload = {
+      id: randomUuid(),
       type: "openai",
       source: "typescript-sdk-openai-tracing",
       sourceTraceId: serializedSpan.trace_id ?? "unknown",
@@ -2299,6 +2380,10 @@ var BitfabOpenAITracingProcessor = class {
     this.extractSpanInputResponse(span, serializedSpan, errors);
     this.applySpanOverrides(serializedSpan, span.traceId ?? "");
     const payload = this.buildSpanPayload(serializedSpan, errors);
+    const canonicalTraceId = span.traceId ? this.getCanonicalTraceId(span.traceId) : void 0;
+    if (canonicalTraceId) {
+      payload.traceId = canonicalTraceId;
+    }
     this.httpClient.sendExternalSpan(payload);
   }
 };
@@ -2614,24 +2699,19 @@ function extractContextFromCollector(collector) {
     return null;
   }
 }
-var TRACE_ID_PATTERN = /^[a-zA-Z0-9_\-.:]+$/;
-var TRACE_ID_MAX_LENGTH = 256;
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function validateTraceId(traceId) {
-  if (typeof traceId !== "string" || traceId.length === 0) {
-    throw new BitfabError("traceId is required and must be a non-empty string");
+  if (typeof traceId !== "string" || !UUID_PATTERN.test(traceId)) {
+    throw new BitfabError("traceId must be a valid Bitfab trace ID");
   }
-  if (traceId.length > TRACE_ID_MAX_LENGTH) {
-    throw new BitfabError(
-      `traceId must be ${TRACE_ID_MAX_LENGTH} characters or fewer`
-    );
-  }
-  if (!TRACE_ID_PATTERN.test(traceId)) {
-    throw new BitfabError(
-      `traceId may only contain letters, digits, "_", "-", ".", ":"`
-    );
+}
+function validateSpanId(id) {
+  if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+    throw new BitfabError("id must be a valid Bitfab span ID");
   }
 }
 var noOpSpan = {
+  id: "",
   traceId: "",
   addContext() {
   },
@@ -2655,6 +2735,7 @@ function getCurrentSpan() {
     return noOpSpan;
   }
   return {
+    id: current.spanId,
     traceId: current.traceId,
     addContext(context) {
       try {
@@ -2746,6 +2827,12 @@ var Bitfab = class {
   constructor(config) {
     /** Gate the empty-key warning to fire at most once. */
     this.apiKeyWarned = false;
+    /**
+     * Mock overrides registered via {@link Bitfab.registerMockOverride}, applied
+     * to every `replay` on this client (after any per-call `mockOverride`). In
+     * registration order; first matcher wins within this list.
+     */
+    this.mockOverrides = [];
     this.apiKeyConfig = config.apiKey;
     this.serviceUrl = config.serviceUrl ?? DEFAULT_SERVICE_URL;
     this.timeout = config.timeout ?? 12e4;
@@ -3358,25 +3445,78 @@ var Bitfab = class {
           const counterKey = `${traceFunctionKey}:${baseSpanParams.spanName}`;
           const callIndex = counters.get(counterKey) ?? 0;
           counters.set(counterKey, callIndex + 1);
-          const shouldMock = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
-          if (shouldMock) {
-            const mockKey = `${counterKey}:${callIndex}`;
-            const mockSpan = replayCtxForMock.mockTree.spans.get(mockKey);
-            if (mockSpan) {
-              let output = mockSpan.output;
-              if (mockSpan.outputMeta !== void 0 && mockSpan.outputMeta !== null) {
-                output = deserializeValue({
-                  json: mockSpan.output,
-                  meta: mockSpan.outputMeta
-                });
-              }
+          const mockKey = `${counterKey}:${callIndex}`;
+          const mockSpan = replayCtxForMock.mockTree.spans.get(mockKey);
+          const emitMock = (output) => {
+            void sendSpan({ result: output, mocked: true });
+            if (fnReturnsPromise) {
+              return Promise.resolve(output);
+            }
+            return output;
+          };
+          const emitMockAsync = (pending) => {
+            if (!fnReturnsPromise) {
+              throw new BitfabError(
+                `Cannot mock synchronous span "${traceFunctionKey}" with an asynchronously-resolved value (lazy recorded-output fetch or an async value function). Make the wrapped function async, or use mock: "all" so recorded outputs are fetched eagerly.`
+              );
+            }
+            return (async () => {
+              const output = await pending;
               void sendSpan({ result: output, mocked: true });
-              if (fnReturnsPromise) {
-                return Promise.resolve(output);
-              }
               return output;
+            })();
+          };
+          const resolveRecordedOutput = () => {
+            const hasInlineOutput = mockSpan?.output !== void 0 || mockSpan?.outputMeta !== void 0;
+            if (!hasInlineOutput && replayCtxForMock.fetchSpanOutput && mockSpan?.externalSpanId) {
+              return replayCtxForMock.fetchSpanOutput(mockSpan.externalSpanId);
+            }
+            if (!mockSpan) {
+              return Promise.reject(
+                new BitfabError(
+                  `No recorded span to source output for "${traceFunctionKey}".`
+                )
+              );
+            }
+            let output = mockSpan.output;
+            if (mockSpan.outputMeta !== void 0 && mockSpan.outputMeta !== null) {
+              output = deserializeValue({
+                json: mockSpan.output,
+                meta: mockSpan.outputMeta
+              });
+            }
+            return output;
+          };
+          if (replayCtxForMock.mockOverrides?.length) {
+            const nodeMeta = {
+              traceFunctionKey,
+              spanName: baseSpanParams.spanName,
+              type: options.type ?? "custom",
+              originalSpanId: mockSpan?.sourceSpanId
+            };
+            const override = replayCtxForMock.mockOverrides.find(
+              (o) => o.match(nodeMeta)
+            );
+            if (override) {
+              const injected = resolveMockValue(override.value, {
+                node: nodeMeta,
+                inputs: args,
+                getOriginalOutput: () => Promise.resolve(resolveRecordedOutput())
+              });
+              if (injected instanceof Promise) {
+                return emitMockAsync(injected);
+              }
+              return emitMock(injected);
             }
           }
+          const shouldMock = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
+          if (shouldMock && mockSpan) {
+            const recorded = resolveRecordedOutput();
+            if (recorded instanceof Promise) {
+              return emitMockAsync(recorded);
+            }
+            return emitMock(recorded);
+          }
         }
         const recordSpan = (result) => {
           if (options.finalize) {
@@ -3451,20 +3591,19 @@ var Bitfab = class {
   }
   /**
    * Get a detached handle to a previously-created trace, looked up by the
-   * caller-supplied id (the same id passed at trace creation).
+   * canonical Bitfab trace ID.
    *
    * The returned handle is not tied to AsyncLocalStorage - each method sends
    * to the server immediately. Useful for adding context to a trace from a
    * different process or thread than the one that created it.
    *
-   * Throws synchronously if `traceId` is malformed (empty, too long, or
-   * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
-   * no trace exists with that id in the org; the failure surfaces as a
+   * Throws synchronously if `traceId` is not a valid Bitfab trace ID. The
+   * server returns 404 if no trace exists with that ID in the org; the failure surfaces as a
    * logged warning (fire-and-forget) or via the awaited promise.
    *
    * Example:
    * ```typescript
-   * const trace = client.getTrace("order_abc_123");
+   * const trace = client.getTrace(traceId);
    * await trace.addContext({ refund_status: "approved" });
    * await trace.setMetadata({ region: "us-west" });
    * ```
@@ -3504,6 +3643,33 @@ var Bitfab = class {
       }
     };
   }
+  /**
+   * Fetch one persisted span from a trace without loading the full trace.
+   * Name lookups return the last matching span by default. Pass `occurrence`
+   * as `"first"` or a zero-based index to select a different match.
+   */
+  async getTraceSpan(traceId, lookup) {
+    validateTraceId(traceId);
+    const hasId = lookup.id !== void 0;
+    const hasName = lookup.name !== void 0;
+    if (hasId === hasName) {
+      throw new BitfabError("Provide exactly one of id or name");
+    }
+    if (hasId) {
+      validateSpanId(lookup.id);
+    } else {
+      if (lookup.name.length === 0) {
+        throw new BitfabError("name must be a non-empty string");
+      }
+      const occurrence = lookup.occurrence ?? "last";
+      if (occurrence !== "first" && occurrence !== "last" && (!Number.isInteger(occurrence) || occurrence < 0)) {
+        throw new BitfabError(
+          'occurrence must be "first", "last", or a non-negative integer'
+        );
+      }
+    }
+    return this.httpClient.getTraceSpan(traceId, lookup);
+  }
   /**
    * Get a function wrapper for a specific trace function key.
    *
@@ -3562,6 +3728,7 @@ var Bitfab = class {
       };
     }
     return this.httpClient.sendExternalTrace({
+      id: params.traceId,
       type: "sdk-function",
       source: "typescript-sdk-function",
       traceFunctionKey: params.traceFunctionKey,
@@ -3617,6 +3784,8 @@ var Bitfab = class {
       externalSpan.input_source_span_id = params.inputSourceSpanId;
     }
     return this.httpClient.sendExternalSpan({
+      id: params.spanId,
+      traceId: params.traceId,
       type: "sdk-function",
       source: "typescript-sdk-function",
       sourceTraceId: params.traceId,
@@ -3626,26 +3795,14 @@ var Bitfab = class {
       ...params.mocked && { mocked: true }
     });
   }
-  /**
-   * Replay historical traces through a function and create a test run.
-   *
-   * Fetches the last N traces for the given trace function key, re-runs each
-   * through the provided function, and returns comparison data.
-   *
-   * Accepts either a `withSpan`-wrapped function (under the same key) or any
-   * plain callable: plain callables are wrapped internally so each replayed
-   * invocation records a trace tied to the test run. The plain-callable form
-   * is how handler-instrumented workflows (LangGraph/LangChain, Claude Agent
-   * SDK) replay - those record traces under a key with no `withSpan`-wrapped
-   * root in the app.
-   *
-   * @param traceFunctionKey - The trace function key to replay
-   * @param fn - The function to run recorded inputs through
-   * @param options - Optional replay options. When `traceIds` is passed,
-   *   `limit` is ignored (with a warning): an explicit ID list already
-   *   determines how many traces replay.
-   * @returns ReplayResult with items, testRunId, and testRunUrl
-   */
+  registerMockOverride(overrideOrMatch, value) {
+    const override = typeof overrideOrMatch === "function" ? { match: overrideOrMatch, value } : overrideOrMatch;
+    this.mockOverrides.push(override);
+  }
+  /** Remove all overrides registered via {@link registerMockOverride}. */
+  clearMockOverrides() {
+    this.mockOverrides.length = 0;
+  }
   async replay(traceFunctionKey, fn, options) {
     const wrappedKey = fn._bitfabTraceFunctionKey;
     let replayFn = fn;
@@ -3660,13 +3817,14 @@ var Bitfab = class {
         `Function is wrapped with trace function key '${wrappedKey}' but replay was called with '${traceFunctionKey}'. Pass matching keys, or pass the unwrapped function to replay it under the explicit key.`
       );
     }
-    const { replay: doReplay } = await import("./replay-IEE4RY57.js");
+    const { replay: doReplay } = await import("./replay-HEGU3YU2.js");
     return doReplay(
       this.httpClient,
       this.serviceUrl,
       traceFunctionKey,
       replayFn,
-      options
+      options,
+      this.mockOverrides
     );
   }
 };
@@ -3885,4 +4043,4 @@ export {
   BitfabFunction,
   finalizers
 };
-//# sourceMappingURL=chunk-SK4TNXRC.js.map
+//# sourceMappingURL=chunk-2M5AWVVQ.js.map