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

package/dist/index.d.ts

@@ -518,11 +518,15 @@ export 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 @@ export interface TokenDeleteResponse {
 export declare const AccountPlan: {
     readonly FREE: "free";
     readonly PRO: "pro";
+    readonly TEAM: "team";
     readonly SCALE: "scale";
     readonly SPONSORED: "sponsored";
 };
 export 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 @@ export 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,37 @@ export 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;
 }
 /**
  * Account as returned by `GET /account` — the entity plus how the request
@@ -1748,11 +1797,11 @@ export 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.
  */
 export type BillingInterval = 'month' | 'year';
 /**
@@ -1808,23 +1857,52 @@ export 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}).
  */
-export interface CheckoutSession {
+export 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.
+ */
+export interface ScheduledChange {
+    readonly plan: AccountPlanType;
+    readonly interval: BillingInterval;
+    readonly at: number;
+}
+/**
+ * The answer of `POST /billing/change` — exactly one field is set.
+ *
+ * `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;
+    readonly url?: string;
+    /** The pending change, when the platform scheduled it instead. */
+    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}).
  */
 export interface BillingPortalSession {
     /** Absolute URL to redirect the browser to. Single use, short-lived. */

package/dist/index.js

@@ -177,11 +177,15 @@ export function validateIdempotencyKey(value) {
  * 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
@@ -191,6 +195,7 @@ export function validateIdempotencyKey(value) {
 export const AccountPlan = {
     FREE: 'free',
     PRO: 'pro',
+    TEAM: 'team',
     SCALE: 'scale',
     SPONSORED: 'sponsored',
 };

package/package.json

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

package/src/index.ts

@@ -590,11 +590,15 @@ export 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
@@ -604,6 +608,7 @@ export interface TokenDeleteResponse {
 export const AccountPlan = {
   FREE: 'free',
   PRO: 'pro',
+  TEAM: 'team',
   SCALE: 'scale',
   SPONSORED: 'sponsored',
 } as const;
@@ -611,18 +616,25 @@ export const AccountPlan = {
 export 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
@@ -636,6 +648,12 @@ export 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.
@@ -695,6 +713,37 @@ export 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;
 }
 
 /**
@@ -2611,11 +2660,11 @@ export interface TokenResource {
 // =============================================================================
 
 /**
- * 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.
  */
 export type BillingInterval = 'month' | 'year';
 
@@ -2671,24 +2720,55 @@ export interface PlansResponse {
 }
 
 /**
- * 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.
+ *
+ * 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}).
+ */
+export 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.
+ */
+export interface ScheduledChange {
+  readonly plan: AccountPlanType;
+  readonly interval: BillingInterval;
+  readonly at: number;
+}
+
+/**
+ * The answer of `POST /billing/change` — exactly one field is set.
  *
- * 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.
+ * `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 CheckoutSession {
+export interface PlanChangeResponse {
   /** Absolute URL to redirect the browser to. Single use, short-lived. */
-  readonly url: string;
+  readonly url?: string;
+  /** The pending change, when the platform scheduled it instead. */
+  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}).
  */
 export interface BillingPortalSession {
   /** Absolute URL to redirect the browser to. Single use, short-lived. */