@spendgraph/sdk 0.6.0 → 0.8.0

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { Client } from "./core/client/index.js";
 import type { ClientOptions } from "./core/types.js";
-import { Alerts, Cli, Credentials, Events, Ingest, Invites, Keys, Models, Playground, Pricing, Projects, Prompts, PromptsAdmin, Stats, Tools } from "./resources/index.js";
+import { Alerts, Cli, Credentials, Events, Files, 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;
@@ -35,5 +35,6 @@ export declare class Spendgraph {
     readonly credentials: Credentials;
     readonly playground: Playground;
     readonly tools: Tools;
+    readonly files: Files;
     constructor(opts: SpendgraphOptions);
 }

package/dist/client.js

@@ -1 +1 @@
-import{Client as s}from"./core/client/index.js";import{Alerts as i,Cli as e,Credentials as h,Events as n,Ingest as p,Invites as r,Keys as o,Models as l,Playground as w,Pricing as m,Projects as c,Prompts as a,PromptsAdmin as d,Stats as g,Tools as v}from"./resources/index.js";class u{http;cli;ingest;stats;events;alerts;prompts;promptsAdmin;keys;projects;invites;pricing;models;credentials;playground;tools;constructor(t){this.http=new s(t),this.cli=new e(this.http),this.ingest=new p(this.http,t.project),this.stats=new g(this.http),this.events=new n(this.http),this.alerts=new i(this.http),this.prompts=new a(this.http),this.promptsAdmin=new d(this.http),this.keys=new o(this.http),this.projects=new c(this.http),this.invites=new r(this.http),this.pricing=new m(this.http),this.models=new l(this.http),this.credentials=new h(this.http),this.playground=new w(this.http),this.tools=new v(this.http)}}export{u as Spendgraph};
+import{Client as s}from"./core/client/index.js";import{Alerts as i,Cli as e,Credentials as h,Events as n,Files as p,Ingest as r,Invites as o,Keys as l,Models as w,Playground as m,Pricing as c,Projects as a,Prompts as d,PromptsAdmin as g,Stats as v,Tools as y}from"./resources/index.js";class u{http;cli;ingest;stats;events;alerts;prompts;promptsAdmin;keys;projects;invites;pricing;models;credentials;playground;tools;files;constructor(t){this.http=new s(t),this.cli=new e(this.http),this.ingest=new r(this.http,t.project),this.stats=new v(this.http),this.events=new n(this.http),this.alerts=new i(this.http),this.prompts=new d(this.http),this.promptsAdmin=new g(this.http),this.keys=new l(this.http),this.projects=new a(this.http),this.invites=new o(this.http),this.pricing=new c(this.http),this.models=new w(this.http),this.credentials=new h(this.http),this.playground=new m(this.http),this.tools=new y(this.http),this.files=new p(this.http)}}export{u as Spendgraph};

package/dist/core/concurrency.d.ts

@@ -0,0 +1,2 @@
+/** Maps with at most `limit` in flight, keeping input order whatever order they land in. */
+export declare function mapLimit<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/core/concurrency.js

@@ -0,0 +1 @@
+async function h(t,e,o){const a=new Array(t.length);let r=0;const l=Array.from({length:Math.max(1,Math.min(e,t.length))},async()=>{for(;r<t.length;){const n=r++;a[n]=await o(t[n],n)}});return await Promise.all(l),a}export{h as mapLimit};

package/dist/core/money.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A micro-USD integer as money somebody reads.
+ *
+ * Two decimal places, because that is what a person is owed for a price. The
+ * exception is the one that keeps this honest: an amount that is not zero but
+ * would print as `$0.00` is shown at the full six places instead, with trailing
+ * zeros trimmed. A judge call costing 250 micro-USD is a real cost, and a run
+ * of ten thousand of them is a real bill; rounding each to nothing and summing
+ * is how a report comes to say a paid run was free.
+ *
+ * Formatting only. The arithmetic stays in integers, which is the whole reason
+ * costs are micro-USD.
+ */
+export declare function formatMicros(micros: number, places?: number): string;
+/**
+ * A price in dollars as the micro-USD integer everything else here holds.
+ *
+ * The one place a float is allowed: a price arrives from a rate card, an
+ * invoice or another system as `40.00`, and it has to become an integer once,
+ * here, rather than at every call site with a different rounding. Rounded to
+ * the nearest micro — below that there is nothing to represent.
+ */
+export declare function microsFromUsd(usd: number): number;

package/dist/core/money.js

@@ -0,0 +1 @@
+const c=1e6,u=6,e=(t,n)=>t.toLocaleString("en-US",{minimumFractionDigits:n,maximumFractionDigits:n});function a(t,n=2){if(!Number.isFinite(t))return"$\u2014";const o=t<0?"-":"",r=Math.abs(t)/1e6,i=e(r,n);if(t===0||/[1-9]/.test(i))return`${o}$${i}`;const s=e(r,6).replace(/0+$/,"");return`${o}$${s}`}function m(t){if(!Number.isFinite(t))throw new Error(`${t} is not an amount.`);return Math.round(t*1e6)}export{a as formatMicros,m as microsFromUsd};

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export type { SpendgraphOptions } from "./client.js";
 export { Spendgraph } from "./client.js";
 export { Client, queryString, SpendgraphError } from "./core/client/index.js";
+export { mapLimit } from "./core/concurrency.js";
+export { formatMicros, microsFromUsd } from "./core/money.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";

package/dist/index.js

@@ -1 +1 @@
-import{Spendgraph as e}from"./client.js";import{Client as i,queryString as p,SpendgraphError as a}from"./core/client/index.js";export*from"./resources/index.js";import{totalTokens as d}from"./rollout/index.js";import{FieldValidationError as s,isMissing as f,serializeFields as x,toBoolean as g,toNumber as S,validateFields as h}from"./schema/index.js";import{SpendGraph as u}from"./track/index.js";export{i as Client,s as FieldValidationError,u as SpendGraph,e as Spendgraph,a as SpendgraphError,f as isMissing,p as queryString,x as serializeFields,g as toBoolean,S as toNumber,d as totalTokens,h as validateFields};
+import{Spendgraph as e}from"./client.js";import{Client as i,queryString as p,SpendgraphError as m}from"./core/client/index.js";import{mapLimit as s}from"./core/concurrency.js";import{formatMicros as f,microsFromUsd as l}from"./core/money.js";export*from"./resources/index.js";import{totalTokens as g}from"./rollout/index.js";import{FieldValidationError as S,isMissing as h,serializeFields as c,toBoolean as u,toNumber as E,validateFields as M}from"./schema/index.js";import{SpendGraph as k}from"./track/index.js";export{i as Client,S as FieldValidationError,k as SpendGraph,e as Spendgraph,m as SpendgraphError,f as formatMicros,h as isMissing,s as mapLimit,l as microsFromUsd,p as queryString,c as serializeFields,u as toBoolean,E as toNumber,g as totalTokens,M as validateFields};

package/dist/resources/files.d.ts

@@ -0,0 +1,35 @@
+import type { Client } from "../core/client/index.js";
+export declare const PUBLISH_FROM: readonly ["text", "md", "html"];
+export declare const PUBLISH_TO: readonly ["md", "html", "txt", "pdf"];
+export type PublishFrom = (typeof PUBLISH_FROM)[number];
+export type PublishTo = (typeof PUBLISH_TO)[number];
+export interface PublishInput {
+    projectId?: string;
+    content: string;
+    from: PublishFrom;
+    to: PublishTo;
+    /** The file's name without its extension; `document` when unset. */
+    name?: string;
+}
+/** A file the app rendered and stored, and the public URL it answers on. */
+export interface PublishedFile {
+    id: string;
+    name: string;
+    type: string;
+    bytes: number;
+    key: string;
+    url: string;
+}
+/**
+ * Files the app renders from content and stores for anyone with the link.
+ *
+ * An API key publishes into the one project it is pinned to. Nothing is read
+ * back through here: a published file is public, so its URL is the way in.
+ */
+export declare class Files {
+    private readonly client;
+    constructor(client: Client);
+    publish(body: PublishInput): Promise<{
+        file: PublishedFile;
+    }>;
+}

package/dist/resources/files.js

@@ -0,0 +1 @@
+const e=["text","md","html"],i=["md","html","txt","pdf"];class l{client;constructor(t){this.client=t}publish(t){return this.client.post("/api/v1/files",t)}}export{l as Files,e as PUBLISH_FROM,i as PUBLISH_TO};

package/dist/resources/index.d.ts

@@ -5,6 +5,8 @@ export { Cli } from "./cli.js";
 export { Credentials } from "./credentials.js";
 export type { EventsPage, EventsQuery, UsageEventRow } from "./events.js";
 export { Events } from "./events.js";
+export type { PublishedFile, PublishFrom, PublishInput, PublishTo } from "./files.js";
+export { Files, PUBLISH_FROM, PUBLISH_TO } from "./files.js";
 export type { IngestResult, Sender, UsageEvent } from "./ingest.js";
 export { Ingest, MAX_EVENTS } from "./ingest.js";
 export type { ApiKeyRow } from "./keys.js";

package/dist/resources/index.js

@@ -1 +1 @@
-import{Alerts as t}from"./alerts.js";import{Cli as m}from"./cli.js";import{Credentials as f}from"./credentials.js";import{Events as s}from"./events.js";import{Ingest as i,MAX_EVENTS as l}from"./ingest.js";import{Keys as d}from"./keys.js";import{Playground as g}from"./playground.js";import{Models as E,Pricing as c}from"./pricing.js";import{Invites as y,Projects as C}from"./projects.js";import{Prompts as M}from"./prompts.js";import{PromptsAdmin as T}from"./prompts-admin.js";import{Stats as u}from"./stats.js";import{Tools as N}from"./tools.js";export{t as Alerts,m as Cli,f as Credentials,s as Events,i as Ingest,y as Invites,d as Keys,l as MAX_EVENTS,E as Models,g as Playground,c as Pricing,C as Projects,M as Prompts,T as PromptsAdmin,u as Stats,N as Tools};
+import{Alerts as e}from"./alerts.js";import{Cli as m}from"./cli.js";import{Credentials as f}from"./credentials.js";import{Events as s}from"./events.js";import{Files as l,PUBLISH_FROM as n,PUBLISH_TO as P}from"./files.js";import{Ingest as I,MAX_EVENTS as S}from"./ingest.js";import{Keys as g}from"./keys.js";import{Playground as E}from"./playground.js";import{Models as T,Pricing as _}from"./pricing.js";import{Invites as v,Projects as y}from"./projects.js";import{Prompts as C}from"./prompts.js";import{PromptsAdmin as H}from"./prompts-admin.js";import{Stats as O}from"./stats.js";import{Tools as j}from"./tools.js";export{e as Alerts,m as Cli,f as Credentials,s as Events,l as Files,I as Ingest,v as Invites,g as Keys,S as MAX_EVENTS,T as Models,n as PUBLISH_FROM,P as PUBLISH_TO,E as Playground,_ as Pricing,y as Projects,C as Prompts,H as PromptsAdmin,O as Stats,j as Tools};

package/dist/resources/ingest.d.ts

@@ -19,6 +19,15 @@ export interface IngestResult {
     rejected: number;
     /** Ids nothing could price. Stored at $0 and counted, never rejected. */
     unpricedModels: string[];
+    /**
+     * What each event was priced at, by the `eventId` it was sent with.
+     *
+     * The server prices from the project's resolved offer as it writes the row,
+     * so this is the figure that was stored rather than a second calculation of
+     * it. A caller reporting usage rather than a rollout has no other way to put
+     * a cost on the call it just made.
+     */
+    costs: Record<string, number>;
 }
 /** The route takes up to this many events per request. */
 export declare const MAX_EVENTS = 100;
@@ -31,12 +40,22 @@ export declare const MAX_EVENTS = 100;
 export interface Sender {
     send(events: UsageEvent[]): Promise<void>;
 }
+/** What one event cost, for a caller that sent exactly one. */
+export type OneCost = number | undefined;
 /** 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>;
+    /**
+     * One event, and what it cost — for a caller that wants the figure back.
+     *
+     * `undefined` where the server could not price the model, which it counts at
+     * zero rather than rejecting. A caller can then say "unpriced" instead of
+     * showing a zero that looks measured.
+     */
+    priced(event: UsageEvent): Promise<OneCost>;
     /** The same write, with the server's answer — which ids went unpriced. */
     report(events: UsageEvent[]): Promise<IngestResult>;
 }

