@shipstatic/types 2.17.0-beta.1 → 2.17.0-beta.10

package/dist/index.d.ts

@@ -669,6 +669,16 @@ export interface Account {
      * `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
@@ -1213,8 +1223,10 @@ export 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.
  */
 export declare const AuthMethod: {
     readonly SESSION: "session";
@@ -1222,7 +1234,6 @@ export declare const AuthMethod: {
     readonly TOKEN: "token";
     readonly AGENT: "agent";
     readonly OAUTH: "oauth";
-    readonly WEBHOOK: "webhook";
     readonly SYSTEM: "system";
 };
 export type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
@@ -1842,6 +1853,20 @@ export 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.
@@ -1874,10 +1899,16 @@ export interface PlanChangeRequest {
     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.
+ * The pending plan change — a Stripe Subscription Schedule, mirrored onto the
+ * account. `at` is when it applies (the current period's end, Unix seconds).
+ *
+ * WHO minted the schedule is deliberately not part of this shape, and both
+ * kinds mirror here identically: Stripe mints one when a customer confirms a
+ * cadence downgrade on its own hosted page, and the platform mints one for a
+ * cheaper TIER, the single move Stripe's Customer Portal cannot express.
+ *
+ * Reversible until it applies, and `DELETE /billing/change` is the only way:
+ * Stripe's Portal displays a pending change but offers no control to undo it.
  */
 export interface ScheduledChange {
     readonly plan: AccountPlanType;
@@ -1885,19 +1916,32 @@ export interface ScheduledChange {
     readonly at: number;
 }
 /**
- * The answer of `POST /billing/change` — exactly one field is set.
+ * 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.
- */
-export interface PlanChangeResponse {
-    /** Absolute URL to redirect the browser to. Single use, short-lived. */
-    readonly url?: string;
-    /** The pending change, when the platform scheduled it instead. */
-    readonly scheduled?: ScheduledChange;
+ * finishes the change and the browser must be redirected to it. A `url` does
+ * NOT imply money moves — on the confirmation page Stripe decides whether to
+ * charge now or defer the change to period end, and says which. `scheduled`
+ * means DONE: the change is booked for period end by the platform itself,
+ * nothing to visit, and the account's `scheduled` field now carries it.
+ *
+ * A client branches on the SHAPE and holds no copy of which move takes which
+ * door — which is what let the server move that boundary without a wire
+ * change (2026-08-25).
+ */
+export 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 to the one field a client needs. The Portal home: cards,
@@ -1921,12 +1965,17 @@ export 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.
  */
-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';
+export 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
  */
-export 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';
+export 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
  */

package/dist/index.js

@@ -1150,8 +1150,10 @@ export 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.
  */
 export const AuthMethod = {
     SESSION: 'session',
@@ -1159,7 +1161,6 @@ export const AuthMethod = {
     TOKEN: 'token',
     AGENT: 'agent',
     OAUTH: 'oauth',
-    WEBHOOK: 'webhook',
     SYSTEM: 'system',
 };
 /**

package/package.json

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

package/src/index.ts

@@ -744,6 +744,16 @@ export interface Account {
    * `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;
 }
 
 /**
@@ -1888,8 +1898,10 @@ export 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.
  */
 export const AuthMethod = {
   SESSION: 'session',
@@ -1897,7 +1909,6 @@ export const AuthMethod = {
   TOKEN: 'token',
   AGENT: 'agent',
   OAUTH: 'oauth',
-  WEBHOOK: 'webhook',
   SYSTEM: 'system',
 } as const;
 
@@ -2703,6 +2714,20 @@ export 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;
 }
 
 /**
@@ -2738,10 +2763,16 @@ export interface PlanChangeRequest {
 }
 
 /**
- * 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.
+ * The pending plan change — a Stripe Subscription Schedule, mirrored onto the
+ * account. `at` is when it applies (the current period's end, Unix seconds).
+ *
+ * WHO minted the schedule is deliberately not part of this shape, and both
+ * kinds mirror here identically: Stripe mints one when a customer confirms a
+ * cadence downgrade on its own hosted page, and the platform mints one for a
+ * cheaper TIER, the single move Stripe's Customer Portal cannot express.
+ *
+ * Reversible until it applies, and `DELETE /billing/change` is the only way:
+ * Stripe's Portal displays a pending change but offers no control to undo it.
  */
 export interface ScheduledChange {
   readonly plan: AccountPlanType;
@@ -2750,19 +2781,26 @@ export interface ScheduledChange {
 }
 
 /**
- * The answer of `POST /billing/change` — exactly one field is set.
+ * 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.
+ * finishes the change and the browser must be redirected to it. A `url` does
+ * NOT imply money moves — on the confirmation page Stripe decides whether to
+ * charge now or defer the change to period end, and says which. `scheduled`
+ * means DONE: the change is booked for period end by the platform itself,
+ * nothing to visit, and the account's `scheduled` field now carries it.
+ *
+ * A client branches on the SHAPE and holds no copy of which move takes which
+ * door — which is what let the server move that boundary without a wire
+ * change (2026-08-25).
  */
-export interface PlanChangeResponse {
-  /** Absolute URL to redirect the browser to. Single use, short-lived. */
-  readonly url?: string;
-  /** The pending change, when the platform scheduled it instead. */
-  readonly scheduled?: ScheduledChange;
-}
+export 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`,
@@ -2793,14 +2831,17 @@ export 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.
  */
 export type ActivityEvent =
   // Account events
   | 'account.create'
-  | 'account.update'
   | 'account.delete'
   | 'account.key.generate'
-  | 'account.plan.paid'
   | 'account.plan.transition'
   // Deployment events
   | 'deployment.create'
@@ -2837,7 +2878,6 @@ export type ActivityEvent =
  */
 export type UserVisibleActivityEvent =
   | 'account.create'
-  | 'account.update'
   | 'account.delete'
   | 'account.key.generate'
   | 'account.plan.transition'