@clocknext/sdk 0.14.0 → 0.16.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/outcomes.ts

@@ -1,29 +1,23 @@
 import { activeQuery, filterByActive } from "../filters.js";
 import type { Transport } from "../http.js";
-import type {
-  CreateOutcomeInput,
-  Outcome,
-  OutcomeDetail,
-  UpdateOutcomeInput,
-} from "../types.js";
+import type { CreateOutcomeInput, Outcome, OutcomeWithSteps, UpdateOutcomeInput } from "../types.js";
 
 /**
- * The `outcomes` resource — manage the org's outcome *types* (the catalog). An
- * outcome is a multi-step workflow. `/api/v1/outcomes`.
+ * The `outcomes` resource — multi-step deliverables billed per completed
+ * outcome. `/api/v1/outcomes`.
  *
- * Two distinct kinds of agent key, in separate namespaces, each unique per
- * organisation — do not conflate them:
- * - the OUTCOME's own `agentKey`, REQUIRED on `create()` and `update()`, which
- *   names the outcome itself in the catalogue;
- * - each STEP's `agentKey`, which is what you pass to `signals.outcome()` to
- *   report usage and to the outcome-adjust API.
+ * `list()` and every write return the outcome without its steps; `get()`
+ * returns it with every step in full (ids included). Each new step is priced
+ * from its own `modelBundle`, on the server.
+ *
+ * There is no `delete()` — the API never deletes catalogue items. Retire an
+ * outcome with `archive()`; `unarchive()` brings it back unchanged.
  */
 export class Outcomes {
   constructor(private readonly 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: { active?: boolean } = {}): Promise<Outcome[]> {
     const res = await this.transport.request<{ outcomes: Outcome[] }>({
       method: "GET",
@@ -33,28 +27,31 @@ export class Outcomes {
     return filterByActive(res.outcomes, params.active);
   }
 
-  /** Create an outcome type with its steps. `POST /api/v1/outcomes`. */
-  async create(input: CreateOutcomeInput): Promise<Outcome> {
-    const res = await this.transport.request<{ outcome: Outcome }>({
-      method: "POST",
-      path: "/api/v1/outcomes",
-      body: input,
+  /** One outcome's configuration, with every step in full. */
+  async get(id: string): Promise<OutcomeWithSteps> {
+    const res = await this.transport.request<{ outcome: OutcomeWithSteps }>({
+      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: string): Promise<OutcomeDetail> {
-    const res = await this.transport.request<{ outcome: OutcomeDetail }>({
-      method: "GET",
-      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input: CreateOutcomeInput): Promise<Outcome> {
+    const res = await this.transport.request<{ created: true; outcome: Outcome }>({
+      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: string, input: UpdateOutcomeInput): Promise<Outcome> {
-    const res = await this.transport.request<{ outcome: Outcome }>({
+    const res = await this.transport.request<{ updated: true; outcome: Outcome }>({
       method: "PATCH",
       path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
       body: input,
@@ -62,21 +59,23 @@ export class Outcomes {
     return res.outcome;
   }
 
-  /** Activate or deactivate an outcome type; returns the updated outcome. */
-  async setActive(id: string, isActive: boolean): Promise<Outcome> {
-    const res = await this.transport.request<{ outcome: Outcome }>({
-      method: "PATCH",
-      path: `/api/v1/outcomes/${encodeURIComponent(id)}`,
-      body: { isActive },
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id: string): Promise<Outcome> {
+    const res = await this.transport.request<{ archived: true; outcome: Outcome }>({
+      method: "POST",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}/archive`,
+      retry: true,
     });
     return res.outcome;
   }
 
-  /** Delete an outcome type. */
-  async delete(id: string): Promise<void> {
-    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: string): Promise<Outcome> {
+    const res = await this.transport.request<{ unarchived: true; outcome: Outcome }>({
+      method: "POST",
+      path: `/api/v1/outcomes/${encodeURIComponent(id)}/unarchive`,
+      retry: true,
     });
+    return res.outcome;
   }
 }

package/src/resources/plans.ts

@@ -1,16 +1,16 @@
 import { activeQuery, filterByActive } from "../filters.js";
 import type { Transport } from "../http.js";
-import type {
-  CreatePlanInput,
-  Plan,
-  PlanDetail,
-  UpdatePlanInput,
-} from "../types.js";
+import type { CreatePlanInput, Plan, UpdatePlanInput } 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 — the billing plans customers subscribe to. Each plan
+ * is a set of `entitlements` (wallet / credit / outcome / unit / composite /
+ * flat lines) billed on a cycle. `/api/v1/plans`.
+ *
+ * A plan's currency is the workspace's primary currency; it can't be chosen.
+ * There is no `delete()` — the API never deletes plans, so customers already
+ * on one keep what they bought. Retire a plan with `archive()`; `unarchive()`
+ * makes it purchasable again.
  */
 export class Plans {
   constructor(private readonly transport: Transport) {}
@@ -27,28 +27,31 @@ export class Plans {
     return filterByActive(res.plans, params.active);
   }
 
-  /** Create a plan. `POST /api/v1/plans`. */
-  async create(input: CreatePlanInput): Promise<Plan> {
+  /** One plan's configuration. */
+  async get(id: string): Promise<Plan> {
     const res = await this.transport.request<{ plan: Plan }>({
-      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: string): Promise<PlanDetail> {
-    const res = await this.transport.request<{ plan: PlanDetail }>({
-      method: "GET",
-      path: `/api/v1/plans/${encodeURIComponent(id)}`,
+  /** Create a plan. It starts active. Not retried on failure — a retry could
+   *  create a second plan. */
+  async create(input: CreatePlanInput): Promise<Plan> {
+    const res = await this.transport.request<{ created: true; plan: Plan }>({
+      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: string, input: UpdatePlanInput): Promise<Plan> {
-    const res = await this.transport.request<{ plan: Plan }>({
+    const res = await this.transport.request<{ updated: true; plan: Plan }>({
       method: "PATCH",
       path: `/api/v1/plans/${encodeURIComponent(id)}`,
       body: input,
@@ -56,21 +59,24 @@ export class Plans {
     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 },
+  /** Retire a plan (`isActive` → false): it can't be bought any more; customers
+   *  already on it are unaffected. Safe to retry. */
+  async archive(id: string): Promise<Plan> {
+    const res = await this.transport.request<{ archived: true; plan: Plan }>({
+      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: string): Promise<void> {
-    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: string): Promise<Plan> {
+    const res = await this.transport.request<{ unarchived: true; plan: Plan }>({
+      method: "POST",
+      path: `/api/v1/plans/${encodeURIComponent(id)}/unarchive`,
+      retry: true,
     });
+    return res.plan;
   }
 }