0xtrace 1.0.3 → 1.0.5

package/dist/core/dispatcher.d.ts

@@ -0,0 +1,57 @@
+import type { IDispatcher, TracePayload } from "./types";
+export interface DispatcherOptions {
+    ingestUrl: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    onError?: (error: Error, payloads: TracePayload[]) => void;
+}
+export declare class Dispatcher implements IDispatcher {
+    private readonly ingestUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly batchSize;
+    private readonly onError;
+    /** The in-memory buffer accumulating payloads between flushes. */
+    private buffer;
+    /** The NodeJS/browser timer handle for the periodic flush. */
+    private flushTimer;
+    /** Tracks all in-flight fetch Promises so flush() can await them. */
+    private inFlight;
+    constructor(opts: DispatcherOptions);
+    /**
+     * Accepts a payload and schedules delivery non-blocking via the microtask
+     * queue. The caller returns immediately; the POST happens asynchronously.
+     */
+    send(payload: TracePayload): void;
+    /**
+     * Waits for all in-flight requests and flushes any remaining buffered
+     * payloads. Call this in tests or on process shutdown.
+     *
+     * @example
+     * process.on('SIGTERM', () => tracer.flush());
+     */
+    flush(): Promise<void>;
+    /**
+     * Stops the periodic flush timer and flushes remaining payloads.
+     * Call when the Tracer instance is being torn down.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Atomically snapshots and clears the buffer, then initiates an async
+     * POST. Multiple concurrent drains are safe — each works on its own slice.
+     */
+    private _drainBuffer;
+    /**
+     * Attempts to POST a batch to the ingest endpoint.
+     * Retries up to MAX_RETRY_ATTEMPTS times with exponential back-off.
+     * Only retries on network errors or 5xx responses.
+     */
+    private _sendWithRetry;
+    /**
+     * Performs the raw HTTP POST with an AbortController timeout.
+     * Throws on network failure or non-2xx status.
+     */
+    private _post;
+}

package/dist/core/tracer.d.ts

