@clocknext/sdk 0.15.0 → 0.17.0

package/README.md

@@ -193,6 +193,22 @@ 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`.
 
@@ -528,10 +544,12 @@ signal log tells you why an individual signal did not.
 
 ```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.
@@ -584,19 +602,20 @@ 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.
+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" });
+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
+// AllowanceError (down to exactly 0 is fine); any "reserved" call when the
 // workspace hasn't enabled the feature is a PlanError.
 
-const { reservedWallet } = await cnk.customers.balances(customerId); // { balanceUsd } | null
+const { wallet } = await cnk.customers.balances(customerId);
+wallet.reservedBalance; // number | undefined
 ```
 
-`reservedWallet` is `null` when the feature is off.
+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
@@ -685,8 +704,75 @@ Customer objects carry `externalId`. Everything else — `signals.usageLog()`,
 the invoice, payment and purchase lists, `portal.createToken()` and members —
 still takes ClockNext's id.
 
-Models, credits, outcomes, units, composites and plans are created and edited in
-the ClockNext dashboard, not through the SDK.
+## 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: "Deep Research",
+  agentKey: "deep_research",
+  marginPercent: 20,
+  modelBundle: [
+    { modelId: "claude-sonnet-4-5", averageTokensPerLLMCall: 100000, input: 60, output: 30, cache: 5, cacheWrite: 5 },
+  ],
+});
+
+const outcome = await cnk.outcomes.create({
+  name: "Contract review",
+  agentKey: "contract_review",
+  marginPercent: 100,
+  steps: [
+    { name: "Extract clauses", agentKey: "contract_review.extract",
+      modelBundle: [{ modelId: "claude-sonnet-4-5", averageTokensPerLLMCall: 50000, input: 70, output: 30, cache: 0 }] },
+  ],
+});
+
+const unit = await cnk.units.create({
+  name: "API calls",
+  agentKey: "api_calls",
+  pricingType: "SLAB",
+  tiers: [{ upTo: 1000, price: 0.01 }, { upTo: null, price: 0.005 }], // last tier: "and above"
+});
+
+const composite = await cnk.composites.create({
+  name: "Voice AI call",
+  refId: "voice_ai",
+  price: 2.5,
+  entitlements: { creditIds: [credit.id] },
+});
+
+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 },
+  ],
+});
+
+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
+```
+
+Models are enabled in the ClockNext dashboard. A bundle line names its model by
+`modelId` — the same id you send as `usage.model` on a signal.
 
 ## Customer portal
 

package/dist/index.cjs

@@ -65,6 +65,7 @@ var FIELD_PATHS = [
   [/\busage\.inputTokens\b/g, "tokens.input"],
   [/\busage\.outputTokens\b/g, "tokens.output"],
   [/\busage\.cacheTokens\b/g, "tokens.cache"],
+  [/\busage\.cacheWriteTokens\b/g, "tokens.cacheWrite"],
   [/\busage\.model\b/g, "model"],
   // A missing/invalid `usage` block as a whole: the caller's equivalent is
   // `tokens` (plus `model`, which the SDK hoists to the top level).
@@ -332,7 +333,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.15.0" ;
+var SDK_VERSION = "0.17.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -436,6 +437,143 @@ var Transport = class {
   }
 };
 
