bitfab 0.13.3 → 0.13.5

package/dist/{chunk-NHYPYRQB.js → chunk-4IHJJRMU.js}

@@ -8,7 +8,7 @@ import {
   getReplayContext,
   isAsyncStorageInitDone,
   serializeValue
-} from "./chunk-LOZFAPCS.js";
+} from "./chunk-BVFST7Q3.js";
 
 // src/claudeAgentSdk.ts
 function nowIso() {
@@ -772,6 +772,31 @@ async function runFunctionWithBaml(bamlSource, inputs, providers, envVars) {
   };
 }
 
+// src/dbSnapshot.ts
+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/langgraph.ts
 var LANGSMITH_HIDDEN_TAG = "langsmith:hidden";
 var LANGGRAPH_METADATA_KEYS = [
@@ -1246,6 +1271,81 @@ var BitfabLangGraphCallbackHandler = class {
   }
 };
 
+// src/replayEnvironment.ts
+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/tracing.ts
 var BitfabOpenAITracingProcessor = class {
   /**
@@ -1737,6 +1837,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,
@@ -2033,7 +2137,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;
@@ -2043,6 +2148,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,
@@ -2052,7 +2158,8 @@ var Bitfab = class {
           },
           ...replayCtxAtRoot?.inputSourceTraceId && {
             inputSourceTraceId: replayCtxAtRoot.inputSourceTraceId
-          }
+          },
+          ...dbSnapshotRef && { dbSnapshotRef }
         });
         pendingSpanPromises.set(traceId, []);
       }
@@ -2072,6 +2179,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,
@@ -2081,6 +2189,9 @@ var Bitfab = class {
             ...replayCtx?.testRunId && { testRunId: replayCtx.testRunId },
             ...replayCtx?.inputSourceSpanId && {
               inputSourceSpanId: replayCtx.inputSourceSpanId
+            },
+            ...dbSnapshotRefForSpan && {
+              dbSnapshotRef: dbSnapshotRefForSpan
             }
           });
           if (isRootSpan) {
@@ -2101,7 +2212,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 {
@@ -2262,6 +2374,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",
@@ -2304,7 +2419,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) {
@@ -2337,7 +2455,7 @@ var Bitfab = class {
    * @returns ReplayResult with items, testRunId, and testRunUrl
    */
   async replay(traceFunctionKey, fn, options) {
-    const { replay: doReplay } = await import("./replay-JX33WJUT.js");
+    const { replay: doReplay } = await import("./replay-CLQKO7U7.js");
     return doReplay(
       this.httpClient,
       this.serviceUrl,
@@ -2347,6 +2465,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;
@@ -2398,11 +2522,13 @@ var BitfabFunction = class {
 
 export {
   BitfabClaudeAgentHandler,
+  SUPPORTED_PROVIDERS,
   BitfabLangGraphCallbackHandler,
+  ReplayEnvironment,
   BitfabOpenAITracingProcessor,
   getCurrentSpan,
   getCurrentTrace,
   Bitfab,
   BitfabFunction
 };
-//# sourceMappingURL=chunk-NHYPYRQB.js.map
+//# sourceMappingURL=chunk-4IHJJRMU.js.map