@clocknext/sdk 0.11.0 → 0.12.1

package/README.md

@@ -1,12 +1,108 @@
 # @clocknext/sdk
 
-Official ClockNext SDK for Node/TypeScript. Record **usage signals** and manage
-**plans, purchases, invoices, customers, catalogs, and billing** from your
-backend — full coverage of the ClockNext `/api/v1` surface.
+Official TypeScript/JavaScript SDK for ClockNext. Use it from a backend to:
 
-> **Server-side only.** Your `cnk_…` API key has org-wide write access — never
-> ship it to a browser. For embedding the customer portal in a browser, mint a
-> short-lived token with `cnk.portal.createToken()`.
+- record credit, wallet, outcome, and unit usage;
+- read customer usage, balances, plans, invoices, and payments;
+- manage customers, billing plans, purchases, catalogs, webhooks, and portal tokens.
+
+The SDK targets the ClockNext `/api/v1` API and requires Node.js 18 or newer.
+It has zero runtime dependencies and works with native `fetch` in Node, Bun,
+Deno, and edge runtimes.
+
+---
+
+## Read this before you write any code
+
+Two facts decide whether your integration works. Neither is obvious from the
+method signatures, and getting either wrong produces **no error at all**.
+
+### 1. A successful signal call does not mean the usage was recorded
+
+Every `POST /api/v1/signal/*` route answers `202 Accepted` as soon as it has
+written your request to a durable inbox. It is validated and priced afterwards,
+by a background worker. So this resolves successfully even when the signal is
+about to be thrown away:
+
+```ts
+const result = await cnk.signals.credit(
+  { customerId, model: model.modelId, agentKey: credit.agentKey, tokens: { input: 1, output: 1 } },
+  { wait: true },
+);
+// { status: "accepted", usageLog: null, rawId: "...", messageId: "..." }
+```
+
+That is a deliberate trade: metering must never put a billing round-trip on your
+request path. But it means **rejections cannot come back through the promise**.
+A signal is silently discarded if any of these is true:
+
+| Cause | How to avoid it |
+| --- | --- |
+| `customerId` does not exist | create the customer first |
+| `model` is not enabled in your workspace | use a `modelId` from `workspace.models()` verbatim |
+| `agentKey` names no credit / outcome step / unit | read it from `credits.list()`, `outcomes.get()`, `units.list()` |
+| the customer has no active purchase of a plan carrying that entitlement | `plans.create()` then `purchases.create()` |
+| `member` is set to an email that is not a member of that customer | `customers.addMember()` first, or omit `member` |
+| a required field is missing | see the tables below |
+| the allowance is exhausted | top up with `customers.adjustCredit()` etc. |
+
+Three things follow.
+
+**The per-signal verdict lives in the ClockNext dashboard, and only there.**
+Every signal is logged with its outcome — accepted, processed, or failed with a
+reason — on the workspace's signal log. That view is owner-only in the product
+UI by design and is not exposed through this SDK or any API. When usage is not
+being billed and the causes below do not explain it, that log is where you look.
+
+**`onError` does not see worker-side rejections.** It fires when the HTTP
+request itself fails — network, timeout, auth, a `4xx` returned *before* the
+`202`. A signal that was accepted and then rejected during pricing never
+reaches it, because from the SDK's point of view that request succeeded. Pass it
+anyway: it is how you catch a bad API key, an unreachable host, and a dropped
+buffer.
+
+**`signals.list()` is the programmatic check, and it is partial.** It returns
+priced usage logs, each with a `status`, so it can tell you a signal landed and
+whether pricing succeeded. It cannot tell you about a signal that was rejected
+*before* it was ever priced — an unknown `agentKey`, a customer with no plan —
+because no usage log is written for one. Those appear only in the dashboard.
+
+```ts
+const usage = await cnk.signals.list({ customerId });
+
+// Nothing here at all → rejected before pricing. Check the dashboard's log.
+console.log(usage.totals.count);
+
+// Present but not billed → priced and refused; `status` says which.
+for (const log of usage.logs) {
+  if (log.status !== "SUCCESS") console.warn(log.id, log.status);
+}
+```
+
+### 2. Nothing can be metered until five things exist
+
+A signal is not self-contained; it references rows that must already be there.
+The full chain, in order:
+
+```
+enabled model  →  catalog entitlement (credit / outcome / unit, with an agentKey)
+               →  plan containing that entitlement
+               →  purchase linking the customer to the plan
+               →  customer
+```
+
+`customerId`, `model` and `agentKey` are **not strings you can invent**. The
+quick start below discovers each one instead of hard-coding it.
+
+---
+
+## Security: backend only
+
+`cnk_...` API keys have organization-wide access. Never expose one in browser
+code, mobile apps, frontend bundles, or public Git repositories.
+
+Use `cnk.portal.createToken()` on your backend when a browser needs to embed the
+customer portal. The browser should receive only the short-lived portal token.
 
 ## Install
 