@@ -0,0 +1,55 @@
+import type { RawCapturePayload, TracerOptions, IDispatcher } from "./types";
+export declare class Tracer {
+    /** Groups all LLM calls in this agent run. */
+    readonly sessionId: string;
+    /** Caller-supplied arbitrary metadata attached to every payload. */
+    private readonly metadata;
+    /** Whether telemetry is active (can be disabled via options). */
+    private readonly enabled;
+    /** Delivery engine — injectable for unit-testing. */
+    private readonly dispatcher;
+    /**
+     * Monotonically increasing step counter.
+     * Step 1 → first call in the session (triggers full snapshot in the DB).
+     * Step N → subsequent calls (store diff only).
+     */
+    private stepCounter;
+    constructor(opts: TracerOptions, dispatcher?: IDispatcher);
+    /**
+     * The method called by every SDK wrapper after intercepting an LLM call.
+     *
+     * Design contract:
+     *   - NEVER awaited by the wrapper; fire-and-forget on microtask queue.
+     *   - Returns void so the wrapper cannot accidentally `await` it.
+     *
+     * @example
+     * // Inside wrappers/openai.ts — after receiving the result:
+     * tracer.captureAsync({ prompt, response, model, tokensIn, tokensOut, latencyMs, isStream });
+     */
+    captureAsync(raw: RawCapturePayload): void;
+    /**
+     * Returns the step index the *next* call will be assigned.
+     * Useful for callers who need to know if this is step 1 (full snapshot)
+     * vs. a later step (diff only) before making the LLM call.
+     */
+    get nextStepIndex(): number;
+    /**
+     * Waits for all buffered and in-flight payloads to be delivered.
+     * Call before process exit or at the end of integration tests.
+     *
+     * @example
+     * afterAll(async () => { await tracer.flush(); });
+     */
+    flush(): Promise<void>;
+    /**
+     * Takes a raw capture from the wrapper and enriches it with:
+     *   - a unique callId
+     *   - the session's sessionId
+     *   - a monotonic stepIndex
+     *   - ISO-8601 timestamp
+     *   - USD cost estimate
+     *   - SDK version string
+     *   - caller metadata
+     */
+    private _enrich;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,64 @@
+/** A single message in an OpenAI-compatible chat conversation. */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool" | "function";
+    content: string | null;
+    name?: string;
+    tool_call_id?: string;
+}
+/** Raw data captured at the intercept point, before any enrichment. */
+export interface RawCapturePayload {
+    /** The messages array sent to the model. */
+    prompt: ChatMessage[] | readonly ChatMessage[];
+    /** The text content of the completion (reconstructed for streams). */
+    response: string;
+    /** Model string exactly as passed by the caller e.g. "gpt-4o". */
+    model: string;
+    /** Prompt tokens from usage object. Undefined for streams (not available). */
+    tokensIn: number | undefined;
+    /** Completion tokens. For streams this is an approximation (chunk count). */
+    tokensOut: number | undefined;
+    /** Wall-clock ms from request start to last byte received. */
+    latencyMs: number;
+    /** Whether the call used server-sent streaming. */
+    isStream: boolean;
+}
+/** The fully enriched payload that gets pushed to the ingest queue. */
+export interface TracePayload extends RawCapturePayload {
+    /** SDK-generated UUID for this individual LLM call. */
+    callId: string;
+    /** Session/trace ID grouping multiple calls in one agent run.
+     *  Set via TracerOptions.sessionId or auto-generated per Tracer instance. */
+    sessionId: string;
+    /** Step index within the session (1-based, incremented per capture). */
+    stepIndex: number;
+    /** ISO-8601 timestamp of the call start. */
+    timestamp: string;
+    /** Estimated USD cost for this call. */
+    estimatedCostUsd: number;
+    /** Version string of the SDK emitting this payload. */
+    sdkVersion: string;
+}
+/** Options passed when constructing a Tracer instance. */
+export interface TracerOptions {
+    /** Full URL of your Next.js ingest endpoint.
+     *  e.g. "https://your-app.vercel.app/api/ingest" */
+    ingestUrl: string;
+    apiKey?: string;
+    /** Optional session ID to group multiple calls into one trace. If omitted,
+    /** Groups multiple LLM calls into one logical agent run.
+     *  Auto-generated (UUID v4) if omitted. */
+    sessionId?: string;
+    /** Attach arbitrary key/value metadata to every payload (e.g. userId, env). */
+    metadata?: Record<string, string>;
+    /** Max ms to wait for the ingest POST before aborting. Default: 5000. */
+    timeoutMs?: number;
+    /** Called when the ingest POST fails. Defaults to console.warn. */
+    onError?: (error: Error, payload: TracePayload) => void;
+    /** Set false to completely disable telemetry (e.g. in unit tests). Default: true */
+    enabled?: boolean;
+}
+/** Minimal interface the Dispatcher must satisfy — useful for testing. */
+export interface IDispatcher {
+    send(payload: TracePayload): void;
+    flush(): Promise<void>;
+}

package/dist/diff.d.ts

