@spendgraph/sdk 0.1.0 → 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+import { Client } from "./core/client/index.js";
+import type { ClientOptions } from "./core/types.js";
+import { Alerts, Credentials, Events, Ingest, Invites, Keys, Models, Playground, Pricing, Projects, Prompts, PromptsAdmin, Stats, Tools } from "./resources/index.js";
+export interface SpendgraphOptions extends ClientOptions {
+    /** Scopes writes that accept one. A key is already pinned to its project. */
+    project?: string;
+}
+/**
+ * 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 declare class Spendgraph {
+    /** The transport. Reach for it only for a route this class does not cover. */
+    readonly http: Client;
+    readonly ingest: Ingest;
+    readonly stats: Stats;
+    readonly events: Events;
+    readonly alerts: Alerts;
+    readonly prompts: Prompts;
+    readonly promptsAdmin: PromptsAdmin;
+    readonly keys: Keys;
+    readonly projects: Projects;
+    readonly invites: Invites;
+    readonly pricing: Pricing;
+    readonly models: Models;
+    readonly credentials: Credentials;
+    readonly playground: Playground;
+    readonly tools: Tools;
+    constructor(opts: SpendgraphOptions);
+}

package/dist/client.js

@@ -0,0 +1,48 @@
+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;
+    events;
+    alerts;
+    prompts;
+    promptsAdmin;
+    keys;
+    projects;
+    invites;
+    pricing;
+    models;
+    credentials;
+    playground;
+    tools;
+    constructor(opts) {
+        this.http = new Client(opts);
+        this.ingest = new Ingest(this.http, opts.project);
+        this.stats = new Stats(this.http);
+        this.events = new Events(this.http);
+        this.alerts = new Alerts(this.http);
+        this.prompts = new Prompts(this.http);
+        this.promptsAdmin = new PromptsAdmin(this.http);
+        this.keys = new Keys(this.http);
+        this.projects = new Projects(this.http);
+        this.invites = new Invites(this.http);
+        this.pricing = new Pricing(this.http);
+        this.models = new Models(this.http);
+        this.credentials = new Credentials(this.http);
+        this.playground = new Playground(this.http);
+        this.tools = new Tools(this.http);
+    }
+}

package/dist/core/client/client.d.ts

@@ -0,0 +1,30 @@
+import type { ClientOptions, Query } from "../types.js";
+/** Drops empty parameters rather than sending the string "undefined". */
+export declare function queryString(query?: Query): string;
+/**
+ * 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 declare class Client {
+    private readonly baseUrl;
+    private readonly doFetch;
+    private readonly sleep;
+    private readonly attempts;
+    private readonly maxWaitMs;
+    private readonly auth;
+    constructor(opts: ClientOptions);
+    /** True once anything is set that the server might accept. */
+    get authenticated(): boolean;
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+    get<T>(path: string, query?: Query): Promise<T>;
+    post<T>(path: string, body?: unknown, query?: Query): Promise<T>;
+    put<T>(path: string, body?: unknown, query?: Query): Promise<T>;
+    patch<T>(path: string, body?: unknown, query?: Query): Promise<T>;
+    delete<T>(path: string, query?: Query): Promise<T>;
+    private send;
+    /** A 204 and an empty body are success, not a JSON parse failure. */
+    private decode;
+    private toError;
+}

package/dist/core/client/client.js

