@spendgraph/sdk 0.1.0 → 0.2.1

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>;
+}

package/dist/resources/ingest.js

@@ -0,0 +1,27 @@
+export const MAX_EVENTS = 100;
+export class Ingest {
+    client;
+    project;
+    constructor(client, project) {
+        this.client = client;
+        this.project = project;
+    }
+    async send(events) {
+        await this.report(events);
+    }
+    async report(events) {
+        const total = { accepted: 0, rejected: 0, unpricedModels: [] };
+        if (events.length === 0)
+            return total;
+        const unpriced = new Set();
+        for (let i = 0; i < events.length; i += MAX_EVENTS) {
+            const res = await this.client.post("/api/v1/ingest", { events: events.slice(i, i + MAX_EVENTS) }, { project: this.project });
+            total.accepted += res?.accepted ?? 0;
+            total.rejected += res?.rejected ?? 0;
+            for (const model of res?.unpricedModels ?? [])
+                unpriced.add(model);
+        }
+        total.unpricedModels = [...unpriced];
+        return total;
+    }
+}

package/dist/resources/keys.d.ts

@@ -0,0 +1,34 @@
+import type { Client } from "../core/client/index.js";
+export interface ApiKeyRow {
+    id: string;
+    name: string;
+    projectId: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+}
+/**
+ * API keys. Dashboard session only, deliberately: a key that could mint keys
+ * would turn one leaked ingest credential into permanent access.
+ */
+export declare class Keys {
+    private readonly client;
+    constructor(client: Client);
+    list(query?: {
+        project?: string;
+    }): Promise<{
+        keys: ApiKeyRow[];
+    }>;
+    /** The plaintext key is in this response and nowhere else, ever again. */
+    create(body: {
+        projectId: string;
+        name: string;
+    }): Promise<{
+        key: ApiKeyRow & {
+            plaintext: string;
+        };
+    }>;
+    revoke(keyId: string): Promise<{
+        revoked: boolean;
+    }>;
+}

package/dist/resources/keys.js

@@ -0,0 +1,15 @@
+export class Keys {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(query = {}) {
+        return this.client.get("/api/v1/keys", { ...query });
+    }
+    create(body) {
+        return this.client.post("/api/v1/keys", body);
+    }
+    revoke(keyId) {
+        return this.client.delete(`/api/v1/keys/${encodeURIComponent(keyId)}`);
+    }
+}

package/dist/resources/playground.d.ts

