@spendgraph/sdk 0.2.0 → 0.3.0

package/dist/ai.js

@@ -1,13 +1,3 @@
-/**
- * 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;
@@ -15,7 +5,6 @@ export function trackAiResult(meter, result, options = {}) {
         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 ??
@@ -32,6 +21,5 @@ export function trackAiResult(meter, result, options = {}) {
         });
     }
     catch {
-        /* fail-open */
     }
 }

package/dist/client.js

@@ -1,18 +1,6 @@
 import { Client } from "./core/client/index.js";
 import { Alerts, Credentials, Events, Ingest, Invites, Keys, Models, Playground, Pricing, Projects, Prompts, PromptsAdmin, Stats, Tools, } from "./resources/index.js";
-/**
- * The whole spendgraph API, one client.
- *
- * Every other package in this repo goes through this rather than calling the
- * app directly, so base URL, auth, retries and error shapes are decided once.
- *
- * An `apiKey` reaches usage, stats and prompts. The dashboard half — keys,
- * projects, pricing, credentials — is gated on a signed-in user server-side and
- * needs `session`; there is no API-key path to it, which is what stops a leaked
- * ingest key from minting more keys or reading a provider secret.
- */
 export class Spendgraph {
-    /** The transport. Reach for it only for a route this class does not cover. */
     http;
     ingest;
     stats;

package/dist/core/client/client.js

@@ -2,12 +2,6 @@ import { SpendgraphError } from "./errors.js";
 const DEFAULT_ATTEMPTS = 3;
 const DEFAULT_MAX_WAIT_MS = 5_000;
 const BACKOFF_BASE_MS = 250;
-/**
- * `retry-after` in milliseconds, or null when the server did not say.
- *
- * Whole seconds per the HTTP spec. Honouring it beats guessing — a backoff
- * shorter than the window just burns another attempt.
- */
 function retryAfterMs(res) {
     const raw = res.headers.get("retry-after");
     if (!raw)
@@ -15,7 +9,6 @@ function retryAfterMs(res) {
     const seconds = Number(raw);
     return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
 }
-/** Drops empty parameters rather than sending the string "undefined". */
 export function queryString(query = {}) {
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(query)) {
@@ -26,12 +19,6 @@ export function queryString(query = {}) {
     const encoded = params.toString();
     return encoded ? `?${encoded}` : "";
 }
-/**
- * The one thing in this package that talks to spendgraph.
- *
- * Every resource module is given this and returns data, which is what makes
- * the rest testable with no server.
- */
 export class Client {
     baseUrl;
     doFetch;
@@ -51,7 +38,6 @@ export class Client {
             ...(opts.session ? { cookie: opts.session } : {}),
         };
     }
-    /** True once anything is set that the server might accept. */
     get authenticated() {
         return Object.keys(this.auth).length > 0;
     }
@@ -110,7 +96,6 @@ export class Client {
             ...(body === undefined ? {} : { body: JSON.stringify(body) }),
         });
     }
-    /** A 204 and an empty body are success, not a JSON parse failure. */
     async decode(res) {
         if (res.status === 204)
             return undefined;

package/dist/core/client/errors.js

@@ -1,16 +1,7 @@
-/**
- * One error type for everything the API can refuse, carrying the status.
- *
- * A caller retrying blind is the failure this prevents: 429 is worth waiting
- * out, 401 never will be, and a message alone cannot tell them apart.
- */
 export class SpendgraphError extends Error {
     status;
-    /** The API's machine-readable code, when it sent one. */
     code;
-    /** How many attempts were made, so a log line says "gave up after 4". */
     attempts;
-    /** The server's own `retry-after`, in ms. Null when it did not send one. */
     retryAfterMs;
     constructor(status, code, message, opts = {}) {
         super(message);
@@ -20,11 +11,6 @@ export class SpendgraphError extends Error {
         this.attempts = opts.attempts ?? 1;
         this.retryAfterMs = opts.retryAfterMs ?? null;
     }
-    /**
-     * Worth trying again: rate limits, server faults, and a connection that never
-     * got far enough to have a status. Never a bad request — retrying a 401 or a
-     * 422 just spends the same attempt budget on the same answer.
-     */
     get retryable() {
         return this.status === 0 || this.status === 429 || this.status >= 500;
     }

package/dist/langchain.js

@@ -1,13 +1,3 @@
-/**
- * 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) => {
@@ -21,7 +11,6 @@ export function spendGraphHandler(meter, options = {}) {
                 models.set(runId, model);
         }
         catch {
-            /* fail-open */
         }
     };
     return {
@@ -33,11 +22,6 @@ export function spendGraphHandler(meter, options = {}) {
             rememberModel(llm, runId, extraParams);
         },
         handleLLMEnd(output, runId) {
-            // Forget the run before anything else can bail out. The usage checks
-            // below give up on any response whose token counts cannot be read, and
-            // the delete used to sit after them — so each such call left its entry
-            // behind for good. This handler is meant to be attached to a long-lived
-            // model instance, which turns that into a map that only ever grows.
             const startedAs = models.get(runId);
             models.delete(runId);
             try {
@@ -49,9 +33,6 @@ export function spendGraphHandler(meter, options = {}) {
                 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") {
@@ -79,7 +60,6 @@ export function spendGraphHandler(meter, options = {}) {
                 });
             }
             catch {
-                /* fail-open */
             }
         },
         handleLLMError(_err, runId) {

package/dist/resources/alerts.js

@@ -1,4 +1,3 @@
-/** Budget alerts the server has raised. */
 export class Alerts {
     client;
     constructor(client) {

package/dist/resources/credentials.js

@@ -1,9 +1,3 @@
-/**
- * Provider API keys held by the server so it can run a prompt for you.
- *
- * Dashboard session only, and it stays that way: these are the secrets an
- * `sg_` key must never be able to read.
- */
 export class Credentials {
     client;
     constructor(client) {
@@ -12,7 +6,6 @@ export class Credentials {
     list() {
         return this.client.get("/api/v1/credentials");
     }
-    /** Write-only from the caller's side — the server never reads one back. */
     set(body) {
         return this.client.put("/api/v1/credentials", body);
     }

package/dist/resources/events.js

@@ -1,4 +1,3 @@
-/** The raw call records behind the totals. */
 export class Events {
     client;
     constructor(client) {
@@ -7,7 +6,6 @@ export class Events {
     list(query = {}) {
         return this.client.get("/api/v1/events", { ...query });
     }
-    /** Walks every page, so a caller does not have to hold the cursor. */
     async *all(query = {}) {
         let cursor = query.cursor;
         do {

package/dist/resources/ingest.js

@@ -1,6 +1,4 @@
-/** The route takes up to this many events per request. */
 export const MAX_EVENTS = 100;
-/** Posts usage straight through, chunked to what the route accepts. */
 export class Ingest {
     client;
     project;
@@ -11,7 +9,6 @@ export class Ingest {
     async send(events) {
         await this.report(events);
     }
-    /** The same write, with the server's answer — which ids went unpriced. */
     async report(events) {
         const total = { accepted: 0, rejected: 0, unpricedModels: [] };
         if (events.length === 0)

package/dist/resources/keys.js

@@ -1,7 +1,3 @@
-/**
- * API keys. Dashboard session only, deliberately: a key that could mint keys
- * would turn one leaked ingest credential into permanent access.
- */
 export class Keys {
     client;
     constructor(client) {
@@ -10,7 +6,6 @@ export class Keys {
     list(query = {}) {
         return this.client.get("/api/v1/keys", { ...query });
     }
-    /** The plaintext key is in this response and nowhere else, ever again. */
     create(body) {
         return this.client.post("/api/v1/keys", body);
     }

package/dist/resources/playground.js

@@ -1,4 +1,3 @@
-/** Ad-hoc runs from the dashboard, streamed. Dashboard session only. */
 export class Playground {
     client;
     constructor(client) {

package/dist/resources/pricing.js

@@ -1,4 +1,3 @@
-/** The pricing catalogue. Dashboard session only. */
 export class Pricing {
     client;
     constructor(client) {
@@ -7,15 +6,12 @@ export class Pricing {
     list() {
         return this.client.get("/api/v1/pricing");
     }
-    /** A manual override for one model, which outranks the synced rows. */
     override(model, body) {
         return this.client.put(`/api/v1/pricing/${encodeURIComponent(model)}`, body);
     }
-    /** Which models the catalogue can price, and which it cannot. */
     coverage() {
         return this.client.get("/api/v1/pricing/coverage");
     }
-    /** What legacy and offer-based pricing would each charge, side by side. */
     readiness() {
         return this.client.get("/api/v1/pricing/readiness");
     }
@@ -23,7 +19,6 @@ export class Pricing {
         return this.client.post("/api/v1/pricing/sync", body);
     }
 }
-/** The model catalogue and the offers behind it. Dashboard session only. */
 export class Models {
     client;
     constructor(client) {
@@ -35,7 +30,6 @@ export class Models {
     offers(query = {}) {
         return this.client.get("/api/v1/offers", { ...query });
     }
-    /** Prices one workload across models or serving providers. */
     compare(query = {}) {
         return this.client.get("/api/v1/compare", { ...query });
     }

package/dist/resources/projects.js

@@ -1,4 +1,3 @@
-/** Projects, their budgets, members and invites. Dashboard session only. */
 export class Projects {
     client;
     constructor(client) {
@@ -36,7 +35,6 @@ export class Projects {
         });
     }
 }
-/** Accepting an invite is the one project call that identifies a person, not a key. */
 export class Invites {
     client;
     constructor(client) {

package/dist/resources/prompts-admin.js

@@ -1,7 +1,3 @@
-/**
- * The prompt operations gated on a dashboard session — publishing a version,
- * archiving a prompt, starting an optimization run, and reading run history.
- */
 export class PromptsAdmin {
     client;
     constructor(client) {
@@ -13,7 +9,6 @@ export class PromptsAdmin {
     archive(promptId, query = {}) {
         return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/archive`, {}, { ...query });
     }
-    /** Starts an optimization run. The budget is required, never defaulted. */
     assay(promptId, body) {
         return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/assay`, body);
     }

package/dist/resources/prompts.js

@@ -1,10 +1,3 @@
-/**
- * Stored prompts, their versions, datasets and rollouts.
- *
- * This is the half of the API a job uses: every method here takes an API key.
- * Publishing, archiving and optimizing are on the dashboard half — see
- * `PromptsAdmin`.
- */
 export class Prompts {
     client;
     constructor(client) {
@@ -16,7 +9,6 @@ export class Prompts {
     create(body) {
         return this.client.post("/api/v1/prompts", body);
     }
-    /** One prompt with its current version. `runs` asks for its recent runs too. */
     get(promptId, query = {}) {
         return this.client.get(`/api/v1/prompts/${encodeURIComponent(promptId)}`, { ...query });
     }
@@ -28,7 +20,6 @@ export class Prompts {
             ...query,
         });
     }
-    /** Promotes a stored version to current. Unchanged text is a no-op, not a fork. */
     promote(promptId, versionId, query = {}) {
         return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/versions`, { versionId }, { ...query });
     }
@@ -37,7 +28,6 @@ export class Prompts {
             ...query,
         });
     }
-    /** Replaces the dataset. Splits are derived, so a case never moves between them. */
     putCases(promptId, cases, query = {}) {
         return this.client.put(`/api/v1/prompts/${encodeURIComponent(promptId)}/cases`, { cases }, { ...query });
     }
@@ -46,19 +36,11 @@ export class Prompts {
             ...query,
         });
     }
-    /**
-     * Records a rollout the caller ran itself. Dedupes on `rolloutId`.
-     *
-     * `priced` is false where no pricing row covered the model. The stored cost
-     * is zero either way — the column is `notNull` — so this flag is the only
-     * thing telling a free call apart from an unpriced one.
-     */
     report(promptId, body, query = {}) {
         return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/rollouts`, body, {
             ...query,
         });
     }
-    /** Runs the prompt server-side, where the spec, rendering and pricing already live. */
     run(promptId, body, query = {}) {
         return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/run`, body, {
             ...query,

package/dist/resources/stats.js

@@ -1,15 +1,8 @@
-/**
- * Spend, read back.
- *
- * Every method here takes an API key, so a job can check what it spent without
- * a dashboard session.
- */
 export class Stats {
     client;
     constructor(client) {
         this.client = client;
     }
-    /** Totals for the window, beside the window before it. */
     summary(query = {}) {
         return this.client.get("/api/v1/stats/summary", { ...query });
     }
@@ -22,7 +15,6 @@ export class Stats {
     byKey(query = {}) {
         return this.client.get("/api/v1/stats/by-key", { ...query });
     }
-    /** Grouped by one metadata tag. `key` picks which tag. */
     byTag(query = {}) {
         return this.client.get("/api/v1/stats/by-tag", { ...query });
     }

package/dist/resources/tools.js

@@ -1,10 +1,3 @@
-/**
- * Declared tools.
- *
- * `get` and `list` take an API key, because binding a handler happens in a
- * running service. Writing one is a dashboard action and needs a session — the
- * same split prompts have.
- */
 export class Tools {
     client;
     constructor(client) {
@@ -13,7 +6,6 @@ export class Tools {
     list(query = {}) {
         return this.client.get("/api/v1/tools", { ...query });
     }
-    /** One tool, addressed by uuid or by the name the model calls. */
     get(name, query = {}) {
         return this.client.get(`/api/v1/tools/${encodeURIComponent(name)}`, { ...query });
     }
@@ -23,7 +15,6 @@ export class Tools {
     update(id, body, query = {}) {
         return this.client.patch(`/api/v1/tools/${encodeURIComponent(id)}`, body, { ...query });
     }
-    /** Out of the list, not destroyed. `archived: false` brings it back. */
     archive(id, archived, query = {}) {
         return this.client.post(`/api/v1/tools/${encodeURIComponent(id)}/archive`, { archived }, { ...query });
     }

package/dist/schema/serialize/serialize.js

@@ -1,5 +1,4 @@
 import { FieldValidationError, isMissing, toBoolean, toNumber, validateFields, } from "../validate/index.js";
-/** One declared value as the text that replaces its placeholder. */
 function renderOne(field, value) {
     switch (field.type) {
         case "number":
@@ -14,16 +13,6 @@ function renderOne(field, value) {
             return String(value);
     }
 }
-/**
- * Validated values as the flat string map the renderer substitutes.
- *
- * Throws rather than rendering something approximate. Headless there is no
- * human reading the reply, so a missing required field would otherwise buy a
- * paid-for response with a hole in it that nothing downstream can detect.
- *
- * An optional field left unset is omitted, so its `{name}` stays visible — the
- * same behaviour the prompt builder has always had.
- */
 export function serializeFields(values, spec) {
     const errors = validateFields(values, spec);
     if (errors.length)

package/dist/schema/validate/validate.js

@@ -6,17 +6,9 @@ export class FieldValidationError extends Error {
         this.errors = errors;
     }
 }
-/** Absent means absent. An empty string is a value someone chose to send. */
 export function isMissing(value) {
     return value === undefined || value === null;
 }
-/**
- * Coercions shared with the renderer.
- *
- * Shared deliberately: if the checker and the renderer disagreed, a value could
- * pass validation and then render as something else — a request you paid for
- * and cannot explain.
- */
 export function toNumber(value) {
     return typeof value === "number" ? value : Number(String(value).trim());
 }
@@ -55,7 +47,6 @@ function checkEnum(field, value) {
         ? null
         : `must be one of ${options.join(" | ")}, got ${JSON.stringify(value)}`;
 }
-/** Catches cycles and BigInt, which otherwise reach the provider as a crash. */
 function checkJson(value) {
     try {
         JSON.stringify(value);
@@ -82,13 +73,6 @@ function checkOne(field, value) {
             return checkJson(value);
     }
 }
-/**
- * Everything wrong with these values, rather than the first thing.
- *
- * Values with no matching field are ignored, not reported: a stored prompt keeps
- * values for placeholders that were later edited out, and treating a stale key
- * as an error would fail a prompt that renders perfectly well.
- */
 export function validateFields(values, spec) {
     const errors = [];
     for (const field of spec) {
@@ -98,7 +82,7 @@ export function validateFields(values, spec) {
                 continue;
             if (field.required)
                 errors.push({ field: field.name, message: "is required" });
-            continue; // optional and unset — the placeholder stays visible
+            continue;
         }
         const problem = checkOne(field, value);
         if (problem)

package/dist/track/track.js

@@ -1,25 +1,10 @@
 import { Client, SpendgraphError } from "../core/client/index.js";
-/** How long a flush may block waiting out a rate limit before giving up. */
 const MAX_RETRY_WAIT_MS = 2_000;
-/**
- * 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 };
@@ -33,33 +18,23 @@ function registerForExitFlush(meter) {
             if (m)
                 void m.flush();
             else
-                liveMeters.delete(r); // collected; stop tracking it
+                liveMeters.delete(r);
         }
     });
 }
-/**
- * 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;
     streamUsageWarned = false;
-    /** The flush currently on the wire, so a later flush() can wait for it. */
     inFlight = null;
     constructor(opts) {
         this.opts = opts;
@@ -67,17 +42,9 @@ export class SpendGraph {
         this.maxBatch = opts.maxBatch ?? 20;
         registerForExitFlush(this);
     }
-    /**
-     * The package's client, given no retries of its own.
-     *
-     * The policy in `send` stays this class's: a flush is awaited inside
-     * serverless handlers, where blocking out a minute-long rate-limit window is
-     * worse than losing the batch, and the client's backoff would do exactly that.
-     */
     clientFor(apiKey) {
         return new Client({ apiKey, baseUrl: this.opts.baseUrl, attempts: 1 });
     }
-    /** Record one LLM call. Synchronous, returns void, never throws. */
     track(event) {
         try {
             if (!this.opts.apiKey) {
@@ -92,25 +59,12 @@ export class SpendGraph {
             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;
@@ -119,24 +73,9 @@ export class SpendGraph {
             "(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) {
@@ -147,42 +86,19 @@ export class SpendGraph {
         }
         void this.flush();
     }
-    /**
-     * Send everything buffered now. Call at the end of serverless handlers.
-     *
-     * Serialised against a flush already running, because this method is not the
-     * only thing that starts one: track() flushes by itself the moment the batch
-     * is full, and so do the timer, the suspend check and the exit hook. Those
-     * empty the queue synchronously, so an awaited flush() used to find nothing
-     * left to send and hand back an already-resolved promise while the real
-     * batch was still on the wire — and the next thing a serverless handler does
-     * after awaiting is return, freezing the runtime and losing exactly the
-     * events the await was there to save.
-     *
-     * The drain still starts synchronously — `drain()` runs as far as its first
-     * await before returning a promise, so the queue is taken during this call
-     * and not a microtask later. That ordering is load-bearing: the suspend
-     * check and the exit hook both fire a flush and then expect the buffer to be
-     * gone, and deferring it broke them.
-     */
     async flush() {
         const prev = this.inFlight;
         const mine = this.drain();
-        // Both, not one after the other: they carry disjoint events, since this
-        // call already took everything the earlier one left behind.
         const run = Promise.allSettled([prev, mine]).then(() => undefined);
         this.inFlight = run;
         try {
             await run;
         }
         finally {
-            // Only the newest link clears the slot. An older one settling last must
-            // not strand a flush that has already queued up behind it.
             if (this.inFlight === run)
                 this.inFlight = null;
         }
     }
-    /** One pass: stop the timer, take the queue, put it on the wire. */
     async drain() {
         if (this.timer) {
             clearTimeout(this.timer);
@@ -196,43 +112,9 @@ export class SpendGraph {
             await this.send(events.slice(i, i + 100), apiKey);
         }
     }
-    /**
-     * 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);
     }
-    /**
-     * The recursive wrapper behind wrap().
-     *
-     * Two things here are deliberate and were both wrong before.
-     *
-     * `Reflect.get` is called without a receiver, so a getter runs with the real
-     * client as `this`. Passing the proxy — the obvious reading of the Proxy
-     * docs — makes any getter that touches a `#private` field throw
-     * "Cannot read private member", and the provider SDKs this is built to wrap
-     * use private fields. That turned a tracking wrapper into a crash on a
-     * client that works perfectly well unwrapped, in an SDK whose whole contract
-     * is to fail open.
-     *
-     * And each wrapper is kept, so `client.messages` and `client.messages.create`
-     * are the same object and the same function every time they are read.
-     * Rebuilding them per access allocated a proxy and a closure on every call
-     * and quietly broke any caller that holds onto a method or compares
-     * identity. The cache is per proxy and keyed by property, so a method always
-     * applies to the object it was read from, and it re-wraps if the underlying
-     * value is ever replaced.
-     */
     proxy(target) {
         const cache = new Map();
         return new Proxy(target, {
@@ -254,9 +136,6 @@ export class SpendGraph {
     }
     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()
@@ -268,20 +147,14 @@ export class SpendGraph {
                 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;
     }
@@ -296,11 +169,9 @@ export class SpendGraph {
             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;
@@ -315,7 +186,6 @@ export class SpendGraph {
                 sawChunk = true;
                 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;
@@ -323,12 +193,9 @@ export class SpendGraph {
                     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;
@@ -357,22 +224,8 @@ export class SpendGraph {
             }
         }
         catch {
-            /* fail-open — never disturb the caller's branch */
         }
     }
-    /**
-     * Says once that a streamed call went untracked.
-     *
-     * A raw OpenAI stream carries no usage unless the caller asks for it, so the
-     * accumulator above finishes with nothing to report and simply returns —
-     * correct, and completely silent. That is the same hole warnNoKey was added
-     * to close: the integration looks right, the dashboard stays empty for those
-     * calls, and nothing anywhere connects the two. Anthropic streams always
-     * carry usage, so in practice this names the one option that fixes it.
-     *
-     * Guarded on having seen at least one chunk, so an empty or aborted stream —
-     * where there was never anything to read — stays quiet.
-     */
     warnStreamNoUsage() {
         if (this.streamUsageWarned)
             return;
@@ -391,7 +244,6 @@ export class SpendGraph {
                 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,
@@ -402,7 +254,6 @@ export class SpendGraph {
                 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,
@@ -415,7 +266,6 @@ export class SpendGraph {
             }
         }
         catch {
-            /* fail-open */
         }
     }
     async send(events, apiKey, attempt = 0) {
@@ -426,23 +276,10 @@ export class SpendGraph {
         catch (err) {
             return this.onSendFailed(err, events, apiKey, attempt);
         }
-        // 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;
         this.reportUnpriced(body);
     }
-    /**
-     * The drop policy, which is this class's rather than the client's.
-     *
-     * 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.
-     */
     async onSendFailed(err, events, apiKey, attempt) {
         const failure = err instanceof SpendgraphError ? err : null;
         if (!failure || failure.status === 0) {
@@ -467,16 +304,6 @@ export class SpendGraph {
         }
         this.reportDropped(events.length, `ingest returned ${failure.status}`);
     }
-    /**
-     * 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.
-     */
     reportUnpriced(body) {
         {
             const parsed = body;
@@ -493,15 +320,6 @@ export class SpendGraph {
                 `These events are recorded but cost $0 until the model is in the catalog.`);
         }
     }
-    /**
-     * 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Track LLM input/output tokens and cost. Three functions, zero dependencies, fail-open.",
   "license": "MIT",
   "repository": {
@@ -43,7 +43,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
     "test": "vitest run"
   },
   "devDependencies": {