@@ -14,374 +110,563 @@ backend — full coverage of the ClockNext `/api/v1` surface.
 npm install @clocknext/sdk
 ```
 
-Requires Node ≥ 18 (native `fetch`). Zero runtime dependencies. Uses only
-Web-standard `fetch` and `crypto`, so it also runs on edge runtimes (Cloudflare
-Workers, Vercel Edge, Deno, Bun).
+## Quick start — zero to a recorded signal
 
-## Quick start
+This is a complete, runnable setup for an empty workspace. Every id is read back
+from the API rather than guessed.
 
 ```ts
 import { ClockNext } from "@clocknext/sdk";
 
-const cnk = new ClockNext({ apiKey: process.env.CLOCKNEXT_API_KEY! });
+const apiKey = process.env.CLOCKNEXT_API_KEY;
+if (!apiKey) throw new Error("CLOCKNEXT_API_KEY is required");
+
+const cnk = new ClockNext({
+  apiKey,
+  // Catches request-level failures (bad key, network, dropped buffer).
+  // Rejections found later, during pricing, are visible only in the dashboard.
+  onError: (error, signal) =>
+    console.error("[clocknext] signal rejected", signal?.type, error),
+});
+
+// 1. Which workspace is this key for? `live` bills real money.
+const { organization } = await cnk.workspace.me();
+console.log(organization.environment); // "sandbox" | "live"
+
+// 2. A model you are allowed to meter against. Use `modelId` VERBATIM.
+const [model] = await cnk.workspace.models({ active: true });
+if (!model) throw new Error("Enable a model in Settings → Models first.");
+
+// 3. A credit type. Its `agentKey` is what signals address.
+let [credit] = await cnk.credits.list({ active: true });
+credit ??= await cnk.credits.create({
+  name: "API credit",
+  agentKey: "api_credit",   // stable, lowercase [a-z0-9._-], unique per org
+  basePrice: 10,
+  marginPercent: 20,
+  pricePerCredit: 12,       // server recomputes this from basePrice × margin
+  tokensPerCredit: 1000,
+});
+
+// 4. A customer.
+const customer = await cnk.customers.create({
+  name: "Acme",
+  email: "billing@acme.com",
+});
+
+// 5. A plan that SELLS that credit, and a purchase linking the two.
+//    Without this step every signal below is silently discarded.
+const plan = await cnk.plans.create({
+  name: "Pro",
+  billingCycle: "MONTHLY",
+  currencyCode: "USD",
+  components: [
+    { type: "CREDIT", billingMode: "ADVANCE", creditId: credit.id, quantity: 10_000 },
+  ],
+});
+await cnk.purchases.create({ customerId: customer.id, planId: plan.id });
 
+// 6. Now a signal can land.
 await cnk.signals.credit({
-  customerId: "cus_123",
-  model: "llama-3.3-70b-versatile", // catalog model id (OrgModel.modelId)
-  agentKey: "api_credit",           // the credit's stable agent key
-  member: "alice@acme.com",
-  tokens: { input: 1200, output: 340, cache: 0 },
+  customerId: customer.id,
+  model: model.modelId,
+  agentKey: credit.agentKey,
+  tokens: { input: 1200, output: 340 },
   custom: { feature: "summarize" },
 });
 
-// Before a serverless function returns (or on shutdown):
+// 7. Required in async mode before the process can exit.
 await cnk.flush();
