@bitfab/sdk 0.36.0 → 0.36.2

package/dist/index.d.cts

@@ -266,9 +266,11 @@ interface ReplayContext {
      * obtains `databaseUrl` for this item. Reported on the trace completion inside
      * `db_snapshot_usage` so the server can distinguish "branch was
      * provisioned and exposed" from "branch URL was actually consumed".
-     * Any future consumption path that hands the URL to customer code by
-     * other means (e.g. a process-isolated runner writing an env overlay)
-     * must also set this.
+     * Only an explicit `databaseUrl` read may set it. A path that hands the URL
+     * over by other means (e.g. a process-isolated runner writing an env
+     * overlay) must leave it alone: setting it there would make every such
+     * replay report `accessed` for free, and the flag would stop separating
+     * "branch was used" from "branch was offered".
      */
     dbSnapshotAccessed?: boolean;
 }
@@ -455,8 +457,11 @@ declare class HttpClient {
     /**
      * Fetch an external span by ID.
      * Blocking GET request.
+     * The replay view limits rawData to input/output serialization fields.
      */
-    getExternalSpan(spanId: string): Promise<ExternalSpanResponse>;
+    getExternalSpan(spanId: string, options?: {
+        view?: "full" | "replay";
+    }): Promise<ExternalSpanResponse>;
     /**
      * Fetch the span tree for a root span.
      * Blocking GET request.
@@ -464,9 +469,11 @@ declare class HttpClient {
      * 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"`.
+     * Pass `includeRootOutput: false` when the root was already fetched.
      */
     getSpanTree(externalSpanId: string, options?: {
         includeOutputs?: boolean;
+        includeRootOutput?: boolean;
     }): Promise<SpanTreeResponse>;
     /**
      * Read which of a replay run's traces the server has fully persisted.
@@ -1393,10 +1400,20 @@ interface ReplayResult<T> {
  * exposed directly here so customer code never sees the word.
  */
 
-declare class ReplayBranch {
+declare class ReplayBranch implements Omit<DbBranchLease, "databaseUrl"> {
     #private;
+    /** The provider's own id for this branch, e.g. for correlating with its console. */
+    readonly neonBranchId: string;
+    /** Env var name the customer's app reads, e.g. `DATABASE_URL`. */
+    readonly envKey: string;
     /** When this branch's URL stops being valid. ISO-8601. */
     readonly expiresAt: string;
+    /**
+     * The instant this branch is pinned to: the source trace's wall clock, read
+     * just before the traced function ran. Compare it against the trace you meant
+     * to replay to confirm the branch is the right point in history.
+     */
+    readonly snapshotTimestamp?: string;
     /** Deep link to the branch in the provider console, if available. */
     readonly providerConsoleUrl?: string;
     /**
@@ -2336,7 +2353,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.0";
+declare const __version__ = "0.36.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -266,9 +266,11 @@ interface ReplayContext {
      * obtains `databaseUrl` for this item. Reported on the trace completion inside
      * `db_snapshot_usage` so the server can distinguish "branch was
      * provisioned and exposed" from "branch URL was actually consumed".
-     * Any future consumption path that hands the URL to customer code by
-     * other means (e.g. a process-isolated runner writing an env overlay)
-     * must also set this.
+     * Only an explicit `databaseUrl` read may set it. A path that hands the URL
+     * over by other means (e.g. a process-isolated runner writing an env
+     * overlay) must leave it alone: setting it there would make every such
+     * replay report `accessed` for free, and the flag would stop separating
+     * "branch was used" from "branch was offered".
      */
     dbSnapshotAccessed?: boolean;
 }
@@ -455,8 +457,11 @@ declare class HttpClient {
     /**
      * Fetch an external span by ID.
      * Blocking GET request.
+     * The replay view limits rawData to input/output serialization fields.
      */
-    getExternalSpan(spanId: string): Promise<ExternalSpanResponse>;
+    getExternalSpan(spanId: string, options?: {
+        view?: "full" | "replay";
+    }): Promise<ExternalSpanResponse>;
     /**
      * Fetch the span tree for a root span.
      * Blocking GET request.
@@ -464,9 +469,11 @@ declare class HttpClient {
      * 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"`.
+     * Pass `includeRootOutput: false` when the root was already fetched.
      */
     getSpanTree(externalSpanId: string, options?: {
         includeOutputs?: boolean;
+        includeRootOutput?: boolean;
     }): Promise<SpanTreeResponse>;
     /**
      * Read which of a replay run's traces the server has fully persisted.
@@ -1393,10 +1400,20 @@ interface ReplayResult<T> {
  * exposed directly here so customer code never sees the word.
  */
 
-declare class ReplayBranch {
+declare class ReplayBranch implements Omit<DbBranchLease, "databaseUrl"> {
     #private;
+    /** The provider's own id for this branch, e.g. for correlating with its console. */
+    readonly neonBranchId: string;
+    /** Env var name the customer's app reads, e.g. `DATABASE_URL`. */
+    readonly envKey: string;
     /** When this branch's URL stops being valid. ISO-8601. */
     readonly expiresAt: string;
+    /**
+     * The instant this branch is pinned to: the source trace's wall clock, read
+     * just before the traced function ran. Compare it against the trace you meant
+     * to replay to confirm the branch is the right point in history.
+     */
+    readonly snapshotTimestamp?: string;
     /** Deep link to the branch in the provider console, if available. */
     readonly providerConsoleUrl?: string;
     /**
@@ -2336,7 +2353,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.0";
+declare const __version__ = "0.36.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-JECWMVJG.js";
+} from "./chunk-XZKYSTWH.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
@@ -20,7 +20,7 @@ import {
   __version__,
   flushTraces,
   reportReplayProgress
-} from "./chunk-4YTIVUYX.js";
+} from "./chunk-4IY5SZYR.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.36.0";
+    __version__ = "0.36.2";
   }
 });
 
@@ -1528,9 +1528,11 @@ var init_http = __esm({
       /**
        * Fetch an external span by ID.
        * Blocking GET request.
+       * The replay view limits rawData to input/output serialization fields.
        */
-      async getExternalSpan(spanId) {
-        const url = `${this.serviceUrl}/api/sdk/externalSpans/${spanId}`;
+      async getExternalSpan(spanId, options) {
+        const query = options?.view === "replay" ? "?view=replay" : "";
+        const url = `${this.serviceUrl}/api/sdk/externalSpans/${spanId}${query}`;
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), 3e4);
         try {
@@ -1568,9 +1570,18 @@ var init_http = __esm({
        * 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"`.
+       * Pass `includeRootOutput: false` when the root was already fetched.
        */
       async getSpanTree(externalSpanId, options) {
-        const query = options?.includeOutputs === false ? "?includeOutputs=false" : "";
+        const searchParams = new URLSearchParams();
+        if (options?.includeOutputs === false) {
+          searchParams.set("includeOutputs", "false");
+        }
+        if (options?.includeRootOutput === false) {
+          searchParams.set("includeRootOutput", "false");
+        }
+        const encodedQuery = searchParams.toString();
+        const query = encodedQuery ? `?${encodedQuery}` : "";
         const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}${query}`;
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), 3e4);
@@ -2153,7 +2164,9 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         `Replay requested a database branch for trace ${originalTraceId} but it could not be resolved (${leaseError.code}): ${leaseError.message}. The function was not run, because replaying it against the live database would produce a result that looks valid but did not use the historical data you asked for.`
       );
     }
-    const span = await httpClient.getExternalSpan(originalSpanId);
+    const span = await httpClient.getExternalSpan(originalSpanId, {
+      view: "replay"
+    });
     const spanData = span.rawData?.span_data ?? {};
     inputs = deserializeInputs(spanData);
     originalOutput = deserializeOutput(spanData);
@@ -2173,7 +2186,8 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     if (needTree) {
       try {
         const treeResponse = await httpClient.getSpanTree(originalSpanId, {
-          includeOutputs
+          includeOutputs,
+          includeRootOutput: false
         });
         if (treeResponse.root) {
           mockTree = buildMockTree(treeResponse.root);
@@ -2195,7 +2209,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     const fetchSpanOutput = mockTree && !includeOutputs ? (externalSpanId) => {
       let pending = outputCache.get(externalSpanId);
       if (!pending) {
-        pending = httpClient.getExternalSpan(externalSpanId).then(
+        pending = httpClient.getExternalSpan(externalSpanId, { view: "replay" }).then(
           (s) => deserializeOutput(
             s.rawData?.span_data ?? {}
           )
@@ -4195,12 +4209,20 @@ var ReplayBranch = class {
     // context can ride along into a log line or a serialized payload.
     __privateAdd(this, _url);
     __privateAdd(this, _context);
-    this.expiresAt = lease.expiresAt;
-    this.providerConsoleUrl = lease.providerConsoleUrl;
-    this.readOnly = lease.readOnly;
-    this.region = lease.region;
-    this.traceId = traceId;
-    __privateSet(this, _url, lease.databaseUrl);
+    const { databaseUrl, ...exposed } = lease;
+    for (const [key, value] of Object.entries(exposed)) {
+      Object.defineProperty(this, key, {
+        value,
+        enumerable: true,
+        configurable: true
+      });
+    }
+    Object.defineProperty(this, "traceId", {
+      value: traceId,
+      enumerable: true,
+      configurable: true
+    });
+    __privateSet(this, _url, databaseUrl);
     __privateSet(this, _context, context);
   }
   /**
@@ -5540,6 +5562,7 @@ var Bitfab = class {
                   dbSnapshotUsage: {
                     neonBranchId: replayCtx.dbBranchLease.neonBranchId,
                     snapshotTimestamp: replayCtx.dbBranchLease.snapshotTimestamp,
+                    region: replayCtx.dbBranchLease.region,
                     originalTraceId: replayCtx.sourceBitfabTraceId,
                     accessed: replayCtx.dbSnapshotAccessed === true
                   }
@@ -5815,6 +5838,9 @@ var Bitfab = class {
         ...params.dbSnapshotUsage.snapshotTimestamp && {
           snapshot_timestamp: params.dbSnapshotUsage.snapshotTimestamp
         },
+        ...params.dbSnapshotUsage.region && {
+          region: params.dbSnapshotUsage.region
+        },
         ...params.dbSnapshotUsage.originalTraceId && {
           original_trace_id: params.dbSnapshotUsage.originalTraceId,
           // Deprecated wire alias, kept so this SDK still reports usage