package/dist/resources/ingest.js

@@ -1 +1 @@
-const i=100;class p{client;project;constructor(c,e){this.client=c,this.project=e}async send(c){await this.report(c)}async report(c){const e={accepted:0,rejected:0,unpricedModels:[]};if(c.length===0)return e;const r=new Set,o=c.map(t=>({...t,eventId:t.eventId??crypto.randomUUID()}));for(let t=0;t<o.length;t+=100){const n=await this.client.post("/api/v1/ingest",{events:o.slice(t,t+100)},{project:this.project});e.accepted+=n?.accepted??0,e.rejected+=n?.rejected??0;for(const s of n?.unpricedModels??[])r.add(s)}return e.unpricedModels=[...r],e}}export{p as Ingest,i as MAX_EVENTS};
+const i=100;class p{client;project;constructor(e,t){this.client=e,this.project=t}async send(e){await this.report(e)}async priced(e){const t=e.eventId??crypto.randomUUID();return(await this.report([{...e,eventId:t}])).costs[t]}async report(e){const t={accepted:0,rejected:0,unpricedModels:[],costs:{}};if(e.length===0)return t;const r=new Set,o=e.map(c=>({...c,eventId:c.eventId??crypto.randomUUID()}));for(let c=0;c<o.length;c+=100){const s=await this.client.post("/api/v1/ingest",{events:o.slice(c,c+100)},{project:this.project});t.accepted+=s?.accepted??0,t.rejected+=s?.rejected??0;for(const n of s?.unpricedModels??[])r.add(n);Object.assign(t.costs,s?.costs??{})}return t.unpricedModels=[...r],t}}export{p as Ingest,i as MAX_EVENTS};

