@bitfab/sdk 0.28.10 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -73,6 +73,76 @@ declare class BitfabError extends Error {
73
73
  constructor(message: string, url?: string | undefined);
74
74
  }
75
75
 
76
+ /**
77
+ * Selective mock overrides for replay.
78
+ *
79
+ * A mock override injects a custom value into a specific span (node) during
80
+ * replay: the matched span short-circuits its real execution and returns the
81
+ * value you supply, so downstream real code runs against the substituted
82
+ * output. This is a third mock mode alongside "run real code" and "replay
83
+ * recorded output" (see {@link MockStrategy}).
84
+ *
85
+ * The matcher and value are deliberately separate so matching stays cheap
86
+ * (structural metadata only, no output fetch) and the recorded output is
87
+ * fetched lazily - and only if the value function actually asks for it via
88
+ * {@link MockOverrideCtx.getOriginalOutput}.
89
+ */
90
+ /**
91
+ * Structural identity of a span during replay, passed to a {@link NodeMatcher}.
92
+ * Carries no output payload - matching must not depend on the recorded output,
93
+ * so the output fetch stays lazy and gated.
94
+ */
95
+ interface SpanNodeMeta {
96
+ /** The `withSpan` key of the executing span (its code-side identity). */
97
+ traceFunctionKey: string;
98
+ /** Resolved span name: `options.name ?? fn.name ?? traceFunctionKey`. */
99
+ spanName: string;
100
+ /** Span type, e.g. "llm", "agent", "tool", "custom". */
101
+ type: string;
102
+ /**
103
+ * The id of this span in the original (replayed) trace, when it exists in
104
+ * that trace's tree. Undefined when the live span has no recorded
105
+ * counterpart (e.g. a span the changed code newly introduced).
106
+ */
107
+ originalSpanId?: string;
108
+ }
109
+ /** Context passed to a {@link MockValue} function for a matched span. */
110
+ interface MockOverrideCtx {
111
+ /** The matched span's structural metadata. */
112
+ node: SpanNodeMeta;
113
+ /** The live replay args passed to the wrapped function this run. */
114
+ inputs: unknown[];
115
+ /**
116
+ * Lazily fetch this span's ORIGINAL recorded output (deserialized). The fetch
117
+ * happens only when called and is memoized per replay item, so a purely flat
118
+ * override that never calls it triggers zero output round trips. Rejects if
119
+ * the span has no recorded counterpart. Being async, it is only usable for
120
+ * spans wrapping async functions.
121
+ */
122
+ getOriginalOutput: () => Promise<unknown>;
123
+ }
124
+ /** Selects which spans an override applies to. Runs on structural metadata. */
125
+ type NodeMatcher = (node: SpanNodeMeta) => boolean;
126
+ /** The function form of {@link MockValue}, receiving the override context. */
127
+ type MockValueFn = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
128
+ /**
129
+ * The value injected for a matched span: either a flat value used as-is, or a
130
+ * function of the {@link MockOverrideCtx} that returns one (or a Promise of
131
+ * one). Full replacement - the value IS the span's output, no merge with the
132
+ * recorded output.
133
+ *
134
+ * The flat side is spelled out (rather than `unknown`) so an inline function
135
+ * still gets a typed `ctx`: `unknown | Fn` would collapse to `unknown` and drop
136
+ * the contextual type. To inject a value that is itself a function, wrap it:
137
+ * `value: () => theFunction`.
138
+ */
139
+ type MockValue = MockValueFn | string | number | boolean | bigint | symbol | object | null | undefined;
140
+ /** One (match, value) pair. */
141
+ interface MockOverride {
142
+ match: NodeMatcher;
143
+ value: MockValue;
144
+ }
145
+
76
146
  /**
77
147
  * HTTP client utilities for Bitfab API requests.
78
148
  *
@@ -96,6 +166,32 @@ declare function flushTraces(timeoutMs?: number): Promise<void>;
96
166
  * case) is still picked up.
97
167
  */
98
168
  type ApiKeyInput = string | (() => string | undefined);
