@spendgraph/sdk 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,421 +1,5 @@
-/** 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.`);
-    }
-}
+export { Spendgraph } from "./client.js";
+export { Client, queryString, SpendgraphError } from "./core/client/index.js";
+export * from "./resources/index.js";
+export { FieldValidationError, serializeFields, validateFields, } from "./schema/index.js";
+export { SpendGraph } from "./track/index.js";

package/dist/langchain.js

@@ -33,6 +33,13 @@ 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 {
                 const msg = output.generations?.[0]?.[0]?.message;
                 const um = msg?.usage_metadata;
@@ -59,10 +66,9 @@ export function spendGraphHandler(meter, options = {}) {
                 const model = msg?.response_metadata?.model ??
                     msg?.response_metadata?.model_name ??
                     output.llmOutput?.model ??
-                    models.get(runId) ??
+                    startedAs ??
                     options.defaultModel ??
                     "unknown";
-                models.delete(runId);
                 meter.track({
                     model,
                     inputTokens,

package/dist/resources/alerts.d.ts

@@ -0,0 +1,18 @@
+import type { Client } from "../core/client/index.js";
+export interface AlertRow {
+    id: string;
+    projectId: string;
+    kind: string;
+    createdAt: string;
+}
+/** Budget alerts the server has raised. */
+export declare class Alerts {
+    private readonly client;
+    constructor(client: Client);
+    list(query?: {
+        project?: string;
+        limit?: number;
+    }): Promise<{
+        alerts: AlertRow[];
+    }>;
+}

package/dist/resources/alerts.js

@@ -0,0 +1,10 @@
+/** Budget alerts the server has raised. */
+export class Alerts {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(query = {}) {
+        return this.client.get("/api/v1/alerts", { ...query });
+    }
+}

package/dist/resources/credentials.d.ts

@@ -0,0 +1,22 @@
+import type { Client } from "../core/client/index.js";
+/**
+ * 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 declare class Credentials {
+    private readonly client;
+    constructor(client: Client);
+    list(): Promise<{
+        providers: unknown[];
+    }>;
+    /** Write-only from the caller's side — the server never reads one back. */
+    set(body: {
+        provider: string;
+        apiKey: string;
+    }): Promise<{
+        provider: string;
+    }>;
+    remove(provider: string): Promise<Record<string, unknown>>;
+}

package/dist/resources/credentials.js

@@ -0,0 +1,22 @@
+/**
+ * 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) {
+        this.client = client;
+    }
+    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);
+    }
+    remove(provider) {
+        return this.client.delete("/api/v1/credentials", { provider });
+    }
+}

package/dist/resources/events.d.ts

@@ -0,0 +1,41 @@
+import type { Client } from "../core/client/index.js";
+export interface EventsQuery {
+    from?: string;
+    to?: string;
+    project?: string;
+    model?: string;
+    key?: string;
+    /** Free-text search. */
+    q?: string;
+    sort?: string;
+    limit?: number;
+    /** From the previous page's `nextCursor`. */
+    cursor?: string;
+    format?: string;
+}
+export interface UsageEventRow {
+    id: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    citationTokens: number;
+    reasoningTokens: number;
+    costMicros: number;
+    metadata: string | null;
+    createdAt: string;
+}
+export interface EventsPage {
+    events: UsageEventRow[];
+    /** Absent on the last page. */
+    nextCursor?: string | null;
+}
+/** The raw call records behind the totals. */
+export declare class Events {
+    private readonly client;
+    constructor(client: Client);
+    list(query?: EventsQuery): Promise<EventsPage>;
+    /** Walks every page, so a caller does not have to hold the cursor. */
+    all(query?: EventsQuery): AsyncGenerator<UsageEventRow>;
+}

package/dist/resources/events.js

@@ -0,0 +1,20 @@
+/** The raw call records behind the totals. */
+export class Events {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    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 {
+            const page = await this.list({ ...query, cursor });
+            for (const event of page.events)
+                yield event;
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor);
+    }
+}

package/dist/resources/index.d.ts

@@ -0,0 +1,21 @@
+export type { AlertRow } from "./alerts.js";
+export { Alerts } from "./alerts.js";
+export { Credentials } from "./credentials.js";
+export type { EventsPage, EventsQuery, UsageEventRow } from "./events.js";
+export { Events } from "./events.js";
+export type { IngestResult, Sender, UsageEvent } from "./ingest.js";
+export { Ingest, MAX_EVENTS } from "./ingest.js";
+export type { ApiKeyRow } from "./keys.js";
+export { Keys } from "./keys.js";
+export { Playground } from "./playground.js";
+export type { PricingRow } from "./pricing.js";
+export { Models, Pricing } from "./pricing.js";
+export type { Budget, ProjectRow } from "./projects.js";
+export { Invites, Projects } from "./projects.js";
+export type { DatasetCase, PromptBlock, RenderedMessage, ReportRolloutInput, Role, RunPromptInput, SavePromptInput, Scoped, } from "./prompts.js";
+export { Prompts } from "./prompts.js";
+export { PromptsAdmin } from "./prompts-admin.js";
+export type { SaveToolInput, ToolEffect, ToolRow } from "./tools.js";
+export { Tools } from "./tools.js";
+export type { ModelRow, RangeQuery, Summary, Timeseries, TimeseriesPoint, Totals, } from "./stats.js";
+export { Stats } from "./stats.js";

package/dist/resources/index.js

@@ -0,0 +1,12 @@
+export { Alerts } from "./alerts.js";
+export { Credentials } from "./credentials.js";
+export { Events } from "./events.js";
+export { Ingest, MAX_EVENTS } from "./ingest.js";
+export { Keys } from "./keys.js";
+export { Playground } from "./playground.js";
+export { Models, Pricing } from "./pricing.js";
+export { Invites, Projects } from "./projects.js";
+export { Prompts } from "./prompts.js";
+export { PromptsAdmin } from "./prompts-admin.js";
+export { Tools } from "./tools.js";
+export { Stats } from "./stats.js";

package/dist/resources/ingest.d.ts

@@ -0,0 +1,42 @@
+import type { Client } from "../core/client/index.js";
+import type { Tag } from "../core/types.js";
+/** One call's consumption. The server prices it from the model id. */
+export interface UsageEvent {
+    eventId?: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** Billed on their own by search-grounded providers, not folded into output. */
+    citationTokens?: number;
+    reasoningTokens?: number;
+    timestamp?: string;
+    metadata?: Record<string, Tag>;
+}
+export interface IngestResult {
+    accepted: number;
+    rejected: number;
+    /** Ids nothing could price. Stored at $0 and counted, never rejected. */
+    unpricedModels: string[];
+}
+/** The route takes up to this many events per request. */
+export declare const MAX_EVENTS = 100;
+/**
+ * Anything that can deliver usage — this sender, a queue, a test double.
+ *
+ * `@spendgraph/llms` accepts this shape, so an `Ingest` from here can be handed
+ * straight to it without either package importing the other's transport.
+ */
+export interface Sender {
+    send(events: UsageEvent[]): Promise<void>;
+}
+/** Posts usage straight through, chunked to what the route accepts. */
+export declare class Ingest implements Sender {
+    private readonly client;
+    private readonly project?;
+    constructor(client: Client, project?: string | undefined);
+    send(events: UsageEvent[]): Promise<void>;
+    /** The same write, with the server's answer — which ids went unpriced. */
+    report(events: UsageEvent[]): Promise<IngestResult>;
+}