bitfab 0.64.18 → 0.64.20

package/dist/index.d.cts

@@ -500,12 +500,35 @@ interface HttpClientConfig {
     timeout?: number;
 }
 type SpanOccurrence = "first" | "last" | number;
+declare const SPAN_TYPES: readonly ["llm", "agent", "function", "guardrail", "handoff", "custom"];
+/**
+ * Span types matching the backend enum.
+ * - llm: LLM API calls
+ * - agent: Autonomous orchestrators
+ * - function: Tool implementations
+ * - guardrail: Safety/validation checks
+ * - handoff: Agent-to-agent transfers
+ * - custom: Application-specific tracing (default)
+ */
+type SpanType = (typeof SPAN_TYPES)[number];
+/**
+ * Which span `getTraceSpan` returns: `id` alone, or `name` and/or `type`
+ * with an optional `occurrence` (`"first"`, `"last"` by default, or a
+ * zero-based index into the matches in the order they ran).
+ */
 type SpanLookup = {
     id: string;
     name?: never;
+    type?: never;
     occurrence?: never;
 } | {
     name: string;
+    type?: SpanType;
+    id?: never;
+    occurrence?: SpanOccurrence;
+} | {
+    type: SpanType;
+    name?: string;
     id?: never;
     occurrence?: SpanOccurrence;
 };
@@ -2866,6 +2889,48 @@ declare class BitfabRivetIntegration<TContext extends object = RivetContextLike>
     private createQueueIterator;
 }
 
+type SpanListField = "input" | "output" | "reasoning" | "content" | "errors" | "contexts";
+type SpanListParams = {
+    spanType?: SpanType;
+    spanName?: string;
+    fields?: SpanListField[];
+    cursor?: string | null;
+    /** Spans per page, 1 to 200, or at most 50 when `fields` is set. The server defaults to 50. */
+    limit?: number;
+};
+type ListedSpan = {
+    id: string;
+    traceId: string;
+    parentSpanId: string | null;
+    name: string | null;
+    type: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    input?: unknown;
+    output?: unknown;
+    reasoning?: unknown;
+    content?: unknown;
+    errors?: unknown;
+    contexts?: unknown;
+};
+type SpanListResult = {
+    spans: ListedSpan[];
+    nextCursor: string | null;
+    hasMore: boolean;
+};
+declare class SpansClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * List one trace's spans in the order they ran, one page at a time. No
+     * filter is required: omit `spanType` and `spanName` to page through every
+     * span. Each span carries one extra key per requested `fields` entry. Pass
+     * the returned `nextCursor` back as `cursor` for the next page. Throws a
+     * `BitfabError` with status 404 when the trace is not in your organization.
+     */
+    list(traceId: string, params?: SpanListParams): Promise<SpanListResult>;
+}
+
 /**
  * Tracing utilities for external trace submission to Bitfab.
  *
@@ -3224,16 +3289,7 @@ interface BitfabConfig {
     dbSnapshot?: DbSnapshotConfig;
     simulationPlan?: boolean;
 }
-/**
- * Span types matching the backend enum.
- * - llm: LLM API calls
- * - agent: Autonomous orchestrators
- * - function: Tool implementations
- * - guardrail: Safety/validation checks
- * - handoff: Agent-to-agent transfers
- * - custom: Application-specific tracing (default)
- */
-type SpanType = "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom";
+
 /**
  * Controls when a span is captured.
  * - always: Capture the span even when it becomes the root of a new trace.
@@ -3387,6 +3443,7 @@ declare class Bitfab {
     readonly assertionCategories: AssertionCategoriesClient;
     readonly organizationMembers: OrganizationMembersClient;
     readonly traces: TracesClient;
+    readonly spans: SpansClient;
     readonly labels: LabelsClient;
     readonly graders: GradersClient;
     readonly experiments: ExperimentsClient;
@@ -3778,8 +3835,10 @@ declare class Bitfab {
     getTrace(traceId: string): DetachedTrace;
     /**
      * Fetch one persisted span from a trace without loading the full trace.
-     * Name lookups return the last matching span by default. Pass `occurrence`
-     * as `"first"` or a zero-based index to select a different match.
+     * Look up by `id` alone, or by `name` and/or `type` (both must match when
+     * both are given). Name and type lookups return the last matching span by
+     * default. Pass `occurrence` as `"first"` or a zero-based index to select a
+     * different match. Returns `null` when no span matches.
      */
     getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
     getSpan(spanId: string): Promise<CapturedSpan | null>;
