@shipstatic/ship 3.1.0 → 3.2.0

package/dist/index.d.cts

@@ -672,9 +672,9 @@ interface TokenDeleteResponse {
  *   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. These
- *   and `free` are the only plans an operator can set; a billed plan is only
- *   ever Stripe's to confer.
+ *   hand, never reached through Checkout: no Stripe subscription and no
+ *   Stripe object behind them. 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
@@ -780,12 +780,10 @@ interface Account {
     /** User profile picture URL, null if not set */
     readonly picture: string | null;
     /**
-     * The tier the account stands at. A sponsored account is Pro that nobody
-     * bills, so it reports `pro` here with {@link billed} false; the grant
-     * itself is the operator's fact, seen on the operator's surfaces and never
-     * here. A console therefore treats a sponsored account exactly as a Pro one
-     * everywhere, and the one difference it can see is the one that is real:
-     * there is no Subscription.
+     * The plan the account is on, by its own name. A granted plan names
+     * itself: a sponsored account reports `sponsored` and a scale one `scale`,
+     * each with {@link billed} false. So a billed plan's name is a promise:
+     * `pro` or `team` here always means a Subscription bills the account.
      */
     readonly plan: AccountPlanType;
     /**
@@ -851,11 +849,12 @@ interface Account {
      */
     readonly billed: boolean;
     /**
-     * The next plan up the ladder this account could move to, or `null` when
-     * there is none: the top billed tier, a plan sold by conversation, 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 conversation plan must never be sent to Checkout.
+     * The next plan up this account could move to: the cheapest sold plan that
+     * offers more than its own, or `null` when none does (the top billed tier)
+     * or the account cannot buy (a plan sold by conversation). 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
+     * conversation plan must never be sent to Checkout.
      */
     readonly upgrade: AccountPlanType | null;
     /**
@@ -2364,6 +2363,13 @@ interface BillingPortalSession {
  */
 interface BillingSyncResponse {
     readonly plan: AccountPlanType;
+    /**
+     * Does Stripe bill that plan? The same fact as {@link Account.billed}, for
+     * the plan named beside it. A purchase lands on a billed plan, so this is
+     * what tells a Checkout arrival that the payment has landed: a plan that is
+     * paid but granted (sponsored) is where the buyer stood before paying.
+     */
+    readonly billed: boolean;
 }
 /**
  * All activity event types logged in the system.

package/dist/index.d.ts

@@ -672,9 +672,9 @@ interface TokenDeleteResponse {
  *   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. These
- *   and `free` are the only plans an operator can set; a billed plan is only
- *   ever Stripe's to confer.
+ *   hand, never reached through Checkout: no Stripe subscription and no
+ *   Stripe object behind them. 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
@@ -780,12 +780,10 @@ interface Account {
     /** User profile picture URL, null if not set */
     readonly picture: string | null;
     /**
-     * The tier the account stands at. A sponsored account is Pro that nobody
-     * bills, so it reports `pro` here with {@link billed} false; the grant
-     * itself is the operator's fact, seen on the operator's surfaces and never
-     * here. A console therefore treats a sponsored account exactly as a Pro one
-     * everywhere, and the one difference it can see is the one that is real:
-     * there is no Subscription.
+     * The plan the account is on, by its own name. A granted plan names
+     * itself: a sponsored account reports `sponsored` and a scale one `scale`,
+     * each with {@link billed} false. So a billed plan's name is a promise:
+     * `pro` or `team` here always means a Subscription bills the account.
      */
     readonly plan: AccountPlanType;
     /**
@@ -851,11 +849,12 @@ interface Account {
      */
     readonly billed: boolean;
     /**
-     * The next plan up the ladder this account could move to, or `null` when
-     * there is none: the top billed tier, a plan sold by conversation, 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 conversation plan must never be sent to Checkout.
+     * The next plan up this account could move to: the cheapest sold plan that
+     * offers more than its own, or `null` when none does (the top billed tier)
+     * or the account cannot buy (a plan sold by conversation). 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
+     * conversation plan must never be sent to Checkout.
      */
     readonly upgrade: AccountPlanType | null;
     /**
@@ -2364,6 +2363,13 @@ interface BillingPortalSession {
  */
 interface BillingSyncResponse {
     readonly plan: AccountPlanType;
+    /**
+     * Does Stripe bill that plan? The same fact as {@link Account.billed}, for
+     * the plan named beside it. A purchase lands on a billed plan, so this is
+     * what tells a Checkout arrival that the payment has landed: a plan that is
+     * paid but granted (sponsored) is where the buyer stood before paying.
+     */
+    readonly billed: boolean;
 }
 /**
  * All activity event types logged in the system.