TypeScript SDK

# npm
npm install @bitfab/sdk

# pnpm
pnpm add @bitfab/sdk

# yarn
yarn add @bitfab/sdk

import { Bitfab } from "@bitfab/sdk"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })

new Bitfab({ apiKey: string })

// Omit apiKey entirely: the SDK reads BITFAB_API_KEY from the environment
new Bitfab({})

// Disable tracing (functions still execute, but no spans are sent)
new Bitfab({ apiKey: string, enabled: false })

// Pass a function to defer resolution explicitly (resolved at first use):
new Bitfab({ apiKey: () => process.env.BITFAB_API_KEY })

// Throws on the first traced call if no key resolves, instead of disabling quietly
new Bitfab({ apiKey: process.env.BITFAB_API_KEY, strict: true })

const orderService = bitfab.getFunction("order-processing")

async function processOrder(orderId: string) {
  return { orderId }
}

async function validateOrder(orderId: string) {
  return { valid: true }
}

// Wrap functions - all share the same trace function key
const tracedProcessOrder = orderService.withSpan(processOrder)
const tracedValidateOrder = orderService.withSpan(validateOrder)

// lib/bitfab.ts -- single source of truth
import { Bitfab } from "@bitfab/sdk"
const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })
export const orderService = bitfab.getFunction("order-processing")

// services/processOrder.ts
import { orderService } from "../lib/bitfab"

async function processOrder(orderId: string) {
  return { orderId }
}

export const tracedProcessOrder = orderService.withSpan(processOrder)

// services/validateOrder.ts
import { orderService } from "../lib/bitfab"

async function validateOrder(orderId: string) {
  return { valid: true }
}

export const tracedValidateOrder = orderService.withSpan(validateOrder)

// ✅ GOOD -- pass function directly, arguments are captured as span input
const result = await orderService.withSpan(
  { name: "ProcessOrder", type: "function" },
  processOrder,
)(orderId)

// ❌ BAD -- anonymous wrapper loses all input capture (span has no input)
const result = await orderService.withSpan(
  { name: "ProcessOrder", type: "function" },
  async () => processOrder(orderId),
)()

const standaloneTask = bitfab.withSpan("one-off-operation", () => {
  return "done"
})

const outer = bitfab.withSpan("outer", { type: "agent" }, async () => {
  await inner()  // Becomes a child of "outer"
})

const inner = bitfab.withSpan("inner", { type: "function" }, async () => {
  // ...
})

type SpanType =
  | "llm"        // LLM calls
  | "agent"      // Agent workflows
  | "function"   // Function calls
  | "guardrail"  // Safety checks
  | "handoff"    // Human handoffs
  | "custom"     // Default

// Function name is automatically captured as span name
async function processOrder(orderId: string) {
  return { orderId }
}
const traced = bitfab.withSpan("order-processing", processOrder)
// Span name: "processOrder"

// Override with name option
const traced = bitfab.withSpan(
  "order-processing",
  { name: "OrderProcessor" },
  processOrder
)
// Span name: "OrderProcessor"

// Set span type
const checkSafety = bitfab.withSpan(
  "safety-check",
  { type: "guardrail" },
  async (content: string) => ({ safe: true })
)

// With getFunction()
const service = bitfab.getFunction("order-processing")
const traced = service.withSpan({ name: "CustomName", type: "function" }, processOrder)

import { streamText } from "ai"
import { finalizers } from "@bitfab/sdk"

const runChatTurn = bitfab.withSpan(
  "chat-turn",
  { type: "agent", finalize: finalizers.aiSdk },
  () => streamText({ model, messages }),
)

// In your route handler:
const result = runChatTurn()                  // live StreamTextResult
return result.toUIMessageStreamResponse()     // stream to the user as usual
// The span records { text, usage, finishReason, toolCalls } in the background.

const runChatTurn = bitfab.withSpan(
  "chat-turn",
  {
    type: "agent",
    finalize: async (r) => ({ answer: await r.text, tokens: await r.totalUsage }),
  },
  () => streamText({ model, messages }),
)

import { finalizers } from "@bitfab/sdk"

let live: ReadableStream
const traced = bitfab.withSpan(
  "render",
  { finalize: (r) => finalizers.readableStream(r, (s) => { live = s }) },
  () => makeReadableStream(),
)
traced()
return new Response(live!)

const chatTurn = bitfab.getFunction("chat-turn")

