@dthink/bloop-sdk 0.4.0

package/dist/client.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Bloop error reporting and LLM tracing client for TypeScript/Node.js.
+ * Zero external dependencies.
+ */
+export interface BloopClientOptions {
+    endpoint: string;
+    projectKey: string;
+    flushInterval?: number;
+    maxBufferSize?: number;
+    environment?: string;
+    release?: string;
+}
+export interface SpanData {
+    id: string;
+    span_type: string;
+    name: string;
+    model?: string;
+    provider?: string;
+    parent_span_id?: string;
+    input_tokens: number;
+    output_tokens: number;
+    cost: number;
+    latency_ms: number;
+    time_to_first_token_ms?: number;
+    status: string;
+    error_message?: string;
+    input?: string;
+    output?: string;
+    metadata?: Record<string, unknown>;
+    started_at: number;
+    ended_at?: number;
+}
+export interface TraceData {
+    id: string;
+    name: string;
+    status: string;
+    session_id?: string;
+    user_id?: string;
+    input?: string;
+    output?: string;
+    metadata?: Record<string, unknown>;
+    prompt_name?: string;
+    prompt_version?: string;
+    started_at: number;
+    ended_at?: number;
+    spans: SpanData[];
+}
+export declare class BloopClient {
+    private endpoint;
+    private projectKey;
+    private flushInterval;
+    private maxBufferSize;
+    private environment;
+    private release;
+    private errorBuffer;
+    private traceBuffer;
+    private timer;
+    private closed;
+    constructor(options: BloopClientOptions);
+    capture(params: {
+        errorType: string;
+        message: string;
+        source?: string;
+        stack?: string;
+        routeOrProcedure?: string;
+        screen?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    trace(options?: {
+        name?: string;
+        traceId?: string;
+        sessionId?: string;
+        userId?: string;
+        promptName?: string;
+        promptVersion?: string;
+    }): Trace;
+    /** @internal */
+    _sendTrace(data: TraceData): void;
+    wrapOpenAI<T>(openaiClient: T): T;
+    wrapAnthropic<T>(anthropicClient: T): T;
+    flush(): void;
+    close(): void;
+    private _flushErrors;
+    private _flushTraces;
+    private _post;
+}
+export declare class Trace {
+    readonly id: string;
+    name: string;
+    status: string;
+    sessionId?: string;
+    userId?: string;
+    input?: string;
+    output?: string;
+    metadata?: Record<string, unknown>;
+    promptName?: string;
+    promptVersion?: string;
+    private client;
+    private spans;
+    private startedAt;
+    private endedAt?;
+    constructor(client: BloopClient, options: {
+        name: string;
+        traceId: string;
+        sessionId?: string;
+        userId?: string;
+        promptName?: string;
+        promptVersion?: string;
+    });
+    span(options?: {
+        spanType?: string;
+        name?: string;
+        model?: string;
+        provider?: string;
+        parentSpanId?: string;
+    }): Span;
+    /** @internal */
+    _addSpan(data: SpanData): void;
+    end(): void;
+}
+export declare class Span {
+    readonly id: string;
+    spanType: string;
+    name: string;
+    model?: string;
+    provider?: string;
+    parentSpanId?: string;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    latencyMs: number;
+    timeToFirstTokenMs?: number;
+    status: string;
+    errorMessage?: string;
+    input?: string;
+    output?: string;
+    metadata?: Record<string, unknown>;
+    private trace;
+    private startedAt;
+    constructor(trace: Trace, options: {
+        spanType: string;
+        name: string;
+        model?: string;
+        provider?: string;
+        parentSpanId?: string;
+    });
+    setTokens(inputTokens: number, outputTokens: number): void;
+    setCost(cost: number): void;
+    setLatency(latencyMs: number, timeToFirstTokenMs?: number): void;
+    setError(message: string): void;
+    end(): void;
+}

package/dist/client.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * Bloop error reporting and LLM tracing client for TypeScript/Node.js.
+ * Zero external dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Span = exports.Trace = exports.BloopClient = void 0;
+const node_crypto_1 = require("node:crypto");
+class BloopClient {
+    endpoint;
+    projectKey;
+    flushInterval;
+    maxBufferSize;
+    environment;
+    release;
+    errorBuffer = [];
+    traceBuffer = [];
+    timer = null;
+    closed = false;
+    constructor(options) {
+        this.endpoint = options.endpoint.replace(/\/+$/, "");
+        this.projectKey = options.projectKey;
+        this.flushInterval = options.flushInterval ?? 5000;
+        this.maxBufferSize = options.maxBufferSize ?? 100;
+        this.environment = options.environment ?? "production";
+        this.release = options.release ?? "";
+        this.timer = setInterval(() => this.flush(), this.flushInterval);
+        if (this.timer.unref)
+            this.timer.unref();
+    }
+    // ── Error Tracking ──
+    capture(params) {
+        this.errorBuffer.push({
+            timestamp: Math.floor(Date.now() / 1000),
+            source: params.source ?? "javascript",
+            environment: this.environment,
+            release: this.release,
+            error_type: params.errorType,
+            message: params.message,
+            stack: params.stack ?? "",
+            route_or_procedure: params.routeOrProcedure ?? "",
+            screen: params.screen ?? "",
+            metadata: params.metadata ?? {},
+        });
+        if (this.errorBuffer.length >= this.maxBufferSize) {
+            this.flush();
+        }
+    }
+    // ── LLM Tracing ──
+    trace(options = {}) {
+        return new Trace(this, {
+            name: options.name ?? "",
+            traceId: options.traceId ?? (0, node_crypto_1.randomUUID)().replace(/-/g, ""),
+            sessionId: options.sessionId,
+            userId: options.userId,
+            promptName: options.promptName,
+            promptVersion: options.promptVersion,
+        });
+    }
+    /** @internal */
+    _sendTrace(data) {
+        this.traceBuffer.push(data);
+        if (this.traceBuffer.length >= 10) {
+            this._flushTraces();
+        }
+    }
+    // ── Auto-Instrumentation ──
+    wrapOpenAI(openaiClient) {
+        const { wrapOpenAI } = require("./integrations/openai");
+        return wrapOpenAI(openaiClient, this);
+    }
+    wrapAnthropic(anthropicClient) {
+        const { wrapAnthropic } = require("./integrations/anthropic");
+        return wrapAnthropic(anthropicClient, this);
+    }
+    // ── Flush & Transport ──
+    flush() {
+        this._flushErrors();
+        this._flushTraces();
+    }
+    close() {
+        this.closed = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.flush();
+    }
+    _flushErrors() {
+        if (this.errorBuffer.length === 0)
+            return;
+        const events = [...this.errorBuffer];
+        this.errorBuffer = [];
+        if (events.length === 1) {
+            this._post("/v1/ingest", events[0]);
+        }
+        else {
+            this._post("/v1/ingest/batch", { events });
+        }
+    }
+    _flushTraces() {
+        if (this.traceBuffer.length === 0)
+            return;
+        const traces = [...this.traceBuffer];
+        this.traceBuffer = [];
+        this._post("/v1/traces/batch", { traces }).catch(() => { });
+    }
+    async _post(path, payload) {
+        const body = JSON.stringify(payload);
+        const sig = (0, node_crypto_1.createHmac)("sha256", this.projectKey)
+            .update(body)
+            .digest("hex");
+        try {
+            await fetch(`${this.endpoint}${path}`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Signature": sig,
+                },
+                body,
+            });
+        }
+        catch {
+            // Silently drop on failure (never crash the app)
+        }
+    }
+}
+exports.BloopClient = BloopClient;
+class Trace {
+    id;
+    name;
+    status = "completed";
+    sessionId;
+    userId;
+    input;
+    output;
+    metadata;
+    promptName;
+    promptVersion;
+    client;
+    spans = [];
+    startedAt;
+    endedAt;
+    constructor(client, options) {
+        this.client = client;
+        this.id = options.traceId;
+        this.name = options.name;
+        this.sessionId = options.sessionId;
+        this.userId = options.userId;
+        this.promptName = options.promptName;
+        this.promptVersion = options.promptVersion;
+        this.startedAt = Date.now();
+    }
+    span(options = {}) {
+        return new Span(this, {
+            spanType: options.spanType ?? "generation",
+            name: options.name ?? "",
+            model: options.model,
+            provider: options.provider,
+            parentSpanId: options.parentSpanId,
+        });
+    }
+    /** @internal */
+    _addSpan(data) {
+        this.spans.push(data);
+    }
+    end() {
+        this.endedAt = Date.now();
+        const data = {
+            id: this.id,
+            name: this.name,
+            status: this.status,
+            started_at: this.startedAt,
+            ended_at: this.endedAt,
+            spans: this.spans,
+        };
+        if (this.sessionId)
+            data.session_id = this.sessionId;
+        if (this.userId)
+            data.user_id = this.userId;
+        if (this.input !== undefined)
+            data.input = this.input;
+        if (this.output !== undefined)
+            data.output = this.output;
+        if (this.metadata)
+            data.metadata = this.metadata;
+        if (this.promptName)
+            data.prompt_name = this.promptName;
+        if (this.promptVersion)
+            data.prompt_version = this.promptVersion;
+        this.client._sendTrace(data);
+    }
+}
+exports.Trace = Trace;
+class Span {
+    id;
+    spanType;
+    name;
+    model;
+    provider;
+    parentSpanId;
+    inputTokens = 0;
+    outputTokens = 0;
+    cost = 0;
+    latencyMs = 0;
+    timeToFirstTokenMs;
+    status = "ok";
+    errorMessage;
+    input;
+    output;
+    metadata;
+    trace;
+    startedAt;
+    constructor(trace, options) {
+        this.trace = trace;
+        this.id = (0, node_crypto_1.randomUUID)().replace(/-/g, "");
+        this.spanType = options.spanType;
+        this.name = options.name;
+        this.model = options.model;
+        this.provider = options.provider;
+        this.parentSpanId = options.parentSpanId;
+        this.startedAt = Date.now();
+    }
+    setTokens(inputTokens, outputTokens) {
+        this.inputTokens = inputTokens;
+        this.outputTokens = outputTokens;
+    }
+    setCost(cost) {
+        this.cost = cost;
+    }
+    setLatency(latencyMs, timeToFirstTokenMs) {
+        this.latencyMs = latencyMs;
+        this.timeToFirstTokenMs = timeToFirstTokenMs;
+    }
+    setError(message) {
+        this.status = "error";
+        this.errorMessage = message;
+    }
+    end() {
+        const endedAt = Date.now();
+        if (this.latencyMs === 0) {
+            this.latencyMs = endedAt - this.startedAt;
+        }
+        const data = {
+            id: this.id,
+            span_type: this.spanType,
+            name: this.name,
+            input_tokens: this.inputTokens,
+            output_tokens: this.outputTokens,
+            cost: this.cost,
+            latency_ms: this.latencyMs,
+            status: this.status,
+            started_at: this.startedAt,
+            ended_at: endedAt,
+        };
+        if (this.model)
+            data.model = this.model;
+        if (this.provider)
+            data.provider = this.provider;
+        if (this.parentSpanId)
+            data.parent_span_id = this.parentSpanId;
+        if (this.timeToFirstTokenMs !== undefined)
+            data.time_to_first_token_ms = this.timeToFirstTokenMs;
+        if (this.errorMessage)
+            data.error_message = this.errorMessage;
+        if (this.input !== undefined)
+            data.input = this.input;
+        if (this.output !== undefined)
+            data.output = this.output;
+        if (this.metadata)
+            data.metadata = this.metadata;
+        this.trace._addSpan(data);
+    }
+}
+exports.Span = Span;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { BloopClient, Trace, Span } from "./client";
+export type { BloopClientOptions, TraceData, SpanData } from "./client";
+export { wrapOpenAI } from "./integrations/openai";
+export { wrapAnthropic } from "./integrations/anthropic";

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapAnthropic = exports.wrapOpenAI = exports.Span = exports.Trace = exports.BloopClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "BloopClient", { enumerable: true, get: function () { return client_1.BloopClient; } });
+Object.defineProperty(exports, "Trace", { enumerable: true, get: function () { return client_1.Trace; } });
+Object.defineProperty(exports, "Span", { enumerable: true, get: function () { return client_1.Span; } });
+var openai_1 = require("./integrations/openai");
+Object.defineProperty(exports, "wrapOpenAI", { enumerable: true, get: function () { return openai_1.wrapOpenAI; } });
+var anthropic_1 = require("./integrations/anthropic");
+Object.defineProperty(exports, "wrapAnthropic", { enumerable: true, get: function () { return anthropic_1.wrapAnthropic; } });

