@spendgraph/sdk 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# @spendgraph/sdk
+
+Track what your LLM calls cost. Three functions, zero dependencies, fail-open.
+
+Tracking must never be the reason a request fails, so every path here is
+non-blocking and swallows its own errors: `track()` returns `void`, network
+failures retry once and then drop with a warning, and nothing throws into your
+handler.
+
+```bash
+npm install @spendgraph/sdk
+```
+
+## Wrap a client
+
+The shortest path — no per-call code, and streaming, cache tokens and OpenAI
+clients are all handled:
+
+```ts
+import { SpendGraph } from "@spendgraph/sdk";
+import Anthropic from "@anthropic-ai/sdk";
+
+const meter = new SpendGraph({
+  apiKey: process.env.SPENDGRAPH_API_KEY,
+  baseUrl: "https://your-spendgraph.example.com",
+});
+
+const anthropic = meter.wrap(new Anthropic());
+```
+
+## Track a call yourself
+
+```ts
+meter.track({
+  model: "claude-sonnet-4-5",
+  inputTokens: 3211,        // fresh tokens only
+  outputTokens: 842,
+  cacheReadTokens: 18004,   // from cache_read_input_tokens
+  cacheWriteTokens: 3211,   // from cache_creation_input_tokens
+  metadata: { feature: "chat", env: "prod" },
+});
+```
+
+**The three token counts are disjoint.** Providers report them that way —
+Anthropic's total input is `input + cache_read + cache_creation` — and spendgraph
+prices them the same way. Do not fold cache tokens into `inputTokens` as well:
+that bills the same tokens twice, at the wrong rate. Omitting them loses the
+spend entirely.
+
+## Serverless
+
+Events batch in memory and flush every 5s or 20 events. Serverless platforms
+suspend a function once it returns rather than exiting it, so neither the timer
+nor `beforeExit` runs — **await `flush()` before your handler returns**:
+
+```ts
+export async function handler(event) {
+  const result = await callTheModel(event);
+  await meter.flush();
+  return result;
+}
+```
+
+If a flush is ever stranded that way, the SDK notices on the next invocation,
+sends the stragglers, and warns once explaining the fix.
+
+## Other integrations
+
+```ts
+import { spendGraphHandler } from "@spendgraph/sdk/langchain";
+await graph.invoke(state, { callbacks: [spendGraphHandler(meter)] });
+
+import { trackAiResult } from "@spendgraph/sdk/ai";
+trackAiResult(meter, await generateText({ model, prompt }));
+```
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `apiKey` | — | Without it, `track()` is a no-op |
+| `baseUrl` | — | Your spendgraph deployment |
+| `flushIntervalMs` | `5000` | |
+| `maxBatch` | `20` | Flush once this many events are queued |
+
+## Unpriced models
+
+The ingest response returns any model id it could not price in
+`unpricedModels`, and the SDK logs each one once:
+
+> `spendgraph: no price for "gpt-5-turbo". These events are recorded but cost $0
+> until the model is in the catalog.`
+
+Events are always stored — an unrecognised id is a mapping problem, not bad
+data — so the tokens survive and only the cost is missing until the catalog
+learns the model.
+
+## License
+
+MIT

package/dist/ai.d.ts

@@ -0,0 +1,32 @@
+import type { SpendGraph } from "./index.js";
+type AiUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    promptTokens?: number;
+    completionTokens?: number;
+};
+type AiResult = {
+    usage?: AiUsage;
+    totalUsage?: AiUsage;
+    response?: {
+        modelId?: string;
+        model?: string;
+    };
+    modelId?: string;
+};
+/**
+ * Track a Vercel AI SDK result:
+ *
+ *   const result = await generateText({ model: anthropic("claude-sonnet-5"), ... });
+ *   trackAiResult(meter, result);
+ *
+ *   streamText({ model, prompt, onFinish: (r) => trackAiResult(meter, r) });
+ *
+ * Fail-open: if the shape is unrecognized, nothing is tracked.
+ */
+export declare function trackAiResult(meter: SpendGraph, result: AiResult, options?: {
+    model?: string;
+    metadata?: Record<string, string | number | boolean>;
+}): void;
+export {};

