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

package/README.md

@@ -102,7 +102,8 @@ import {
 import type {
   PlatformLimits,        // per-request size limits from /limits (file size, file count, total size)
   Plan, PlansResponse,   // the public plan menu from /plans
-  BillingInterval, StripeSession,
+  BillingInterval,       // 'month' | 'year' — Stripe's own recurring interval
+  CheckoutSession, BillingPortalSession,  // the two hosted Stripe pages
   ActivityListResponse,
   PingResponse,
 } from '@shipstatic/types';

package/dist/index.d.ts

@@ -610,15 +610,16 @@ export interface Account {
      */
     readonly used?: number | null;
     /**
-     * True while the Stripe subscription's status is `past_due` and Stripe is
+     * True while the Stripe Subscription's status is `past_due` and Stripe is
      * still retrying the card. The plan is unchanged — the account keeps
      * everything it has — so this is a banner, not a gate.
      *
-     * A BOOLEAN rather than the status string: one fact for the console to
-     * act on. Stripe's own status word is mirrored on the account row for the
-     * operator surface.
+     * A BOOLEAN rather than the status string: one fact for the console to act
+     * on. It carries STRIPE'S OWN WORD (`past_due` → `pastDue`) rather than a
+     * synonym, so no reader has to hold a translation; the full status string is
+     * mirrored on the account row for the operator surface.
      */
-    readonly overdue: boolean;
+    readonly pastDue: boolean;
 }
 /**
  * Account as returned by `GET /account` — the entity plus how the request
@@ -1770,13 +1771,20 @@ export 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;
     };
@@ -1800,14 +1808,25 @@ export interface PlansResponse {
     readonly plans: readonly Plan[];
 }
 /**
- * A page Stripe hosts — a Checkout Session or a Customer Portal session — the
- * answer of `POST /billing/checkout` and `POST /billing/portal` alike.
+ * The answer of `POST /billing/checkout` — Stripe's `Checkout.Session`,
+ * projected to the one field a client needs.
  *
- * One shape for both because both say the same thing: the platform is not
- * where this happens, go here. There is nothing else to return — the
- * outcome arrives later, as a Stripe webhook.
+ * 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.
+ */
+export interface CheckoutSession {
+    /** Absolute URL to redirect the browser to. Single use, short-lived. */
+    readonly url: string;
+}
+/**
+ * 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.
  */
-export interface StripeSession {
+export interface BillingPortalSession {
     /** Absolute URL to redirect the browser to. Single use, short-lived. */
     readonly url: string;
 }

package/package.json

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

package/src/index.ts

@@ -685,15 +685,16 @@ export interface Account {
    */
   readonly used?: number | null;
   /**
-   * True while the Stripe subscription's status is `past_due` and Stripe is
+   * True while the Stripe Subscription's status is `past_due` and Stripe is
    * still retrying the card. The plan is unchanged — the account keeps
    * everything it has — so this is a banner, not a gate.
    *
-   * A BOOLEAN rather than the status string: one fact for the console to
-   * act on. Stripe's own status word is mirrored on the account row for the
-   * operator surface.
+   * A BOOLEAN rather than the status string: one fact for the console to act
+   * on. It carries STRIPE'S OWN WORD (`past_due` → `pastDue`) rather than a
+   * synonym, so no reader has to hold a translation; the full status string is
+   * mirrored on the account row for the operator surface.
    */
-  readonly overdue: boolean;
+  readonly pastDue: boolean;
 }
 
 /**
@@ -2634,13 +2635,20 @@ export 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 month: number; readonly year: number };
+  readonly price: 'contact' | { readonly month: number; readonly year: number };
   /**
    * The caps this plan publishes, or `null` where the menu deliberately says
    * nothing (a plan sold by conversation publishes no numbers).
@@ -2663,14 +2671,26 @@ export interface PlansResponse {
 }
 
 /**
- * A page Stripe hosts — a Checkout Session or a Customer Portal session — the
- * answer of `POST /billing/checkout` and `POST /billing/portal` alike.
+ * The answer of `POST /billing/checkout` — Stripe's `Checkout.Session`,
+ * projected to the one field a client needs.
  *
- * One shape for both because both say the same thing: the platform is not
- * where this happens, go here. There is nothing else to return — the
- * outcome arrives later, as a Stripe webhook.
+ * 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.
+ */
+export interface CheckoutSession {
+  /** Absolute URL to redirect the browser to. Single use, short-lived. */
+  readonly url: string;
+}
+
+/**
+ * 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.
  */
-export interface StripeSession {
+export interface BillingPortalSession {
   /** Absolute URL to redirect the browser to. Single use, short-lived. */
   readonly url: string;
 }