package/dist/integrations/anthropic.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Anthropic auto-instrumentation for bloop LLM tracing.
+ *
+ * Wraps `messages.create()` to automatically capture:
+ * - Model, tokens, latency, TTFT (streaming), errors
+ * - Cost is always 0 -- calculated server-side from pricing table
+ */
+import type { BloopClient } from "../client";
+export declare function wrapAnthropic<T>(anthropicClient: T, bloopClient: BloopClient): T;

package/dist/integrations/anthropic.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Anthropic auto-instrumentation for bloop LLM tracing.
+ *
+ * Wraps `messages.create()` to automatically capture:
+ * - Model, tokens, latency, TTFT (streaming), errors
+ * - Cost is always 0 -- calculated server-side from pricing table
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapAnthropic = wrapAnthropic;
+function detectProvider(client) {
+    try {
+        const baseUrl = String(client.baseURL || client._baseURL || "");
+        if (baseUrl.includes("anthropic.com"))
+            return "anthropic";
+        const url = new URL(baseUrl);
+        return url.hostname.split(".")[0] || "anthropic";
+    }
+    catch {
+        return "anthropic";
+    }
+}
+function wrapAnthropic(anthropicClient, bloopClient) {
+    const client = anthropicClient;
+    const provider = detectProvider(client);
+    const originalCreate = client.messages.create.bind(client.messages);
+    client.messages.create = function tracedCreate(...args) {
+        const params = args[0] || {};
+        const model = params.model || "unknown";
+        const stream = params.stream || false;
+        const startMs = Date.now();
+        const trace = bloopClient.trace({ name: `${provider}/${model}` });
+        const span = trace.span({
+            spanType: "generation",
+            name: "messages.create",
+            model,
+            provider,
+        });
+        if (stream) {
+            return handleStreaming(originalCreate, args, trace, span, startMs, model);
+        }
+        return originalCreate(...args).then((response) => {
+            const endMs = Date.now();
+            const usage = response?.usage;
+            if (usage) {
+                span.setTokens(usage.input_tokens || 0, usage.output_tokens || 0);
+            }
+            span.setLatency(endMs - startMs);
+            span.cost = 0; // Server-side pricing
+            span.model = response?.model || model;
+            span.end();
+            trace.end();
+            return response;
+        }, (err) => {
+            const endMs = Date.now();
+            span.setLatency(endMs - startMs);
+            span.setError(err.message);
+            span.end();
+            trace.status = "error";
+            trace.end();
+            throw err;
+        });
+    };
+    return anthropicClient;
+}
+async function* handleStreaming(originalCreate, args, trace, span, startMs, model) {
+    let firstTokenSeen = false;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let resolvedModel = model;
+    try {
+        const stream = await originalCreate(...args);
+        for await (const event of stream) {
+            const eventType = event?.type || "";
+            if (!firstTokenSeen && eventType === "content_block_delta") {
+                firstTokenSeen = true;
+                span.timeToFirstTokenMs = Date.now() - startMs;
+            }
+            // Track usage from message_start event
+            if (eventType === "message_start" && event.message) {
+                resolvedModel = event.message.model || resolvedModel;
+                if (event.message.usage) {
+                    inputTokens = event.message.usage.input_tokens || 0;
+                }
+            }
+            // Track output tokens from message_delta event
+            if (eventType === "message_delta" && event.usage) {
+                outputTokens = event.usage.output_tokens || 0;
+            }
+            yield event;
+        }
+        const endMs = Date.now();
+        span.setTokens(inputTokens, outputTokens);
+        span.setLatency(endMs - startMs);
+        span.cost = 0;
+        span.model = resolvedModel;
+        span.end();
+        trace.end();
+    }
+    catch (err) {
+        const endMs = Date.now();
+        span.setTokens(inputTokens, outputTokens);
+        span.setLatency(endMs - startMs);
+        span.setError(err.message);
+        span.end();
+        trace.status = "error";
+        trace.end();
+        throw err;
+    }
+}

