@clocknext/sdk 0.14.0 → 0.16.0

package/README.md

@@ -4,7 +4,8 @@ Official TypeScript/JavaScript SDK for ClockNext. Use it from a backend to:
 
 - 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.
+- manage customers, their members and balances, purchases, and portal tokens;
+- list the billing plans a customer can be subscribed to.
 
 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,
@@ -26,7 +27,7 @@ about to be thrown away:
 
 ```ts
 const result = await cnk.signals.credit(
-  { customerId, model: model.modelId, agentKey: credit.agentKey, tokens: { input: 1, output: 1 } },
+  { customerId, model, agentKey: credit.agentKey, tokens: { input: 1, output: 1 } },
   { wait: true },
 );
 // { status: "accepted", usageLog: null, rawId: "...", messageId: "..." }
@@ -39,9 +40,9 @@ 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()` |
+| `model` is not enabled in your workspace | use a model id enabled under **Settings → Models** in the dashboard, verbatim |
+| `agentKey` names no credit / outcome step / unit | read it from `customers.balances()` — every credit, outcome step and unit on the customer's plan carries its `agentKey` |
+| the customer has no active purchase of a plan carrying that entitlement | pick a plan with `plans.list()`, 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. |
@@ -61,21 +62,22 @@ 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.
+**`signals.usageLog()` is the programmatic check, and it is partial.** It
+returns priced usage rows, 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 row is written for one. Those appear only in the
+dashboard.
 
 ```ts
-const usage = await cnk.signals.list({ customerId });
+const page = await cnk.signals.usageLog({ customerId });
 
 // Nothing here at all → rejected before pricing. Check the dashboard's log.
-console.log(usage.totals.count);
+console.log(page.usageLogs.length);
 
 // 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);
+for (const row of page.usageLogs) {
+  if (row.status !== "SUCCESS") console.warn(row.id, row.status);
 }
 ```
 
@@ -85,14 +87,17 @@ 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)
+enabled model  →  entitlement (credit / outcome / unit, with an agentKey)
                →  plan containing that entitlement
                →  purchase linking the customer to the plan
                →  customer
 ```
 
+The model, the entitlements and the plan are set up in the ClockNext dashboard.
+The SDK then links a customer to a plan and meters against it.
+
 `customerId`, `model` and `agentKey` are **not strings you can invent**. The
-quick start below discovers each one instead of hard-coding it.
+quick start below reads each one back instead of hard-coding it.
 
 ---
 
@@ -112,8 +117,13 @@ npm install @clocknext/sdk
 
 ## Quick start — zero to a recorded signal
 
-This is a complete, runnable setup for an empty workspace. Every id is read back
-from the API rather than guessed.
+Before running this, do the one-time setup in the ClockNext dashboard:
+
+1. Enable a model under **Settings → Models**.
+2. Create a credit (its `agentKey` is what signals address).
+3. Create a plan that sells that credit.
+
+Everything else is read back from the API rather than guessed.
 
 ```ts
 import { ClockNext } from "@clocknext/sdk";