+
+// 8. Prove it. Ingestion is asynchronous, so allow a moment.
+const usage = await cnk.signals.list({ customerId: customer.id });
+console.log(usage.totals.count, "signals recorded");
 ```
 
-## Recording signals
+A runnable version is in [`examples/node-basic.ts`](./examples/node-basic.ts),
+shipped with the package.
 
-There are three signal types, matching ClockNext's billable primitives. Each has
-a typed helper that enforces the right required fields at compile time, and each
-posts to **its own route** — `/api/v1/signal/credit`, `/signal/wallet`,
-`/signal/outcome`. The signal's `type` is what picks that route; from 0.10 it is
-no longer sent in the body.
+## Signals
 
-> **Migrating from 0.9 or earlier?** Your calling code does not change — same
-> methods, same arguments. What changed is the wire: the SDK now targets the
-> `/api/v1/signal/*` family instead of the deprecated `POST /api/v1/usage`, and
-> the `metric` field is now `composite` (see [Composites](#composites)). Bump the
-> package and you are migrated.
+Signals are billable usage events. Each kind posts to its own route.
 
-`model` is always the **catalog model id** enabled in your org (matched
-case-insensitively against `OrgModel.modelId`). Credits and outcomes are
-referenced by their **stable `agentKey`** (assigned when you create the credit /
-outcome step), not by display name.
+| SDK method | Meter | Required fields |
+| --- | --- | --- |
+| `signals.credit()` | Credit allowance | `customerId`, `model`, `agentKey`, `tokens` |
+| `signals.wallet()` | Customer wallet | `customerId`, `model`, `tokens` |
+| `signals.outcome()` | Outcome workflow step | `customerId`, `model`, `agentKey`, `runId`, `tokens` |
+| `signals.unit()` | Quantity-based unit | `customerId`, `agentKey` |
 
-```ts
-// Credit — metered against a credit (by agentKey); charged at the model's real cost + your margin
-await cnk.signals.credit({ customerId, model: "llama-3.3-70b-versatile", agentKey: "api_credit", tokens: { input: 1200, output: 340 } });
+`signals.track(signal)` is the underlying call the four convenience methods wrap;
+use it when the kind is dynamic.
 
-// Wallet — debits the customer's USD wallet at model cost
-await cnk.signals.wallet({ customerId, model: "openai/gpt-oss-120b", tokens: { input: 800, output: 5000 } });
+### Where each value comes from
 
-// Outcome — one step of a run (agentKey = the OutcomeStep's agent key)
-await cnk.signals.outcome({ customerId, model: "llama-3.3-70b-versatile", agentKey: "resolved_ticket.triage", runId: "ticket_9021", tokens: { input: 600, output: 150 } });
+| Field | Source | Notes |
+| --- | --- | --- |
+| `model` | `workspace.models()` → `modelId` | Use it verbatim. Matching is case-insensitive but the id must exist; `"openai/gpt-4o"` is not the same as `"gpt-4o"`. |
+| `agentKey` (credit) | `credits.list()` → `agentKey` | Case-insensitive. |
+| `agentKey` (outcome) | `outcomes.get(id)` → `steps[].agentKey` | The **step's** key, not the outcome's own `agentKey`. `outcomes.list()` does not return steps. |
+| `agentKey` (unit) | `units.list()` → `agentKey` | Matched **exactly** — keys are stored lowercased. |
+| `member` | `customers.listMembers(id)` → `email` | Optional. **If set to an email that is not a member of this customer, the whole signal is discarded.** Add them with `customers.addMember()` first. |
+| `composite.ref` | `composites.list()` → `refId` | An unknown `ref` is ignored, not rejected — the signal still records. |
+
+### Credit and wallet
+
+```ts
+await cnk.signals.credit({
+  customerId,
+  model: model.modelId,
+  agentKey: credit.agentKey,
+  tokens: { input: 500, output: 120 },
+});
+
+await cnk.signals.wallet({
+  customerId,
+  model: model.modelId,
+  tokens: { input: 500, output: 120 },
+});
 ```
 
+Wallet signals take no `agentKey` — they debit money at the model's cost rather
+than drawing on a named entitlement — and cannot be grouped into a composite.
+
 ### Outcome runs
 
-An outcome is billed per **run**, not per step. Every signal for one run shares a
-`runId` (opaque — any id you can correlate, e.g. your ticket/session id), so a
-step can fire as many times as it needs to. The run bills **once**, when you mark
-the final step `complete: true` — completion is never inferred from step
-coverage. Sending `complete` twice is a safe no-op.
+An outcome is billed once per run, not once per step. Reuse the same `runId` for
+every step and set `complete: true` only on the final one.
 
 ```ts
 const runId = "ticket_9021";
-// each step of the run carries the same runId…
-await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.triage", runId, tokens: { input: 600, output: 150 } });
-await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.verify", runId, tokens: { input: 200, output: 80 } }); // may repeat
-// …and the last one closes (and bills) the run:
-await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.resolve", runId, complete: true, tokens: { input: 500, output: 200 } });
+
+await cnk.signals.outcome({
+  customerId,
+  model: model.modelId,
+  agentKey: "resolved_ticket.triage",   // a STEP key
+  runId,
+  tokens: { input: 600, output: 150 },
+});
+
+await cnk.signals.outcome({
+  customerId,
+  model: model.modelId,
+  agentKey: "resolved_ticket.resolve",
+  runId,
+  complete: true,
+  tokens: { input: 500, output: 200 },
+});
 ```
 
-### Composites
+A step may repeat within a run — a verify loop firing three times is three
+signals and one outcome. `complete: true` twice is a safe no-op.
 
-A **composite** bundles several credits / outcomes / units and is priced and
-billed as one thing. Tag a signal with `composite` to group it into one
-*occurrence* — `ref` is the composite's ref ID and `value` is your own
-correlation id for that occurrence (a session, a call, a job):
+### Unit usage
+
+Units carry no model and no tokens. `quantity` defaults to `1`.
 
 ```ts
-await cnk.signals.credit({
-  customerId, model: "llama-3.3-70b-versatile", agentKey: "api_credit",
-  tokens: { input: 1200, output: 340 },
-  composite: { ref: "voice_ai", value: "call_5f3a" },
-});
+await cnk.signals.unit({ customerId, agentKey: "seats", quantity: 3 });
 ```
 
-An occurrence opens on the first tagged signal and costs nothing. **Closing it
-is what bills it** — one charge for the bundle, however many signals it
-contained:
+`signals.unit()` takes **no `{ wait: true }` option** — unit reports are never
+buffered and are always sent immediately.
+
+### Composites
+
+A composite groups credit, outcome, and unit signals into one billable
+occurrence. Tag each signal, then close the occurrence explicitly.
 
 ```ts
-await cnk.signals.completeComposite({
+const composite = { ref: "voice_ai", value: "call_5f3a" };
+
+await cnk.signals.credit({
   customerId,
-  composite: { ref: "voice_ai", value: "call_5f3a" },
+  model: model.modelId,
+  agentKey: credit.agentKey,
+  tokens: { input: 100, output: 50 },
+  composite,
 });
+
+// Closing is ALWAYS explicit. Put it on the line before your own return.
+await cnk.signals.completeComposite({ customerId, composite });
 ```
 
-Only your code knows when the work ended, so closing is a declaration, not
-something ClockNext infers from which signals have arrived: tagged signals may
-arrive in any order and the occurrence stays open and unbilled until you say
-otherwise. Put the call on the line before your own `return`.
+**An outcome's `complete: true` does not close a composite occurrence.** It
+closes the run, and nothing else — whatever mix of credits, outcomes and units
+the composite wraps. If you tag outcome signals with a `composite`, you must
+still call `completeComposite()`, or that occurrence stays open and is never
+billed.
 
-An **outcome never needs it** — its own `complete: true` closes its run and the
-matching occurrence together. Credits and units have no "done" signal of their
-own, so this is theirs.
+Closing twice is safe. Closing early is safe — the server parks the ping until
+the first tagged signal arrives. Wallet signals do not participate in composites.
 
-Closing twice is safe (`ALREADY_COMPLETED`, and it cannot bill again), and so is
-closing *early* — before every entitlement in the bundle has reported, or while
-a prepaid slot pool is full: the server parks the request and applies it when
-the blocker clears, rather than failing it.
+## Delivery status: `buffered`, `accepted`, `recorded`, `dropped`
 
-A tag that names no live composite is ignored and never fails the signal — the
-signal carries money, the tag only decides what it is grouped under. Tags on
-wallet signals are ignored.
+Every metering call resolves with a `status` saying how far the signal actually
+got. Branch on it rather than on the legacy `queued` boolean, which collapses
+the first two states into one.
 
-> **Renamed in 0.10.** This field was called `metric` and was documented as
-> "reporting only, never changes what's billed". That was wrong: where the plan
-> sells the composite, the occurrence is the billable unit. Rename `metric:` to
-> `composite:` — the shape (`{ ref, value }`) is unchanged.
+| `status` | Meaning | Can it still be lost? |
+| --- | --- | --- |
+| `"buffered"` | In this process's memory, not yet sent (async mode) | **Yes** — flush before the process exits |
+| `"accepted"` | Written to the server's durable inbox (`202`), not yet priced | No, but not billed yet either |
+| `"recorded"` | Priced inline; `usageLog` is populated | No |
+| `"dropped"` | The SDK discarded it — client closed, or local queue full | Already lost; `onDrop` fired |
 
-### Async vs sync
+The default mode is `async`: the signal is buffered locally and the call returns
+immediately.
 
-By default the client is in **`async`** mode: `track()` buffers the signal and
-returns immediately (`{ queued: true }`), and a background flusher drains the
-buffer on a size/interval trigger. This keeps billing telemetry off your LLM hot
-path.
+```ts
+const signal = {
+  customerId,
+  model: model.modelId,
+  agentKey: credit.agentKey,
+  tokens: { input: 1200, output: 340 },
+};
 
-> **"Batching" here means timing, not a bulk request.** Each signal is still its
-> own POST to its own `/api/v1/signal/*` route; the flusher just groups *when*
-> sends happen and caps how many run at once (`batch.maxConcurrency`). There is
-> no single bulk-ingest call, so size your request budget per signal.
+const cnk = new ClockNext({ apiKey });                   // async (default)
+await cnk.signals.credit(signal);                        // -> { status: "buffered" }
+await cnk.signals.credit(signal, { wait: true });        // -> "accepted" | "recorded"
 
-To await the request itself (rather than buffering it), either:
+const sync = new ClockNext({ apiKey, mode: "sync" });    // every signal awaits
+```
 
-```ts
-// per call
-const res = await cnk.signals.credit({ … }, { wait: true });
+`{ wait: true }` and `mode: "sync"` wait for the server to **accept** the
+signal, never for it to finish pricing. No mode of this SDK blocks a request
+thread on a billing result.
 
-// or globally
-const cnk = new ClockNext({ apiKey, mode: "sync" });
-```
+`cnk.pending` reports how many signals are currently buffered.
+
+### Serverless and shutdown
 
-> **Awaiting is not the same as billed.** Where the server has a durable queue
-> configured it answers `202` and prices the signal in a worker, so you get
-> `{ queued: true, messageId, usageLog: null }` — accepted, not yet recorded, and
-> validated only later (a bad `agentKey` is dropped there, silently). Only when
-> the server prices inline do you get `{ queued: false, usageLog }`. Branch on
-> `queued`; never assume `usageLog` is populated.
->
-> To confirm a signal landed, read it back with `signals.list({ customerId })`.
-> There is no way to price a signal without recording it — send one against a
-> **sandbox** organisation instead.
-
-> In `async` mode, server-side rejections (e.g. insufficient allowance, `422`)
-> surface via the `onError` hook or `flush()`, not from the `track()` call.
-
-### Reliability
-
-- **Retries:** transient failures (network, timeout, `408/409/429/5xx`) are
-  retried with exponential backoff + equal jitter, honoring `Retry-After`.
-  Deterministic `4xx` (`400/401/404/422`) are never retried.
-- **Replay safety:** reads (`GET`) and `DELETE` are retried automatically. Metering
-  signals (`signals.*`) opt into retries too — made safe by the idempotency key
-  below. Other non-idempotent writes — e.g. `customers.create`, `plans.create`,
-  `purchases.create` — are *not* auto-retried, so a transient blip can never
-  create a duplicate.
-- **Idempotency:** every metering signal carries an idempotency key — auto-
-  generated per signal, or pass your own via `idempotencyKey` on the signal —
-  reused across all retries, so a retried send is **deduplicated by the server**
-  instead of double-counted. Pass a stable key (e.g. your own event id) to also
-  dedup across process restarts or at-least-once redelivery.
-- **Flushing:** call `await cnk.flush()` before a serverless return, and
-  `await cnk.close()` on graceful shutdown to drain the buffer.
-- **Durability:** the async buffer is **in-memory**. A signal already accepted
-  by the server is durable on the server side, but signals still buffered when a
-  process crashes (before send) are lost. For zero-loss-before-receipt, either
-  run in `sync` mode (or `{ wait: true }`) so the send completes before your
-  code continues, or call `flush()`/`close()` at the right boundaries. A
-  pluggable before-send persistence store is not yet available.
-
-## Customers
+The local queue is in memory, so it must be drained before the process can
+freeze or exit.
 
 ```ts
-const c   = await cnk.customers.create({ name: "Acme", email: "ops@acme.com" });
-const one = await cnk.customers.get(c.id);
-const page = await cnk.customers.list({ limit: 50, q: "ac" });
-await cnk.customers.update(c.id, { legalName: "Acme Inc." });
-await cnk.customers.delete(c.id);
-
-// iterate every customer (auto-follows the cursor)
-for await (const cust of cnk.customers.iterate()) { /* … */ }
-
-// insights
-await cnk.customers.usage(c.id, { limit: 50 });
-await cnk.customers.balances(c.id);
-await cnk.customers.plan(c.id);
-await cnk.customers.revenue(c.id, { range: "30d" });
+// Serverless handler — flush, but do NOT close: the container is reused.
+try {
+  // application work and signal tracking
+} finally {
+  await cnk.flush();
+}
+
+// Long-running process, on shutdown only:
+await cnk.close();
 ```
 
-### Members
+Construct the client **once at module scope**, not per request. After `close()`
+the client is permanently shut: further signals resolve `{ status: "dropped" }`
+and fire `onDrop` with reason `"closed"`. Never call `close()` in a serverless
+handler.
+
+If losing a buffered signal is unacceptable, use `mode: "sync"` or
+`{ wait: true }`, and supply your own stable `idempotencyKey`.
+
+## Idempotency and retries
+
+Metering calls get an idempotency key automatically and reuse it across every
+retry, so a retried send is deduplicated server-side instead of double-billing.
+Supply your own stable key to also deduplicate across process restarts and
+at-least-once redelivery:
 
 ```ts
