bitfab 0.13.8 → 0.15.0

package/dist/chunk-QT7HWOKU.js

@@ -0,0 +1,131 @@
+// src/errors.ts
+var BitfabError = class extends Error {
+  constructor(message, url) {
+    super(message);
+    this.url = url;
+    this.name = "BitfabError";
+  }
+};
+
+// src/asyncStorage.ts
+var AsyncLocalStorageClass = null;
+var initDone = false;
+function registerAsyncLocalStorageClass(cls) {
+  if (!AsyncLocalStorageClass) {
+    AsyncLocalStorageClass = cls;
+  }
+  initDone = true;
+}
+function assertAsyncStorageRegistered() {
+  if (!AsyncLocalStorageClass) {
+    console.warn(
+      "Bitfab: AsyncLocalStorage not available \u2014 nested span context will not propagate."
+    );
+  }
+}
+var asyncStorageReady = (typeof process !== "undefined" && process.versions?.node ? (
+  // The join trick hides "node:async_hooks" from static analysis so
+  // bundlers that ban Node.js built-ins don't fail at build time.
+  // webpackIgnore tells webpack/turbopack to emit a native import()
+  // so Node.js can resolve the module at runtime.
+  import(
+    /* webpackIgnore: true */
+    ["node", "async_hooks"].join(":")
+  ).then(
+    (mod) => {
+      registerAsyncLocalStorageClass(mod.AsyncLocalStorage);
+    }
+  ).catch(() => {
+  })
+) : Promise.resolve()).then(() => {
+  initDone = true;
+});
+function isAsyncStorageInitDone() {
+  return initDone;
+}
+function createAsyncLocalStorage() {
+  return AsyncLocalStorageClass ? new AsyncLocalStorageClass() : null;
+}
+
+// src/replayContext.ts
+var replayContextStorage = null;
+var replayContextReady = asyncStorageReady.then(() => {
+  replayContextStorage = createAsyncLocalStorage();
+});
+function getReplayContext() {
+  return replayContextStorage?.getStore() ?? null;
+}
+function runWithReplayContext(ctx, fn) {
+  if (replayContextStorage) {
+    return replayContextStorage.run(ctx, fn);
+  }
+  return fn();
+}
+
+// src/serialize.ts
+import superjson from "superjson";
+var MAX_SERIALIZED_BYTES = 512e3;
+function describeValue(value) {
+  try {
+    const ctorName = value?.constructor?.name;
+    if (ctorName && ctorName !== "Object") {
+      return ctorName;
+    }
+  } catch {
+  }
+  return typeof value;
+}
+function unserializableStub(value, reason) {
+  let summary;
+  try {
+    summary = `<unserializable: ${describeValue(value)} (${reason})>`;
+  } catch {
+    summary = `<unserializable (${reason})>`;
+  }
+  return { json: summary };
+}
+function serializeValue(value) {
+  try {
+    const { json, meta } = superjson.serialize(value);
+    let size;
+    try {
+      size = JSON.stringify(json).length;
+    } catch {
+      return unserializableStub(value, "stringify_failed_after_superjson");
+    }
+    if (size > MAX_SERIALIZED_BYTES) {
+      return unserializableStub(value, `too_large_${size}_bytes`);
+    }
+    return meta ? { json, meta } : { json };
+  } catch {
+    try {
+      return { json: JSON.parse(JSON.stringify(value)) };
+    } catch {
+      return unserializableStub(value, "json_stringify_failed");
+    }
+  }
+}
+function deserializeValue(serialized) {
+  if (serialized.meta === void 0) {
+    return serialized.json;
+  }
+  return superjson.deserialize({
+    json: serialized.json,
+    meta: serialized.meta
+  });
+}
+
+export {
+  BitfabError,
+  registerAsyncLocalStorageClass,
+  assertAsyncStorageRegistered,
+  asyncStorageReady,
+  isAsyncStorageInitDone,
+  createAsyncLocalStorage,
+  replayContextReady,
+  getReplayContext,
+  runWithReplayContext,
+  serializeValue,
+  deserializeValue
+};
+//# sourceMappingURL=chunk-QT7HWOKU.js.map

