@bitfab/sdk 0.27.2 → 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.2";
+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) {
@@ -3352,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.
@@ -3359,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.
    *
@@ -3475,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();
@@ -3534,7 +3594,7 @@ var Bitfab = class {
    */
   getLangGraphCallbackHandler(traceFunctionKey) {
     return new BitfabLangGraphCallbackHandler({
-      apiKey: this.apiKey,
+      apiKey: this.resolveApiKey(),
       traceFunctionKey,
       serviceUrl: this.serviceUrl,
       getActiveSpanContext: () => {
@@ -3586,7 +3646,7 @@ var Bitfab = class {
    */
   getClaudeAgentHandler(traceFunctionKey) {
     return new BitfabClaudeAgentHandler({
-      apiKey: this.apiKey,
+      apiKey: this.resolveApiKey(),
       traceFunctionKey,
       serviceUrl: this.serviceUrl,
       getActiveSpanContext: () => {
@@ -3758,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;
@@ -3775,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)
@@ -4035,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) {
@@ -4046,7 +4108,7 @@ var Bitfab = class {
         });
       },
       setMetadata: (metadata) => {
-        if (!this.enabled) {
+        if (!this.isTracingEnabled()) {
           return Promise.resolve();
         }
         if (typeof metadata !== "object" || metadata === null) {
@@ -4055,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) {