@clocknext/sdk 0.3.0 → 0.5.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.5.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -339,13 +339,14 @@ var Credits = class {
     });
     return res.credits;
   }
-  /** Create a credit type. `POST /api/v1/credits`. */
+  /** Create a credit type; returns the created credit. `POST /api/v1/credits`. */
   async create(input) {
-    await this.transport.request({
+    const res = await this.transport.request({
       method: "POST",
       path: "/api/v1/credits",
       body: input
     });
+    return res.credit;
   }
   /** Fetch one credit type with usage stats. `GET /api/v1/credits/:id`. */
   async get(id) {
@@ -355,13 +356,14 @@ var Credits = class {
     });
     return res.credit;
   }
-  /** Update a credit type's definition. `PATCH /api/v1/credits/:id`. */
+  /** Update a credit type's definition; returns the updated credit. `PATCH /api/v1/credits/:id`. */
   async update(id, input) {
-    await this.transport.request({
+    const res = await this.transport.request({
       method: "PATCH",
       path: `/api/v1/credits/${encodeURIComponent(id)}`,
       body: input
     });
+    return res.credit;
   }
   /** Activate or deactivate a credit type. */
   async setActive(id, isActive) {
@@ -441,12 +443,12 @@ var Customers = class {
       path: `/api/v1/customers/${encodeURIComponent(id)}`
     });
   }
-  /** A customer's usage history. `GET /api/v1/customers/:id/usage`. */
+  /** A customer's usage history. `GET /api/v1/usage?customerId=`. */
   async usage(id, params = {}) {
     const res = await this.transport.request({
       method: "GET",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/usage`,
-      query: { limit: params.limit }
+      path: `/api/v1/usage`,
+      query: { customerId: id, limit: params.limit }
     });
     return { customer: res.customer, totals: res.totals, logs: res.logs };
   }
@@ -457,6 +459,37 @@ var Customers = class {
       path: `/api/v1/customers/${encodeURIComponent(id)}/balances`
     });
   }
+  /**
+   * One credit balance for a customer, matched by `creditId` or `creditName`;
+   * `null` when the customer has no plan or no matching credit. Convenience
+   * over `balances()` + `Array.find` — it fetches the FULL balances under the
+   * hood (there is no server-side scoped read), so prefer `balances()` when you
+   * need several rows from the same customer.
+   */
+  async creditBalance(customerId, match) {
+    const { credits } = await this.balances(customerId);
+    return credits.find(
+      (c) => match.creditId != null && c.creditId === match.creditId || match.creditName != null && c.creditName === match.creditName
+    ) ?? null;
+  }
+  /** One outcome balance for a customer, matched by `outcomeId` or
+   *  `outcomeName`; `null` when absent. See {@link creditBalance} for the
+   *  fetch-then-filter caveat. */
+  async outcomeBalance(customerId, match) {
+    const { outcomes } = await this.balances(customerId);
+    return outcomes.find(
+      (o) => match.outcomeId != null && o.outcomeId === match.outcomeId || match.outcomeName != null && o.outcomeName === match.outcomeName
+    ) ?? null;
+  }
+  /** One unit balance for a customer, matched by `unitId` or `unitName`;
+   *  `null` when absent. See {@link creditBalance} for the fetch-then-filter
+   *  caveat. */
+  async unitBalance(customerId, match) {
+    const { units } = await this.balances(customerId);
+    return units.find(
+      (u) => match.unitId != null && u.unitId === match.unitId || match.unitName != null && u.unitName === match.unitName
+    ) ?? null;
+  }
   /** The customer's current plan. `GET …/:id/plan`. */
   plan(id) {
     return this.transport.request({
@@ -464,14 +497,6 @@ var Customers = class {
       path: `/api/v1/customers/${encodeURIComponent(id)}/plan`
     });
   }
-  /** Revenue / cost / profit / margin over a window. `GET …/:id/revenue`. */
-  revenue(id, params = {}) {
-    return this.transport.request({
-      method: "GET",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/revenue`,
-      query: { range: params.range }
-    });
-  }
   // --- Members -------------------------------------------------------------
   /** List a customer's members. `GET …/:id/members`. */
   async listMembers(id) {
@@ -526,22 +551,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) {
@@ -650,13 +662,14 @@ var Outcomes = class {
     });
     return res.outcome;
   }
-  /** Activate or deactivate an outcome type. */
+  /** Activate or deactivate an outcome type; returns the updated outcome. */
   async setActive(id, isActive) {
-    await this.transport.request({
+    const res = await this.transport.request({
       method: "PATCH",
       path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
       body: { isActive }
     });
+    return res.outcome;
   }
   /** Delete an outcome type. */
   async delete(id) {
@@ -830,6 +843,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 +862,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 +884,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 +902,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 +941,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 +951,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 +1059,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 +1110,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 +1134,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() {