@bitfab/sdk 0.13.3 → 0.13.5

package/dist/index.cjs

@@ -35,7 +35,7 @@ var __version__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.13.3";
+    __version__ = "0.13.5";
   }
 });
 
@@ -49,6 +49,21 @@ var init_constants = __esm({
   }
 });
 
+// src/errors.ts
+var BitfabError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    "use strict";
+    BitfabError = class extends Error {
+      constructor(message, url) {
+        super(message);
+        this.url = url;
+        this.name = "BitfabError";
+      }
+    };
+  }
+});
+
 // src/http.ts
 function awaitOnExit(promise) {
   pendingTracePromises.add(promise);
@@ -67,18 +82,12 @@ async function flushTraces(timeoutMs = 5e3) {
     new Promise((resolve) => setTimeout(resolve, timeoutMs))
   ]);
 }
-var BitfabError, pendingTracePromises, HttpClient;
+var pendingTracePromises, HttpClient;
 var init_http = __esm({
   "src/http.ts"() {
     "use strict";
     init_constants();
-    BitfabError = class extends Error {
-      constructor(message, url) {
-        super(message);
-        this.url = url;
-        this.name = "BitfabError";
-      }
-    };
+    init_errors();
     pendingTracePromises = /* @__PURE__ */ new Set();
     if (typeof process !== "undefined" && process.versions != null && process.versions.node != null) {
       let isFlushing = false;
@@ -257,7 +266,7 @@ var init_http = __esm({
        * Start a replay session by fetching historical traces.
        * Blocking call — creates a test run and returns lightweight item references.
        */
-      async startReplay(traceFunctionKey, limit, traceIds, codeChangeDescription, codeChangeFiles) {
+      async startReplay(traceFunctionKey, limit, traceIds, codeChangeDescription, codeChangeFiles, includeDbBranchLease) {
         const payload = { traceFunctionKey, limit };
         if (traceIds) {
           payload.traceIds = traceIds;
@@ -268,8 +277,12 @@ var init_http = __esm({
         if (codeChangeFiles !== void 0) {
           payload.codeChangeFiles = codeChangeFiles;
         }
+        if (includeDbBranchLease) {
+          payload.includeDbBranchLease = true;
+        }
+        const timeout = includeDbBranchLease ? 18e4 : 3e4;
         return this.request("/api/sdk/replay/start", payload, {
-          timeout: 3e4
+          timeout
         });
       }
       /**
@@ -355,6 +368,27 @@ var init_http = __esm({
           { timeout: 3e4 }
         );
       }
+      /**
+       * 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.
+       */
+      async resolveDbBranchLease(testRunId, traceId, dbSnapshotRef) {
+        return this.request(
+          "/api/sdk/replay/resolveDbBranchLease",
+          { testRunId, traceId, dbSnapshotRef },
+          { timeout: 9e4 }
+        );
+      }
+      /** Release a previously-resolved DB branch lease. Idempotent server-side. */
+      async releaseDbBranchLease(leaseId) {
+        await this.request(
+          "/api/sdk/replay/releaseDbBranchLease",
+          { leaseId },
+          { timeout: 3e4 }
+        );
+      }
     };
   }
 });
@@ -532,42 +566,66 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy) {
-  const span = await httpClient.getExternalSpan(serverItem.externalSpanId);
-  const spanData = span.rawData?.span_data ?? {};
-  const inputs = deserializeInputs(spanData);
-  const originalOutput = deserializeOutput(spanData);
-  let mockTree;
-  if (mockStrategy === "all" || mockStrategy === "marked") {
-    const treeResponse = await httpClient.getSpanTree(serverItem.externalSpanId);
-    mockTree = buildMockTree(treeResponse.root);
-  }
+async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, environment) {
+  const lease = environment ? serverItem.dbBranchLease : void 0;
+  let inputs = [];
+  let originalOutput;
   let result;
   let error = null;
+  const replayedTraceId = crypto.randomUUID();
   try {
+    const span = await httpClient.getExternalSpan(serverItem.externalSpanId);
+    const spanData = span.rawData?.span_data ?? {};
+    inputs = deserializeInputs(spanData);
+    originalOutput = deserializeOutput(spanData);
+    let mockTree;
+    if (mockStrategy === "all" || mockStrategy === "marked") {
+      const treeResponse = await httpClient.getSpanTree(
+        serverItem.externalSpanId
+      );
+      mockTree = buildMockTree(treeResponse.root);
+    }
     const maybePromise = runWithReplayContext(
       {
         testRunId,
+        traceId: replayedTraceId,
         inputSourceSpanId: span.id,
         inputSourceTraceId: span.externalTraceId,
+        sourceBitfabTraceId: serverItem.traceId,
         mockTree,
         callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
-        mockStrategy
+        mockStrategy,
+        dbBranchLease: lease
       },
       () => fn(...inputs)
     );
     result = maybePromise instanceof Promise ? await maybePromise : maybePromise;
   } catch (e) {
     error = e instanceof Error ? e.message : String(e);
+  } finally {
+    if (lease) {
+      try {
+        await httpClient.releaseDbBranchLease(lease.leaseId);
+      } catch (e) {
+        try {
+          console.warn(
+            `Bitfab: failed to release DB branch lease ${lease.leaseId} (TTL janitor will catch it): ${e instanceof Error ? e.message : String(e)}`
+          );
+        } catch {
+        }
+      }
+    }
   }
   return {
+    traceId: replayedTraceId,
     input: inputs,
     result,
     originalOutput,
     error,
     durationMs: serverItem.durationMs ?? null,
     tokens: serverItem.tokens ?? null,
-    model: serverItem.model ?? null
+    model: serverItem.model ?? null,
+    dbSnapshotRef: serverItem.dbSnapshotRef ?? null
   };
 }
 async function mapWithConcurrency(tasks, maxConcurrency) {
@@ -597,23 +655,39 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     options?.limit ?? 5,
     options?.traceIds,
     options?.codeChangeDescription,
-    options?.codeChangeFiles
+    options?.codeChangeFiles,
+    options?.environment !== void 0
+    // includeDbBranchLease
   );
   const mockStrategy = options?.mock ?? "none";
   const maxConcurrency = options?.maxConcurrency ?? 10;
   const tasks = serverItems.map(
-    (serverItem) => () => processItem(httpClient, serverItem, fn, testRunId, mockStrategy)
+    (serverItem) => () => processItem(
+      httpClient,
+      serverItem,
+      fn,
+      testRunId,
+      mockStrategy,
+      options?.environment
+    )
   );
   const resultItems = await mapWithConcurrency(tasks, maxConcurrency);
   await flushTraces();
+  let serverTraceIds = {};
   try {
-    await httpClient.completeReplay(testRunId);
+    const completeResult = await httpClient.completeReplay(testRunId);
+    serverTraceIds = completeResult.traceIds ?? {};
   } catch (e) {
     try {
       console.error("Bitfab: Failed to complete replay:", e);
     } catch {
     }
   }
+  for (const item of resultItems) {
+    if (item.traceId) {
+      item.traceId = serverTraceIds[item.traceId] ?? null;
+    }
+  }
   return {
     items: resultItems,
     testRunId,
@@ -639,6 +713,8 @@ __export(index_exports, {
   BitfabLangGraphCallbackHandler: () => BitfabLangGraphCallbackHandler,
   BitfabOpenAITracingProcessor: () => BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL: () => DEFAULT_SERVICE_URL,
+  ReplayEnvironment: () => ReplayEnvironment,
+  SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
   __version__: () => __version__,
   flushTraces: () => flushTraces,
   getCurrentSpan: () => getCurrentSpan,
@@ -1415,6 +1491,34 @@ async function runFunctionWithBaml(bamlSource, inputs, providers, envVars) {
 
 // src/client.ts
 init_constants();
+
+// src/dbSnapshot.ts
+init_errors();
+var SUPPORTED_PROVIDERS = [
+  "neon",
+  "ardent",
+  "dolt",
+  "gfs",
+  "mongodb-atlas",
+  "dynamodb",
+  "snowflake",
+  "bigquery"
+];
+function validateDbSnapshotConfig(config) {
+  if (!SUPPORTED_PROVIDERS.includes(config.provider)) {
+    throw new BitfabError(
+      `dbSnapshot.provider "${config.provider}" is not supported. Supported providers: ${SUPPORTED_PROVIDERS.join(", ")}.`
+    );
+  }
+}
+function buildSnapshotRef(config, sdkWallClockBeforeFn) {
+  return {
+    provider: config.provider,
+    sdkWallClockBeforeFn
+  };
+}
+
+// src/client.ts
 init_http();
 
 // src/langgraph.ts
@@ -1895,6 +1999,84 @@ var BitfabLangGraphCallbackHandler = class {
 
 // src/client.ts
 init_replayContext();
+
+// src/replayEnvironment.ts
+init_replayContext();
+var ReplayEnvironment = class {
+  /**
+   * The per-trace branch URL for the item currently being replayed.
+   * Throws if read outside a replay item.
+   */
+  get databaseUrl() {
+    return this.require().databaseUrl;
+  }
+  /** When the per-trace branch URL stops being valid. ISO-8601. */
+  get expiresAt() {
+    return this.require().expiresAt;
+  }
+  /** Deep link to the branch in the provider console, if available. */
+  get providerConsoleUrl() {
+    return this.require().providerConsoleUrl;
+  }
+  /**
+   * True if the branch is read-only. Customer code can use this to skip
+   * write operations during replay when the provider returned a read-only
+   * lease.
+   */
+  get readOnly() {
+    return this.require().readOnly;
+  }
+  /** The historical trace ID that produced the input for this replay item. */
+  get traceId() {
+    return this.require().traceId;
+  }
+  /**
+   * How the resolver pinned this branch.
+   * - "timestamp": snapshot at SDK wall clock; bounded by replication lag.
+   * - "lsn": customer LSN mapped to a replica snapshot (future).
+   */
+  get precision() {
+    return this.require().precision;
+  }
+  /** True when read inside a replay item that has a resolved branch. */
+  get active() {
+    return this.read() !== null;
+  }
+  /** Non-throwing variant for callers that handle the inactive case. */
+  snapshot() {
+    return this.read();
+  }
+  read() {
+    const ctx = getReplayContext();
+    if (!ctx?.dbBranchLease) {
+      return null;
+    }
+    const traceId = ctx.sourceBitfabTraceId ?? ctx.inputSourceTraceId;
+    if (!traceId) {
+      return null;
+    }
+    const lease = ctx.dbBranchLease;
+    return {
+      databaseUrl: lease.databaseUrl,
+      expiresAt: lease.expiresAt,
+      providerConsoleUrl: lease.providerConsoleUrl,
+      readOnly: lease.readOnly,
+      traceId,
+      precision: lease.precision
+    };
+  }
+  require() {
+    const snapshot = this.read();
+    if (!snapshot) {
+      throw new Error(
+        "ReplayEnvironment accessed outside of a replay item. Pass it to bitfab.replay({ environment }) and only read it inside the replayed function."
+      );
+    }
+    return snapshot;
+  }
+};
+
+// src/client.ts
 init_serialize();
 
 // src/tracing.ts
@@ -2390,6 +2572,10 @@ var Bitfab = class {
       this.enabled = enabled;
     }
     this.bamlClient = config.bamlClient ?? null;
+    if (config.dbSnapshot) {
+      validateDbSnapshotConfig(config.dbSnapshot);
+    }
+    this.dbSnapshot = config.dbSnapshot;
     this.httpClient = new HttpClient({
       apiKey: this.apiKey,
       serviceUrl: this.serviceUrl,
@@ -2686,7 +2872,8 @@ var Bitfab = class {
       }
       const currentStack = getSpanStack();
       const parentContext = currentStack[currentStack.length - 1];
-      const traceId = parentContext?.traceId ?? crypto.randomUUID();
+      const replayCtxForTraceId = parentContext ? null : getReplayContext();
+      const traceId = parentContext?.traceId ?? replayCtxForTraceId?.traceId ?? crypto.randomUUID();
       const spanId = crypto.randomUUID();
       const parentSpanId = parentContext?.spanId ?? null;
       const isRootSpan = parentSpanId === null;
@@ -2696,6 +2883,7 @@ var Bitfab = class {
       const startedAt = (/* @__PURE__ */ new Date()).toISOString();
       if (isRootSpan && !activeTraceStates.has(traceId)) {
         const replayCtxAtRoot = getReplayContext();
+        const dbSnapshotRef = self.dbSnapshot ? buildSnapshotRef(self.dbSnapshot, startedAt) : void 0;
         activeTraceStates.set(traceId, {
           traceId,
           startedAt,
@@ -2705,7 +2893,8 @@ var Bitfab = class {
           },
           ...replayCtxAtRoot?.inputSourceTraceId && {
             inputSourceTraceId: replayCtxAtRoot.inputSourceTraceId
-          }
+          },
+          ...dbSnapshotRef && { dbSnapshotRef }
         });
         pendingSpanPromises.set(traceId, []);
       }
@@ -2725,6 +2914,7 @@ var Bitfab = class {
         try {
           const endedAt = (/* @__PURE__ */ new Date()).toISOString();
           const replayCtx = getReplayContext();
+          const dbSnapshotRefForSpan = isRootSpan ? activeTraceStates.get(traceId)?.dbSnapshotRef : void 0;
           const spanPromise = self.sendWrapperSpan({
             ...baseSpanParams,
             ...params,
@@ -2734,6 +2924,9 @@ var Bitfab = class {
             ...replayCtx?.testRunId && { testRunId: replayCtx.testRunId },
             ...replayCtx?.inputSourceSpanId && {
               inputSourceSpanId: replayCtx.inputSourceSpanId
+            },
+            ...dbSnapshotRefForSpan && {
+              dbSnapshotRef: dbSnapshotRefForSpan
             }
           });
           if (isRootSpan) {
@@ -2754,7 +2947,8 @@ var Bitfab = class {
               metadata: traceState?.metadata,
               contexts: traceState?.contexts ?? [],
               testRunId: traceState?.testRunId,
-              inputSourceTraceId: traceState?.inputSourceTraceId
+              inputSourceTraceId: traceState?.inputSourceTraceId,
+              dbSnapshotRef: traceState?.dbSnapshotRef
             });
             activeTraceStates.delete(traceId);
           } else {
@@ -2915,6 +3109,9 @@ var Bitfab = class {
     if (params.inputSourceTraceId) {
       rawTrace.input_source_trace_id = params.inputSourceTraceId;
     }
+    if (params.dbSnapshotRef) {
+      rawTrace.db_snapshot_ref = params.dbSnapshotRef;
+    }
     this.httpClient.sendExternalTrace({
       type: "sdk-function",
       source: "typescript-sdk-function",
@@ -2957,7 +3154,10 @@ var Bitfab = class {
         ...params.contexts && params.contexts.length > 0 && {
           contexts: params.contexts
         },
-        ...params.prompt !== void 0 && { prompt: params.prompt }
+        ...params.prompt !== void 0 && { prompt: params.prompt },
+        ...params.dbSnapshotRef && {
+          db_snapshot_ref: params.dbSnapshotRef
+        }
       }
     };
     if (params.parentSpanId) {
@@ -3000,6 +3200,12 @@ var Bitfab = class {
     );
   }
 };
+/**
+ * Per-trace environment for `replay({ environment })`. Construct one,
+ * pass it to replay, and read `env.databaseUrl` inside the replayed
+ * function to pick up the per-trace branch URL.
+ */
+Bitfab.ReplayEnvironment = ReplayEnvironment;
 var BitfabFunction = class {
   constructor(client, traceFunctionKey) {
     this.client = client;
@@ -3061,6 +3267,8 @@ init_http();
   BitfabLangGraphCallbackHandler,
   BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL,
+  ReplayEnvironment,
+  SUPPORTED_PROVIDERS,
   __version__,
   flushTraces,
   getCurrentSpan,