+// src/filters.ts
+function activeQuery(active) {
+  return active === true ? "true" : void 0;
+}
+function filterByActive(rows, active) {
+  return active === false ? rows.filter((row) => !row.isActive) : rows;
+}
+
+// src/resources/composites.ts
+var Composites = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** List them. `{ active: true }` returns only active ones, `{ active: false }`
+   *  only archived ones; omit it for both. */
+  async list(params = {}) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: "/api/v1/composites",
+      query: { active: activeQuery(params.active) }
+    });
+    return filterByActive(res.composites, params.active);
+  }
+  /** One composite's configuration. */
+  async get(id) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: `/api/v1/composites/${encodeURIComponent(id)}`
+    });
+    return res.composite;
+  }
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/composites",
+      body: input
+    });
+    return res.composite;
+  }
+  /** PARTIAL update: only the fields you send change. `entitlements`, when
+   *  sent, is the complete new set. Renaming `refId` cuts live traffic over at
+   *  once — ship the new tag to your callers first. */
+  async update(id, input) {
+    const res = await this.transport.request({
+      method: "PATCH",
+      path: `/api/v1/composites/${encodeURIComponent(id)}`,
+      body: input
+    });
+    return res.composite;
+  }
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/composites/${encodeURIComponent(id)}/archive`,
+      retry: true
+    });
+    return res.composite;
+  }
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/composites/${encodeURIComponent(id)}/unarchive`,
+      retry: true
+    });
+    return res.composite;
+  }
+};
+
+// src/resources/credits.ts
+var Credits = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** List them. `{ active: true }` returns only active ones, `{ active: false }`
+   *  only archived ones; omit it for both. */
+  async list(params = {}) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: "/api/v1/credits",
+      query: { active: activeQuery(params.active) }
+    });
+    return filterByActive(res.credits, params.active);
+  }
+  /** One credit's configuration. */
+  async get(id) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`
+    });
+    return res.credit;
+  }
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/credits",
+      body: input
+    });
+    return res.credit;
+  }
+  /** PARTIAL update: only the fields you send change. Send `modelBundle` to
+   *  re-price; leave it out to keep the stored base price. */
+  async update(id, input) {
+    const res = await this.transport.request({
+      method: "PATCH",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`,
+      body: input
+    });
+    return res.credit;
+  }
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/credits/${encodeURIComponent(id)}/archive`,
+      retry: true
+    });
+    return res.credit;
+  }
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/credits/${encodeURIComponent(id)}/unarchive`,
+      retry: true
+    });
+    return res.credit;
+  }
+};
+
 // src/idempotency.ts
 function newKey() {
   const c = globalThis.crypto;
@@ -664,7 +802,7 @@ var Customers = class {
    * Top up (positive `delta`) or draw down (negative `delta`) a customer's
    * wallet, in USD — allowed whatever the customer's plan. `remaining` is the
    * resulting USD balance. No `agentKey` — a customer has exactly one wallet.
-   * Pass `pool: "RESERVED"` to move the Reserved Wallet instead (then
+   * Pass `pool: "reserved"` to move the Reserved Wallet instead (then
    * `remaining` is its balance). `POST …/:id/wallet/adjust`.
    */
   adjustWallet(id, input) {
@@ -795,6 +933,71 @@ var Invoices = class {
   }
 };
 
+// src/resources/outcomes.ts
+var Outcomes = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** List them. `{ active: true }` returns only active ones, `{ active: false }`
+   *  only archived ones; omit it for both. */
+  async list(params = {}) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: "/api/v1/outcomes",
+      query: { active: activeQuery(params.active) }
+    });
+    return filterByActive(res.outcomes, params.active);
+  }
+  /** One outcome's configuration, with every step in full. */
+  async get(id) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}`
+    });
+    return res.outcome;
+  }
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/outcomes",
+      body: input
+    });
+    return res.outcome;
+  }
+  /** PARTIAL update: only the fields you send change. Leave `steps` out to
+   *  leave the steps alone; send it and it is the complete list — pass each
+   *  existing step's `id` (or its same `agentKey`) to keep it. */
+  async update(id, input) {
+    const res = await this.transport.request({
+      method: "PATCH",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
+      body: input
+    });
+    return res.outcome;
+  }
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}/archive`,
+      retry: true
+    });
+    return res.outcome;
+  }
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}/unarchive`,
+      retry: true
+    });
+    return res.outcome;
+  }
+};
+
 // src/resources/payments.ts
 var Payments = class {
   constructor(transport) {
@@ -819,14 +1022,6 @@ var Payments = class {
   }
 };
 
-// src/filters.ts
-function activeQuery(active) {
-  return active === true ? "true" : void 0;
-}
-function filterByActive(rows, active) {
-  return active === false ? rows.filter((row) => !row.isActive) : rows;
-}
-
 // src/resources/plans.ts
 var Plans = class {
   constructor(transport) {
@@ -844,6 +1039,54 @@ var Plans = class {
     });
     return filterByActive(res.plans, params.active);
   }
+  /** One plan's configuration. */
+  async get(id) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: `/api/v1/plans/${encodeURIComponent(id)}`
+    });
+    return res.plan;
+  }
+  /** Create a plan. It starts active. Not retried on failure — a retry could
+   *  create a second plan. */
+  async create(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/plans",
+      body: input
+    });
+    return res.plan;
+  }
+  /** PARTIAL update: only the fields you send change. `entitlements`, when
+   *  sent, is the complete new list — the list `get()` returned can be sent
+   *  back as it is. Changes apply to new purchases only. */
+  async update(id, input) {
+    const res = await this.transport.request({
+      method: "PATCH",
+      path: `/api/v1/plans/${encodeURIComponent(id)}`,
+      body: input
+    });
+    return res.plan;
+  }
+  /** Retire a plan (`isActive` → false): it can't be bought any more; customers
+   *  already on it are unaffected. Safe to retry. */
+  async archive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/plans/${encodeURIComponent(id)}/archive`,
+      retry: true
+    });
+    return res.plan;
+  }
+  /** Make an archived plan purchasable again (`isActive` → true). Safe to retry. */
+  async unarchive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/plans/${encodeURIComponent(id)}/unarchive`,
+      retry: true
+    });
+    return res.plan;
+  }
 };
 
 // src/resources/portal.ts
@@ -949,12 +1192,14 @@ function signalToWire(signal) {
   const body = {
     ...customerRefToWire(signal),
     // `usage` is required on all three model-priced kinds. input/output are
-    // always sent; `cacheTokens` only when provided (the server defaults 0).
+    // always sent; `cacheTokens` / `cacheWriteTokens` only when provided (the
+    // server defaults each to 0).
     usage: {
       model: signal.model,
       inputTokens: t.input,
       outputTokens: t.output,
-      ...t.cache != null ? { cacheTokens: t.cache } : {}
+      ...t.cache != null ? { cacheTokens: t.cache } : {},
+      ...t.cacheWrite != null ? { cacheWriteTokens: t.cacheWrite } : {}
     }
   };
   if (signal.member) body.member = signal.member;
@@ -1204,14 +1449,86 @@ var Signals = class {
   }
 };
 
+// src/resources/units.ts
+var Units = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** List them. `{ active: true }` returns only active ones, `{ active: false }`
+   *  only archived ones; omit it for both. */
+  async list(params = {}) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: "/api/v1/units",
+      query: { active: activeQuery(params.active) }
+    });
+    return filterByActive(res.units, params.active);
+  }
+  /** One unit's configuration. */
+  async get(id) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: `/api/v1/units/${encodeURIComponent(id)}`
+    });
+    return res.unit;
+  }
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/units",
+      body: input
+    });
+    return res.unit;
+  }
+  /** PARTIAL update: only the fields you send change. `tiers`, when sent, is
+   *  the complete new tier list. */
+  async update(id, input) {
+    const res = await this.transport.request({
+      method: "PATCH",
+      path: `/api/v1/units/${encodeURIComponent(id)}`,
+      body: input
+    });
+    return res.unit;
+  }
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/units/${encodeURIComponent(id)}/archive`,
+      retry: true
+    });
+    return res.unit;
+  }
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id) {
+    const res = await this.transport.request({
+      method: "POST",
+      path: `/api/v1/units/${encodeURIComponent(id)}/unarchive`,
+      retry: true
+    });
+    return res.unit;
+  }
+};
+
 // src/client.ts
 var ClockNext = class {
   /** Record usage signals (credit / wallet / outcome / unit) and read the usage log. */
   signals;
   /** Manage customers, their members, and balances. */
   customers;
-  /** List billing plans. */
+  /** Billing plans: list, get, create, update, archive, unarchive. */
   plans;
+  /** Credits: list, get, create, update, archive, unarchive (no delete). */
+  credits;
+  /** Outcomes: list, get, create, update, archive, unarchive (no delete). */
+  outcomes;
+  /** Units: list, get, create, update, archive, unarchive (no delete). */
+  units;
+  /** Composites: list, get, create, update, archive, unarchive (no delete). */
+  composites;
   /** Subscribe customers to plans (purchases). */
   purchases;
   /** Read invoices and mint hosted pay links. */
@@ -1234,6 +1551,10 @@ var ClockNext = class {
     this.signals = new Signals(transport, this.flusher, this.cfg);
     this.customers = new Customers(transport);
     this.plans = new Plans(transport);
+    this.credits = new Credits(transport);
+    this.outcomes = new Outcomes(transport);
+    this.units = new Units(transport);
+    this.composites = new Composites(transport);
     this.purchases = new Purchases(transport);
     this.invoices = new Invoices(transport);
     this.payments = new Payments(transport);