@shipstatic/types 2.17.0-beta.9 → 2.18.0-beta.1

package/dist/index.d.ts

@@ -1899,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;
@@ -1915,9 +1921,15 @@ export interface ScheduledChange {
  * 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 type PlanChangeResponse = 
 /** GO: a Stripe page finishes the change. Absolute URL, single use, short-lived. */
@@ -1954,12 +1966,13 @@ 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.
+ * Retention: activity rows age out. An account keeps a recent window and,
+ * beneath it, never fewer than its most recent handful — so a dormant
+ * account's history is never empty — and a row that outlives the window
+ * keeps no IP address. Activity from deploys made without an account ages
+ * out sooner, and deleting an account removes its rows outright, at any age.
  */
-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';
+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' | 'checkout.open' | '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/package.json

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

package/src/index.ts

@@ -2763,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;
@@ -2780,9 +2786,15 @@ export interface ScheduledChange {
  * 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 type PlanChangeResponse =
   /** GO: a Stripe page finishes the change. Absolute URL, single use, short-lived. */
@@ -2820,10 +2832,11 @@ 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.
+ * Retention: activity rows age out. An account keeps a recent window and,
+ * beneath it, never fewer than its most recent handful — so a dormant
+ * account's history is never empty — and a row that outlives the window
+ * keeps no IP address. Activity from deploys made without an account ages
+ * out sooner, and deleting an account removes its rows outright, at any age.
  */
 export type ActivityEvent =
   // Account events
@@ -2847,6 +2860,10 @@ export type ActivityEvent =
   | 'token.create'
   | 'token.consume'
   | 'token.delete'
+  // Billing events (internal: the operator's stream, never the customer's
+  // feed — the feed's copy of this fact is the `account.plan.transition` it
+  // may become)
+  | 'checkout.open'
   // Admin events (not user-visible)
   | 'admin.account.plan.update'
   | 'admin.account.suspended.update'
@@ -2856,10 +2873,17 @@ export type ActivityEvent =
   | 'admin.domain.delete'
   | '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.
+// The billing boundary: the stream records the PLATFORM'S own acts, and
+// Stripe records the subscription's life. `checkout.open` is ours — the
+// platform mints the Session, and it is the one billing act that exists
+// before Stripe holds anything. `account.plan.transition` is ours — what a
+// change MEANS, entitlement crossing our threshold. Everything between those
+// two edges (invoices, refunds, disputes, retries, scheduled changes) is the
+// subscription's own history, which belongs to Stripe as merchant of record
+// and is shown to the customer in the Customer Portal; none of it is
+// restated here. Refusals write no history either: the stream records what
+// happened to resources, never what was declined — a detection
+// (`deployment.flagged`) is a fact discovered about content, not a refusal.
 
 /**
  * Activity events visible to users in the dashboard