@@ -4095,7 +4154,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.64.18";
+declare const __version__ = "0.64.20";
 
 /**
  * Constants for the Bitfab SDK.
@@ -4234,4 +4293,4 @@ declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, ca
     run?: boolean;
 }): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, type ArchiveLabelTarget, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type Experiment, type ExperimentCategoryTally, type ExperimentCodeChangeTotals, type ExperimentJitter, type ExperimentPage, type ExperimentRollup, type ExperimentRollupResult, type ExperimentRunBy, type ExperimentStatus, type ExperimentTally, type ExperimentTotals, ExperimentsClient, type GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelOutcome, type GraderLabelSource, type GraderLabelUpdate, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, type ListExperimentsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayInterrupt, type ReplayInterruptSignal, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SaveScenarioData, type SaveScenarioHistoryEntry, type SaveScenarioParams, type Scenario, type ScenarioData, type ScenarioDataAppend, type ScenarioDataOrigin, type ScenarioHistoryEntry, type ScenarioSource, type ScenarioTrigger, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, type ArchiveLabelTarget, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type Experiment, type ExperimentCategoryTally, type ExperimentCodeChangeTotals, type ExperimentJitter, type ExperimentPage, type ExperimentRollup, type ExperimentRollupResult, type ExperimentRunBy, type ExperimentStatus, type ExperimentTally, type ExperimentTotals, ExperimentsClient, type GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelOutcome, type GraderLabelSource, type GraderLabelUpdate, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, type ListExperimentsParams, type ListedSpan, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayInterrupt, type ReplayInterruptSignal, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SaveScenarioData, type SaveScenarioHistoryEntry, type SaveScenarioParams, type Scenario, type ScenarioData, type ScenarioDataAppend, type ScenarioDataOrigin, type ScenarioHistoryEntry, type ScenarioSource, type ScenarioTrigger, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, type SpanListField, type SpanListParams, type SpanListResult, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, SpansClient, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };

package/dist/index.d.ts

@@ -500,12 +500,35 @@ interface HttpClientConfig {
     timeout?: number;
 }
 type SpanOccurrence = "first" | "last" | number;
+declare const SPAN_TYPES: readonly ["llm", "agent", "function", "guardrail", "handoff", "custom"];
+/**
+ * Span types matching the backend enum.
+ * - llm: LLM API calls
+ * - agent: Autonomous orchestrators
+ * - function: Tool implementations
+ * - guardrail: Safety/validation checks
+ * - handoff: Agent-to-agent transfers
+ * - custom: Application-specific tracing (default)
+ */
+type SpanType = (typeof SPAN_TYPES)[number];
+/**
+ * Which span `getTraceSpan` returns: `id` alone, or `name` and/or `type`
+ * with an optional `occurrence` (`"first"`, `"last"` by default, or a
+ * zero-based index into the matches in the order they ran).
+ */
 type SpanLookup = {
     id: string;
     name?: never;
+    type?: never;
     occurrence?: never;
 } | {
     name: string;
+    type?: SpanType;
+    id?: never;
+    occurrence?: SpanOccurrence;
+} | {
+    type: SpanType;
+    name?: string;
     id?: never;
     occurrence?: SpanOccurrence;
 };
@@ -2866,6 +2889,48 @@ declare class BitfabRivetIntegration<TContext extends object = RivetContextLike>
     private createQueueIterator;
 }
 