-await cnk.customers.addMember(c.id, { name: "Alice", email: "alice@acme.com" });
-const members = await cnk.customers.listMembers(c.id);
-await cnk.customers.updateMember(c.id, members[0].id, { name: "Alice R." });
-await cnk.customers.removeMember(c.id, members[0].id);
+await cnk.signals.credit({
+  customerId,
+  model: model.modelId,
+  agentKey: credit.agentKey,
+  tokens: { input: 10, output: 5 },
+  idempotencyKey: `llm-request:${requestId}`,
+});
 ```
 
-### Wallet & billing config
+When a signal fails permanently, the key it was sent with is available on both
+the error (`error.idempotencyKey`) and the signal handed to `onError`/`onDrop`.
+**Replay with that key** — generating a new one bills the event twice.
 
-```ts
-// wallet
-await cnk.customers.wallet(c.id, { limit: 50 });               // { balanceUsd, transactions }
-await cnk.customers.addWalletEntry(c.id, { type: "CREDIT", amount: 25 }); // top up (DEBIT to spend)
+Retries apply to network failures, timeouts, `408`, `429`, `5xx`, and the one
+transient `409`. Validation, authentication, not-found, plan, allowance and
+permanent-conflict errors are never retried. Reads and `DELETE`s are retried;
+`POST`/`PATCH` are not, except metering calls, which opt in because they are
+idempotency-keyed.
 
