@spendgraph/sdk 0.1.0 → 0.2.1

package/dist/resources/tools.d.ts

@@ -0,0 +1,66 @@
+import type { FieldSpec } from "../schema/index.js";
+import type { Client } from "../core/client/index.js";
+import type { Scoped } from "./prompts.js";
+/** What calling a tool does outside the process. Null means nobody has said. */
+export type ToolEffect = "readonly" | "idempotent" | "destructive";
+/**
+ * A tool's declaration, as stored.
+ *
+ * The handler is not here and never will be: this is what the model is told,
+ * and the function it maps to lives in the caller's codebase.
+ */
+export interface ToolRow {
+    id: string;
+    projectId: string;
+    name: string;
+    description: string;
+    args: FieldSpec[];
+    effect: ToolEffect | null;
+    pinned: boolean;
+    archivedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SaveToolInput {
+    projectId: string;
+    name: string;
+    description: string;
+    args?: FieldSpec[];
+    effect?: ToolEffect | null;
+    pinned?: boolean;
+}
+/**
+ * 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 declare class Tools {
+    private readonly client;
+    constructor(client: Client);
+    list(query?: Scoped & {
+        limit?: number;
+        cursor?: string;
+        archived?: "only" | "active" | "all";
+    }): Promise<{
+        tools: ToolRow[];
+        nextCursor: string | null;
+    }>;
+    /** One tool, addressed by uuid or by the name the model calls. */
+    get(name: string, query?: Scoped): Promise<{
+        tool: ToolRow;
+    }>;
+    create(body: SaveToolInput): Promise<{
+        tool: ToolRow;
+    }>;
+    update(id: string, body: SaveToolInput, query?: Scoped): Promise<{
+        tool: ToolRow;
+    }>;
+    /** Out of the list, not destroyed. `archived: false` brings it back. */
+    archive(id: string, archived: boolean, query?: Scoped): Promise<{
+        id: string;
+        archivedAt: string | null;
+        unchanged?: boolean;
+    }>;
+}

package/dist/resources/tools.js

@@ -0,0 +1,21 @@
+export class Tools {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(query = {}) {
+        return this.client.get("/api/v1/tools", { ...query });
+    }
+    get(name, query = {}) {
+        return this.client.get(`/api/v1/tools/${encodeURIComponent(name)}`, { ...query });
+    }
+    create(body) {
+        return this.client.post("/api/v1/tools", body);
+    }
+    update(id, body, query = {}) {
+        return this.client.patch(`/api/v1/tools/${encodeURIComponent(id)}`, body, { ...query });
+    }
+    archive(id, archived, query = {}) {
+        return this.client.post(`/api/v1/tools/${encodeURIComponent(id)}/archive`, { archived }, { ...query });
+    }
+}

package/dist/rollout/index.d.ts

@@ -0,0 +1 @@
+export type { RolloutInput, RolloutRecord, RolloutStep } from "./rollout.js";

package/dist/rollout/index.js

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

package/dist/rollout/rollout.d.ts

