@shipstatic/ship 2.5.0-beta.1 → 2.6.0-beta.10

package/dist/index.d.cts

@@ -518,11 +518,15 @@ interface TokenDeleteResponse {
  * 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.
+ * - **Billed** — `pro`, `team`. The plans a customer buys; the only plans
+ *   Stripe knows about, and the only ones the platform never sets by hand —
+ *   each is derived from the Stripe Subscription, which names its plan on the
+ *   Price it is on. They form a ladder: a dearer tier is a superset of the one
+ *   below it, and the API says which is next in {@link Account.upgrade}.
  * - **Granted** — `scale`, `sponsored`. Paid plans the operator confers by
- *   hand; no Stripe subscription, no Checkout, no Stripe object at all.
+ *   hand; no Stripe subscription, no Checkout, no Stripe object at all. These
+ *   and `free` are the only plans an operator can set; a billed plan is only
+ *   ever Stripe's to confer.
  *
  * The numbers each plan confers — caps, sizes — are POLICY and are delivered
  * by the API (`GET /plans`, `GET /account`, `GET /limits`), never published
@@ -532,23 +536,31 @@ interface TokenDeleteResponse {
 declare const AccountPlan: {
     readonly FREE: "free";
     readonly PRO: "pro";
+    readonly TEAM: "team";
     readonly SCALE: "scale";
     readonly SPONSORED: "sponsored";
 };
 type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
- * 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
+ * The three things an account ACCUMULATES, and therefore the three 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.
+ * All three are counts plans SELL, and every plan publishes a number for each.
+ * A platform subdomain (`my-app.shipstatic.com`) is among them: the namespace
+ * is the platform's, so every plan bounds how many names one account may take
+ * from it — which is not the address every deployment gets by construction
+ * (`happy-cat-abc1234.shipstatic.com`), one per deployment and bounded by
+ * `deployments` already.
  *
  * Every cap carries a number on every plan — never `null`, never
- * "unlimited" — so no consumer needs an "is it bounded?" branch.
+ * "unlimited" — so no consumer needs an "is it bounded?" branch. A cap of `0`
+ * means the plan does not have the feature at all; a cap of `N` bounds
+ * creation, and what an account already holds above a cap stays until a plan
+ * TRANSITION fits it (excess paused, newest first — a domain is the only kind
+ * that pauses).
  *
  * 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
@@ -562,6 +574,12 @@ interface Caps {
      * different question asked of a different resource.)
      */
     readonly deployments: number;
+    /**
+     * Names the customer chose under the platform's own suffix
+     * (`my-app.shipstatic.com`) — every row, paused ones included, by the same
+     * rule as custom domains.
+     */
+    readonly platformDomains: number;
     /**
      * Hostnames the customer owns — every row, paused ones included. A paused
      * domain still occupies its slot, so deleting one is what frees capacity.
@@ -620,6 +638,47 @@ interface Account {
      * mirrored on the account row for the operator surface.
      */
     readonly pastDue: boolean;
+    /**
+     * Does Stripe bill this plan — is there a Subscription behind it? True for
+     * every billed tier, including one no longer on the menu (a grandfathered
+     * row keeps its subscribers), so a console cannot derive it from `/plans`.
+     * It is what sends the account to the Customer Portal rather than to
+     * Checkout, and what a granted plan (`scale`, `sponsored`) never is.
+     */
+    readonly billed: boolean;
+    /**
+     * The next plan up the ladder this account could move to, or `null` when
+     * there is none: the top billed tier, every granted plan, and any plan not
+     * on the menu answer `null`. One server-side fact so that no surface
+     * derives "can this account upgrade, and to what" from the menu — a
+     * grandfathered row has no menu price to compare, and a granted account
+     * must never be sent to Checkout.
+     */
+    readonly upgrade: AccountPlanType | null;
+    /**
+     * The live Subscription's billing interval — Stripe's
+     * `Price.recurring.interval`, mirrored — or `null` when no Subscription
+     * bills the account (free and granted plans). It is what lets the console
+     * offer the current plan's OTHER interval as a switch.
+     */
+    readonly interval: BillingInterval | null;
+    /**
+     * The pending plan change, or `null`. *Up is now, down is at period end*:
+     * a downgrade is a Stripe Subscription Schedule that applies at `at`, and
+     * until then the account keeps everything it paid for. Reversible —
+     * `DELETE /billing/change` releases it.
+     */
+    readonly scheduled: ScheduledChange | null;
+    /**
+     * When the Subscription is set to END — Stripe's `cancel_at`, mirrored
+     * (Unix seconds) — or `null` while it renews. Set by a cancellation in the
+     * Customer Portal; the Portal is also where it is resumed. The console
+     * needs it to ACT: no "cancel" offered to an account already cancelling,
+     * and no plan change offered until it is resumed (the API refuses one).
+     * Mirrored on the rule that survives: what the console must act on is
+     * mirrored, what it would merely display is not.
+     */
+    readonly cancelAt: number | null;
 }
 /**
  * Account as returned by `GET /account` — the entity plus how the request
@@ -1164,8 +1223,10 @@ declare const SIGN_IN_RETURN_PARAM = "signing-in";
  * Client populations: `SESSION` (first-party cookie), `API_KEY` (`ship-`
  * key), `TOKEN` (`deploy-` deploy token), `AGENT` (anonymous public deploy —
  * no credential; the platform grants the public-account identity per
- * request), `OAUTH` (delegated access token). Server populations: `WEBHOOK`
- * (signed webhook processing), `SYSTEM` (scheduled/background jobs).
+ * request), `OAUTH` (delegated access token). The one server population:
+ * `SYSTEM` (scheduled/background jobs). Webhook receipt is deliberately not
+ * a population: a signed delivery is verified, never authorized — it acts
+ * as no one and audits as no one.
  */
 declare const AuthMethod: {
     readonly SESSION: "session";
@@ -1173,7 +1234,6 @@ declare const AuthMethod: {
     readonly TOKEN: "token";
     readonly AGENT: "agent";
     readonly OAUTH: "oauth";
-    readonly WEBHOOK: "webhook";
     readonly SYSTEM: "system";
 };
 type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
@@ -1748,11 +1808,11 @@ interface TokenResource {
     delete: (token: string) => Promise<TokenDeleteResponse>;
 }
 /**
- * How often a subscription renews. The platform sells one plan at two
- * intervals, so this is the only thing a buyer chooses at checkout.
+ * How often a subscription renews. Every billed plan is sold at both
+ * intervals, so a buyer chooses a plan and an interval, and nothing else.
  *
  * It never branches business logic — monthly and yearly confer identical
- * caps. It exists to be displayed and to pick a price at checkout.
+ * caps. It exists to be displayed and to pick a Price at checkout.
  */
 type BillingInterval = 'month' | 'year';
 /**
@@ -1771,13 +1831,20 @@ interface Plan {
     /** 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.
+     * What it costs, per interval — 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: formatting is the reader's job.
+     *
+     * **A free plan costs `{ month: 0, year: 0 }`, not a sentinel.** Free IS
+     * zero, so it is a number like any other and every reader formats it with
+     * the same call; a `'free'` member bought one thing — a branch in each
+     * consumer that mapped it straight back to `$0`.
+     *
+     * `'contact'` stays, and the asymmetry is the point: "not sold at a list
+     * price" is genuinely a different KIND of answer, not a different number, so
+     * it is a different shape. Two shapes, and each earns its own.
      */
-    readonly price: 'free' | 'contact' | {
+    readonly price: 'contact' | {
         readonly month: number;
         readonly year: number;
     };
@@ -1786,6 +1853,20 @@ interface Plan {
      * nothing (a plan sold by conversation publishes no numbers).
      */
     readonly caps: Caps | null;
+    /**
+     * Why this row cannot be ordered right now — the closed door's own sentence,
+     * verbatim — or absent when the way is open. A menu lists what can be
+     * ordered, and a row that is sold but not yet orderable (its door is closed:
+     * checkout unbuilt, a feature unfinished) SAYS SO on the menu instead of
+     * only at the order.
+     *
+     * Clients branch on PRESENCE and render the sentence unchanged — they know
+     * *that* the row is closed, never *which* door or *when it lifts*; the
+     * vocabulary of doors stays server-side. The same rule the refusal follows:
+     * `POST /billing/change` onto a closed row answers 400 with
+     * `details.closed`, and its `message` is this sentence.
+     */
+    readonly closed?: string;
 }
 /**
  * Response for `GET /plans` — the whole public menu, in display order.
@@ -1801,23 +1882,59 @@ interface PlansResponse {
     readonly plans: readonly Plan[];
 }
 /**
- * The answer of `POST /billing/checkout` — Stripe's `Checkout.Session`,
- * projected to the one field a client needs.
+ * The body of `POST /billing/change` — the one door for "get me onto this
+ * plan". Both fields required: with more than one billed plan there is no
+ * honest default, and the console always knows which card was clicked.
  *
- * There is nothing else to return: the outcome arrives later, as a Stripe
- * webhook. It is its own type rather than a shape shared with
- * {@link BillingPortalSession} because Stripe has two distinct objects here,
- * and naming one of them for both would be the reader's translation to make.
+ * The SERVER decides what the change means — the rule is *up is now, down is
+ * at period end* — so the client holds no copy of the ladder: a free account
+ * is sent to Stripe Checkout, a billed account moving up is sent to the
+ * Portal's confirmation page (money moves now, so Stripe's page takes the
+ * consent), and a billed account moving down gets a Stripe Subscription
+ * Schedule that applies the change at period end. The answer says which
+ * happened ({@link PlanChangeResponse}).
  */
-interface CheckoutSession {
-    /** Absolute URL to redirect the browser to. Single use, short-lived. */
+interface PlanChangeRequest {
+    readonly plan: AccountPlanType;
+    readonly interval: BillingInterval;
+}
+/**
+ * The pending plan change — a Stripe Subscription Schedule the platform
+ * minted, mirrored onto the account. `at` is when it applies (the current
+ * period's end, Unix seconds). Reversible until then: `DELETE
+ * /billing/change` releases it.
+ */
+interface ScheduledChange {
+    readonly plan: AccountPlanType;
+    readonly interval: BillingInterval;
+    readonly at: number;
+}
+/**
+ * The answer of `POST /billing/change` — exactly one field is set, and the
+ * UNION is what holds that: an answer carrying both, or neither, does not
+ * compile, so "which door was taken" is structural rather than prose.
+ *
+ * `url` means GO: a Stripe page (Checkout, or the Portal's confirmation page)
+ * finishes the change and the browser must be redirected to it. `scheduled`
+ * means DONE: the downgrade is booked for period end, nothing to visit, and
+ * the account's `scheduled` field now carries it.
+ */
+type PlanChangeResponse = 
+/** GO: a Stripe page finishes the change. Absolute URL, single use, short-lived. */
+{
     readonly url: string;
+    readonly scheduled?: never;
 }
+/** DONE: the downgrade is booked for period end; nothing to visit. */
+ | {
+    readonly url?: never;
+    readonly scheduled: ScheduledChange;
+};
 /**
  * The answer of `POST /billing/portal` — Stripe's `BillingPortal.Session`,
- * projected the same way. Identical in shape to {@link CheckoutSession} and
- * deliberately not merged with it: they are two Stripe objects, and either may
- * gain a field the other never has.
+ * projected to the one field a client needs. The Portal home: cards,
+ * invoices, cancellation. Plan changes have their own door
+ * ({@link PlanChangeRequest}).
  */
 interface BillingPortalSession {
     /** Absolute URL to redirect the browser to. Single use, short-lived. */
@@ -1836,12 +1953,17 @@ interface BillingSyncResponse {
 /**
  * All activity event types logged in the system.
  * Uses dot notation consistently: {resource}.{action}
+ *
+ * Retention: activity rows are permanent — the account's own history and
+ * the platform's audit ledgers are one table, kept for the life of the
+ * account (deletion removes them). Only the personal payload is
+ * time-bounded: past 90 days each row sheds its IP.
  */
-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';
+type ActivityEvent = 'account.create' | 'account.delete' | 'account.key.generate' | '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
  */
-type UserVisibleActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete';
+type UserVisibleActivityEvent = 'account.create' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete';
 /**
  * Activity record returned from the API
  */
@@ -3020,6 +3142,6 @@ declare class Ship extends Ship$1 {
 }
 
 declare namespace Ship {
-  export { API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountDeleteResponse, AccountGetResponse, AccountKeyResponse, AccountPlan, AccountPlanType, AccountResource, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BillingInterval, BillingPortalSession, BillingSyncResponse, CALLER, Caps, CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, DeployBodyContext, DeployFile, DeployInput, DeployTransport, Deployment, DeploymentCreateResponse, DeploymentDeleteResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentSetOptions, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DeploymentVia, DeploymentViaType, DnsLookup, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDeleteResponse, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetOptions, DomainSetResult, DomainShareResponse, DomainStatus, DomainStatusType, DomainValidateResponse, DomainVerifyResponse, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, LabelsResponse, ListOptions, ListResponse, MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, PingResponse, Plan, PlansResponse, PlatformLimits, RequestResult, ResourceContext, SHIP_ENV, SIGN_IN_RETURN_PARAM, SPACheckDebug, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, ShipRequestInit, StaticFile, TTL_CONSTRAINTS, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validatePassword, validateToken, validateTtl };
+  export { API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountDeleteResponse, AccountGetResponse, AccountKeyResponse, AccountPlan, AccountPlanType, AccountResource, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BillingInterval, BillingPortalSession, BillingSyncResponse, CALLER, Caps, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, DeployBodyContext, DeployFile, DeployInput, DeployTransport, Deployment, DeploymentCreateResponse, DeploymentDeleteResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentSetOptions, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DeploymentVia, DeploymentViaType, DnsLookup, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDeleteResponse, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetOptions, DomainSetResult, DomainShareResponse, DomainStatus, DomainStatusType, DomainValidateResponse, DomainVerifyResponse, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, LabelsResponse, ListOptions, ListResponse, MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, PingResponse, Plan, PlanChangeRequest, PlanChangeResponse, PlansResponse, PlatformLimits, RequestResult, ResourceContext, SHIP_ENV, SIGN_IN_RETURN_PARAM, SPACheckDebug, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, ScheduledChange, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, ShipRequestInit, StaticFile, TTL_CONSTRAINTS, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validatePassword, validateToken, validateTtl };
 }
 export = Ship;

package/dist/index.d.ts

@@ -518,11 +518,15 @@ interface TokenDeleteResponse {
  * 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.
+ * - **Billed** — `pro`, `team`. The plans a customer buys; the only plans
+ *   Stripe knows about, and the only ones the platform never sets by hand —
+ *   each is derived from the Stripe Subscription, which names its plan on the
+ *   Price it is on. They form a ladder: a dearer tier is a superset of the one
+ *   below it, and the API says which is next in {@link Account.upgrade}.
  * - **Granted** — `scale`, `sponsored`. Paid plans the operator confers by
- *   hand; no Stripe subscription, no Checkout, no Stripe object at all.
+ *   hand; no Stripe subscription, no Checkout, no Stripe object at all. These
+ *   and `free` are the only plans an operator can set; a billed plan is only
+ *   ever Stripe's to confer.
  *
  * The numbers each plan confers — caps, sizes — are POLICY and are delivered
  * by the API (`GET /plans`, `GET /account`, `GET /limits`), never published
@@ -532,23 +536,31 @@ interface TokenDeleteResponse {
 declare const AccountPlan: {
     readonly FREE: "free";
     readonly PRO: "pro";
+    readonly TEAM: "team";
     readonly SCALE: "scale";
     readonly SPONSORED: "sponsored";
 };
 type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
- * 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
+ * The three things an account ACCUMULATES, and therefore the three 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.
+ * All three are counts plans SELL, and every plan publishes a number for each.
+ * A platform subdomain (`my-app.shipstatic.com`) is among them: the namespace
+ * is the platform's, so every plan bounds how many names one account may take
+ * from it — which is not the address every deployment gets by construction
+ * (`happy-cat-abc1234.shipstatic.com`), one per deployment and bounded by
+ * `deployments` already.
  *
  * Every cap carries a number on every plan — never `null`, never
- * "unlimited" — so no consumer needs an "is it bounded?" branch.
+ * "unlimited" — so no consumer needs an "is it bounded?" branch. A cap of `0`
+ * means the plan does not have the feature at all; a cap of `N` bounds
+ * creation, and what an account already holds above a cap stays until a plan
+ * TRANSITION fits it (excess paused, newest first — a domain is the only kind
+ * that pauses).
  *
  * 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
@@ -562,6 +574,12 @@ interface Caps {
      * different question asked of a different resource.)
      */
     readonly deployments: number;
+    /**
+     * Names the customer chose under the platform's own suffix
+     * (`my-app.shipstatic.com`) — every row, paused ones included, by the same
+     * rule as custom domains.
+     */
+    readonly platformDomains: number;
     /**
      * Hostnames the customer owns — every row, paused ones included. A paused
      * domain still occupies its slot, so deleting one is what frees capacity.
@@ -620,6 +638,47 @@ interface Account {
      * mirrored on the account row for the operator surface.
      */
     readonly pastDue: boolean;
+    /**
+     * Does Stripe bill this plan — is there a Subscription behind it? True for
+     * every billed tier, including one no longer on the menu (a grandfathered
+     * row keeps its subscribers), so a console cannot derive it from `/plans`.
+     * It is what sends the account to the Customer Portal rather than to
+     * Checkout, and what a granted plan (`scale`, `sponsored`) never is.
+     */
+    readonly billed: boolean;
+    /**
+     * The next plan up the ladder this account could move to, or `null` when
+     * there is none: the top billed tier, every granted plan, and any plan not
+     * on the menu answer `null`. One server-side fact so that no surface
+     * derives "can this account upgrade, and to what" from the menu — a
+     * grandfathered row has no menu price to compare, and a granted account
+     * must never be sent to Checkout.
+     */
+    readonly upgrade: AccountPlanType | null;
+    /**
+     * The live Subscription's billing interval — Stripe's
+     * `Price.recurring.interval`, mirrored — or `null` when no Subscription
+     * bills the account (free and granted plans). It is what lets the console
+     * offer the current plan's OTHER interval as a switch.
+     */
+    readonly interval: BillingInterval | null;
+    /**
+     * The pending plan change, or `null`. *Up is now, down is at period end*:
+     * a downgrade is a Stripe Subscription Schedule that applies at `at`, and
+     * until then the account keeps everything it paid for. Reversible —
+     * `DELETE /billing/change` releases it.
+     */
+    readonly scheduled: ScheduledChange | null;
+    /**
+     * When the Subscription is set to END — Stripe's `cancel_at`, mirrored
+     * (Unix seconds) — or `null` while it renews. Set by a cancellation in the
+     * Customer Portal; the Portal is also where it is resumed. The console
+     * needs it to ACT: no "cancel" offered to an account already cancelling,
+     * and no plan change offered until it is resumed (the API refuses one).
+     * Mirrored on the rule that survives: what the console must act on is
+     * mirrored, what it would merely display is not.
+     */
+    readonly cancelAt: number | null;
 }
 /**
  * Account as returned by `GET /account` — the entity plus how the request
@@ -1164,8 +1223,10 @@ declare const SIGN_IN_RETURN_PARAM = "signing-in";
  * Client populations: `SESSION` (first-party cookie), `API_KEY` (`ship-`
  * key), `TOKEN` (`deploy-` deploy token), `AGENT` (anonymous public deploy —
  * no credential; the platform grants the public-account identity per
- * request), `OAUTH` (delegated access token). Server populations: `WEBHOOK`
- * (signed webhook processing), `SYSTEM` (scheduled/background jobs).
+ * request), `OAUTH` (delegated access token). The one server population:
+ * `SYSTEM` (scheduled/background jobs). Webhook receipt is deliberately not
+ * a population: a signed delivery is verified, never authorized — it acts
+ * as no one and audits as no one.
  */
 declare const AuthMethod: {
     readonly SESSION: "session";
@@ -1173,7 +1234,6 @@ declare const AuthMethod: {
     readonly TOKEN: "token";
     readonly AGENT: "agent";
     readonly OAUTH: "oauth";
-    readonly WEBHOOK: "webhook";
     readonly SYSTEM: "system";
 };
 type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
@@ -1748,11 +1808,11 @@ interface TokenResource {
     delete: (token: string) => Promise<TokenDeleteResponse>;
 }
 /**
- * How often a subscription renews. The platform sells one plan at two
- * intervals, so this is the only thing a buyer chooses at checkout.
+ * How often a subscription renews. Every billed plan is sold at both
+ * intervals, so a buyer chooses a plan and an interval, and nothing else.
  *
  * It never branches business logic — monthly and yearly confer identical
- * caps. It exists to be displayed and to pick a price at checkout.
+ * caps. It exists to be displayed and to pick a Price at checkout.
  */
 type BillingInterval = 'month' | 'year';
 /**
@@ -1771,13 +1831,20 @@ interface Plan {
     /** 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.
+     * What it costs, per interval — 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: formatting is the reader's job.
+     *
+     * **A free plan costs `{ month: 0, year: 0 }`, not a sentinel.** Free IS
+     * zero, so it is a number like any other and every reader formats it with
+     * the same call; a `'free'` member bought one thing — a branch in each
+     * consumer that mapped it straight back to `$0`.
+     *
+     * `'contact'` stays, and the asymmetry is the point: "not sold at a list
+     * price" is genuinely a different KIND of answer, not a different number, so
+     * it is a different shape. Two shapes, and each earns its own.
      */
-    readonly price: 'free' | 'contact' | {
+    readonly price: 'contact' | {
         readonly month: number;
         readonly year: number;
     };
@@ -1786,6 +1853,20 @@ interface Plan {
      * nothing (a plan sold by conversation publishes no numbers).
      */
     readonly caps: Caps | null;
+    /**
+     * Why this row cannot be ordered right now — the closed door's own sentence,
+     * verbatim — or absent when the way is open. A menu lists what can be
+     * ordered, and a row that is sold but not yet orderable (its door is closed:
+     * checkout unbuilt, a feature unfinished) SAYS SO on the menu instead of
+     * only at the order.
+     *
+     * Clients branch on PRESENCE and render the sentence unchanged — they know
+     * *that* the row is closed, never *which* door or *when it lifts*; the
+     * vocabulary of doors stays server-side. The same rule the refusal follows:
+     * `POST /billing/change` onto a closed row answers 400 with
+     * `details.closed`, and its `message` is this sentence.
+     */
+    readonly closed?: string;
 }
 /**
  * Response for `GET /plans` — the whole public menu, in display order.
@@ -1801,23 +1882,59 @@ interface PlansResponse {
     readonly plans: readonly Plan[];
 }
 /**
- * The answer of `POST /billing/checkout` — Stripe's `Checkout.Session`,
- * projected to the one field a client needs.
+ * The body of `POST /billing/change` — the one door for "get me onto this
+ * plan". Both fields required: with more than one billed plan there is no
+ * honest default, and the console always knows which card was clicked.
  *
- * There is nothing else to return: the outcome arrives later, as a Stripe
- * webhook. It is its own type rather than a shape shared with
- * {@link BillingPortalSession} because Stripe has two distinct objects here,
- * and naming one of them for both would be the reader's translation to make.
+ * The SERVER decides what the change means — the rule is *up is now, down is
+ * at period end* — so the client holds no copy of the ladder: a free account
+ * is sent to Stripe Checkout, a billed account moving up is sent to the
+ * Portal's confirmation page (money moves now, so Stripe's page takes the
+ * consent), and a billed account moving down gets a Stripe Subscription
+ * Schedule that applies the change at period end. The answer says which
+ * happened ({@link PlanChangeResponse}).
  */
-interface CheckoutSession {
-    /** Absolute URL to redirect the browser to. Single use, short-lived. */
+interface PlanChangeRequest {
+    readonly plan: AccountPlanType;
+    readonly interval: BillingInterval;
+}
+/**
+ * The pending plan change — a Stripe Subscription Schedule the platform
+ * minted, mirrored onto the account. `at` is when it applies (the current
+ * period's end, Unix seconds). Reversible until then: `DELETE
+ * /billing/change` releases it.
+ */
+interface ScheduledChange {
+    readonly plan: AccountPlanType;
+    readonly interval: BillingInterval;
+    readonly at: number;
+}
+/**
+ * The answer of `POST /billing/change` — exactly one field is set, and the
+ * UNION is what holds that: an answer carrying both, or neither, does not
+ * compile, so "which door was taken" is structural rather than prose.
+ *
+ * `url` means GO: a Stripe page (Checkout, or the Portal's confirmation page)
+ * finishes the change and the browser must be redirected to it. `scheduled`
+ * means DONE: the downgrade is booked for period end, nothing to visit, and
+ * the account's `scheduled` field now carries it.
+ */
+type PlanChangeResponse = 
+/** GO: a Stripe page finishes the change. Absolute URL, single use, short-lived. */
+{
     readonly url: string;
+    readonly scheduled?: never;
 }
+/** DONE: the downgrade is booked for period end; nothing to visit. */
+ | {
+    readonly url?: never;
+    readonly scheduled: ScheduledChange;
+};
 /**
  * The answer of `POST /billing/portal` — Stripe's `BillingPortal.Session`,
- * projected the same way. Identical in shape to {@link CheckoutSession} and
- * deliberately not merged with it: they are two Stripe objects, and either may
- * gain a field the other never has.
+ * projected to the one field a client needs. The Portal home: cards,
+ * invoices, cancellation. Plan changes have their own door
+ * ({@link PlanChangeRequest}).
  */
 interface BillingPortalSession {
     /** Absolute URL to redirect the browser to. Single use, short-lived. */
@@ -1836,12 +1953,17 @@ interface BillingSyncResponse {
 /**
  * All activity event types logged in the system.
  * Uses dot notation consistently: {resource}.{action}
+ *
+ * Retention: activity rows are permanent — the account's own history and
+ * the platform's audit ledgers are one table, kept for the life of the
+ * account (deletion removes them). Only the personal payload is
+ * time-bounded: past 90 days each row sheds its IP.
  */
-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';
+type ActivityEvent = 'account.create' | 'account.delete' | 'account.key.generate' | '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
  */
-type UserVisibleActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete';
+type UserVisibleActivityEvent = 'account.create' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete';
 /**
  * Activity record returned from the API
  */
@@ -3019,4 +3141,4 @@ declare class Ship extends Ship$1 {
     protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
 }
 
-export { API_KEY, API_PATHS, AUTH_BASE_PATH, type Account, type AccountDeleteResponse, type AccountGetResponse, type AccountKeyResponse, AccountPlan, type AccountPlanType, type AccountResource, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, type BillingInterval, type BillingPortalSession, type BillingSyncResponse, CALLER, type Caps, type CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, type DeployBodyContext, type DeployFile, type DeployInput, type DeployTransport, type Deployment, type DeploymentCreateResponse, type DeploymentDeleteResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, type DeploymentSetOptions, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, DeploymentVia, type DeploymentViaType, type DnsLookup, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDeleteResponse, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetOptions, type DomainSetResult, type DomainShareResponse, DomainStatus, type DomainStatusType, type DomainValidateResponse, type DomainVerifyResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type LabelsResponse, type ListOptions, type ListResponse, type MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, type PingResponse, type Plan, type PlansResponse, type PlatformLimits, type RequestResult, type ResourceContext, SHIP_ENV, SIGN_IN_RETURN_PARAM, type SPACheckDebug, type SPACheckRequest, type SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, type SetupInstructionsResponse, Ship, type ShipClientOptions, ShipError, type ShipEvents, type ShipRequestInit, type StaticFile, TTL_CONSTRAINTS, type Token, type TokenCreateOptions, type TokenCreateResponse, type TokenDeleteResponse, TokenKind, type TokenKindType, type TokenListResponse, type TokenProvider, type TokenResource, type Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validatePassword, validateToken, validateTtl };
+export { API_KEY, API_PATHS, AUTH_BASE_PATH, type Account, type AccountDeleteResponse, type AccountGetResponse, type AccountKeyResponse, AccountPlan, type AccountPlanType, type AccountResource, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, type BillingInterval, type BillingPortalSession, type BillingSyncResponse, CALLER, type Caps, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, type DeployBodyContext, type DeployFile, type DeployInput, type DeployTransport, type Deployment, type DeploymentCreateResponse, type DeploymentDeleteResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, type DeploymentSetOptions, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, DeploymentVia, type DeploymentViaType, type DnsLookup, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDeleteResponse, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetOptions, type DomainSetResult, type DomainShareResponse, DomainStatus, type DomainStatusType, type DomainValidateResponse, type DomainVerifyResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type LabelsResponse, type ListOptions, type ListResponse, type MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, type PingResponse, type Plan, type PlanChangeRequest, type PlanChangeResponse, type PlansResponse, type PlatformLimits, type RequestResult, type ResourceContext, SHIP_ENV, SIGN_IN_RETURN_PARAM, type SPACheckDebug, type SPACheckRequest, type SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, type ScheduledChange, type SetupInstructionsResponse, Ship, type ShipClientOptions, ShipError, type ShipEvents, type ShipRequestInit, type StaticFile, TTL_CONSTRAINTS, type Token, type TokenCreateOptions, type TokenCreateResponse, type TokenDeleteResponse, TokenKind, type TokenKindType, type TokenListResponse, type TokenProvider, type TokenResource, type Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validatePassword, validateToken, validateTtl };