@clocknext/sdk 0.14.0 → 0.16.0

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).
@@ -77,7 +78,8 @@ function translateFieldPaths(message) {
   }
   return out;
 }
-var ALLOWANCE_MESSAGE = /\binsufficient\b|\bno allowance left\b|\bno slots left\b|\boutcomes remaining\b|\btop up the (?:allowance|balance)\b/i;
+var ALLOWANCE_MESSAGE = /\binsufficient\b|\bno allowance left\b|\bno slots left\b|\boutcomes remaining\b|\btop up the (?:allowance|balance)\b|\bbelow zero\b/i;
+var IDEMPOTENCY_KEY_REUSED = /\bidempotency key was already used\b/i;
 function isAllowanceFailure(message, code) {
   if (code) return code === "ALLOWANCE_EXHAUSTED";
   return ALLOWANCE_MESSAGE.test(message);
@@ -101,6 +103,9 @@ function errorFromResponse(status, message, retryAfterMs, meta = {}) {
     });
   }
   if (status === 422) {
+    if (IDEMPOTENCY_KEY_REUSED.test(raw)) {
+      return new ConflictError(raw, { ...opts, retryable: false });
+    }
     return isAllowanceFailure(raw, code) ? new AllowanceError(raw, opts) : new PlanError(raw, opts);
   }
   if (status === 429) return new RateLimitError(raw, { retryAfterMs, idempotencyKey });
@@ -328,7 +333,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.14.0" ;
+var SDK_VERSION = "0.16.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -446,11 +451,8 @@ var Composites = class {
     this.transport = transport;
   }
   transport;
-  /** List composites. Pass `{ active: true }` for only the ones a signal can
-   *  still be tagged with — the default list INCLUDES archived ones, which
-   *  keep every row they already own.
-   *  `{ active: false }` returns only archived ones; omitting it returns
-   *  both. See `activeQuery` — the API itself only supports `true`. */
+  /** 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",
@@ -459,7 +461,16 @@ var Composites = class {
     });
     return filterByActive(res.composites, params.active);
   }
-  /** Create a composite. `POST /api/v1/composites`. */
+  /** 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",
@@ -468,6 +479,35 @@ var Composites = class {
     });
     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
@@ -476,9 +516,8 @@ var Credits = class {
     this.transport = transport;
   }
   transport;
-  /** List credit types. Pass `{ active: true }` to only return active ones.
-   *  `{ active: false }` returns only archived ones; omitting it returns
-   *  both. See `activeQuery` — the API itself only supports `true`. */
+  /** 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",
@@ -487,24 +526,26 @@ var Credits = class {
     });
     return filterByActive(res.credits, params.active);
   }
-  /** Create a credit type; returns the created credit. `POST /api/v1/credits`. */
-  async create(input) {
+  /** One credit's configuration. */
+  async get(id) {
     const res = await this.transport.request({
-      method: "POST",
-      path: "/api/v1/credits",
-      body: input
+      method: "GET",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`
     });
     return res.credit;
   }
-  /** Fetch one credit type with usage stats. `GET /api/v1/credits/:id`. */
-  async get(id) {
+  /** 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: "GET",
-      path: `/api/v1/credits/${encodeURIComponent(id)}`
+      method: "POST",
+      path: "/api/v1/credits",
+      body: input
     });
     return res.credit;
   }
-  /** Update a credit type's definition; returns the updated credit. `PATCH /api/v1/credits/:id`. */
+  /** 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",
@@ -513,24 +554,37 @@ var Credits = class {
     });
     return res.credit;
   }
-  /** Activate or deactivate a credit type. */
-  async setActive(id, isActive) {
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id) {
     const res = await this.transport.request({
-      method: "PATCH",
-      path: `/api/v1/credits/${encodeURIComponent(id)}`,
-      body: { isActive }
+      method: "POST",
+      path: `/api/v1/credits/${encodeURIComponent(id)}/archive`,
+      retry: true
     });
     return res.credit;
   }
-  /** Delete a credit type. Refused while a customer is linked to it. */
-  async delete(id) {
-    await this.transport.request({
-      method: "DELETE",
-      path: `/api/v1/credits/${encodeURIComponent(id)}`
+  /** 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;
+  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/customers.ts
 var Customers = class {
   constructor(transport) {
@@ -584,6 +638,36 @@ var Customers = class {
     });
     return res.customer;
   }
+  /**
+   * Fetch one customer by YOUR id for them (its `externalId`), instead of
+   * ours. Same result as {@link get}. `GET /api/v1/customers/ext/:externalId`.
+   * An unknown external id is a `NotFoundError`; only active customers match.
+   */
+  async getByExternalId(externalId) {
+    const res = await this.transport.request({
+      method: "GET",
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}`
+    });
+    return res.customer;
+  }
+  /** Update a customer (partial), addressed by its `externalId`. Same body as
+   *  {@link update}. `PATCH /api/v1/customers/ext/:externalId`. */
+  async updateByExternalId(externalId, input) {
+    const res = await this.transport.request({
+      method: "PATCH",
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}`,
+      body: input
+    });
+    return res.customer;
+  }
+  /** {@link delete}, addressing the customer by its `externalId`.
+   *  `DELETE /api/v1/customers/ext/:externalId`. */
+  async deleteByExternalId(externalId) {
+    await this.transport.request({
+      method: "DELETE",
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}`
+    });
+  }
   /** Delete a customer (members, invitations, usage logs cascade). */
   async delete(id) {
     await this.transport.request({
@@ -591,15 +675,6 @@ var Customers = class {
       path: `/api/v1/customers/${encodeURIComponent(id)}`
     });
   }
-  /** 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/usage`,
-      query: { customerId: id, limit: params.limit }
-    });
-    return { customer: res.customer, totals: res.totals, logs: res.logs };
-  }
   /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
   balances(id) {
     return this.transport.request({
@@ -607,6 +682,14 @@ var Customers = class {
       path: `/api/v1/customers/${encodeURIComponent(id)}/balances`
     });
   }
+  /** {@link balances}, addressing the customer by its `externalId`.
+   *  `GET /api/v1/customers/ext/:externalId/balances`. */
+  balancesByExternalId(externalId) {
+    return this.transport.request({
+      method: "GET",
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}/balances`
+    });
+  }
   /**
    * One credit balance for a customer, matched by `creditId` or `creditName`;
    * `null` when the customer has no plan or no matching credit. Convenience
@@ -645,6 +728,14 @@ var Customers = class {
       path: `/api/v1/customers/${encodeURIComponent(id)}/plan`
     });
   }
+  /** {@link plan}, addressing the customer by its `externalId`.
+   *  `GET /api/v1/customers/ext/:externalId/plan`. */
+  planByExternalId(externalId) {
+    return this.transport.request({
+      method: "GET",
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}/plan`
+    });
+  }
   // --- Members -------------------------------------------------------------
   /** List a customer's members. `GET …/:id/members`. */
   async listMembers(id) {
@@ -680,72 +771,129 @@ var Customers = class {
     });
     return res.member;
   }
