@clocknext/sdk 0.13.0 → 0.15.0

package/src/resources/customers.ts

@@ -1,6 +1,8 @@
 import type { Transport } from "../http.js";
+import { newKey } from "../idempotency.js";
 import type {
   AddMemberInput,
+  AdjustResult,
   ApiCustomer,
   CompositeAdjustInput,
   CreateCustomerInput,
@@ -14,19 +16,18 @@ import type {
   MemberProfile,
   OutcomeAdjustInput,
   OutcomeBalance,
+  RecurringGrantInput,
+  RecurringGrantResult,
   RemovedMember,
   UnitAdjustInput,
   UnitBalance,
   UpdateMemberInput,
-  UsageList,
-  WalletEntryInput,
-  WalletList,
-  WalletTransaction,
+  WalletAdjustInput,
 } from "../types.js";
 
 /**
  * The `customers` resource — full CRUD over the org's customers plus the
- * read-only insight endpoints (usage / balances / plan). Every call is scoped
+ * read-only insight endpoints (balances / plan). Every call is scoped
  * to the API key's organisation server-side; a customer in another org
  * resolves as a NotFoundError.
  */
@@ -94,6 +95,42 @@ export class Customers {
     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: string): Promise<ApiCustomer> {
+    const res = await this.transport.request<{ customer: ApiCustomer }>({
+      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: string,
+    input: CustomerProfileInput,
+  ): Promise<ApiCustomer> {
+    const res = await this.transport.request<{ customer: ApiCustomer }>({
+      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: string): Promise<void> {
+    await this.transport.request({
+      method: "DELETE",
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}`,
+    });
+  }
+
   /** Delete a customer (members, invitations, usage logs cascade). */
   async delete(id: string): Promise<void> {
     await this.transport.request({
@@ -102,21 +139,20 @@ export class Customers {
     });
   }
 
-  /** A customer's usage history. `GET /api/v1/usage?customerId=`. */
-  async usage(id: string, params: { limit?: number } = {}): Promise<UsageList> {
-    const res = await this.transport.request<UsageList>({
+  /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
+  balances(id: string): Promise<CustomerBalances> {
+    return this.transport.request<CustomerBalances>({
       method: "GET",
-      path: `/api/v1/usage`,
-      query: { customerId: id, limit: params.limit },
+      path: `/api/v1/customers/${encodeURIComponent(id)}/balances`,
     });
-    return { customer: res.customer, totals: res.totals, logs: res.logs };
   }
 
-  /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
-  balances(id: string): Promise<CustomerBalances> {
+  /** {@link balances}, addressing the customer by its `externalId`.
+   *  `GET /api/v1/customers/ext/:externalId/balances`. */
+  balancesByExternalId(externalId: string): Promise<CustomerBalances> {
     return this.transport.request<CustomerBalances>({
       method: "GET",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/balances`,
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}/balances`,
     });
   }
 
@@ -183,6 +219,15 @@ export class Customers {
     });
   }
 
+  /** {@link plan}, addressing the customer by its `externalId`.
+   *  `GET /api/v1/customers/ext/:externalId/plan`. */
+  planByExternalId(externalId: string): Promise<CustomerPlan> {
+    return this.transport.request<CustomerPlan>({
+      method: "GET",
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}/plan`,
+    });
+  }
+
   // --- Members -------------------------------------------------------------
 
   /** List a customer's members. `GET …/:id/members`. */
@@ -227,95 +272,169 @@ export class Customers {
     return res.member;
   }
 
-  // --- Wallet & billing config --------------------------------------------
+  // --- Billing config -----------------------------------------------------
 
-  /** The customer's wallet balance + transactions. `GET …/:id/wallet`. */
-  wallet(id: string, params: { limit?: number } = {}): Promise<WalletList> {
-    return this.transport.request<WalletList>({
-      method: "GET",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/wallet`,
-      query: { limit: params.limit },
-    });
+  // 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. 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: string, input: CreditAdjustInput): Promise<AdjustResult> {
+    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: string, input: OutcomeAdjustInput): Promise<AdjustResult> {
+    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: string, input: UnitAdjustInput): Promise<AdjustResult> {
+    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: string, input: CompositeAdjustInput): Promise<AdjustResult> {
+    return this.adjust(`/api/v1/customers/${encodeURIComponent(id)}/composites/adjust`, input);
   }
 
   /**
-   * Record a manual wallet entry (top-up or deduction). `amount` is always
-   * positive; the sign comes from `type`. `POST …/:id/wallet`.
+   * 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`.
    */
-  async addWalletEntry(
-    id: string,
-    input: WalletEntryInput,
-  ): Promise<{ transaction: WalletTransaction; balanceUsd: number }> {
-    return this.transport.request<{
-      transaction: WalletTransaction;
-      balanceUsd: number;
-    }>({
-      method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/wallet`,
-      body: input,
-    });
+  adjustWallet(id: string, input: WalletAdjustInput): Promise<AdjustResult> {
+    return this.adjust(`/api/v1/customers/${encodeURIComponent(id)}/wallet/adjust`, input);
   }
 
-  // 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.
+  /** {@link adjustCredit}, addressing the customer by its `externalId` (`id`
+   *  here). `POST /api/v1/customers/ext/:externalId/credits/adjust`. */
+  adjustCreditByExternalId(id: string, input: CreditAdjustInput): Promise<AdjustResult> {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/credits/adjust`, input);
+  }
 
-  // --- Balance adjustments -------------------------------------------------
+  /** {@link adjustOutcome}, addressing the customer by its `externalId` (`id`
+   *  here). `POST /api/v1/customers/ext/:externalId/outcomes/adjust`. */
+  adjustOutcomeByExternalId(id: string, input: OutcomeAdjustInput): Promise<AdjustResult> {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/outcomes/adjust`, input);
+  }
 
-  /** Grant or claw back a credit balance. Returns the remaining balance.
-   *  `POST …/:id/credits/adjust`. */
-  async adjustCredit(
-    id: string,
-    input: CreditAdjustInput,
-  ): Promise<{ remaining: number }> {
-    const res = await this.transport.request<{ remaining: number }>({
-      method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/credits/adjust`,
-      body: input,
-    });
-    return { remaining: res.remaining };
+  /** {@link adjustUnit}, addressing the customer by its `externalId` (`id`
+   *  here). `POST /api/v1/customers/ext/:externalId/units/adjust`. */
+  adjustUnitByExternalId(id: string, input: UnitAdjustInput): Promise<AdjustResult> {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/units/adjust`, input);
   }
 
-  /** Grant or claw back an outcome balance. Returns the remaining balance. */
-  async adjustOutcome(
-    id: string,
-    input: OutcomeAdjustInput,
-  ): Promise<{ remaining: number }> {
-    const res = await this.transport.request<{ remaining: number }>({
-      method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/outcomes/adjust`,
-      body: input,
-    });
-    return { remaining: res.remaining };
+  /** {@link adjustComposite}, addressing the customer by its `externalId`
+   *  (`id` here). `POST /api/v1/customers/ext/:externalId/composites/adjust`. */
+  adjustCompositeByExternalId(id: string, input: CompositeAdjustInput): Promise<AdjustResult> {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/composites/adjust`, input);
   }
 
-  /** Grant or claw back a unit balance. Returns the remaining balance. */
-  async adjustUnit(
-    id: string,
-    input: UnitAdjustInput,
-  ): Promise<{ remaining: number }> {
-    const res = await this.transport.request<{ remaining: number }>({
+  /** {@link adjustWallet}, addressing the customer by its `externalId` (`id`
+   *  here). `POST /api/v1/customers/ext/:externalId/wallet/adjust`. */
+  adjustWalletByExternalId(id: string, input: WalletAdjustInput): Promise<AdjustResult> {
+    return this.adjust(`/api/v1/customers/ext/${encodeURIComponent(id)}/wallet/adjust`, 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.
+   */
+  private async adjust(
+    path: string,
+    input:
+      | CreditAdjustInput
+      | OutcomeAdjustInput
+      | UnitAdjustInput
+      | CompositeAdjustInput
+      | WalletAdjustInput,
+  ): Promise<AdjustResult> {
+    const idempotencyKey = input.idempotencyKey ?? newKey();
+    const res = await this.transport.request<{
+      remaining: number;
+      replayed?: boolean;
+      adjustedAt?: string;
+      customerArchived?: boolean;
+    }>({
       method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/units/adjust`,
-      body: input,
+      path,
+      idempotencyKey,
+      body: { ...input, idempotencyKey },
+      retry: true,
     });
-    return { remaining: res.remaining };
+
+    const result: AdjustResult = {
+      remaining: res.remaining,
+      replayed: res.replayed === true,
+      customerArchived: res.customerArchived === true,
+    };
+    if (result.replayed && typeof res.adjustedAt === "string") {
+      result.adjustedAt = res.adjustedAt;
+    }
+    return result;
   }
 
+  // --- Recurring grants ----------------------------------------------------
+
   /**
-   * 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`.
+   * 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 adjustComposite(
+  async updateRecurringGrant(
     id: string,
-    input: CompositeAdjustInput,
-  ): Promise<{ remaining: number }> {
-    const res = await this.transport.request<{ remaining: number }>({
-      method: "POST",
-      path: `/api/v1/customers/${encodeURIComponent(id)}/composites/adjust`,
+    input: RecurringGrantInput,
+  ): Promise<RecurringGrantResult> {
+    const res = await this.transport.request<
+      RecurringGrantResult & { updated: true }
+    >({
+      method: "PUT",
+      path: `/api/v1/customers/${encodeURIComponent(id)}/recurring-grant`,
+      body: input,
+    });
+    return toRecurringGrantResult(res);
+  }
+
+  /** {@link updateRecurringGrant}, addressing the customer by its
+   *  `externalId`. `PUT /api/v1/customers/ext/:externalId/recurring-grant`. */
+  async updateRecurringGrantByExternalId(
+    externalId: string,
+    input: RecurringGrantInput,
+  ): Promise<RecurringGrantResult> {
+    const res = await this.transport.request<
+      RecurringGrantResult & { updated: true }
+    >({
+      method: "PUT",
+      path: `/api/v1/customers/ext/${encodeURIComponent(externalId)}/recurring-grant`,
       body: input,
     });
-    return { remaining: res.remaining };
+    return toRecurringGrantResult(res);
   }
 }
+
+/** Drop the response's `updated: true` marker, keeping `balanceUsd` only when
+ *  the server sent it (wallet grants). */
+function toRecurringGrantResult(res: RecurringGrantResult): RecurringGrantResult {
+  return {
+    kind: res.kind,
+    quantity: res.quantity,
+    ...(res.balanceUsd !== undefined ? { balanceUsd: res.balanceUsd } : {}),
+  };
+}

package/src/resources/invoices.ts

@@ -39,7 +39,7 @@ export class Invoices {
   }
 
   /**
-   * 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: string): Promise<PayLink> {

package/src/resources/plans.ts

@@ -1,16 +1,11 @@
 import { activeQuery, filterByActive } from "../filters.js";
 import type { Transport } from "../http.js";
-import type {
-  CreatePlanInput,
-  Plan,
-  PlanDetail,
-  UpdatePlanInput,
-} from "../types.js";
+import type { Plan } from "../types.js";
 
 /**
- * The `plans` resource — define and manage the billing plans customers
- * subscribe to. Each plan is a set of entitlement components (wallet / credit /
- * outcome / unit / flat) billed on a cycle. `/api/v1/plans`.
+ * The `plans` resource — read the billing plans customers can subscribe to.
+ * Each plan is a set of entitlement components (wallet / credit / outcome /
+ * unit / flat) billed on a cycle. `/api/v1/plans`.
  */
 export class Plans {
   constructor(private readonly transport: Transport) {}
@@ -26,51 +21,4 @@ export class Plans {
     });
     return filterByActive(res.plans, params.active);
   }
-
-  /** Create a plan. `POST /api/v1/plans`. */
-  async create(input: CreatePlanInput): Promise<Plan> {
-    const res = await this.transport.request<{ plan: Plan }>({
-      method: "POST",
-      path: "/api/v1/plans",
-      body: input,
-    });
-    return res.plan;
-  }
-
-  /** Fetch one plan with aggregate subscriber/invoice stats. `GET /api/v1/plans/:id`. */
-  async get(id: string): Promise<PlanDetail> {
-    const res = await this.transport.request<{ plan: PlanDetail }>({
-      method: "GET",
-      path: `/api/v1/plans/${encodeURIComponent(id)}`,
-    });
-    return res.plan;
-  }
-
-  /** Replace a plan's definition (components + settings). `PATCH /api/v1/plans/:id`. */
-  async update(id: string, input: UpdatePlanInput): Promise<Plan> {
-    const res = await this.transport.request<{ plan: Plan }>({
-      method: "PATCH",
-      path: `/api/v1/plans/${encodeURIComponent(id)}`,
-      body: input,
-    });
-    return res.plan;
-  }
-
-  /** Activate or deactivate a plan without rewriting it. */
-  async setActive(id: string, isActive: boolean): Promise<Plan> {
-    const res = await this.transport.request<{ plan: Plan }>({
-      method: "PATCH",
-      path: `/api/v1/plans/${encodeURIComponent(id)}`,
-      body: { isActive },
-    });
-    return res.plan;
-  }
-
-  /** Delete a plan. Refused once any customer has purchased it. */
-  async delete(id: string): Promise<void> {
-    await this.transport.request({
-      method: "DELETE",
-      path: `/api/v1/plans/${encodeURIComponent(id)}`,
-    });
-  }
 }

package/src/resources/signals.ts

@@ -1,5 +1,6 @@
 import type { Transport } from "../http.js";
 import type { Flusher } from "../flusher.js";
+import { customerRefToWire } from "../customer-ref.js";
 import { newKey } from "../idempotency.js";
 import type {
   CompositeCompletionInput,
@@ -15,8 +16,8 @@ import type {
   TrackResult,
   UnitInput,
   UnitTrackResult,
-  UnitUsageList,
-  UsageList,
+  UsageLogListParams,
+  UsageLogPage,
   WalletInput,
 } from "../types.js";
 
@@ -44,6 +45,7 @@ const SIGNAL_PATHS: Record<SignalType, string> = {
 const UNIT_PATH = "/api/v1/signal/unit";
 const COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
 const OUTCOME_COMPLETE_PATH = "/api/v1/signal/outcome/complete";
+const USAGE_LOG_PATH = "/api/v1/signal/usage-log";
 
 /**
  * Builds the request body for a typed Signal.
@@ -65,7 +67,7 @@ const OUTCOME_COMPLETE_PATH = "/api/v1/signal/outcome/complete";
 export function signalToWire(signal: Signal): Record<string, unknown> {
   const t = signal.tokens;
   const body: Record<string, unknown> = {
-    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).
     usage: {
@@ -279,9 +281,8 @@ export class Signals {
       path: OUTCOME_COMPLETE_PATH,
       idempotencyKey,
       body: {
-        customerId: input.customerId,
+        ...customerRefToWire(input),
         runId: input.runId,
-        complete: true,
         ...(input.member ? { member: input.member } : {}),
         idempotencyKey,
       },
@@ -297,27 +298,6 @@ export class Signals {
     };
   }
 
-  /**
-   * 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: {
-    customerId: string;
-    limit?: number;
-  }): Promise<UsageList> {
-    const res = await this.transport.request<UsageList>({
-      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
@@ -339,7 +319,7 @@ export class Signals {
       path: UNIT_PATH,
       idempotencyKey,
       body: {
-        customerId: input.customerId,
+        ...customerRefToWire(input),
         agentKey: input.agentKey,
         ...(input.quantity != null ? { quantity: input.quantity } : {}),
         ...(input.member ? { member: input.member } : {}),
@@ -407,7 +387,7 @@ export class Signals {
       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
@@ -430,19 +410,34 @@ export class Signals {
   }
 
   /**
-   * A customer's unit balances + recent unit events. `GET /api/v1/units`.
+   * One customer's usage history, merged from every meter kind — credit,
+   * outcome, unit, wallet, and completed composite occurrences — into one
+   * feed sorted by time. `GET /api/v1/signal/usage-log`. Exactly the same
+   * rows the customer portal's own "Usage logs" table shows, so a caller can
+   * build against this instead of the portal UI.
    *
-   * 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.
+   * Cursor-paginated, NOT page-numbered: `limit` + `cursor` in, `nextCursor`
+   * out. Omit `cursor` for the first page; pass the previous page's
+   * `nextCursor` back to fetch the next one, and stop once it comes back
+   * `null`. Unlike offset pagination, the cost of a page never grows with how
+   * deep you've paged — each page only asks for rows strictly before the
+   * cursor's position.
+   *
+   * Read-only; unlike {@link track}/{@link unit}/etc., there is nothing to
+   * buffer or retry here.
    */
-  unitUsage(params: {
-    customerId: string;
-    limit?: number;
-  }): Promise<UnitUsageList> {
-    return this.transport.request<UnitUsageList>({
+  usageLog(params: UsageLogListParams): Promise<UsageLogPage> {
+    return this.transport.request<UsageLogPage>({
       method: "GET",
-      path: "/api/v1/units",
-      query: { customerId: params.customerId, limit: params.limit },
+      path: USAGE_LOG_PATH,
+      query: {
+        customerId: params.customerId,
+        limit: params.limit,
+        cursor: params.cursor,
+        period: params.period,
+        from: params.from,
+        to: params.to,
+      },
     });
   }
 }