@bitfab/sdk 0.38.2 → 0.38.3

package/dist/index.d.cts

@@ -1234,7 +1234,7 @@ interface ReplayOptions {
      * because either source already determines how many traces replay.
      */
     limit?: number;
-    /** Optional list of specific trace IDs to replay (max 100). */
+    /** Optional list of specific trace IDs to replay (max 100). Mutually exclusive with `datasetId`. */
     traceIds?: string[];
     /** Optional display name for the resulting experiment/test run. */
     name?: string;
@@ -1291,7 +1291,8 @@ interface ReplayOptions {
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
-     * Dataset this replay runs against. When set, the resulting experiment is
+     * Dataset this replay runs against. Mutually exclusive with `traceIds`. When
+     * set, the resulting experiment is
      * durably attributed to the dataset (stored on the test run), so it appears
      * under the dataset's experiments even if the trace lineage can't be
      * reconstructed. Validated server-side against the org.
@@ -2717,7 +2718,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.2";
+declare const __version__ = "0.38.3";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2785,4 +2786,39 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-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 DbBranchTimings, 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 ReplayProgressItem, 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 };
+type ReplayFunction = (...args: any[]) => unknown | Promise<unknown>;
+type ReplayRegistryOptions = Omit<ReplayOptions, "onItemStart" | "onItemFinish" | "onProgress">;
+interface ReplayRegistryContext {
+    /** Values supplied through `--params` and repeated `--param name=value`. */
+    params: Readonly<Record<string, unknown>>;
+}
+type ReplayOptionsFactory = (context: ReplayRegistryContext) => ReplayRegistryOptions | Promise<ReplayRegistryOptions>;
+interface ReplayRegistration {
+    /** Client instance used by the production traced function. */
+    client: Bitfab;
+    /** The exact traced function production calls. */
+    fn: ReplayFunction;
+    /**
+     * Required for handler-instrumented or otherwise plain callables. Omit for a
+     * `withSpan`-wrapped function and the registry reads the wrapper's key.
+     */
+    traceFunctionKey?: string;
+    /**
+     * Per-function replay behavior and defaults. Put executable configuration
+     * such as `mockOverride` and `adaptInputs` here; command-line values override
+     * overlapping scalar defaults such as `mock` and `maxConcurrency`.
+     */
+    options?: ReplayRegistryOptions;
+    /** Build executable replay behavior from caller-supplied CLI parameters. */
+    optionsFactory?: ReplayOptionsFactory;
+}
+type ReplayRegistry = Record<string, ReplayRegistration>;
+/**
+ * Define the project-owned list of replayable functions.
+ *
+ * The registry is deliberately data-only: the SDK owns the replay CLI, so an
+ * SDK upgrade can add replay features without regenerating the project file.
+ */
+declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+
+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 DbBranchTimings, 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 ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, 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__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.d.ts

@@ -1234,7 +1234,7 @@ interface ReplayOptions {
      * because either source already determines how many traces replay.
      */
     limit?: number;
-    /** Optional list of specific trace IDs to replay (max 100). */
+    /** Optional list of specific trace IDs to replay (max 100). Mutually exclusive with `datasetId`. */
     traceIds?: string[];
     /** Optional display name for the resulting experiment/test run. */
     name?: string;
@@ -1291,7 +1291,8 @@ interface ReplayOptions {
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
-     * Dataset this replay runs against. When set, the resulting experiment is
+     * Dataset this replay runs against. Mutually exclusive with `traceIds`. When
+     * set, the resulting experiment is
      * durably attributed to the dataset (stored on the test run), so it appears
      * under the dataset's experiments even if the trace lineage can't be
      * reconstructed. Validated server-side against the org.
@@ -2717,7 +2718,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.2";
+declare const __version__ = "0.38.3";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2785,4 +2786,39 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-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 DbBranchTimings, 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 ReplayProgressItem, 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 };
+type ReplayFunction = (...args: any[]) => unknown | Promise<unknown>;
+type ReplayRegistryOptions = Omit<ReplayOptions, "onItemStart" | "onItemFinish" | "onProgress">;
+interface ReplayRegistryContext {
+    /** Values supplied through `--params` and repeated `--param name=value`. */
+    params: Readonly<Record<string, unknown>>;
+}
+type ReplayOptionsFactory = (context: ReplayRegistryContext) => ReplayRegistryOptions | Promise<ReplayRegistryOptions>;
+interface ReplayRegistration {
+    /** Client instance used by the production traced function. */
+    client: Bitfab;
+    /** The exact traced function production calls. */
+    fn: ReplayFunction;
+    /**
+     * Required for handler-instrumented or otherwise plain callables. Omit for a
+     * `withSpan`-wrapped function and the registry reads the wrapper's key.
+     */
+    traceFunctionKey?: string;
+    /**
+     * Per-function replay behavior and defaults. Put executable configuration
+     * such as `mockOverride` and `adaptInputs` here; command-line values override
+     * overlapping scalar defaults such as `mock` and `maxConcurrency`.
+     */
+    options?: ReplayRegistryOptions;
+    /** Build executable replay behavior from caller-supplied CLI parameters. */
+    optionsFactory?: ReplayOptionsFactory;
+}
+type ReplayRegistry = Record<string, ReplayRegistration>;
+/**
+ * Define the project-owned list of replayable functions.
+ *
+ * The registry is deliberately data-only: the SDK owns the replay CLI, so an
+ * SDK upgrade can add replay features without regenerating the project file.
+ */
+declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+
+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 DbBranchTimings, 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 ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, 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__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.js

@@ -7,11 +7,12 @@ import {
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
   SUPPORTED_PROVIDERS,
+  defineReplayRegistry,
   finalizers,
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-CWXCVY75.js";
+} from "./chunk-RJPHMJWO.js";
 import "./chunk-GFBQ2AMO.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -24,7 +25,7 @@ import {
   flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-SU7EAKOV.js";
+} from "./chunk-WX6AEFCP.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
@@ -43,6 +44,7 @@ export {
   ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,
+  defineReplayRegistry,
   finalizers,
   flushTraces,
   getCurrentReplayBranch,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.38.2";
+    __version__ = "0.38.3";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -2811,6 +2811,11 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       );
     }
   }
+  if (options?.traceIds !== void 0 && options?.datasetId !== void 0) {
+    throw new BitfabError(
+      "traceIds and datasetId select different replay sources and cannot be used together."
+    );
+  }
   if (options?.limit !== void 0 && options?.traceIds !== void 0) {
     try {
       console.warn(
@@ -3138,6 +3143,7 @@ __export(node_exports, {
   ReplayError: () => ReplayError,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
   __version__: () => __version__,
+  defineReplayRegistry: () => defineReplayRegistry,
   finalizers: () => finalizers,
   flushTraces: () => flushTraces,
   getCurrentReplayBranch: () => getCurrentReplayBranch,
@@ -7078,6 +7084,13 @@ var finalizers = {
 init_http();
 init_replay();
 
+// src/replayRegistry.ts
+init_errors();
+init_replay();
+function defineReplayRegistry(registry) {
+  return registry;
+}
+
 // src/node.ts
 init_asyncStorage();
 assertAsyncStorageRegistered();
@@ -7099,6 +7112,7 @@ assertAsyncStorageRegistered();
   ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,
+  defineReplayRegistry,
   finalizers,
   flushTraces,
   getCurrentReplayBranch,