@bitfab/sdk 0.28.11 → 0.29.1

package/dist/{chunk-ZBWTCBVQ.js → chunk-RTPEBWVO.js}

@@ -6,14 +6,15 @@ import {
   getReplayContext,
   isAsyncStorageInitDone,
   randomUuid,
+  resolveMockValue,
   serializeValue,
   toJsonSafe,
   toJsonSafeReport,
   warnOnce
-} from "./chunk-5E4BUIYA.js";
+} from "./chunk-YZU6WFG2.js";
 
 // src/version.generated.ts
-var __version__ = "0.28.11";
+var __version__ = "0.29.1";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -438,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 {
@@ -2821,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;
@@ -3405,7 +3417,7 @@ var Bitfab = class {
                   dbSnapshotUsage: {
                     neonBranchId: replayCtx.dbBranchLease.neonBranchId,
                     snapshotTimestamp: replayCtx.dbBranchLease.snapshotTimestamp,
-                    sourceTraceId: replayCtx.sourceBitfabTraceId,
+                    originalTraceId: replayCtx.sourceBitfabTraceId,
                     accessed: replayCtx.dbSnapshotAccessed === true
                   }
                 }
@@ -3433,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) {
@@ -3656,8 +3721,11 @@ var Bitfab = class {
         ...params.dbSnapshotUsage.snapshotTimestamp && {
           snapshot_timestamp: params.dbSnapshotUsage.snapshotTimestamp
         },
-        ...params.dbSnapshotUsage.sourceTraceId && {
-          source_trace_id: params.dbSnapshotUsage.sourceTraceId
+        ...params.dbSnapshotUsage.originalTraceId && {
+          original_trace_id: params.dbSnapshotUsage.originalTraceId,
+          // Deprecated wire alias, kept so this SDK still reports usage
+          // against servers that predate the rename.
+          source_trace_id: params.dbSnapshotUsage.originalTraceId
         },
         accessed: params.dbSnapshotUsage.accessed
       };
@@ -3730,26 +3798,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;
@@ -3764,13 +3820,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-SKW5A7II.js");
     return doReplay(
       this.httpClient,
       this.serviceUrl,
       traceFunctionKey,
       replayFn,
-      options
+      options,
+      this.mockOverrides
     );
   }
 };
@@ -3989,4 +4046,4 @@ export {
   BitfabFunction,
   finalizers
 };
-//# sourceMappingURL=chunk-ZBWTCBVQ.js.map
+//# sourceMappingURL=chunk-RTPEBWVO.js.map