+type SpanListField = "input" | "output" | "reasoning" | "content" | "errors" | "contexts";
+type SpanListParams = {
+    spanType?: SpanType;
+    spanName?: string;
+    fields?: SpanListField[];
+    cursor?: string | null;
+    /** Spans per page, 1 to 200, or at most 50 when `fields` is set. The server defaults to 50. */
+    limit?: number;
+};
+type ListedSpan = {
+    id: string;
+    traceId: string;
+    parentSpanId: string | null;
+    name: string | null;
+    type: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    input?: unknown;
+    output?: unknown;
+    reasoning?: unknown;
+    content?: unknown;
+    errors?: unknown;
+    contexts?: unknown;
+};
+type SpanListResult = {
+    spans: ListedSpan[];
+    nextCursor: string | null;
+    hasMore: boolean;
+};
+declare class SpansClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * List one trace's spans in the order they ran, one page at a time. No
+     * filter is required: omit `spanType` and `spanName` to page through every
+     * span. Each span carries one extra key per requested `fields` entry. Pass
+     * the returned `nextCursor` back as `cursor` for the next page. Throws a
+     * `BitfabError` with status 404 when the trace is not in your organization.
+     */
+    list(traceId: string, params?: SpanListParams): Promise<SpanListResult>;
+}
+
 /**
  * Tracing utilities for external trace submission to Bitfab.
  *
@@ -3224,16 +3289,7 @@ interface BitfabConfig {
     dbSnapshot?: DbSnapshotConfig;
     simulationPlan?: boolean;
 }
-/**
- * Span types matching the backend enum.
- * - llm: LLM API calls
- * - agent: Autonomous orchestrators
- * - function: Tool implementations
- * - guardrail: Safety/validation checks
- * - handoff: Agent-to-agent transfers
- * - custom: Application-specific tracing (default)
- */
-type SpanType = "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom";
+
 /**
  * Controls when a span is captured.
  * - always: Capture the span even when it becomes the root of a new trace.
@@ -3387,6 +3443,7 @@ declare class Bitfab {
     readonly assertionCategories: AssertionCategoriesClient;
     readonly organizationMembers: OrganizationMembersClient;
     readonly traces: TracesClient;
+    readonly spans: SpansClient;
     readonly labels: LabelsClient;
     readonly graders: GradersClient;
     readonly experiments: ExperimentsClient;
@@ -3778,8 +3835,10 @@ declare class Bitfab {
     getTrace(traceId: string): DetachedTrace;
     /**
      * Fetch one persisted span from a trace without loading the full trace.
-     * Name lookups return the last matching span by default. Pass `occurrence`
-     * as `"first"` or a zero-based index to select a different match.
+     * Look up by `id` alone, or by `name` and/or `type` (both must match when
+     * both are given). Name and type lookups return the last matching span by
+     * default. Pass `occurrence` as `"first"` or a zero-based index to select a
+     * different match. Returns `null` when no span matches.
      */
     getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
     getSpan(spanId: string): Promise<CapturedSpan | null>;