-  // --- Wallet & billing config --------------------------------------------
-  /** The customer's wallet balance + transactions. `GET …/:id/wallet`. */
-  wallet(id, params = {}) {
-    return this.transport.request({
-      method: "GET",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/wallet`,
-      query: { limit: params.limit }
-    });
-  }
-  /**
-   * Record a manual wallet entry (top-up or deduction). `amount` is always
-   * positive; the sign comes from `type`. `POST …/:id/wallet`.
-   */
-  async addWalletEntry(id, input) {
-    return this.transport.request({
-      method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/wallet`,
-      body: input
-    });
-  }
+  // --- Billing config -----------------------------------------------------
   // 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. Returns the remaining balance.
-   *  `POST …/:id/credits/adjust`. */
-  async adjustCredit(id, input) {
-    const res = await this.transport.request({
-      method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/credits/adjust`,
-      body: input
-    });
-    return { remaining: res.remaining };
+  /** Grant or claw back a credit balance. The credit must be a prepaid part of
+   *  the customer's current plan. Pass `idempotencyKey` to make it safe to
+   *  retry. `POST …/:id/credits/adjust`. */
+  adjustCredit(id, input) {
+    return this.adjust(`/api/v1/customers/${encodeURIComponent(id)}/credits/adjust`, input);
+  }
+  /** Grant or claw back an outcome balance. The outcome must be a prepaid part
+   *  of the customer's current plan. `POST …/:id/outcomes/adjust`. */
+  adjustOutcome(id, input) {
+    return this.adjust(`/api/v1/customers/${encodeURIComponent(id)}/outcomes/adjust`, input);
+  }
+  /** Grant or claw back a unit balance. The unit must be a prepaid part of the
+   *  customer's current plan. `POST …/:id/units/adjust`. */
+  adjustUnit(id, input) {
+    return this.adjust(`/api/v1/customers/${encodeURIComponent(id)}/units/adjust`, input);
+  }
+  /** Grant or claw back slots on a customer's ADVANCE composite pool for the
+   *  current billing cycle. `remaining` is the resulting slot count.
+   *  `POST …/:id/composites/adjust`. */
+  adjustComposite(id, input) {
+    return this.adjust(`/api/v1/customers/${encodeURIComponent(id)}/composites/adjust`, input);
+  }
+  /**
+   * 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
+   * `remaining` is its balance). `POST …/:id/wallet/adjust`.
+   */
+  adjustWallet(id, input) {
+    return this.adjust(`/api/v1/customers/${encodeURIComponent(id)}/wallet/adjust`, input);
+  }
+  /** {@link adjustCredit}, addressing the customer by its `externalId` (`id`
+   *  here). `POST /api/v1/customers/ext/:externalId/credits/adjust`. */
+  adjustCreditByExternalId(id, input) {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/credits/adjust`, input);
+  }
+  /** {@link adjustOutcome}, addressing the customer by its `externalId` (`id`
+   *  here). `POST /api/v1/customers/ext/:externalId/outcomes/adjust`. */
+  adjustOutcomeByExternalId(id, input) {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/outcomes/adjust`, input);
+  }
+  /** {@link adjustUnit}, addressing the customer by its `externalId` (`id`
+   *  here). `POST /api/v1/customers/ext/:externalId/units/adjust`. */
+  adjustUnitByExternalId(id, input) {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/units/adjust`, input);
+  }
+  /** {@link adjustComposite}, addressing the customer by its `externalId`
+   *  (`id` here). `POST /api/v1/customers/ext/:externalId/composites/adjust`. */
+  adjustCompositeByExternalId(id, input) {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/composites/adjust`, input);
+  }
+  /** {@link adjustWallet}, addressing the customer by its `externalId` (`id`
+   *  here). `POST /api/v1/customers/ext/:externalId/wallet/adjust`. */
+  adjustWalletByExternalId(id, input) {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/wallet/adjust`, input);
   }