const streamFromService = chatTurn.withSpan({ name: "stream-service" }, async function* () {
  yield "first"
  yield "second"
})

const handleChunk = chatTurn.withSpan({ name: "handle-chunk" }, async (chunk: string) => chunk)

const runController = chatTurn.withSpan({ name: "controller", type: "agent" }, async () => {
  for await (const chunk of streamFromService()) {
    await handleChunk(chunk)
  }
})

await runController()

import { getCurrentSpan } from "@bitfab/sdk"

async function processOrder(orderId: string) {
  const userId = await getCurrentUser()
  getCurrentSpan()?.addContext({ user_id: userId, order_id: orderId })
  return { orderId, status: "completed" }
}

const traced = bitfab.withSpan("order-processing", { type: "function" }, processOrder)

getCurrentSpan()?.addContext({ user_id: "u-123" })
getCurrentSpan()?.addContext({ request_id: "req-789" })
// Result: contexts: [{ user_id: "u-123" }, { request_id: "req-789" }]

import { getCurrentSpan } from "@bitfab/sdk"

const traced = bitfab.withSpan("my-function", async () => {
  const { id, traceId } = getCurrentSpan()
  console.log("Current span:", id, "trace:", traceId)
  return { id, traceId }
})

import { getCurrentSpan } from "@bitfab/sdk"

async function classifyText(text: string) {
  const prompt = `Classify the following text: ${text}`
  getCurrentSpan()?.setPrompt(prompt)
  const result = await llm.complete(prompt)
  return result
}

const traced = bitfab.withSpan("classification", { type: "llm" }, classifyText)

import { getCurrentTrace } from "@bitfab/sdk"

const traced = bitfab.withSpan("order-processing", { type: "function" }, async () => {
  const trace = getCurrentTrace()

  // Set session ID (stored as database column, filterable in dashboard)
  trace?.setSessionId("session-123")

  // Set trace metadata (stored in raw trace data)
  trace?.setMetadata({ region: "us-west-2", environment: "production" })

  // Add context entries (stored as key-value pairs, accumulates across calls)
  trace?.addContext({ workflow: "checkout-flow", batch_id: "batch-2024-01" })

  return { status: "completed" }
})

import { getCurrentTrace } from "@bitfab/sdk"

const traced = bitfab.withSpan("order-processing", { type: "function" }, async () => {
  if (isHealthCheck) {
    getCurrentTrace()?.drop()
  }

  return { status: "completed" }
})

const trace = client.getTrace(traceId)
await trace.addContext({ refund_status: "approved" })
await trace.setMetadata({ region: "us-west" })
await trace.setSessionId("session_xyz")

const span = await client.getTraceSpan(traceId, { name: "GenerateAnswer" })
const first = await client.getTraceSpan(traceId, {
  name: "GenerateAnswer",
  occurrence: "first",
})
const exact = await client.getTraceSpan(traceId, { id: spanId })

const risky = bitfab.withSpan("risky-service", () => {
  throw new Error("error")
})

try {
  risky()
} catch (e) {
  // Span records error and timing
}

new Bitfab({
  apiKey: string,                    // Required
  serviceUrl?: string,               // Default: https://bitfab.ai
  timeout?: number,                  // Request timeout in ms (default: 120000)
  envVars?: { OPENAI_API_KEY: string },  // For native function execution
  enabled?: boolean,                 // Default: true
  bamlClient?: unknown               // Generated BAML client (for wrapBAML)
})

const pipeline = bitfab.getFunction("my-function")

const updatedFn = pipeline.withSpan(
  { name: "UpdatedPipeline", type: "function" },
  async (input: string) => {
    // New implementation to test
    return { result: input.toUpperCase() }
  },
)

// Replay all traces (up to limit)
const result = await bitfab.replay("my-function", updatedFn, {
  name: "Uppercase candidate",
  limit: 10,
  maxConcurrency: 5,  // Default: 10
})

// Replay specific traces by ID
const result2 = await bitfab.replay("my-function", updatedFn, {
  traceIds: ["trace-id-1", "trace-id-2"],
})