-// billing config — currency is set through update()
-await cnk.customers.update(c.id, { currencyCode: "EUR" });
+Client-side batching is timing and concurrency management, not a bulk API — each
+signal is still an individual HTTP request.
 
-// grant / claw back balances (delta is signed)
-await cnk.customers.adjustCredit(c.id, { creditId: "cr_1", delta: 100 });
-const { remaining } = await cnk.customers.adjustOutcome(c.id, { outcomeId: "out_1", delta: -1 });
-await cnk.customers.adjustUnit(c.id, { unitId: "un_1", delta: 5 });
-```
+## Handling errors
 
-## Plans & purchases
+Branch on error classes, never on message text.
 
 ```ts
-// define a plan
-const plan = await cnk.plans.create({
-  name: "Pro",
-  billingCycle: "MONTHLY",
-  currencyCode: "USD",
-  components: [
-    { type: "WALLET", billingMode: "ADVANCE", amount: 100 },
-    { type: "CREDIT", billingMode: "ADVANCE", creditId: "cr_1", quantity: 10_000 },
-  ],
-});
-await cnk.plans.list({ active: true });
-await cnk.plans.setActive(plan.id, false);
+import {
+  ClockNextError,
+  AllowanceError,
+  AuthError,
+  ConflictError,
+  ForbiddenError,
+  NetworkError,
+  NotFoundError,
+  PlanError,
+  RateLimitError,
+  ServerError,
+  ValidationError,
+} from "@clocknext/sdk";
 
