TypeScript SDK Reference

// Values
export { Bitfab, BitfabError, BitfabFunction, getCurrentSpan, getCurrentTrace, DetachedTrace } from "@bitfab/sdk"
export { BitfabOpenAITracingProcessor } from "@bitfab/sdk"
export { flushTraces } from "@bitfab/sdk"
export { reportReplayProgress } from "@bitfab/sdk"
export { __version__, DEFAULT_SERVICE_URL, BITFAB_PROGRESS_PREFIX } from "@bitfab/sdk"

// Types
export type {
  AllowedEnvVars,
  BamlExecutionResult,
  BitfabConfig,
  CapturedSpan,
  CurrentSpan,
  CurrentTrace,
  ProviderDefinition,
  ReplayItem,
  ReplayOptions,
  ReplayResult,
  SpanOptions,
  SpanLookup,
  SpanOccurrence,
  SpanType,
  ActiveSpanContext,
  DetachedTrace,
  TraceResponse,
  TracingProcessor,
  WrapBAMLOptions,
  WrappedBamlFn,
} from "@bitfab/sdk"

withSpan<TArgs extends unknown[], TReturn>(
  traceFunctionKey: string,
  optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn),
  maybeFn?: (...args: TArgs) => TReturn,
): (...args: TArgs) => TReturn

getFunction(traceFunctionKey: string): BitfabFunction

// Form 1 -- uses bamlClient from constructor
wrapBAML<TArgs, TReturn>(
  method: (...args: TArgs) => Promise<TReturn>,
  options?: WrapBAMLOptions,
): WrappedBamlFn<TArgs, TReturn>

// Form 2 -- explicit client
wrapBAML<TArgs, TReturn>(
  bamlClient: unknown,
  method: (...args: TArgs) => Promise<TReturn>,
  options?: WrapBAMLOptions,
): WrappedBamlFn<TArgs, TReturn>

getTrace(traceId: string): DetachedTrace

getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>

async replay<TReturn>(
  traceFunctionKey: string,
  fn: (...args: any[]) => TReturn | Promise<TReturn>,
  options?: ReplayOptions,
): Promise<ReplayResult<TReturn>>

async call<T = unknown>(
  methodName: string,
  inputs?: Record<string, unknown>,
): Promise<T>

getLangGraphCallbackHandler(traceFunctionKey: string): BitfabLangGraphCallbackHandler

getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor

getOpenAiAgentHandler(traceFunctionKey: string): BitfabOpenAIAgentHandler

getClaudeAgentHandler(traceFunctionKey: string): BitfabClaudeAgentHandler

getVercelAiMiddleware(traceFunctionKey: string): BitfabLanguageModelMiddleware

withSpan<TArgs, TReturn>(
  optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn),
  maybeFn?: (...args: TArgs) => TReturn,
): (...args: TArgs) => TReturn

getVercelAiMiddleware(): BitfabLanguageModelMiddleware

getClaudeAgentHandler(): BitfabClaudeAgentHandler

getLangGraphCallbackHandler(): BitfabLangGraphCallbackHandler

class BitfabError extends Error {
  constructor(message: string, url?: string)
  readonly url?: string
}

function getCurrentSpan(): CurrentSpan

function getCurrentTrace(): CurrentTrace

async function flushTraces(timeoutMs?: number): Promise<void>

interface SpanOptions {
  name?: string    // defaults to fn.name || traceFunctionKey
  type?: SpanType  // defaults to "custom"
}

type SpanType = "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom"

interface CurrentSpan {
  readonly id: string
  readonly traceId: string
  addContext(context: Record<string, unknown>): void
  setPrompt(prompt: string): void
}

interface CurrentTrace {
  setSessionId(sessionId: string): void
  setMetadata(metadata: Record<string, unknown>): void
  addContext(context: Record<string, unknown>): void
  drop(): void
}

interface DetachedTrace {
  readonly traceId: string
  addContext(context: Record<string, unknown>): Promise<unknown>
  setMetadata(metadata: Record<string, unknown>): Promise<unknown>
  setSessionId(sessionId: string): Promise<unknown>
}

interface WrapBAMLOptions {
  onCollector?: (collector: unknown) => void
}

interface WrappedBamlFn<TArgs extends unknown[], TReturn> {
  (...args: TArgs): Promise<TReturn>
  collector: unknown | null
}

interface ReplayOptions {
  limit?: number      // ignored (with a warning) when traceIds is passed
  traceIds?: string[] // max 100; the ID count determines how many traces replay
  name?: string       // display name for the resulting experiment/test run
  maxConcurrency?: number  // default 10
  experimentGroupId?: string
  environment?: ReplayEnvironment // per-trace DB branch exposed to the replayed fn
  datasetId?: string       // durably attributes the experiment to a dataset
  graderIds?: string[]     // graders attached to this run, unioned with the dataset's at grading (max 100)
  onProgress?: (progress: ReplayProgress) => void // per-item running totals
}

interface ReplayProgress {
  testRunId?: string // replay test run id
  completed: number  // items finished so far (succeeded or errored)
  total: number      // items in the run
  succeeded: number  // of completed, how many the fn ran without throwing
  errored: number    // of completed, how many threw
  item?: {           // the single trace that just settled
    traceId?: string | null      // null during the run; the server replay id arrives at completion
    originalTraceId: string | null // the original (historical) trace replayed
    sourceTraceId: string | null // deprecated alias for originalTraceId
    input?: unknown[]
    result?: unknown
    originalOutput?: unknown
    error: string | null       // its replay error, or null when it ran ok
    durationMs: number | null  // how long this one trace took to replay
    tokens?: TokenUsage | null
    model?: string | null
    dbSnapshotRef?: DbSnapshotRef | null
  }
}

interface ReplayResult<T> {
  items: ReplayItem<T>[]
  testRunId: string
  testRunUrl: string
}

interface ReplayItem<T> {
  input: unknown[]
  result: T | undefined
  originalOutput: unknown
  error: string | null
  durationMs: number | null // the original trace's duration
  tokens: TokenUsage | null // the replayed run's token usage (compare vs the original)
  model: string | null // the original trace's model
  traceId: string | null // the new replay trace's server id, written in after the run completes (null on older servers)
  originalTraceId: string // the original (historical) trace being replayed
  originalSpanId: string // the original root span the inputs were read from
  sourceTraceId: string // deprecated alias for originalTraceId
  sourceSpanId: string // deprecated alias for originalSpanId
  dbSnapshotRef: DbSnapshotRef | null // the source trace's snapshot pin, if any
}

interface AllowedEnvVars {
  OPENAI_API_KEY?: string
}

interface ActiveSpanContext {
  traceId: string
  spanId: string
}