TypeScript SDK Reference

// Values
export { Bitfab, BitfabError, BitfabFunction, getCurrentSpan, getCurrentTrace } from "bitfab"
export { BitfabOpenAITracingProcessor } from "bitfab"
export { flushTraces } from "bitfab"
export { __version__, DEFAULT_SERVICE_URL } from "bitfab"

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

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>

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

getClaudeAgentHandler(traceFunctionKey: string): BitfabClaudeAgentHandler

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

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 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
}

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

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

interface ReplayOptions {
  limit?: number
  traceIds?: string[]
  maxConcurrency?: number  // default 10
}

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

interface ReplayItem<T> {
  input: unknown[]
  result: T | undefined
  originalOutput: unknown
  error: string | null
}

interface AllowedEnvVars {
  OPENAI_API_KEY?: string
}

interface ActiveSpanContext {
  traceId: string
  spanId: string
}