@spendgraph/sdk 0.1.0 → 0.2.0

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,30 @@
+/**
+ * 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) {
+        this.client = client;
+    }
+    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 });
+    }
+    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 });
+    }
+    /** 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/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,42 @@
+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":
+            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);
+    }
+}
+/**
+ * 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)
+        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,108 @@
+export class FieldValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(errors.map((e) => `${e.field}: ${e.message}`).join("; "));
+        this.name = "FieldValidationError";
+        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());
+}
+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)}`;
+}
+/** Catches cycles and BigInt, which otherwise reach the provider as a crash. */
+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);
+    }
+}
+/**
+ * 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) {
+        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; // optional and unset — the placeholder stays visible
+        }
+        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";