@bitfab/sdk 0.18.1 → 0.19.0

package/dist/index.d.cts

@@ -335,6 +335,14 @@ declare class ReplayEnvironment {
     get active(): boolean;
     /** Non-throwing variant for callers that handle the inactive case. */
     snapshot(): ReplayEnvironmentSnapshot | null;
+    /**
+     * Record on the replay context that customer code obtained the branch
+     * URL. Only `databaseUrl` and `snapshot()` count — `active`, `readOnly`
+     * and friends inspect the lease without exposing the connection string,
+     * so they don't prove the replayed code could have connected to the
+     * branch.
+     */
+    private markAccessed;
     private read;
     private require;
 }
@@ -1055,7 +1063,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.18.1";
+declare const __version__ = "0.19.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -335,6 +335,14 @@ declare class ReplayEnvironment {
     get active(): boolean;
     /** Non-throwing variant for callers that handle the inactive case. */
     snapshot(): ReplayEnvironmentSnapshot | null;
+    /**
+     * Record on the replay context that customer code obtained the branch
+     * URL. Only `databaseUrl` and `snapshot()` count — `active`, `readOnly`
+     * and friends inspect the lease without exposing the connection string,
+     * so they don't prove the replayed code could have connected to the
+     * branch.
+     */
+    private markAccessed;
     private read;
     private require;
 }
@@ -1055,7 +1063,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.18.1";
+declare const __version__ = "0.19.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -11,10 +11,10 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-ILIUTS5D.js";
+} from "./chunk-FA6DBCAT.js";
 import {
   BitfabError
-} from "./chunk-QT7HWOKU.js";
+} from "./chunk-EQI6ZJC3.js";
 export {
   Bitfab,
   BitfabClaudeAgentHandler,

package/dist/node.cjs

@@ -91,28 +91,6 @@ var init_errors = __esm({
   }
 });
 
-// src/replayContext.ts
-function getReplayContext() {
-  return replayContextStorage?.getStore() ?? null;
-}
-function runWithReplayContext(ctx, fn) {
-  if (replayContextStorage) {
-    return replayContextStorage.run(ctx, fn);
-  }
-  return fn();
-}
-var replayContextStorage, replayContextReady;
-var init_replayContext = __esm({
-  "src/replayContext.ts"() {
-    "use strict";
-    init_asyncStorage();
-    replayContextStorage = null;
-    replayContextReady = asyncStorageReady.then(() => {
-      replayContextStorage = createAsyncLocalStorage();
-    });
-  }
-});
-
 // src/serialize.ts
 function describeValue(value) {
   try {
@@ -163,12 +141,89 @@ function deserializeValue(serialized) {
     meta: serialized.meta
   });
 }
-var import_superjson, MAX_SERIALIZED_BYTES;
+function toJsonSafe(value) {
+  return toJsonSafeInner(value, 0, /* @__PURE__ */ new WeakSet());
+}
+function toJsonSafeInner(value, depth, seen) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  const className = value?.constructor?.name ?? typeof value;
+  if (depth > MAX_SAFE_DEPTH) {
+    return `<${className}>`;
+  }
+  if (typeof value !== "object") {
+    try {
+      return String(value);
+    } catch {
+      return `<${className}>`;
+    }
+  }
+  if (seen.has(value)) {
+    return `<cycle ${className}>`;
+  }
+  seen.add(value);
+  let result;
+  if (Array.isArray(value)) {
+    result = value.map((item) => toJsonSafeInner(item, depth + 1, seen));
+  } else if (typeof value.toJSON === "function") {
+    try {
+      result = toJsonSafeInner(
+        value.toJSON(),
+        depth + 1,
+        seen
+      );
+    } catch {
+      result = `<${className}>`;
+    }
+  } else {
+    try {
+      const obj = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (!k.startsWith("_")) {
+          obj[k] = toJsonSafeInner(v, depth + 1, seen);
+        }
+      }
+      result = obj;
+    } catch {
+      result = `<${className}>`;
+    }
+  }
+  seen.delete(value);
+  return result;
+}
+var import_superjson, MAX_SERIALIZED_BYTES, MAX_SAFE_DEPTH;
 var init_serialize = __esm({
   "src/serialize.ts"() {
     "use strict";
     import_superjson = __toESM(require("superjson"), 1);
     MAX_SERIALIZED_BYTES = 512e3;
+    MAX_SAFE_DEPTH = 6;
+  }
+});
+
+// src/replayContext.ts
+function getReplayContext() {
+  return replayContextStorage?.getStore() ?? null;
+}
+function runWithReplayContext(ctx, fn) {
+  if (replayContextStorage) {
+    return replayContextStorage.run(ctx, fn);
+  }
+  return fn();
+}
+var replayContextStorage, replayContextReady;
+var init_replayContext = __esm({
+  "src/replayContext.ts"() {
+    "use strict";
+    init_asyncStorage();
+    replayContextStorage = null;
+    replayContextReady = asyncStorageReady.then(() => {
+      replayContextStorage = createAsyncLocalStorage();
+    });
   }
 });
 
