@bitfab/sdk 0.54.6 → 0.54.8

package/dist/index.d.cts

@@ -426,6 +426,8 @@ declare class HttpClient {
      * the function form if one was supplied. Never read at construction.
      */
     private resolveApiKey;
+    /** @internal Whether this client currently has credentials for trace delivery. */
+    hasApiKey(): boolean;
     /**
      * This client's span transport, built on first use.
      *
@@ -917,6 +919,7 @@ declare class BitfabClaudeAgentHandler {
     private readonly ownsHttpClient;
     private readonly traceFunctionKey;
     private readonly getActiveSpanContext;
+    private readonly shouldRecord;
     private runToSpan;
     private traceId;
     private rootSpanId;
@@ -941,6 +944,7 @@ declare class BitfabClaudeAgentHandler {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext$2 | null;
+        shouldRecord?: () => boolean;
         /**
          * The owning `Bitfab` client's HTTP client. Supplied by
          * `getClaudeAgentHandler()` so this handler shares that client's single
@@ -1412,6 +1416,7 @@ declare class BitfabLangGraphCallbackHandler {
     private readonly ownsHttpClient;
     private readonly traceFunctionKey;
     private readonly getActiveSpanContext;
+    private readonly shouldRecord;
     private readonly captureTools;
     private runToSpan;
     private invocations;
@@ -1421,6 +1426,7 @@ declare class BitfabLangGraphCallbackHandler {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext$1 | null;
+        shouldRecord?: () => boolean;
         /** Whether callback tool events should emit spans. Defaults to true. */
         captureTools?: boolean;
         /**
@@ -2322,6 +2328,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
     private readonly ownsHttpClient;
     private activeTraces;
     private readonly getActiveSpanContext;
+    private readonly shouldRecord;
     private activeSpanMappings;
     private canonicalTraceIds;
     private getCanonicalTraceId;
@@ -2335,6 +2342,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext | null;
+        shouldRecord?: () => boolean;
         /**
          * The owning `Bitfab` client's HTTP client. Supplied by
          * `getOpenAiTracingProcessor()` so this processor shares that client's
@@ -2755,7 +2763,8 @@ declare class Bitfab {
     private readonly serviceUrl;
     private readonly timeout;
     private readonly envVars;
-    private readonly captureConfigured;
+    private readonly captureConfiguredInCode;
+    private captureConfiguredFromEnv;
     private readonly strict;
     private readonly httpClient;
     /** Dataset operations for the authenticated organization. */
@@ -2876,8 +2885,10 @@ declare class Bitfab {
      * early resolve that found nothing never poisons a later one.
      */
     private resolveApiKey;
+    private isCaptureConfigured;
     private isCaptureEnabled;
     private shouldRecord;
+    private prepareFrameworkIntegration;
     get captureEnabled(): boolean;
     /**
      * Fetch the function with its current version and BAML prompt from the server.
@@ -3420,7 +3431,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.54.6";
+declare const __version__ = "0.54.8";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -426,6 +426,8 @@ declare class HttpClient {
      * the function form if one was supplied. Never read at construction.
      */
     private resolveApiKey;
+    /** @internal Whether this client currently has credentials for trace delivery. */
+    hasApiKey(): boolean;
     /**
      * This client's span transport, built on first use.
      *
@@ -917,6 +919,7 @@ declare class BitfabClaudeAgentHandler {
     private readonly ownsHttpClient;
     private readonly traceFunctionKey;
     private readonly getActiveSpanContext;
+    private readonly shouldRecord;
     private runToSpan;
     private traceId;
     private rootSpanId;
@@ -941,6 +944,7 @@ declare class BitfabClaudeAgentHandler {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext$2 | null;
+        shouldRecord?: () => boolean;
         /**
          * The owning `Bitfab` client's HTTP client. Supplied by
          * `getClaudeAgentHandler()` so this handler shares that client's single
@@ -1412,6 +1416,7 @@ declare class BitfabLangGraphCallbackHandler {
     private readonly ownsHttpClient;
     private readonly traceFunctionKey;
     private readonly getActiveSpanContext;
+    private readonly shouldRecord;
     private readonly captureTools;
     private runToSpan;
     private invocations;
@@ -1421,6 +1426,7 @@ declare class BitfabLangGraphCallbackHandler {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext$1 | null;
+        shouldRecord?: () => boolean;
         /** Whether callback tool events should emit spans. Defaults to true. */
         captureTools?: boolean;
         /**
@@ -2322,6 +2328,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
     private readonly ownsHttpClient;
     private activeTraces;
     private readonly getActiveSpanContext;
+    private readonly shouldRecord;
     private activeSpanMappings;
     private canonicalTraceIds;
     private getCanonicalTraceId;
@@ -2335,6 +2342,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext | null;
+        shouldRecord?: () => boolean;
         /**
          * The owning `Bitfab` client's HTTP client. Supplied by
          * `getOpenAiTracingProcessor()` so this processor shares that client's
@@ -2755,7 +2763,8 @@ declare class Bitfab {
     private readonly serviceUrl;
     private readonly timeout;
     private readonly envVars;
-    private readonly captureConfigured;
+    private readonly captureConfiguredInCode;
+    private captureConfiguredFromEnv;
     private readonly strict;
     private readonly httpClient;
     /** Dataset operations for the authenticated organization. */
@@ -2876,8 +2885,10 @@ declare class Bitfab {
      * early resolve that found nothing never poisons a later one.
      */
     private resolveApiKey;
+    private isCaptureConfigured;
     private isCaptureEnabled;
     private shouldRecord;
+    private prepareFrameworkIntegration;
     get captureEnabled(): boolean;
     /**
      * Fetch the function with its current version and BAML prompt from the server.
@@ -3420,7 +3431,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.54.6";
+declare const __version__ = "0.54.8";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -20,7 +20,7 @@ import {
   getCurrentTrace,
   reseedFromRegistry,
   seedFromRegistry
-} from "./chunk-2ZUDLA5T.js";
+} from "./chunk-L4SB4W3Z.js";
 import "./chunk-EGWJYCNT.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -29,7 +29,7 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-2J7QZHRC.js";
+} from "./chunk-M2AEKEZE.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -37,7 +37,7 @@ import {
   MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-QEQXIG5A.js";
+} from "./chunk-4LMLPCYL.js";
 import "./chunk-VCRFFCLY.js";
 export {
   AssertionCategoriesClient,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.54.6";
+    __version__ = "0.54.8";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -2320,6 +2320,15 @@ var init_http = __esm({
       resolveApiKey() {
         return typeof this.apiKey === "function" ? this.apiKey() : this.apiKey;
       }
+      /** @internal Whether this client currently has credentials for trace delivery. */
+      hasApiKey() {
+        try {
+          const apiKey = this.resolveApiKey();
+          return apiKey !== void 0 && apiKey.trim() !== "";
+        } catch {
+          return false;
+        }
+      }
       /**
        * This client's span transport, built on first use.
        *
@@ -4504,6 +4513,7 @@ var BitfabClaudeAgentHandler = class {
     });
     this.traceFunctionKey = config.traceFunctionKey;
     this.getActiveSpanContext = config.getActiveSpanContext ?? null;
+    this.shouldRecord = config.shouldRecord ?? (() => this.httpClient.hasApiKey());
     this.preToolUseHook = this.preToolUseHook.bind(this);
     this.postToolUseHook = this.postToolUseHook.bind(this);
     this.postToolUseFailureHook = this.postToolUseFailureHook.bind(this);
@@ -4608,6 +4618,9 @@ var BitfabClaudeAgentHandler = class {
     this.httpClient.traceCompletion.end(spanInfo.traceId, spanInfo.spanId);
   }
   sendSpan(spanInfo) {
+    if (!this.shouldRecord()) {
+      return;
+    }
     const spanData = {
       name: spanInfo.name,
       type: spanInfo.type
@@ -4651,6 +4664,9 @@ var BitfabClaudeAgentHandler = class {
     }
   }
   sendTraceCompletion(endedAt, metadata) {
+    if (!this.shouldRecord()) {
+      return;
+    }
     if (this.traceId === null) {
       return;
     }
@@ -6192,6 +6208,7 @@ var BitfabLangGraphCallbackHandler = class {
     });
     this.traceFunctionKey = config.traceFunctionKey;
     this.getActiveSpanContext = config.getActiveSpanContext ?? null;
+    this.shouldRecord = config.shouldRecord ?? (() => this.httpClient.hasApiKey());
     this.captureTools = config.captureTools ?? true;
   }
   /**
@@ -6300,6 +6317,9 @@ var BitfabLangGraphCallbackHandler = class {
     this.httpClient.traceCompletion.end(spanInfo.traceId, spanInfo.spanId);
   }
   sendSpan(spanInfo) {
+    if (!this.shouldRecord()) {
+      return;
+    }
     const spanData = {
       name: spanInfo.name,
       type: spanInfo.type
@@ -6343,6 +6363,9 @@ var BitfabLangGraphCallbackHandler = class {
     }
   }
   sendTraceCompletion(rootSpan, activeContext) {
+    if (!this.shouldRecord()) {
+      return;
+    }
     const completed = activeContext === null;
     const traceData = {
       id: rootSpan.traceId,
@@ -6363,6 +6386,9 @@ var BitfabLangGraphCallbackHandler = class {
     }
   }
   sendTraceStart(rootSpan) {
+    if (!this.shouldRecord()) {
+      return;
+    }
     const traceData = {
       id: rootSpan.traceId,
       type: "sdk-function",
@@ -7071,6 +7097,7 @@ var BitfabOpenAITracingProcessor = class {
       timeout: config.timeout ?? 1e4
     });
     this.getActiveSpanContext = config.getActiveSpanContext ?? null;
+    this.shouldRecord = config.shouldRecord ?? (() => this.httpClient.hasApiKey());
   }
   getCanonicalTraceId(sourceTraceId) {
     const existing = this.canonicalTraceIds[sourceTraceId];
@@ -7191,6 +7218,9 @@ var BitfabOpenAITracingProcessor = class {
    * the OpenAI trace into an outer withSpan trace.
    */
   sendTrace(trace, options = {}) {
+    if (!this.shouldRecord()) {
+      return;
+    }
     try {
       const traceData = trace.toJSON();
       if (options.sourceTraceId) {
@@ -7305,6 +7335,9 @@ var BitfabOpenAITracingProcessor = class {
    * and parent_id are rewritten to link the span into the withSpan tree.
    */
   sendSpan(span) {
+    if (!this.shouldRecord()) {
+      return;
+    }
     const errors = [];
     const [serializedSpan, exportErrors] = this.exportSpan(span);
     errors.push(...exportErrors);
@@ -7874,6 +7907,30 @@ function readEnv2(name) {
   }
   return void 0;
 }
+var CAPTURE_ENABLED_ENV = "BITFAB_CAPTURE_ENABLED";
+var TRUE_ENV_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes"]);
+var FALSE_ENV_VALUES = /* @__PURE__ */ new Set(["0", "false", "no"]);
+function readBooleanEnv(name) {
+  const raw = readEnv2(name);
+  if (raw === void 0) {
+    return void 0;
+  }
+  const value = raw.trim().toLowerCase();
+  if (value === "") {
+    return void 0;
+  }
+  if (TRUE_ENV_VALUES.has(value)) {
+    return true;
+  }
+  if (FALSE_ENV_VALUES.has(value)) {
+    return false;
+  }
+  warnOnce(
+    `unrecognized-boolean-env:${name}`,
+    `${name}="${raw}" is not 0 or 1; ignoring it.`
+  );
+  return void 0;
+}
 var DEFAULT_AUTO_TRACE_MAX_DEPTH = 30;
 var DEFAULT_AUTO_TRACE_MAX_SPANS = 500;
 var AUTO_TRACE_PROTOCOL = "ts-auto-v1";
@@ -7928,7 +7985,7 @@ var Bitfab = class {
         "Bitfab({ enabled }) is deprecated; pass captureEnabled instead."
       );
     }
-    this.captureConfigured = (config.captureEnabled ?? true) && (config.enabled ?? true);
+    this.captureConfiguredInCode = config.captureEnabled === void 0 && config.enabled === void 0 ? void 0 : (config.captureEnabled ?? true) && (config.enabled ?? true);
     this.strict = config.strict ?? false;
     this.bamlClient = config.bamlClient ?? null;
     if (config.dbSnapshot) {
@@ -8382,7 +8439,7 @@ var Bitfab = class {
         "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.captureConfigured && !this.apiKeyWarned) {
+    if (this.isCaptureConfigured() && !this.apiKeyWarned) {
       this.apiKeyWarned = true;
       console.warn(
         "Bitfab: apiKey is empty - tracing is disabled. Provide a valid API key to enable tracing."
@@ -8390,18 +8447,32 @@ var Bitfab = class {
     }
     return void 0;
   }
+  isCaptureConfigured() {
+    if (this.captureConfiguredInCode !== void 0) {
+      return this.captureConfiguredInCode;
+    }
+    if (this.captureConfiguredFromEnv === void 0) {
+      this.captureConfiguredFromEnv = readBooleanEnv(CAPTURE_ENABLED_ENV) ?? true;
+    }
+    return this.captureConfiguredFromEnv;
+  }
   isCaptureEnabled() {
-    if (!this.captureConfigured) {
+    if (!this.isCaptureConfigured()) {
       return false;
     }
     return this.resolveApiKey() !== void 0;
   }
   shouldRecord() {
-    if (!this.captureConfigured && !getReplayContext() && !inSeedScope()) {
+    if (!this.isCaptureConfigured() && !getReplayContext() && !inSeedScope()) {
       return false;
     }
     return this.resolveApiKey() !== void 0;
   }
+  prepareFrameworkIntegration() {
+    if (this.isCaptureConfigured() && this.strict) {
+      this.resolveApiKey();
+    }
+  }
   get captureEnabled() {
     return this.isCaptureEnabled();
   }
@@ -8459,14 +8530,16 @@ var Bitfab = class {
           resultStr = String(executionResult.result);
         }
       }
-      this.httpClient.sendInternalTrace(functionVersion.id, {
-        result: resultStr,
-        source: "typescript-sdk",
-        ...Object.keys(inputs).length > 0 && { inputs },
-        ...executionResult.rawCollector != null && {
-          rawCollector: executionResult.rawCollector
-        }
-      });
+      if (this.shouldRecord()) {
+        this.httpClient.sendInternalTrace(functionVersion.id, {
+          result: resultStr,
+          source: "typescript-sdk",
+          ...Object.keys(inputs).length > 0 && { inputs },
+          ...executionResult.rawCollector != null && {
+            rawCollector: executionResult.rawCollector
+          }
+        });
+      }
       return executionResult.result;
     } catch (error) {
       if (error instanceof BitfabError) {
@@ -8496,11 +8569,10 @@ var Bitfab = class {
    * @returns A BitfabOpenAITracingProcessor instance configured for this client
    */
   getOpenAiTracingProcessor() {
+    this.prepareFrameworkIntegration();
     return new BitfabOpenAITracingProcessor({
-      // 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,
+      shouldRecord: () => this.shouldRecord(),
       getActiveSpanContext: () => {
         const stack = getSpanStack();
         return stack[stack.length - 1] ?? null;
@@ -8558,10 +8630,11 @@ var Bitfab = class {
    * @returns A BitfabLangGraphCallbackHandler configured for this client
    */
   getLangGraphCallbackHandler(traceFunctionKey) {
+    this.prepareFrameworkIntegration();
     return new BitfabLangGraphCallbackHandler({
-      apiKey: this.resolveApiKey(),
       traceFunctionKey,
       serviceUrl: this.serviceUrl,
+      shouldRecord: () => this.shouldRecord(),
       getActiveSpanContext: () => {
         const stack = getSpanStack();
         return stack[stack.length - 1] ?? null;
@@ -8600,10 +8673,11 @@ var Bitfab = class {
    * @experimental This API may change before it is stable.
    */
   getLangGraphIntegration(traceFunctionKey, options) {
+    this.prepareFrameworkIntegration();
     const callbackHandler = new BitfabLangGraphCallbackHandler({
-      apiKey: this.resolveApiKey(),
       traceFunctionKey,
       serviceUrl: this.serviceUrl,
+      shouldRecord: () => this.shouldRecord(),
       getActiveSpanContext: () => {
         const stack = getSpanStack();
         return stack[stack.length - 1] ?? null;
@@ -8642,10 +8716,11 @@ var Bitfab = class {
    * @returns A BitfabClaudeAgentHandler configured for this client
    */
   getClaudeAgentHandler(traceFunctionKey) {
+    this.prepareFrameworkIntegration();
     return new BitfabClaudeAgentHandler({
-      apiKey: this.resolveApiKey(),
       traceFunctionKey,
       serviceUrl: this.serviceUrl,
+      shouldRecord: () => this.shouldRecord(),
       getActiveSpanContext: () => {
         const stack = getSpanStack();
         return stack[stack.length - 1] ?? null;