169
+ type SpanOccurrence = "first" | "last" | number;
170
+ type SpanLookup = {
171
+ id: string;
172
+ name?: never;
173
+ occurrence?: never;
174
+ } | {
175
+ name: string;
176
+ id?: never;
177
+ occurrence?: SpanOccurrence;
178
+ };
179
+ interface CapturedSpan {
180
+ id: string;
181
+ traceId: string;
182
+ parentSpanId: string | null;
183
+ name: string | null;
184
+ type: string;
185
+ input: unknown;
186
+ output: unknown;
187
+ contexts: Record<string, unknown>[];
188
+ prompt: string | null;
189
+ metadata: Record<string, unknown>;
190
+ metrics: Record<string, unknown> | null;
191
+ errors: unknown;
192
+ startedAt: string | null;
193
+ endedAt: string | null;
194
+ }
99
195
  interface TokenUsage {
100
196
  input: number | null;
101
197
  output: number | null;
@@ -628,6 +724,15 @@ interface ReplayOptions {
628
724
  * - "all": every child withSpan returns historical output
629
725
  */
630
726
  mock?: MockStrategy;
727
+ /**
728
+ * Selective mock overrides: inject custom values into specific spans during
729
+ * replay, so downstream real code runs against the substituted output. Each
730
+ * override is a `{ match, value }` pair; the first matcher that
731
+ * matches a span wins. These take precedence over any overrides registered on
732
+ * the client via `registerMockOverride`, and over the base `mock` strategy - a
733
+ * span no override matches falls back to that strategy. See {@link MockOverride}.
734
+ */
735
+ mockOverride?: MockOverride | MockOverride[];
631
736
  /**
632
737
  * Per-trace environment. When the source trace carries a DB branching
633
738
  * snapshot, the SDK populates `environment.databaseUrl` before invoking
@@ -861,6 +966,8 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
861
966
  private activeTraces;
862
967
  private readonly getActiveSpanContext;
863
968
  private activeSpanMappings;
969
+ private canonicalTraceIds;
970
+ private getCanonicalTraceId;
864
971
  /**
865
972
  * Initialize the tracing processor.
866
973
  *
@@ -951,6 +1058,8 @@ interface WrappedBamlFn<TArgs extends unknown[], TReturn> {
951
1058
  * A handle to the current active span, allowing context to be added.
952
1059
  */
953
1060
  interface CurrentSpan {
1061
+ /** The Bitfab ID for the current span. */
1062
+ readonly id: string;
954
1063
  /** The trace ID for the current span. */
955
1064
  readonly traceId: string;
956
1065
  /**
@@ -966,7 +1075,7 @@ interface CurrentSpan {
966
1075
  }
967
1076
  /**
968
1077
  * A detached handle to a previously-created trace, looked up by its
969
- * caller-supplied id (the same id passed when the trace was started).
1078
+ * canonical Bitfab trace ID.
970
1079
  *
971
1080
  * Unlike `getCurrentTrace()`, this handle is not tied to AsyncLocalStorage -
972
1081
  * each method sends to the server immediately. Useful for adding context
@@ -974,7 +1083,7 @@ interface CurrentSpan {
974
1083
  * agent that wants to annotate the original conversation's trace).
975
1084
  */
976
1085
  interface DetachedTrace {
977
- /** The caller-supplied trace id this handle resolves. */
1086
+ /** The canonical Bitfab trace ID this handle resolves. */
978
1087
  readonly traceId: string;
979
1088
  /**
980
1089
  * Append a context entry to this trace. Each call adds one entry to the
@@ -1162,6 +1271,12 @@ declare class Bitfab {
1162
1271
  private readonly httpClient;
1163
1272
  private readonly bamlClient;
1164
1273
  private readonly dbSnapshot;
1274
+ /**
1275
+ * Mock overrides registered via {@link Bitfab.registerMockOverride}, applied
1276
+ * to every `replay` on this client (after any per-call `mockOverride`). In
1277
+ * registration order; first matcher wins within this list.
1278
+ */
1279
+ private readonly mockOverrides;
1165
1280
  /**
1166
1281
  * Initialize the Bitfab client.
1167
1282
  *
@@ -1394,25 +1509,30 @@ declare class Bitfab {
1394
1509
  withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
1395
1510
  /**
1396
1511
  * Get a detached handle to a previously-created trace, looked up by the
1397
- * caller-supplied id (the same id passed at trace creation).
1512
+ * canonical Bitfab trace ID.
1398
1513
  *
1399
1514
  * The returned handle is not tied to AsyncLocalStorage - each method sends
1400
1515
  * to the server immediately. Useful for adding context to a trace from a
1401
1516
  * different process or thread than the one that created it.
1402
1517
  *
1403
- * Throws synchronously if `traceId` is malformed (empty, too long, or
1404
- * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
1405
- * no trace exists with that id in the org; the failure surfaces as a
1518
+ * Throws synchronously if `traceId` is not a valid Bitfab trace ID. The
1519
+ * server returns 404 if no trace exists with that ID in the org; the failure surfaces as a
1406
1520
  * logged warning (fire-and-forget) or via the awaited promise.
1407
1521
  *
1408
1522
  * Example:
1409
1523
  * ```typescript
1410
- * const trace = client.getTrace("order_abc_123");
1524
+ * const trace = client.getTrace(traceId);
1411
1525
  * await trace.addContext({ refund_status: "approved" });
1412
1526
  * await trace.setMetadata({ region: "us-west" });
1413
1527
  * ```
1414
1528
  */
1415
1529
  getTrace(traceId: string): DetachedTrace;
1530
+ /**
1531
+ * Fetch one persisted span from a trace without loading the full trace.
1532
+ * Name lookups return the last matching span by default. Pass `occurrence`
1533
+ * as `"first"` or a zero-based index to select a different match.
1534
+ */
1535
+ getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
1416
1536
  /**
1417
1537
  * Get a function wrapper for a specific trace function key.
1418
1538
  *
@@ -1464,6 +1584,30 @@ declare class Bitfab {
1464
1584
  * determines how many traces replay.
1465
1585
  * @returns ReplayResult with items, testRunId, and testRunUrl
1466
1586
  */
1587
+ /**
1588
+ * Register a mock override applied to every subsequent `replay` on this
1589
+ * client, so downstream real code runs against a value you supply for the
1590
+ * matched span. Instance-scoped (no global state); call {@link clearMockOverrides}
1591
+ * to reset. Per-call `replay({ mockOverride })` overrides take precedence, and
1592
+ * both take precedence over the base `mock` strategy.
1593
+ *
1594
+ * ```ts
1595
+ * // Object form (value is a flat value here)
1596
+ * bitfab.registerMockOverride({
1597
+ * match: (node) => node.traceFunctionKey === "classify-intent",
1598
+ * value: { label: "refund" },
1599
+ * })
1600
+ * // Ordered form (equivalent); value may also be a function of the context
1601
+ * bitfab.registerMockOverride(
1602
+ * (node) => node.traceFunctionKey === "classify-intent",
1603
+ * ({ inputs }) => ({ label: "refund" }),
1604
+ * )
1605
+ * ```
1606
+ */
1607
+ registerMockOverride(override: MockOverride): void;
1608
+ registerMockOverride(match: NodeMatcher, value: MockValue): void;
1609
+ /** Remove all overrides registered via {@link registerMockOverride}. */
1610
+ clearMockOverrides(): void;
1467
1611
  replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
1468
1612
  }
1469
1613
  /**
@@ -1614,7 +1758,7 @@ declare class BitfabFunction {
1614
1758
  /**
1615
1759
  * SDK version from package.json (injected at build time)
1616
1760
  */
1617
- declare const __version__ = "0.28.10";
1761
+ declare const __version__ = "0.29.0";
1618
1762
 
1619
1763
  /**
1620
1764
  * Constants for the Bitfab SDK.
@@ -1682,4 +1826,4 @@ declare const finalizers: {
1682
1826
  readableStream: typeof readableStream;
1683
1827
  };
1684
1828
 
1685
- export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };
1829
+ export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };
package/dist/index.d.ts CHANGED
@@ -73,6 +73,76 @@ declare class BitfabError extends Error {
73
73
  constructor(message: string, url?: string | undefined);
74
74
  }
75
75
 
76
+ /**
77
+ * Selective mock overrides for replay.
78
+ *
79
+ * A mock override injects a custom value into a specific span (node) during
80
+ * replay: the matched span short-circuits its real execution and returns the
81
+ * value you supply, so downstream real code runs against the substituted
82
+ * output. This is a third mock mode alongside "run real code" and "replay
83
+ * recorded output" (see {@link MockStrategy}).
84
+ *
85
+ * The matcher and value are deliberately separate so matching stays cheap
86
+ * (structural metadata only, no output fetch) and the recorded output is
87
+ * fetched lazily - and only if the value function actually asks for it via
88
+ * {@link MockOverrideCtx.getOriginalOutput}.
89
+ */
90
+ /**
91
+ * Structural identity of a span during replay, passed to a {@link NodeMatcher}.
92
+ * Carries no output payload - matching must not depend on the recorded output,
93
+ * so the output fetch stays lazy and gated.
94
+ */
95
+ interface SpanNodeMeta {
96
+ /** The `withSpan` key of the executing span (its code-side identity). */
97
+ traceFunctionKey: string;
98
+ /** Resolved span name: `options.name ?? fn.name ?? traceFunctionKey`. */
99
+ spanName: string;
100
+ /** Span type, e.g. "llm", "agent", "tool", "custom". */
101
+ type: string;
102
+ /**
103
+ * The id of this span in the original (replayed) trace, when it exists in
104
+ * that trace's tree. Undefined when the live span has no recorded
105
+ * counterpart (e.g. a span the changed code newly introduced).
106
+ */
107
+ originalSpanId?: string;
108
+ }
109
+ /** Context passed to a {@link MockValue} function for a matched span. */
110
+ interface MockOverrideCtx {
111
+ /** The matched span's structural metadata. */
112
+ node: SpanNodeMeta;
113
+ /** The live replay args passed to the wrapped function this run. */
114
+ inputs: unknown[];
115
+ /**
116
+ * Lazily fetch this span's ORIGINAL recorded output (deserialized). The fetch
117
+ * happens only when called and is memoized per replay item, so a purely flat
118
+ * override that never calls it triggers zero output round trips. Rejects if
119
+ * the span has no recorded counterpart. Being async, it is only usable for
120
+ * spans wrapping async functions.
121
+ */
122
+ getOriginalOutput: () => Promise<unknown>;
123
+ }
124
+ /** Selects which spans an override applies to. Runs on structural metadata. */
125
+ type NodeMatcher = (node: SpanNodeMeta) => boolean;
126
+ /** The function form of {@link MockValue}, receiving the override context. */
127
+ type MockValueFn = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
128
+ /**
129
+ * The value injected for a matched span: either a flat value used as-is, or a
130
+ * function of the {@link MockOverrideCtx} that returns one (or a Promise of
131
+ * one). Full replacement - the value IS the span's output, no merge with the
132
+ * recorded output.
133
+ *
134
+ * The flat side is spelled out (rather than `unknown`) so an inline function
135
+ * still gets a typed `ctx`: `unknown | Fn` would collapse to `unknown` and drop
136
+ * the contextual type. To inject a value that is itself a function, wrap it:
137
+ * `value: () => theFunction`.
138
+ */
139
+ type MockValue = MockValueFn | string | number | boolean | bigint | symbol | object | null | undefined;
140
+ /** One (match, value) pair. */
141
+ interface MockOverride {
142
+ match: NodeMatcher;
143
+ value: MockValue;
144
+ }
145
+
76
146
  /**
77
147
  * HTTP client utilities for Bitfab API requests.
78
148
  *
@@ -96,6 +166,32 @@ declare function flushTraces(timeoutMs?: number): Promise<void>;
96
166
  * case) is still picked up.
97
167
  */
98
168
  type ApiKeyInput = string | (() => string | undefined);
169
+ type SpanOccurrence = "first" | "last" | number;
170
+ type SpanLookup = {
171
+ id: string;
172
+ name?: never;
173
+ occurrence?: never;
174
+ } | {
175
+ name: string;
176
+ id?: never;
177
+ occurrence?: SpanOccurrence;
178
+ };
179
+ interface CapturedSpan {
180
+ id: string;
181
+ traceId: string;
182
+ parentSpanId: string | null;
183
+ name: string | null;
184
+ type: string;
185
+ input: unknown;
186
+ output: unknown;
187
+ contexts: Record<string, unknown>[];
188
+ prompt: string | null;
189
+ metadata: Record<string, unknown>;
190
+ metrics: Record<string, unknown> | null;
191
+ errors: unknown;
192
+ startedAt: string | null;
193
+ endedAt: string | null;
194
+ }
99
195
  interface TokenUsage {
100
196
  input: number | null;
101
197
  output: number | null;
@@ -628,6 +724,15 @@ interface ReplayOptions {
628
724
  * - "all": every child withSpan returns historical output
629
725
  */
630
726
  mock?: MockStrategy;
727
+ /**
728
+ * Selective mock overrides: inject custom values into specific spans during
729
+ * replay, so downstream real code runs against the substituted output. Each
730
+ * override is a `{ match, value }` pair; the first matcher that
731
+ * matches a span wins. These take precedence over any overrides registered on
732
+ * the client via `registerMockOverride`, and over the base `mock` strategy - a
733
+ * span no override matches falls back to that strategy. See {@link MockOverride}.
734
+ */
735
+ mockOverride?: MockOverride | MockOverride[];
631
736
  /**
632
737
  * Per-trace environment. When the source trace carries a DB branching
633
738
  * snapshot, the SDK populates `environment.databaseUrl` before invoking
@@ -861,6 +966,8 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
861
966
  private activeTraces;
862
967
  private readonly getActiveSpanContext;
863
968
  private activeSpanMappings;
969
+ private canonicalTraceIds;
970
+ private getCanonicalTraceId;
864
971
  /**
865
972
  * Initialize the tracing processor.
866
973
  *
@@ -951,6 +1058,8 @@ interface WrappedBamlFn<TArgs extends unknown[], TReturn> {
951
1058
  * A handle to the current active span, allowing context to be added.
952
1059
  */
953
1060
  interface CurrentSpan {
1061
+ /** The Bitfab ID for the current span. */
1062
+ readonly id: string;
954
1063
  /** The trace ID for the current span. */
955
1064
  readonly traceId: string;
956
1065
  /**
@@ -966,7 +1075,7 @@ interface CurrentSpan {
966
1075
  }
967
1076
  /**
968
1077
  * A detached handle to a previously-created trace, looked up by its
969
- * caller-supplied id (the same id passed when the trace was started).
1078
+ * canonical Bitfab trace ID.
970
1079
  *
971
1080
  * Unlike `getCurrentTrace()`, this handle is not tied to AsyncLocalStorage -
972
1081
  * each method sends to the server immediately. Useful for adding context
@@ -974,7 +1083,7 @@ interface CurrentSpan {
974
1083
  * agent that wants to annotate the original conversation's trace).
975
1084
  */
976
1085
  interface DetachedTrace {
977
- /** The caller-supplied trace id this handle resolves. */
1086
+ /** The canonical Bitfab trace ID this handle resolves. */
978
1087
  readonly traceId: string;
979
1088
  /**
980
1089
  * Append a context entry to this trace. Each call adds one entry to the
@@ -1162,6 +1271,12 @@ declare class Bitfab {
1162
1271
  private readonly httpClient;
1163
1272
  private readonly bamlClient;
1164
1273
  private readonly dbSnapshot;
1274
+ /**
1275
+ * Mock overrides registered via {@link Bitfab.registerMockOverride}, applied
1276
+ * to every `replay` on this client (after any per-call `mockOverride`). In
1277
+ * registration order; first matcher wins within this list.
1278
+ */
1279
+ private readonly mockOverrides;
1165
1280
  /**
1166
1281
  * Initialize the Bitfab client.
1167
1282
  *
@@ -1394,25 +1509,30 @@ declare class Bitfab {
1394
1509
  withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
1395
1510
  /**
1396
1511
  * Get a detached handle to a previously-created trace, looked up by the
1397
- * caller-supplied id (the same id passed at trace creation).
1512
+ * canonical Bitfab trace ID.
1398
1513
  *
1399
1514
  * The returned handle is not tied to AsyncLocalStorage - each method sends
1400
1515
  * to the server immediately. Useful for adding context to a trace from a
1401
1516
  * different process or thread than the one that created it.
1402
1517
  *
1403
- * Throws synchronously if `traceId` is malformed (empty, too long, or
1404
- * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
1405
- * no trace exists with that id in the org; the failure surfaces as a
1518
+ * Throws synchronously if `traceId` is not a valid Bitfab trace ID. The
1519
+ * server returns 404 if no trace exists with that ID in the org; the failure surfaces as a
1406
1520
  * logged warning (fire-and-forget) or via the awaited promise.
1407
1521
  *
1408
1522
  * Example:
1409
1523
  * ```typescript
1410
- * const trace = client.getTrace("order_abc_123");
1524
+ * const trace = client.getTrace(traceId);
1411
1525
  * await trace.addContext({ refund_status: "approved" });
1412
1526
  * await trace.setMetadata({ region: "us-west" });
1413
1527
  * ```
1414
1528
  */
1415
1529
  getTrace(traceId: string): DetachedTrace;
1530
+ /**
1531
+ * Fetch one persisted span from a trace without loading the full trace.
1532
+ * Name lookups return the last matching span by default. Pass `occurrence`
1533
+ * as `"first"` or a zero-based index to select a different match.
1534
+ */
1535
+ getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
1416
1536
  /**
1417
1537
  * Get a function wrapper for a specific trace function key.
1418
1538
  *
@@ -1464,6 +1584,30 @@ declare class Bitfab {
1464
1584
  * determines how many traces replay.
1465
1585
  * @returns ReplayResult with items, testRunId, and testRunUrl
1466
1586
  */
1587
+ /**
1588
+ * Register a mock override applied to every subsequent `replay` on this
1589
+ * client, so downstream real code runs against a value you supply for the
1590
+ * matched span. Instance-scoped (no global state); call {@link clearMockOverrides}
1591
+ * to reset. Per-call `replay({ mockOverride })` overrides take precedence, and
1592
+ * both take precedence over the base `mock` strategy.
1593
+ *
1594
+ * ```ts
1595
+ * // Object form (value is a flat value here)
1596
+ * bitfab.registerMockOverride({
1597
+ * match: (node) => node.traceFunctionKey === "classify-intent",
1598
+ * value: { label: "refund" },
1599
+ * })
1600
+ * // Ordered form (equivalent); value may also be a function of the context
1601
+ * bitfab.registerMockOverride(
1602
+ * (node) => node.traceFunctionKey === "classify-intent",
1603
+ * ({ inputs }) => ({ label: "refund" }),
1604
+ * )
1605
+ * ```
1606
+ */
1607
+ registerMockOverride(override: MockOverride): void;
1608
+ registerMockOverride(match: NodeMatcher, value: MockValue): void;
1609
+ /** Remove all overrides registered via {@link registerMockOverride}. */
1610
+ clearMockOverrides(): void;
1467
1611
  replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
1468
1612
  }
1469
1613
  /**
@@ -1614,7 +1758,7 @@ declare class BitfabFunction {
1614
1758
  /**
1615
1759
  * SDK version from package.json (injected at build time)
1616
1760
  */
1617
- declare const __version__ = "0.28.10";
1761
+ declare const __version__ = "0.29.0";
1618
1762
 
1619
1763
  /**
1620
1764
  * Constants for the Bitfab SDK.
@@ -1682,4 +1826,4 @@ declare const finalizers: {
1682
1826
  readableStream: typeof readableStream;
1683
1827
  };
1684
1828
 
1685
- export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };
1829
+ export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };
package/dist/index.js CHANGED
@@ -14,12 +14,12 @@ import {
14
14
  flushTraces,
15
15
  getCurrentSpan,
16
16
  getCurrentTrace
17
- } from "./chunk-SK4TNXRC.js";
17
+ } from "./chunk-2M5AWVVQ.js";
18
18
  import {
19
19
  BITFAB_PROGRESS_PREFIX,
20
20
  BitfabError,
21
21
  reportReplayProgress
22
- } from "./chunk-5E4BUIYA.js";
22
+ } from "./chunk-V3XORTWI.js";
23
23
  export {
24
24
  BITFAB_PROGRESS_PREFIX,
25
25
  Bitfab,