-// subscribe a customer (auto-cancels their existing active/scheduled purchase)
-const purchase = await cnk.purchases.create({ customerId: c.id, planId: plan.id });
-await cnk.purchases.setAutoPayment(purchase.id, false, { pauseReason: "trial" });
-await cnk.purchases.cancel(purchase.id);
+try {
+  await cnk.customers.get(customerId);
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    // No such customer in this workspace.
+  } else if (error instanceof AuthError) {
+    // Rotate or correct the API key.
+  } else if (error instanceof ValidationError) {
+    // Fix the request shape or required fields.
+  } else if (error instanceof RateLimitError || error instanceof ServerError) {
+    // Already retried by the SDK; add an application-level fallback.
+  } else if (error instanceof ClockNextError) {
+    console.error(error.status, error.code, error.message);
+  }
+}
 ```
 
-## Invoices & payments (read-only)
+| Class | Status | Meaning |
+| --- | --- | --- |
+| `ValidationError` | 400 | Malformed request or failed schema validation |
+| `AuthError` | 401 | Missing, invalid or expired API key |
+| `ForbiddenError` | 403 | Key is valid but not permitted to do this |
+| `NotFoundError` | 404 | Unknown resource (also returned for cross-org access) |
+| `ConflictError` | 409 | Conflict — usually an archived customer. Permanent, and not retried |
+| `PlanError` | 422 | No active plan, meter not in plan, model not enabled, member missing |
+| `AllowanceError` | 422 | The entitlement ran out — top up or upsell |
+| `RateLimitError` | 429 | Rate limited; carries `retryAfterMs` |
+| `ServerError` | 5xx | Server-side failure |
+| `NetworkError` | — | fetch threw or the request timed out |
+
+All extend `ClockNextError`, which exposes `.status` (`number | undefined`),
+`.retryable`, `.code` (the server's machine-readable code, when it sends one),
+and `.idempotencyKey` on metering calls. Constructor failures — a missing
+`apiKey`, no available `fetch` — throw `ValidationError`, so a single
+`instanceof ClockNextError` catches setup problems too.
+
+### Signal failures do not arrive here
+
+Because ingest answers `202` before validating, **a try/catch around
+`signals.credit()` will not catch a rejected signal**, with or without
+`{ wait: true }` — and neither will `onError`. A rejection discovered during
+pricing has no programmatic channel at all; it is recorded on the workspace's
+signal log in the ClockNext dashboard, which is owner-only by design.
+
+What the hooks below DO cover is everything that fails before the `202`: an
+invalid API key, an unreachable host, a timeout, and signals the SDK dropped
+without sending.
 
 ```ts
-const invoices = await cnk.invoices.list({ customerId: c.id, status: "OPEN" });
-const { invoice, plan } = await cnk.invoices.get(invoices[0].id);
-const { url } = await cnk.invoices.payLink(invoices[0].id); // hosted pay link (OPEN only)
-
-const payments = await cnk.payments.list({ customerId: c.id });
-await cnk.payments.get(payments[0].id); // id = the paid invoice id
+import { ClockNext, ClockNextError } from "@clocknext/sdk";
+
+const cnk = new ClockNext({
+  apiKey,
+  onError: (error, signal) => {
+    // `error` is `unknown`; narrow it.
+    if (error instanceof ClockNextError) {
+      logger.error({ status: error.status, key: error.idempotencyKey }, error.message);
+    }
+    deadLetter.push(signal); // replay later with signal.idempotencyKey
+  },
+  onDrop: (signal, reason) => logger.error({ signal, reason }, "signal dropped"),
+  onRetry: ({ attempt, delayMs, error }) => logger.warn({ attempt, delayMs, error }),
+  onFlush: (sentCount) => logger.info({ sentCount }, "signals flushed"),
+});
 ```
 
-## Catalogs: credits, outcomes, units
+`onFlush` counts signals the server **accepted**, not signals it billed.
 
-Define the billable *types*; record usage against them with `signals.*`.
+So the division of labour is: these hooks tell you your integration cannot
+reach ClockNext; `signals.list()` tells you what got priced; the dashboard's
+signal log tells you why an individual signal did not.
 
-```ts
-// credit type — signals.credit({ agentKey }) meters against it
-await cnk.credits.create({ name: "API", agentKey: "api_credit", basePrice: 1, marginPercent: 20, pricePerCredit: 0.01 });
-await cnk.credits.list({ active: true });
-
-// outcome type — a multi-step workflow. TWO kinds of agentKey, both required and
-// both unique per org: the outcome's own (its identity) and each step's (what
-// signals.outcome() reports against). They are separate namespaces.
-await cnk.outcomes.create({
-  name: "Resolved ticket",
-  agentKey: "resolved_ticket",
-  basePrice: 1, marginPercent: 20, pricePerOutcome: 2,
-  steps: [{ name: "Triage", agentKey: "resolved_ticket.triage", basePrice: 0.5 }],
-});
+## Balances and usage
 