package/dist/chunk-QT7HWOKU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/asyncStorage.ts","../src/replayContext.ts","../src/serialize.ts"],"sourcesContent":["/**\n * Shared error type for Bitfab SDK runtime errors. Lives in its own\n * module to avoid import cycles between `http.ts` and modules that need\n * to throw structured errors (e.g. `dbSnapshot.ts` validation).\n */\n\nexport class BitfabError extends Error {\n  constructor(\n    message: string,\n    public readonly url?: string,\n  ) {\n    super(message)\n    this.name = \"BitfabError\"\n  }\n}\n","/**\n * Shared AsyncLocalStorage loader.\n *\n * Provides two ways to initialize AsyncLocalStorage:\n *\n * 1. **Synchronous registration** (preferred for Node.js):\n *    `asyncStorageNode.ts` calls `registerAsyncLocalStorageClass()` at module\n *    evaluation time, so the class is available immediately — no async gap.\n *    The `node.ts` entry point imports it before anything else.\n *\n * 2. **Async dynamic import** (fallback for the default entry point):\n *    Loads `node:async_hooks` via a bundler-safe dynamic import. This is used\n *    by the default `index.ts` entry point so the SDK works in browsers\n *    (where the import silently fails) and in Node.js when imported via the\n *    default entry point.\n *\n * ## Why the dynamic import looks like this\n *\n * We need to handle three environments:\n *\n * 1. **Pure Node.js** — `import(\"node:async_hooks\")` works natively.\n * 2. **Webpack/Turbopack (Next.js server)** — The bundler processes\n *    `import()` calls at build time. The `webpackIgnore` magic comment tells\n *    webpack (and turbopack) to emit a native `import()` call instead of\n *    trying to resolve it, so Node.js handles it at runtime.\n * 3. **Browsers / Edge** — The `process.versions?.node` guard prevents\n *    execution entirely. If it somehow runs, `.catch(() => {})` swallows\n *    the failure.\n */\n\nexport interface AsyncLocalStorageLike<T> {\n  getStore(): T | undefined\n  run<R>(store: T, fn: () => R): R\n}\n\nlet AsyncLocalStorageClass: (new () => AsyncLocalStorageLike<unknown>) | null =\n  null\nlet initDone = false\n\n/**\n * Register the AsyncLocalStorage class synchronously.\n *\n * Called by `asyncStorageNode.ts` at module evaluation time so the class\n * is available before any span is created — no async gap, no race condition.\n *\n * Safe to call multiple times; subsequent calls are no-ops.\n */\nexport function registerAsyncLocalStorageClass(\n  cls: new () => AsyncLocalStorageLike<unknown>,\n): void {\n  if (!AsyncLocalStorageClass) {\n    AsyncLocalStorageClass = cls\n  }\n  initDone = true\n}\n\n/**\n * Assert that AsyncLocalStorage was registered successfully.\n *\n * Called by `node.ts` after importing `asyncStorageNode.ts` to catch\n * import-order bugs at startup rather than silently degrading to the\n * browser fallback (flat spans with no nesting).\n *\n * This should ONLY be called from the Node.js entry point where we\n * know `node:async_hooks` must be available.\n */\nexport function assertAsyncStorageRegistered(): void {\n  if (!AsyncLocalStorageClass) {\n    console.warn(\n      \"Bitfab: AsyncLocalStorage not available — nested span context will not propagate.\",\n    )\n  }\n}\n\nexport const asyncStorageReady: Promise<void> = (\n  typeof process !== \"undefined\" && process.versions?.node\n    ? // The join trick hides \"node:async_hooks\" from static analysis so\n      // bundlers that ban Node.js built-ins don't fail at build time.\n      // webpackIgnore tells webpack/turbopack to emit a native import()\n      // so Node.js can resolve the module at runtime.\n      import(\n        /* webpackIgnore: true */\n        [\"node\", \"async_hooks\"].join(\":\")\n      )\n        .then(\n          (mod: {\n            AsyncLocalStorage: new () => AsyncLocalStorageLike<unknown>\n          }) => {\n            registerAsyncLocalStorageClass(mod.AsyncLocalStorage)\n          },\n        )\n        .catch(() => {})\n    : Promise.resolve()\n).then(() => {\n  initDone = true\n})\n\nexport function isAsyncStorageInitDone(): boolean {\n  return initDone\n}\n\nexport function createAsyncLocalStorage<T>(): AsyncLocalStorageLike<T> | null {\n  return AsyncLocalStorageClass\n    ? (new AsyncLocalStorageClass() as AsyncLocalStorageLike<T>)\n    : null\n}\n","/**\n * Replay context propagation via AsyncLocalStorage.\n *\n * When set, the withSpan wrapper injects testRunId into the span payload\n * so that new spans created during replay are linked to the test run.\n * Optionally carries a mock tree so child spans can return historical\n * outputs instead of executing.\n */\n\nimport {\n  type AsyncLocalStorageLike,\n  asyncStorageReady,\n  createAsyncLocalStorage,\n} from \"./asyncStorage.js\"\n\n/** A single span entry in the mock tree with its historical output. */\nexport interface MockSpan {\n  sourceSpanId: string\n  output: unknown\n  outputMeta?: unknown\n}\n\n/**\n * Per-item DB branch resolved by the Bitfab service from the source\n * trace's `dbSnapshotRef`. Carried on the replay context so that\n * customer code reads `databaseUrl` through `ReplayEnvironment`, and so\n * the process-isolated replay runner can materialize it into a `.env`\n * overlay file before customer code initializes its DB client.\n *\n * `neonBranchId` is the literal Neon branch id; passing it to\n * `releaseDbBranchLease` deletes that branch.\n */\nexport interface DbBranchLease {\n  neonBranchId: string\n  /** Env var name the customer's app reads, e.g. \"DATABASE_URL\". */\n  envKey: string\n  databaseUrl: string\n  expiresAt: string\n  providerConsoleUrl?: string\n  readOnly?: boolean\n}\n\n/**\n * Pre-built lookup table of historical span outputs.\n * Keys are `${traceFunctionKey}:${spanName}:${callIndex}` so that repeated\n * calls with the same (key, name) are matched by call order, but spans\n * sharing only the traceFunctionKey (different name) do not collide.\n */\nexport interface MockTree {\n  spans: Map<string, MockSpan>\n}\n\nexport interface ReplayContext {\n  testRunId: string\n  traceId?: string\n  inputSourceSpanId?: string\n  /**\n   * External trace ID from `external_traces.id`. Used for span-chain\n   * lookup against the source platform's trace tree (Braintrust, etc.).\n   * NOT the same as the Bitfab `traceId` — see `sourceBitfabTraceId`.\n   */\n  inputSourceTraceId?: string\n  /**\n   * The Bitfab `traces.id` of the historical trace that produced this\n   * replay item's input. This is what customer-facing surfaces (e.g.\n   * `ReplayEnvironment.traceId`) should expose, since it's the ID the\n   * customer sees in the Bitfab dashboard.\n   */\n  sourceBitfabTraceId?: string\n  mockTree?: MockTree\n  callCounters?: Map<string, number>\n  mockStrategy?: \"none\" | \"all\" | \"marked\"\n  dbBranchLease?: DbBranchLease\n  /**\n   * Collector for the replay item's trace-persistence work. When present,\n   * the root span's send path pushes a promise that resolves only after\n   * every span upload AND the trace completion have been sent (registered\n   * synchronously at send time, so the replay runner can await it after\n   * the wrapped fn resolves). This is what lets replay guarantee traces\n   * are persisted server-side before `completeReplay` builds the\n   * trace-ID mapping. Absent outside replay, where sends stay\n   * fire-and-forget.\n   */\n  pendingPersistence?: Promise<unknown>[]\n}\n\nlet replayContextStorage: AsyncLocalStorageLike<ReplayContext | null> | null =\n  null\n\nexport const replayContextReady: Promise<void> = asyncStorageReady.then(() => {\n  replayContextStorage = createAsyncLocalStorage<ReplayContext | null>()\n})\n\n/** Get the current replay context, if any. */\nexport function getReplayContext(): ReplayContext | null {\n  return replayContextStorage?.getStore() ?? null\n}\n\n/** Run a function within a replay context. */\nexport function runWithReplayContext<T>(ctx: ReplayContext, fn: () => T): T {\n  if (replayContextStorage) {\n    return replayContextStorage.run(ctx, fn)\n  }\n  return fn()\n}\n","/**\n * Serialization utilities for Bitfab SDK.\n *\n * This module provides serialization with type metadata preservation,\n * using superjson for handling special JavaScript types like Date, Map,\n * Set, BigInt, undefined, etc.\n */\n\nimport superjson from \"superjson\"\n\n/**\n * Serialized value with JSON data and optional superjson meta for type preservation.\n *\n * The json field contains the JSON-serializable data.\n * The meta field (if present) contains superjson type information for deserializing\n * special types like Date, Map, Set, BigInt, etc.\n */\nexport interface SerializedValue {\n  json: unknown\n  meta?: unknown\n}\n\n// Cap on serialized payload size. superjson can succeed on values like SDK\n// client instances (OpenAI, etc.) and produce hundreds of KB to MB of useless\n// internal state. Anything beyond this is replaced with a stub so the span\n// still ships and the trace isn't dropped server-side.\nconst MAX_SERIALIZED_BYTES = 512_000\n\nfunction describeValue(value: unknown): string {\n  try {\n    const ctorName = (value as { constructor?: { name?: string } })?.constructor\n      ?.name\n    if (ctorName && ctorName !== \"Object\") {\n      return ctorName\n    }\n  } catch {\n    // Property access on `value` can throw (Proxy, poisoned getter).\n  }\n  return typeof value\n}\n\nfunction unserializableStub(value: unknown, reason: string): SerializedValue {\n  let summary: string\n  try {\n    summary = `<unserializable: ${describeValue(value)} (${reason})>`\n  } catch {\n    summary = `<unserializable (${reason})>`\n  }\n  return { json: summary }\n}\n\n/**\n * Serialize a value using superjson for trace storage.\n *\n * Handles arbitrary JavaScript values including:\n * - Date, RegExp, Error\n * - Map, Set\n * - BigInt\n * - undefined (in objects/arrays)\n * - Circular references\n *\n * Guarantees:\n * - Never throws. Pathological inputs (SDK clients, proxies, poisoned\n *   getters, circular graphs that defeat superjson) return a stub string.\n * - Never returns a payload larger than MAX_SERIALIZED_BYTES; oversized\n *   inputs are replaced with a stub. Without this the wire-side\n *   `JSON.stringify` in http.ts can produce a request that times out or\n *   gets rejected, leaving a trace with zero spans.\n *\n * @param value - Any JavaScript value to serialize\n * @returns SerializedValue with 'json' field containing the data.\n *          If type metadata is needed for reconstruction, includes 'meta' field.\n *\n * @example\n * ```typescript\n * const result = serializeValue(new Date('2024-01-15T10:30:00Z'))\n * // result.json contains the ISO string\n * // result.meta contains type info for Date reconstruction\n * ```\n */\nexport function serializeValue(value: unknown): SerializedValue {\n  try {\n    const { json, meta } = superjson.serialize(value)\n\n    let size: number\n    try {\n      size = JSON.stringify(json).length\n    } catch {\n      return unserializableStub(value, \"stringify_failed_after_superjson\")\n    }\n    if (size > MAX_SERIALIZED_BYTES) {\n      return unserializableStub(value, `too_large_${size}_bytes`)\n    }\n\n    return meta ? { json, meta } : { json }\n  } catch {\n    try {\n      return { json: JSON.parse(JSON.stringify(value)) }\n    } catch {\n      return unserializableStub(value, \"json_stringify_failed\")\n    }\n  }\n}\n\n/**\n * Deserialize a value that was serialized with serializeValue.\n *\n * @param serialized - A SerializedValue object with 'json' and optional 'meta'\n * @returns The reconstructed JavaScript value\n *\n * @example\n * ```typescript\n * const serialized = serializeValue(new Date('2024-01-15'))\n * const date = deserializeValue(serialized)\n * // date is a Date object\n * ```\n */\nexport function deserializeValue(serialized: SerializedValue): unknown {\n  if (serialized.meta === undefined) {\n    // No metadata, return as-is\n    return serialized.json\n  }\n\n  // Use superjson to deserialize with type reconstruction\n  // Cast json to the expected superjson type\n  type SuperJSONResult = Parameters<typeof superjson.deserialize>[0]\n  return superjson.deserialize({\n    json: serialized.json as SuperJSONResult[\"json\"],\n    meta: serialized.meta as SuperJSONResult[\"meta\"],\n  })\n}\n"],"mappings":";AAMO,IAAM,cAAN,cAA0B,MAAM;AAAA,EACrC,YACE,SACgB,KAChB;AACA,UAAM,OAAO;AAFG;AAGhB,SAAK,OAAO;AAAA,EACd;AACF;;;ACqBA,IAAI,yBACF;AACF,IAAI,WAAW;AAUR,SAAS,+BACd,KACM;AACN,MAAI,CAAC,wBAAwB;AAC3B,6BAAyB;AAAA,EAC3B;AACA,aAAW;AACb;AAYO,SAAS,+BAAqC;AACnD,MAAI,CAAC,wBAAwB;AAC3B,YAAQ;AAAA,MACN;AAAA,IACF;AAAA,EACF;AACF;AAEO,IAAM,qBACX,OAAO,YAAY,eAAe,QAAQ,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA,EAKhD;AAAA;AAAA,IAEE,CAAC,QAAQ,aAAa,EAAE,KAAK,GAAG;AAAA,IAE/B;AAAA,IACC,CAAC,QAEK;AACJ,qCAA+B,IAAI,iBAAiB;AAAA,IACtD;AAAA,EACF,EACC,MAAM,MAAM;AAAA,EAAC,CAAC;AAAA,IACjB,QAAQ,QAAQ,GACpB,KAAK,MAAM;AACX,aAAW;AACb,CAAC;AAEM,SAAS,yBAAkC;AAChD,SAAO;AACT;AAEO,SAAS,0BAA8D;AAC5E,SAAO,yBACF,IAAI,uBAAuB,IAC5B;AACN;;;ACnBA,IAAI,uBACF;AAEK,IAAM,qBAAoC,kBAAkB,KAAK,MAAM;AAC5E,yBAAuB,wBAA8C;AACvE,CAAC;AAGM,SAAS,mBAAyC;AACvD,SAAO,sBAAsB,SAAS,KAAK;AAC7C;AAGO,SAAS,qBAAwB,KAAoB,IAAgB;AAC1E,MAAI,sBAAsB;AACxB,WAAO,qBAAqB,IAAI,KAAK,EAAE;AAAA,EACzC;AACA,SAAO,GAAG;AACZ;;;AChGA,OAAO,eAAe;AAkBtB,IAAM,uBAAuB;AAE7B,SAAS,cAAc,OAAwB;AAC7C,MAAI;AACF,UAAM,WAAY,OAA+C,aAC7D;AACJ,QAAI,YAAY,aAAa,UAAU;AACrC,aAAO;AAAA,IACT;AAAA,EACF,QAAQ;AAAA,EAER;AACA,SAAO,OAAO;AAChB;AAEA,SAAS,mBAAmB,OAAgB,QAAiC;AAC3E,MAAI;AACJ,MAAI;AACF,cAAU,oBAAoB,cAAc,KAAK,CAAC,KAAK,MAAM;AAAA,EAC/D,QAAQ;AACN,cAAU,oBAAoB,MAAM;AAAA,EACtC;AACA,SAAO,EAAE,MAAM,QAAQ;AACzB;AA+BO,SAAS,eAAe,OAAiC;AAC9D,MAAI;AACF,UAAM,EAAE,MAAM,KAAK,IAAI,UAAU,UAAU,KAAK;AAEhD,QAAI;AACJ,QAAI;AACF,aAAO,KAAK,UAAU,IAAI,EAAE;AAAA,IAC9B,QAAQ;AACN,aAAO,mBAAmB,OAAO,kCAAkC;AAAA,IACrE;AACA,QAAI,OAAO,sBAAsB;AAC/B,aAAO,mBAAmB,OAAO,aAAa,IAAI,QAAQ;AAAA,IAC5D;AAEA,WAAO,OAAO,EAAE,MAAM,KAAK,IAAI,EAAE,KAAK;AAAA,EACxC,QAAQ;AACN,QAAI;AACF,aAAO,EAAE,MAAM,KAAK,MAAM,KAAK,UAAU,KAAK,CAAC,EAAE;AAAA,IACnD,QAAQ;AACN,aAAO,mBAAmB,OAAO,uBAAuB;AAAA,IAC1D;AAAA,EACF;AACF;AAeO,SAAS,iBAAiB,YAAsC;AACrE,MAAI,WAAW,SAAS,QAAW;AAEjC,WAAO,WAAW;AAAA,EACpB;AAKA,SAAO,UAAU,YAAY;AAAA,IAC3B,MAAM,WAAW;AAAA,IACjB,MAAM,WAAW;AAAA,EACnB,CAAC;AACH;","names":[]}