package/dist/ai.js

@@ -0,0 +1,37 @@
+/**
+ * Track a Vercel AI SDK result:
+ *
+ *   const result = await generateText({ model: anthropic("claude-sonnet-5"), ... });
+ *   trackAiResult(meter, result);
+ *
+ *   streamText({ model, prompt, onFinish: (r) => trackAiResult(meter, r) });
+ *
+ * Fail-open: if the shape is unrecognized, nothing is tracked.
+ */
+export function trackAiResult(meter, result, options = {}) {
+    try {
+        const usage = result?.totalUsage ?? result?.usage;
+        let inputTokens = usage?.inputTokens ?? usage?.promptTokens;
+        const outputTokens = usage?.outputTokens ?? usage?.completionTokens;
+        if (typeof inputTokens !== "number" || typeof outputTokens !== "number")
+            return;
+        // v5 inputTokens includes cached tokens — split them out
+        const cacheReadTokens = usage?.cachedInputTokens ?? 0;
+        inputTokens = Math.max(0, inputTokens - cacheReadTokens);
+        const model = options.model ??
+            result?.response?.modelId ??
+            result?.response?.model ??
+            result?.modelId ??
+            "unknown";
+        meter.track({
+            model,
+            inputTokens,
+            outputTokens,
+            cacheReadTokens,
+            metadata: options.metadata,
+        });
+    }
+    catch {
+        /* fail-open */
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+export interface SpendGraphOptions {
+    /** spendgraph API key (sg_…). Without it the SDK is a no-op. */
+    apiKey: string | undefined;
+    /** Base URL of your deployed spendgraph app, e.g. https://costs.yourco.com */
+    baseUrl: string;
+    /** Flush at most this often (ms). Default 5000. */
+    flushIntervalMs?: number;
+    /** Flush when the buffer reaches this size. Default 20. */
+    maxBatch?: number;
+}
+export interface TrackEvent {
+    model: string;
+    /** Uncached input tokens — cache tokens go in the fields below. */
+    inputTokens: number;
+    outputTokens: number;
+    /** Prompt-cache read (hit) tokens, billed at the provider's cache-read rate. */
+    cacheReadTokens?: number;
+    /** Prompt-cache write (creation) tokens. */
+    cacheWriteTokens?: number;
+    /**
+     * Client-side id: retried sends dedupe server-side.
+     * Must be 8–64 characters — shorter ids are rejected with a 422.
+     */
+    eventId?: string;
+    /** ISO timestamp; defaults to server receive time. */
+    timestamp?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * Fire-and-forget token tracking. track() never throws and never blocks;
+ * events batch in memory and flush every 5s or 20 events. Network failures
+ * retry once, then drop with one console.warn — tracking can never break
+ * the host app.
+ */
+export declare class SpendGraph {
+    private readonly opts;
+    private queue;
+    private timer;
+    private warned;
+    /** Events lost in the current run of failures, reset by a successful flush. */
+    private dropped;
+    /** Unpriced model ids already reported, so each is named at most once. */
+    private readonly unpricedSeen;
+    private readonly interval;
+    private readonly maxBatch;
+    /** When the pending flush was scheduled, for the suspend check in track(). */
+    private timerAt;
+    private suspendWarned;
+    private noKeyWarned;
+    constructor(opts: SpendGraphOptions);
+    /** Record one LLM call. Synchronous, returns void, never throws. */
+    track(event: TrackEvent): void;
+    /**
+     * Says once that tracking is off.
+     *
+     * Running without a key stays a no-op on purpose — it keeps spendgraph out of
+     * tests and local runs without branching at every call site. But an unset
+     * SPENDGRAPH_API_KEY is indistinguishable from that choice, and it is the
+     * likeliest reason a fresh integration records nothing at all: the code is
+     * wired up correctly, the dashboard is empty, and nothing anywhere says why.
+     * Every other failure in this class warns once; this was the one that stayed
+     * quiet, which made it the hardest to find.
+     */
+    private warnNoKey;
+    /**
+     * Notices that the runtime froze with events still buffered.
+     *
+     * Serverless platforms suspend a function once it returns rather than
+     * exiting it, so neither the flush timer nor `beforeExit` ever runs and the
+     * queue is lost without a sound — the failure Langfuse documents for Lambda
+     * and Vercel. There is no reliable flag for "am I serverless", but there is
+     * direct evidence: a pending timer whose deadline passed long ago did not
+     * fire, which only happens if the runtime stopped executing between calls.
+     *
+     * Seeing that, send the stragglers now (they survive into this invocation)
+     * and say once what the fix is. Correct callers await flush(), which clears
+     * the timer, so this never fires for them.
+     */
+    private detectSuspendedRuntime;
+    /** Send everything buffered now. Call at the end of serverless handlers. */
+    flush(): Promise<void>;
+    /**
+     * Wrap an Anthropic or OpenAI client. Use the wrapped client exactly as
+     * before — token usage is read off each response and tracked automatically.
+     *
+     * Streaming is covered too:
+     * - helper streams (`anthropic.messages.stream()`,
+     *   `openai.beta.chat.completions.stream()`) are tracked via their
+     *   final-message promise — the stream you get back is untouched;
+     * - raw streams (`create({ stream: true })`) are tee'd: you receive one
+     *   branch, usage is accumulated off the other. For OpenAI raw streams,
+     *   pass `stream_options: { include_usage: true }` or there is no usage
+     *   to read and the call goes untracked.
+     */
+    wrap<T extends object>(client: T): T;
+    private proxy;
+    private observeResult;
+    private interceptStream;
+    /** Accumulate usage off a tee'd SSE branch (Anthropic events / OpenAI chunks). */
+    private consumeStream;
+    private trackFromResponse;
+    private send;
+    /**
+     * Surfaces model ids the server could not price, once each.
+     *
+     * These are accepted and stored, so nothing here is an error — but they cost
+     * $0, and a dashboard reading $0 is indistinguishable from one reading
+     * "nothing happened". Naming the id in the integrator's own console is the
+     * cheapest possible moment to catch a typo or an unmapped model, and the
+     * per-id guard keeps a steady stream of the same unknown model from becoming
+     * log noise.
+     */
+    private reportUnpriced;
+    /**
+     * Warns once per outage, with a running count of what was lost.
+     *
+     * Warning on every flush would spam a hot loop, but warning exactly once per
+     * process — the previous behaviour — hid a server-side bug that failed every
+     * full batch: one line early in a long-lived process, then silence, while the
+     * dashboard quietly undercounted. The count is what makes the silence legible
+     * when someone does go looking.
+     */
+    private reportDropped;
+}

package/dist/index.js

@@ -0,0 +1,421 @@
+/** How long a flush may block waiting out a rate limit before giving up. */
+const MAX_RETRY_WAIT_MS = 2_000;
+/**
+ * `retry-after` in milliseconds, or null when the server did not say.
+ *
+ * Sent as whole seconds per the HTTP spec; spendgraph's ingest always sets it
+ * alongside a 429.
+ */
+function retryAfterMs(res) {
+    const raw = res.headers.get("retry-after");
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
+}
+/**
+ * Last-chance flush when the process winds down, shared by every meter.
+ *
+ * `beforeExit` is the right hook — unlike `exit` it permits async work, so the
+ * final send can actually complete. But it used to be registered per instance,
+ * so an app holding more than ten meters tripped Node's
+ * MaxListenersExceededWarning and kept every one of them alive forever.
+ *
+ * One listener, and meters are held weakly so a discarded one can still be
+ * collected. Deliberately no SIGTERM handler: installing one removes Node's
+ * default signal behaviour from the host application, and a telemetry library
+ * has no business changing how its host shuts down.
+ */
+const liveMeters = new Set();
+let exitHookInstalled = false;
+function registerForExitFlush(meter) {
+    if (typeof process === "undefined" || typeof process.on !== "function")
+        return;
+    // WeakRef is everywhere the SDK runs, but fall back rather than assume
+    const ref = typeof WeakRef === "function"
+        ? new WeakRef(meter)
+        : { deref: () => meter };
+    liveMeters.add(ref);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("beforeExit", () => {
+        for (const r of liveMeters) {
+            const m = r.deref();
+            if (m)
+                void m.flush();
+            else
+                liveMeters.delete(r); // collected; stop tracking it
+        }
+    });
+}
+/**
+ * Fire-and-forget token tracking. track() never throws and never blocks;
+ * events batch in memory and flush every 5s or 20 events. Network failures
+ * retry once, then drop with one console.warn — tracking can never break
+ * the host app.
+ */
+export class SpendGraph {
+    opts;
+    queue = [];
+    timer = null;
+    warned = false;
+    /** Events lost in the current run of failures, reset by a successful flush. */
+    dropped = 0;
+    /** Unpriced model ids already reported, so each is named at most once. */
+    unpricedSeen = new Set();
+    interval;
+    maxBatch;
+    /** When the pending flush was scheduled, for the suspend check in track(). */
+    timerAt = 0;
+    suspendWarned = false;
+    noKeyWarned = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.interval = opts.flushIntervalMs ?? 5000;
+        this.maxBatch = opts.maxBatch ?? 20;
+        registerForExitFlush(this);
+    }
+    /** Record one LLM call. Synchronous, returns void, never throws. */
+    track(event) {
+        try {
+            if (!this.opts.apiKey) {
+                this.warnNoKey();
+                return;
+            }
+            this.detectSuspendedRuntime();
+            this.queue.push(event);
+            if (this.queue.length >= this.maxBatch) {
+                void this.flush();
+            }
+            else if (!this.timer) {
+                this.timer = setTimeout(() => void this.flush(), this.interval);
+                this.timerAt = Date.now();
+                // don't hold the process open just to flush telemetry
+                this.timer.unref?.();
+            }
+        }
+        catch {
+            /* fail-open */
+        }
+    }
+    /**
+     * Says once that tracking is off.
+     *
+     * Running without a key stays a no-op on purpose — it keeps spendgraph out of
+     * tests and local runs without branching at every call site. But an unset
+     * SPENDGRAPH_API_KEY is indistinguishable from that choice, and it is the
+     * likeliest reason a fresh integration records nothing at all: the code is
+     * wired up correctly, the dashboard is empty, and nothing anywhere says why.
+     * Every other failure in this class warns once; this was the one that stayed
+     * quiet, which made it the hardest to find.
+     */
+    warnNoKey() {
+        if (this.noKeyWarned)
+            return;
+        this.noKeyWarned = true;
+        console.warn("spendgraph: no apiKey set, so track() is recording nothing. Pass apiKey " +
+            "(usually from SPENDGRAPH_API_KEY) to start tracking, or ignore this if " +
+            "tracking is meant to be off here.");
+    }
+    /**
+     * Notices that the runtime froze with events still buffered.
+     *
+     * Serverless platforms suspend a function once it returns rather than
+     * exiting it, so neither the flush timer nor `beforeExit` ever runs and the
+     * queue is lost without a sound — the failure Langfuse documents for Lambda
+     * and Vercel. There is no reliable flag for "am I serverless", but there is
+     * direct evidence: a pending timer whose deadline passed long ago did not
+     * fire, which only happens if the runtime stopped executing between calls.
+     *
+     * Seeing that, send the stragglers now (they survive into this invocation)
+     * and say once what the fix is. Correct callers await flush(), which clears
+     * the timer, so this never fires for them.
+     */
+    detectSuspendedRuntime() {
+        if (!this.timer)
+            return;
+        // 2x the interval, so ordinary event-loop lag is never mistaken for a freeze
+        if (Date.now() - this.timerAt <= this.interval * 2)
+            return;
+        if (!this.suspendWarned) {
+            this.suspendWarned = true;
+            console.warn("spendgraph: a scheduled flush never ran — this runtime suspends between " +
+                "invocations, so buffered events are lost. Await meter.flush() before " +
+                "your handler returns.");
+        }
+        void this.flush();
+    }
+    /** Send everything buffered now. Call at the end of serverless handlers. */
+    async flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.queue.length === 0 || !this.opts.apiKey)
+            return;
+        const events = this.queue.splice(0, this.queue.length);
+        for (let i = 0; i < events.length; i += 100) {
+            await this.send(events.slice(i, i + 100));
+        }
+    }
+    /**
+     * Wrap an Anthropic or OpenAI client. Use the wrapped client exactly as
+     * before — token usage is read off each response and tracked automatically.
+     *
+     * Streaming is covered too:
+     * - helper streams (`anthropic.messages.stream()`,
+     *   `openai.beta.chat.completions.stream()`) are tracked via their
+     *   final-message promise — the stream you get back is untouched;
+     * - raw streams (`create({ stream: true })`) are tee'd: you receive one
+     *   branch, usage is accumulated off the other. For OpenAI raw streams,
+     *   pass `stream_options: { include_usage: true }` or there is no usage
+     *   to read and the call goes untracked.
+     */
+    wrap(client) {
+        return this.proxy(client);
+    }
+    proxy(target) {
+        return new Proxy(target, {
+            get: (obj, prop, receiver) => {
+                const value = Reflect.get(obj, prop, receiver);
+                if (typeof value === "function") {
+                    return (...args) => this.observeResult(value.apply(obj, args), args);
+                }
+                if (value !== null && typeof value === "object") {
+                    return this.proxy(value);
+                }
+                return value;
+            },
+        });
+    }
+    observeResult(result, args) {
+        try {
+            // Helper streams return synchronously and expose a final-message
+            // promise (Anthropic MessageStream / OpenAI ChatCompletionStream).
+            // Awaiting it does not consume the caller's iterator.
+            const helper = result;
+            const final = typeof helper?.finalMessage === "function"
+                ? helper.finalMessage()
+                : typeof helper?.finalChatCompletion === "function"
+                    ? helper.finalChatCompletion()
+                    : null;
+            if (final instanceof Promise) {
+                final.then((m) => this.trackFromResponse(m), () => { });
+                return result;
+            }
+            if (result instanceof Promise) {
+                // Raw streaming (create({stream: true})) resolves to an SSE stream;
+                // swap in a tee'd branch so we can read usage without consuming the
+                // caller's. Only then do we replace the promise — non-streaming
+                // calls keep the SDK's original promise (withResponse() etc.).
+                const wantsStream = !!args[0]
+                    ?.stream;
+                if (wantsStream) {
+                    return result.then((v) => this.interceptStream(v));
+                }
+                // provider errors are the caller's to handle
+                result.then((v) => this.trackFromResponse(v), () => { });
+            }
+        }
+        catch {
+            /* fail-open */
+        }
+        return result;
+    }
+    interceptStream(v) {
+        try {
+            const s = v;
+            if (s &&
+                typeof s.tee === "function" &&
+                typeof s[Symbol.asyncIterator] === "function") {
+                const [mine, theirs] = s.tee();
+                void this.consumeStream(mine);
+                return theirs;
+            }
+            this.trackFromResponse(v);
+        }
+        catch {
+            /* fail-open */
+        }
+        return v;
+    }
+    /** Accumulate usage off a tee'd SSE branch (Anthropic events / OpenAI chunks). */
+    async consumeStream(iter) {
+        try {
+            let model;
+            let inputTokens;
+            let outputTokens;
+            let cacheReadTokens = 0;
+            let cacheWriteTokens = 0;
+            for await (const raw of iter) {
+                const ev = raw;
+                if (ev?.type === "message_start" && ev.message) {
+                    // Anthropic: input + cache usage arrive up front
+                    model = ev.message.model ?? model;
+                    const u = ev.message.usage ?? {};
+                    inputTokens = u.input_tokens ?? inputTokens;
+                    cacheReadTokens = u.cache_read_input_tokens ?? 0;
+                    cacheWriteTokens = u.cache_creation_input_tokens ?? 0;
+                }
+                else if (ev?.type === "message_delta" && ev.usage) {
+                    // Anthropic: cumulative output count
+                    outputTokens = ev.usage.output_tokens ?? outputTokens;
+                }
+                else if (ev?.object === "chat.completion.chunk") {
+                    // OpenAI: usage only on the final chunk, and only with
+                    // stream_options: { include_usage: true }
+                    model = ev.model ?? model;
+                    if (ev.usage) {
+                        const u = ev.usage;
+                        const cached = u.prompt_tokens_details?.cached_tokens ?? 0;
+                        inputTokens = Math.max(0, (u.prompt_tokens ?? 0) - cached);
+                        cacheReadTokens = cached;
+                        outputTokens = u.completion_tokens;
+                    }
+                }
+            }
+            if (model &&
+                typeof inputTokens === "number" &&
+                typeof outputTokens === "number") {
+                this.track({
+                    model,
+                    inputTokens,
+                    outputTokens,
+                    cacheReadTokens,
+                    cacheWriteTokens,
+                });
+            }
+        }
+        catch {
+            /* fail-open — never disturb the caller's branch */
+        }
+    }
+    trackFromResponse(res) {
+        try {
+            if (!res || typeof res !== "object")
+                return;
+            const r = res;
+            if (!r.usage || !r.model)
+                return;
+            const u = r.usage;
+            if (typeof u.input_tokens === "number" && typeof u.output_tokens === "number") {
+                // Anthropic: cache tokens are separate fields already
+                this.track({
+                    model: r.model,
+                    inputTokens: u.input_tokens,
+                    outputTokens: u.output_tokens,
+                    cacheReadTokens: u.cache_read_input_tokens ?? 0,
+                    cacheWriteTokens: u.cache_creation_input_tokens ?? 0,
+                });
+                return;
+            }
+            if (typeof u.prompt_tokens === "number" && typeof u.completion_tokens === "number") {
+                // OpenAI: cached tokens are included in prompt_tokens — split them out
+                const cached = u.prompt_tokens_details?.cached_tokens ?? 0;
+                this.track({
+                    model: r.model,
+                    inputTokens: Math.max(0, u.prompt_tokens - cached),
+                    outputTokens: u.completion_tokens,
+                    cacheReadTokens: cached,
+                });
+            }
+        }
+        catch {
+            /* fail-open */
+        }
+    }
+    async send(events, attempt = 0) {
+        try {
+            const res = await fetch(`${this.opts.baseUrl.replace(/\/$/, "")}/api/v1/ingest`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-api-key": this.opts.apiKey,
+                },
+                body: JSON.stringify({ events }),
+            });
+            if (!res.ok && res.status >= 500 && attempt === 0) {
+                return this.send(events, 1);
+            }
+            // 429 is the one failure the server tells you how to fix: it sends
+            // retry-after, and the window is at most a minute wide, so a batch that
+            // arrived at the end of one is deliverable a second later. Dropping it
+            // immediately threw that away and reported the least useful thing it
+            // could — "ingest returned 429" — for the one status with a documented
+            // remedy. The wait is capped because flush() is awaited inside serverless
+            // handlers, where blocking for a minute is worse than losing the batch.
+            if (res.status === 429 && attempt === 0) {
+                const waitMs = retryAfterMs(res);
+                if (waitMs !== null && waitMs <= MAX_RETRY_WAIT_MS) {
+                    await new Promise((r) => setTimeout(r, waitMs));
+                    return this.send(events, 1);
+                }
+                this.reportDropped(events.length, waitMs === null
+                    ? "rate limited by ingest"
+                    : `rate limited by ingest, clear in ${Math.ceil(waitMs / 1000)}s`);
+                return;
+            }
+            if (!res.ok) {
+                this.reportDropped(events.length, `ingest returned ${res.status}`);
+                return;
+            }
+            // A run of failures is over; a later one is news again rather than more
+            // of the same, so the warning is allowed to fire once more.
+            this.warned = false;
+            this.dropped = 0;
+            await this.reportUnpriced(res);
+        }
+        catch (err) {
+            if (attempt === 0)
+                return this.send(events, 1);
+            this.reportDropped(events.length, `unreachable (${String(err)})`);
+        }
+    }
+    /**
+     * Surfaces model ids the server could not price, once each.
+     *
+     * These are accepted and stored, so nothing here is an error — but they cost
+     * $0, and a dashboard reading $0 is indistinguishable from one reading
+     * "nothing happened". Naming the id in the integrator's own console is the
+     * cheapest possible moment to catch a typo or an unmapped model, and the
+     * per-id guard keeps a steady stream of the same unknown model from becoming
+     * log noise.
+     */
+    async reportUnpriced(res) {
+        try {
+            const body = (await res.json());
+            if (!Array.isArray(body?.unpricedModels))
+                return;
+            const fresh = body.unpricedModels
+                .filter((m) => typeof m === "string")
+                .filter((m) => !this.unpricedSeen.has(m));
+            if (fresh.length === 0)
+                return;
+            for (const m of fresh)
+                this.unpricedSeen.add(m);
+            console.warn(`spendgraph: no price for ${fresh.map((m) => `"${m}"`).join(", ")}. ` +
+                `These events are recorded but cost $0 until the model is in the catalog.`);
+        }
+        catch {
+            // a body we cannot read is not worth failing a successful flush over
+        }
+    }
+    /**
+     * Warns once per outage, with a running count of what was lost.
+     *
+     * Warning on every flush would spam a hot loop, but warning exactly once per
+     * process — the previous behaviour — hid a server-side bug that failed every
+     * full batch: one line early in a long-lived process, then silence, while the
+     * dashboard quietly undercounted. The count is what makes the silence legible
+     * when someone does go looking.
+     */
+    reportDropped(count, reason) {
+        this.dropped += count;
+        if (this.warned)
+            return;
+        this.warned = true;
+        console.warn(`spendgraph: ${reason}; dropped ${this.dropped} event(s). ` +
+            `Further drops are counted but not logged until a flush succeeds.`);
+    }
+}