// Result structure
console.log(result.testRunId)   // Test run identifier
console.log(result.testRunUrl)  // Dashboard URL
for (const item of result.items) {
  console.log(item.input)           // Original input
  console.log(item.result)          // New output
  console.log(item.originalOutput)  // Original output
  console.log(item.error)           // Error if any
  console.log(item.durationMs)      // Original trace duration in ms (or null)
  console.log(item.tokens)          // { input, output, cached, total } or null
  console.log(item.model)           // Original model name, or null
  console.log(item.traceId)         // Server trace ID for the replayed execution
}

// scripts/replay.ts
import { graph } from "../src/agent"          // the compiled LangGraph graph
import { bitfab } from "../src/bitfabClient"  // same client as instrumentation

const handler = bitfab.getLangGraphCallbackHandler("my-agent")  // same key

const replayMyAgent = async (state: AgentState) =>
  graph.invoke(state, {
    callbacks: [handler],
    configurable: buildReplayConfig(),
  })

const result = await bitfab.replay("my-agent", replayMyAgent, { limit: 10 })

const fetchArticle = bitfab.withSpan(
  "fetch-article-from-db",
  { mockOnReplay: true },
  async (id: string) => db.articles.findById(id),
)

const summarize = bitfab.withSpan(
  "summarize-article",
  async (article: Article) => /* real summarization, no flag */
)

const processArticle = bitfab.withSpan(
  "process-article",
  async (id: string) => summarize(await fetchArticle(id)),
)

// During replay, fetch-article-from-db returns its recorded output;
// summarize-article runs real so you can iterate on it.
const result = await bitfab.replay("process-article", processArticle, {
  limit: 10,
})

const result = await bitfab.replay("process-article", processArticle, {
  mock: "none", // run everything real...
  mockOverride: {
    // ...except this span, which gets the value you supply
    match: (node) => node.traceFunctionKey === "fetch-article-from-db",
    value: { id: "fixed", title: "Fixed title" }, // a flat value
  },
})

value: async ({ inputs, getOriginalOutput }) => ({
  ...(await getOriginalOutput()),
  score: 1,
})

bitfab.registerMockOverride({
  match: (node) => node.type === "llm",
  value: { label: "refund" },
})
// or the ordered form: registerMockOverride(match, value)
bitfab.clearMockOverrides() // reset

const result = await bitfab.replay("my-function", updatedFn, {
  // Recorded as (userId, limit); current signature is ({ userId, limit }).
  adaptInputs: (inputs, ctx) => {
    const [userId, limit] = inputs as [string, number]
    return [{ userId, limit }]
  },
})

// scripts/replay-adapters/extraction.ts
import type { AdaptInputsFn } from "@bitfab/sdk"

export const adaptInputs: AdaptInputsFn = (inputs, ctx) => {
  const [userId, limit] = inputs as [string, number]
  return [{ userId, limit }]
}

// scripts/replay.ts
import { adaptInputs } from "./replay-adapters/extraction"

await bitfab.replay("my-function", updatedFn, { limit, adaptInputs })

import { readFileSync } from "node:fs"

const before = readFileSync("src/foo.ts", "utf8")
// ...edit src/foo.ts...
const after = readFileSync("src/foo.ts", "utf8")

const result = await bitfab.replay("my-function", updatedFn, {
  name: "Retry fix candidate",
  codeChangeDescription: "fix off-by-one in retry logic",
  codeChangeFiles: [{ path: "src/foo.ts", before, after }],
})

const result = await bitfab.replay("my-function", updatedFn, { limit })

// Human-readable summary goes to stderr, so stdout stays pure JSON.
console.error(`Test run: ${result.testRunUrl}`)
console.error(`Items:    ${result.items.length}`)

// Full structured dump to stdout, ready for JSON.parse.
console.log(JSON.stringify(result, null, 2))

/**
 * Replay production traces through instrumented functions.
 *
 * Uses bitfab.replay() to fetch real traces and re-run them through
 * the current code, creating a test run for side-by-side comparison.
 *
 * Usage:
 *   npx tsx scripts/replay.ts <pipeline>
 *   npx tsx scripts/replay.ts <pipeline> --limit 20
 *   npx tsx scripts/replay.ts <pipeline> --trace-ids id1,id2
 */
import "dotenv/config"
import { reportReplayProgress } from "@bitfab/sdk"
import { bitfab } from "../lib/bitfab"
import { extractMemories } from "../services/extraction"
import { searchDocuments } from "../services/search"

const FUNCTIONS = {
  extraction: "my-extraction-pipeline",
  search: "my-search-pipeline",
} as const

