@shipstatic/types 2.12.0 → 2.13.0-beta.1

package/README.md

@@ -24,7 +24,7 @@ import type {
   Deployment, DeploymentListResponse, DeploymentDeleteResponse, DeploymentSetOptions,
   Domain, DomainSetResult, DomainSetOptions, DomainListResponse, DnsRecord, DnsLookup, DomainDnsResponse, DomainRecordsResponse, DomainShareResponse, DomainValidateResponse, DomainDeleteResponse, DomainVerifyResponse,
   Token, TokenListResponse, TokenCreateResponse, TokenCreateOptions, TokenDeleteResponse,
-  Account, AccountUsage, AccountOverrides, AccountDeleteResponse, AccountKeyResponse,
+  Account, Caps, AccountDeleteResponse, AccountKeyResponse,
   LabelsResponse, SetupInstructionsResponse,
   StaticFile
 } from '@shipstatic/types';
@@ -90,7 +90,7 @@ Both helpers accept an optional operation-name string for contextual messages (`
 import {
   DeploymentStatus,   // pending | success | failed | deleting
   DomainStatus,       // pending | partial | success | paused
-  AccountPlan,        // free | standard | sponsored | enterprise | suspended | terminating | terminated
+  AccountPlan,        // free | pro | scale | sponsored — tiers only; suspension and deletion are account facts
   FileValidationStatus, // pending | processing_error | excluded | validation_failed | ready
   AuthMethod,         // session | apiKey | token | agent | oauth | webhook | system
 } from '@shipstatic/types';
@@ -100,9 +100,9 @@ import {
 
 ```typescript
 import type {
-  PlatformLimits,        // plan-based caps from /limits (file size, file count, total size)
-  BillingStatus,
-  CheckoutSession,
+  PlatformLimits,        // per-request size limits from /limits (file size, file count, total size)
+  Plan, PlansResponse,   // the public plan menu from /plans
+  BillingInterval, StripeSession,
   ActivityListResponse,
   PingResponse,
 } from '@shipstatic/types';

package/dist/index.d.ts

@@ -510,48 +510,64 @@ export interface TokenDeleteResponse {
     readonly token: string;
 }
 /**
- * Account plan constants
+ * Every plan an account can hold — the platform's whole plan vocabulary, in
+ * one place, and nothing about what a plan is WORTH.
+ *
+ * A plan is a TIER and nothing else. Whether an account may act is a separate
+ * fact (`Account.suspended`; deletion ends the session outright), so an
+ * account keeps its tier through suspension and into deletion.
+ *
+ * - **Free** — `free`.
+ * - **Billed** — `pro`. The one plan a customer can buy; the only plan Stripe
+ *   knows about, and the only one the platform never sets by hand — it is
+ *   derived from the Stripe subscription.
+ * - **Granted** — `scale`, `sponsored`. Paid plans the operator confers by
+ *   hand; no Stripe subscription, no Checkout, no Stripe object at all.
+ *
+ * The numbers each plan confers — caps, sizes — are POLICY and are delivered
+ * by the API (`GET /plans`, `GET /account`, `GET /limits`), never published
+ * here: a price or a cap in a published package is pinned to whatever version
+ * a client installed (`CLAUDE.md`, "Validation: format vs policy").
  */
 export declare const AccountPlan: {
     readonly FREE: "free";
-    readonly STANDARD: "standard";
+    readonly PRO: "pro";
+    readonly SCALE: "scale";
     readonly SPONSORED: "sponsored";
-    readonly ENTERPRISE: "enterprise";
-    readonly SUSPENDED: "suspended";
-    readonly TERMINATING: "terminating";
-    readonly TERMINATED: "terminated";
 };
 export type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
- * Account usage metrics — always available regardless of billing provider.
+ * The two things an account ACCUMULATES, and therefore the two things a plan
+ * caps. One word for the count and for the ceiling: `Account.usage` and
+ * `Account.caps` are the same shape, so a surface renders "2 of 3" by
+ * dividing one by the other and can never divide by a different denominator
+ * than the 403 uses.
+ *
+ * Both are counts paid plans SELL. A platform subdomain (`x.shipstatic.com`)
+ * is not among them: the platform owns the name, it costs nothing, and no
+ * plan bounds how many an account may hold.
  *
- * This is where a caller's own totals live. Lists answer pages and carry no
- * `total` (see {@link ListOptions}); a count is an aggregate over a
- * collection, so it belongs to the summary resource that owns the
- * collection. `GET /account` is that resource for one caller, `GET
- * /admin/stats` for the platform.
+ * Every cap carries a number on every plan — never `null`, never
+ * "unlimited" — so no consumer needs an "is it bounded?" branch.
  *
- * The counted dimensions are the ones the plan caps — deployments and
- * domains (`PlatformLimits`) — plus the billable custom-domain subset, so a
- * surface can render "3 of 10" without a second request.
+ * A count is an aggregate over a collection, so it lives on the summary
+ * resource that owns the collection: `GET /account` for one caller, `GET
+ * /admin/stats` platform-wide. Lists answer pages and carry no `total` (see
+ * {@link ListOptions}).
  */
-export interface AccountUsage {
-    /** Number of active custom domains (excludes paused) */
-    customDomains: number;
+export interface Caps {
     /**
-     * Deployments counted against the plan's deployment cap — every row
-     * whatever its status, because that is what the cap counts, so a surface
-     * renders "3 of 10" against the denominator the 403 divides by. (`GET
-     * /deployments` lists successful ones only; that is a different question
-     * asked of a different resource.) Optional by the additive-evolution law:
-     * an API predating this field omits it.
+     * Deployments — every row whatever its status, because that is what the cap
+     * counts. (`GET /deployments` lists successful ones only; that is a
+     * different question asked of a different resource.)
      */
-    deployments?: number;
+    readonly deployments: number;
     /**
-     * Domains counted against the plan's domain cap — every domain, platform
-     * and custom alike, unlike `customDomains`. Optional for the same reason.
+     * Hostnames the customer owns — every row, paused ones included. A paused
+     * domain still occupies its slot, so deleting one is what frees capacity.
+     * A downgraded account therefore reads honestly as "3 of 0".
      */
-    domains?: number;
+    readonly customDomains: number;
 }
 /**
  * Core account object - used in both API responses and SDK
@@ -564,10 +580,22 @@ export interface Account {
     readonly name: string | null;
     /** User profile picture URL, null if not set */
     readonly picture: string | null;
-    /** Account plan status */
+    /** The account's tier. */
     readonly plan: AccountPlanType;
-    /** Account usage metrics (custom domains, etc.) */
-    readonly usage: AccountUsage;
+    /**
+     * True while the operator has suspended the account: reads and deletes
+     * still work, every write is refused. The plan is unchanged underneath.
+     */
+    readonly suspended: boolean;
+    /** What the account currently holds — see {@link Caps}. */
+    readonly usage: Caps;
+    /**
+     * What the account is allowed to hold — the same three keys as
+     * {@link usage}, so the pair divides. These are the account's EFFECTIVE
+     * caps: its plan's numbers, plus whatever the operator granted it
+     * individually.
+     */
+    readonly caps: Caps;
     /** Unix timestamp (seconds) when account was created */
     readonly created: number;
     /** Unix timestamp (seconds) when account was activated (first deployment), null if not yet activated */
@@ -581,8 +609,16 @@ export interface Account {
      * when present rather than forcing a lockstep SDK release.
      */
     readonly used?: number | null;
-    /** Grace period expiration (unix seconds), null if no grace period active */
-    readonly grace: number | null;
+    /**
+     * True while the Stripe subscription's status is `past_due` and Stripe is
+     * still retrying the card. The plan is unchanged — the account keeps
+     * everything it has — so this is a banner, not a gate.
+     *
+     * A BOOLEAN rather than the status string: one fact for the console to
+     * act on. Stripe's own status word is mirrored on the account row for the
+     * operator surface.
+     */
+    readonly overdue: boolean;
 }
 /**
  * Account as returned by `GET /account` — the entity plus how the request
@@ -606,10 +642,10 @@ export interface AccountGetResponse extends Account {
  * {@link DeploymentDeleteResponse} for the law.
  */
 export interface AccountDeleteResponse {
-    /** The account that was marked for termination */
+    /** The account whose deletion was accepted */
     readonly account: string;
-    /** The plan the account is in while cleanup runs */
-    readonly plan: AccountPlanType;
+    /** Unix timestamp (seconds) the deletion was requested; cleanup completes it */
+    readonly deleted: number;
 }
 /**
  * Response from `PUT /account/key` — the account's single API key, minted in
@@ -627,22 +663,6 @@ export interface AccountKeyResponse {
     /** The raw API key (shown once at mint, then never again) */
     readonly secret: string;
 }
-/**
- * Account-specific configuration overrides
- * Allows per-account customization of limits without changing plan
- */
-export interface AccountOverrides {
-    /** Override for maximum number of domains */
-    domains?: number;
-    /** Override for maximum number of deployments */
-    deployments?: number;
-    /** Override for maximum individual file size in bytes */
-    fileSize?: number;
-    /** Override for maximum number of files per deployment */
-    filesCount?: number;
-    /** Override for maximum total deployment size in bytes */
-    totalSize?: number;
-}
 /**
  * Every path the public API answers on, declared once.
  *
@@ -694,6 +714,7 @@ export declare const API_PATHS: {
     readonly ACTIVITIES: "/activities";
     readonly LABELS: "/labels";
     readonly LIMITS: "/limits";
+    readonly PLANS: "/plans";
     readonly PING: "/ping";
     readonly SETUP: "/setup";
     readonly SPA_CHECK: "/spa-check";
@@ -1726,54 +1747,85 @@ export interface TokenResource {
     delete: (token: string) => Promise<TokenDeleteResponse>;
 }
 /**
- * Billing status response from GET /billing/status
+ * How often a subscription renews. The platform sells one plan at two
+ * intervals, so this is the only thing a buyer chooses at checkout.
  *
- * Note: The user's `plan` comes from Account, not here.
- * This endpoint only returns billing-specific data (usage, portal, etc.)
+ * It never branches business logic — monthly and yearly confer identical
+ * caps. It exists to be displayed and to pick a price at checkout.
+ */
+export type BillingInterval = 'month' | 'year';
+/**
+ * One row of the plan menu, answered by `GET /plans`.
  *
- * If `billing` is null, the user has no active billing.
+ * **Vocabulary here, values from the server.** The shape is a wire contract
+ * every surface agrees on; the numbers in it are policy the API owns and may
+ * change on a deploy (`CLAUDE.md`, "Validation: format vs policy"). That is
+ * why the public site and the console both READ this endpoint instead of
+ * carrying their own copy of the price list — a hand-copied plan table was
+ * the platform's longest-lived restatement.
  */
-export interface BillingStatus {
-    /** Creem billing ID, or null if no active billing */
-    billing: string | null;
-    /** Number of billing units (1 unit = 1 custom domain), null if no billing */
-    units: number | null;
-    /** Billing status from Creem (active, trialing, canceled, etc.), null if no billing */
-    status: string | null;
-    /** Link to Creem customer portal for billing management, null if unavailable */
-    portal: string | null;
+export interface Plan {
+    /** Which plan this row describes. */
+    readonly plan: AccountPlanType;
+    /** Display name, as the marketing site and the console should print it. */
+    readonly name: string;
+    /**
+     * What it costs. A union rather than a nullable number, so "free" and
+     * "talk to us" are two different answers instead of two readings of the
+     * same `null`. Amounts are integer CENTS in USD, as the API's plan table
+     * states them and as Stripe's Prices are provisioned from it — the wire
+     * never carries a formatted price, because formatting is the reader's job.
+     */
+    readonly price: 'free' | 'contact' | {
+        readonly month: number;
+        readonly year: number;
+    };
+    /**
+     * The caps this plan publishes, or `null` where the menu deliberately says
+     * nothing (a plan sold by conversation publishes no numbers).
+     */
+    readonly caps: Caps | null;
 }
 /**
- * Acknowledgement of `POST /billing/cancel`.
+ * Response for `GET /plans` — the whole public menu, in display order.
  *
- * Cancelling leaves no billing entity to return, so it answers with the
- * account and the one field of the account the call changed — the plan it
- * landed on. See {@link DeploymentDeleteResponse} for the law.
+ * Public, unauthenticated and cacheable: it describes the product, not the
+ * caller. Plans the operator only ever grants by hand are absent — a menu
+ * lists what can be ordered.
  *
- * This read `{ success: true, message: 'Subscription canceled successfully…' }`
- * until 2026-07-29, an anonymous shape that `web/my` redeclared inline and
- * whose prose no surface ever displayed: both callers await the promise and
- * discard the body, then compose their own toast. The message was written,
- * serialized, and thrown away on every cancellation.
+ * An aggregate rather than a list: the registry is the bound, so there is no
+ * cursor (the {@link LabelsResponse} shape).
  */
-export interface BillingCancelResponse {
-    /** The account whose subscription was cancelled */
-    readonly account: string;
-    /** The plan the account now holds — `free` on a successful cancellation */
-    readonly plan: AccountPlanType;
+export interface PlansResponse {
+    readonly plans: readonly Plan[];
 }
 /**
- * Checkout session response from POST /billing/checkout
+ * A page Stripe hosts — a Checkout Session or a Customer Portal session — the
+ * answer of `POST /billing/checkout` and `POST /billing/portal` alike.
+ *
+ * One shape for both because both say the same thing: the platform is not
+ * where this happens, go here. There is nothing else to return — the
+ * outcome arrives later, as a Stripe webhook.
  */
-export interface CheckoutSession {
-    /** URL to redirect user to Creem checkout page */
-    url: string;
+export interface StripeSession {
+    /** Absolute URL to redirect the browser to. Single use, short-lived. */
+    readonly url: string;
+}
+/**
+ * The answer of `POST /billing/sync` — the account's plan after the platform
+ * re-read Stripe. The success page calls it once on arrival from Checkout,
+ * instead of polling for the webhook: a card payment is settled by the time
+ * Stripe redirects, so one read makes the plan current before anything
+ * renders.
+ */
+export interface BillingSyncResponse {
+    readonly plan: AccountPlanType;
 }
 /**
  * All activity event types logged in the system.
  * Uses dot notation consistently: {resource}.{action}
  */
-export type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'account.suspended' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'deployment.open' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete' | 'admin.account.plan.update' | 'admin.account.ref.update' | 'admin.account.billing.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.billing.sync' | 'admin.billing.terminated' | 'admin.impersonate' | 'billing.active' | 'billing.canceled' | 'billing.paused' | 'billing.expired' | 'billing.paid' | 'billing.trialing' | 'billing.scheduled_cancel' | 'billing.unpaid' | 'billing.update' | 'billing.past_due' | 'refund.created' | 'dispute.created' | 'billing.sync' | 'billing.stale' | 'billing.race';
+export type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'deployment.open' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete' | 'admin.account.plan.update' | 'admin.account.suspended.update' | 'admin.account.ref.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.impersonate';
 /**
  * Activity events visible to users in the dashboard
  */

package/dist/index.js

@@ -169,16 +169,30 @@ export function validateIdempotencyKey(value) {
 // ACCOUNT TYPES
 // =============================================================================
 /**
- * Account plan constants
+ * Every plan an account can hold — the platform's whole plan vocabulary, in
+ * one place, and nothing about what a plan is WORTH.
+ *
+ * A plan is a TIER and nothing else. Whether an account may act is a separate
+ * fact (`Account.suspended`; deletion ends the session outright), so an
+ * account keeps its tier through suspension and into deletion.
+ *
+ * - **Free** — `free`.
+ * - **Billed** — `pro`. The one plan a customer can buy; the only plan Stripe
+ *   knows about, and the only one the platform never sets by hand — it is
+ *   derived from the Stripe subscription.
+ * - **Granted** — `scale`, `sponsored`. Paid plans the operator confers by
+ *   hand; no Stripe subscription, no Checkout, no Stripe object at all.
+ *
+ * The numbers each plan confers — caps, sizes — are POLICY and are delivered
+ * by the API (`GET /plans`, `GET /account`, `GET /limits`), never published
+ * here: a price or a cap in a published package is pinned to whatever version
+ * a client installed (`CLAUDE.md`, "Validation: format vs policy").
  */
 export const AccountPlan = {
     FREE: 'free',
-    STANDARD: 'standard',
+    PRO: 'pro',
+    SCALE: 'scale',
     SPONSORED: 'sponsored',
-    ENTERPRISE: 'enterprise',
-    SUSPENDED: 'suspended',
-    TERMINATING: 'terminating',
-    TERMINATED: 'terminated',
 };
 // =============================================================================
 // WIRE SURFACE
@@ -234,6 +248,7 @@ export const API_PATHS = {
     ACTIVITIES: '/activities',
     LABELS: '/labels',
     LIMITS: '/limits',
+    PLANS: '/plans',
     PING: '/ping',
     SETUP: '/setup',
     SPA_CHECK: '/spa-check',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.12.0",
+  "version": "2.13.0-beta.1",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -582,50 +582,66 @@ export interface TokenDeleteResponse {
 // =============================================================================
 
 /**
- * Account plan constants
+ * Every plan an account can hold — the platform's whole plan vocabulary, in
+ * one place, and nothing about what a plan is WORTH.
+ *
+ * A plan is a TIER and nothing else. Whether an account may act is a separate
+ * fact (`Account.suspended`; deletion ends the session outright), so an
+ * account keeps its tier through suspension and into deletion.
+ *
+ * - **Free** — `free`.
+ * - **Billed** — `pro`. The one plan a customer can buy; the only plan Stripe
+ *   knows about, and the only one the platform never sets by hand — it is
+ *   derived from the Stripe subscription.
+ * - **Granted** — `scale`, `sponsored`. Paid plans the operator confers by
+ *   hand; no Stripe subscription, no Checkout, no Stripe object at all.
+ *
+ * The numbers each plan confers — caps, sizes — are POLICY and are delivered
+ * by the API (`GET /plans`, `GET /account`, `GET /limits`), never published
+ * here: a price or a cap in a published package is pinned to whatever version
+ * a client installed (`CLAUDE.md`, "Validation: format vs policy").
  */
 export const AccountPlan = {
   FREE: 'free',
-  STANDARD: 'standard',
+  PRO: 'pro',
+  SCALE: 'scale',
   SPONSORED: 'sponsored',
-  ENTERPRISE: 'enterprise',
-  SUSPENDED: 'suspended',
-  TERMINATING: 'terminating',
-  TERMINATED: 'terminated',
 } as const;
 
 export type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 
 /**
- * Account usage metrics — always available regardless of billing provider.
+ * The two things an account ACCUMULATES, and therefore the two things a plan
+ * caps. One word for the count and for the ceiling: `Account.usage` and
+ * `Account.caps` are the same shape, so a surface renders "2 of 3" by
+ * dividing one by the other and can never divide by a different denominator
+ * than the 403 uses.
  *
- * This is where a caller's own totals live. Lists answer pages and carry no
- * `total` (see {@link ListOptions}); a count is an aggregate over a
- * collection, so it belongs to the summary resource that owns the
- * collection. `GET /account` is that resource for one caller, `GET
- * /admin/stats` for the platform.
+ * Both are counts paid plans SELL. A platform subdomain (`x.shipstatic.com`)
+ * is not among them: the platform owns the name, it costs nothing, and no
+ * plan bounds how many an account may hold.
  *
- * The counted dimensions are the ones the plan caps — deployments and
- * domains (`PlatformLimits`) — plus the billable custom-domain subset, so a
- * surface can render "3 of 10" without a second request.
+ * Every cap carries a number on every plan — never `null`, never
+ * "unlimited" — so no consumer needs an "is it bounded?" branch.
+ *
+ * A count is an aggregate over a collection, so it lives on the summary
+ * resource that owns the collection: `GET /account` for one caller, `GET
+ * /admin/stats` platform-wide. Lists answer pages and carry no `total` (see
+ * {@link ListOptions}).
  */
-export interface AccountUsage {
-  /** Number of active custom domains (excludes paused) */
-  customDomains: number;
+export interface Caps {
   /**
-   * Deployments counted against the plan's deployment cap — every row
-   * whatever its status, because that is what the cap counts, so a surface
-   * renders "3 of 10" against the denominator the 403 divides by. (`GET
-   * /deployments` lists successful ones only; that is a different question
-   * asked of a different resource.) Optional by the additive-evolution law:
-   * an API predating this field omits it.
+   * Deployments — every row whatever its status, because that is what the cap
+   * counts. (`GET /deployments` lists successful ones only; that is a
+   * different question asked of a different resource.)
    */
-  deployments?: number;
+  readonly deployments: number;
   /**
-   * Domains counted against the plan's domain cap — every domain, platform
-   * and custom alike, unlike `customDomains`. Optional for the same reason.
+   * Hostnames the customer owns — every row, paused ones included. A paused
+   * domain still occupies its slot, so deleting one is what frees capacity.
+   * A downgraded account therefore reads honestly as "3 of 0".
    */
-  domains?: number;
+  readonly customDomains: number;
 }
 
 /**
@@ -639,10 +655,22 @@ export interface Account {
   readonly name: string | null;
   /** User profile picture URL, null if not set */
   readonly picture: string | null;
-  /** Account plan status */
+  /** The account's tier. */
   readonly plan: AccountPlanType;
-  /** Account usage metrics (custom domains, etc.) */
-  readonly usage: AccountUsage;
+  /**
+   * True while the operator has suspended the account: reads and deletes
+   * still work, every write is refused. The plan is unchanged underneath.
+   */
+  readonly suspended: boolean;
+  /** What the account currently holds — see {@link Caps}. */
+  readonly usage: Caps;
+  /**
+   * What the account is allowed to hold — the same three keys as
+   * {@link usage}, so the pair divides. These are the account's EFFECTIVE
+   * caps: its plan's numbers, plus whatever the operator granted it
+   * individually.
+   */
+  readonly caps: Caps;
   /** Unix timestamp (seconds) when account was created */
   readonly created: number;
   /** Unix timestamp (seconds) when account was activated (first deployment), null if not yet activated */
@@ -656,8 +684,16 @@ export interface Account {
    * when present rather than forcing a lockstep SDK release.
    */
   readonly used?: number | null;
-  /** Grace period expiration (unix seconds), null if no grace period active */
-  readonly grace: number | null;
+  /**
+   * True while the Stripe subscription's status is `past_due` and Stripe is
+   * still retrying the card. The plan is unchanged — the account keeps
+   * everything it has — so this is a banner, not a gate.
+   *
+   * A BOOLEAN rather than the status string: one fact for the console to
+   * act on. Stripe's own status word is mirrored on the account row for the
+   * operator surface.
+   */
+  readonly overdue: boolean;
 }
 
 /**
@@ -683,10 +719,10 @@ export interface AccountGetResponse extends Account {
  * {@link DeploymentDeleteResponse} for the law.
  */
 export interface AccountDeleteResponse {
-  /** The account that was marked for termination */
+  /** The account whose deletion was accepted */
   readonly account: string;
-  /** The plan the account is in while cleanup runs */
-  readonly plan: AccountPlanType;
+  /** Unix timestamp (seconds) the deletion was requested; cleanup completes it */
+  readonly deleted: number;
 }
 
 /**
@@ -706,23 +742,6 @@ export interface AccountKeyResponse {
   readonly secret: string;
 }
 
-/**
- * Account-specific configuration overrides
- * Allows per-account customization of limits without changing plan
- */
-export interface AccountOverrides {
-  /** Override for maximum number of domains */
-  domains?: number;
-  /** Override for maximum number of deployments */
-  deployments?: number;
-  /** Override for maximum individual file size in bytes */
-  fileSize?: number;
-  /** Override for maximum number of files per deployment */
-  filesCount?: number;
-  /** Override for maximum total deployment size in bytes */
-  totalSize?: number;
-}
-
 // =============================================================================
 // WIRE SURFACE
 // =============================================================================
@@ -778,6 +797,7 @@ export const API_PATHS = {
   ACTIVITIES: '/activities',
   LABELS: '/labels',
   LIMITS: '/limits',
+  PLANS: '/plans',
   PING: '/ping',
   SETUP: '/setup',
   SPA_CHECK: '/spa-check',
@@ -2590,50 +2610,80 @@ export interface TokenResource {
 // =============================================================================
 
 /**
- * Billing status response from GET /billing/status
+ * How often a subscription renews. The platform sells one plan at two
+ * intervals, so this is the only thing a buyer chooses at checkout.
  *
- * Note: The user's `plan` comes from Account, not here.
- * This endpoint only returns billing-specific data (usage, portal, etc.)
+ * It never branches business logic — monthly and yearly confer identical
+ * caps. It exists to be displayed and to pick a price at checkout.
+ */
+export type BillingInterval = 'month' | 'year';
+
+/**
+ * One row of the plan menu, answered by `GET /plans`.
  *
- * If `billing` is null, the user has no active billing.
+ * **Vocabulary here, values from the server.** The shape is a wire contract
+ * every surface agrees on; the numbers in it are policy the API owns and may
+ * change on a deploy (`CLAUDE.md`, "Validation: format vs policy"). That is
+ * why the public site and the console both READ this endpoint instead of
+ * carrying their own copy of the price list — a hand-copied plan table was
+ * the platform's longest-lived restatement.
  */
-export interface BillingStatus {
-  /** Creem billing ID, or null if no active billing */
-  billing: string | null;
-  /** Number of billing units (1 unit = 1 custom domain), null if no billing */
-  units: number | null;
-  /** Billing status from Creem (active, trialing, canceled, etc.), null if no billing */
-  status: string | null;
-  /** Link to Creem customer portal for billing management, null if unavailable */
-  portal: string | null;
+export interface Plan {
+  /** Which plan this row describes. */
+  readonly plan: AccountPlanType;
+  /** Display name, as the marketing site and the console should print it. */
+  readonly name: string;
+  /**
+   * What it costs. A union rather than a nullable number, so "free" and
+   * "talk to us" are two different answers instead of two readings of the
+   * same `null`. Amounts are integer CENTS in USD, as the API's plan table
+   * states them and as Stripe's Prices are provisioned from it — the wire
+   * never carries a formatted price, because formatting is the reader's job.
+   */
+  readonly price: 'free' | 'contact' | { readonly month: number; readonly year: number };
+  /**
+   * The caps this plan publishes, or `null` where the menu deliberately says
+   * nothing (a plan sold by conversation publishes no numbers).
+   */
+  readonly caps: Caps | null;
 }
 
 /**
- * Acknowledgement of `POST /billing/cancel`.
+ * Response for `GET /plans` — the whole public menu, in display order.
  *
- * Cancelling leaves no billing entity to return, so it answers with the
- * account and the one field of the account the call changed — the plan it
- * landed on. See {@link DeploymentDeleteResponse} for the law.
+ * Public, unauthenticated and cacheable: it describes the product, not the
+ * caller. Plans the operator only ever grants by hand are absent — a menu
+ * lists what can be ordered.
  *
- * This read `{ success: true, message: 'Subscription canceled successfully…' }`
- * until 2026-07-29, an anonymous shape that `web/my` redeclared inline and
- * whose prose no surface ever displayed: both callers await the promise and
- * discard the body, then compose their own toast. The message was written,
- * serialized, and thrown away on every cancellation.
+ * An aggregate rather than a list: the registry is the bound, so there is no
+ * cursor (the {@link LabelsResponse} shape).
  */
-export interface BillingCancelResponse {
-  /** The account whose subscription was cancelled */
-  readonly account: string;
-  /** The plan the account now holds — `free` on a successful cancellation */
-  readonly plan: AccountPlanType;
+export interface PlansResponse {
+  readonly plans: readonly Plan[];
 }
 
 /**
- * Checkout session response from POST /billing/checkout
+ * A page Stripe hosts — a Checkout Session or a Customer Portal session — the
+ * answer of `POST /billing/checkout` and `POST /billing/portal` alike.
+ *
+ * One shape for both because both say the same thing: the platform is not
+ * where this happens, go here. There is nothing else to return — the
+ * outcome arrives later, as a Stripe webhook.
+ */
+export interface StripeSession {
+  /** Absolute URL to redirect the browser to. Single use, short-lived. */
+  readonly url: string;
+}
+
+/**
+ * The answer of `POST /billing/sync` — the account's plan after the platform
+ * re-read Stripe. The success page calls it once on arrival from Checkout,
+ * instead of polling for the webhook: a card payment is settled by the time
+ * Stripe redirects, so one read makes the plan current before anything
+ * renders.
  */
-export interface CheckoutSession {
-  /** URL to redirect user to Creem checkout page */
-  url: string;
+export interface BillingSyncResponse {
+  readonly plan: AccountPlanType;
 }
 
 // =============================================================================
@@ -2652,7 +2702,6 @@ export type ActivityEvent =
   | 'account.key.generate'
   | 'account.plan.paid'
   | 'account.plan.transition'
-  | 'account.suspended'
   // Deployment events
   | 'deployment.create'
   | 'deployment.update'
@@ -2671,31 +2720,17 @@ export type ActivityEvent =
   | 'token.delete'
   // Admin events (not user-visible)
   | 'admin.account.plan.update'
+  | 'admin.account.suspended.update'
   | 'admin.account.ref.update'
-  | 'admin.account.billing.update'
   | 'admin.account.labels.update'
   | 'admin.deployment.delete'
   | 'admin.domain.delete'
-  | 'admin.billing.sync'
-  | 'admin.billing.terminated'
-  | 'admin.impersonate'
-  // Webhook events (logged directly from payment provider)
-  | 'billing.active'
-  | 'billing.canceled'
-  | 'billing.paused'
-  | 'billing.expired'
-  | 'billing.paid'
-  | 'billing.trialing'
-  | 'billing.scheduled_cancel'
-  | 'billing.unpaid'
-  | 'billing.update'
-  | 'billing.past_due'
-  | 'refund.created'
-  | 'dispute.created'
-  // Billing operational events (admin/debug only, not user-visible)
-  | 'billing.sync' // Outbound: unit count pushed to payment provider
-  | 'billing.stale' // Dropped: webhook predates last known state
-  | 'billing.race'; // Dropped: concurrent webhook already updated state
+  | 'admin.impersonate';
+
+// A subscription's own history is not logged here. What a plan change MEANS
+// is recorded once, as `account.plan.transition`; everything behind it
+// (invoices, refunds, disputes, retries) belongs to Stripe, which owns the
+// record and shows it to the customer in the Customer Portal.
 
 /**
  * Activity events visible to users in the dashboard