@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/{chunk-SK4TNXRC.js → chunk-2M5AWVVQ.js} +230 -72
- package/dist/chunk-2M5AWVVQ.js.map +1 -0
- package/dist/{chunk-5E4BUIYA.js → chunk-V3XORTWI.js} +45 -8
- package/dist/chunk-V3XORTWI.js.map +1 -0
- package/dist/index.cjs +279 -76
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +153 -9
- package/dist/index.d.ts +153 -9
- package/dist/index.js +2 -2
- package/dist/node.cjs +279 -76
- package/dist/node.cjs.map +1 -1
- package/dist/node.d.cts +1 -1
- package/dist/node.d.ts +1 -1
- package/dist/node.js +2 -2
- package/dist/{replay-IEE4RY57.js → replay-HEGU3YU2.js} +2 -2
- package/package.json +1 -1
- package/dist/chunk-5E4BUIYA.js.map +0 -1
- package/dist/chunk-SK4TNXRC.js.map +0 -1
- /package/dist/{replay-IEE4RY57.js.map → replay-HEGU3YU2.js.map} +0 -0
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
|
1404
|
-
*
|
|
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(
|
|
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.
|
|
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
|
1404
|
-
*
|
|
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(
|
|
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.
|
|
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-
|
|
17
|
+
} from "./chunk-2M5AWVVQ.js";
|
|
18
18
|
import {
|
|
19
19
|
BITFAB_PROGRESS_PREFIX,
|
|
20
20
|
BitfabError,
|
|
21
21
|
reportReplayProgress
|
|
22
|
-
} from "./chunk-
|
|
22
|
+
} from "./chunk-V3XORTWI.js";
|
|
23
23
|
export {
|
|
24
24
|
BITFAB_PROGRESS_PREFIX,
|
|
25
25
|
Bitfab,
|