@spendgraph/sdk 0.5.1 → 0.7.0

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,8 +1,8 @@
 {
   "name": "@spendgraph/sdk",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Track LLM input/output tokens and cost. Three functions, zero dependencies, fail-open.",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fnLog0/spendgraph.git",
@@ -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"
@@ -36,16 +37,14 @@
     "./ai": {
       "types": "./dist/ai.d.ts",
       "import": "./dist/ai.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
-    "test": "vitest run"
-  },
   "devDependencies": {
     "typescript": "^5"
   },
@@ -54,5 +53,9 @@
   },
   "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"
   }
-}
+}