package/dist/{chunk-4ANYHNQJ.js → chunk-YPG3XIG4.js}

@@ -1,14 +1,350 @@
 import {
   BitfabError,
-  DEFAULT_SERVICE_URL,
-  HttpClient,
   asyncStorageReady,
   createAsyncLocalStorage,
   deserializeValue,
   getReplayContext,
   isAsyncStorageInitDone,
   serializeValue
-} from "./chunk-VFGUZWAV.js";
+} from "./chunk-QT7HWOKU.js";
+
+// src/version.generated.ts
+var __version__ = "0.15.0";
+
+// src/constants.ts
+var DEFAULT_SERVICE_URL = "https://bitfab.ai";
+
+// src/http.ts
+var pendingTracePromises = /* @__PURE__ */ new Set();
+function awaitOnExit(promise) {
+  pendingTracePromises.add(promise);
+  void promise.finally(() => {
+    pendingTracePromises.delete(promise);
+  }).catch(() => {
+  });
+  return promise;
+}
+async function flushTraces(timeoutMs = 5e3) {
+  if (pendingTracePromises.size === 0) {
+    return;
+  }
+  await Promise.race([
+    Promise.allSettled(Array.from(pendingTracePromises)),
+    new Promise((resolve) => setTimeout(resolve, timeoutMs))
+  ]);
+}
+if (typeof process !== "undefined" && process.versions != null && process.versions.node != null) {
+  let isFlushing = false;
+  process.on("beforeExit", () => {
+    if (pendingTracePromises.size > 0 && !isFlushing) {
+      isFlushing = true;
+      Promise.allSettled(
+        Array.from(pendingTracePromises).map(
+          (p) => p.catch(() => {
+          })
+        )
+      ).then(() => {
+        isFlushing = false;
+      }).catch(() => {
+        isFlushing = false;
+      });
+    }
+  });
+}
+var HttpClient = class {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.serviceUrl = config.serviceUrl;
+    this.timeout = config.timeout ?? 12e4;
+  }
+  /**
+   * Make an HTTP request to the Bitfab API. Defaults to POST; pass
+   * `options.method` to use a different verb (e.g. "PATCH").
+   *
+   * @param endpoint - The API endpoint (without base URL)
+   * @param payload - The request body
+   * @param options - Optional request options
+   * @returns The parsed JSON response
+   * @throws {BitfabError} If the request fails
+   */
+  async request(endpoint, payload, options) {
+    const url = `${this.serviceUrl}${endpoint}`;
+    const timeout = options?.timeout ?? this.timeout;
+    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 }
+        ]
+      });
+    }
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new BitfabError(
+          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+        );
+      }
+      const result = await response.json();
+      if (result.error) {
+        if (result.url) {
+          throw new BitfabError(
+            `${result.error} Configure it at: ${this.serviceUrl}${result.url}`,
+            result.url
+          );
+        }
+        throw new BitfabError(result.error);
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof BitfabError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BitfabError(`Request timed out after ${timeout}ms`);
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Look up a function by name.
+   * Blocks until complete - needed for function execution.
+   */
+  async lookupFunction(name) {
+    return this.request("/api/sdk/functions/lookup", { name });
+  }
+  /**
+   * Send an internal trace (from BAML execution).
+   * Fire-and-forget with awaitOnExit - doesn't block the caller.
+   */
+  sendInternalTrace(functionId, payload) {
+    void awaitOnExit(
+      this.request(`/api/sdk/functions/${functionId}/traces`, {
+        ...payload,
+        sdkVersion: __version__
+      })
+    ).catch((error) => {
+      try {
+        console.error("Bitfab: Failed to create trace:", error);
+      } catch {
+      }
+    });
+  }
+  /**
+   * Send an external span (from withSpan wrapper or OpenAI tracing).
+   * Fire-and-forget with awaitOnExit - doesn't block the caller.
+   * Returns the tracked promise so callers can optionally await it.
+   */
+  sendExternalSpan(payload) {
+    return awaitOnExit(
+      this.request("/api/sdk/externalSpans", {
+        ...payload,
+        sdkVersion: __version__
+      })
+    ).catch((error) => {
+      try {
+        console.error("Bitfab: Failed to create external span:", error);
+      } catch {
+      }
+    });
+  }
+  /**
+   * Send an external trace (from OpenAI tracing).
+   * Fire-and-forget with awaitOnExit - doesn't block the caller.
+   * Returns the tracked promise so callers can optionally await it
+   * (the replay path does, so trace completions are persisted before
+   * `completeReplay` builds the trace-ID mapping).
+   */
+  sendExternalTrace(payload) {
+    return awaitOnExit(
+      this.request("/api/sdk/externalTraces", {
+        ...payload,
+        sdkVersion: __version__
+      })
+    ).catch((error) => {
+      try {
+        console.error("Bitfab: Failed to create external trace:", error);
+      } catch {
+      }
+    });
+  }
+  /**
+   * Partial update of an existing external trace identified by sourceTraceId.
+   * Used by the detached `client.getTrace(id)` handle. Fire-and-forget;
+   * returns a tracked promise that callers may optionally await.
+   */
+  patchTrace(sourceTraceId, payload) {
+    const endpoint = `/api/sdk/externalTraces/${encodeURIComponent(sourceTraceId)}`;
+    return awaitOnExit(
+      this.request(endpoint, payload, { method: "PATCH" })
+    ).catch((error) => {
+      try {
+        console.error("Bitfab: Failed to patch trace:", error);
+      } catch {
+      }
+    });
+  }
+  /**
+   * 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, includeDbBranchLease, experimentGroupId) {
+    const payload = { traceFunctionKey };
+    if (limit !== void 0) {
+      payload.limit = limit;
+    }
+    if (traceIds) {
+      payload.traceIds = traceIds;
+    }
+    if (codeChangeDescription !== void 0) {
+      payload.codeChangeDescription = codeChangeDescription;
+    }
+    if (codeChangeFiles !== void 0) {
+      payload.codeChangeFiles = codeChangeFiles;
+    }
+    if (includeDbBranchLease) {
+      payload.includeDbBranchLease = true;
+    }
+    if (experimentGroupId !== void 0) {
+      payload.experimentGroupId = experimentGroupId;
+    }
+    const timeout = includeDbBranchLease ? 18e4 : 3e4;
+    return this.request("/api/sdk/replay/start", payload, {
+      timeout
+    });
+  }
+  /**
+   * Fetch an external span by ID.
+   * Blocking GET request.
+   */
+  async getExternalSpan(spanId) {
+    const url = `${this.serviceUrl}/api/sdk/externalSpans/${spanId}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 3e4);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new BitfabError(
+          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof BitfabError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BitfabError("Request timed out after 30000ms");
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Fetch the span tree for a root span.
+   * Blocking GET request.
+   */
+  async getSpanTree(externalSpanId) {
+    const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 3e4);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new BitfabError(
+          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof BitfabError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BitfabError("Request timed out after 30000ms");
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Mark a replay test run as completed.
+   * Blocking call.
+   */
+  async completeReplay(testRunId) {
+    return this.request(
+      "/api/sdk/replay/complete",
+      { testRunId },
+      { 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 by deleting its Neon branch. Idempotent server-side. */
+  async releaseDbBranchLease(neonBranchId) {
+    await this.request(
+      "/api/sdk/replay/releaseDbBranchLease",
+      { neonBranchId },
+      { timeout: 3e4 }
+    );
+  }
+};
 
 // src/claudeAgentSdk.ts
 function nowIso() {
@@ -2162,9 +2498,18 @@ var Bitfab = class {
         spanType: options.type ?? "custom"
       };
       const sendSpan = async (params) => {
+        const replayCtx = getReplayContext();
+        const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
+        let resolvePersistence;
+        if (persistenceCollector) {
+          persistenceCollector.push(
+            new Promise((resolve) => {
+              resolvePersistence = resolve;
+            })
+          );
+        }
         try {
           const endedAt = (/* @__PURE__ */ new Date()).toISOString();
-          const replayCtx = getReplayContext();
           const spanPromise = self.sendWrapperSpan({
             ...baseSpanParams,
             ...params,
@@ -2179,13 +2524,17 @@ var Bitfab = class {
           if (isRootSpan) {
             const pending = pendingSpanPromises.get(traceId) ?? [];
             pending.push(spanPromise);
-            await Promise.race([
-              Promise.allSettled(pending),
-              new Promise((resolve) => setTimeout(resolve, 5e3))
-            ]);
+            if (persistenceCollector) {
+              await Promise.allSettled(pending);
+            } else {
+              await Promise.race([
+                Promise.allSettled(pending),
+                new Promise((resolve) => setTimeout(resolve, 5e3))
+              ]);
+            }
             pendingSpanPromises.delete(traceId);
             const traceState = activeTraceStates.get(traceId);
-            self.sendTraceCompletion({
+            const completionPromise = self.sendTraceCompletion({
               traceFunctionKey,
               traceId,
               startedAt: traceState?.startedAt ?? startedAt,
@@ -2198,6 +2547,9 @@ var Bitfab = class {
               dbSnapshotRef: traceState?.dbSnapshotRef
             });
             activeTraceStates.delete(traceId);
+            if (persistenceCollector) {
+              await completionPromise;
+            }
           } else {
             const pending = pendingSpanPromises.get(traceId);
             if (pending) {
@@ -2207,6 +2559,8 @@ var Bitfab = class {
             }
           }
         } catch {
+        } finally {
+          resolvePersistence?.();
         }
       };
       const replayCtxForMock = getReplayContext();
@@ -2359,7 +2713,7 @@ var Bitfab = class {
     if (params.dbSnapshotRef) {
       rawTrace.db_snapshot_ref = params.dbSnapshotRef;
     }
-    this.httpClient.sendExternalTrace({
+    return this.httpClient.sendExternalTrace({
       type: "sdk-function",
       source: "typescript-sdk-function",
       traceFunctionKey: params.traceFunctionKey,
@@ -2433,11 +2787,13 @@ var Bitfab = class {
    *
    * @param traceFunctionKey - The trace function key to replay
    * @param fn - The function to replay (must be the return value of `withSpan`)
-   * @param options - Optional replay options (limit, traceIds)
+   * @param options - Optional replay options. `limit` and `traceIds` are
+   *   mutually exclusive — an explicit ID list already determines how many
+   *   traces replay, so passing both throws a BitfabError.
    * @returns ReplayResult with items, testRunId, and testRunUrl
    */
   async replay(traceFunctionKey, fn, options) {
-    const { replay: doReplay } = await import("./replay-F7K2JQCZ.js");
+    const { replay: doReplay } = await import("./replay-3MQS22GS.js");
     return doReplay(
       this.httpClient,
       this.serviceUrl,
@@ -2503,6 +2859,9 @@ var BitfabFunction = class {
 };
 
 export {
+  __version__,
+  DEFAULT_SERVICE_URL,
+  flushTraces,
   BitfabClaudeAgentHandler,
   SUPPORTED_PROVIDERS,
   BitfabLangGraphCallbackHandler,
@@ -2513,4 +2872,4 @@ export {
   Bitfab,
   BitfabFunction
 };
-//# sourceMappingURL=chunk-4ANYHNQJ.js.map
+//# sourceMappingURL=chunk-YPG3XIG4.js.map