@@ -0,0 +1,75 @@
+import type { RenderedMessage as Message } from "../resources/prompts.js";
+/**
+ * The record every capability writes.
+ *
+ * A prompt run is a rollout with one step. A graph run is a rollout with
+ * several. The `steps` column exists in `prompt_rollouts` from the first
+ * migration for exactly that reason, so the shape lives here rather than under
+ * `prompt/` — a second copy is how the two capabilities end up disagreeing
+ * about what a rollout is.
+ */
+/** One unit of work inside a rollout. A prompt run has one; an agent run many. */
+export interface RolloutStep {
+    /** Position in the run, so a failure can be attributed to a step. */
+    index: number;
+    /** What produced it — a prompt id, a tool name, a node name. */
+    source: string;
+    model?: string;
+    input?: unknown;
+    output?: string;
+    status?: "completed" | "failed";
+    error?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    latencyMs?: number;
+}
+/** What a caller hands back after running something itself. */
+export interface RolloutInput {
+    /** Dedupe key. Generated if omitted; supply your own to make a retry safe. */
+    rolloutId?: string;
+    versionId?: string | null;
+    model: string;
+    fields: Record<string, string>;
+    rendered: Message[];
+    output: string;
+    status?: "completed" | "failed";
+    error?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    citationTokens?: number;
+    reasoningTokens?: number;
+    latencyMs?: number;
+    /**
+     * The steps a multi-step run took. Absent for a single prompt call, which is
+     * the same thing with one step and nothing worth listing.
+     */
+    steps?: RolloutStep[];
+    /**
+     * The tools this run was offered, whether or not it called them.
+     *
+     * Without it a rollout cannot answer the first question anyone asks of a
+     * tool-using agent that got something wrong: was the tool it needed even in
+     * front of it? "Chose not to call `refund`" and "was never shown `refund`"
+     * produce identical records and want opposite fixes. Selection makes this
+     * sharper, not softer, because the offered set now varies per turn.
+     */
+    offeredTools?: string[];
+    /** Set only for evaluation rollouts. Production traffic leaves it unset. */
+    caseId?: string;
+    seed?: number;
+    candidateId?: string;
+    parentId?: string;
+    generation?: number;
+}
+/** What the server returns once it has priced and stored one. */
+export interface RolloutRecord {
+    rolloutId: string;
+    status: "completed" | "failed";
+    output: string;
+    costMicros: number;
+    latencyMs: number;
+    inputTokens: number;
+    outputTokens: number;
+}

package/dist/rollout/rollout.js

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

package/dist/schema/index.d.ts

@@ -0,0 +1,3 @@
+export { serializeFields } from "./serialize/index.js";
+export type { FieldSpec, FieldType } from "./types/index.js";
+export { type FieldError, FieldValidationError, validateFields } from "./validate/index.js";

package/dist/schema/index.js

@@ -0,0 +1,2 @@
+export { serializeFields } from "./serialize/index.js";
+export { FieldValidationError, validateFields } from "./validate/index.js";

package/dist/schema/serialize/index.d.ts

@@ -0,0 +1 @@
+export { serializeFields } from "./serialize.js";

package/dist/schema/serialize/index.js

@@ -0,0 +1 @@
+export { serializeFields } from "./serialize.js";

package/dist/schema/serialize/serialize.d.ts

