@clocknext/sdk 0.16.0 → 0.18.0

package/README.md

@@ -561,7 +561,8 @@ await cnk.customers.unitBalance(customerId, { unitName: "Seats" });
 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
+  // page.usageLogs — each row has a `type`: credit | outcome | unit | wallet | composite,
+  // and `custom`: the `custom` object sent on the signal (or null)
   cursor = page.nextCursor ?? undefined;
 } while (cursor);
 ```
@@ -727,7 +728,7 @@ const credit = await cnk.credits.create({
   agentKey: "deep_research",
   marginPercent: 20,
   modelBundle: [
-    { orgModelId: "cm_model_01", averageTokensPerLLMCall: 100000, input: 60, output: 30, cache: 5, cacheWrite: 5 },
+    { modelId: "claude-sonnet-4-5", averageTokensPerLLMCall: 100000, input: 60, output: 30, cache: 5, cacheWrite: 5 },
   ],
 });
 
@@ -737,7 +738,7 @@ const outcome = await cnk.outcomes.create({
   marginPercent: 100,
   steps: [
     { name: "Extract clauses", agentKey: "contract_review.extract",
-      modelBundle: [{ orgModelId: "cm_model_01", averageTokensPerLLMCall: 50000, input: 70, output: 30, cache: 0 }] },
+      modelBundle: [{ modelId: "claude-sonnet-4-5", averageTokensPerLLMCall: 50000, input: 70, output: 30, cache: 0 }] },
   ],
 });
 
@@ -771,8 +772,44 @@ 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's `orgModelId` is
-the workspace's id for the model.
+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.
+
+## Taxes
+
+`cnk.taxes` manages the tax rates charged to your customers by billing country
+— the same rates as **Settings → Taxes** in the dashboard. Every active tax for
+a customer's country is applied to their invoices and portal purchases
+automatically; a customer with no country is charged no tax.
+
+It has four calls: `list()`, `get(id)`, `create(input)` and `update(id, input)`.
+
+- **`behavior` is lower case:** `"inclusive"` (already inside the price) or
+  `"exclusive"` (added on top).
+- **`countryCode`** is a 2-letter ISO code (`"IN"`, `"GB"`); lower case is
+  accepted, a country name is refused.
+- **No duplicates:** two active taxes can't share a name (ignoring case) in the
+  same country — that's a `ConflictError`.
+- **`update()` is partial**, and only affects invoices issued afterwards —
+  issued invoices keep the tax they were issued with.
+- **Archiving is dashboard-only.** There is no `archive()` / `unarchive()` /
+  `delete()`; an archived tax reads back with `isActive: false` and can still
+  be updated.
+
+```ts
+const gst = await cnk.taxes.create({
+  name: "GST",
+  percentage: 18,
+  countryCode: "IN",
+  behavior: "exclusive",
+  description: "India GST",
+});
+
+const active = await cnk.taxes.list({ active: true }); // omit for archived ones too
+const one = await cnk.taxes.get(gst.id);
+
+await cnk.taxes.update(gst.id, { percentage: 12 }); // only the percentage changes
+```
 
 ## Customer portal
 

package/dist/index.cjs

@@ -333,7 +333,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.16.0" ;
+var SDK_VERSION = "0.18.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -1441,7 +1441,6 @@ var Signals = class {
         customerId: params.customerId,
         limit: params.limit,
         cursor: params.cursor,
-        period: params.period,
         from: params.from,
         to: params.to
       }
@@ -1513,6 +1512,54 @@ var Units = class {
   }
 };
 
+// src/resources/taxes.ts
+var Taxes = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** List them, oldest first. `{ 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/taxes",
+      query: { active: activeQuery(params.active) }
+    });
+    return filterByActive(res.taxes, params.active);
+  }
+  /** One tax. */
+  async get(id) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: `/api/v1/taxes/${encodeURIComponent(id)}`
+    });
+    return res.tax;
+  }
+  /** Create one. It starts active. Two active taxes can't share a name
+   *  (ignoring case) in the same country — that's a `ConflictError`. 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/taxes",
+      body: input
+    });
+    return res.tax;
+  }
+  /** PARTIAL update: only the fields you send change. Archived taxes can be
+   *  edited and stay archived. Only invoices issued afterwards use the new
+   *  values. */
+  async update(id, input) {
+    const res = await this.transport.request({
+      method: "PATCH",
+      path: `/api/v1/taxes/${encodeURIComponent(id)}`,
+      body: input
+    });
+    return res.tax;
+  }
+};
+
 // src/client.ts
 var ClockNext = class {
   /** Record usage signals (credit / wallet / outcome / unit) and read the usage log. */
@@ -1529,6 +1576,8 @@ var ClockNext = class {
   units;
   /** Composites: list, get, create, update, archive, unarchive (no delete). */
   composites;
+  /** Tax rates by country: list, get, create, update (archive in the dashboard). */
+  taxes;
   /** Subscribe customers to plans (purchases). */
   purchases;
   /** Read invoices and mint hosted pay links. */
@@ -1555,6 +1604,7 @@ var ClockNext = class {
     this.outcomes = new Outcomes(transport);
     this.units = new Units(transport);
     this.composites = new Composites(transport);
+    this.taxes = new Taxes(transport);
     this.purchases = new Purchases(transport);
     this.invoices = new Invoices(transport);
     this.payments = new Payments(transport);