platform-types 1.10.704 → 1.10.706

package/dist/cjs/subscription.js

@@ -13,8 +13,9 @@
  *   (see `PlanCatalogue.trial`). A trial with no payment method drops to
  *   `basico` (`active`, free-tier limits, no lock-out) on the first nightly
  *   sweep after that date, unless a courtesy gift covers today. A Stripe
- *   checkout adds its own fixed 30-day trial, which does not follow those
- *   globals (ADR-0010) and is ended by Stripe's events. Courtesy
+ *   checkout grants no trial of its own: it carries over what is left of the
+ *   row's `trialEndsAt` (as `subscription_data.trial_end`) when that is at
+ *   least 48 h + 5 min away, and bills from checkout otherwise. 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

package/dist/subscription.d.ts

@@ -12,8 +12,9 @@
  *   (see `PlanCatalogue.trial`). A trial with no payment method drops to
  *   `basico` (`active`, free-tier limits, no lock-out) on the first nightly
  *   sweep after that date, unless a courtesy gift covers today. A Stripe
- *   checkout adds its own fixed 30-day trial, which does not follow those
- *   globals (ADR-0010) and is ended by Stripe's events. Courtesy
+ *   checkout grants no trial of its own: it carries over what is left of the
+ *   row's `trialEndsAt` (as `subscription_data.trial_end`) when that is at
+ *   least 48 h + 5 min away, and bills from checkout otherwise. 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
@@ -38,7 +39,9 @@ declare global {
      *   `trialTier` platform global with `trialEndsAt` set `trialDays` days out
      *   (`PlanCatalogue.trial`) — once that date passes with no payment method the
      *   nightly sweep drops the row to `basico`/`active` (unless a courtesy gift
-     *   covers today) — and a Stripe checkout adds its own fixed 30-day trial.
+     *   covers today). A Stripe checkout carries over the remaining
+     *   `trialEndsAt` when it is at least 48 h + 5 min away, else no trial —
+     *   never a fresh fixed period.
      * - `active` — paid subscription, period current.
      * - `past_due` — payment failed, in the 7-day grace window.
      * - `readonly` — grace elapsed, writes blocked, tenant can still read.
@@ -223,17 +226,22 @@ declare global {
     /**
      * How a billing cycle of a plan can be bought:
      *
-     * - `self`  — self-serve checkout: the cycle has a charged price and the
-     *             plan has a `currency`.
+     * - `self`  — self-serve checkout: the cycle has a charged price, the
+     *             plan has a `currency`, and the plan is active.
      * - `sales` — the plan charges some cycle, but not this one self-serve
-     *             (no price on it, or no `currency`); route to "Contactar ventas".
+     *             (no price on it, no `currency`, or `isActive: false`); route
+     *             to "Contactar ventas". On `GET /subscription/plans` the
+     *             caller's OWN hidden tier reads `self` instead, as checkout
+     *             lets that store renew it.
      * - `none`  — neither cycle is charged (the free tier); nothing to buy.
      */
     type PlanCheckoutMode = 'self' | 'sales' | 'none';
     /**
      * A sellable plan in the catalog, exactly as `GET /subscription/plans` and
      * `GET /public/plans` emit it — both build it with the same catalogue
-     * builder, so the two endpoints return identical plans. The template fields
+     * builder, so the two endpoints return identical plans — except the
+     * caller's own hidden tier's `checkout` on `GET /subscription/plans` (see
+     * {@link PlanCheckoutMode}). The template fields
      * (copy, prices, flags) live in DynamoDB (`PLAN#{tier}` / `SK: PLAN`),
      * administered via `POST /platform/billing/plans` +
      * `PATCH /platform/billing/plans/{tier}`; `features` are code, rendered at
@@ -271,7 +279,9 @@ declare global {
         /**
          * Whether the plan is shown on the pricing page and accepting new
          * subscribers. Pre-launch / sales-led tiers set this `false` without
-         * deleting the row.
+         * deleting the row. `POST /subscription/checkout` refuses a `false`
+         * tier with 400 `PLAN_NOT_PURCHASABLE` unless the store's subscription
+         * is already on it — existing subscribers on it may renew.
          */
         isActive: boolean;
         /**
@@ -716,9 +726,10 @@ declare global {
     }
     /**
      * One tier's `SK: PLAN` template row, as assessed by
-     * `report-plan-catalog-drift` (`POST /platform/operations`). Plan features
-     * are code (`planFeatureMatrix.ts`) and cannot drift; the template row is
-     * the only catalogue state a seeder/admin write can still leave stale.
+     * `report-plan-catalog-drift` (`POST /platform/operations`). Plan feature
+     * DEFAULTS are code (`planFeatureMatrix.ts`) and cannot drift; the template
+     * row — its live `grants` overlay included — is the only catalogue state a
+     * seeder/admin write can still leave stale.
      */
     interface TierCatalogDrift {
         tier: PlanTier;
@@ -732,6 +743,19 @@ declare global {
          * place to echo a catalogue's payment-provider IDs.
          */
         missingProviderIds: string[];
+        /**
+         * Keys in the template row's `grants` overlay that the api does not
+         * declare (retired or misspelt), sorted. Inert — every reader ignores them
+         * and the code default applies — but stored, so they are drift: a `null`
+         * for that key on `PATCH /platform/billing/plans/grants` removes them.
+         */
+        undeclaredGrantKeys: string[];
+        /**
+         * Declared keys whose overlay value has the wrong shape for their type
+         * (a `limit` on a boolean key, a fraction, `-2`), sorted. Ignored on read
+         * exactly like an undeclared key, and reported for the same reason.
+         */
+        malformedGrantKeys: string[];
     }
     /** One store holding at least one `OVERRIDE#` row under a key the api no longer declares. */
     interface OrphanOverrideStore {
@@ -778,7 +802,9 @@ declare global {
     interface PlanCatalogDriftReport {
         /**
          * True when ANY tier lacks a template row, a paid one is missing a provider
-         * identifier, or any store holds an override under an undeclared key.
+         * identifier, a tier's `grants` overlay holds an undeclared key
+         * (`undeclaredGrantKeys`) or a wrong-shape value (`malformedGrantKeys`), or
+         * any store holds an override under an undeclared key.
          *
          * ⚠️ An UNBUILT roster (`orphanOverrides.rosterBuiltAt === null`) does not
          * flip this. A stage whose scan has never completed would otherwise answer
@@ -794,6 +820,112 @@ declare global {
         tiers: TierCatalogDrift[];
         orphanOverrides: OrphanOverrideDrift;
     }
+    /**
+     * One feature's grant on one tier, as `PATCH /platform/billing/plans/grants`
+     * takes and reports it: `{ enabled }` for a boolean key, `{ limit }` for a
+     * numeric or metered one (`-1` = unlimited).
+     */
+    type PlanGrantValue = {
+        enabled: boolean;
+    } | {
+        limit: number;
+    };
+    /**
+     * Body of `PATCH /platform/billing/plans/grants` (MANAGER). One request sets
+     * one or more keys on any tiers, atomically: `grants[key][tier]` is the new
+     * grant, or `null` to drop that tier's overlay entry (the code default
+     * applies again). A value equal to the code default is stored as no entry,
+     * so the overlay stays sparse. The final ladder of every changed key must
+     * rise with `displayOrder` (`FEATURE_LADDER_NON_MONOTONIC` otherwise).
+     */
+    interface PlanGrantsWriteRequest {
+        /**
+         * Keyed by feature key. A `string` key rather than `FeatureKey` because a
+         * `null` may name an undeclared key, to clear an inert overlay entry; a
+         * non-null value for one is refused (`PLAN_GRANT_UNKNOWN_KEY`).
+         */
+        grants: Record<string, Partial<Record<PlanTier, PlanGrantValue | null>>>;
+        /** Screened operator reason (10-500 characters, no personal data); lands in each tier's audit entry. */
+        reason: string;
+        /**
+         * Required on a live write: the comma-joined sorted keys the request
+         * changes — the string a dry run of the same body returns. It names the
+         * keys, not the tiers or values, so it proves the caller meant those keys;
+         * the dry run is where the tiers and the impact are reviewed.
+         */
+        confirm?: string;
+        /** `true` writes nothing and returns the impact plus the `confirm` string. */
+        dryRun?: boolean;
+    }
+    /** One key's effective grant on one tier, before and after the write. */
+    interface PlanGrantChange {
+        key: string;
+        /** `null` for an undeclared key — it has no effective grant on either side. */
+        before: PlanGrantValue | null;
+        after: PlanGrantValue | null;
+    }
+    /**
+     * Stores on a tier that a reduction would bite, for one key: they lose a
+     * boolean feature, or their current usage exceeds a lowered limit. Measured
+     * per store with its own overrides applied, so a store whose override keeps
+     * the old grant is not listed. A `readonly` / `canceled` store is never
+     * examined — its plan already lapsed, so the reduction takes nothing more.
+     */
+    interface PlanGrantImpact {
+        key: string;
+        storeIds: string[];
+        /**
+         * `false` for a lowered limit with no usage counter to compare against
+         * (`priceListsMax`): `storeIds` is then
+         * empty because nothing was measured, never because nothing is over.
+         */
+        measured: boolean;
+    }
+    /** One affected tier in a `PATCH /platform/billing/plans/grants` result. */
+    interface PlanGrantsTierResult {
+        tier: PlanTier;
+        changes: PlanGrantChange[];
+        /**
+         * Stores on this tier, any status: those whose SUBSCRIPTION row is on it
+         * (`planTier-status`) plus, on `profesional` — the tier a store with no
+         * SUBSCRIPTION row resolves to — every store with no row. A lower bound
+         * when `truncated`.
+         */
+        subscribedStores: number;
+        /** Dry run only: per reduced key, the stores it bites. Empty when nothing on this tier is reduced. */
+        impact?: PlanGrantImpact[];
+        /**
+         * Dry run: `impact` is a lower bound — more live stores than the walk
+         * examines (100), the request's time budget ran out, one store could not
+         * be read, or the tier's store list itself is short. Live write (present
+         * only when `true`): the follow-up did not reach every store — the budget
+         * ran out, a frame or grace reconcile failed, or the store list is short;
+         * a `PLAN_GRANTS_FANOUT_INCOMPLETE` error row carries the counts. On a
+         * `storefront` / `customDomain` change, every listed store it did not
+         * settle has a due-now grace entry the hourly storefront grace sweep
+         * reconciles (unless the row says some were not scheduled).
+         */
+        truncated?: boolean;
+        /** Live write only: how many stores the `subscription` socket frame was sent to. */
+        notifiedStores?: number;
+        /**
+         * Live write only, and only when the tier's `storefront` or `customDomain`
+         * changed: how many stores' shop grace a reconcile settled — written
+         * (a lost grant starts the 14-day grace; a regained one clears it) or
+         * already in line. A failed reconcile, a store gone, or a store the budget
+         * did not reach is not counted.
+         */
+        reconciledStores?: number;
+    }
+    /** `data` of `PATCH /platform/billing/plans/grants`. */
+    interface PlanGrantsWriteResult {
+        dryRun: boolean;
+        /** `false` on a dry run and on an identical replay (no change, no write, no audit). */
+        written: boolean;
+        /** The comma-joined sorted changed keys — what a live run must send as `confirm`. Empty when nothing changes. */
+        confirm: string;
+        tiers: PlanGrantsTierResult[];
+    }
 }
 export type BillingProviderName = SubscriptionProvider;
 export type InvoiceSummary = globalThis.InvoiceSummary;

package/dist/subscription.js

@@ -12,8 +12,9 @@
  *   (see `PlanCatalogue.trial`). A trial with no payment method drops to
  *   `basico` (`active`, free-tier limits, no lock-out) on the first nightly
  *   sweep after that date, unless a courtesy gift covers today. A Stripe
- *   checkout adds its own fixed 30-day trial, which does not follow those
- *   globals (ADR-0010) and is ended by Stripe's events. Courtesy
+ *   checkout grants no trial of its own: it carries over what is left of the
+ *   row's `trialEndsAt` (as `subscription_data.trial_end`) when that is at
+ *   least 48 h + 5 min away, and bills from checkout otherwise. 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

package/package.json

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