package/dist/resources/prompts.d.ts

@@ -1,15 +1,27 @@
 import type { Client } from "../core/client/index.js";
-export type Role = "system" | "user" | "assistant";
+/**
+ * A turn as a rollout records it.
+ *
+ * `tool` is here because a conversation that used tools is not three roles
+ * pretending to be two. Narrating a result into a `user` message kept the words
+ * and lost the fact — and it misled the one reader that cared: the summary
+ * takes the last user message as the question when a prompt names no
+ * `question` field, so a tool-using run was captioned with whatever the tool
+ * said back.
+ */
+export type Role = "system" | "user" | "assistant" | "tool";
 export interface RenderedMessage {
     role: Role;
     content: string;
+    /** Which tool answered, on a `tool` turn. Absent on the other three. */
+    name?: string;
 }
 export interface PromptBlock {
     title?: string;
     body?: string;
 }
 export interface SavePromptInput {
-    projectId: string;
+    projectId?: string;
     name: string;
     blocks?: PromptBlock[];
     variables?: Record<string, string>;

package/dist/resources/tools.d.ts

@@ -22,7 +22,7 @@ export interface ToolRow {
     updatedAt: string;
 }
 export interface SaveToolInput {
-    projectId: string;
+    projectId?: string;
     name: string;
     description: string;
     args?: FieldSpec[];

package/dist/rollout/rollout.d.ts

@@ -21,8 +21,25 @@ export interface RolloutStep {
     error?: string;
     inputTokens?: number;
     outputTokens?: number;
+    /**
+     * The four counts a provider bills apart from input and output.
+     *
+     * Optional and usually absent: most steps are a tool call, which has no
+     * tokens at all. A step that made a model call and left them off is saying
+     * the reply did not carry them — which is not the same as a workload that
+     * used no cache, and is why a rollup leaves the key out rather than adding a
+     * zero. The write is billed at a premium and the read at a discount, so a
+     * total built from the first two alone is wrong in both directions at once.
+     */
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    citationTokens?: number;
+    reasoningTokens?: number;
     latencyMs?: number;
 }
+/** The counts beyond input and output, in the order a report reads them. */
+declare const EXTRA: readonly ["cacheReadTokens", "cacheWriteTokens", "citationTokens", "reasoningTokens"];
+type Extra = (typeof EXTRA)[number];
 /**
  * What every step in a rollout adds up to.
  *
@@ -34,7 +51,7 @@ export interface RolloutStep {
 export declare function totalTokens(steps: RolloutStep[]): {
     inputTokens: number;
     outputTokens: number;
-};
+} & Partial<Record<Extra, 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. */
@@ -85,3 +102,4 @@ export interface RolloutRecord {
     inputTokens: number;
     outputTokens: number;
 }
+export {};

package/dist/rollout/rollout.js

@@ -1 +1 @@
-function u(t){return typeof t!="number"||!Number.isFinite(t)||t<0?0:Math.trunc(t)}function r(t){let n=0,o=0;for(const e of t)n+=u(e.inputTokens),o+=u(e.outputTokens);return{inputTokens:n,outputTokens:o}}export{r as totalTokens};
+const c=["cacheReadTokens","cacheWriteTokens","citationTokens","reasoningTokens"];function s(n){return typeof n!="number"||!Number.isFinite(n)||n<0?0:Math.trunc(n)}function u(n){let i=0,r=0;const o={};for(const t of n){i+=s(t.inputTokens),r+=s(t.outputTokens);for(const e of c)t[e]!==void 0&&(o[e]=(o[e]??0)+s(t[e]))}return{inputTokens:i,outputTokens:r,...o}}export{u as totalTokens};

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

@@ -1,7 +1,7 @@
 /**
  * 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
+ * Deliberately a copy of `lib/prompts/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.

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

@@ -15,6 +15,10 @@ export declare function isMissing(value: unknown): boolean;
  * 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.
+ *
+ * A numeric string passing is the point: a value off the wire arrives as text,
+ * and refusing `"40"` for a number field would refuse every form and query
+ * string there is.
  */
 export declare function toNumber(value: unknown): number;
 export declare function toBoolean(value: unknown): boolean;

package/dist/schema/validate/validate.js

@@ -1 +1 @@
-class l extends Error{errors;constructor(e){super(e.map(t=>`${t.field}: ${t.message}`).join("; ")),this.name="FieldValidationError",this.errors=e}}function s(n){return n==null}function u(n){return typeof n=="number"?n:Number(String(n).trim())}function p(n){return typeof n=="boolean"?n:String(n).toLowerCase()==="true"}function c(n,e){const t=String(e);return n.maxLength!==void 0&&t.length>n.maxLength?`is ${t.length} characters, over the limit of ${n.maxLength}`:null}function a(n,e){const t=u(e);return Number.isFinite(t)?n.min!==void 0&&t<n.min?`is ${t}, below the minimum of ${n.min}`:n.max!==void 0&&t>n.max?`is ${t}, above the maximum of ${n.max}`:null:`expects a number, got ${JSON.stringify(e)}`}function m(n){if(typeof n=="boolean")return null;const e=String(n).toLowerCase();return e==="true"||e==="false"?null:`expects true or false, got ${JSON.stringify(n)}`}function f(n,e){const t=n.options??[];return t.length===0?"is an enum with no options declared":t.includes(String(e))?null:`must be one of ${t.join(" | ")}, got ${JSON.stringify(e)}`}function g(n){try{return JSON.stringify(n),null}catch(e){return`is not serialisable: ${e.message}`}}function h(n,e){switch(n.type){case"string":case"text":return c(n,e);case"number":return a(n,e);case"boolean":return m(e);case"enum":return f(n,e);case"list":return Array.isArray(e)?null:`expects an array, got ${typeof e}`;case"json":return g(e)}}function x(n,e){const t=[];for(const r of e){const o=n[r.name];if(s(o)){if(r.default!==void 0)continue;r.required&&t.push({field:r.name,message:"is required"});continue}const i=h(r,o);i&&t.push({field:r.name,message:i})}return t}export{l as FieldValidationError,s as isMissing,p as toBoolean,u as toNumber,x as validateFields};
+class l extends Error{errors;constructor(r){super(r.map(e=>`${e.field}: ${e.message}`).join("; ")),this.name="FieldValidationError",this.errors=r}}function u(n){return n==null}const i=n=>Array.isArray(n);function c(n){return typeof n=="number"?n:i(n)?Number.NaN:Number(String(n).trim())}function x(n){return typeof n=="boolean"?n:i(n)?!1:String(n).toLowerCase()==="true"}function a(n,r){const e=String(r);return n.maxLength!==void 0&&e.length>n.maxLength?`is ${e.length} characters, over the limit of ${n.maxLength}`:null}function f(n,r){const e=c(r);return Number.isFinite(e)?n.min!==void 0&&e<n.min?`is ${e}, below the minimum of ${n.min}`:n.max!==void 0&&e>n.max?`is ${e}, above the maximum of ${n.max}`:null:`expects a number, got ${JSON.stringify(r)}`}function m(n){if(typeof n=="boolean")return null;if(i(n))return`expects true or false, got ${JSON.stringify(n)}`;const r=String(n).toLowerCase();return r==="true"||r==="false"?null:`expects true or false, got ${JSON.stringify(n)}`}function g(n,r){const e=n.options??[];return e.length===0?"is an enum with no options declared":e.includes(String(r))?null:`must be one of ${e.join(" | ")}, got ${JSON.stringify(r)}`}function h(n){try{return JSON.stringify(n),null}catch(r){return`is not serialisable: ${r.message}`}}function p(n,r){switch(n.type){case"string":case"text":return a(n,r);case"number":return f(n,r);case"boolean":return m(r);case"enum":return g(n,r);case"list":return Array.isArray(r)?null:`expects an array, got ${typeof r}`;case"json":return h(r)}}function d(n,r){const e=[];for(const t of r){const o=n[t.name];if(u(o)){if(t.default!==void 0)continue;t.required&&e.push({field:t.name,message:"is required"});continue}const s=p(t,o);s&&e.push({field:t.name,message:s})}return e}export{l as FieldValidationError,u as isMissing,x as toBoolean,c as toNumber,d as validateFields};

package/docs/client.mdx

@@ -0,0 +1,85 @@
+export const meta = {
+  title: "The client — spendgraph docs",
+  description:
+    "Spendgraph is the whole API in one client: prompts, tools, stats, events, keys and projects. One capital letter apart from the meter, and a different thing entirely.",
+};
+
+# The client
+
+`SpendGraph` meters what you spend. `Spendgraph` reads and writes everything else — prompts, tools, stats, events, keys, projects.
+
+```ts
+import { Spendgraph } from "@spendgraph/sdk";
+
+const sg = new Spendgraph({
+  apiKey: process.env.SPENDGRAPH_API_KEY,
+  baseUrl: "https://spendgraph.locusgraph.com",
+});
+
+const { prompts } = await sg.prompts.list();
+const summary = await sg.stats.summary({ from, to });
+```
+
+<Callout tone="trap" title="Two classes, one capital letter apart">
+  `SpendGraph` is the meter — `wrap`, `track`, `flush`. `Spendgraph` is the API client. Both are exported from the package root, autocomplete offers both, and picking the wrong one gives you an object with none of the methods you expected. The meter is the one with the capital G.
+</Callout>
+
+## Why go through it
+
+Every other spendgraph package talks to the app through this client rather than opening a socket of its own. Base URL, auth, retries, backoff and error shapes are decided once, here, instead of five times slightly differently.
+
+If you are adding an endpoint, it gets a method on a resource module before it gets a caller anywhere else.
+
+## Two halves, and the line between them
+
+```
+  sg_… API key      ──▶  usage · stats · events · prompts · tools
+                         read and write, in one pinned project
+
+  session / sgc_…   ──▶  keys · projects · pricing · credentials
+                         gated on a signed-in user, server-side
+```
+
+That split is deliberate and there is no API-key path across it. `credentials` holds provider keys and `keys` mints API keys, so a leaked ingest key that could reach either would be a much worse leak than it is.
+
+```ts
+new Spendgraph({ apiKey: "sg_…", baseUrl });     // the first half
+new Spendgraph({ session: cookie, baseUrl });    // the second
+new Spendgraph({ token: "sgc_…", baseUrl });     // a terminal, via cli.exchange
+```
+
+An `sgc_` token stands in for a person's session anywhere a session is accepted, and unlike a cookie it can be revoked — see `cli.revoke`.
+
+## A key is already pinned
+
+An API key names no project of its own, so the pin is the whole of its authority. `project` on the constructor scopes writes that accept one; it cannot widen anything.
+
+Naming a *different* project in a body comes back `403 project_not_accessible` rather than quietly landing in the key's own project. A write that goes somewhere you did not ask for, under a `200` that says it worked, is worse than a refusal.
+
+## The resources
+
+| | |
+| --- | --- |
+| `sg.stats` | `summary` · `timeseries` · `byModel` · `byKey` · `byTag` |
+| `sg.events` | `list` — raw events, filtered, paged, or as CSV |
+| `sg.ingest` | reporting usage by hand, up to 100 events a call |
+| `sg.prompts` | `list` · `create` · `update` · `promote` · `rollouts` · `report` |
+| `sg.tools` | `list` · `get` · `create` · `update` · `archive` |
+| `sg.alerts` | what budget alerts have fired |
+| `sg.keys` · `sg.projects` · `sg.invites` | the dashboard half |
+| `sg.pricing` · `sg.models` | the price catalogue |
+| `sg.credentials` | provider keys, session-gated |
+| `sg.playground` | what the dashboard's playground calls |
+| `sg.cli` | how a terminal obtains and revokes a token |
+
+## The escape hatch
+
+`sg.http` is the transport underneath. Reach for it only for a route the class does not cover yet — you keep the auth, retries and error handling, and you give up the types.
+
+```ts
+await sg.http.get("/api/v1/something-new");
+```
+
+## Next
+
+What happens when a call fails, and what retries on its own: [Errors and retries](/docs/sdk/errors).

package/docs/errors.mdx

@@ -0,0 +1,82 @@
+export const meta = {
+  title: "Errors and retries — spendgraph docs",
+  description:
+    "One error type carrying the status, the code, and how many attempts it took. The client retries what is worth retrying and nothing else; the meter never throws at all.",
+};
+
+# Errors and retries
+
+The two classes fail in opposite directions, on purpose.
+
+```
+  SpendGraph  (the meter)   ──▶  never throws · drops data rather than
+                                 take your app down with it
+
+  Spendgraph  (the client)  ──▶  throws SpendgraphError · you asked for
+                                 an answer, so a failure is one
+```
+
+A metering call is a side effect and losing one costs you a row on a chart. A read you awaited is the thing your code is about, and swallowing its failure would hand you an empty array that looks like an empty account.
+
+## SpendgraphError
+
+```ts
+import { SpendgraphError } from "@spendgraph/sdk";
+
+try {
+  await sg.stats.summary({ from, to });
+} catch (err) {
+  if (err instanceof SpendgraphError) {
+    err.status;         // 401, 429, 500 — 0 if the connection never landed
+    err.code;           // the API's machine-readable code
+    err.attempts;       // so a log line can say "gave up after 3"
+    err.retryAfterMs;   // what the server asked for, or null
+    err.retryable;      // whether trying again could ever help
+  }
+}
+```
+
+One error type for everything the API can refuse. A caller retrying blind is what that prevents: a 429 is worth waiting out, a 401 never will be, and a message alone cannot tell them apart.
+
+## What retries itself
+
+```
+  429 · 5xx · no connection   ──▶  retried, with backoff
+  400 · 401 · 403 · 404 · 422 ──▶  thrown at once
+```
+
+Retrying a 401 spends the same attempt budget on the same answer. `retryable` encodes that, and the client acts on it before you ever see the error.
+
+| | |
+| --- | --- |
+| `attempts` | total tries including the first. Default **3** |
+| `maxWaitMs` | longest single backoff. Default **5000** |
+| `maxRetryAfterMs` | ceiling on a `retry-after` the server sent. Default **60000** |
+
+```ts
+const sg = new Spendgraph({ apiKey, baseUrl, attempts: 5, maxWaitMs: 2000 });
+```
+
+## `retry-after` wins, but not unbounded
+
+When the server sends `retry-after`, the client waits that long rather than guessing — the server knows when its window reopens and your backoff does not.
+
+The two caps do different jobs, and the difference is worth keeping straight. `maxWaitMs` bounds **our own** backoff and is small. `maxRetryAfterMs` bounds **the server's** instruction and is much larger, because clamping a `retry-after: 600` down to five seconds would retry straight back into the same closed window and burn every remaining attempt for nothing.
+
+Backoff is spread with jitter so a fleet of clients does not wake in lockstep and rebuild the spike that rate-limited them.
+
+<Callout tone="trap" title="Status 0 is not a verdict">
+  A connection that never reached the server has no status code, and treating that as "not retryable" drops spend on every blip. It is retried; a 422 never is, because the same body will be refused the same way and the budget is spent on nothing.
+</Callout>
+
+## Why the meter is different
+
+The SDK's metering half batches events — 5 seconds or 20 events, whichever lands first — and if the server is unreachable it drops them.
+
+That is a trade, stated plainly: a metering library that takes your app down when the meter is having a bad day has failed at something more important than metering. [`flush()`](/docs/sdk/tracking) is how you decide when the risk of losing a batch matters more than the latency of waiting for it.
+
+## Unpriced models are not errors
+
+A model id with no price is accepted, stored at $0, and returned in `unpricedModels` on the ingest response. The SDK logs each unknown id once.
+
+Token counts are never thrown away for want of a price, and a typo in a model name surfaces while you are still wiring things up rather than as an inexplicably empty dashboard a fortnight later.

package/docs/tracking.mdx

@@ -0,0 +1,62 @@
+export const meta = {
+  title: "Tracking — spendgraph docs",
+  description:
+    "The three SDK functions: wrap a client, track an event by hand, and flush before a serverless runtime freezes.",
+};
+
+# Tracking
+
+Three functions. Most apps only ever call the first.
+
+## meter.wrap(client)
+
+A proxy over an Anthropic or OpenAI client. After each call resolves, the provider's own usage block — `usage.input_tokens` or `usage.prompt_tokens` — is read and reported. No per-call code, and no wrapper object to thread through your app.
+
+```ts
+const anthropic = meter.wrap(new Anthropic());
+const openai = meter.wrap(new OpenAI());
+```
+
+It also reads cache counts off the reply, which is the main reason to prefer it over hand-rolling `track()` against a provider that supports caching.
+
+## meter.track(event)
+
+Manual reporting, for any provider or framework:
+
+```ts
+meter.track({
+  model: "gemini-2.5-pro",
+  inputTokens: usage.promptTokenCount,
+  outputTokens: usage.candidatesTokenCount,
+  metadata: { feature: "search" }, // optional, ≤1KB
+  eventId: crypto.randomUUID(),    // optional: retries dedupe server-side
+});
+```
+
+`metadata` is what the **Cost by tenant** and **Cost by feature** breakdowns group on. Two keys you will want on day one are `feature` and either `tenant` or `env` — without them, spend is one undifferentiated number and the dashboard can only tell you that it went up.
+
+`eventId` makes a retry safe. Send the same id twice and the second is discarded server-side rather than double-counted.
+
+## meter.flush()
+
+Sends everything buffered right now.
+
+<Callout tone="trap" title="Serverless runtimes freeze the moment you respond">
+  Vercel functions, Lambda, and Cloudflare Workers stop executing as soon as the response is sent — and the batched events go with them. `await meter.flush()` before returning from a route handler, or you will lose the tail of every request.
+</Callout>
+
+```ts
+export async function POST(req: Request) {
+  const reply = await anthropic.messages.create(/* … */);
+  await meter.flush();
+  return Response.json(reply);
+}
+```
+
+On a long-lived server you can ignore it — the batch timer handles things.
+
+## Unknown models
+
+A model id spendgraph has no price for is still stored, at $0, and flagged on the [Pricing](/pricing) page. Token counts are never thrown away for want of a price.
+
+The ingest response also returns any such id in `unpricedModels`, and the SDK logs each one once. That is deliberate: a typo in a model name should surface while you are still wiring the integration, not as an inexplicably empty dashboard a fortnight later.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Track LLM input/output tokens and cost. Three functions, zero dependencies, fail-open.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,6 +29,7 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./docs/*": "./docs/*",
     "./langchain": {
       "types": "./dist/langchain.d.ts",
       "import": "./dist/langchain.js"
@@ -41,13 +42,11 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
-    "test": "vitest run"
-  },
   "devDependencies": {
+    "@spendgraph/config": "0.8.0",
     "typescript": "^5"
   },
   "engines": {
@@ -55,5 +54,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.tests.json"
   }
-}
+}