@@ -0,0 +1,143 @@
+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)
+        return null;
+    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)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        params.set(key, String(value));
+    }
+    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;
+    sleep;
+    attempts;
+    maxWaitMs;
+    auth;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.doFetch = opts.fetch ?? globalThis.fetch;
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.attempts = Math.max(1, opts.attempts ?? DEFAULT_ATTEMPTS);
+        this.maxWaitMs = opts.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+        this.auth = {
+            ...opts.headers,
+            ...(opts.apiKey ? { "x-api-key": opts.apiKey } : {}),
+            ...(opts.session ? { cookie: opts.session } : {}),
+        };
+    }
+    /** True once anything is set that the server might accept. */
+    get authenticated() {
+        return Object.keys(this.auth).length > 0;
+    }
+    async request(path, init = {}) {
+        if (!this.authenticated) {
+            throw new SpendgraphError(401, "no_credentials", "No spendgraph apiKey or session set.");
+        }
+        const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        let last;
+        for (let attempt = 1; attempt <= this.attempts; attempt++) {
+            let res;
+            try {
+                res = await this.doFetch(url, {
+                    ...init,
+                    headers: { "content-type": "application/json", ...this.auth, ...init.headers },
+                });
+            }
+            catch (err) {
+                last = new SpendgraphError(0, "network_error", err.message, {
+                    attempts: attempt,
+                });
+                if (attempt < this.attempts) {
+                    await this.sleep(Math.min(this.maxWaitMs, BACKOFF_BASE_MS * 2 ** (attempt - 1)));
+                    continue;
+                }
+                throw last;
+            }
+            if (res.ok)
+                return (await this.decode(res));
+            last = await this.toError(res, attempt);
+            if (!last.retryable || attempt === this.attempts)
+                throw last;
+            const wait = retryAfterMs(res) ?? BACKOFF_BASE_MS * 2 ** (attempt - 1);
+            await this.sleep(Math.min(this.maxWaitMs, wait));
+        }
+        throw last ?? new SpendgraphError(0, "unknown", "Request failed.");
+    }
+    get(path, query) {
+        return this.request(`${path}${queryString(query)}`);
+    }
+    post(path, body, query) {
+        return this.send("POST", path, body, query);
+    }
+    put(path, body, query) {
+        return this.send("PUT", path, body, query);
+    }
+    patch(path, body, query) {
+        return this.send("PATCH", path, body, query);
+    }
+    delete(path, query) {
+        return this.request(`${path}${queryString(query)}`, { method: "DELETE" });
+    }
+    send(method, path, body, query) {
+        return this.request(`${path}${queryString(query)}`, {
+            method,
+            ...(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;
+        const text = await res.text();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    async toError(res, attempt) {
+        let code = "http_error";
+        let message = `${res.status} ${res.statusText}`.trim();
+        try {
+            const body = (await res.json());
+            if (body?.error?.code)
+                code = body.error.code;
+            if (body?.error?.message)
+                message = body.error.message;
+        }
+        catch { }
+        return new SpendgraphError(res.status, code, message, {
+            attempts: attempt,
+            retryAfterMs: retryAfterMs(res),
+        });
+    }
+}

package/dist/core/client/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare class SpendgraphError extends Error {
+    readonly status: number;
+    /** The API's machine-readable code, when it sent one. */
+    readonly code: string;
+    /** How many attempts were made, so a log line says "gave up after 4". */
+    readonly attempts: number;
+    /** The server's own `retry-after`, in ms. Null when it did not send one. */
+    readonly retryAfterMs: number | null;
+    constructor(status: number, code: string, message: string, opts?: {
+        attempts?: number;
+        retryAfterMs?: number | 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(): boolean;
+}

package/dist/core/client/errors.js

@@ -0,0 +1,31 @@
+/**
+ * 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);
+        this.name = "SpendgraphError";
+        this.status = status;
+        this.code = code;
+        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/core/client/index.d.ts

@@ -0,0 +1,2 @@
+export { Client, queryString } from "./client.js";
+export { SpendgraphError } from "./errors.js";

package/dist/core/client/index.js

@@ -0,0 +1,2 @@
+export { Client, queryString } from "./client.js";
+export { SpendgraphError } from "./errors.js";

package/dist/core/types.d.ts

@@ -0,0 +1,28 @@
+export type Tag = string | number | boolean;
+/** How a request proves who it is. */
+export interface Credentials {
+    /** spendgraph API key (sg_…). Reaches the key-scoped half of the API. */
+    apiKey?: string;
+    /**
+     * A dashboard session cookie. The other half of the API is gated on a signed-in
+     * user and has no API-key path, so a caller without one gets a 401 from the
+     * server rather than a different answer from here.
+     */
+    session?: string;
+    /** Sent on every request, under anything set above. */
+    headers?: Record<string, string>;
+}
+export interface ClientOptions extends Credentials {
+    /** Base URL of your deployed spendgraph app. */
+    baseUrl: string;
+    /** Injected for tests and for runtimes with a non-global fetch. */
+    fetch?: typeof fetch;
+    /** Injected so tests do not actually wait out a backoff. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Total attempts including the first. Default 3. */
+    attempts?: number;
+    /** Never wait longer than this for one backoff. Default 5000. */
+    maxWaitMs?: number;
+}
+/** Query parameters, with undefined dropped rather than sent as "undefined". */
+export type Query = Record<string, string | number | boolean | undefined | null>;

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,124 +1,9 @@
-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;
-}
+export type { SpendgraphOptions } from "./client.js";
+export { Spendgraph } from "./client.js";
+export { Client, queryString, SpendgraphError } from "./core/client/index.js";
+export type { ClientOptions, Credentials as ClientCredentials, Query, Tag } from "./core/types.js";
+export * from "./resources/index.js";
+export type { RolloutInput, RolloutRecord, RolloutStep } from "./rollout/index.js";
+export { type FieldError, type FieldSpec, type FieldType, FieldValidationError, serializeFields, validateFields, } from "./schema/index.js";
+export type { SpendGraphOptions, TrackEvent } from "./track/index.js";
+export { SpendGraph } from "./track/index.js";