-  /** Grant or claw back an outcome balance. Returns the remaining balance. */
-  async adjustOutcome(id, input) {
+  /**
+   * The one body behind all ten adjust calls.
+   *
+   * Every adjustment carries an idempotency key — the caller's, or one
+   * generated here ONCE per call, exactly like signals. The server
+   * deduplicates on it, so a transient failure is safe to retry: the same key
+   * rides every attempt, and a retry of one that already landed comes back as
+   * `replayed: true` instead of adjusting again. The key is also copied onto
+   * any thrown error (`error.idempotencyKey`) so the caller can replay safely.
+   */
+  async adjust(path, input) {
+    const idempotencyKey = input.idempotencyKey ?? newKey();
     const res = await this.transport.request({
       method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/outcomes/adjust`,
-      body: input
+      path,
+      idempotencyKey,
+      body: { ...input, idempotencyKey },
+      retry: true
     });
-    return { remaining: res.remaining };
+    const result = {
+      remaining: res.remaining,
+      replayed: res.replayed === true,
+      customerArchived: res.customerArchived === true
+    };
+    if (result.replayed && typeof res.adjustedAt === "string") {
+      result.adjustedAt = res.adjustedAt;
+    }
+    return result;
   }
-  /** Grant or claw back a unit balance. Returns the remaining balance. */
-  async adjustUnit(id, input) {
+  // --- Recurring grants ----------------------------------------------------
+  /**
+   * Change how much a customer is granted every billing cycle (wallet top-up,
+   * credits, outcomes, units or a composite pool). Any increase or decrease
+   * applies to their current balance immediately. `PUT …/:id/recurring-grant`.
+   */
+  async updateRecurringGrant(id, input) {
     const res = await this.transport.request({
-      method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/units/adjust`,
+      method: "PUT",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/recurring-grant`,
       body: input
     });
-    return { remaining: res.remaining };
+    return toRecurringGrantResult(res);
   }
-  /**
-   * Grant or claw back slots on a customer's ADVANCE composite pool for the
-   * current billing cycle. Returns the resulting `remaining` slot count.
-   * `POST …/:id/composites/adjust`.
-   */
-  async adjustComposite(id, input) {
+  /** {@link updateRecurringGrant}, addressing the customer by its
+   *  `externalId`. `PUT /api/v1/customers/ext/:externalId/recurring-grant`. */
+  async updateRecurringGrantByExternalId(externalId, input) {
     const res = await this.transport.request({
-      method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/composites/adjust`,
+      method: "PUT",
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}/recurring-grant`,
       body: input
     });
-    return { remaining: res.remaining };
+    return toRecurringGrantResult(res);
   }
 };
+function toRecurringGrantResult(res) {
+  return {
+    kind: res.kind,
+    quantity: res.quantity,
+    ...res.balanceUsd !== void 0 ? { balanceUsd: res.balanceUsd } : {}
+  };
+}
 
 // src/resources/invoices.ts
 var Invoices = class {
@@ -774,7 +922,7 @@ var Invoices = class {
     });
   }
   /**
-   * Mint a hosted pay link for an OPEN invoice. PAID/VOID invoices are rejected
+   * Mint a hosted pay link for an OPEN invoice. PAID/VOID/AUTO_CLOSED invoices are rejected
    * with a `ConflictError`. `GET /api/v1/invoices/:id/pay-link`.
    */
   payLink(id) {
@@ -791,9 +939,8 @@ var Outcomes = class {
     this.transport = transport;
   }
   transport;
-  /** List outcome types. Pass `{ active: true }` to only return active ones.
-   *  `{ active: false }` returns only archived ones; omitting it returns
-   *  both. See `activeQuery` — the API itself only supports `true`. */
+  /** 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",
@@ -802,24 +949,27 @@ var Outcomes = class {
     });
     return filterByActive(res.outcomes, params.active);
   }
-  /** Create an outcome type with its steps. `POST /api/v1/outcomes`. */
-  async create(input) {
+  /** One outcome's configuration, with every step in full. */
+  async get(id) {
     const res = await this.transport.request({
-      method: "POST",
-      path: "/api/v1/outcomes",
-      body: input
+      method: "GET",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}`
     });
     return res.outcome;
   }