@@ -0,0 +1,7 @@
+import type { Client } from "../core/client/index.js";
+/** Ad-hoc runs from the dashboard, streamed. Dashboard session only. */
+export declare class Playground {
+    private readonly client;
+    constructor(client: Client);
+    run(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+}

package/dist/resources/playground.js

@@ -0,0 +1,9 @@
+export class Playground {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    run(body) {
+        return this.client.post("/api/v1/playground/run", body);
+    }
+}

package/dist/resources/pricing.d.ts

@@ -0,0 +1,49 @@
+import type { Client } from "../core/client/index.js";
+export interface PricingRow {
+    model: string;
+    provider: string;
+    inputPerMtokMicros: number;
+    outputPerMtokMicros: number;
+    cacheReadPerMtokMicros: number | null;
+    cacheWritePerMtokMicros: number | null;
+    /** Flat charge per call — Perplexity bills one for the search behind Sonar. */
+    perRequestMicros: number | null;
+}
+/** The pricing catalogue. Dashboard session only. */
+export declare class Pricing {
+    private readonly client;
+    constructor(client: Client);
+    list(): Promise<Record<string, unknown>>;
+    /** A manual override for one model, which outranks the synced rows. */
+    override(model: string, body: Record<string, unknown>): Promise<{
+        pricing: PricingRow;
+    }>;
+    /** Which models the catalogue can price, and which it cannot. */
+    coverage(): Promise<Record<string, unknown>>;
+    /** What legacy and offer-based pricing would each charge, side by side. */
+    readiness(): Promise<Record<string, unknown>>;
+    sync(body?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+/** The model catalogue and the offers behind it. Dashboard session only. */
+export declare class Models {
+    private readonly client;
+    constructor(client: Client);
+    list(query?: {
+        creator?: string;
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+    offers(query?: {
+        model?: string;
+        q?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Prices one workload across models or serving providers. */
+    compare(query?: {
+        models?: string;
+        offers?: string;
+        baseline?: string;
+        benchmark?: string;
+        in?: number;
+        out?: number;
+        requests?: number;
+    }): Promise<Record<string, unknown>>;
+}

package/dist/resources/pricing.js

@@ -0,0 +1,36 @@
+export class Pricing {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list() {
+        return this.client.get("/api/v1/pricing");
+    }
+    override(model, body) {
+        return this.client.put(`/api/v1/pricing/${encodeURIComponent(model)}`, body);
+    }
+    coverage() {
+        return this.client.get("/api/v1/pricing/coverage");
+    }
+    readiness() {
+        return this.client.get("/api/v1/pricing/readiness");
+    }
+    sync(body = {}) {
+        return this.client.post("/api/v1/pricing/sync", body);
+    }
+}
+export class Models {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(query = {}) {
+        return this.client.get("/api/v1/models", { ...query });
+    }
+    offers(query = {}) {
+        return this.client.get("/api/v1/offers", { ...query });
+    }
+    compare(query = {}) {
+        return this.client.get("/api/v1/compare", { ...query });
+    }
+}

package/dist/resources/projects.d.ts

@@ -0,0 +1,54 @@
+import type { Client } from "../core/client/index.js";
+export interface ProjectRow {
+    id: string;
+    name: string;
+    createdAt: string;
+}
+export interface Budget {
+    monthlyLimitMicros: number | null;
+    alertThresholdPct: number | null;
+}
+/** Projects, their budgets, members and invites. Dashboard session only. */
+export declare class Projects {
+    private readonly client;
+    constructor(client: Client);
+    list(): Promise<{
+        projects: ProjectRow[];
+    }>;
+    create(body: {
+        name: string;
+    }): Promise<{
+        project: ProjectRow;
+    }>;
+    budget(projectId: string): Promise<{
+        budget: Budget;
+    }>;
+    setBudget(projectId: string, body: Partial<Budget>): Promise<{
+        ok: boolean;
+    }>;
+    members(projectId: string): Promise<Record<string, unknown>>;
+    addMember(projectId: string, body: Record<string, unknown>): Promise<{
+        ok: boolean;
+    }>;
+    removeMember(projectId: string, userId: string): Promise<{
+        ok: boolean;
+    }>;
+    invite(projectId: string, body: Record<string, unknown>): Promise<{
+        ok: boolean;
+        added?: unknown;
+    }>;
+    revokeInvite(projectId: string, inviteId: string): Promise<{
+        ok: boolean;
+    }>;
+}
+/** Accepting an invite is the one project call that identifies a person, not a key. */
+export declare class Invites {
+    private readonly client;
+    constructor(client: Client);
+    preview(token: string): Promise<{
+        project: ProjectRow;
+    }>;
+    accept(token: string): Promise<{
+        project: ProjectRow;
+    }>;
+}

package/dist/resources/projects.js

@@ -0,0 +1,49 @@
+export class Projects {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list() {
+        return this.client.get("/api/v1/projects");
+    }
+    create(body) {
+        return this.client.post("/api/v1/projects", body);
+    }
+    budget(projectId) {
+        return this.client.get(`/api/v1/projects/${encodeURIComponent(projectId)}/budget`);
+    }
+    setBudget(projectId, body) {
+        return this.client.put(`/api/v1/projects/${encodeURIComponent(projectId)}/budget`, body);
+    }
+    members(projectId) {
+        return this.client.get(`/api/v1/projects/${encodeURIComponent(projectId)}/members`);
+    }
+    addMember(projectId, body) {
+        return this.client.post(`/api/v1/projects/${encodeURIComponent(projectId)}/members`, body);
+    }
+    removeMember(projectId, userId) {
+        return this.client.delete(`/api/v1/projects/${encodeURIComponent(projectId)}/members`, {
+            userId,
+        });
+    }
+    invite(projectId, body) {
+        return this.client.post(`/api/v1/projects/${encodeURIComponent(projectId)}/invites`, body);
+    }
+    revokeInvite(projectId, inviteId) {
+        return this.client.delete(`/api/v1/projects/${encodeURIComponent(projectId)}/invites`, {
+            inviteId,
+        });
+    }
+}
+export class Invites {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    preview(token) {
+        return this.client.get("/api/v1/invites/accept", { token });
+    }
+    accept(token) {
+        return this.client.post("/api/v1/invites/accept", { token });
+    }
+}

package/dist/resources/prompts-admin.d.ts

@@ -0,0 +1,23 @@
+import type { Client } from "../core/client/index.js";
+import type { Scoped } from "./prompts.js";
+/**
+ * The prompt operations gated on a dashboard session — publishing a version,
+ * archiving a prompt, starting an optimization run, and reading run history.
+ */
+export declare class PromptsAdmin {
+    private readonly client;
+    constructor(client: Client);
+    publish(promptId: string, body?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    archive(promptId: string, query?: Scoped): Promise<Record<string, unknown>>;
+    /** Starts an optimization run. The budget is required, never defaulted. */
+    assay(promptId: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    runs(query?: {
+        project?: string;
+        limit?: number;
+    }): Promise<{
+        runs: unknown[];
+    }>;
+    run(runId: string): Promise<{
+        run: unknown;
+    }>;
+}

package/dist/resources/prompts-admin.js

@@ -0,0 +1,21 @@
+export class PromptsAdmin {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    publish(promptId, body = {}) {
+        return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/publish`, body);
+    }
+    archive(promptId, query = {}) {
+        return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/archive`, {}, { ...query });
+    }
+    assay(promptId, body) {
+        return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/assay`, body);
+    }
+    runs(query = {}) {
+        return this.client.get("/api/v1/prompts/runs", { ...query });
+    }
+    run(runId) {
+        return this.client.get(`/api/v1/prompts/runs/${encodeURIComponent(runId)}`);
+    }
+}

package/dist/resources/prompts.d.ts

@@ -0,0 +1,124 @@
+import type { Client } from "../core/client/index.js";
+export type Role = "system" | "user" | "assistant";
+export interface RenderedMessage {
+    role: Role;
+    content: string;
+}
+export interface PromptBlock {
+    title?: string;
+    body?: string;
+}
+export interface SavePromptInput {
+    projectId: string;
+    name: string;
+    blocks?: PromptBlock[];
+    variables?: Record<string, string>;
+    question?: string;
+    models?: string[];
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface ReportRolloutInput {
+    /** Chosen by the caller so a retried report writes one row, not two. */
+    rolloutId: string;
+    versionId?: string | null;
+    model: string;
+    fields?: Record<string, string>;
+    rendered: RenderedMessage[];
+    output?: string;
+    status?: "completed" | "failed";
+    error?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    citationTokens?: number;
+    reasoningTokens?: number;
+    latencyMs?: number;
+    caseId?: string;
+    /** Which repetition this is. pass^k needs it even when k is 1. */
+    seed?: number;
+    candidateId?: string;
+    parentId?: string;
+    generation?: number;
+}
+export interface RunPromptInput {
+    rolloutId: string;
+    [key: string]: unknown;
+}
+export interface DatasetCase {
+    caseId: string;
+    fieldValues?: Record<string, string>;
+    expected?: string | null;
+    split?: "feedback" | "held_out";
+}
+export interface Scoped {
+    project?: string;
+}
+/**
+ * Stored prompts, their versions, datasets and rollouts.
+ *
+ * This is the half of the API a job uses: every method here takes an API key.
+ * Publishing, archiving and optimizing are on the dashboard half — see
+ * `PromptsAdmin`.
+ */
+export declare class Prompts {
+    private readonly client;
+    constructor(client: Client);
+    list(query?: Scoped & {
+        limit?: number;
+        cursor?: string;
+        archived?: boolean;
+    }): Promise<{
+        prompts: unknown[];
+        nextCursor?: string | null;
+    }>;
+    create(body: SavePromptInput): Promise<{
+        prompt: unknown;
+    }>;
+    /** One prompt with its current version. `runs` asks for its recent runs too. */
+    get<T = Record<string, unknown>>(promptId: string, query?: Scoped & {
+        runs?: number;
+    }): Promise<T>;
+    update(promptId: string, body: SavePromptInput, query?: Scoped): Promise<Record<string, unknown>>;
+    versions<T = Record<string, unknown>>(promptId: string, query?: Scoped & {
+        limit?: number;
+        origin?: string;
+    }): Promise<T>;
+    /** Promotes a stored version to current. Unchanged text is a no-op, not a fork. */
+    promote(promptId: string, versionId: string, query?: Scoped): Promise<{
+        promoted: string;
+        unchanged?: boolean;
+    }>;
+    cases<T = Record<string, unknown>>(promptId: string, query?: Scoped): Promise<T>;
+    /** Replaces the dataset. Splits are derived, so a case never moves between them. */
+    putCases<T = {
+        counts: unknown;
+        problem: unknown;
+    }>(promptId: string, cases: DatasetCase[], query?: Scoped): Promise<T>;
+    rollouts(promptId: string, query?: Scoped & {
+        limit?: number;
+        cursor?: string;
+        evaluation?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Records a rollout the caller ran itself. Dedupes on `rolloutId`.
+     *
+     * `priced` is false where no pricing row covered the model. The stored cost
+     * is zero either way — the column is `notNull` — so this flag is the only
+     * thing telling a free call apart from an unpriced one.
+     */
+    report(promptId: string, body: ReportRolloutInput, query?: Scoped): Promise<{
+        rollout: unknown;
+        deduped?: boolean;
+        priced?: boolean;
+    }>;
+    /** Runs the prompt server-side, where the spec, rendering and pricing already live. */
+    run<T = {
+        rollout: unknown;
+        recorded?: boolean;
+        note?: string | null;
+        deduped?: boolean;
+        priced?: boolean;
+    }>(promptId: string, body: RunPromptInput, query?: Scoped): Promise<T>;
+}

package/dist/resources/prompts.js

@@ -0,0 +1,49 @@
+export class Prompts {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(query = {}) {
+        return this.client.get("/api/v1/prompts", { ...query });
+    }
+    create(body) {
+        return this.client.post("/api/v1/prompts", body);
+    }
+    get(promptId, query = {}) {
+        return this.client.get(`/api/v1/prompts/${encodeURIComponent(promptId)}`, { ...query });
+    }
+    update(promptId, body, query = {}) {
+        return this.client.put(`/api/v1/prompts/${encodeURIComponent(promptId)}`, body, { ...query });
+    }
+    versions(promptId, query = {}) {
+        return this.client.get(`/api/v1/prompts/${encodeURIComponent(promptId)}/versions`, {
+            ...query,
+        });
+    }
+    promote(promptId, versionId, query = {}) {
+        return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/versions`, { versionId }, { ...query });
+    }
+    cases(promptId, query = {}) {
+        return this.client.get(`/api/v1/prompts/${encodeURIComponent(promptId)}/cases`, {
+            ...query,
+        });
+    }
+    putCases(promptId, cases, query = {}) {
+        return this.client.put(`/api/v1/prompts/${encodeURIComponent(promptId)}/cases`, { cases }, { ...query });
+    }
+    rollouts(promptId, query = {}) {
+        return this.client.get(`/api/v1/prompts/${encodeURIComponent(promptId)}/rollouts`, {
+            ...query,
+        });
+    }
+    report(promptId, body, query = {}) {
+        return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/rollouts`, body, {
+            ...query,
+        });
+    }
+    run(promptId, body, query = {}) {
+        return this.client.post(`/api/v1/prompts/${encodeURIComponent(promptId)}/run`, body, {
+            ...query,
+        });
+    }
+}

package/dist/resources/stats.d.ts

@@ -0,0 +1,65 @@
+import type { Client } from "../core/client/index.js";
+/** Shared by every stats read. Defaults to the last 30 days, all visible projects. */
+export interface RangeQuery {
+    /** ISO timestamp. Defaults to 30 days before `to`. */
+    from?: string;
+    /** ISO timestamp. Defaults to now. */
+    to?: string;
+    /** An API key is pinned to its own project and refuses any other. */
+    project?: string;
+}
+export interface Totals {
+    costMicros: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    requests: number;
+}
+export interface Summary {
+    current: Totals;
+    /** The window of the same length immediately before `from`. */
+    previous: Totals;
+    pricing: unknown;
+}
+export interface TimeseriesPoint {
+    day: string;
+    costMicros: number;
+    inputTokens: number;
+    outputTokens: number;
+    requests: number;
+}
+export interface Timeseries {
+    days: TimeseriesPoint[];
+    bucket: string;
+}
+export interface ModelRow {
+    model: string;
+    costMicros: number;
+    inputTokens: number;
+    outputTokens: number;
+    requests: number;
+}
+/**
+ * Spend, read back.
+ *
+ * Every method here takes an API key, so a job can check what it spent without
+ * a dashboard session.
+ */
+export declare class Stats {
+    private readonly client;
+    constructor(client: Client);
+    /** Totals for the window, beside the window before it. */
+    summary(query?: RangeQuery): Promise<Summary>;
+    timeseries(query?: RangeQuery & {
+        bucket?: "day" | "hour";
+    }): Promise<Timeseries>;
+    byModel(query?: RangeQuery): Promise<{
+        models: ModelRow[];
+    }>;
+    byKey(query?: RangeQuery): Promise<Record<string, unknown>>;
+    /** Grouped by one metadata tag. `key` picks which tag. */
+    byTag(query?: RangeQuery & {
+        key?: string;
+    }): Promise<Record<string, unknown>>;
+}

package/dist/resources/stats.js

@@ -0,0 +1,21 @@
+export class Stats {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    summary(query = {}) {
+        return this.client.get("/api/v1/stats/summary", { ...query });
+    }
+    timeseries(query = {}) {
+        return this.client.get("/api/v1/stats/timeseries", { ...query });
+    }
+    byModel(query = {}) {
+        return this.client.get("/api/v1/stats/by-model", { ...query });
+    }
+    byKey(query = {}) {
+        return this.client.get("/api/v1/stats/by-key", { ...query });
+    }
+    byTag(query = {}) {
+        return this.client.get("/api/v1/stats/by-tag", { ...query });
+    }
+}