bitfab 0.27.2 → 0.28.1

package/dist/index.d.cts

@@ -30,6 +30,91 @@ type AllowedEnvVars = {
     OPENAI_API_KEY?: string;
 };
 
+/**
+ * Per-trace database snapshot ref capture.
+ *
+ * Every root span carries a `DbSnapshotRef` that pins the DB state at trace
+ * open by wall-clock timestamp. Capturing the timestamp is free (no IO) and
+ * harmless, so it happens on every trace regardless of configuration: that
+ * lets any trace be replayed against a historical branch later. A `provider`
+ * is attached only when the customer configured `dbSnapshot`; when absent it
+ * is resolved at replay time. The Bitfab service uses the timestamp to
+ * materialize an ephemeral branch from `customer-main`.
+ */
+declare const SUPPORTED_PROVIDERS: readonly ["neon"];
+type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
+interface DbSnapshotConfig {
+    /** Discriminator for the server-side resolver. */
+    provider: DbSnapshotProvider;
+}
+interface DbSnapshotRef {
+    /**
+     * The wall-clock ISO timestamp the SDK observed immediately before
+     * invoking the wrapped function. The name encodes its provenance:
+     * SDK-observed, wall clock (not monotonic), captured before user code
+     * began executing. Always present.
+     */
+    sdkWallClockBeforeFn: string;
+    /**
+     * The configured provider for server-side branch resolution. Only set when
+     * the customer configured `dbSnapshot`; otherwise the provider is resolved
+     * at replay time.
+     */
+    provider?: DbSnapshotProvider;
+}
+
+/**
+ * Shared error type for Bitfab SDK runtime errors. Lives in its own
+ * module to avoid import cycles between `http.ts` and modules that need
+ * to throw structured errors (e.g. `dbSnapshot.ts` validation).
+ */
+declare class BitfabError extends Error {
+    readonly url?: string | undefined;
+    constructor(message: string, url?: string | undefined);
+}
+
+/**
+ * HTTP client utilities for Bitfab API requests.
+ *
+ * This module provides:
+ * - HttpClient class for making API requests
+ * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
+ */
+
+/**
+ * Wait for all pending fire-and-forget operations (spans, traces) to complete.
+ * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.
+ *
+ * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+ */
+declare function flushTraces(timeoutMs?: number): Promise<void>;
+/**
+ * How the API key is supplied internally: either a literal string or a
+ * function resolved each time the key is needed (at request/send time). The
+ * function form is what defers key resolution past module-load construction
+ * so an env var loaded after the client is built (the ESM dotenv-hoisting
+ * case) is still picked up.
+ */
+type ApiKeyInput = string | (() => string | undefined);
+interface TokenUsage {
+    input: number | null;
+    output: number | null;
+    cached: number | null;
+    total: number | null;
+}
+/**
+ * Describes a single file edited as part of a code change.
+ *
+ * - `path`: file path (relative to the repo root, or any consistent root)
+ * - `before`: file contents before the change ("" for newly created files)
+ * - `after`: file contents after the change ("" for deleted files)
+ */
+interface CodeChangeFile {
+    path: string;
+    before: string;
+    after: string;
+}
+
 /**
  * Claude Agent SDK handler for Bitfab tracing.
  *
@@ -40,6 +125,7 @@ type AllowedEnvVars = {
  *   1. SDK hooks (PreToolUse, PostToolUse, etc.) for tool/subagent lifecycle
  *   2. Stream wrapping for LLM turn capture from the message stream
  */