@@ -0,0 +1,12 @@
+import type { FieldSpec } from "../types/index.js";
+/**
+ * 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 declare function serializeFields(values: Record<string, unknown>, spec: FieldSpec[]): Record<string, string>;

package/dist/schema/serialize/serialize.js

@@ -0,0 +1,31 @@
+import { FieldValidationError, isMissing, toBoolean, toNumber, validateFields, } from "../validate/index.js";
+function renderOne(field, value) {
+    switch (field.type) {
+        case "number":
+            return String(toNumber(value));
+        case "boolean":
+            return toBoolean(value) ? (field.trueText ?? "true") : (field.falseText ?? "false");
+        case "list":
+            return value.map(String).join(field.separator ?? ", ");
+        case "json":
+            return JSON.stringify(value, null, 2);
+        default:
+            return String(value);
+    }
+}
+export function serializeFields(values, spec) {
+    const errors = validateFields(values, spec);
+    if (errors.length)
+        throw new FieldValidationError(errors);
+    const out = {};
+    for (const field of spec) {
+        const value = values[field.name];
+        if (isMissing(value)) {
+            if (field.default !== undefined)
+                out[field.name] = field.default;
+            continue;
+        }
+        out[field.name] = renderOne(field, value);
+    }
+    return out;
+}

package/dist/schema/types/index.d.ts

@@ -0,0 +1 @@
+export type { FieldSpec, FieldType } from "./types.js";

package/dist/schema/types/index.js

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

package/dist/schema/types/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Typed prompt fields — what a `{placeholder}` accepts, and how it renders.
+ *
+ * Deliberately a copy of `lib/fields.ts` rather than an import. This package is
+ * published and depends on nothing; reaching into the app for a type would make
+ * every installed copy break the next time the app moved a file. The two are
+ * kept in step by the wire format, which is the only contract that matters.
+ *
+ * A field type is two things, and the second is the one that gets forgotten: an
+ * input contract, and a rendering rule. Everything ends up interpolated into a
+ * string, so `{max_words}` given `50` has to become `"50"` and `{tags}` given
+ * `["a","b"]` has to become something the prompt author chose rather than
+ * whatever the first implementation happened to do.
+ *
+ * Deliberately not called `Variable`: a tool's arguments and an agent node's
+ * inputs are the same problem, and naming this after prompts guarantees it gets
+ * written twice more with three different meanings for `required`.
+ */
+export type FieldType = "string" | "text" | "number" | "boolean" | "enum" | "list" | "json";
+export interface FieldSpec {
+    /** Matches the `{placeholder}` in the blocks or question. */
+    name: string;
+    type: FieldType;
+    /** A missing required field throws before anything is sent. */
+    required: boolean;
+    /**
+     * Substituted verbatim when the field is absent — already-rendered text, not
+     * a value to coerce. A `list` default is the joined string, a `json` default
+     * is the printed JSON. Authored once by a human rather than typed per run, so
+     * asking for it in final form is simpler than parsing it back per type.
+     */
+    default?: string;
+    /**
+     * What the field means. Shown in the UI, and given to the optimizer's
+     * reflector — knowing what a field is *for* is the difference between a
+     * useful prompt mutation and a guess.
+     */
+    description?: string;
+    /** `enum` — the permitted values. */
+    options?: string[];
+    /** `list` — what joins the items. Defaults to ", ". */
+    separator?: string;
+    /** `number` — inclusive bounds. */
+    min?: number;
+    max?: number;
+    /** `string` | `text` — rejected above this length. */
+    maxLength?: number;
+    /** `boolean` — words to render instead of "true"/"false". */
+    trueText?: string;
+    falseText?: string;
+    /**
+     * This is the field a dataset varies.
+     *
+     * A prompt declaring `{question}` plus 200 stored values for it *is* a
+     * 200-case dataset; this flag is what says which field those values fill.
+     */
+    datasetKey?: boolean;
+}

package/dist/schema/types/types.js

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

package/dist/schema/validate/index.d.ts

@@ -0,0 +1 @@
+export { type FieldError, FieldValidationError, isMissing, toBoolean, toNumber, validateFields, } from "./validate.js";

package/dist/schema/validate/index.js

@@ -0,0 +1 @@
+export { FieldValidationError, isMissing, toBoolean, toNumber, validateFields, } from "./validate.js";

package/dist/schema/validate/validate.d.ts