-  /** Fetch one outcome type with steps + stats. `GET /api/v1/outcomes/:id`. */
-  async get(id) {
+  /** 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: "GET",
-      path: `/api/v1/outcomes/${encodeURIComponent(id)}`
+      method: "POST",
+      path: "/api/v1/outcomes",
+      body: input
     });
     return res.outcome;
   }
-  /** Update an outcome type's definition. `PATCH /api/v1/outcomes/:id`. */
+  /** 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",
@@ -828,21 +978,23 @@ var Outcomes = class {
     });
     return res.outcome;
   }
-  /** Activate or deactivate an outcome type; returns the updated outcome. */
-  async setActive(id, isActive) {
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id) {
     const res = await this.transport.request({
-      method: "PATCH",
-      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
-      body: { isActive }
+      method: "POST",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}/archive`,
+      retry: true
     });
     return res.outcome;
   }
-  /** Delete an outcome type. */
-  async delete(id) {
-    await this.transport.request({
-      method: "DELETE",
-      path: `/api/v1/outcomes/${encodeURIComponent(id)}`
+  /** 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;
   }
 };
 
@@ -887,24 +1039,27 @@ var Plans = class {
     });
     return filterByActive(res.plans, params.active);
   }
-  /** Create a plan. `POST /api/v1/plans`. */
-  async create(input) {
+  /** One plan's configuration. */
+  async get(id) {
     const res = await this.transport.request({
-      method: "POST",
-      path: "/api/v1/plans",
-      body: input
+      method: "GET",
+      path: `/api/v1/plans/${encodeURIComponent(id)}`
     });
     return res.plan;
   }
-  /** Fetch one plan with aggregate subscriber/invoice stats. `GET /api/v1/plans/:id`. */
-  async get(id) {
+  /** 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: "GET",
-      path: `/api/v1/plans/${encodeURIComponent(id)}`
+      method: "POST",
+      path: "/api/v1/plans",
+      body: input
     });
     return res.plan;
   }
-  /** Replace a plan's definition (components + settings). `PATCH /api/v1/plans/:id`. */
+  /** 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",
@@ -913,21 +1068,24 @@ var Plans = class {
     });
     return res.plan;
   }
-  /** Activate or deactivate a plan without rewriting it. */
-  async setActive(id, isActive) {
+  /** 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: "PATCH",
-      path: `/api/v1/plans/${encodeURIComponent(id)}`,
-      body: { isActive }
+      method: "POST",
+      path: `/api/v1/plans/${encodeURIComponent(id)}/archive`,
+      retry: true
     });
     return res.plan;
   }
-  /** Delete a plan. Refused once any customer has purchased it. */
-  async delete(id) {
-    await this.transport.request({
-      method: "DELETE",
-      path: `/api/v1/plans/${encodeURIComponent(id)}`
+  /** 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;
   }
 };
 
@@ -1011,15 +1169,12 @@ 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/customer-ref.ts
+function customerRefToWire(ref) {
+  return {
+    ...ref.customerId != null ? { customerId: ref.customerId } : {},
+    ...ref.externalId != null ? { externalId: ref.externalId } : {}
+  };
 }
 
 // src/resources/signals.ts
@@ -1035,14 +1190,16 @@ var USAGE_LOG_PATH = "/api/v1/signal/usage-log";
 function signalToWire(signal) {
   const t = signal.tokens;
   const body = {
-    customerId: signal.customerId,
+    ...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;
@@ -1146,9 +1303,8 @@ var Signals = class {
       path: OUTCOME_COMPLETE_PATH,
       idempotencyKey,
       body: {
-        customerId: input.customerId,
+        ...customerRefToWire(input),
         runId: input.runId,
-        complete: true,
         ...input.member ? { member: input.member } : {},
         idempotencyKey
       },
@@ -1163,23 +1319,6 @@ var Signals = class {
       ...handles(res)
     };
   }
-  /**
-   * Recent usage logs + totals for a customer. `GET /api/v1/usage`.
-   *
-   * Still the legacy path, deliberately. The `/api/v1/signal/*` family is
-   * POST-only — it replaced how usage is INGESTED, not how it is read — so
-   * `GET /api/v1/usage` has no successor and is not deprecated. It is also the
-   * only way to prove a signal landed, which matters more now that ingestion
-   * answers `202` for everything.
-   */
-  async list(params) {
-    const res = await this.transport.request({
-      method: "GET",
-      path: "/api/v1/usage",
-      query: { customerId: params.customerId, limit: params.limit }
-    });
-    return { customer: res.customer, totals: res.totals, logs: res.logs };
-  }
   /**
    * Record one unit-metered event (a fixed-price meter with no tokens),
    * addressed to a catalog unit by its `agentKey`. Sent immediately — unit
@@ -1199,7 +1338,7 @@ var Signals = class {
       path: UNIT_PATH,
       idempotencyKey,
       body: {
-        customerId: input.customerId,
+        ...customerRefToWire(input),
         agentKey: input.agentKey,
         ...input.quantity != null ? { quantity: input.quantity } : {},
         ...input.member ? { member: input.member } : {},
@@ -1256,7 +1395,7 @@ var Signals = class {
       path: COMPOSITE_COMPLETE_PATH,
       idempotencyKey,
       body: {
-        customerId: input.customerId,
+        ...customerRefToWire(input),
         composite: { [input.composite.ref]: input.composite.value },
         // Auto-assigned like the others. A retry here could not double-BILL
         // even without it — closing a closed occurrence is a server-side
@@ -1277,19 +1416,6 @@ var Signals = class {
       ...handles(res)
     };
   }
-  /**
-   * A customer's unit balances + recent unit events. `GET /api/v1/units`.
-   *
-   * Legacy path for the same reason as {@link list}: the signal family is
-   * POST-only, so the read side has no successor and is not deprecated.
-   */
-  unitUsage(params) {
-    return this.transport.request({
-      method: "GET",
-      path: "/api/v1/units",
-      query: { customerId: params.customerId, limit: params.limit }
-    });
-  }
   /**
    * One customer's usage history, merged from every meter kind — credit,
    * outcome, unit, wallet, and completed composite occurrences — into one
@@ -1329,148 +1455,88 @@ var Units = class {
     this.transport = transport;
   }
   transport;
-  /** List unit types. Pass `{ active: true }` to only return active ones.
-   *  `{ active: false }` returns only archived ones; omitting it returns
-   *  both. See `activeQuery` — the API itself only supports `true`. */
+  /** 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-catalog",
+      path: "/api/v1/units",
       query: { active: activeQuery(params.active) }
     });
     return filterByActive(res.units, params.active);
   }
-  /** Create a unit type. `POST /api/v1/units-catalog`. */
-  async create(input) {
-    const res = await this.transport.request({
-      method: "POST",
-      path: "/api/v1/units-catalog",
-      body: input
-    });
-    return res.unit;
-  }
-  /** Fetch one unit type with stats. `GET /api/v1/units-catalog/:id`. */
+  /** One unit's configuration. */
   async get(id) {
     const res = await this.transport.request({
       method: "GET",
-      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`
+      path: `/api/v1/units/${encodeURIComponent(id)}`
     });
     return res.unit;
   }
-  /** Update a unit type's definition. `PATCH /api/v1/units-catalog/:id`. */
-  async update(id, input) {
+  /** 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: "PATCH",
-      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`,
+      method: "POST",
+      path: "/api/v1/units",
       body: input
     });
     return res.unit;
   }
-  /** Activate or deactivate a unit type. */
-  async setActive(id, isActive) {
+  /** 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-catalog/${encodeURIComponent(id)}`,
-      body: { isActive }
+      path: `/api/v1/units/${encodeURIComponent(id)}`,
+      body: input
     });
     return res.unit;
   }
-  /** Delete a unit type. */
-  async delete(id) {
-    await this.transport.request({
-      method: "DELETE",
-      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`
-    });
-  }
-};
-
-// src/resources/webhooks.ts
-var Webhooks = class {
-  constructor(transport) {
-    this.transport = transport;
-  }
-  transport;
-  /** List configured webhooks. `GET /api/v1/webhooks`. */
-  async list() {
-    const res = await this.transport.request({
-      method: "GET",
-      path: "/api/v1/webhooks"
-    });
-    return res.webhooks;
-  }
-  /** Create or replace the webhook for a kind. `POST /api/v1/webhooks`. */
-  async upsert(input) {
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id) {
     const res = await this.transport.request({
       method: "POST",
-      path: "/api/v1/webhooks",
-      body: input
-    });
-    return res.webhook;
-  }
-  /** Delete the webhook for a kind (idempotent). `DELETE /api/v1/webhooks/:kind`. */
-  async delete(kind) {
-    await this.transport.request({
-      method: "DELETE",
-      path: `/api/v1/webhooks/${encodeURIComponent(kind)}`
-    });
-  }
-};
-
-// 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"
+      path: `/api/v1/units/${encodeURIComponent(id)}/archive`,
+      retry: true
     });
+    return res.unit;
   }
-  /** The org's enabled models with live prices. `{ active: true }` returns only
-   *  the models that can be metered right now.
-   *  `{ active: false }` returns only archived ones; omitting it returns
-   *  both. See `activeQuery` — the API itself only supports `true`. */
-  async models(params = {}) {
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id) {
     const res = await this.transport.request({
-      method: "GET",
-      path: "/api/v1/models",
-      query: { active: activeQuery(params.active) }
+      method: "POST",
+      path: `/api/v1/units/${encodeURIComponent(id)}/unarchive`,
+      retry: true
     });
-    return filterByActive(res.models, params.active);
+    return res.unit;
   }
 };
 
 // src/client.ts
 var ClockNext = class {
-  /** Record + read usage signals (credit / wallet / outcome / unit). */
+  /** Record usage signals (credit / wallet / outcome / unit) and read the usage log. */
   signals;
-  /** Manage customers, their members, wallet, and balances. */
+  /** Manage customers, their members, and balances. */
   customers;
-  /** Define and manage 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. */
   invoices;
   /** Read payments (paid invoices). */
   payments;
-  /** Manage the credit-type catalog. */
-  credits;
-  /** Manage the composite catalog — bundles billed as one thing. */
-  composites;
-  /** Manage the outcome-type catalog. */
-  outcomes;
-  /** Manage the unit-type catalog. */
-  units;
-  /** Configure threshold webhooks. */
-  webhooks;
   /** Mint customer-portal embed tokens. */
   portal;
-  /** Identify the workspace (sandbox/live) + list its models. `/me`, `/models`. */
-  workspace;
   cfg;
   flusher;
   constructor(config) {
@@ -1485,16 +1551,14 @@ var ClockNext = class {
     this.signals = new Signals(transport, this.flusher, this.cfg);
     this.customers = new Customers(transport);
     this.plans = new Plans(transport);
-    this.purchases = new Purchases(transport);
-    this.invoices = new Invoices(transport);
-    this.payments = new Payments(transport);
     this.credits = new Credits(transport);
-    this.composites = new Composites(transport);
     this.outcomes = new Outcomes(transport);
     this.units = new Units(transport);
-    this.webhooks = new Webhooks(transport);
+    this.composites = new Composites(transport);
+    this.purchases = new Purchases(transport);
+    this.invoices = new Invoices(transport);
+    this.payments = new Payments(transport);
     this.portal = new Portal(transport);
-    this.workspace = new Workspace(transport);
   }
   /** Number of signals currently buffered (async mode). */
   get pending() {