@spendgraph/sdk 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/sdk",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Track LLM input/output tokens and cost. Three functions, zero dependencies, fail-open.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,7 +29,6 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./docs/*": "./docs/*",
     "./langchain": {
       "types": "./dist/langchain.d.ts",
       "import": "./dist/langchain.js"
@@ -42,11 +41,10 @@
   },
   "files": [
     "dist",
-    "docs",
     "README.md"
   ],
   "devDependencies": {
-    "@spendgraph/config": "0.8.0",
+    "@spendgraph/config": "0.8.2",
     "typescript": "^5"
   },
   "engines": {

package/docs/client.mdx

@@ -1,85 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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

@@ -1,62 +0,0 @@
-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.