@@ -0,0 +1,28 @@
+import type { FieldSpec } from "../types/index.js";
+export type FieldError = {
+    field: string;
+    message: string;
+};
+export declare class FieldValidationError extends Error {
+    readonly errors: FieldError[];
+    constructor(errors: FieldError[]);
+}
+/** Absent means absent. An empty string is a value someone chose to send. */
+export declare function isMissing(value: unknown): boolean;
+/**
+ * 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 declare function toNumber(value: unknown): number;
+export declare function toBoolean(value: unknown): boolean;
+/**
+ * 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 declare function validateFields(values: Record<string, unknown>, spec: FieldSpec[]): FieldError[];

package/dist/schema/validate/validate.js

@@ -0,0 +1,92 @@
+export class FieldValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(errors.map((e) => `${e.field}: ${e.message}`).join("; "));
+        this.name = "FieldValidationError";
+        this.errors = errors;
+    }
+}
+export function isMissing(value) {
+    return value === undefined || value === null;
+}
+export function toNumber(value) {
+    return typeof value === "number" ? value : Number(String(value).trim());
+}
+export function toBoolean(value) {
+    return typeof value === "boolean" ? value : String(value).toLowerCase() === "true";
+}
+function checkText(field, value) {
+    const text = String(value);
+    return field.maxLength !== undefined && text.length > field.maxLength
+        ? `is ${text.length} characters, over the limit of ${field.maxLength}`
+        : null;
+}
+function checkNumber(field, value) {
+    const n = toNumber(value);
+    if (!Number.isFinite(n))
+        return `expects a number, got ${JSON.stringify(value)}`;
+    if (field.min !== undefined && n < field.min)
+        return `is ${n}, below the minimum of ${field.min}`;
+    if (field.max !== undefined && n > field.max)
+        return `is ${n}, above the maximum of ${field.max}`;
+    return null;
+}
+function checkBoolean(value) {
+    if (typeof value === "boolean")
+        return null;
+    const s = String(value).toLowerCase();
+    return s === "true" || s === "false"
+        ? null
+        : `expects true or false, got ${JSON.stringify(value)}`;
+}
+function checkEnum(field, value) {
+    const options = field.options ?? [];
+    if (options.length === 0)
+        return "is an enum with no options declared";
+    return options.includes(String(value))
+        ? null
+        : `must be one of ${options.join(" | ")}, got ${JSON.stringify(value)}`;
+}
+function checkJson(value) {
+    try {
+        JSON.stringify(value);
+        return null;
+    }
+    catch (err) {
+        return `is not serialisable: ${err.message}`;
+    }
+}
+function checkOne(field, value) {
+    switch (field.type) {
+        case "string":
+        case "text":
+            return checkText(field, value);
+        case "number":
+            return checkNumber(field, value);
+        case "boolean":
+            return checkBoolean(value);
+        case "enum":
+            return checkEnum(field, value);
+        case "list":
+            return Array.isArray(value) ? null : `expects an array, got ${typeof value}`;
+        case "json":
+            return checkJson(value);
+    }
+}
+export function validateFields(values, spec) {
+    const errors = [];
+    for (const field of spec) {
+        const value = values[field.name];
+        if (isMissing(value)) {
+            if (field.default !== undefined)
+                continue;
+            if (field.required)
+                errors.push({ field: field.name, message: "is required" });
+            continue;
+        }
+        const problem = checkOne(field, value);
+        if (problem)
+            errors.push({ field: field.name, message: problem });
+    }
+    return errors;
+}

package/dist/track/index.d.ts

@@ -0,0 +1,2 @@
+export type { SpendGraphOptions, TrackEvent } from "./track.js";
+export { SpendGraph } from "./track.js";

package/dist/track/index.js

@@ -0,0 +1 @@
+export { SpendGraph } from "./track.js";

package/dist/track/track.d.ts

@@ -0,0 +1,209 @@
+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;
+    /**
+     * Billed on their own by search-grounded providers — Perplexity Sonar Deep
+     * Research charges both at rates that are neither input nor output. Leave
+     * them unset for every other provider; OpenAI's `reasoning_tokens` are
+     * already counted inside `completion_tokens` and would be billed twice.
+     */
+    citationTokens?: number;
+    reasoningTokens?: 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;
+    private streamUsageWarned;
+    /** The flush currently on the wire, so a later flush() can wait for it. */
+    private inFlight;
+    constructor(opts: SpendGraphOptions);
+    /**
+     * 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.
+     */
+    private clientFor;
+    /** 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.
+     *
+     * 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.
+     */
+    flush(): Promise<void>;
+    /** One pass: stop the timer, take the queue, put it on the wire. */
+    private drain;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    private proxy;
+    private observeResult;
+    private interceptStream;
+    /** Accumulate usage off a tee'd SSE branch (Anthropic events / OpenAI chunks). */
+    private consumeStream;
+    /**
+     * 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.
+     */
+    private warnStreamNoUsage;
+    private trackFromResponse;
+    private send;
+    /**
+     * 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.
+     */
+    private onSendFailed;
+    /**
+     * 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;
+}