@bitfab/sdk 0.27.1 → 0.28.0

package/dist/index.cjs

@@ -636,7 +636,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.generated.ts
-var __version__ = "0.27.1";
+var __version__ = "0.28.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -795,6 +795,13 @@ var HttpClient = class {
     this.serviceUrl = config.serviceUrl;
     this.timeout = config.timeout ?? 12e4;
   }
+  /**
+   * Resolve the API key at the moment it is needed (request time), invoking
+   * the function form if one was supplied. Never read at construction.
+   */
+  resolveApiKey() {
+    return typeof this.apiKey === "function" ? this.apiKey() : this.apiKey;
+  }
   /**
    * Make an HTTP request to the Bitfab API. Defaults to POST; pass
    * `options.method` to use a different verb (e.g. "PATCH").
@@ -825,7 +832,7 @@ var HttpClient = class {
         method,
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`
+          Authorization: `Bearer ${this.resolveApiKey() ?? ""}`
         },
         body,
         signal: controller.signal
@@ -986,7 +993,7 @@ var HttpClient = class {
     try {
       const response = await fetch(url, {
         method: "GET",
-        headers: { Authorization: `Bearer ${this.apiKey}` },
+        headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
         signal: controller.signal
       });
       if (!response.ok) {
@@ -1022,7 +1029,7 @@ var HttpClient = class {
     try {
       const response = await fetch(url, {
         method: "GET",
-        headers: { Authorization: `Bearer ${this.apiKey}` },
+        headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
         signal: controller.signal
       });
       if (!response.ok) {
@@ -1996,6 +2003,7 @@ function buildSnapshotRef(config, sdkWallClockBeforeFn) {
 init_randomUuid();
 init_serialize();
 var LANGSMITH_HIDDEN_TAG = "langsmith:hidden";
+var CHAIN_RUN_TYPES = /* @__PURE__ */ new Set(["chain", "parser", "prompt"]);
 var LANGGRAPH_METADATA_KEYS = [
   "langgraph_step",
   "langgraph_node",
@@ -2006,6 +2014,18 @@ var LANGGRAPH_METADATA_KEYS = [
 function nowIso2() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function normalizeChainStartArgs(parentRunIdOrRunType, runTypeOrRunName, runNameOrParentRunId) {
+  if (parentRunIdOrRunType && CHAIN_RUN_TYPES.has(parentRunIdOrRunType)) {
+    return {
+      parentRunId: runNameOrParentRunId,
+      runName: runTypeOrRunName
+    };
+  }
+  return {
+    parentRunId: parentRunIdOrRunType,
+    runName: runNameOrParentRunId
+  };
+}
 function convertMessage(message) {
   if (typeof message !== "object" || message === null) {
     return { role: "unknown", content: String(message) };
@@ -2217,6 +2237,7 @@ var BitfabLangGraphCallbackHandler = class {
     const willHide = tags?.includes(LANGSMITH_HIDDEN_TAG) === true;
     let invocation;
     let effectiveParentId;
+    let isRootInvocation = false;
     if (parentSpan) {
       const existing = this.invocations.get(parentSpan.rootRunId);
       if (existing) {
@@ -2247,6 +2268,7 @@ var BitfabLangGraphCallbackHandler = class {
       };
       this.invocations.set(runId, invocation);
       effectiveParentId = activeContext?.spanId ?? null;
+      isRootInvocation = true;
     }
     const lgMetadata = extractLangGraphMetadata(metadata);
     const contexts = Object.keys(lgMetadata).length > 0 ? [lgMetadata] : [];
@@ -2269,6 +2291,9 @@ var BitfabLangGraphCallbackHandler = class {
       spanInfo.hidden = true;
     }
     this.runToSpan.set(runId, spanInfo);
+    if (isRootInvocation) {
+      this.sendTraceStart(spanInfo);
+    }
     return spanInfo;
   }
   completeSpan(runId, output, error, extraContexts) {
@@ -2359,11 +2384,35 @@ var BitfabLangGraphCallbackHandler = class {
     } catch {
     }
   }
+  sendTraceStart(rootSpan) {
+    const traceData = {
+      type: "sdk-function",
+      source: "typescript-sdk-langgraph",
+      traceFunctionKey: this.traceFunctionKey,
+      externalTrace: {
+        id: rootSpan.traceId,
+        started_at: rootSpan.startedAt,
+        workflow_name: this.traceFunctionKey
+      },
+      completed: false
+    };
+    const finalized = finalizeTracePayload(traceData);
+    try {
+      this.httpClient.sendExternalTrace(finalized);
+    } catch {
+    }
+  }
   // ── chain callbacks (graph nodes) ─────────────────────────────
-  async handleChainStart(chain, inputs, runId, parentRunId, tags, metadata) {
+  async handleChainStart(chain, inputs, runId, parentRunIdOrRunType, tags, metadata, runTypeOrRunName, runNameOrParentRunId) {
     try {
-      const idArr = chain.id;
-      const name = chain.name ?? idArr?.[idArr.length - 1] ?? "chain";
+      const { parentRunId, runName } = normalizeChainStartArgs(
+        parentRunIdOrRunType,
+        runTypeOrRunName,
+        runNameOrParentRunId
+      );
+      const serialized = chain ?? {};
+      const idArr = serialized.id;
+      const name = runName ?? serialized.name ?? idArr?.[idArr.length - 1] ?? "chain";
       this.startSpan(
         runId,
         parentRunId,
@@ -2398,11 +2447,12 @@ var BitfabLangGraphCallbackHandler = class {
     }
   }
   // ── LLM callbacks ─────────────────────────────────────────────
-  async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, tags, metadata) {
+  async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, tags, metadata, runName) {
     try {
-      const model = extractModelName(llm, metadata);
-      const idArr = llm.id;
-      const name = model ?? idArr?.[idArr.length - 1] ?? "llm";
+      const serialized = llm ?? {};
+      const model = extractModelName(serialized, metadata);
+      const idArr = serialized.id;
+      const name = runName ?? model ?? idArr?.[idArr.length - 1] ?? "llm";
       const converted = messages.map((batch) => batch.map(convertMessage));
       const spanInfo = this.startSpan(
         runId,
@@ -2417,11 +2467,12 @@ var BitfabLangGraphCallbackHandler = class {
     } catch {
     }
   }
-  async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, tags, metadata) {
+  async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, tags, metadata, runName) {
     try {
-      const model = extractModelName(llm, metadata);
-      const idArr = llm.id;
-      const name = model ?? idArr?.[idArr.length - 1] ?? "llm";
+      const serialized = llm ?? {};
+      const model = extractModelName(serialized, metadata);
+      const idArr = serialized.id;
+      const name = runName ?? model ?? idArr?.[idArr.length - 1] ?? "llm";
       const spanInfo = this.startSpan(
         runId,
         parentRunId,
@@ -2474,9 +2525,10 @@ var BitfabLangGraphCallbackHandler = class {
   async handleLLMNewToken() {
   }
   // ── tool callbacks ────────────────────────────────────────────
-  async handleToolStart(tool, input, runId, parentRunId, tags, metadata) {
+  async handleToolStart(tool, input, runId, parentRunId, tags, metadata, runName) {
     try {
-      const name = tool.name ?? "tool";
+      const serialized = tool ?? {};
+      const name = runName ?? serialized.name ?? "tool";
       this.startSpan(
         runId,
         parentRunId,
@@ -2506,9 +2558,10 @@ var BitfabLangGraphCallbackHandler = class {
     }
   }
   // ── retriever callbacks ───────────────────────────────────────
-  async handleRetrieverStart(retriever, query, runId, parentRunId, tags, metadata) {
+  async handleRetrieverStart(retriever, query, runId, parentRunId, tags, metadata, runName) {
     try {
-      const name = retriever.name ?? "retriever";
+      const serialized = retriever ?? {};
+      const name = runName ?? serialized.name ?? "retriever";
       this.startSpan(
         runId,
         parentRunId,
@@ -3306,6 +3359,12 @@ function getCurrentTrace() {
     }
   };
 }
+function readEnv(name) {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env[name];
+  }
+  return void 0;
+}
 var Bitfab = class {
   /**
    * Initialize the Bitfab client.
@@ -3313,30 +3372,75 @@ var Bitfab = class {
    * @param config - Configuration options for the client
    */
   constructor(config) {
-    this.apiKey = config.apiKey;
+    /** Gate the empty-key warning to fire at most once. */
+    this.apiKeyWarned = false;
+    this.apiKeyConfig = config.apiKey;
     this.serviceUrl = config.serviceUrl ?? DEFAULT_SERVICE_URL;
     this.timeout = config.timeout ?? 12e4;
     this.envVars = config.envVars ?? {};
-    const enabled = config.enabled ?? true;
-    if (enabled && (!config.apiKey || config.apiKey.trim() === "")) {
-      console.warn(
-        "Bitfab: apiKey is empty \u2014 tracing is disabled. Provide a valid API key to enable tracing."
-      );
-      this.enabled = false;
-    } else {
-      this.enabled = enabled;
-    }
+    this.explicitlyEnabled = config.enabled ?? true;
+    this.strict = config.strict ?? false;
     this.bamlClient = config.bamlClient ?? null;
     if (config.dbSnapshot) {
       validateDbSnapshotConfig(config.dbSnapshot);
     }
     this.dbSnapshot = config.dbSnapshot;
     this.httpClient = new HttpClient({
-      apiKey: this.apiKey,
+      apiKey: () => this.resolveApiKey(),
       serviceUrl: this.serviceUrl,
       timeout: this.timeout
     });
   }
+  /**
+   * Resolve the API key lazily, the first time a span actually needs it.
+   *
+   * The key is intentionally NOT read at construction. In ESM, a shim that
+   * does `new Bitfab({ apiKey: process.env.BITFAB_API_KEY })` is hoisted and
+   * evaluated before the importing script's body runs `dotenv.config()`, so
+   * the key would be empty at construction even though it is set moments
+   * later. Resolving here (at first `withSpan` call / first request) reads
+   * the key after env loading has run.
+   *
+   * Resolution order: the configured value (string, or function called each
+   * time it is still unresolved), then a fallback read of `BITFAB_API_KEY`
+   * from the environment. Once a non-empty key is found it is cached, so an
+   * early resolve that found nothing never poisons a later one.
+   */
+  resolveApiKey() {
+    if (this.resolvedApiKey !== void 0) {
+      return this.resolvedApiKey;
+    }
+    const fromConfig = typeof this.apiKeyConfig === "function" ? this.apiKeyConfig() : this.apiKeyConfig;
+    const candidate = fromConfig && fromConfig.trim() !== "" ? fromConfig : readEnv("BITFAB_API_KEY");
+    const key = candidate && candidate.trim() !== "" ? candidate : void 0;
+    if (key) {
+      this.resolvedApiKey = key;
+      return key;
+    }
+    if (this.strict) {
+      throw new BitfabError(
+        "Bitfab: no API key resolved. Set BITFAB_API_KEY or pass apiKey to new Bitfab(). If a script loads env with dotenv, load it before the module that constructs the client is imported (e.g. `node --env-file=.env script.ts`), or pass `apiKey: () => process.env.BITFAB_API_KEY`."
+      );
+    }
+    if (this.explicitlyEnabled && !this.apiKeyWarned) {
+      this.apiKeyWarned = true;
+      console.warn(
+        "Bitfab: apiKey is empty \u2014 tracing is disabled. Provide a valid API key to enable tracing."
+      );
+    }
+    return void 0;
+  }
+  /**
+   * Whether tracing should run, decided lazily at call time (not frozen at
+   * construction). An explicit `enabled: false` short-circuits without ever
+   * touching the key.
+   */
+  isTracingEnabled() {
+    if (!this.explicitlyEnabled) {
+      return false;
+    }
+    return this.resolveApiKey() !== void 0;
+  }
   /**
    * Fetch the function with its current version and BAML prompt from the server.
    *
@@ -3429,7 +3533,9 @@ var Bitfab = class {
    */
   getOpenAiTracingProcessor() {
     return new BitfabOpenAITracingProcessor({
-      apiKey: this.apiKey,
+      // Resolved at getter-call time (framework handlers are set up after env
+      // loads); the withSpan path stays lazy via the constructor HttpClient thunk.
+      apiKey: this.resolveApiKey(),
       serviceUrl: this.serviceUrl,
       getActiveSpanContext: () => {
         const stack = getSpanStack();
@@ -3488,7 +3594,7 @@ var Bitfab = class {
    */
   getLangGraphCallbackHandler(traceFunctionKey) {
     return new BitfabLangGraphCallbackHandler({
-      apiKey: this.apiKey,
+      apiKey: this.resolveApiKey(),
       traceFunctionKey,
       serviceUrl: this.serviceUrl,
       getActiveSpanContext: () => {
@@ -3540,7 +3646,7 @@ var Bitfab = class {
    */
   getClaudeAgentHandler(traceFunctionKey) {
     return new BitfabClaudeAgentHandler({
-      apiKey: this.apiKey,
+      apiKey: this.resolveApiKey(),
       traceFunctionKey,
       serviceUrl: this.serviceUrl,
       getActiveSpanContext: () => {
@@ -3712,9 +3818,8 @@ var Bitfab = class {
    * @returns A wrapped function with the same signature that creates spans for inputs and outputs
    */
   withSpan(traceFunctionKey, optionsOrFn, maybeFn) {
-    if (!this.enabled) {
-      const fn2 = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
-      return fn2;
+    if (!this.explicitlyEnabled) {
+      return typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
     }
     const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
     const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
@@ -3729,6 +3834,9 @@ var Bitfab = class {
       }
     })();
     const wrappedFn = function(...args) {
+      if (!self.isTracingEnabled()) {
+        return fn.apply(this, args);
+      }
       if (!asyncLocalStorage && !isAsyncStorageInitDone()) {
         return asyncLocalStorageReady.then(
           () => wrappedFn.apply(this, args)
@@ -3989,7 +4097,7 @@ var Bitfab = class {
     return {
       traceId,
       addContext: (context) => {
-        if (!this.enabled) {
+        if (!this.isTracingEnabled()) {
           return Promise.resolve();
         }
         if (typeof context !== "object" || context === null) {
@@ -4000,7 +4108,7 @@ var Bitfab = class {
         });
       },
       setMetadata: (metadata) => {
-        if (!this.enabled) {
+        if (!this.isTracingEnabled()) {
           return Promise.resolve();
         }
         if (typeof metadata !== "object" || metadata === null) {
@@ -4009,7 +4117,7 @@ var Bitfab = class {
         return this.httpClient.patchTrace(traceId, { mergeMetadata: metadata });
       },
       setSessionId: (sessionId) => {
-        if (!this.enabled) {
+        if (!this.isTracingEnabled()) {
           return Promise.resolve();
         }
         if (typeof sessionId !== "string" || sessionId.length === 0) {