@bitfab/sdk 0.36.4 → 0.36.6

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
@@ -1213,31 +1213,56 @@ interface ReplayOptions {
1213
1213
  * distinguish items whose function ran (`succeeded`) from items that threw
1214
1214
  * (`errored`).
1215
1215
  *
1216
- * Invoked synchronously right after each item settles, so keep it cheap. A
1216
+ * Invoked synchronously right after each item finishes, so keep it cheap. A
1217
1217
  * throwing callback never crashes the run: the error is swallowed so progress
1218
1218
  * UI can't break replay.
1219
1219
  */
1220
- onProgress?: (progress: ReplayProgress) => void;
1221
- }
1222
- /** Running totals reported to {@link ReplayOptions.onProgress} as replay proceeds. */
1223
- interface ReplayProgress {
1220
+ onItemFinish?: (progress: ReplayItemFinishProgress) => void;
1224
1221
  /**
1225
- * Event kind. Omitted (or `"item"`) for the per-trace settle events streamed
1226
- * during the run. `"complete"` marks the single terminal event emitted once
1227
- * the run has settled and been enriched server-side; it carries the full
1228
- * {@link ReplayProgress.result} and has no `item`. The Bitfab plugin reads
1229
- * that terminal event to build the run's final result without parsing stdout.
1222
+ * @deprecated Use {@link onItemFinish}. This compatibility callback receives
1223
+ * the same per-item finish events plus the legacy whole-run `"complete"`
1224
+ * event. It is ignored when `onItemFinish` is also provided.
1230
1225
  */
1231
- type?: "item" | "complete";
1226
+ onProgress?: (progress: ReplayProgress) => void;
1232
1227
  /**
1233
- * The full {@link ReplayResult}, present only on the terminal `"complete"`
1234
- * event. Lets the plugin ingest the enriched result (server-aggregated tokens,
1235
- * server trace ids) over the same channel as progress, so a dependency logging
1236
- * to stdout can never block it.
1228
+ * Called once when each replay item begins processing, before input loading,
1229
+ * mock preparation, database branching, or the customer function runs. Use
1230
+ * it with {@link onItemFinish} to distinguish queued items from items that
1231
+ * are still in flight. A throwing callback never crashes the run.
1237
1232
  */
1238
- result?: ReplayResult<unknown>;
1233
+ onItemStart?: (progress: ReplayItemStartProgress) => void;
1234
+ }
1235
+ /** Emitted through {@link ReplayOptions.onItemStart} when a worker starts an item. */
1236
+ interface ReplayItemStartProgress {
1237
+ type: "started";
1239
1238
  /** Test run ID created for this replay. */
1240
- testRunId?: string;
1239
+ testRunId: string;
1240
+ /** Items whose processing has started so far. */
1241
+ started: number;
1242
+ /** Items that have finished so far, whether they succeeded or errored. */
1243
+ completed: number;
1244
+ /** Total number of items in this replay run. */
1245
+ total: number;
1246
+ /** Of the completed items, how many finished without a code or replay error. */
1247
+ succeeded: number;
1248
+ /** Of the completed items, how many finished with an error. */
1249
+ errored: number;
1250
+ /** The historical trace and span whose replay processing just started. */
1251
+ item: {
1252
+ originalTraceId: string;
1253
+ originalSpanId: string;
1254
+ /** @deprecated alias for `originalTraceId`. */
1255
+ sourceTraceId: string;
1256
+ /** @deprecated alias for `originalSpanId`. */
1257
+ sourceSpanId: string;
1258
+ };
1259
+ }
1260
+ /** Running totals reported to {@link ReplayOptions.onItemFinish} as replay proceeds. */
1261
+ interface ReplayItemFinishProgress {
1262
+ /** Event kind, omitted for backward-compatible per-item events. */
1263
+ type?: "item";
1264
+ /** Test run ID created for this replay. */
1265
+ testRunId: string;
1241
1266
  /** Items that have finished so far, whether they succeeded or errored. */
1242
1267
  completed: number;
1243
1268
  /** Total number of items in this replay run. */
@@ -1247,7 +1272,7 @@ interface ReplayProgress {
1247
1272
  /** Of the completed items, how many have `item.error` set. */
1248
1273
  errored: number;
1249
1274
  /**
1250
- * The single item that just settled to produce this event. `traceId` is null
1275
+ * The single item that just finished to produce this event. `traceId` is null
1251
1276
  * at this stage (the server replay id isn't known until the run completes);
1252
1277
  * `originalTraceId` is the original (historical) trace that was replayed (so
1253
1278
  * a UI can identify or link it); `error` is its replay error, or null when it
@@ -1255,7 +1280,7 @@ interface ReplayProgress {
1255
1280
  * progress UI show per-trace pass/fail and timing as the run streams, without
1256
1281
  * waiting for the full {@link ReplayResult}.
1257
1282
  */
1258
- item?: {
1283
+ item: {
1259
1284
  /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
1260
1285
  traceId?: string | null;
1261
1286
  /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -1284,30 +1309,49 @@ interface ReplayProgress {
1284
1309
  dbSnapshotRef?: DbSnapshotRef | null;
1285
1310
  };
1286
1311
  }
1312
+ /**
1313
+ * @deprecated Use {@link ReplayItemFinishProgress}. This legacy shape also
1314
+ * represents the item-less terminal `"complete"` event emitted by
1315
+ * {@link ReplayOptions.onProgress}.
1316
+ */
1317
+ interface ReplayProgress {
1318
+ type?: "item" | "complete";
1319
+ result?: ReplayResult<unknown>;
1320
+ testRunId?: string;
1321
+ completed: number;
1322
+ total: number;
1323
+ succeeded: number;
1324
+ errored: number;
1325
+ item?: ReplayItemFinishProgress["item"];
1326
+ }
1287
1327
  /**
1288
1328
  * Wire prefix the Bitfab plugin scans for. Each line {@link reportReplayProgress}
1289
1329
  * writes is this prefix followed by the JSON of the running totals (plus the
1290
- * settled `item`). The plugin polls these lines to report live progress while a
1330
+ * finished `item`). The plugin polls these lines to report live progress while a
1291
1331
  * replay runs in the background; keep the SDK emitter and the plugin parser in
1292
1332
  * sync.
1293
1333
  */
1294
1334
  declare const BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
1295
1335
  /**
1296
- * A ready-made {@link ReplayOptions.onProgress} callback for replay scripts.
1336
+ * A ready-made replay lifecycle callback for replay scripts.
1297
1337
  * Pass it straight in:
1298
1338
  *
1299
1339
  * ```ts
1300
- * await bitfab.replay("my-fn", fn, { limit, onProgress: reportReplayProgress })
1340
+ * await bitfab.replay("my-fn", fn, {
1341
+ * limit,
1342
+ * onItemStart: reportReplayProgress,
1343
+ * onItemFinish: reportReplayProgress,
1344
+ * })
1301
1345
  * ```
1302
1346
  *
1303
- * It writes one `@@bitfab:progress` line per trace to stderr, which the Bitfab
1304
- * plugin polls to report live progress while the replay runs in the background,
1347
+ * It writes `@@bitfab:progress` lines to stderr, which the Bitfab plugin polls
1348
+ * to report in-flight and finished items while replay runs in the background,
1305
1349
  * so scripts never hand-format the wire protocol.
1306
1350
  * stdout is left untouched for direct-run ReplayResult JSON. Outside Node (no
1307
1351
  * `process.stderr`, e.g. a browser) it is a no-op, and a write failure is
1308
1352
  * swallowed so progress can never crash a run.
1309
1353
  */
1310
- declare function reportReplayProgress(progress: ReplayProgress): void;
1354
+ declare function reportReplayProgress(progress: ReplayItemFinishProgress | ReplayItemStartProgress | ReplayProgress): void;
1311
1355
  /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
1312
1356
  interface AdaptContext {
1313
1357
  /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -1878,6 +1922,27 @@ interface SpanOptions {
1878
1922
  */
1879
1923
  finalize?: (result: any) => unknown | Promise<unknown>;
1880
1924
  }
1925
+ /**
1926
+ * The standard method context passed to a decorator.
1927
+ *
1928
+ * Defined structurally instead of referencing TypeScript's built-in
1929
+ * `ClassMethodDecoratorContext`, which was added in TypeScript 5.0. This keeps
1930
+ * the SDK's non-decorator APIs consumable by projects on older compilers.
1931
+ */
1932
+ interface SpanMethodDecoratorContext<TThis, TValue> {
1933
+ readonly kind: "method";
1934
+ readonly name: string | symbol;
1935
+ readonly static: boolean;
1936
+ readonly private: boolean;
1937
+ readonly access: {
1938
+ has(object: TThis): boolean;
1939
+ get(object: TThis): TValue;
1940
+ };
1941
+ addInitializer(initializer: (this: TThis) => void): void;
1942
+ readonly metadata?: Record<PropertyKey, unknown>;
1943
+ }
1944
+ /** A standard ECMAScript method decorator produced by {@link Bitfab.span}. */
1945
+ type SpanMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(originalMethod: (this: TThis, ...args: TArgs) => TReturn, context: SpanMethodDecoratorContext<TThis, (this: TThis, ...args: TArgs) => TReturn>) => (this: TThis, ...args: TArgs) => TReturn;
1881
1946
 
1882
1947
  /**
1883
1948
  * Client for making provider-based API calls via BAML.
@@ -2148,6 +2213,31 @@ declare class Bitfab {
2148
2213
  * @returns A wrapped function with the same signature that creates spans for inputs and outputs
2149
2214
  */
2150
2215
  withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
2216
+ /**
2217
+ * Create a standard ECMAScript method decorator that records each invocation
2218
+ * as a span.
2219
+ *
2220
+ * It supports instance, static, and private methods; use
2221
+ * {@link Bitfab.withSpan} for standalone functions, class fields, and
2222
+ * accessors.
2223
+ *
2224
+ * @example
2225
+ * ```typescript
2226
+ * const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY });
2227
+ *
2228
+ * class OrderService {
2229
+ * @bitfab.span("order-processing", { type: "agent" })
2230
+ * async process(orderId: string) {
2231
+ * return { orderId };
2232
+ * }
2233
+ * }
2234
+ * ```
2235
+ *
2236
+ * @param traceFunctionKey - A string identifier for grouping spans
2237
+ * @param options - Span configuration applied to the decorated method
2238
+ * @returns A standard ECMAScript method decorator
2239
+ */
2240
+ span(traceFunctionKey: string, options?: SpanOptions): SpanMethodDecorator;
2151
2241
  /**
2152
2242
  * Get a detached handle to a previously-created trace, looked up by the
2153
2243
  * canonical Bitfab trace ID.
@@ -2292,6 +2382,25 @@ declare class BitfabFunction {
2292
2382
  * @returns A wrapped function with the same signature that creates spans
2293
2383
  */
2294
2384
  withSpan<TArgs extends unknown[], TReturn>(optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
2385
+ /**
2386
+ * Create a standard ECMAScript method decorator bound to this function key.
2387
+ *
2388
+ * @example
2389
+ * ```typescript
2390
+ * const orders = client.getFunction("order-processing");
2391
+ *
2392
+ * class OrderService {
2393
+ * @orders.span({ type: "agent" })
2394
+ * async process(orderId: string) {
2395
+ * return { orderId };
2396
+ * }
2397
+ * }
2398
+ * ```
2399
+ *
2400
+ * @param options - Span configuration applied to the decorated method
2401
+ * @returns A standard ECMAScript method decorator
2402
+ */
2403
+ span(options?: SpanOptions): SpanMethodDecorator;
2295
2404
  /**
2296
2405
  * Get a Vercel AI SDK language-model middleware bound to this function's key.
2297
2406
  *
@@ -2399,7 +2508,7 @@ declare class BitfabFunction {
2399
2508
  /**
2400
2509
  * SDK version from package.json (injected at build time)
2401
2510
  */
2402
- declare const __version__ = "0.36.4";
2511
+ declare const __version__ = "0.36.6";
2403
2512
 
2404
2513
  /**
2405
2514
  * Constants for the Bitfab SDK.
@@ -2467,4 +2576,4 @@ declare const finalizers: {
2467
2576
  readableStream: typeof readableStream;
2468
2577
  };
2469
2578
 
2470
- 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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, 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, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
2579
+ 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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
package/dist/index.d.ts CHANGED
@@ -1213,31 +1213,56 @@ interface ReplayOptions {
1213
1213
  * distinguish items whose function ran (`succeeded`) from items that threw
1214
1214
  * (`errored`).
1215
1215
  *
1216
- * Invoked synchronously right after each item settles, so keep it cheap. A
1216
+ * Invoked synchronously right after each item finishes, so keep it cheap. A
1217
1217
  * throwing callback never crashes the run: the error is swallowed so progress
1218
1218
  * UI can't break replay.
1219
1219
  */
1220
- onProgress?: (progress: ReplayProgress) => void;
1221
- }
1222
- /** Running totals reported to {@link ReplayOptions.onProgress} as replay proceeds. */
1223
- interface ReplayProgress {
1220
+ onItemFinish?: (progress: ReplayItemFinishProgress) => void;
1224
1221
  /**
1225
- * Event kind. Omitted (or `"item"`) for the per-trace settle events streamed
1226
- * during the run. `"complete"` marks the single terminal event emitted once
1227
- * the run has settled and been enriched server-side; it carries the full
1228
- * {@link ReplayProgress.result} and has no `item`. The Bitfab plugin reads
1229
- * that terminal event to build the run's final result without parsing stdout.
1222
+ * @deprecated Use {@link onItemFinish}. This compatibility callback receives
1223
+ * the same per-item finish events plus the legacy whole-run `"complete"`
1224
+ * event. It is ignored when `onItemFinish` is also provided.
1230
1225
  */
1231
- type?: "item" | "complete";
1226
+ onProgress?: (progress: ReplayProgress) => void;
1232
1227
  /**
1233
- * The full {@link ReplayResult}, present only on the terminal `"complete"`
1234
- * event. Lets the plugin ingest the enriched result (server-aggregated tokens,
1235
- * server trace ids) over the same channel as progress, so a dependency logging
1236
- * to stdout can never block it.
1228
+ * Called once when each replay item begins processing, before input loading,
1229
+ * mock preparation, database branching, or the customer function runs. Use
1230
+ * it with {@link onItemFinish} to distinguish queued items from items that
1231
+ * are still in flight. A throwing callback never crashes the run.
1237
1232
  */
1238
- result?: ReplayResult<unknown>;
1233
+ onItemStart?: (progress: ReplayItemStartProgress) => void;
1234
+ }
1235
+ /** Emitted through {@link ReplayOptions.onItemStart} when a worker starts an item. */
1236
+ interface ReplayItemStartProgress {
1237
+ type: "started";
1239
1238
  /** Test run ID created for this replay. */
1240
- testRunId?: string;
1239
+ testRunId: string;
1240
+ /** Items whose processing has started so far. */
1241
+ started: number;
1242
+ /** Items that have finished so far, whether they succeeded or errored. */
1243
+ completed: number;
1244
+ /** Total number of items in this replay run. */
1245
+ total: number;
1246
+ /** Of the completed items, how many finished without a code or replay error. */
1247
+ succeeded: number;
1248
+ /** Of the completed items, how many finished with an error. */
1249
+ errored: number;
1250
+ /** The historical trace and span whose replay processing just started. */
1251
+ item: {
1252
+ originalTraceId: string;
1253
+ originalSpanId: string;
1254
+ /** @deprecated alias for `originalTraceId`. */
1255
+ sourceTraceId: string;
1256
+ /** @deprecated alias for `originalSpanId`. */
1257
+ sourceSpanId: string;
1258
+ };
1259
+ }
1260
+ /** Running totals reported to {@link ReplayOptions.onItemFinish} as replay proceeds. */
1261
+ interface ReplayItemFinishProgress {
1262
+ /** Event kind, omitted for backward-compatible per-item events. */
1263
+ type?: "item";
1264
+ /** Test run ID created for this replay. */
1265
+ testRunId: string;
1241
1266
  /** Items that have finished so far, whether they succeeded or errored. */
1242
1267
  completed: number;
1243
1268
  /** Total number of items in this replay run. */
@@ -1247,7 +1272,7 @@ interface ReplayProgress {
1247
1272
  /** Of the completed items, how many have `item.error` set. */
1248
1273
  errored: number;
1249
1274
  /**
1250
- * The single item that just settled to produce this event. `traceId` is null
1275
+ * The single item that just finished to produce this event. `traceId` is null
1251
1276
  * at this stage (the server replay id isn't known until the run completes);
1252
1277
  * `originalTraceId` is the original (historical) trace that was replayed (so
1253
1278
  * a UI can identify or link it); `error` is its replay error, or null when it
@@ -1255,7 +1280,7 @@ interface ReplayProgress {
1255
1280
  * progress UI show per-trace pass/fail and timing as the run streams, without
1256
1281
  * waiting for the full {@link ReplayResult}.
1257
1282
  */
1258
- item?: {
1283
+ item: {
1259
1284
  /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
1260
1285
  traceId?: string | null;
1261
1286
  /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -1284,30 +1309,49 @@ interface ReplayProgress {
1284
1309
  dbSnapshotRef?: DbSnapshotRef | null;
1285
1310
  };
1286
1311
  }
1312
+ /**
1313
+ * @deprecated Use {@link ReplayItemFinishProgress}. This legacy shape also
1314
+ * represents the item-less terminal `"complete"` event emitted by
1315
+ * {@link ReplayOptions.onProgress}.
1316
+ */
1317
+ interface ReplayProgress {
1318
+ type?: "item" | "complete";
1319
+ result?: ReplayResult<unknown>;
1320
+ testRunId?: string;
1321
+ completed: number;
1322
+ total: number;
1323
+ succeeded: number;
1324
+ errored: number;
1325
+ item?: ReplayItemFinishProgress["item"];
1326
+ }
1287
1327
  /**
1288
1328
  * Wire prefix the Bitfab plugin scans for. Each line {@link reportReplayProgress}
1289
1329
  * writes is this prefix followed by the JSON of the running totals (plus the
1290
- * settled `item`). The plugin polls these lines to report live progress while a
1330
+ * finished `item`). The plugin polls these lines to report live progress while a
1291
1331
  * replay runs in the background; keep the SDK emitter and the plugin parser in
1292
1332
  * sync.
1293
1333
  */
1294
1334
  declare const BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
1295
1335
  /**
1296
- * A ready-made {@link ReplayOptions.onProgress} callback for replay scripts.
1336
+ * A ready-made replay lifecycle callback for replay scripts.
1297
1337
  * Pass it straight in:
1298
1338
  *
1299
1339
  * ```ts
1300
- * await bitfab.replay("my-fn", fn, { limit, onProgress: reportReplayProgress })
1340
+ * await bitfab.replay("my-fn", fn, {
1341
+ * limit,
1342
+ * onItemStart: reportReplayProgress,
1343
+ * onItemFinish: reportReplayProgress,
1344
+ * })
1301
1345
  * ```
1302
1346
  *
1303
- * It writes one `@@bitfab:progress` line per trace to stderr, which the Bitfab
1304
- * plugin polls to report live progress while the replay runs in the background,
1347
+ * It writes `@@bitfab:progress` lines to stderr, which the Bitfab plugin polls
1348
+ * to report in-flight and finished items while replay runs in the background,
1305
1349
  * so scripts never hand-format the wire protocol.
1306
1350
  * stdout is left untouched for direct-run ReplayResult JSON. Outside Node (no
1307
1351
  * `process.stderr`, e.g. a browser) it is a no-op, and a write failure is
1308
1352
  * swallowed so progress can never crash a run.
1309
1353
  */
1310
- declare function reportReplayProgress(progress: ReplayProgress): void;
1354
+ declare function reportReplayProgress(progress: ReplayItemFinishProgress | ReplayItemStartProgress | ReplayProgress): void;
1311
1355
  /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
1312
1356
  interface AdaptContext {
1313
1357
  /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -1878,6 +1922,27 @@ interface SpanOptions {
1878
1922
  */
1879
1923
  finalize?: (result: any) => unknown | Promise<unknown>;
1880
1924
  }
1925
+ /**
1926
+ * The standard method context passed to a decorator.
1927
+ *
1928
+ * Defined structurally instead of referencing TypeScript's built-in
1929
+ * `ClassMethodDecoratorContext`, which was added in TypeScript 5.0. This keeps
1930
+ * the SDK's non-decorator APIs consumable by projects on older compilers.
1931
+ */
1932
+ interface SpanMethodDecoratorContext<TThis, TValue> {
1933
+ readonly kind: "method";
1934
+ readonly name: string | symbol;
1935
+ readonly static: boolean;
1936
+ readonly private: boolean;
1937
+ readonly access: {
1938
+ has(object: TThis): boolean;
1939
+ get(object: TThis): TValue;
1940
+ };
1941
+ addInitializer(initializer: (this: TThis) => void): void;
1942
+ readonly metadata?: Record<PropertyKey, unknown>;
1943
+ }
1944
+ /** A standard ECMAScript method decorator produced by {@link Bitfab.span}. */
1945
+ type SpanMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(originalMethod: (this: TThis, ...args: TArgs) => TReturn, context: SpanMethodDecoratorContext<TThis, (this: TThis, ...args: TArgs) => TReturn>) => (this: TThis, ...args: TArgs) => TReturn;
1881
1946
 
1882
1947
  /**
1883
1948
  * Client for making provider-based API calls via BAML.
@@ -2148,6 +2213,31 @@ declare class Bitfab {
2148
2213
  * @returns A wrapped function with the same signature that creates spans for inputs and outputs
2149
2214
  */
2150
2215
  withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
2216
+ /**
2217
+ * Create a standard ECMAScript method decorator that records each invocation
2218
+ * as a span.
2219
+ *
2220
+ * It supports instance, static, and private methods; use
2221
+ * {@link Bitfab.withSpan} for standalone functions, class fields, and
2222
+ * accessors.
2223
+ *
2224
+ * @example
2225
+ * ```typescript
2226
+ * const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY });
2227
+ *
2228
+ * class OrderService {
2229
+ * @bitfab.span("order-processing", { type: "agent" })
2230
+ * async process(orderId: string) {
2231
+ * return { orderId };
2232
+ * }
2233
+ * }
2234
+ * ```
2235
+ *
2236
+ * @param traceFunctionKey - A string identifier for grouping spans
2237
+ * @param options - Span configuration applied to the decorated method
2238
+ * @returns A standard ECMAScript method decorator
2239
+ */
2240
+ span(traceFunctionKey: string, options?: SpanOptions): SpanMethodDecorator;
2151
2241
  /**
2152
2242
  * Get a detached handle to a previously-created trace, looked up by the
2153
2243
  * canonical Bitfab trace ID.
@@ -2292,6 +2382,25 @@ declare class BitfabFunction {
2292
2382
  * @returns A wrapped function with the same signature that creates spans
2293
2383
  */
2294
2384
  withSpan<TArgs extends unknown[], TReturn>(optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
2385
+ /**
2386
+ * Create a standard ECMAScript method decorator bound to this function key.
2387
+ *
2388
+ * @example
2389
+ * ```typescript
2390
+ * const orders = client.getFunction("order-processing");
2391
+ *
2392
+ * class OrderService {
2393
+ * @orders.span({ type: "agent" })
2394
+ * async process(orderId: string) {
2395
+ * return { orderId };
2396
+ * }
2397
+ * }
2398
+ * ```
2399
+ *
2400
+ * @param options - Span configuration applied to the decorated method
2401
+ * @returns A standard ECMAScript method decorator
2402
+ */
2403
+ span(options?: SpanOptions): SpanMethodDecorator;
2295
2404
  /**
2296
2405
  * Get a Vercel AI SDK language-model middleware bound to this function's key.
2297
2406
  *
@@ -2399,7 +2508,7 @@ declare class BitfabFunction {
2399
2508
  /**
2400
2509
  * SDK version from package.json (injected at build time)
2401
2510
  */
2402
- declare const __version__ = "0.36.4";
2511
+ declare const __version__ = "0.36.6";
2403
2512
 
2404
2513
  /**
2405
2514
  * Constants for the Bitfab SDK.
@@ -2467,4 +2576,4 @@ declare const finalizers: {
2467
2576
  readableStream: typeof readableStream;
2468
2577
  };
2469
2578
 
2470
- 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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, 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, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
2579
+ 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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  getCurrentReplayBranch,
12
12
  getCurrentSpan,
13
13
  getCurrentTrace
14
- } from "./chunk-5NT3VGCB.js";
14
+ } from "./chunk-BXWUPEC4.js";
15
15
  import {
16
16
  BITFAB_PROGRESS_PREFIX,
17
17
  BitfabError,
@@ -23,7 +23,7 @@ import {
23
23
  flushTraces,
24
24
  reportReplayProgress,
25
25
  serializeReplayResult
26
- } from "./chunk-6AXY24UL.js";
26
+ } from "./chunk-ENOQ2K2H.js";
27
27
  export {
28
28
  BITFAB_PROGRESS_PREFIX,
29
29
  Bitfab,