@@ -447,13 +502,93 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.18.1";
+var __version__ = "0.19.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
 // src/http.ts
 init_errors();
+function serializePayloadBody(payload) {
+  try {
+    return { body: JSON.stringify(payload), dropped: [] };
+  } catch {
+    const dropped = [];
+    const sanitize = (value, seen) => {
+      const t = typeof value;
+      if (value === null || t === "string" || t === "number" || t === "boolean") {
+        return value;
+      }
+      if (t === "bigint") {
+        dropped.push("BigInt");
+        return "<unserializable: BigInt>";
+      }
+      if (t === "function") {
+        const name = value.name || "Function";
+        dropped.push(name);
+        return `<unserializable: ${name}>`;
+      }
+      if (t === "symbol") {
+        dropped.push("Symbol");
+        return "<unserializable: Symbol>";
+      }
+      if (t !== "object") {
+        return void 0;
+      }
+      const obj = value;
+      const className = obj.constructor?.name || "object";
+      if (seen.has(obj)) {
+        dropped.push(className);
+        return `<cycle: ${className}>`;
+      }
+      seen.add(obj);
+      let result;
+      if (Array.isArray(obj)) {
+        result = obj.map((item) => sanitize(item, seen));
+      } else if (typeof obj.toJSON === "function") {
+        try {
+          result = sanitize(obj.toJSON(), seen);
+        } catch {
+          dropped.push(className);
+          result = `<unserializable: ${className}>`;
+        }
+      } else {
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+          out[k] = sanitize(v, seen);
+        }
+        result = out;
+      }
+      seen.delete(obj);
+      return result;
+    };
+    let sanitized;
+    try {
+      sanitized = sanitize(payload, /* @__PURE__ */ new WeakSet());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        body: JSON.stringify({ error: `payload_serialize_failed: ${message}` }),
+        dropped
+      };
+    }
+    if (dropped.length > 0 && typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized)) {
+      const obj = sanitized;
+      const existing = Array.isArray(obj.errors) ? obj.errors : [];
+      obj.errors = [
+        ...existing,
+        {
+          source: "sdk",
+          step: "json_serialize",
+          error: `stubbed non-serializable value(s): ${[
+            ...new Set(dropped)
+          ].join(", ")}`
+        }
+      ];
+    }
+    return { body: JSON.stringify(sanitized), dropped };
+  }
+}
 var pendingTracePromises = /* @__PURE__ */ new Set();
 function awaitOnExit(promise) {
   pendingTracePromises.add(promise);
@@ -512,23 +647,14 @@ var HttpClient = class {
     const method = options?.method ?? "POST";
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
-    let body;
-    let serializationError;
-    try {
-      body = JSON.stringify(payload);
-    } catch (error) {
-      serializationError = error instanceof Error ? error.message : String(error);
-      body = JSON.stringify({
-        ...Object.fromEntries(
-          Object.entries(payload).filter(
-            ([, v]) => typeof v === "string" || typeof v === "number"
-          )
-        ),
-        rawSpan: {},
-        errors: [
-          { source: "sdk", step: "json_serialize", error: serializationError }
-        ]
-      });
+    const { body, dropped } = serializePayloadBody(payload);
+    if (dropped.length > 0) {
+      try {
+        console.warn(
+          `Bitfab: request body to ${endpoint} held ${dropped.length} non-serializable value(s) (${[...new Set(dropped)].join(", ")}); they were stubbed so the span still sends, but the trace may be incomplete or not replayable. Capture a JSON-safe projection of this input to make it replayable.`
+        );
+      } catch {
+      }
     }
     try {
       const response = await fetch(url, {
@@ -786,33 +912,11 @@ var HttpClient = class {
 };
 
 // src/claudeAgentSdk.ts
+init_serialize();
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
-function safeSerialize(value) {
-  if (value === null || value === void 0) {
-    return value;
-  }
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return value.map(safeSerialize);
-  }
-  if (typeof value === "object") {
-    if (typeof value.toJSON === "function") {
-      return value.toJSON();
-    }
-    const result = {};
-    for (const [k, v] of Object.entries(value)) {
-      if (!k.startsWith("_")) {
-        result[k] = safeSerialize(v);
-      }
-    }
-    return result;
-  }
-  return String(value);
-}
+var safeSerialize = toJsonSafe;
 function extractContentBlocks(content) {
   if (!Array.isArray(content)) {
     return [];
@@ -1568,6 +1672,7 @@ function buildSnapshotRef(config, sdkWallClockBeforeFn) {
 }
 
 // src/langgraph.ts
+init_serialize();
 var LANGSMITH_HIDDEN_TAG = "langsmith:hidden";
 var LANGGRAPH_METADATA_KEYS = [
   "langgraph_step",
@@ -1579,56 +1684,7 @@ var LANGGRAPH_METADATA_KEYS = [
 function nowIso2() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
-var MAX_SERIALIZE_DEPTH = 6;
-function safeSerialize2(value) {
-  return safeSerializeInner(value, 0, /* @__PURE__ */ new WeakSet());
-}
-function safeSerializeInner(value, depth, seen) {
-  if (value === null || value === void 0) {
-    return value;
-  }
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return value;
-  }
-  const className = value?.constructor?.name ?? typeof value;
-  if (depth > MAX_SERIALIZE_DEPTH) {
-    return `<${className}>`;
-  }
-  if (typeof value === "object") {
-    if (seen.has(value)) {
-      return `<cycle ${className}>`;
-    }
-    seen.add(value);
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => safeSerializeInner(item, depth + 1, seen));
-  }
-  if (typeof value === "object") {
-    if (typeof value.toJSON === "function") {
-      try {
-        return value.toJSON();
-      } catch {
-        return `<${className}>`;
-      }
-    }
-    try {
-      const result = {};
-      for (const [k, v] of Object.entries(value)) {
-        if (!k.startsWith("_")) {
-          result[k] = safeSerializeInner(v, depth + 1, seen);
-        }
-      }
-      return result;
-    } catch {
-      return `<${className}>`;
-    }
-  }
-  try {
-    return String(value);
-  } catch {
-    return `<${className}>`;
-  }
-}
+var safeSerialize2 = toJsonSafe;
 function convertMessage(message) {
   if (typeof message !== "object" || message === null) {
     return { role: "unknown", content: String(message) };
@@ -2162,7 +2218,9 @@ var ReplayEnvironment = class {
    * Throws if read outside a replay item.
    */
   get databaseUrl() {
-    return this.require().databaseUrl;
+    const snapshot = this.require();
+    this.markAccessed();
+    return snapshot.databaseUrl;
   }
   /** When the per-trace branch URL stops being valid. ISO-8601. */
   get expiresAt() {
@@ -2190,7 +2248,24 @@ var ReplayEnvironment = class {
   }
   /** Non-throwing variant for callers that handle the inactive case. */
   snapshot() {
-    return this.read();
+    const snapshot = this.read();
+    if (snapshot) {
+      this.markAccessed();
+    }
+    return snapshot;
+  }
+  /**
+   * Record on the replay context that customer code obtained the branch
+   * URL. Only `databaseUrl` and `snapshot()` count — `active`, `readOnly`
+   * and friends inspect the lease without exposing the connection string,
+   * so they don't prove the replayed code could have connected to the
+   * branch.
+   */
+  markAccessed() {
+    const ctx = getReplayContext();
+    if (ctx?.dbBranchLease) {
+      ctx.dbSnapshotAccessed = true;
+    }
   }
   read() {
     const ctx = getReplayContext();
@@ -3122,7 +3197,19 @@ var Bitfab = class {
               contexts: traceState?.contexts ?? [],
               testRunId: traceState?.testRunId,
               inputSourceTraceId: traceState?.inputSourceTraceId,
-              dbSnapshotRef: traceState?.dbSnapshotRef
+              dbSnapshotRef: traceState?.dbSnapshotRef,
+              // Built AFTER the wrapped fn finished, so `accessed` reflects
+              // whether customer code obtained the branch URL during this
+              // item. Omitted entirely when no lease was attached, so the
+              // server can distinguish "no branch" from "branch ignored".
+              ...replayCtx?.dbBranchLease && {
+                dbSnapshotUsage: {
+                  neonBranchId: replayCtx.dbBranchLease.neonBranchId,
+                  snapshotTimestamp: replayCtx.dbBranchLease.snapshotTimestamp,
+                  sourceTraceId: replayCtx.sourceBitfabTraceId,
+                  accessed: replayCtx.dbSnapshotAccessed === true
+                }
+              }
             });
             activeTraceStates.delete(traceId);
             if (persistenceCollector) {
@@ -3294,6 +3381,18 @@ var Bitfab = class {
     if (params.dbSnapshotRef) {
       rawTrace.db_snapshot_ref = params.dbSnapshotRef;
     }
+    if (params.dbSnapshotUsage) {
+      rawTrace.db_snapshot_usage = {
+        neon_branch_id: params.dbSnapshotUsage.neonBranchId,
+        ...params.dbSnapshotUsage.snapshotTimestamp && {
+          snapshot_timestamp: params.dbSnapshotUsage.snapshotTimestamp
+        },
+        ...params.dbSnapshotUsage.sourceTraceId && {
+          source_trace_id: params.dbSnapshotUsage.sourceTraceId
+        },
+        accessed: params.dbSnapshotUsage.accessed
+      };
+    }
     return this.httpClient.sendExternalTrace({
       type: "sdk-function",
       source: "typescript-sdk-function",