@@ -129,58 +139,41 @@ const cnk = new ClockNext({
     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"
+// 1. The model you enabled under Settings → Models. Use its id VERBATIM.
+const model = "gpt-4o";
 
-// 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.");
+// 2. A plan to subscribe the customer to.
+const [plan] = await cnk.plans.list({ active: true });
+if (!plan) throw new Error("Create a plan in the dashboard 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.
+// 3. A customer, and a purchase linking them to the plan.
+//    Without the purchase every signal below is silently discarded.
 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.
+// 4. The credit's agentKey, read off the customer's balances.
+const { credits } = await cnk.customers.balances(customer.id);
+const credit = credits[0];
+if (!credit) throw new Error("The plan must sell at least one credit.");
+
+// 5. Now a signal can land.
 await cnk.signals.credit({
   customerId: customer.id,
-  model: model.modelId,
+  model,
   agentKey: credit.agentKey,
   tokens: { input: 1200, output: 340 },
   custom: { feature: "summarize" },
 });
 
-// 7. Required in async mode before the process can exit.
+// 6. 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");
+// 7. Prove it. Ingestion is asynchronous, so allow a moment.
+const page = await cnk.signals.usageLog({ customerId: customer.id });
+console.log(page.usageLogs.length, "signals recorded");
 ```
 
 A runnable version is in [`examples/node-basic.ts`](./examples/node-basic.ts),
@@ -200,30 +193,49 @@ Signals are billable usage events. Each kind posts to its own route.
 `signals.track(signal)` is the underlying call the four convenience methods wrap;
 use it when the kind is dynamic.
 
+`tokens` takes `input` and `output` (required), plus two optional prompt-cache
+counts that each default to 0:
+
+- `cache` — tokens **read** from the prompt cache, priced at the model's cache-read rate.
+- `cacheWrite` — tokens **written** into the prompt cache, priced at the model's
+  separate cache-write rate.
+
+```ts
+await cnk.signals.credit({
+  customerId,
+  model: "claude-sonnet-4-5",
+  agentKey: "api_credit",
+  tokens: { input: 1200, output: 340, cache: 800, cacheWrite: 2000 },
+});
+```
+
+Every signal method can take `externalId` (your own id for the customer — see
+[Your own customer ids](#your-own-customer-ids)) instead of `customerId`.
+
 ### Where each value comes from
 
 | 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. |
+| `model` | **Settings → Models** in the dashboard | Use it verbatim. Matching is case-insensitive but the id must exist; `"openai/gpt-4o"` is not the same as `"gpt-4o"`. |
+| `agentKey` (credit) | `customers.balances(id)` → `credits[].agentKey` | Case-insensitive. |
+| `agentKey` (outcome) | `customers.balances(id)` → `outcomes[].steps[].agentKey` | The **step's** key, not the outcome's own `agentKey`. |
+| `agentKey` (unit) | `customers.balances(id)` → `units[].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. |
+| `composite.ref` | the composite's **Ref ID** in the dashboard | An unknown `ref` is ignored, not rejected — the signal still records. |
 
 ### Credit and wallet
 
 ```ts
 await cnk.signals.credit({
   customerId,
-  model: model.modelId,
+  model,
   agentKey: credit.agentKey,
   tokens: { input: 500, output: 120 },
 });
 
 await cnk.signals.wallet({
   customerId,
-  model: model.modelId,
+  model,
   tokens: { input: 500, output: 120 },
 });
 ```
@@ -243,7 +255,7 @@ const runId = "ticket_9021";
 
 await cnk.signals.outcome({
   customerId,
-  model: model.modelId,
+  model,
   agentKey: "resolved_ticket.triage",   // a STEP key
   runId,
   tokens: { input: 600, output: 150 },
@@ -251,7 +263,7 @@ await cnk.signals.outcome({
 
 await cnk.signals.outcome({
   customerId,
-  model: model.modelId,
+  model,
   agentKey: "resolved_ticket.resolve",
   runId,
   tokens: { input: 500, output: 200 },
@@ -288,7 +300,7 @@ const composite = { ref: "voice_ai", value: "call_5f3a" };
 
 await cnk.signals.credit({
   customerId,
-  model: model.modelId,
+  model,
   agentKey: credit.agentKey,
   tokens: { input: 100, output: 50 },
   composite,
@@ -326,7 +338,7 @@ immediately.
 ```ts
 const signal = {
   customerId,
-  model: model.modelId,
+  model,
   agentKey: credit.agentKey,
   tokens: { input: 1200, output: 340 },
 };
@@ -379,22 +391,60 @@ at-least-once redelivery:
 ```ts
 await cnk.signals.credit({
   customerId,
-  model: model.modelId,
+  model,
   agentKey: credit.agentKey,
   tokens: { input: 10, output: 5 },
   idempotencyKey: `llm-request:${requestId}`,
 });
 ```
 
+Every signal accepts `idempotencyKey` — `credit`, `wallet`, `outcome`,
+`completeOutcome`, `unit` and `completeComposite`:
+
+```ts
+await cnk.signals.unit({ customerId, agentKey: "seats", quantity: 3, idempotencyKey: `seat-sync:${syncId}` });
+await cnk.signals.completeComposite({ customerId, composite, idempotencyKey: `call-done:${callId}` });
+```
+
 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.
 
+### Balance adjustments
+
+Adjustments (`customers.adjustCredit()` and friends) work like signals: every
+call gets an idempotency key automatically (a UUID, generated once per call and
+reused across its retries), so a network blip never adjusts twice. Pass your own
+`idempotencyKey` — your order / top-up id — to also dedupe **your own** retries
+across restarts or redelivery, which an auto key can't survive.
+
+```ts
+const res = await cnk.customers.adjustCredit(customerId, {
+  agentKey: "api_credit",
+  delta: 500,
+  idempotencyKey: `topup:${orderId}`,
+});
+
+if (res.replayed) {
+  // An earlier call with this key already added the 500 (at res.adjustedAt).
+  // Nothing was added this time; res.remaining is the balance now.
+}
+```
+
+- Same key, same request → nothing is adjusted again; `replayed: true`,
+  `adjustedAt` is when the original happened, `remaining` is the current balance.
+- Same key, different request (another customer, entitlement or amount) →
+  `ConflictError`, nothing adjusted. Use a new key for a new adjustment.
+- A failed adjustment (validation, not on the plan, …) does not use up its key —
+  fix the request and send it again with the same key.
+- Keys are unique per workspace and per adjust endpoint (credits, outcomes,
+  units, composites, wallet). 1–255 characters.
+
 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.
+`POST`/`PATCH` are not, except metering calls and balance adjustments, which
+opt in because they are always idempotency-keyed.
 
 Client-side batching is timing and concurrency management, not a bulk API — each
 signal is still an individual HTTP request.
@@ -487,17 +537,19 @@ const cnk = new ClockNext({
 `onFlush` counts signals the server **accepted**, not signals it billed.
 
 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
+reach ClockNext; `signals.usageLog()` tells you what got priced; the dashboard's
 signal log tells you why an individual signal did not.
 
 ## Balances and usage
 
 ```ts
 const balances = await cnk.customers.balances(customerId);
-balances.wallet?.balanceUsd;
+balances.wallet.balance;          // USD; always present
+balances.wallet.reservedBalance;  // USD; undefined unless Reserved Wallet is on
 balances.credits;   // granted, used, remaining
 balances.outcomes;  // granted, remaining, steps
 balances.units;     // granted, remaining
+balances.composites; // prepaid composite pools: refId, granted, used, remaining
 
 // Convenience lookups — these fetch the full snapshot, so prefer `balances()`
 // when you need more than one row from the same customer.
@@ -505,18 +557,33 @@ 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 });
+// Usage history across every meter, newest first, cursor-paginated.
+let cursor: string | undefined;
+do {
+  const page = await cnk.signals.usageLog({ customerId, limit: 50, cursor });
+  // page.usageLogs — each row has a `kind`: credit | outcome | unit | wallet | composite
+  cursor = page.nextCursor ?? undefined;
+} while (cursor);
 ```
 
-Adjustments use stable agent keys, not display names. All four return the
-resulting `{ remaining }` balance; a reduce is never rejected or floored for
-going below 0 — the resulting balance may read negative, same as a real-usage
-overdraft already can.
+Adjustments use stable agent keys, not display names. **A credit, outcome, unit
+or composite can only be adjusted when it is a prepaid (ADVANCE) part of the
+customer's current plan** — the same set `customers.balances()` shows.
+Otherwise the call fails with a `PlanError` ("… is not part of this customer's
+plan") and nothing is written. That includes an entitlement that is only
+billed in arrears, one that is only covered through a composite, and a
+customer with no plan (or a cancelled one). **The wallet can always be
+adjusted**, whatever the plan.
+
+Every adjust call returns `{ remaining, replayed, customerArchived }` (plus
+`adjustedAt` on a replay — see [Balance adjustments](#balance-adjustments)). A
+reduce is never rejected or floored for going below 0 — the resulting balance
+may read negative, same as a real-usage overdraft already can.
+`customerArchived: true` means the customer is archived; the same rules apply
+(archiving cancels their plan, so usually only the wallet can still move).
 
 ```ts
-await cnk.customers.adjustCredit(customerId, { agentKey: "api_credit", delta: 100 });
+await cnk.customers.adjustCredit(customerId, { agentKey: "api_credit", delta: 100, idempotencyKey: `grant:${grantId}` });
 await cnk.customers.adjustOutcome(customerId, { agentKey: "resolved_ticket.triage", delta: 1 });
 await cnk.customers.adjustUnit(customerId, { agentKey: "seats", delta: 5 });
 
@@ -524,6 +591,40 @@ await cnk.customers.adjustUnit(customerId, { agentKey: "seats", delta: 5 });
 // value signals tag it with — named `agentKey` on the wire so all four share
 // one request shape. Adjusts the CURRENT billing cycle's ADVANCE slot pool.
 await cnk.customers.adjustComposite(customerId, { agentKey: "voice_ai", delta: 2 });
+
+await cnk.customers.adjustWallet(customerId, { delta: 25 }); // USD, no agentKey
+```
+
+### Reserved Wallet
+
+Some workspaces turn on a **Reserved Wallet**: a second balance that sits behind
+the customer's ordinary wallet (Settings → Organisation → "Enable Reserved
+balance in wallet"). When a wallet-funded Arrear charge comes in, it draws from
+the Wallet first, then from the Reserved Wallet down to 0, and anything still
+left pushes the Wallet negative. The Reserved Wallet itself never goes
+negative, and a normal (`main`) wallet adjustment never touches it.
+
+```ts
+// Top up (or, with a negative delta, reduce) the Reserved Wallet.
+const { remaining } = await cnk.customers.adjustWallet(customerId, { delta: 500, pool: "reserved" });
+// `remaining` is the Reserved balance. Reducing below 0 is refused with an
+// AllowanceError (down to exactly 0 is fine); any "reserved" call when the
+// workspace hasn't enabled the feature is a PlanError.
+
+const { wallet } = await cnk.customers.balances(customerId);
+wallet.reservedBalance; // number | undefined
+```
+
+When the feature is off, `wallet.reservedBalance` is left out of `balances()`.
+
+To change how much a customer is granted **every billing cycle** (not just
+their balance right now), use `updateRecurringGrant`. Any increase or decrease
+applies to their balance immediately. `quantity` is USD for the wallet and a
+whole number for everything else; the wallet needs no `agentKey`.
+
+```ts
+await cnk.customers.updateRecurringGrant(customerId, { kind: "wallet", quantity: 10000 });
+await cnk.customers.updateRecurringGrant(customerId, { kind: "credit", agentKey: "api_credit", quantity: 5000 });
 ```
 
 ## Customers, plans, and billing
@@ -537,6 +638,10 @@ for await (const c of cnk.customers.iterate()) {
   // follows the cursor for you
 }
 
+// `{ active: true }` returns only active plans, `{ active: false }` only
+// archived ones, and omitting it returns both.
+const [plan] = await cnk.plans.list({ active: true });
+
 const purchase = await cnk.purchases.create({ customerId: customer.id, planId: plan.id });
 await cnk.purchases.setAutoPayment(purchase.id, false, {
   pauseReason: "Customer requested manual payment",
@@ -547,90 +652,131 @@ Additional resource methods:
 
 ```text
 cnk.customers.get / update / delete / iterate
+cnk.customers.getByExternalId / updateByExternalId / updateRecurringGrantByExternalId
+cnk.customers.adjustCreditByExternalId / adjustOutcomeByExternalId / adjustUnitByExternalId
+cnk.customers.adjustCompositeByExternalId / adjustWalletByExternalId
+cnk.customers.deleteByExternalId / balancesByExternalId / planByExternalId
 cnk.customers.listMembers / addMember / updateMember / removeMember
-cnk.customers.wallet / addWalletEntry / usage / plan / balances
+cnk.customers.balances / creditBalance / outcomeBalance / unitBalance / plan
+cnk.customers.adjustCredit / adjustOutcome / adjustUnit / adjustComposite / adjustWallet
+cnk.customers.updateRecurringGrant
 
-cnk.plans.list / get / create / update / setActive / delete
+cnk.signals.credit / wallet / outcome / unit / track
+cnk.signals.completeOutcome / completeComposite / usageLog
+
+cnk.plans.list
 cnk.purchases.list / get / create / cancel / setAutoPayment
 cnk.invoices.list / get / payLink
 cnk.payments.list / get
-cnk.webhooks.list / upsert / delete
 cnk.portal.createToken
 ```
 
-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.
-
-## Catalogs and workspace discovery
+### Your own customer ids
 
-This is where `agentKey` and `modelId` come from.
+Give a customer an `externalId` — the id **your** product already uses for
+them — and you never have to store ClockNext's customer id. It is 1–32
+letters, numbers or `-`, case-sensitive, and unique among your active
+customers (a clash is a `ConflictError`).
 
 ```ts
-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 });
-```
+await cnk.customers.create({ name: "Acme", email: "billing@acme.com", externalId: "acme-42" });
+
+// Signals and purchases.create() take `externalId` in place of `customerId`:
+await cnk.signals.credit({ externalId: "acme-42", agentKey: "api_credit", model: "gpt-4o", tokens: { input: 1200, output: 300 } });
+await cnk.purchases.create({ externalId: "acme-42", planId: plan.id });
 
-`{ active: true }` returns only active rows, `{ active: false }` only archived
-ones, and omitting it returns both.
+// Read, update, or resize the recurring grant by your id:
+const acme = await cnk.customers.getByExternalId("acme-42");
+await cnk.customers.updateByExternalId("acme-42", { currencyCode: "USD" });
+await cnk.customers.updateRecurringGrantByExternalId("acme-42", { kind: "wallet", quantity: 10000 });
 
-Creating catalog entries:
+// Manage balances by your id too:
+await cnk.customers.adjustCreditByExternalId("acme-42", { agentKey: "api_credit", delta: 500 });
+await cnk.customers.adjustWalletByExternalId("acme-42", { delta: 250 });
+
+await cnk.customers.update(acme.id, { externalId: null }); // clear it
+```
+
+If you send both, `customerId` wins and `externalId` is ignored. An unknown
+`externalId` is a `NotFoundError`; on a signal (processed asynchronously) it
+leaves the signal Pending with that reason — create the customer and retry.
+Customer objects carry `externalId`. Everything else — `signals.usageLog()`,
+the invoice, payment and purchase lists, `portal.createToken()` and members —
+still takes ClockNext's id.
+
+## Catalogue: credits, outcomes, units, composites and plans
+
+Each of `cnk.credits`, `cnk.outcomes`, `cnk.units`, `cnk.composites` and
+`cnk.plans` has the same six calls: `list()`, `get(id)`, `create(input)`,
+`update(id, input)`, `archive(id)` and `unarchive(id)`.
+
+- **Nothing is deleted.** There is no `delete()`: retire an item with
+  `archive()`, bring it back with `unarchive()`. Usage history never loses
+  what it points at.
+- **`update()` is partial** — only the fields you send change. A list you do
+  send (`modelBundle`, `steps`, `tiers`, `entitlements`) is the complete new
+  list.
+- **Prices are never typed in.** A credit or outcome step sends a
+  `modelBundle` — one line per model — and ClockNext works the price out from
+  the models' live prices.
+- **A plan's currency** is your workspace's primary currency; it can't be set.
 
 ```ts
 const credit = await cnk.credits.create({
-  name: "API credit",
-  agentKey: "api_credit",     // stable identity; a rename never changes it
-  basePrice: 10,
+  name: "Deep Research",
+  agentKey: "deep_research",
   marginPercent: 20,
-  pricePerCredit: 12,         // recomputed server-side from basePrice × margin
-  tokensPerCredit: 1000,
+  modelBundle: [
+    { orgModelId: "cm_model_01", averageTokensPerLLMCall: 100000, input: 60, output: 30, cache: 5, cacheWrite: 5 },
+  ],
 });
 
 const outcome = await cnk.outcomes.create({
-  name: "Resolved ticket",
-  agentKey: "resolved_ticket",          // the OUTCOME's key
-  basePrice: 1,
-  marginPercent: 20,
-  pricePerOutcome: 1.2,
+  name: "Contract review",
+  agentKey: "contract_review",
+  marginPercent: 100,
   steps: [
-    { name: "Triage", agentKey: "resolved_ticket.triage", basePrice: 0.5 },
-    { name: "Resolve", agentKey: "resolved_ticket.resolve", basePrice: 0.5 },
+    { name: "Extract clauses", agentKey: "contract_review.extract",
+      modelBundle: [{ orgModelId: "cm_model_01", averageTokensPerLLMCall: 50000, input: 70, output: 30, cache: 0 }] },
   ],
 });
 
 const unit = await cnk.units.create({
-  name: "Seats",
-  agentKey: "seats",
-  pricingType: "FLAT",
-  flatPrice: 5,               // price per event; tiered units take `tiers` instead
+  name: "API calls",
+  agentKey: "api_calls",
+  pricingType: "SLAB",
+  tiers: [{ upTo: 1000, price: 0.01 }, { upTo: null, price: 0.005 }], // last tier: "and above"
 });
-```
 
-Signals report against a **step's** `agentKey`, never the outcome's own.
+const composite = await cnk.composites.create({
+  name: "Voice AI call",
+  refId: "voice_ai",
+  price: 2.5,
+  entitlements: { creditIds: [credit.id] },
+});
 
-Other catalog methods:
+const plan = await cnk.plans.create({
+  name: "Pro",
+  billingCycle: "MONTHLY",
+  entitlements: [
+    { type: "CREDIT", billingMode: "ADVANCE", creditId: credit.id, quantity: 1000, rollover: true },
+    { type: "OUTCOME", billingMode: "ARREAR", outcomeId: outcome.id },
+    { type: "PRICING_METRIC", billingMode: "ADVANCE", compositeId: composite.id, quantity: 50 },
+    { type: "WALLET", billingMode: "ADVANCE", amount: 25 },
+  ],
+});
 
-```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
+await cnk.credits.update(credit.id, { marginPercent: 50 }); // only the margin changes
+await cnk.units.archive(unit.id);                           // retire it
+await cnk.units.unarchive(unit.id);                         // and bring it back
 ```
 
-## Webhooks and customer portal
+Models are enabled in the ClockNext dashboard; a bundle line's `orgModelId` is
+the workspace's id for the model.
 
-```ts
-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");
+## Customer portal
 
+```ts
 const { token, expiresAt } = await cnk.portal.createToken({
   customerId,
   ttlSeconds: 600,