@clocknext/sdk 0.3.0 → 0.4.0

package/README.md

@@ -90,12 +90,16 @@ const cnk = new ClockNext({ apiKey, mode: "sync" });
 - **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`), idempotent replaces (`PUT`, e.g.
-  `customers.setCurrency`), and `DELETE` are retried automatically. Metering
-  signals (`signals.*`) opt into retries too, since metering is best-effort.
-  Other non-idempotent writes — e.g. `customers.create`, `plans.create`,
+- **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
@@ -140,9 +144,8 @@ await cnk.customers.removeMember(c.id, members[0].id);
 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)
 
-// billing config
-await cnk.customers.setCurrency(c.id, "EUR");
-await cnk.customers.setCreditTypes(c.id, ["cr_1", "cr_2"]);
+// billing config — currency is set through update()
+await cnk.customers.update(c.id, { currencyCode: "EUR" });
 
 // grant / claw back balances (delta is signed)
 await cnk.customers.adjustCredit(c.id, { creditId: "cr_1", delta: 100 });
@@ -200,7 +203,7 @@ await cnk.outcomes.create({
 });
 
 // unit type — a quantity-priced meter (FLAT / SLAB / VOLUME)
-await cnk.units.create({ name: "Seats", pricingType: "FLAT", flatPrice: 5 });
+await cnk.units.create({ name: "Seats", agentKey: "seats", pricingType: "FLAT", flatPrice: 5 });
 ```
 
 ### Unit metering
@@ -208,7 +211,7 @@ await cnk.units.create({ name: "Seats", pricingType: "FLAT", flatPrice: 5 });
 Record a unit event (no tokens) and read a customer's unit balances:
 
 ```ts
-await cnk.signals.unit({ customerId: c.id, unit: "Seats" });
+await cnk.signals.unit({ customerId: c.id, agentKey: "seats" });
 await cnk.signals.unitUsage({ customerId: c.id });
 ```
 

package/dist/index.cjs

@@ -229,7 +229,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.3.0" ;
+var SDK_VERSION = "0.4.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -526,22 +526,9 @@ var Customers = class {
       body: input
     });
   }
-  /** Set the customer's currency. `PUT …/:id/currency`. */
-  async setCurrency(id, currencyCode) {
-    await this.transport.request({
-      method: "PUT",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/currency`,
-      body: { currencyCode }
-    });
-  }
-  /** Set which credit types the customer is billed against. `PUT …/:id/credits`. */
-  async setCreditTypes(id, creditIds) {
-    await this.transport.request({
-      method: "PUT",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/credits`,
-      body: { creditIds }
-    });
-  }
+  // Note: a customer's currency is set through `update(id, { currencyCode })`
+  // (PATCH …/:id) — there is no separate currency endpoint. Credit-type
+  // assignment has no public API.
   // --- Balance adjustments -------------------------------------------------
   /** Grant or claw back a credit balance. `POST …/:id/credits/adjust`. */
   async adjustCredit(id, input) {
@@ -830,6 +817,17 @@ var Purchases = class {
   }
 };
 
+// src/idempotency.ts
+function newKey() {
+  const c = globalThis.crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+    const r = Math.random() * 16 | 0;
+    const v = ch === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+
 // src/resources/signals.ts
 function signalToWire(signal) {
   const body = {
@@ -838,17 +836,15 @@ function signalToWire(signal) {
     model: signal.model
   };
   if (signal.member) body.member = signal.member;
-  if (signal.status) body.status = signal.status;
   if (signal.custom) body.custom = signal.custom;
   const t = signal.tokens;
-  if (t) {
-    if (t.input != null) body.inputTokens = t.input;
-    if (t.output != null) body.outputTokens = t.output;
-    if (t.cache != null) body.cacheTokens = t.cache;
-  }
+  body.inputTokens = t.input;
+  body.outputTokens = t.output;
+  if (t.cache != null) body.cacheTokens = t.cache;
   if (signal.type === "credit" || signal.type === "outcome") {
     body.agentKey = signal.agentKey;
   }
+  if (signal.idempotencyKey) body.idempotencyKey = signal.idempotencyKey;
   return body;
 }
 var Signals = class {
@@ -862,6 +858,7 @@ var Signals = class {
   cfg;
   async track(signal, opts = {}) {
     const body = signalToWire(signal);
+    if (body.idempotencyKey == null) body.idempotencyKey = newKey();
     const sendNow = opts.wait || this.cfg.mode === "sync";
     if (!sendNow) {
       this.flusher.enqueue({ body, signal });
@@ -879,6 +876,23 @@ var Signals = class {
       usageLog: res.usageLog ?? null
     };
   }
+  /**
+   * Validate + price a signal WITHOUT recording it (server `dryRun`). Returns
+   * the projected usage log so an integration can preflight before sending real
+   * traffic — no inbox row, wallet / outcome writes, or webhooks fire.
+   */
+  async verify(signal) {
+    const body = signalToWire(signal);
+    body.dryRun = true;
+    const res = await this.transport.request({
+      method: "POST",
+      path: "/api/v1/usage",
+      body,
+      // A dry run writes nothing, so it is always safe to retry.
+      retry: true
+    });
+    return res.usageLog ?? null;
+  }
   /** Meter a named credit. */
   credit(input, opts) {
     return this.track({ ...input, type: "credit" }, opts);
@@ -901,9 +915,9 @@ var Signals = class {
     return { customer: res.customer, totals: res.totals, logs: res.logs };
   }
   /**
-   * Record one unit-metered event (a fixed-price meter with no tokens), matched
-   * to a catalog unit by name. Sent immediately — unit events are not buffered.
-   * `POST /api/v1/units`.
+   * Record one unit-metered event (a fixed-price meter with no tokens),
+   * addressed to a catalog unit by its `agentKey`. Sent immediately — unit
+   * events are not buffered. `POST /api/v1/units`.
    */
   async unit(input) {
     return this.transport.request({
@@ -911,7 +925,7 @@ var Signals = class {
       path: "/api/v1/units",
       body: {
         customerId: input.customerId,
-        unit: input.unit,
+        agentKey: input.agentKey,
         ...input.member ? { member: input.member } : {}
       },
       // Best-effort metering opts into retries on transient failures.
@@ -1019,6 +1033,33 @@ var Webhooks = class {
   }
 };
 
+// src/resources/workspace.ts
+var Workspace = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** Identify the org + key behind the request, incl. `sandbox` | `live`. */
+  me() {
+    return this.transport.request({
+      method: "GET",
+      path: "/api/v1/me"
+    });
+  }
+  /** The org's enabled models with live prices. `{ active: true }` returns only
+   *  the models that can be metered right now. */
+  async models(params = {}) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: "/api/v1/models",
+      query: {
+        active: params.active === void 0 ? void 0 : String(params.active)
+      }
+    });
+    return res.models;
+  }
+};
+
 // src/client.ts
 var ClockNext = class {
   /** Record + read usage signals (credit / wallet / outcome / unit). */
@@ -1043,6 +1084,8 @@ var ClockNext = class {
   webhooks;
   /** Mint customer-portal embed tokens. */
   portal;
+  /** Identify the workspace (sandbox/live) + list its models. `/me`, `/models`. */
+  workspace;
   cfg;
   flusher;
   constructor(config) {
@@ -1065,6 +1108,7 @@ var ClockNext = class {
     this.units = new Units(transport);
     this.webhooks = new Webhooks(transport);
     this.portal = new Portal(transport);
+    this.workspace = new Workspace(transport);
   }
   /** Number of signals currently buffered (async mode). */
   get pending() {