+
 interface ActiveSpanContext$2 {
     traceId: string;
     spanId: string;
@@ -96,7 +182,7 @@ declare class BitfabClaudeAgentHandler {
     private rootInput;
     private rootOutput;
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         traceFunctionKey: string;
         serviceUrl?: string;
         timeout?: number;
@@ -285,83 +371,6 @@ declare class BitfabVercelAiHandler {
     get middleware(): BitfabLanguageModelMiddleware;
 }
 
-/**
- * Per-trace database snapshot ref capture.
- *
- * Every root span carries a `DbSnapshotRef` that pins the DB state at trace
- * open by wall-clock timestamp. Capturing the timestamp is free (no IO) and
- * harmless, so it happens on every trace regardless of configuration: that
- * lets any trace be replayed against a historical branch later. A `provider`
- * is attached only when the customer configured `dbSnapshot`; when absent it
- * is resolved at replay time. The Bitfab service uses the timestamp to
- * materialize an ephemeral branch from `customer-main`.
- */
-declare const SUPPORTED_PROVIDERS: readonly ["neon"];
-type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
-interface DbSnapshotConfig {
-    /** Discriminator for the server-side resolver. */
-    provider: DbSnapshotProvider;
-}
-interface DbSnapshotRef {
-    /**
-     * The wall-clock ISO timestamp the SDK observed immediately before
-     * invoking the wrapped function. The name encodes its provenance:
-     * SDK-observed, wall clock (not monotonic), captured before user code
-     * began executing. Always present.
-     */
-    sdkWallClockBeforeFn: string;
-    /**
-     * The configured provider for server-side branch resolution. Only set when
-     * the customer configured `dbSnapshot`; otherwise the provider is resolved
-     * at replay time.
-     */
-    provider?: DbSnapshotProvider;
-}
-
-/**
- * Shared error type for Bitfab SDK runtime errors. Lives in its own
- * module to avoid import cycles between `http.ts` and modules that need
- * to throw structured errors (e.g. `dbSnapshot.ts` validation).
- */
-declare class BitfabError extends Error {
-    readonly url?: string | undefined;
-    constructor(message: string, url?: string | undefined);
-}
-
-/**
- * HTTP client utilities for Bitfab API requests.
- *
- * This module provides:
- * - HttpClient class for making API requests
- * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
- */
-
-/**
- * Wait for all pending fire-and-forget operations (spans, traces) to complete.
- * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.
- *
- * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
- */
-declare function flushTraces(timeoutMs?: number): Promise<void>;
-interface TokenUsage {
-    input: number | null;
-    output: number | null;
-    cached: number | null;
-    total: number | null;
-}
-/**
- * Describes a single file edited as part of a code change.
- *
- * - `path`: file path (relative to the repo root, or any consistent root)
- * - `before`: file contents before the change ("" for newly created files)
- * - `after`: file contents after the change ("" for deleted files)
- */
-interface CodeChangeFile {
-    path: string;
-    before: string;
-    after: string;
-}
-
 /**
  * LangGraph/LangChain callback handler for Bitfab tracing.
  *
@@ -372,6 +381,7 @@ interface CodeChangeFile {
  * Duck-typed to match LangChain.js's BaseCallbackHandler interface.
  * No @langchain/core dependency required.
  */
+
 interface ActiveSpanContext$1 {
     traceId: string;
     spanId: string;
@@ -401,7 +411,7 @@ declare class BitfabLangGraphCallbackHandler {
     private runToSpan;
     private invocations;
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         traceFunctionKey: string;
         serviceUrl?: string;
         timeout?: number;
@@ -670,6 +680,8 @@ interface ReplayOptions {
 }
 /** Running totals reported to {@link ReplayOptions.onProgress} as replay proceeds. */
 interface ReplayProgress {
+    /** Test run ID created for this replay. */
+    testRunId?: string;
     /** Items that have finished so far, whether they succeeded or errored. */
     completed: number;
     /** Total number of items in this replay run. */
@@ -687,9 +699,21 @@ interface ReplayProgress {
      * {@link ReplayResult}.
      */
     item?: {
+        /** Source (historical) trace ID being replayed. */
         traceId: string | null;
+        /** Local SDK replay trace ID, before the server maps it to a row ID. */
+        replayTraceId?: string | null;
+        /** Deserialized inputs from the original trace. */
+        input?: unknown[];
+        /** The result returned by the replayed function, or undefined on error. */
+        result?: unknown;
+        /** The original output from the historical trace. */
+        originalOutput?: unknown;
         error: string | null;
         durationMs: number | null;
+        tokens?: TokenUsage | null;
+        model?: string | null;
+        dbSnapshotRef?: DbSnapshotRef | null;
     };
 }
 /**
@@ -782,6 +806,7 @@ interface ReplayResult<T> {
  * This module provides utilities for sending external traces (e.g., from OpenAI API calls)
  * to Bitfab for monitoring and analysis.
  */
+
 interface Trace {
     traceId: string;
     toJSON(): unknown;
@@ -842,7 +867,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
      * @param config - Configuration options
      */
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext | null;
@@ -1009,8 +1034,19 @@ declare function getCurrentSpan(): CurrentSpan;
  */
 declare function getCurrentTrace(): CurrentTrace;
 interface BitfabConfig {
-    /** The API key for Bitfab API authentication. When undefined or empty, tracing is disabled. */
-    apiKey?: string;
+    /**
+     * The API key for Bitfab API authentication. Resolved lazily, the first
+     * time a span actually needs it, not at construction. When it resolves
+     * empty, tracing is disabled (a no-op, unless `strict` is set).
+     *
+     * Accepts either a string or a function returning the key. The function
+     * form is resolved at first use, so it survives the ESM trap where a shim
+     * built at module load runs before the script body's `dotenv.config()`:
+     * `apiKey: () => process.env.BITFAB_API_KEY`. When omitted (or it resolves
+     * empty), the SDK also falls back to reading `BITFAB_API_KEY` from the
+     * environment itself, again at first use.
+     */
+    apiKey?: string | (() => string | null | undefined);
     /** The base URL for the Bitfab API (default: https://bitfab.ai) */
     serviceUrl?: string;
     /** Request timeout in milliseconds (default: 120000) */
@@ -1019,6 +1055,14 @@ interface BitfabConfig {
     envVars?: AllowedEnvVars;
     /** Whether the client is enabled. Defaults to true. When false, withSpan returns the original function unwrapped. */
     enabled?: boolean;
+    /**
+     * Fail loud instead of degrading quietly. When true, the first traced call
+     * with no resolvable API key throws a `BitfabError` rather than silently
+     * disabling tracing. Off by default so a missing telemetry key never takes
+     * down the host app; turn it on in standalone scripts where a run that
+     * emits no traces is a failure you want surfaced immediately.
+     */
+    strict?: boolean;
     /** The generated BAML client instance (e.g., `b` from your baml_client). Used by wrapBAML() when no explicit client is passed. */
     bamlClient?: unknown;
     /**
@@ -1093,11 +1137,17 @@ declare class Bitfab {
      * function to pick up the per-trace branch URL.
      */
     static readonly ReplayEnvironment: typeof ReplayEnvironment;
-    private readonly apiKey;
+    private readonly apiKeyConfig;
+    /** Cached only once a non-empty key is found, so an early resolve (before env loaded) can't poison a later one. */
+    private resolvedApiKey;
+    /** Gate the empty-key warning to fire at most once. */
+    private apiKeyWarned;
     private readonly serviceUrl;
     private readonly timeout;
     private readonly envVars;
-    private readonly enabled;
+    /** The user's on/off intent. The effective enabled state ANDs this with "a key resolved" (see isTracingEnabled). */
+    private readonly explicitlyEnabled;
+    private readonly strict;
     private readonly httpClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
@@ -1107,6 +1157,28 @@ declare class Bitfab {
      * @param config - Configuration options for the client
      */
     constructor(config: BitfabConfig);
+    /**
+     * 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.
+     */
+    private resolveApiKey;
+    /**
+     * Whether tracing should run, decided lazily at call time (not frozen at
+     * construction). An explicit `enabled: false` short-circuits without ever
+     * touching the key.
+     */
+    private isTracingEnabled;
     /**
      * Fetch the function with its current version and BAML prompt from the server.
      *
@@ -1531,7 +1603,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.27.2";
+declare const __version__ = "0.28.1";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -30,6 +30,91 @@ type AllowedEnvVars = {
     OPENAI_API_KEY?: string;
 };
 
+/**
+ * Per-trace database snapshot ref capture.
+ *
+ * Every root span carries a `DbSnapshotRef` that pins the DB state at trace
+ * open by wall-clock timestamp. Capturing the timestamp is free (no IO) and
+ * harmless, so it happens on every trace regardless of configuration: that
+ * lets any trace be replayed against a historical branch later. A `provider`
+ * is attached only when the customer configured `dbSnapshot`; when absent it
+ * is resolved at replay time. The Bitfab service uses the timestamp to
+ * materialize an ephemeral branch from `customer-main`.
+ */
+declare const SUPPORTED_PROVIDERS: readonly ["neon"];
+type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
+interface DbSnapshotConfig {
+    /** Discriminator for the server-side resolver. */
+    provider: DbSnapshotProvider;
+}
+interface DbSnapshotRef {
+    /**
+     * The wall-clock ISO timestamp the SDK observed immediately before
+     * invoking the wrapped function. The name encodes its provenance:
+     * SDK-observed, wall clock (not monotonic), captured before user code
+     * began executing. Always present.
+     */
+    sdkWallClockBeforeFn: string;
+    /**
+     * The configured provider for server-side branch resolution. Only set when
+     * the customer configured `dbSnapshot`; otherwise the provider is resolved
+     * at replay time.
+     */
+    provider?: DbSnapshotProvider;
+}
+
+/**
+ * Shared error type for Bitfab SDK runtime errors. Lives in its own
+ * module to avoid import cycles between `http.ts` and modules that need
+ * to throw structured errors (e.g. `dbSnapshot.ts` validation).
+ */
+declare class BitfabError extends Error {
+    readonly url?: string | undefined;
+    constructor(message: string, url?: string | undefined);
+}
+
+/**
+ * HTTP client utilities for Bitfab API requests.
+ *
+ * This module provides:
+ * - HttpClient class for making API requests
+ * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
+ */
+
+/**
+ * Wait for all pending fire-and-forget operations (spans, traces) to complete.
+ * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.
+ *
+ * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+ */
+declare function flushTraces(timeoutMs?: number): Promise<void>;
+/**
+ * How the API key is supplied internally: either a literal string or a
+ * function resolved each time the key is needed (at request/send time). The
+ * function form is what defers key resolution past module-load construction
+ * so an env var loaded after the client is built (the ESM dotenv-hoisting
+ * case) is still picked up.
+ */
+type ApiKeyInput = string | (() => string | undefined);
+interface TokenUsage {
+    input: number | null;
+    output: number | null;
+    cached: number | null;
+    total: number | null;
+}
+/**
+ * Describes a single file edited as part of a code change.
+ *
+ * - `path`: file path (relative to the repo root, or any consistent root)
+ * - `before`: file contents before the change ("" for newly created files)
+ * - `after`: file contents after the change ("" for deleted files)
+ */
+interface CodeChangeFile {
+    path: string;
+    before: string;
+    after: string;
+}
+
 /**
  * Claude Agent SDK handler for Bitfab tracing.
  *
@@ -40,6 +125,7 @@ type AllowedEnvVars = {
  *   1. SDK hooks (PreToolUse, PostToolUse, etc.) for tool/subagent lifecycle
  *   2. Stream wrapping for LLM turn capture from the message stream
  */
+
 interface ActiveSpanContext$2 {
     traceId: string;
     spanId: string;
@@ -96,7 +182,7 @@ declare class BitfabClaudeAgentHandler {
     private rootInput;
     private rootOutput;
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         traceFunctionKey: string;
         serviceUrl?: string;
         timeout?: number;
@@ -285,83 +371,6 @@ declare class BitfabVercelAiHandler {
     get middleware(): BitfabLanguageModelMiddleware;
 }
 
-/**
- * Per-trace database snapshot ref capture.
- *
- * Every root span carries a `DbSnapshotRef` that pins the DB state at trace
- * open by wall-clock timestamp. Capturing the timestamp is free (no IO) and
- * harmless, so it happens on every trace regardless of configuration: that
- * lets any trace be replayed against a historical branch later. A `provider`
- * is attached only when the customer configured `dbSnapshot`; when absent it
- * is resolved at replay time. The Bitfab service uses the timestamp to
- * materialize an ephemeral branch from `customer-main`.
- */
-declare const SUPPORTED_PROVIDERS: readonly ["neon"];
-type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
-interface DbSnapshotConfig {
-    /** Discriminator for the server-side resolver. */
-    provider: DbSnapshotProvider;
-}
-interface DbSnapshotRef {
-    /**
-     * The wall-clock ISO timestamp the SDK observed immediately before
-     * invoking the wrapped function. The name encodes its provenance:
-     * SDK-observed, wall clock (not monotonic), captured before user code
-     * began executing. Always present.
-     */
-    sdkWallClockBeforeFn: string;
-    /**
-     * The configured provider for server-side branch resolution. Only set when
-     * the customer configured `dbSnapshot`; otherwise the provider is resolved
-     * at replay time.
-     */
-    provider?: DbSnapshotProvider;
-}
-
-/**
- * Shared error type for Bitfab SDK runtime errors. Lives in its own
- * module to avoid import cycles between `http.ts` and modules that need
- * to throw structured errors (e.g. `dbSnapshot.ts` validation).
- */
-declare class BitfabError extends Error {
-    readonly url?: string | undefined;
-    constructor(message: string, url?: string | undefined);
-}
-
-/**
- * HTTP client utilities for Bitfab API requests.
- *
- * This module provides:
- * - HttpClient class for making API requests
- * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
- */
-
-/**
- * Wait for all pending fire-and-forget operations (spans, traces) to complete.
- * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.
- *
- * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
- */
-declare function flushTraces(timeoutMs?: number): Promise<void>;
-interface TokenUsage {
-    input: number | null;
-    output: number | null;
-    cached: number | null;
-    total: number | null;
-}
-/**
- * Describes a single file edited as part of a code change.
- *
- * - `path`: file path (relative to the repo root, or any consistent root)
- * - `before`: file contents before the change ("" for newly created files)
- * - `after`: file contents after the change ("" for deleted files)
- */
-interface CodeChangeFile {
-    path: string;
-    before: string;
-    after: string;
-}
-
 /**
  * LangGraph/LangChain callback handler for Bitfab tracing.
  *
@@ -372,6 +381,7 @@ interface CodeChangeFile {
  * Duck-typed to match LangChain.js's BaseCallbackHandler interface.
  * No @langchain/core dependency required.
  */
+
 interface ActiveSpanContext$1 {
     traceId: string;
     spanId: string;
@@ -401,7 +411,7 @@ declare class BitfabLangGraphCallbackHandler {
     private runToSpan;
     private invocations;
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         traceFunctionKey: string;
         serviceUrl?: string;
         timeout?: number;
@@ -670,6 +680,8 @@ interface ReplayOptions {
 }
 /** Running totals reported to {@link ReplayOptions.onProgress} as replay proceeds. */
 interface ReplayProgress {
+    /** Test run ID created for this replay. */
+    testRunId?: string;
     /** Items that have finished so far, whether they succeeded or errored. */
     completed: number;
     /** Total number of items in this replay run. */
@@ -687,9 +699,21 @@ interface ReplayProgress {
      * {@link ReplayResult}.
      */
     item?: {
+        /** Source (historical) trace ID being replayed. */
         traceId: string | null;
+        /** Local SDK replay trace ID, before the server maps it to a row ID. */
+        replayTraceId?: string | null;
+        /** Deserialized inputs from the original trace. */
+        input?: unknown[];
+        /** The result returned by the replayed function, or undefined on error. */
+        result?: unknown;
+        /** The original output from the historical trace. */
+        originalOutput?: unknown;
         error: string | null;
         durationMs: number | null;
+        tokens?: TokenUsage | null;
+        model?: string | null;
+        dbSnapshotRef?: DbSnapshotRef | null;
     };
 }
 /**
@@ -782,6 +806,7 @@ interface ReplayResult<T> {
  * This module provides utilities for sending external traces (e.g., from OpenAI API calls)
  * to Bitfab for monitoring and analysis.
  */
+
 interface Trace {
     traceId: string;
     toJSON(): unknown;
@@ -842,7 +867,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
      * @param config - Configuration options
      */
     constructor(config: {
-        apiKey?: string;
+        apiKey?: ApiKeyInput;
         serviceUrl?: string;
         timeout?: number;
         getActiveSpanContext?: () => ActiveSpanContext | null;
@@ -1009,8 +1034,19 @@ declare function getCurrentSpan(): CurrentSpan;
  */
 declare function getCurrentTrace(): CurrentTrace;
 interface BitfabConfig {
-    /** The API key for Bitfab API authentication. When undefined or empty, tracing is disabled. */
-    apiKey?: string;
+    /**
+     * The API key for Bitfab API authentication. Resolved lazily, the first
+     * time a span actually needs it, not at construction. When it resolves
+     * empty, tracing is disabled (a no-op, unless `strict` is set).
+     *
+     * Accepts either a string or a function returning the key. The function
+     * form is resolved at first use, so it survives the ESM trap where a shim
+     * built at module load runs before the script body's `dotenv.config()`:
+     * `apiKey: () => process.env.BITFAB_API_KEY`. When omitted (or it resolves
+     * empty), the SDK also falls back to reading `BITFAB_API_KEY` from the
+     * environment itself, again at first use.
+     */
+    apiKey?: string | (() => string | null | undefined);
     /** The base URL for the Bitfab API (default: https://bitfab.ai) */
     serviceUrl?: string;
     /** Request timeout in milliseconds (default: 120000) */
@@ -1019,6 +1055,14 @@ interface BitfabConfig {
     envVars?: AllowedEnvVars;
     /** Whether the client is enabled. Defaults to true. When false, withSpan returns the original function unwrapped. */
     enabled?: boolean;
+    /**
+     * Fail loud instead of degrading quietly. When true, the first traced call
+     * with no resolvable API key throws a `BitfabError` rather than silently
+     * disabling tracing. Off by default so a missing telemetry key never takes
+     * down the host app; turn it on in standalone scripts where a run that
+     * emits no traces is a failure you want surfaced immediately.
+     */
+    strict?: boolean;
     /** The generated BAML client instance (e.g., `b` from your baml_client). Used by wrapBAML() when no explicit client is passed. */
     bamlClient?: unknown;
     /**
@@ -1093,11 +1137,17 @@ declare class Bitfab {
      * function to pick up the per-trace branch URL.
      */
     static readonly ReplayEnvironment: typeof ReplayEnvironment;
-    private readonly apiKey;
+    private readonly apiKeyConfig;
+    /** Cached only once a non-empty key is found, so an early resolve (before env loaded) can't poison a later one. */
+    private resolvedApiKey;
+    /** Gate the empty-key warning to fire at most once. */
+    private apiKeyWarned;
     private readonly serviceUrl;
     private readonly timeout;
     private readonly envVars;
-    private readonly enabled;
+    /** The user's on/off intent. The effective enabled state ANDs this with "a key resolved" (see isTracingEnabled). */
+    private readonly explicitlyEnabled;
+    private readonly strict;
     private readonly httpClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
@@ -1107,6 +1157,28 @@ declare class Bitfab {
      * @param config - Configuration options for the client
      */
     constructor(config: BitfabConfig);
+    /**
+     * 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.
+     */
+    private resolveApiKey;
+    /**
+     * Whether tracing should run, decided lazily at call time (not frozen at
+     * construction). An explicit `enabled: false` short-circuits without ever
+     * touching the key.
+     */
+    private isTracingEnabled;
     /**
      * Fetch the function with its current version and BAML prompt from the server.
      *
@@ -1531,7 +1603,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.27.2";
+declare const __version__ = "0.28.1";
 
 /**
  * Constants for the Bitfab SDK.