package/dist/langchain.d.ts

@@ -0,0 +1,69 @@
+import type { SpendGraph } from "./index.js";
+type SerializedLlm = {
+    kwargs?: {
+        model?: string;
+        model_name?: string;
+    };
+};
+type ExtraParams = {
+    invocation_params?: {
+        model?: string;
+        model_name?: string;
+        modelId?: string;
+    };
+};
+type LlmResult = {
+    generations?: Array<Array<{
+        message?: {
+            usage_metadata?: {
+                input_tokens?: number;
+                output_tokens?: number;
+                input_token_details?: {
+                    cache_read?: number;
+                    cache_creation?: number;
+                };
+            };
+            response_metadata?: {
+                model?: string;
+                model_name?: string;
+            };
+        };
+    }>>;
+    llmOutput?: {
+        model?: string;
+        tokenUsage?: {
+            promptTokens?: number;
+            completionTokens?: number;
+        };
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+            cache_read_input_tokens?: number;
+            cache_creation_input_tokens?: number;
+        };
+    };
+};
+export interface LangchainHandlerOptions {
+    /** Attached to every tracked event, e.g. { feature: "rag" }. */
+    metadata?: Record<string, string | number | boolean>;
+    /** Fallback when the model name can't be read from the run. */
+    defaultModel?: string;
+}
+/**
+ * LangChain / LangGraph callback handler.
+ *
+ *   const handler = spendGraphHandler(meter);
+ *   await chain.invoke(input, { callbacks: [handler] });   // LangChain
+ *   await graph.invoke(input, { callbacks: [handler] });   // LangGraph
+ *
+ * Or pass it in the model constructor (`new ChatAnthropic({ callbacks: [...] })`)
+ * to cover every call that model makes. Fail-open like the rest of the SDK.
+ */
+export declare function spendGraphHandler(meter: SpendGraph, options?: LangchainHandlerOptions): {
+    name: string;
+    handleLLMStart(llm: SerializedLlm, _prompts: string[], runId: string, _parentRunId?: string, extraParams?: ExtraParams): void;
+    handleChatModelStart(llm: SerializedLlm, _messages: unknown, runId: string, _parentRunId?: string, extraParams?: ExtraParams): void;
+    handleLLMEnd(output: LlmResult, runId: string): void;
+    handleLLMError(_err: unknown, runId: string): void;
+};
+export {};

