bitfab 0.9.2

package/dist/index.d.cts

@@ -0,0 +1,568 @@
+import { Trace, Span } from '@openai/agents';
+
+/**
+ * BAML execution utilities for the Bitfab TypeScript SDK.
+ * This module provides functions to execute BAML prompts dynamically on the client side.
+ */
+/**
+ * Provider definition from the server.
+ */
+interface ProviderDefinition {
+    provider: string;
+    apiKeyEnv: string;
+    models: Array<{
+        model: string;
+        description: string;
+    }>;
+}
+/**
+ * Result of a BAML function execution with raw collector data.
+ */
+interface BamlExecutionResult {
+    /** The parsed result of the function */
+    result: unknown;
+    /** Raw collector data for the server to parse */
+    rawCollector: Record<string, unknown> | null;
+}
+/**
+ * Type for allowed environment variables.
+ * Only OPENAI_API_KEY is currently supported.
+ */
+type AllowedEnvVars = {
+    OPENAI_API_KEY?: string;
+};
+
+/**
+ * HTTP client utilities for Bitfab API requests.
+ *
+ * This module provides:
+ * - HttpClient class for making API requests
+ * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
+ */
+/**
+ * Error class for Bitfab API errors.
+ */
+declare class BitfabError extends Error {
+    readonly url?: string | undefined;
+    constructor(message: string, url?: string | undefined);
+}
+/**
+ * Wait for all pending fire-and-forget operations (spans, traces) to complete.
+ * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.
+ *
+ * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+ */
+declare function flushTraces(timeoutMs?: number): Promise<void>;
+
+/**
+ * Tracing utilities for external trace submission to Bitfab.
+ *
+ * This module provides utilities for sending external traces (e.g., from OpenAI API calls)
+ * to Bitfab for monitoring and analysis.
+ */
+
+interface TraceResponse {
+    traceId: string;
+    status: "success";
+}
+interface ActiveSpanContext {
+    traceId: string;
+    spanId: string;
+}
+/**
+ * TracingProcessor interface from OpenAI Agents SDK v0.3.7
+ */
+interface TracingProcessor {
+    onTraceStart(trace: Trace): Promise<void>;
+    onTraceEnd(trace: Trace): Promise<void>;
+    onSpanStart(span: Span<any>): Promise<void>;
+    onSpanEnd(span: Span<any>): Promise<void>;
+    forceFlush(): Promise<void>;
+    shutdown(timeout?: number): Promise<void>;
+}
+/**
+ * Tracing processor for OpenAI Agents SDK integration.
+ *
+ * Implements the TracingProcessor interface from the OpenAI Agents SDK to
+ * automatically capture traces and spans and send them to Bitfab for
+ * monitoring and analysis.
+ *
+ * Example usage:
+ * ```typescript
+ * import { Bitfab } from '@goharvest/bitfab';
+ * import { addTraceProcessor } from '@openai/agents';
+ *
+ * const client = new Bitfab({ apiKey: 'your-api-key' });
+ * const processor = client.getOpenAiTracingProcessor();
+ * addTraceProcessor(processor);
+ * ```
+ */
+declare class BitfabOpenAITracingProcessor implements TracingProcessor {
+    private readonly httpClient;
+    private activeTraces;
+    private readonly getActiveSpanContext;
+    private activeSpanMappings;
+    /**
+     * Initialize the tracing processor.
+     *
+     * @param config - Configuration options
+     */
+    constructor(config: {
+        apiKey?: string;
+        serviceUrl?: string;
+        timeout?: number;
+        getActiveSpanContext?: () => ActiveSpanContext | null;
+    });
+    /**
+     * Called when a trace is started.
+     * If there's an active withSpan context, the trace ID is remapped to the
+     * outer trace and sent to pre-create the external_traces row on the server.
+     */
+    onTraceStart(trace: Trace): Promise<void>;
+    /**
+     * Called when a trace is ended.
+     * If mapped to a withSpan trace, sends with remapped ID and completed=false
+     * since the parent withSpan handles completion.
+     */
+    onTraceEnd(trace: Trace): Promise<void>;
+    /**
+     * Called when a span is started.
+     */
+    onSpanStart(span: Span<any>): Promise<void>;
+    /**
+     * Called when a span is ended.
+     *
+     * Send all spans to Bitfab for complete trace capture.
+     */
+    onSpanEnd(span: Span<any>): Promise<void>;
+    /**
+     * Called when a trace is being flushed.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Called when the trace processor is shutting down.
+     */
+    shutdown(_timeout?: number): Promise<void>;
+    /**
+     * Send trace to Bitfab API (fire-and-forget).
+     * When traceIdOverride is provided, the trace ID is remapped to link
+     * the OpenAI trace into an outer withSpan trace.
+     */
+    private sendTrace;
+    /**
+     * Export span to JSON object, collecting any errors.
+     */
+    private exportSpan;
+    /**
+     * Extract and add input/response to serialized span, updating errors list.
+     */
+    private extractSpanInputResponse;
+    /**
+     * If the span's trace is mapped to a withSpan trace, rewrite trace_id and parent_id.
+     */
+    private applySpanOverrides;
+    /**
+     * Build span payload for the external spans API.
+     */
+    private buildSpanPayload;
+    /**
+     * Send span to Bitfab API (fire-and-forget).
+     * If the span belongs to a trace mapped to a withSpan trace, the trace_id
+     * and parent_id are rewritten to link the span into the withSpan tree.
+     */
+    private sendSpan;
+}
+
+/**
+ * Bitfab client for provider-based API calls.
+ */
+
+/**
+ * Options for wrapBAML.
+ */
+interface WrapBAMLOptions {
+    /** Called after each BAML invocation with the Collector instance. */
+    onCollector?: (collector: unknown) => void;
+}
+/**
+ * A function returned by wrapBAML that exposes the BAML collector from the last call.
+ */
+interface WrappedBamlFn<TArgs extends unknown[], TReturn> {
+    (...args: TArgs): Promise<TReturn>;
+    /** The BAML Collector instance from the most recent call. `null` before the first call or if @boundaryml/baml is unavailable. */
+    collector: unknown | null;
+}
+/**
+ * A handle to the current active span, allowing context to be added.
+ */
+interface CurrentSpan {
+    /** The trace ID for the current span. */
+    readonly traceId: string;
+    /**
+     * Add a context entry to this span. Each call appends to the contexts array.
+     * Context entries are stored in span_data.contexts as [{key, value}, ...].
+     */
+    addContext(context: Record<string, unknown>): void;
+    /**
+     * Set the prompt for this span. Stored in span_data.prompt.
+     * Calling multiple times overwrites the previous value.
+     */
+    setPrompt(prompt: string): void;
+}
+/**
+ * A handle to the current active trace, allowing trace-level context to be set.
+ */
+interface CurrentTrace {
+    /**
+     * Set the session ID for this trace. Stored in the database session_id column.
+     */
+    setSessionId(sessionId: string): void;
+    /**
+     * Set metadata for this trace. Stored in rawData.metadata.
+     * Subsequent calls merge with existing metadata, with later values taking precedence.
+     */
+    setMetadata(metadata: Record<string, unknown>): void;
+    /**
+     * Add a context entry to this trace. Each call appends to the contexts array.
+     * Context entries are stored in rawData.contexts as [{key, value}, ...].
+     */
+    addContext(context: Record<string, unknown>): void;
+}
+/**
+ * Get a handle to the current active span.
+ *
+ * Call this from inside a traced function (wrapped with `withSpan`) to get
+ * a span handle that allows adding context at runtime.
+ *
+ * Returns a no-op object if called outside of a span context (methods do nothing).
+ */
+declare function getCurrentSpan(): CurrentSpan;
+/**
+ * Get a handle to the current active trace.
+ *
+ * Call this from inside a traced function (wrapped with `withSpan`) to get
+ * a trace handle that allows setting trace-level context at runtime.
+ *
+ * Returns a no-op object if called outside of a span context (methods do nothing).
+ */
+declare function getCurrentTrace(): CurrentTrace;
+interface BitfabConfig {
+    /** The API key for Bitfab API authentication. When undefined or empty, tracing is disabled. */
+    apiKey?: string;
+    /** The base URL for the Bitfab API (default: https://bitfab.ai) */
+    serviceUrl?: string;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+    /** Environment variables for LLM provider API keys (only OPENAI_API_KEY is supported) */
+    envVars?: AllowedEnvVars;
+    /** Whether the client is enabled. Defaults to true. When false, withSpan returns the original function unwrapped. */
+    enabled?: boolean;
+    /** The generated BAML client instance (e.g., `b` from your baml_client). Used by wrapBAML() when no explicit client is passed. */
+    bamlClient?: unknown;
+}
+/**
+ * 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";
+/**
+ * Options for configuring span behavior.
+ */
+interface SpanOptions {
+    /**
+     * The name of the span. Defaults to the function name if available,
+     * otherwise falls back to the trace function key.
+     */
+    name?: string;
+    /**
+     * The type of span. Defaults to "custom" if not specified.
+     */
+    type?: SpanType;
+}
+
+/**
+ * Client for making provider-based API calls via BAML.
+ */
+declare class Bitfab {
+    private readonly apiKey;
+    private readonly serviceUrl;
+    private readonly timeout;
+    private readonly envVars;
+    private readonly enabled;
+    private readonly httpClient;
+    private readonly bamlClient;
+    /**
+     * Initialize the Bitfab client.
+     *
+     * @param config - Configuration options for the client
+     */
+    constructor(config: BitfabConfig);
+    /**
+     * Fetch the function with its current version and BAML prompt from the server.
+     *
+     * @param methodName - The name of the method to fetch
+     * @returns The function with current version, BAML prompt, and provider definitions
+     * @throws {BitfabError} If the function is not found or an error occurs
+     */
+    private fetchFunctionVersion;
+    /**
+     * Call a method with the given named arguments via BAML execution.
+     *
+     * @param methodName - The name of the method to call
+     * @param inputs - Named arguments to pass to the method
+     * @returns The result of the BAML function execution
+     * @throws {BitfabError} If service_url is not set, or if an error occurs
+     */
+    call<T = unknown>(methodName: string, inputs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Get a tracing processor for OpenAI Agents SDK integration.
+     *
+     * This processor automatically captures traces and spans from the OpenAI Agents SDK
+     * and sends them to Bitfab for monitoring and analysis.
+     *
+     * Example usage:
+     * ```typescript
+     * import { addTraceProcessor } from '@openai/agents';
+     *
+     * const client = new Bitfab({ apiKey: 'your-api-key' });
+     * const processor = client.getOpenAiTracingProcessor();
+     * addTraceProcessor(processor);
+     * ```
+     *
+     * @returns A BitfabOpenAITracingProcessor instance configured for this client
+     */
+    getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor;
+    /**
+     * Wrap a BAML client method to automatically capture prompt and LLM metadata.
+     *
+     * Creates a BAML Collector, calls the method through a tracked client,
+     * then extracts rendered messages and token usage — calling setPrompt()
+     * and addContext() on the current span automatically.
+     *
+     * The BAML client can be provided in the constructor or passed explicitly:
+     *
+     * ```typescript
+     * // Option 1: bamlClient in constructor (use wrapBAML with just the method)
+     * const client = new Bitfab({ apiKey: 'your-api-key', bamlClient: b });
+     * const traced = client.withSpan('classify', { type: 'llm' },
+     *   client.wrapBAML(b.ClassifyText)
+     * );
+     *
+     * // Option 2: pass bamlClient at call site
+     * const client = new Bitfab({ apiKey: 'your-api-key' });
+     * const traced = client.withSpan('classify', { type: 'llm' },
+     *   client.wrapBAML(b, b.ClassifyText)
+     * );
+     * ```
+     *
+     * @param methodOrClient - Either a BAML method (uses constructor bamlClient) or the BAML client instance
+     * @param maybeMethodOrOptions - The BAML method when the first argument is a client, or WrapBAMLOptions when the first argument is the method
+     * @param maybeOptions - WrapBAMLOptions when using the two-argument (client, method) form
+     * @returns An async function with the same signature that instruments the BAML call
+     */
+    wrapBAML<TArgs extends unknown[], TReturn>(methodOrClient: unknown, maybeMethodOrOptions?: ((...args: TArgs) => Promise<TReturn>) | WrapBAMLOptions, maybeOptions?: WrapBAMLOptions): WrappedBamlFn<TArgs, TReturn>;
+    /**
+     * Wrap a function to automatically create a span for its inputs and outputs.
+     *
+     * The wrapped function behaves identically to the original, but sends
+     * span data to Bitfab in the background after each call.
+     *
+     * Example usage:
+     * ```typescript
+     * const client = new Bitfab({ apiKey: 'your-api-key' });
+     *
+     * async function processOrder(orderId: string, items: string[]): Promise<{ total: number }> {
+     *   // ... process order
+     *   return { total: 100 };
+     * }
+     *
+     * // Basic usage (defaults to "custom" span type)
+     * const tracedProcessOrder = client.withSpan('order-processing', processOrder);
+     *
+     * // With explicit span type
+     * const tracedProcessOrder = client.withSpan('order-processing', { type: 'function' }, processOrder);
+     *
+     * // Call the wrapped function normally
+     * const result = await tracedProcessOrder('order-123', ['item-1', 'item-2']);
+     * // Span is automatically sent to Bitfab
+     * ```
+     *
+     * @param traceFunctionKey - A string identifier for grouping spans (e.g., 'order-processing', 'user-auth')
+     * @param optionsOrFn - Either SpanOptions or the function to wrap
+     * @param maybeFn - The function to wrap if options were provided
+     * @returns A wrapped function with the same signature that creates spans for inputs and outputs
+     */
+    withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    /**
+     * Get a function wrapper for a specific trace function key.
+     *
+     * This provides a fluent API alternative to calling withSpan directly,
+     * allowing you to bind the traceFunctionKey once and wrap multiple functions.
+     *
+     * Example usage:
+     * ```typescript
+     * const client = new Bitfab({ apiKey: 'your-api-key' });
+     *
+     * const orderFunc = client.getFunction('order-processing');
+     * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+     * const tracedValidateOrder = orderFunc.withSpan(validateOrder);
+     * ```
+     *
+     * @param traceFunctionKey - A string identifier for grouping spans
+     * @returns A BitfabFunction instance for wrapping functions
+     */
+    getFunction(traceFunctionKey: string): BitfabFunction;
+    /**
+     * Send trace completion when a root span ends.
+     * Internal method to record trace completion with end time.
+     * Fire-and-forget - sends to externalTraces endpoint via httpClient.
+     */
+    private sendTraceCompletion;
+    /**
+     * Send a wrapper span from function execution.
+     * Internal method to record spans when using withSpan.
+     * Fire-and-forget - sends to externalSpans endpoint via httpClient.
+     */
+    private sendWrapperSpan;
+    /**
+     * Replay historical traces through a function and create a test run.
+     *
+     * Fetches the last N traces for the given trace function key, re-runs each
+     * through the provided function, and returns comparison data.
+     *
+     * The function must have been wrapped with `withSpan` — replay injects
+     * `testRunId` via async context so new spans are linked to the test run.
+     *
+     * @param traceFunctionKey - The trace function key to replay
+     * @param fn - The function to replay (must be the return value of `withSpan`)
+     * @param options - Optional replay options (limit, traceIds)
+     * @returns ReplayResult with items, testRunId, and testRunUrl
+     */
+    replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: {
+        limit?: number;
+        traceIds?: string[];
+        maxConcurrency?: number;
+    }): Promise<{
+        items: Array<{
+            input: unknown[];
+            result: TReturn | undefined;
+            originalOutput: unknown;
+            error: string | null;
+        }>;
+        testRunId: string;
+        testRunUrl: string;
+    }>;
+}
+/**
+ * Represents a Bitfab function that can wrap user functions for tracing.
+ *
+ * This provides a fluent API for binding a traceFunctionKey once and
+ * then wrapping multiple functions with that key.
+ *
+ * Example usage:
+ * ```typescript
+ * const client = new Bitfab({ apiKey: 'your-api-key' });
+ *
+ * const orderFunc = client.getFunction('order-processing');
+ * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+ * const tracedValidateOrder = orderFunc.withSpan(validateOrder);
+ * ```
+ */
+declare class BitfabFunction {
+    private readonly client;
+    private readonly traceFunctionKey;
+    constructor(client: Bitfab, traceFunctionKey: string);
+    /**
+     * Wrap a function to automatically create a span for its inputs and outputs.
+     *
+     * The wrapped function behaves identically to the original, but sends
+     * span data to Bitfab in the background after each call.
+     *
+     * Example usage:
+     * ```typescript
+     * const orderFunc = client.getFunction('order-processing');
+     *
+     * // Basic usage (defaults to "custom" span type)
+     * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+     *
+     * // With explicit span type
+     * const tracedProcessOrder = orderFunc.withSpan({ type: 'function' }, processOrder);
+     * ```
+     *
+     * @param optionsOrFn - Either SpanOptions or the function to wrap
+     * @param maybeFn - The function to wrap if options were provided
+     * @returns A wrapped function with the same signature that creates spans
+     */
+    withSpan<TArgs extends unknown[], TReturn>(optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    /**
+     * Wrap a BAML client method to automatically capture prompt and LLM metadata.
+     * Delegates to the parent client's wrapBAML method.
+     *
+     * @param methodOrClient - Either a BAML method (uses constructor bamlClient) or the BAML client instance
+     * @param maybeMethodOrOptions - The BAML method when the first argument is a client, or WrapBAMLOptions when the first argument is the method
+     * @param maybeOptions - WrapBAMLOptions when using the two-argument (client, method) form
+     * @returns An async function with the same signature that instruments the BAML call
+     */
+    wrapBAML<TArgs extends unknown[], TReturn>(methodOrClient: unknown, maybeMethodOrOptions?: ((...args: TArgs) => Promise<TReturn>) | WrapBAMLOptions, maybeOptions?: WrapBAMLOptions): WrappedBamlFn<TArgs, TReturn>;
+}
+
+/**
+ * Auto-generated version file.
+ * This file is generated by scripts/generate-version.ts during build.
+ * DO NOT EDIT MANUALLY.
+ */
+/**
+ * SDK version from package.json (injected at build time)
+ */
+declare const __version__ = "0.9.2";
+
+/**
+ * Constants for the Bitfab SDK.
+ */
+/**
+ * Default service URL for Bitfab API.
+ */
+declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
+
+/**
+ * Replay historical traces through a function and create a test run.
+ *
+ * The replay flow has three phases:
+ * 1. Start — fetches historical traces from the server and creates a test run
+ * 2. Execute — re-runs each trace's inputs through the provided function locally
+ * 3. Complete — marks the test run as completed on the server
+ */
+
+interface ReplayOptions {
+    /** Maximum number of traces to replay (1–100, default 5). */
+    limit?: number;
+    /** Optional list of specific trace IDs to replay. */
+    traceIds?: string[];
+    /** Maximum number of items to process in parallel. Set to 1 for sequential. Default 10. */
+    maxConcurrency?: number;
+}
+interface ReplayItem<T> {
+    /** Deserialized inputs from the original trace. */
+    input: unknown[];
+    /** The result returned by the function during replay, or undefined on error. */
+    result: T | undefined;
+    /** The original output from the historical trace. */
+    originalOutput: unknown;
+    /** Error message if the function threw, or null on success. */
+    error: string | null;
+}
+interface ReplayResult<T> {
+    /** Individual replay items with inputs, results, and comparison data. */
+    items: ReplayItem<T>[];
+    /** The test run ID created on the server. */
+    testRunId: string;
+    /** Full URL to view the test run in the dashboard. */
+    testRunUrl: string;
+}
+
+export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, type BitfabConfig, BitfabError, BitfabFunction, BitfabOpenAITracingProcessor, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type ProviderDefinition, type ReplayItem, type ReplayOptions, type ReplayResult, type SpanOptions, type SpanType, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };