platform-types 1.10.701 → 1.10.702

package/dist/cjs/subscription.js

@@ -8,8 +8,11 @@
  *
  * Notes:
  * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0):
- *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. The launch policy
- *   (ADR-0010) gives every new paid subscription a 30-day Stripe trial; courtesy
+ *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. A new store starts trialing on
+ *   the `trialTier` platform global, with `trialEndsAt` set `trialDays` days out
+ *   (see `PlanCatalogue.trial`); that date is not yet enforced for a store
+ *   without a payment provider. A Stripe checkout adds its own fixed 30-day
+ *   trial, which does not follow those globals (ADR-0010). Courtesy
  *   gifts (formerly the Founders cohort) are now a one-off ops action via
  *   `gift-subscription` that sets `freeUntil` on the SUBSCRIPTION row.
  * - `freeUntil` lives on every Subscription independent of status. It is the
@@ -24,7 +27,7 @@
  *   enabled:false until they do.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEATURE_KEYS = exports.PLAN_TIERS = void 0;
+exports.FEATURE_KEYS = exports.isPaidPlanTier = exports.PAID_PLAN_TIERS = exports.PLAN_TIERS = void 0;
 /*
  * Runtime tuples for the unions above.
  *
@@ -44,6 +47,15 @@ exports.FEATURE_KEYS = exports.PLAN_TIERS = void 0;
 const exhaustiveTuple = () => (tuple) => tuple;
 /** Every plan tier, in rank order (lowest first). */
 exports.PLAN_TIERS = exhaustiveTuple()(['basico', 'emprendedor', 'profesional', 'avanzado']);
+/**
+ * Every paid tier, in rank order (lowest first) — `PLAN_TIERS` without the free
+ * `basico`. The one list of "tiers that bill": the trial-tier vocabulary, the
+ * grace sweep's tier fan-out and the provider plan seeders all read it.
+ */
+exports.PAID_PLAN_TIERS = exhaustiveTuple()(['emprendedor', 'profesional', 'avanzado']);
+/** Whether `value` names a paid tier — narrows an untyped read (a stored row, a global) to `PaidPlanTier`. */
+const isPaidPlanTier = (value) => typeof value === 'string' && exports.PAID_PLAN_TIERS.includes(value);
+exports.isPaidPlanTier = isPaidPlanTier;
 /**
  * Every gated feature key.
  *

package/dist/subscription.d.ts

@@ -7,8 +7,11 @@
  *
  * Notes:
  * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0):
- *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. The launch policy
- *   (ADR-0010) gives every new paid subscription a 30-day Stripe trial; courtesy
+ *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. A new store starts trialing on
+ *   the `trialTier` platform global, with `trialEndsAt` set `trialDays` days out
+ *   (see `PlanCatalogue.trial`); that date is not yet enforced for a store
+ *   without a payment provider. A Stripe checkout adds its own fixed 30-day
+ *   trial, which does not follow those globals (ADR-0010). Courtesy
  *   gifts (formerly the Founders cohort) are now a one-off ops action via
  *   `gift-subscription` that sets `freeUntil` on the SUBSCRIPTION row.
  * - `freeUntil` lives on every Subscription independent of status. It is the
@@ -24,10 +27,15 @@
  */
 declare global {
     type PlanTier = 'basico' | 'emprendedor' | 'profesional' | 'avanzado';
+    /** A tier that bills — every `PlanTier` but the free `basico`. Enumerated by `PAID_PLAN_TIERS`. */
+    type PaidPlanTier = Exclude<PlanTier, 'basico'>;
     /**
      * Lifecycle status of a tenant's subscription.
      *
-     * - `trialing` — new paid-tier signup in their 30-day Stripe trial.
+     * - `trialing` — a trial on a paid tier: a new store trials on the
+     *   `trialTier` platform global with `trialEndsAt` set `trialDays` days out
+     *   (`PlanCatalogue.trial`) — a date not yet enforced for a store without a
+     *   payment provider — and a Stripe checkout adds its own fixed 30-day trial.
      * - `active` — paid subscription, period current.
      * - `past_due` — payment failed, in the 7-day grace window.
      * - `readonly` — grace elapsed, writes blocked, tenant can still read.
@@ -319,13 +327,24 @@ declare global {
     }
     /**
      * `data` of `GET /public/plans` and `GET /subscription/plans` — both return
-     * the same `{ plans, groups }`: the plans plus the feature groups their rows
-     * render under.
+     * the same `{ plans, groups, trial }`: the plans, the feature groups their
+     * rows render under, and the trial a new store starts on.
      */
     interface PlanCatalogue {
         plans: Plan[];
         /** Every group a `features[].group` can name, with its label and sort position. */
         groups: PlanFeatureGroup[];
+        /**
+         * What a store registered now starts on: `tier` — a paid tier — in status
+         * `trialing`, with `trialEndsAt` set `days` days out. That date is not yet
+         * enforced for a store without a payment provider. Resolved from the platform globals
+         * `trialTier` / `trialDays` — `profesional` / `30` when unset or invalid —
+         * so it is always present.
+         */
+        trial: {
+            tier: PaidPlanTier;
+            days: number;
+        };
     }
     /**
      * One audit row per MANAGER-driven plan mutation (`POST` / `PATCH
@@ -422,17 +441,35 @@ declare global {
     /** A single usage entry as returned by GET /subscription. */
     interface SubscriptionUsageEntry {
         key: FeatureKey;
-        /** Period in YYYYMM format; `null` for lifetime caps (maxProducts/maxCustomers/maxUsers). */
+        /**
+         * Period in YYYYMM format for a monthly counter; `null` for a cap that never
+         * resets — the lifetime caps (maxProducts/maxCustomers/maxUsers) and the
+         * row-counted ones (webhooks, maxWarehouses: active rows, as their caps count).
+         */
         period: string | null;
         current: number;
-        /** `null` for unlimited tiers (no cap). */
+        /**
+         * The resolved ceiling: `-1` is the unlimited sentinel, and `null` means
+         * the plan declares no ceiling for this key.
+         */
         limit: number | null;
-        /** `null` when `limit` is unlimited/uncapped. */
+        /** `limit - current`, floored at zero; `null` whenever `limit` is `-1` or `null`. */
         remaining: number | null;
     }
     /**
-     * Full subscription snapshot pushed to the frontend on subscription/entitlement
-     * changes. Flat shape — matches GET /subscription wire format directly.
+     * Full subscription snapshot. Three producers emit it:
+     *
+     * - `GET /subscription` — the full `usage[]`, including the row-counted
+     *   `webhooks` / `maxWarehouses` meters. The two are present together or
+     *   absent together: both are absent when the row count failed in this pass,
+     *   and absent is not zero;
+     * - the `GET /store` subscription embed — WITHOUT those two meters (monthly
+     *   and lifetime only) and without `provider`;
+     * - the reply of the MANAGER `PUT /platform/stores/{storeId}/subscription` —
+     *   built by the same assembly as `GET /subscription`, meters included.
+     *
+     * The WebSocket only nudges a refetch on subscription/entitlement changes; it
+     * never carries this payload.
      */
     interface SubscriptionSyncPayload {
         planTier: PlanTier;
@@ -738,6 +775,14 @@ export type BillingProviderName = SubscriptionProvider;
 export type InvoiceSummary = globalThis.InvoiceSummary;
 /** Every plan tier, in rank order (lowest first). */
 export declare const PLAN_TIERS: readonly ["basico", "emprendedor", "profesional", "avanzado"];
+/**
+ * Every paid tier, in rank order (lowest first) — `PLAN_TIERS` without the free
+ * `basico`. The one list of "tiers that bill": the trial-tier vocabulary, the
+ * grace sweep's tier fan-out and the provider plan seeders all read it.
+ */
+export declare const PAID_PLAN_TIERS: readonly ["emprendedor", "profesional", "avanzado"];
+/** Whether `value` names a paid tier — narrows an untyped read (a stored row, a global) to `PaidPlanTier`. */
+export declare const isPaidPlanTier: (value: unknown) => value is PaidPlanTier;
 /**
  * Every gated feature key.
  *

package/dist/subscription.js

@@ -7,8 +7,11 @@
  *
  * Notes:
  * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0):
- *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. The launch policy
- *   (ADR-0010) gives every new paid subscription a 30-day Stripe trial; courtesy
+ *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. A new store starts trialing on
+ *   the `trialTier` platform global, with `trialEndsAt` set `trialDays` days out
+ *   (see `PlanCatalogue.trial`); that date is not yet enforced for a store
+ *   without a payment provider. A Stripe checkout adds its own fixed 30-day
+ *   trial, which does not follow those globals (ADR-0010). Courtesy
  *   gifts (formerly the Founders cohort) are now a one-off ops action via
  *   `gift-subscription` that sets `freeUntil` on the SUBSCRIPTION row.
  * - `freeUntil` lives on every Subscription independent of status. It is the
@@ -41,6 +44,14 @@
 const exhaustiveTuple = () => (tuple) => tuple;
 /** Every plan tier, in rank order (lowest first). */
 export const PLAN_TIERS = exhaustiveTuple()(['basico', 'emprendedor', 'profesional', 'avanzado']);
+/**
+ * Every paid tier, in rank order (lowest first) — `PLAN_TIERS` without the free
+ * `basico`. The one list of "tiers that bill": the trial-tier vocabulary, the
+ * grace sweep's tier fan-out and the provider plan seeders all read it.
+ */
+export const PAID_PLAN_TIERS = exhaustiveTuple()(['emprendedor', 'profesional', 'avanzado']);
+/** Whether `value` names a paid tier — narrows an untyped read (a stored row, a global) to `PaidPlanTier`. */
+export const isPaidPlanTier = (value) => typeof value === 'string' && PAID_PLAN_TIERS.includes(value);
 /**
  * Every gated feature key.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.701",
+	"version": "1.10.702",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",