-// unit type — a quantity-priced meter (FLAT / SLAB / VOLUME)
-await cnk.units.create({ name: "Seats", agentKey: "seats", pricingType: "FLAT", flatPrice: 5 });
+```ts
+const balances = await cnk.customers.balances(customerId);
+balances.wallet?.balanceUsd;
+balances.credits;   // granted, used, remaining
+balances.outcomes;  // granted, remaining, steps
+balances.units;     // granted, remaining
+
+// Convenience lookups — these fetch the full snapshot, so prefer `balances()`
+// when you need more than one row from the same customer.
+await cnk.customers.creditBalance(customerId, { creditName: "API credit" });
+await cnk.customers.outcomeBalance(customerId, { outcomeName: "Resolved ticket" });
+await cnk.customers.unitBalance(customerId, { unitName: "Seats" });
+
+// Usage history, and unit balances + recent unit events.
+await cnk.signals.list({ customerId, limit: 50 });
+await cnk.signals.unitUsage({ customerId, limit: 50 });
 ```
 
-### Unit metering
+Adjustments use stable agent keys, not display names:
 
-Record a unit event (no tokens, no model) and read a customer's unit balances:
+```ts
+await cnk.customers.adjustCredit(customerId, { agentKey: "api_credit", delta: 100 });
+await cnk.customers.adjustOutcome(customerId, { agentKey: "resolved_ticket.triage", delta: 1 });
+await cnk.customers.adjustUnit(customerId, { agentKey: "seats", delta: 5 });
+```
+
+## Customers, plans, and billing
 
 ```ts
-await cnk.signals.unit({ customerId: c.id, agentKey: "seats" });
+const customer = await cnk.customers.create({ name: "Acme", email: "billing@acme.com" });
+await cnk.customers.update(customer.id, { currencyCode: "USD" });
+await cnk.customers.list({ limit: 50, q: "acme" });
 
-// several at once, instead of N separate calls
-await cnk.signals.unit({ customerId: c.id, agentKey: "seats", quantity: 3 });
+for await (const c of cnk.customers.iterate()) {
+  // follows the cursor for you
+}
 
-// part of a composite, and safe to retry
-await cnk.signals.unit({
-  customerId: c.id, agentKey: "seats",
-  composite: { ref: "voice_ai", value: "call_5f3a" },
-  idempotencyKey: `seats:${requestId}`,
+const purchase = await cnk.purchases.create({ customerId: customer.id, planId: plan.id });
+await cnk.purchases.setAutoPayment(purchase.id, false, {
+  pauseReason: "Customer requested manual payment",
 });
-
-await cnk.signals.unitUsage({ customerId: c.id });
 ```
 
-`quantity` defaults to 1. On a prepaid (ADVANCE) plan the draw is
-all-or-nothing: asking for more than remains is refused in full rather than
-partially filled.
+Additional resource methods:
+
+```text
+cnk.customers.get / update / delete / iterate
+cnk.customers.listMembers / addMember / updateMember / removeMember
+cnk.customers.wallet / addWalletEntry / usage / plan / balances
+
+cnk.plans.list / get / create / update / setActive / delete
+cnk.purchases.list / get / create / cancel / setAutoPayment
+cnk.invoices.list / get / payLink
+cnk.payments.list / get
+cnk.webhooks.list / upsert / delete
+cnk.portal.createToken
+```
 
-> **Changed in 0.10.** `signals.unit()` moved to `POST /api/v1/signal/unit`,
-> which is **durable** (the report is written down before it is priced, so a
-> failure parks for retry instead of losing a billable event) and **idempotent**
-> (on the old route a retried report drew the balance down twice). Because it can
-> now answer `202`, this resolves `{ queued, unitUsage, rawId }` rather than a
-> bare `{ unitUsage }` — branch on `queued`, don't assume `unitUsage`.
+Note: `plans.update()` is a full rewrite and takes the *input* shape, which is
+not the shape `plans.get()` returns. Rebuild the components rather than passing
+the read result straight back.
 
-## Webhooks
+## Catalogs and workspace discovery
 
-Threshold alerts — at most one per kind (`CREDIT` / `OUTCOME` / `WALLET`):
+This is where `agentKey` and `modelId` come from.
 
 ```ts
-await cnk.webhooks.upsert({ kind: "WALLET", threshold: 10, url: "https://acme.com/hooks/clocknext" });
-await cnk.webhooks.list();
-await cnk.webhooks.delete("WALLET");
+const models     = await cnk.workspace.models({ active: true });
+const credits    = await cnk.credits.list({ active: true });
+const outcomes   = await cnk.outcomes.list({ active: true });
+const units      = await cnk.units.list({ active: true });
+const composites = await cnk.composites.list({ active: true });
 ```
 
