@bitfab/sdk 0.28.10 → 0.28.11

package/dist/index.cjs

@@ -683,7 +683,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.generated.ts
-var __version__ = "0.28.10";
+var __version__ = "0.28.11";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -923,6 +923,50 @@ var HttpClient = class {
   async lookupFunction(name) {
     return this.request("/api/sdk/functions/lookup", { name });
   }
+  async getTraceSpan(traceId, lookup) {
+    const searchParams = new URLSearchParams();
+    if (lookup.id !== void 0) {
+      searchParams.set("id", lookup.id);
+    } else {
+      searchParams.set("name", lookup.name);
+      searchParams.set("occurrence", String(lookup.occurrence ?? "last"));
+    }
+    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}/span?${searchParams.toString()}`;
+    const response = await this.get(endpoint);
+    return response.span;
+  }
+  async get(endpoint) {
+    const url = `${this.serviceUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
+        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 ${this.timeout}ms`);
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * Send an internal trace (from BAML execution).
    * Fire-and-forget with awaitOnExit - doesn't block the caller.
@@ -979,12 +1023,12 @@ var HttpClient = class {
     });
   }
   /**
-   * Partial update of an existing external trace identified by sourceTraceId.
+   * Partial update of an existing trace identified by its Bitfab trace ID.
    * 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)}`;
+  patchTrace(traceId, payload) {
+    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}`;
     return awaitOnExit(
       this.request(endpoint, payload, { method: "PATCH" })
     ).catch((error) => {
@@ -1322,6 +1366,7 @@ var BitfabClaudeAgentHandler = class {
     const traceId = this.ensureTrace();
     const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
+      id: randomUuid(),
       spanId,
       traceId,
       parentId: parentId ?? null,
@@ -1385,6 +1430,8 @@ var BitfabClaudeAgentHandler = class {
       rawSpan.parent_id = spanInfo.parentId;
     }
     const payload = {
+      id: spanInfo.id,
+      traceId: spanInfo.traceId,
       type: "sdk-function",
       source: "typescript-sdk-claude-agent-sdk",
       traceFunctionKey: this.traceFunctionKey,
@@ -1414,6 +1461,7 @@ var BitfabClaudeAgentHandler = class {
       externalTrace.metadata = metadata;
     }
     const traceData = {
+      id: traceId,
       type: "sdk-function",
       source: "typescript-sdk-claude-agent-sdk",
       traceFunctionKey: this.traceFunctionKey,
@@ -1682,6 +1730,7 @@ var BitfabClaudeAgentHandler = class {
     }
     Object.assign(llmContext, this.currentLlmUsage);
     const spanInfo = {
+      id: randomUuid(),
       spanId,
       traceId,
       parentId,
@@ -2328,6 +2377,7 @@ var BitfabLangGraphCallbackHandler = class {
     const contexts = Object.keys(lgMetadata).length > 0 ? [lgMetadata] : [];
     const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
+      id: randomUuid(),
       spanId: runId,
       traceId: invocation.traceId,
       rootRunId: invocation.rootRunId,
@@ -2406,6 +2456,8 @@ var BitfabLangGraphCallbackHandler = class {
       rawSpan.parent_id = spanInfo.parentId;
     }
     const payload = {
+      id: spanInfo.id,
+      traceId: spanInfo.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2421,6 +2473,7 @@ var BitfabLangGraphCallbackHandler = class {
   sendTraceCompletion(rootSpan, activeContext) {
     const completed = activeContext === null;
     const traceData = {
+      id: rootSpan.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2440,6 +2493,7 @@ var BitfabLangGraphCallbackHandler = class {
   }
   sendTraceStart(rootSpan) {
     const traceData = {
+      id: rootSpan.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2798,6 +2852,7 @@ var ReplayEnvironment = class {
 init_serialize();
 
 // src/tracing.ts
+init_randomUuid();
 var BitfabOpenAITracingProcessor = class {
   /**
    * Initialize the tracing processor.
@@ -2807,6 +2862,7 @@ var BitfabOpenAITracingProcessor = class {
   constructor(config) {
     this.activeTraces = {};
     this.activeSpanMappings = {};
+    this.canonicalTraceIds = {};
     this.httpClient = new HttpClient({
       apiKey: config.apiKey,
       serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
@@ -2814,6 +2870,15 @@ var BitfabOpenAITracingProcessor = class {
     });
     this.getActiveSpanContext = config.getActiveSpanContext ?? null;
   }
+  getCanonicalTraceId(sourceTraceId) {
+    const existing = this.canonicalTraceIds[sourceTraceId];
+    if (existing) {
+      return existing;
+    }
+    const created = randomUuid();
+    this.canonicalTraceIds[sourceTraceId] = created;
+    return created;
+  }
   /**
    * Called when a trace is started.
    * If there's an active withSpan context, the trace ID is remapped to the
@@ -2825,7 +2890,12 @@ var BitfabOpenAITracingProcessor = class {
     if (activeContext) {
       this.activeSpanMappings[trace.traceId] = activeContext;
     }
-    this.sendTrace(trace, activeContext ? { id: activeContext.traceId } : {});
+    const canonicalTraceId = activeContext?.traceId ?? this.getCanonicalTraceId(trace.traceId);
+    this.canonicalTraceIds[trace.traceId] = canonicalTraceId;
+    this.sendTrace(trace, {
+      id: canonicalTraceId,
+      sourceTraceId: activeContext?.traceId
+    });
   }
   /**
    * Called when a trace is ended.
@@ -2834,11 +2904,13 @@ var BitfabOpenAITracingProcessor = class {
    */
   async onTraceEnd(trace) {
     const mapping = this.activeSpanMappings[trace.traceId];
-    this.sendTrace(
-      trace,
-      mapping ? { id: mapping.traceId } : { completed: true }
-    );
+    this.sendTrace(trace, {
+      completed: mapping === void 0,
+      id: mapping?.traceId ?? this.getCanonicalTraceId(trace.traceId),
+      sourceTraceId: mapping?.traceId
+    });
     delete this.activeSpanMappings[trace.traceId];
+    delete this.canonicalTraceIds[trace.traceId];
     delete this.activeTraces[trace.traceId];
   }
   /**
@@ -2868,22 +2940,25 @@ var BitfabOpenAITracingProcessor = class {
   async shutdown(_timeout) {
     this.activeTraces = {};
     this.activeSpanMappings = {};
+    this.canonicalTraceIds = {};
   }
   /**
    * Send trace to Bitfab API (fire-and-forget).
    * When traceIdOverride is provided, the trace ID is remapped to link
    * the OpenAI trace into an outer withSpan trace.
    */
-  sendTrace(trace, overrides = {}) {
+  sendTrace(trace, options = {}) {
     try {
-      const { completed, ...traceOverrides } = overrides;
       const traceData = trace.toJSON();
-      Object.assign(traceData, traceOverrides);
+      if (options.sourceTraceId) {
+        traceData.id = options.sourceTraceId;
+      }
       this.httpClient.sendExternalTrace({
+        ...options.id && { id: options.id },
         type: "openai",
         source: "typescript-sdk-openai-tracing",
         externalTrace: traceData,
-        completed: completed ?? false
+        completed: options.completed ?? false
       });
     } catch {
     }
@@ -2969,6 +3044,7 @@ var BitfabOpenAITracingProcessor = class {
    */
   buildSpanPayload(serializedSpan, errors) {
     const payload = {
+      id: randomUuid(),
       type: "openai",
       source: "typescript-sdk-openai-tracing",
       sourceTraceId: serializedSpan.trace_id ?? "unknown",
@@ -2991,6 +3067,10 @@ var BitfabOpenAITracingProcessor = class {
     this.extractSpanInputResponse(span, serializedSpan, errors);
     this.applySpanOverrides(serializedSpan, span.traceId ?? "");
     const payload = this.buildSpanPayload(serializedSpan, errors);
+    const canonicalTraceId = span.traceId ? this.getCanonicalTraceId(span.traceId) : void 0;
+    if (canonicalTraceId) {
+      payload.traceId = canonicalTraceId;
+    }
     this.httpClient.sendExternalSpan(payload);
   }
 };
@@ -3307,24 +3387,19 @@ function extractContextFromCollector(collector) {
     return null;
   }
 }
-var TRACE_ID_PATTERN = /^[a-zA-Z0-9_\-.:]+$/;
-var TRACE_ID_MAX_LENGTH = 256;
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function validateTraceId(traceId) {
-  if (typeof traceId !== "string" || traceId.length === 0) {
-    throw new BitfabError("traceId is required and must be a non-empty string");
+  if (typeof traceId !== "string" || !UUID_PATTERN.test(traceId)) {
+    throw new BitfabError("traceId must be a valid Bitfab trace ID");
   }
-  if (traceId.length > TRACE_ID_MAX_LENGTH) {
-    throw new BitfabError(
-      `traceId must be ${TRACE_ID_MAX_LENGTH} characters or fewer`
-    );
-  }
-  if (!TRACE_ID_PATTERN.test(traceId)) {
-    throw new BitfabError(
-      `traceId may only contain letters, digits, "_", "-", ".", ":"`
-    );
+}
+function validateSpanId(id) {
+  if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+    throw new BitfabError("id must be a valid Bitfab span ID");
   }
 }
 var noOpSpan = {
+  id: "",
   traceId: "",
   addContext() {
   },
@@ -3348,6 +3423,7 @@ function getCurrentSpan() {
     return noOpSpan;
   }
   return {
+    id: current.spanId,
     traceId: current.traceId,
     addContext(context) {
       try {
@@ -4144,20 +4220,19 @@ var Bitfab = class {
   }
   /**
    * Get a detached handle to a previously-created trace, looked up by the
-   * caller-supplied id (the same id passed at trace creation).
+   * canonical Bitfab trace ID.
    *
    * The returned handle is not tied to AsyncLocalStorage - each method sends
    * to the server immediately. Useful for adding context to a trace from a
    * different process or thread than the one that created it.
    *
-   * Throws synchronously if `traceId` is malformed (empty, too long, or
-   * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
-   * no trace exists with that id in the org; the failure surfaces as a
+   * Throws synchronously if `traceId` is not a valid Bitfab trace ID. The
+   * server returns 404 if no trace exists with that ID in the org; the failure surfaces as a
    * logged warning (fire-and-forget) or via the awaited promise.
    *
    * Example:
    * ```typescript
-   * const trace = client.getTrace("order_abc_123");
+   * const trace = client.getTrace(traceId);
    * await trace.addContext({ refund_status: "approved" });
    * await trace.setMetadata({ region: "us-west" });
    * ```
@@ -4197,6 +4272,33 @@ var Bitfab = class {
       }
     };
   }
+  /**
+   * Fetch one persisted span from a trace without loading the full trace.
+   * Name lookups return the last matching span by default. Pass `occurrence`
+   * as `"first"` or a zero-based index to select a different match.
+   */
+  async getTraceSpan(traceId, lookup) {
+    validateTraceId(traceId);
+    const hasId = lookup.id !== void 0;
+    const hasName = lookup.name !== void 0;
+    if (hasId === hasName) {
+      throw new BitfabError("Provide exactly one of id or name");
+    }
+    if (hasId) {
+      validateSpanId(lookup.id);
+    } else {
+      if (lookup.name.length === 0) {
+        throw new BitfabError("name must be a non-empty string");
+      }
+      const occurrence = lookup.occurrence ?? "last";
+      if (occurrence !== "first" && occurrence !== "last" && (!Number.isInteger(occurrence) || occurrence < 0)) {
+        throw new BitfabError(
+          'occurrence must be "first", "last", or a non-negative integer'
+        );
+      }
+    }
+    return this.httpClient.getTraceSpan(traceId, lookup);
+  }
   /**
    * Get a function wrapper for a specific trace function key.
    *
@@ -4255,6 +4357,7 @@ var Bitfab = class {
       };
     }
     return this.httpClient.sendExternalTrace({
+      id: params.traceId,
       type: "sdk-function",
       source: "typescript-sdk-function",
       traceFunctionKey: params.traceFunctionKey,
@@ -4310,6 +4413,8 @@ var Bitfab = class {
       externalSpan.input_source_span_id = params.inputSourceSpanId;
     }
     return this.httpClient.sendExternalSpan({
+      id: params.spanId,
+      traceId: params.traceId,
       type: "sdk-function",
       source: "typescript-sdk-function",
       sourceTraceId: params.traceId,