package/dist/langchain.js

@@ -0,0 +1,83 @@
+/**
+ * LangChain / LangGraph callback handler.
+ *
+ *   const handler = spendGraphHandler(meter);
+ *   await chain.invoke(input, { callbacks: [handler] });   // LangChain
+ *   await graph.invoke(input, { callbacks: [handler] });   // LangGraph
+ *
+ * Or pass it in the model constructor (`new ChatAnthropic({ callbacks: [...] })`)
+ * to cover every call that model makes. Fail-open like the rest of the SDK.
+ */
+export function spendGraphHandler(meter, options = {}) {
+    const models = new Map();
+    const rememberModel = (llm, runId, extraParams) => {
+        try {
+            const model = extraParams?.invocation_params?.model ??
+                extraParams?.invocation_params?.model_name ??
+                extraParams?.invocation_params?.modelId ??
+                llm?.kwargs?.model ??
+                llm?.kwargs?.model_name;
+            if (model)
+                models.set(runId, model);
+        }
+        catch {
+            /* fail-open */
+        }
+    };
+    return {
+        name: "spendgraph",
+        handleLLMStart(llm, _prompts, runId, _parentRunId, extraParams) {
+            rememberModel(llm, runId, extraParams);
+        },
+        handleChatModelStart(llm, _messages, runId, _parentRunId, extraParams) {
+            rememberModel(llm, runId, extraParams);
+        },
+        handleLLMEnd(output, runId) {
+            try {
+                const msg = output.generations?.[0]?.[0]?.message;
+                const um = msg?.usage_metadata;
+                const tu = output.llmOutput?.tokenUsage;
+                const au = output.llmOutput?.usage;
+                let inputTokens = um?.input_tokens ?? au?.input_tokens ?? tu?.promptTokens;
+                const outputTokens = um?.output_tokens ?? au?.output_tokens ?? tu?.completionTokens;
+                if (typeof inputTokens !== "number" || typeof outputTokens !== "number")
+                    return;
+                // Cache tokens: usage_metadata.input_tokens INCLUDES them (LangChain
+                // normalizes to a total) so they're split out; the raw Anthropic
+                // llmOutput.usage shape keeps them separate already.
+                let cacheReadTokens = 0;
+                let cacheWriteTokens = 0;
+                if (um?.input_token_details && typeof um.input_tokens === "number") {
+                    cacheReadTokens = um.input_token_details.cache_read ?? 0;
+                    cacheWriteTokens = um.input_token_details.cache_creation ?? 0;
+                    inputTokens = Math.max(0, inputTokens - cacheReadTokens - cacheWriteTokens);
+                }
+                else if (au) {
+                    cacheReadTokens = au.cache_read_input_tokens ?? 0;
+                    cacheWriteTokens = au.cache_creation_input_tokens ?? 0;
+                }
+                const model = msg?.response_metadata?.model ??
+                    msg?.response_metadata?.model_name ??
+                    output.llmOutput?.model ??
+                    models.get(runId) ??
+                    options.defaultModel ??
+                    "unknown";
+                models.delete(runId);
+                meter.track({
+                    model,
+                    inputTokens,
+                    outputTokens,
+                    cacheReadTokens,
+                    cacheWriteTokens,
+                    metadata: options.metadata,
+                });
+            }
+            catch {
+                /* fail-open */
+            }
+        },
+        handleLLMError(_err, runId) {
+            models.delete(runId);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@spendgraph/sdk",
+  "version": "0.1.0",
+  "description": "Track LLM input/output tokens and cost. Three functions, zero dependencies, fail-open.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fnLog0/spendgraph.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/fnLog0/spendgraph#readme",
+  "bugs": {
+    "url": "https://github.com/fnLog0/spendgraph/issues"
+  },
+  "keywords": [
+    "llm",
+    "cost",
+    "tokens",
+    "openai",
+    "anthropic",
+    "observability",
+    "pricing"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.js"
+    },
+    "./ai": {
+      "types": "./dist/ai.d.ts",
+      "import": "./dist/ai.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}