type Pipeline = keyof typeof FUNCTIONS

const pipeline = process.argv[2] as Pipeline | undefined
const args = process.argv.slice(3)

if (!pipeline || !FUNCTIONS[pipeline]) {
  console.error(
    `Usage: npx tsx scripts/replay.ts <${Object.keys(FUNCTIONS).join("|")}> [--limit N] [--trace-ids id1,id2]`,
  )
  process.exit(1)
}

let limit = 10
let traceIds: string[] | undefined

for (let i = 0; i < args.length; i++) {
  if (args[i] === "--limit" && args[i + 1]) {
    limit = Number.parseInt(args[i + 1], 10)
    i++
  } else if (args[i] === "--trace-ids" && args[i + 1]) {
    traceIds = args[i + 1].split(",").map((id) => id.trim())
    i++
  }
}

// Each pipeline gets its own replay function -- replay deserializes
// historical inputs and spreads them into the function. If a signature drifts
// after traces were captured, add an input adapter (see the "Adapting inputs"
// section): write scripts/replay-adapters/<name>.ts, import its `adaptInputs`,
// and pass it here, e.g.
//   import { adaptInputs } from "./replay-adapters/extraction"
//   return bitfab.replay(FUNCTIONS.extraction, fn, { limit, adaptInputs })

async function replayExtraction() {
  const fn = async (conversation: string, existingItems: unknown[]) => {
    return extractMemories(conversation, existingItems)
  }
  // limit is ignored when traceIds is passed -- an explicit ID list
  // already determines how many traces replay.
  return bitfab.replay(FUNCTIONS.extraction, fn, {
    ...(traceIds ? { traceIds } : { limit }),
    // Live progress the Bitfab plugin polls while replay runs in the background.
    onProgress: reportReplayProgress,
  })
}

async function replaySearch() {
  const fn = async (query: string, opts: Record<string, unknown>) => {
    return searchDocuments(query, {
      userId: opts.userId as string,
      limit: (opts.limit as number) ?? 10,
    })
  }
  return bitfab.replay(FUNCTIONS.search, fn, {
    ...(traceIds ? { traceIds } : { limit }),
    // Live progress the Bitfab plugin polls while replay runs in the background.
    onProgress: reportReplayProgress,
  })
}

const REPLAY_FNS: Record<Pipeline, () => ReturnType<typeof bitfab.replay>> = {
  extraction: replayExtraction,
  search: replaySearch,
}

async function main() {
  const functionKey = FUNCTIONS[pipeline!]
  // Human-readable output goes to stderr; stdout carries only the ReplayResult JSON.
  console.error(`[replay] Replaying ${traceIds?.length ?? limit} traces from "${functionKey}"...\n`)

  const result = await REPLAY_FNS[pipeline!]()
  console.error(`Test run: ${result.testRunUrl}\n`)

  let changed = 0, same = 0, errors = 0

  for (const item of result.items) {
    const input = item.input as unknown[] | undefined
    const label = typeof input?.[0] === "string"
      ? input[0].slice(0, 80)
      : JSON.stringify(input?.[0] ?? "unknown").slice(0, 80)

    if (item.error) {
      console.error(`  ✗ "${label}"`)
      console.error(`    Error: ${item.error}`)
      errors++
    } else {
      const origStr =
        typeof item.originalOutput === "string"
          ? item.originalOutput
          : JSON.stringify(item.originalOutput)
      const newStr =
        typeof item.result === "string"
          ? item.result
          : JSON.stringify(item.result)
      const isSame = origStr === newStr
      const marker = isSame ? "=" : "Δ"

      console.error(`  ${marker} "${label}"`)
      console.error(`    Original: ${origStr}`)
      console.error(`    New:      ${newStr}`)

      isSame ? same++ : changed++
    }
  }

  console.error(`\n─── Summary ───`)
  console.error(`  Pipeline: ${pipeline}`)
  console.error(`  Replayed: ${result.items.length}`)
  console.error(`  Same:     ${same}`)
  console.error(`  Changed:  ${changed}`)
  if (errors > 0) console.error(`  Errors:   ${errors}`)
  console.error(`\n  ${result.testRunUrl}`)

  // Full ReplayResult as JSON to stdout (the Replay Output Contract).
  console.log(JSON.stringify(result, null, 2))
}

main().catch((err) => {
  console.error("[replay] Fatal error:", err)
  process.exit(1)
})