@@ -4095,7 +4154,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.64.18";
+declare const __version__ = "0.64.20";
 
 /**
  * Constants for the Bitfab SDK.
@@ -4234,4 +4293,4 @@ declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, ca
     run?: boolean;
 }): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, type ArchiveLabelTarget, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type Experiment, type ExperimentCategoryTally, type ExperimentCodeChangeTotals, type ExperimentJitter, type ExperimentPage, type ExperimentRollup, type ExperimentRollupResult, type ExperimentRunBy, type ExperimentStatus, type ExperimentTally, type ExperimentTotals, ExperimentsClient, type GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelOutcome, type GraderLabelSource, type GraderLabelUpdate, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, type ListExperimentsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayInterrupt, type ReplayInterruptSignal, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SaveScenarioData, type SaveScenarioHistoryEntry, type SaveScenarioParams, type Scenario, type ScenarioData, type ScenarioDataAppend, type ScenarioDataOrigin, type ScenarioHistoryEntry, type ScenarioSource, type ScenarioTrigger, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, type ArchiveLabelTarget, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type Experiment, type ExperimentCategoryTally, type ExperimentCodeChangeTotals, type ExperimentJitter, type ExperimentPage, type ExperimentRollup, type ExperimentRollupResult, type ExperimentRunBy, type ExperimentStatus, type ExperimentTally, type ExperimentTotals, ExperimentsClient, type GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelOutcome, type GraderLabelSource, type GraderLabelUpdate, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, type ListExperimentsParams, type ListedSpan, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayInterrupt, type ReplayInterruptSignal, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SaveScenarioData, type SaveScenarioHistoryEntry, type SaveScenarioParams, type Scenario, type ScenarioData, type ScenarioDataAppend, type ScenarioDataOrigin, type ScenarioHistoryEntry, type ScenarioSource, type ScenarioTrigger, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, type SpanListField, type SpanListParams, type SpanListResult, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, SpansClient, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };

package/dist/index.js

@@ -28,6 +28,7 @@ import {
   LabelsClient,
   OrganizationMembersClient,
   SUPPORTED_PROVIDERS,
+  SpansClient,
   TracesClient,
   defineReplayRegistry,
   finalizers,
@@ -36,7 +37,7 @@ import {
   getCurrentTrace,
   reseedFromRegistry,
   seedFromRegistry
-} from "./chunk-4AZHPORE.js";
+} from "./chunk-NEZUD2GD.js";
 import "./chunk-YWXQM6J3.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -45,7 +46,7 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-HYIDCLES.js";
+} from "./chunk-RZ3GXYXE.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -53,7 +54,7 @@ import {
   MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-J76P75JP.js";
+} from "./chunk-YZKNF5CY.js";
 import "./chunk-MT36GJMW.js";
 export {
   AssertionCategoriesClient,
@@ -85,6 +86,7 @@ export {
   OrganizationMembersClient,
   ReplayError,
   SUPPORTED_PROVIDERS,
+  SpansClient,
   TracesClient,
   __version__,
   defineReplayRegistry,

package/dist/node.cjs

@@ -97,7 +97,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.64.18";
+    __version__ = "0.64.20";
     __packageName__ = "bitfab";
   }
 });
@@ -2130,6 +2130,7 @@ var http_exports = {};
 __export(http_exports, {
   BitfabError: () => BitfabError,
   HttpClient: () => HttpClient,
+  SPAN_TYPES: () => SPAN_TYPES,
   awaitOnExit: () => awaitOnExit,
   awaitPendingRequests: () => awaitPendingRequests,
   experimentIdWireFields: () => experimentIdWireFields,
@@ -2304,7 +2305,7 @@ function warnDroppedExternalTrace(error) {
 function experimentIdWireFields(experimentId) {
   return { experimentId, testRunId: experimentId };
 }
-var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, REPLAY_COMPLETE_REQUEST_TIMEOUT_MS, REPLAY_INTERRUPT_REQUEST_TIMEOUT_MS, REPLAY_HEARTBEAT_REQUEST_TIMEOUT_MS, OTLP_TRACES_ENDPOINT, RETRYABLE_STATUSES, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, liveHttpClients, carrierSeq, HttpClient;
+var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, REPLAY_COMPLETE_REQUEST_TIMEOUT_MS, REPLAY_INTERRUPT_REQUEST_TIMEOUT_MS, REPLAY_HEARTBEAT_REQUEST_TIMEOUT_MS, OTLP_TRACES_ENDPOINT, RETRYABLE_STATUSES, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, liveHttpClients, SPAN_TYPES, carrierSeq, HttpClient;
 var init_http = __esm({
   "src/http.ts"() {
     "use strict";
@@ -2362,6 +2363,14 @@ var init_http = __esm({
         });
       });
     }
+    SPAN_TYPES = [
+      "llm",
+      "agent",
+      "function",
+      "guardrail",
+      "handoff",
+      "custom"
+    ];
     carrierSeq = 0;
     HttpClient = class {
       constructor(config) {
@@ -2746,7 +2755,12 @@ var init_http = __esm({
         if (lookup.id !== void 0) {
           searchParams.set("id", lookup.id);
         } else {
-          searchParams.set("name", lookup.name);
+          if (lookup.name !== void 0) {
+            searchParams.set("name", lookup.name);
+          }
+          if (lookup.type !== void 0) {
+            searchParams.set("type", lookup.type);
+          }
           searchParams.set("occurrence", String(lookup.occurrence ?? "last"));
         }
         const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}/span?${searchParams.toString()}`;
@@ -5373,6 +5387,7 @@ __export(node_exports, {
   OrganizationMembersClient: () => OrganizationMembersClient,
   ReplayError: () => ReplayError,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
+  SpansClient: () => SpansClient,
   TracesClient: () => TracesClient,
   __version__: () => __version__,
   defineReplayRegistry: () => defineReplayRegistry,
@@ -6532,6 +6547,20 @@ async function runFunctionWithBaml(bamlSource, inputs, providers, envVars) {
   };
 }
 
+// src/bitfabIds.ts
+init_errors();
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function validateTraceId(traceId) {
+  if (typeof traceId !== "string" || !UUID_PATTERN.test(traceId)) {
+    throw new BitfabError("traceId must be a valid Bitfab trace ID");
+  }
+}
+function validateSpanId(id) {
+  if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+    throw new BitfabError("id must be a valid Bitfab span ID");
+  }
+}
+
 // src/client.ts
 init_captureSuppression();
 
@@ -8904,6 +8933,35 @@ function runWithSeedContext(ctx, fn) {
 init_serialize();
 init_simulationPlan();
 init_spanOrigin();
+
+// src/spans.ts
+var LIST_PATH = "/api/sdk/spans/list";
+function withoutUndefined(params) {
+  return Object.fromEntries(
+    Object.entries(params).filter(([, value]) => value !== void 0)
+  );
+}
+var SpansClient = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /**
+   * List one trace's spans in the order they ran, one page at a time. No
+   * filter is required: omit `spanType` and `spanName` to page through every
+   * span. Each span carries one extra key per requested `fields` entry. Pass
+   * the returned `nextCursor` back as `cursor` for the next page. Throws a
+   * `BitfabError` with status 404 when the trace is not in your organization.
+   */
+  async list(traceId, params = {}) {
+    validateTraceId(traceId);
+    return this.httpClient.request(
+      LIST_PATH,
+      withoutUndefined({ traceId, ...params })
+    );
+  }
+};
+
+// src/client.ts
 init_traceMetadata();
 
 // src/traces.ts