package/dist/integrations/index.d.ts

@@ -0,0 +1,2 @@
+export { wrapOpenAI } from "./openai";
+export { wrapAnthropic } from "./anthropic";

package/dist/integrations/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapAnthropic = exports.wrapOpenAI = void 0;
+var openai_1 = require("./openai");
+Object.defineProperty(exports, "wrapOpenAI", { enumerable: true, get: function () { return openai_1.wrapOpenAI; } });
+var anthropic_1 = require("./anthropic");
+Object.defineProperty(exports, "wrapAnthropic", { enumerable: true, get: function () { return anthropic_1.wrapAnthropic; } });

package/dist/integrations/openai.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OpenAI auto-instrumentation for bloop LLM tracing.
+ *
+ * Wraps `chat.completions.create()` to automatically capture:
+ * - Model, tokens, latency, TTFT (streaming), errors
+ * - Cost is always 0 -- calculated server-side from pricing table
+ */
+import type { BloopClient } from "../client";
+export declare function wrapOpenAI<T>(openaiClient: T, bloopClient: BloopClient): T;

package/dist/integrations/openai.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * OpenAI auto-instrumentation for bloop LLM tracing.
+ *
+ * Wraps `chat.completions.create()` to automatically capture:
+ * - Model, tokens, latency, TTFT (streaming), errors
+ * - Cost is always 0 -- calculated server-side from pricing table
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapOpenAI = wrapOpenAI;
+const PROVIDER_MAP = {
+    "api.openai.com": "openai",
+    "api.minimax.io": "minimax",
+    "api.moonshot.ai": "kimi",
+    "generativelanguage.googleapis.com": "google",
+};
+function detectProvider(client) {
+    try {
+        const baseUrl = String(client.baseURL || "");
+        for (const [domain, provider] of Object.entries(PROVIDER_MAP)) {
+            if (baseUrl.includes(domain))
+                return provider;
+        }
+        const url = new URL(baseUrl);
+        return url.hostname.split(".")[0] || "openai";
+    }
+    catch {
+        return "openai";
+    }
+}
+function wrapOpenAI(openaiClient, bloopClient) {
+    const client = openaiClient;
+    const provider = detectProvider(client);
+    const originalCreate = client.chat.completions.create.bind(client.chat.completions);
+    client.chat.completions.create = function tracedCreate(...args) {
+        const params = args[0] || {};
+        const model = params.model || "unknown";
+        const stream = params.stream || false;
+        const startMs = Date.now();
+        const trace = bloopClient.trace({ name: `${provider}/${model}` });
+        const span = trace.span({
+            spanType: "generation",
+            name: "chat.completions.create",
+            model,
+            provider,
+        });
+        if (stream) {
+            return handleStreaming(originalCreate, args, trace, span, startMs, model);
+        }
+        return originalCreate(...args).then((response) => {
+            const endMs = Date.now();
+            const usage = response?.usage;
+            if (usage) {
+                span.setTokens(usage.prompt_tokens || 0, usage.completion_tokens || 0);
+            }
+            span.setLatency(endMs - startMs);
+            span.cost = 0; // Server-side pricing
+            span.model = response?.model || model;
+            span.end();
+            trace.end();
+            return response;
+        }, (err) => {
+            const endMs = Date.now();
+            span.setLatency(endMs - startMs);
+            span.setError(err.message);
+            span.end();
+            trace.status = "error";
+            trace.end();
+            throw err;
+        });
+    };
+    return openaiClient;
+}
+async function* handleStreaming(originalCreate, args, trace, span, startMs, model) {
+    let firstTokenSeen = false;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let resolvedModel = model;
+    try {
+        const stream = await originalCreate(...args);
+        for await (const chunk of stream) {
+            if (!firstTokenSeen) {
+                firstTokenSeen = true;
+                span.timeToFirstTokenMs = Date.now() - startMs;
+            }
+            if (chunk.model)
+                resolvedModel = chunk.model;
+            // Track usage from final chunk (OpenAI includes it with stream_options)
+            if (chunk.usage) {
+                inputTokens = chunk.usage.prompt_tokens || 0;
+                outputTokens = chunk.usage.completion_tokens || 0;
+            }
+            yield chunk;
+        }
+        const endMs = Date.now();
+        span.setTokens(inputTokens, outputTokens);
+        span.setLatency(endMs - startMs);
+        span.cost = 0;
+        span.model = resolvedModel;
+        span.end();
+        trace.end();
+    }
+    catch (err) {
+        const endMs = Date.now();
+        span.setTokens(inputTokens, outputTokens);
+        span.setLatency(endMs - startMs);
+        span.setError(err.message);
+        span.end();
+        trace.status = "error";
+        trace.end();
+        throw err;
+    }
+}