@@ -0,0 +1,74 @@
+import type { ChatMessage } from "./core/types";
+/** A single entry in the diff — describes ONE message's change. */
+export type DiffOperation = {
+    op: "add";
+    index: number;
+    message: ChatMessage;
+} | {
+    op: "remove";
+    index: number;
+} | {
+    op: "keep";
+    index: number;
+};
+/** The payload stored in prompt_snapshots.diff_from_previous */
+export interface MessageDiff {
+    /** Only the add/remove operations (keeps are omitted to save bytes). */
+    operations: Array<{
+        op: "add";
+        index: number;
+        message: ChatMessage;
+    } | {
+        op: "remove";
+        index: number;
+    }>;
+    /** Net token change: positive = context grew, negative = messages pruned. */
+    tokenDelta: number;
+    /** How many messages were added in this step. */
+    added: number;
+    /** How many messages were removed in this step. */
+    removed: number;
+}
+/**
+ * Rough token estimator — 1 token ≈ 4 characters (GPT rule of thumb).
+ * The SDK does not run a full tokenizer to stay dependency-free.
+ * The backend can re-calculate with tiktoken if needed.
+ */
+export declare function estimateTokens(messages: readonly ChatMessage[]): number;
+/**
+ * Computes the minimal diff between `prev` and `curr` message arrays.
+ *
+ * Algorithm: O(n) two-pointer walk.
+ *   1. Build a Set of keys in `prev` for O(1) lookup.
+ *   2. Walk `curr` — any message not in `prev` is an ADD.
+ *   3. Walk `prev` — any message not in `curr` is a REMOVE.
+ *
+ * This is sufficient for 99% of real agent patterns where the context
+ * array only ever has messages appended (never reordered mid-stream).
+ * For adversarial reordering, swap to Myers diff.
+ *
+ * @example
+ * const diff = computeMessageDiff(step1Messages, step2Messages);
+ * // { operations: [{ op: "add", index: 3, message: {...} }], tokenDelta: 42, added: 1, removed: 0 }
+ */
+export declare function computeMessageDiff(prev: readonly ChatMessage[], curr: readonly ChatMessage[]): MessageDiff;
+/**
+ * Applies a stored diff forward onto a base message array.
+ * The frontend calls this to reconstruct the full message array for step N:
+ *
+ *   const step1 = fullSnapshot;           // stored in DB for step 1
+ *   const step2 = applyDiff(step1, diff); // reconstructed from diff
+ *   const step3 = applyDiff(step2, diff); // and so on...
+ *
+ * @throws {Error} if the diff references an out-of-bounds index.
+ */
+export declare function applyDiff(base: readonly ChatMessage[], diff: MessageDiff): ChatMessage[];
+/**
+ * Replays an ordered series of diffs from a base snapshot.
+ * Use this when you need to reconstruct every step in a session at once.
+ *
+ * @example
+ * const steps = replayDiffs(step1Snapshot, [diff2, diff3, diff4]);
+ * // steps[0] === step1, steps[1] === step2, steps[2] === step3, steps[3] === step4
+ */
+export declare function replayDiffs(baseSnapshot: readonly ChatMessage[], diffs: MessageDiff[]): ChatMessage[][];

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Tracer } from "./core/tracer";
+export { Dispatcher } from "./core/dispatcher";
+export { wrapOpenAI } from "./wrappers/openai";
+export { calcCostUsd, formatCostUsd } from "./utils/cost";
+export type { ChatMessage, RawCapturePayload, TracePayload, TracerOptions, IDispatcher, } from "./core/types";
+export type { DispatcherOptions } from "./core/dispatcher";

package/dist/utils/cost.d.ts

@@ -0,0 +1,21 @@
+export interface CalcCostParams {
+    model: string;
+    tokensIn: number;
+    tokensOut: number;
+}
+/**
+ * Returns the estimated USD cost for a single LLM call.
+ * Returns 0 for unrecognised models rather than throwing, so the SDK
+ * never crashes user code due to a missing pricing entry.
+ *
+ * @example
+ * calcCostUsd({ model: "gpt-4o", tokensIn: 1000, tokensOut: 500 })
+ * // → 0.00750
+ */
+export declare function calcCostUsd({ model, tokensIn, tokensOut }: CalcCostParams): number;
+/**
+ * Formats a USD cost as a human-readable string.
+ * @example formatCost(0.0075) → "$0.0075"
+ * @example formatCost(0.00000120) → "$0.0000012"
+ */
+export declare function formatCostUsd(usd: number): string;

package/dist/wrappers/openai.d.ts

@@ -0,0 +1,21 @@
+import OpenAI from "openai";
+import type { Tracer } from "../core/tracer";
+/**
+ * Wraps an OpenAI client with a transparent telemetry layer.
+ *
+ * @param client  The original `new OpenAI(...)` instance.
+ * @param tracer  A configured `Tracer` instance (owns the session + dispatch).
+ * @returns       A Proxy of the client — drop-in replacement, same types.
+ *
+ * @example
+ * import OpenAI from "openai";
+ * import { Tracer, wrapOpenAI } from "@prompt-tracer/sdk";
+ *
+ * const openai  = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+ * const tracer  = new Tracer({ ingestUrl: "https://your-app.com/api/ingest" });
+ * const ai      = wrapOpenAI(openai, tracer);
+ *
+ * // Use exactly like the original client — streaming, tools, everything works.
+ * const res = await ai.chat.completions.create({ model: "gpt-4o", messages });
+ */
+export declare function wrapOpenAI(client: OpenAI, tracer: Tracer): OpenAI;

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "0xtrace",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Proxy-based LLM telemetry SDK for 0xtrace",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     }
@@ -15,7 +17,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup"
+    "build": "tsup && tsc --project tsconfig.build.json"
   },
   "dependencies": {
     "diff": "^9.0.0",