@@ -9784,16 +9842,8 @@ function extractContextFromCollector(collector) {
     return null;
   }
 }
-var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-function validateTraceId(traceId) {
-  if (typeof traceId !== "string" || !UUID_PATTERN.test(traceId)) {
-    throw new BitfabError("traceId must be a valid Bitfab trace ID");
-  }
-}
-function validateSpanId(id) {
-  if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
-    throw new BitfabError("id must be a valid Bitfab span ID");
-  }
+function isSpanType(value) {
+  return SPAN_TYPES.some((spanType) => spanType === value);
 }
 var noOpSpan = {
   id: "",
@@ -10027,6 +10077,7 @@ var Bitfab = class {
     this.assertionCategories = new AssertionCategoriesClient(this.httpClient);
     this.organizationMembers = new OrganizationMembersClient(this.httpClient);
     this.traces = new TracesClient(this.httpClient);
+    this.spans = new SpansClient(this.httpClient);
     this.labels = new LabelsClient(this.httpClient);
     this.graders = new GradersClient(this.httpClient);
     this.experiments = new ExperimentsClient(this.httpClient);
@@ -11505,22 +11556,27 @@ var Bitfab = class {
   }
   /**
    * Fetch one persisted span from a trace without loading the full trace.
-   * Name lookups return the last matching span by default. Pass `occurrence`
-   * as `"first"` or a zero-based index to select a different match.
+   * Look up by `id` alone, or by `name` and/or `type` (both must match when
+   * both are given). Name and type lookups return the last matching span by
+   * default. Pass `occurrence` as `"first"` or a zero-based index to select a
+   * different match. Returns `null` when no span matches.
    */
   async getTraceSpan(traceId, lookup) {
     validateTraceId(traceId);
     const hasId = lookup.id !== void 0;
-    const hasName = lookup.name !== void 0;
-    if (hasId === hasName) {
-      throw new BitfabError("Provide exactly one of id or name");
+    const hasNameOrType = lookup.name !== void 0 || lookup.type !== void 0;
+    if (hasId === hasNameOrType) {
+      throw new BitfabError("Provide id, or name and/or type");
     }
     if (hasId) {
       validateSpanId(lookup.id);
     } else {
-      if (lookup.name.length === 0) {
+      if (lookup.name !== void 0 && lookup.name.length === 0) {
         throw new BitfabError("name must be a non-empty string");
       }
+      if (lookup.type !== void 0 && !isSpanType(lookup.type)) {
+        throw new BitfabError(`type must be one of ${SPAN_TYPES.join(", ")}`);
+      }
       const occurrence = lookup.occurrence ?? "last";
       if (occurrence !== "first" && occurrence !== "last" && (!Number.isInteger(occurrence) || occurrence < 0)) {
         throw new BitfabError(
@@ -12355,6 +12411,7 @@ assertAsyncStorageRegistered();
   OrganizationMembersClient,
   ReplayError,
   SUPPORTED_PROVIDERS,
+  SpansClient,
   TracesClient,
   __version__,
   defineReplayRegistry,