bloop-sdk 0.2.0 → 0.3.0

package/dist/bloop.d.ts

@@ -20,21 +20,153 @@ export interface ErrorEvent {
     userIdHash?: string;
     metadata?: Record<string, unknown>;
 }
+export type SpanType = "generation" | "tool" | "retrieval" | "custom";
+export type SpanStatus = "ok" | "error";
+export type TraceStatus = "running" | "completed" | "error";
+export interface TraceOptions {
+    name: string;
+    sessionId?: string;
+    userId?: string;
+    input?: string;
+    metadata?: Record<string, unknown>;
+    promptName?: string;
+    promptVersion?: string;
+}
+export interface SpanOptions {
+    spanType: SpanType;
+    name?: string;
+    model?: string;
+    provider?: string;
+    input?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SpanEndOptions {
+    inputTokens?: number;
+    outputTokens?: number;
+    cost?: number;
+    status: SpanStatus;
+    errorMessage?: string;
+    output?: string;
+    timeToFirstTokenMs?: number;
+}
+export interface TraceEndOptions {
+    status: TraceStatus;
+    output?: string;
+}
+/** Options for the traceGeneration convenience method. */
+export interface TraceGenerationOptions {
+    name: string;
+    model?: string;
+    provider?: string;
+    input?: string;
+    sessionId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare class Span {
+    id: string;
+    parentSpanId: string | null;
+    spanType: SpanType;
+    name: string;
+    model?: string;
+    provider?: string;
+    startedAt: number;
+    input?: string;
+    metadata?: Record<string, unknown>;
+    inputTokens?: number;
+    outputTokens?: number;
+    cost?: number;
+    latencyMs?: number;
+    timeToFirstTokenMs?: number;
+    status?: SpanStatus;
+    errorMessage?: string;
+    output?: string;
+    constructor(opts: SpanOptions & {
+        parentSpanId?: string | null;
+    });
+    /** End this span and record metrics. */
+    end(opts: SpanEndOptions): void;
+    /** Serialize to server-expected format with snake_case keys. */
+    toJSON(): object;
+}
+export declare class Trace {
+    id: string;
+    name: string;
+    sessionId?: string;
+    userId?: string;
+    status: TraceStatus;
+    input?: string;
+    output?: string;
+    metadata?: Record<string, unknown>;
+    promptName?: string;
+    promptVersion?: string;
+    startedAt: number;
+    endedAt?: number;
+    spans: Span[];
+    private _client;
+    constructor(opts: TraceOptions, client: BloopClient);
+    /** Create a new span within this trace. */
+    startSpan(opts: SpanOptions): Span;
+    /** End this trace and push it to the client's trace buffer. */
+    end(opts: TraceEndOptions): void;
+    /** Serialize to server-expected format. */
+    private _toPayload;
+}
+export declare const MODEL_COSTS: Record<string, {
+    input: number;
+    output: number;
+}>;
 export declare class BloopClient {
     private config;
     private buffer;
+    private traceBuffer;
     private timer;
     private signingKey;
     private keyReady;
+    private globalHandlersInstalled;
+    private _modelCosts;
     constructor(config: BloopConfig);
     /** Import the HMAC key using Web Crypto API. */
     private importKey;
+    /**
+     * Install global error handlers for uncaught exceptions and unhandled rejections.
+     * Detects runtime (Node.js vs browser) and installs appropriate handlers.
+     * Uses addEventListener (not assignment) to avoid clobbering existing handlers.
+     */
+    installGlobalHandlers(): void;
     /** Capture an Error object. */
     captureError(error: Error, context?: Partial<ErrorEvent>): void;
     /** Capture a structured error event. */
     capture(event: ErrorEvent): void;
+    /** Start a new trace. Returns a Trace object for adding spans. */
+    startTrace(opts: TraceOptions): Trace;
+    /**
+     * Convenience method: creates a trace with a single generation span,
+     * calls the provided function, and ends both span and trace.
+     * Returns the value returned by the callback.
+     */
+    traceGeneration<T>(opts: TraceGenerationOptions, fn: (span: Span) => Promise<T>): Promise<T>;
+    /** Set custom cost rates for a model (per-token in dollars). */
+    setModelCosts(model: string, costs: {
+        input: number;
+        output: number;
+    }): void;
+    /** Wrap an OpenAI-compatible client instance to automatically trace all LLM calls. */
+    wrapOpenAI<T extends object>(client: T): T;
+    /** Wrap an Anthropic client instance to automatically trace all messages.create calls. */
+    wrapAnthropic<T extends object>(client: T): T;
+    /** Internal: trace an OpenAI-style API call. */
+    private _traceOpenAICall;
+    /** Internal: trace an Anthropic messages.create call. */
+    private _traceAnthropicCall;
+    /** Push a completed trace payload to the buffer. Called by Trace.end(). */
+    private _pushTrace;
     /** Flush buffered events to the server. */
     flush(): Promise<void>;
+    /** Flush error events to the ingest endpoint. */
+    private _flushErrors;
+    /** Flush trace payloads to the traces endpoint. */
+    private _flushTraces;
     /** Express/Koa error middleware. */
     errorMiddleware(): (err: Error, req: any, _res: any, next: any) => void;
     /** Stop the flush timer. Call on process shutdown. */

package/dist/bloop.js

@@ -1,8 +1,146 @@
+// ---- Span Class ----
+export class Span {
+    constructor(opts) {
+        this.id = crypto.randomUUID();
+        this.parentSpanId = opts.parentSpanId ?? null;
+        this.spanType = opts.spanType;
+        this.name = opts.name ?? opts.spanType;
+        this.model = opts.model;
+        this.provider = opts.provider;
+        this.startedAt = Date.now();
+        this.input = opts.input;
+        this.metadata = opts.metadata;
+    }
+    /** End this span and record metrics. */
+    end(opts) {
+        this.latencyMs = Date.now() - this.startedAt;
+        this.status = opts.status;
+        this.inputTokens = opts.inputTokens;
+        this.outputTokens = opts.outputTokens;
+        this.cost = opts.cost;
+        this.errorMessage = opts.errorMessage;
+        this.output = opts.output;
+        this.timeToFirstTokenMs = opts.timeToFirstTokenMs;
+    }
+    /** Serialize to server-expected format with snake_case keys. */
+    toJSON() {
+        return {
+            id: this.id,
+            parent_span_id: this.parentSpanId,
+            span_type: this.spanType,
+            name: this.name,
+            model: this.model ?? null,
+            provider: this.provider ?? null,
+            input: this.input ?? null,
+            output: this.output ?? null,
+            metadata: this.metadata ?? null,
+            started_at: this.startedAt,
+            input_tokens: this.inputTokens ?? null,
+            output_tokens: this.outputTokens ?? null,
+            cost: this.cost ?? null,
+            latency_ms: this.latencyMs ?? null,
+            time_to_first_token_ms: this.timeToFirstTokenMs ?? null,
+            status: this.status ?? null,
+            error_message: this.errorMessage ?? null,
+        };
+    }
+}
+export class Trace {
+    constructor(opts, client) {
+        this.status = "running";
+        this.spans = [];
+        this.id = crypto.randomUUID();
+        this.name = opts.name;
+        this.sessionId = opts.sessionId;
+        this.userId = opts.userId;
+        this.input = opts.input;
+        this.metadata = opts.metadata;
+        this.promptName = opts.promptName;
+        this.promptVersion = opts.promptVersion;
+        this.startedAt = Date.now();
+        this._client = client;
+    }
+    /** Create a new span within this trace. */
+    startSpan(opts) {
+        const span = new Span({
+            ...opts,
+            parentSpanId: null,
+        });
+        this.spans.push(span);
+        return span;
+    }
+    /** End this trace and push it to the client's trace buffer. */
+    end(opts) {
+        this.endedAt = Date.now();
+        this.status = opts.status;
+        if (opts.output !== undefined) {
+            this.output = opts.output;
+        }
+        this._client["_pushTrace"](this._toPayload());
+    }
+    /** Serialize to server-expected format. */
+    _toPayload() {
+        return {
+            id: this.id,
+            session_id: this.sessionId ?? null,
+            user_id: this.userId ?? null,
+            name: this.name,
+            status: this.status,
+            input: this.input ?? null,
+            output: this.output ?? null,
+            metadata: this.metadata ?? null,
+            prompt_name: this.promptName ?? null,
+            prompt_version: this.promptVersion ?? null,
+            started_at: this.startedAt,
+            ended_at: this.endedAt ?? null,
+            spans: this.spans.map((s) => s.toJSON()),
+        };
+    }
+}
+// ---- Auto-Instrumentation: Provider Detection ----
+const PROVIDER_MAP = {
+    "api.openai.com": "openai",
+    "api.anthropic.com": "anthropic",
+    "api.minimax.io": "minimax",
+    "api.minimaxi.com": "minimax",
+    "api.moonshot.ai": "kimi",
+    "generativelanguage.googleapis.com": "google",
+};
+function detectProvider(client) {
+    try {
+        const baseURL = client?.baseURL || client?._options?.baseURL || "";
+        const hostname = new URL(baseURL).hostname;
+        return PROVIDER_MAP[hostname] || hostname;
+    }
+    catch {
+        return "unknown";
+    }
+}
+// ---- Auto-Instrumentation: Model Pricing ----
+export const MODEL_COSTS = {
+    // OpenAI (per token in dollars)
+    "gpt-4o": { input: 2.50 / 1000000, output: 10.00 / 1000000 },
+    "gpt-4o-mini": { input: 0.15 / 1000000, output: 0.60 / 1000000 },
+    "gpt-4-turbo": { input: 10.00 / 1000000, output: 30.00 / 1000000 },
+    // Anthropic
+    "claude-sonnet-4-5-20250929": { input: 3.00 / 1000000, output: 15.00 / 1000000 },
+    "claude-haiku-4-5-20251001": { input: 0.80 / 1000000, output: 4.00 / 1000000 },
+    // Minimax
+    "MiniMax-M1": { input: 0.40 / 1000000, output: 2.20 / 1000000 },
+    "MiniMax-Text-01": { input: 0.20 / 1000000, output: 1.10 / 1000000 },
+    // Kimi
+    "kimi-k2": { input: 0.60 / 1000000, output: 2.50 / 1000000 },
+    "moonshot-v1-8k": { input: 0.20 / 1000000, output: 2.00 / 1000000 },
+};
+// ---- BloopClient ----
 export class BloopClient {
     constructor(config) {
         this.buffer = [];
+        this.traceBuffer = [];
         this.timer = null;
         this.signingKey = null;
+        this.globalHandlersInstalled = false;
+        this._modelCosts = {};
         this.config = {
             source: "api",
             maxBufferSize: 20,
@@ -19,6 +157,49 @@ export class BloopClient {
         const encoder = new TextEncoder();
         this.signingKey = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
     }
+    /**
+     * Install global error handlers for uncaught exceptions and unhandled rejections.
+     * Detects runtime (Node.js vs browser) and installs appropriate handlers.
+     * Uses addEventListener (not assignment) to avoid clobbering existing handlers.
+     */
+    installGlobalHandlers() {
+        if (this.globalHandlersInstalled)
+            return;
+        this.globalHandlersInstalled = true;
+        const isNode = typeof globalThis !== "undefined" &&
+            typeof globalThis.process?.on === "function";
+        if (isNode) {
+            const proc = globalThis.process;
+            proc.on("uncaughtException", (error) => {
+                this.captureError(error, {
+                    metadata: { unhandled: true, mechanism: "uncaughtException" },
+                });
+                this.flush();
+            });
+            proc.on("unhandledRejection", (reason) => {
+                const error = reason instanceof Error ? reason : new Error(String(reason));
+                this.captureError(error, {
+                    metadata: { unhandled: true, mechanism: "unhandledRejection" },
+                });
+            });
+        }
+        else if (typeof globalThis !== "undefined" && typeof globalThis.addEventListener === "function") {
+            globalThis.addEventListener("error", (event) => {
+                const error = event.error instanceof Error ? event.error : new Error(event.message || "Unknown error");
+                this.captureError(error, {
+                    metadata: { unhandled: true, mechanism: "onerror" },
+                });
+            });
+            globalThis.addEventListener("unhandledrejection", (event) => {
+                const error = event.reason instanceof Error
+                    ? event.reason
+                    : new Error(String(event.reason));
+                this.captureError(error, {
+                    metadata: { unhandled: true, mechanism: "onunhandledrejection" },
+                });
+            });
+        }
+    }
     /** Capture an Error object. */
     captureError(error, context) {
         this.capture({
@@ -55,8 +236,208 @@ export class BloopClient {
             this.flush();
         }
     }
+    // ---- LLM Tracing ----
+    /** Start a new trace. Returns a Trace object for adding spans. */
+    startTrace(opts) {
+        return new Trace(opts, this);
+    }
+    /**
+     * Convenience method: creates a trace with a single generation span,
+     * calls the provided function, and ends both span and trace.
+     * Returns the value returned by the callback.
+     */
+    async traceGeneration(opts, fn) {
+        const trace = this.startTrace({
+            name: opts.name,
+            sessionId: opts.sessionId,
+            userId: opts.userId,
+            input: opts.input,
+            metadata: opts.metadata,
+        });
+        const span = trace.startSpan({
+            spanType: "generation",
+            name: opts.name,
+            model: opts.model,
+            provider: opts.provider,
+            input: opts.input,
+        });
+        try {
+            const result = await fn(span);
+            trace.end({ status: "completed", output: span.output });
+            return result;
+        }
+        catch (err) {
+            if (!span.status) {
+                span.end({
+                    status: "error",
+                    errorMessage: err instanceof Error ? err.message : String(err),
+                });
+            }
+            trace.end({ status: "error" });
+            throw err;
+        }
+    }
+    // ---- Auto-Instrumentation ----
+    /** Set custom cost rates for a model (per-token in dollars). */
+    setModelCosts(model, costs) {
+        this._modelCosts[model] = costs;
+    }
+    /** Wrap an OpenAI-compatible client instance to automatically trace all LLM calls. */
+    wrapOpenAI(client) {
+        const bloop = this;
+        const provider = detectProvider(client);
+        return new Proxy(client, {
+            get(target, prop, receiver) {
+                const val = Reflect.get(target, prop, receiver);
+                if (prop === "chat") {
+                    return new Proxy(val, {
+                        get(chatTarget, chatProp, chatReceiver) {
+                            const chatVal = Reflect.get(chatTarget, chatProp, chatReceiver);
+                            if (chatProp === "completions") {
+                                return new Proxy(chatVal, {
+                                    get(compTarget, compProp, compReceiver) {
+                                        const compVal = Reflect.get(compTarget, compProp, compReceiver);
+                                        if (compProp === "create" && typeof compVal === "function") {
+                                            return async function (...args) {
+                                                return bloop._traceOpenAICall(provider, "chat.completions.create", compVal.bind(compTarget), args);
+                                            };
+                                        }
+                                        return compVal;
+                                    },
+                                });
+                            }
+                            return chatVal;
+                        },
+                    });
+                }
+                if (prop === "embeddings") {
+                    return new Proxy(val, {
+                        get(embTarget, embProp, embReceiver) {
+                            const embVal = Reflect.get(embTarget, embProp, embReceiver);
+                            if (embProp === "create" && typeof embVal === "function") {
+                                return async function (...args) {
+                                    return bloop._traceOpenAICall(provider, "embeddings.create", embVal.bind(embTarget), args);
+                                };
+                            }
+                            return embVal;
+                        },
+                    });
+                }
+                return val;
+            },
+        });
+    }
+    /** Wrap an Anthropic client instance to automatically trace all messages.create calls. */
+    wrapAnthropic(client) {
+        const bloop = this;
+        return new Proxy(client, {
+            get(target, prop, receiver) {
+                const val = Reflect.get(target, prop, receiver);
+                if (prop === "messages") {
+                    return new Proxy(val, {
+                        get(msgTarget, msgProp, msgReceiver) {
+                            const msgVal = Reflect.get(msgTarget, msgProp, msgReceiver);
+                            if (msgProp === "create" && typeof msgVal === "function") {
+                                return async function (...args) {
+                                    return bloop._traceAnthropicCall(msgVal.bind(msgTarget), args);
+                                };
+                            }
+                            return msgVal;
+                        },
+                    });
+                }
+                return val;
+            },
+        });
+    }
+    /** Internal: trace an OpenAI-style API call. */
+    async _traceOpenAICall(provider, method, fn, args) {
+        const params = args[0] || {};
+        const model = params.model || "unknown";
+        const traceName = `${provider}.${method}`;
+        const trace = this.startTrace({ name: traceName });
+        const span = trace.startSpan({
+            spanType: "generation",
+            name: traceName,
+            model,
+            provider,
+            input: params.messages
+                ? JSON.stringify(params.messages.slice(-1))
+                : undefined,
+        });
+        try {
+            const response = await fn(...args);
+            // Extract usage from response
+            const usage = response?.usage;
+            const inputTokens = usage?.prompt_tokens || 0;
+            const outputTokens = usage?.completion_tokens || 0;
+            // Compute cost
+            const rates = this._modelCosts[model] || MODEL_COSTS[model];
+            let cost = 0;
+            if (rates) {
+                cost = inputTokens * rates.input + outputTokens * rates.output;
+            }
+            // Extract output
+            const output = response?.choices?.[0]?.message?.content;
+            span.end({ inputTokens, outputTokens, cost, status: "ok", output });
+            trace.end({ status: "completed", output });
+            return response;
+        }
+        catch (err) {
+            span.end({
+                status: "error",
+                errorMessage: err?.message || String(err),
+            });
+            trace.end({ status: "error" });
+            throw err;
+        }
+    }
+    /** Internal: trace an Anthropic messages.create call. */
+    async _traceAnthropicCall(fn, args) {
+        const params = args[0] || {};
+        const model = params.model || "unknown";
+        const trace = this.startTrace({ name: "anthropic.messages.create" });
+        const span = trace.startSpan({
+            spanType: "generation",
+            name: "anthropic.messages.create",
+            model,
+            provider: "anthropic",
+        });
+        try {
+            const response = await fn(...args);
+            const inputTokens = response?.usage?.input_tokens || 0;
+            const outputTokens = response?.usage?.output_tokens || 0;
+            const rates = this._modelCosts[model] || MODEL_COSTS[model];
+            let cost = 0;
+            if (rates) {
+                cost = inputTokens * rates.input + outputTokens * rates.output;
+            }
+            const output = response?.content?.[0]?.text;
+            span.end({ inputTokens, outputTokens, cost, status: "ok", output });
+            trace.end({ status: "completed", output });
+            return response;
+        }
+        catch (err) {
+            span.end({
+                status: "error",
+                errorMessage: err?.message || String(err),
+            });
+            trace.end({ status: "error" });
+            throw err;
+        }
+    }
+    /** Push a completed trace payload to the buffer. Called by Trace.end(). */
+    _pushTrace(payload) {
+        this.traceBuffer.push(payload);
+    }
     /** Flush buffered events to the server. */
     async flush() {
+        const flushErrors = this._flushErrors();
+        const flushTraces = this._flushTraces();
+        await Promise.all([flushErrors, flushTraces]);
+    }
+    /** Flush error events to the ingest endpoint. */
+    async _flushErrors() {
         if (this.buffer.length === 0)
             return;
         // Ensure key is ready
@@ -90,6 +471,39 @@ export class BloopClient {
             }
         }
     }
+    /** Flush trace payloads to the traces endpoint. */
+    async _flushTraces() {
+        if (this.traceBuffer.length === 0)
+            return;
+        // Ensure key is ready
+        await this.keyReady;
+        const traces = this.traceBuffer.splice(0);
+        const body = JSON.stringify({ traces });
+        const signature = await this.sign(body);
+        const headers = {
+            "Content-Type": "application/json",
+            "X-Signature": signature,
+        };
+        if (this.config.projectKey) {
+            headers["X-Project-Key"] = this.config.projectKey;
+        }
+        try {
+            const resp = await fetch(`${this.config.endpoint}/v1/traces/batch`, {
+                method: "POST",
+                headers,
+                body,
+            });
+            if (!resp.ok) {
+                console.warn(`[bloop] trace flush failed: ${resp.status}`);
+            }
+        }
+        catch (err) {
+            if (typeof globalThis !== "undefined" &&
+                globalThis.process?.env?.NODE_ENV !== "production") {
+                console.warn("[bloop] trace flush error:", err);
+            }
+        }
+    }
     /** Express/Koa error middleware. */
     errorMiddleware() {
         return (err, req, _res, next) => {
@@ -135,9 +549,29 @@ class HttpError extends Error {
 //   release: "1.0.0",
 // });
 //
+// // Install global handlers (Node.js or browser)
+// client.installGlobalHandlers();
+//
 // // Capture errors
 // client.captureError(new Error("something broke"), { route: "/api/users" });
 //
+// // LLM Tracing
+// const trace = client.startTrace({ name: "chat-completion", input: "Hello" });
+// const span = trace.startSpan({ spanType: "generation", model: "gpt-4o", provider: "openai" });
+// // ... call LLM ...
+// span.end({ inputTokens: 100, outputTokens: 50, cost: 0.0025, status: "ok", output: "Hi!" });
+// trace.end({ status: "completed", output: "Hi!" });
+//
+// // Convenience: traceGeneration
+// const result = await client.traceGeneration(
+//   { name: "quick-gen", model: "gpt-4o", provider: "openai", input: "Hello" },
+//   async (span) => {
+//     const response = "Hi!"; // call LLM here
+//     span.end({ inputTokens: 10, outputTokens: 5, cost: 0.001, status: "ok", output: response });
+//     return response;
+//   }
+// );
+//
 // // Express middleware
 // app.use(client.errorMiddleware());
 //

package/dist/test-auto-instrument.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Type-level and behavioral tests for auto-instrumentation.
+ * `npx tsc --noEmit` must pass with this file included.
+ *
+ * Tests cover:
+ * 1. MODEL_COSTS export exists and has correct shape
+ * 2. detectProvider() helper works (tested indirectly via wrapOpenAI)
+ * 3. BloopClient.wrapOpenAI() exists, accepts an object, returns same type
+ * 4. BloopClient.wrapAnthropic() exists, accepts an object, returns same type
+ * 5. BloopClient.setModelCosts() exists with correct signature
+ * 6. Wrapped client preserves original type
+ * 7. Backward compatibility: all existing APIs still work
+ */
+export {};

package/dist/test-auto-instrument.js

@@ -0,0 +1,79 @@
+/**
+ * Type-level and behavioral tests for auto-instrumentation.
+ * `npx tsc --noEmit` must pass with this file included.
+ *
+ * Tests cover:
+ * 1. MODEL_COSTS export exists and has correct shape
+ * 2. detectProvider() helper works (tested indirectly via wrapOpenAI)
+ * 3. BloopClient.wrapOpenAI() exists, accepts an object, returns same type
+ * 4. BloopClient.wrapAnthropic() exists, accepts an object, returns same type
+ * 5. BloopClient.setModelCosts() exists with correct signature
+ * 6. Wrapped client preserves original type
+ * 7. Backward compatibility: all existing APIs still work
+ */
+import { BloopClient, MODEL_COSTS, } from "./bloop.js";
+// ---- Test: MODEL_COSTS export exists and has correct shape ----
+const costs = MODEL_COSTS;
+// Verify specific models exist
+const gpt4oCost = MODEL_COSTS["gpt-4o"];
+const gpt4oMiniCost = MODEL_COSTS["gpt-4o-mini"];
+// Values should be numbers (compile-time check)
+const inputCost = MODEL_COSTS["gpt-4o"].input;
+const outputCost = MODEL_COSTS["gpt-4o"].output;
+// ---- Test: BloopClient construction (unchanged) ----
+const client = new BloopClient({
+    endpoint: "https://errors.test.com",
+    projectKey: "test-key",
+    environment: "test",
+    release: "1.0.0",
+});
+// ---- Test: setModelCosts() method exists ----
+client.setModelCosts("my-custom-model", { input: 0.001, output: 0.002 });
+client.setModelCosts("gpt-4o", { input: 0.003, output: 0.01 }); // Override built-in
+// wrapOpenAI should accept any object and return the same type
+const mockOAI = {};
+const wrappedOAI = client.wrapOpenAI(mockOAI);
+// The returned type must be the same as the input type
+function assertTypePreserved(input) {
+    return client.wrapOpenAI(input);
+}
+const mockAnthropic = {};
+const wrappedAnthropic = client.wrapAnthropic(mockAnthropic);
+// ---- Test: Backward compatibility - existing APIs still work ----
+async function testBackwardCompat() {
+    // startTrace still works
+    const trace = client.startTrace({ name: "compat-test" });
+    const span = trace.startSpan({ spanType: "generation", model: "gpt-4o" });
+    span.end({ status: "ok", inputTokens: 10, outputTokens: 5 });
+    trace.end({ status: "completed" });
+    // traceGeneration still works
+    const result = await client.traceGeneration({ name: "compat-gen", model: "gpt-4o", provider: "openai" }, async (span) => {
+        span.end({ status: "ok" });
+        return "result";
+    });
+    const s = result;
+    // flush/close still work
+    await client.flush();
+    await client.close();
+}
+const extClient = {};
+const wrappedExt = client.wrapOpenAI(extClient);
+// customProp and someMethod should still be accessible (type-level)
+const _cp = wrappedExt.customProp;
+const _sm = wrappedExt.someMethod;
+// ---- Test: wrapOpenAI and wrapAnthropic can be called with plain objects ----
+const plainWrapped = client.wrapOpenAI({
+    chat: {
+        completions: {
+            create: async () => ({ choices: [], usage: { prompt_tokens: 0, completion_tokens: 0 } }),
+        },
+    },
+});
+const anthropicPlain = client.wrapAnthropic({
+    messages: {
+        create: async () => ({
+            content: [{ type: "text", text: "hello" }],
+            usage: { input_tokens: 0, output_tokens: 0 },
+        }),
+    },
+});

package/dist/test-tracing.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Type-level tests for LLM tracing support.
+ * This file exercises all new types and APIs.
+ * `npx tsc --noEmit` must pass for these tests to be "green."
+ */
+export {};

package/dist/test-tracing.js

@@ -0,0 +1,188 @@
+/**
+ * Type-level tests for LLM tracing support.
+ * This file exercises all new types and APIs.
+ * `npx tsc --noEmit` must pass for these tests to be "green."
+ */
+import { BloopClient, } from "./bloop.js";
+// ---- Test: Types exist and are correct ----
+const spanType = "generation";
+const spanType2 = "tool";
+const spanType3 = "retrieval";
+const spanType4 = "custom";
+const spanStatus = "ok";
+const spanStatus2 = "error";
+const traceStatus = "running";
+const traceStatus2 = "completed";
+const traceStatus3 = "error";
+// ---- Test: TraceOptions interface ----
+const traceOpts = {
+    name: "chat-completion",
+    sessionId: "sess-123",
+    userId: "user-456",
+    input: "Hello, world!",
+    metadata: { key: "value" },
+    promptName: "my-prompt",
+    promptVersion: "1.0",
+};
+// Minimal TraceOptions (only name required)
+const traceOptsMinimal = {
+    name: "minimal-trace",
+};
+// ---- Test: SpanOptions interface ----
+const spanOpts = {
+    spanType: "generation",
+    name: "gpt-4o call",
+    model: "gpt-4o",
+    provider: "openai",
+    input: "prompt text",
+    metadata: { temperature: 0.7 },
+};
+// Minimal SpanOptions (only spanType required)
+const spanOptsMinimal = {
+    spanType: "tool",
+};
+// ---- Test: SpanEndOptions interface ----
+const spanEndOpts = {
+    inputTokens: 100,
+    outputTokens: 50,
+    cost: 0.0025,
+    status: "ok",
+    errorMessage: undefined,
+    output: "Generated text",
+    timeToFirstTokenMs: 300,
+};
+// Minimal SpanEndOptions (only status required)
+const spanEndOptsMinimal = {
+    status: "error",
+    errorMessage: "Something went wrong",
+};
+// ---- Test: TraceEndOptions interface ----
+const traceEndOpts = {
+    status: "completed",
+    output: "Final response text",
+};
+const traceEndOptsMinimal = {
+    status: "error",
+};
+// ---- Test: BloopClient.startTrace() returns a Trace ----
+const client = new BloopClient({
+    endpoint: "https://errors.test.com",
+    projectKey: "test-key",
+    environment: "test",
+    release: "1.0.0",
+});
+const trace = client.startTrace({
+    name: "chat-completion",
+    sessionId: "sess-123",
+    userId: "user-456",
+    input: "What is the weather?",
+    metadata: { source: "api" },
+    promptName: "weather-prompt",
+    promptVersion: "2.1",
+});
+// ---- Test: Trace properties ----
+const traceId = trace.id;
+const traceName = trace.name;
+const traceSessionId = trace.sessionId;
+const traceUserId = trace.userId;
+const traceStatusProp = trace.status;
+const traceInput = trace.input;
+const traceOutput = trace.output;
+const traceMetadata = trace.metadata;
+const tracePromptName = trace.promptName;
+const tracePromptVersion = trace.promptVersion;
+const traceStartedAt = trace.startedAt;
+const traceEndedAt = trace.endedAt;
+const traceSpans = trace.spans;
+// ---- Test: Trace.startSpan() returns a Span ----
+const span = trace.startSpan({
+    spanType: "generation",
+    name: "gpt-4o call",
+    model: "gpt-4o",
+    provider: "openai",
+    input: "prompt",
+    metadata: { key: "val" },
+});
+// ---- Test: Span properties ----
+const spanId = span.id;
+const spanParentId = span.parentSpanId;
+const spanSpanType = span.spanType;
+const spanName = span.name;
+const spanModel = span.model;
+const spanProvider = span.provider;
+const spanStartedAt = span.startedAt;
+const spanInput = span.input;
+const spanMetadata = span.metadata;
+// ---- Test: Span.end() ----
+span.end({
+    inputTokens: 100,
+    outputTokens: 50,
+    cost: 0.0025,
+    status: "ok",
+    output: "generated response",
+    timeToFirstTokenMs: 300,
+});
+// After end(), these should be set
+const spanInputTokens = span.inputTokens;
+const spanOutputTokens = span.outputTokens;
+const spanCost = span.cost;
+const spanLatencyMs = span.latencyMs;
+const spanTtft = span.timeToFirstTokenMs;
+const spanStatusProp = span.status;
+const spanErrorMessage = span.errorMessage;
+const spanOutput = span.output;
+// ---- Test: Span.toJSON() returns object ----
+const spanJson = span.toJSON();
+// ---- Test: Trace.end() ----
+trace.end({
+    status: "completed",
+    output: "Final answer about weather",
+});
+// ---- Test: traceGeneration convenience method ----
+async function testTraceGeneration() {
+    const result = await client.traceGeneration({
+        name: "simple-generation",
+        model: "gpt-4o",
+        provider: "openai",
+        input: "Hello",
+    }, async (span) => {
+        // Do LLM call
+        span.end({
+            inputTokens: 10,
+            outputTokens: 5,
+            cost: 0.001,
+            status: "ok",
+            output: "Hi!",
+        });
+        return "Hi!";
+    });
+    // result should be the return value of the callback
+    const output = result;
+}
+// ---- Test: TraceGenerationOptions has correct shape ----
+async function testTraceGenerationMinimal() {
+    const result = await client.traceGeneration({
+        name: "minimal-gen",
+        input: "test",
+    }, async (span) => {
+        span.end({ status: "ok" });
+        return 42;
+    });
+    const num = result;
+}
+// ---- Test: flush() still works (backward compat) ----
+async function testFlush() {
+    await client.flush();
+}
+// ---- Test: close() still works (backward compat) ----
+async function testClose() {
+    await client.close();
+}
+// ---- Test: Error tracking still works (backward compat) ----
+function testErrorTracking() {
+    client.captureError(new Error("test error"), { route: "/api/test" });
+    client.capture({
+        errorType: "TestError",
+        message: "test message",
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bloop-sdk",
-  "version": "0.2.0",
-  "description": "Lightweight error reporting SDK for bloop",
+  "version": "0.3.0",
+  "description": "Lightweight error reporting and LLM tracing SDK for bloop",
   "main": "dist/bloop.js",
   "types": "dist/bloop.d.ts",
   "files": ["dist"],
@@ -9,7 +9,7 @@
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["error-tracking", "observability", "bloop"],
+  "keywords": ["error-tracking", "observability", "llm-tracing", "bloop"],
   "license": "MIT",
   "repository": {
     "type": "git",