@clocknext/sdk 0.3.0 → 0.5.0

package/dist/index.js

@@ -227,7 +227,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;
@@ -337,13 +337,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) {
@@ -353,13 +354,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) {
@@ -439,12 +441,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 };
   }
@@ -455,6 +457,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({
@@ -462,14 +495,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) {
@@ -524,22 +549,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) {
@@ -648,13 +660,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) {
@@ -828,6 +841,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 = {
@@ -836,17 +860,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 {
@@ -860,6 +882,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 });
@@ -877,6 +900,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);
@@ -899,9 +939,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({
@@ -909,7 +949,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.
@@ -1017,6 +1057,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). */
@@ -1041,6 +1108,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) {
@@ -1063,6 +1132,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() {