-## Customer portal token
+`{ active: true }` returns only active rows, `{ active: false }` only archived
+ones, and omitting it returns both.
+
+Creating catalog entries:
 
 ```ts
-const { token, expiresAt } = await cnk.portal.createToken({ customerId: "cus_123", ttlSeconds: 600 });
-// render <iframe src={`https://payments.clocknext.com/portal/embed?token=${token}`} />
+const credit = await cnk.credits.create({
+  name: "API credit",
+  agentKey: "api_credit",     // stable identity; a rename never changes it
+  basePrice: 10,
+  marginPercent: 20,
+  pricePerCredit: 12,         // recomputed server-side from basePrice × margin
+  tokensPerCredit: 1000,
+});
+
+const outcome = await cnk.outcomes.create({
+  name: "Resolved ticket",
+  agentKey: "resolved_ticket",          // the OUTCOME's key
+  basePrice: 1,
+  marginPercent: 20,
+  pricePerOutcome: 1.2,
+  steps: [
+    { name: "Triage", agentKey: "resolved_ticket.triage", basePrice: 0.5 },
+    { name: "Resolve", agentKey: "resolved_ticket.resolve", basePrice: 0.5 },
+  ],
+});
+
+const unit = await cnk.units.create({
+  name: "Seats",
+  agentKey: "seats",
+  pricingType: "FLAT",
+  flatPrice: 5,               // price per event; tiered units take `tiers` instead
+});
 ```
 
-## Errors
+Signals report against a **step's** `agentKey`, never the outcome's own.
+
+Other catalog methods:
+
+```text
+cnk.credits.create / get / update / setActive / delete
+cnk.outcomes.create / get / update / setActive / delete
+cnk.units.create / get / update / setActive / delete
+cnk.composites.list / create
+```
 
-All failures throw typed errors you can branch on:
+## Webhooks and customer portal
 
 ```ts
-import { AllowanceError, AuthError, RateLimitError } from "@clocknext/sdk";
+await cnk.webhooks.upsert({
+  kind: "WALLET",                 // "WALLET" | "CREDIT" | "OUTCOME"
+  threshold: 10,
+  url: "https://example.com/clocknext/webhook",
+});
+await cnk.webhooks.list();
+await cnk.webhooks.delete("WALLET");
 
-try {
-  await cnk.signals.credit({ … }, { wait: true });
-} catch (err) {
-  if (err instanceof AllowanceError) {/* upsell */}
-  else if (err instanceof AuthError) {/* bad key */}
-  else if (err instanceof RateLimitError) {/* back off */}
-}
+const { token, expiresAt } = await cnk.portal.createToken({
+  customerId,
+  ttlSeconds: 600,
+});
 ```
 
-`ValidationError (400)` · `AuthError (401)` · `NotFoundError (404)` ·
-`PlanError (422)` · `AllowanceError (422)` · `ConflictError (409)` ·
-`RateLimitError (429)` · `ServerError (5xx)` · `NetworkError` — all extend
-`ClockNextError` (`.status`, `.retryable`).
+Pass the portal token to your frontend and embed it using your portal URL. Never
+pass the API key to the frontend.
 
 ## Configuration
 
 ```ts
-new ClockNext({
-  apiKey: "cnk_…",                 // required
-  baseUrl: "https://payments.clocknext.com",
-  mode: "async",                    // "async" | "sync"
+const cnk = new ClockNext({
+  apiKey,
+  baseUrl: "https://payments.clocknext.com", // optional
+  mode: "async",                              // "async" (default) | "sync"
   timeoutMs: 10_000,
-  batch: { maxSize: 20, maxIntervalMs: 2000, maxConcurrency: 5, maxQueueSize: 10_000 },
-  retry: { maxAttempts: 5, baseDelayMs: 200, maxDelayMs: 10_000 },
-  onError: (err, signal) => {},
-  onFlush: (count) => {},
-  onRetry: ({ attempt, delayMs }) => {},
+  fetch: myFetch,                             // optional fetch implementation
+  logger: { warn: console.warn, debug: console.debug },
+  batch: {
+    maxSize: 20,
+    maxIntervalMs: 2_000,
+    maxConcurrency: 5,
+    maxQueueSize: 10_000,
+  },
+  retry: {
+    maxAttempts: 5,
+    baseDelayMs: 200,
+    maxDelayMs: 10_000,
+  },
+  onError: (error, signal) => {},
   onDrop: (signal, reason) => {},
+  onRetry: ({ attempt, delayMs, error }) => {},
+  onFlush: (sentCount) => {},
 });
 ```
 
-Numeric options are validated: a negative or non-finite value (e.g. a bad
-`timeoutMs`) falls back to its default rather than silently breaking the client.
+With no `onError` supplied the SDK reports failures on `console.error` rather
+than swallowing them. Pass `onError: () => {}` to silence that deliberately.
+
+## Testing and packaging
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+The package publishes ESM and CommonJS builds with TypeScript declarations, and
+ships its annotated `src/` so source maps resolve and the implementation is
+readable from `node_modules`.
 
 ## License