platform-types 1.10.700 → 1.10.701

package/dist/cjs/subscription.js

@@ -24,3 +24,72 @@
  *   enabled:false until they do.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEATURE_KEYS = exports.PLAN_TIERS = void 0;
+/*
+ * Runtime tuples for the unions above.
+ *
+ * A union alone cannot be iterated, and any consumer that needs to enumerate
+ * every tier or key — zeroing a breakdown, fanning a query across tiers,
+ * rendering a pricing table's rows — otherwise hand-rolls its own copy that
+ * compiles fine while silently omitting a member. A missing member is not a
+ * visible break: it is a bucket that reads zero forever, or a row that never
+ * renders.
+ *
+ * ⚠️ `satisfies readonly PlanTier[]` alone does NOT catch that — it checks each
+ * element IS a tier, never that every tier is present. Hence `exhaustiveTuple`,
+ * whose second type parameter fails to resolve unless the tuple covers the
+ * union, making an omission a compile error at the tuple itself. Module-private
+ * on purpose: it is a type-level trick, not part of the published surface.
+ */
+const exhaustiveTuple = () => (tuple) => tuple;
+/** Every plan tier, in rank order (lowest first). */
+exports.PLAN_TIERS = exhaustiveTuple()(['basico', 'emprendedor', 'profesional', 'avanzado']);
+/**
+ * Every gated feature key.
+ *
+ * ⚠️ Adding a member here is not the whole change, and `typecheck` is what
+ * stops it shipping half-done. In the api, a new key needs a grant in **every
+ * tier** of `PLAN_FEATURES` (`stacks/services/planFeatureMatrix.ts`): that
+ * constant is typed total over every `PlanTier` × `FeatureKey` cell, so a tier
+ * missing the new key's grant, or a grant of the wrong shape for the key's
+ * declared `type`, fails `typecheck` at the `PLAN_FEATURES` declaration
+ * itself. It also widens the api's per-store override key schema, so a new key
+ * immediately becomes a valid override target.
+ *
+ * ⚠️ **A new member also obliges an api PLATFORM-STACK deploy.** Entitlements
+ * resolve inside the Lambda authorizer, built in `PlatformStack`. Deploying only
+ * the handler stacks leaves a STALE authorizer running the previous matrix: the
+ * key is absent from the resolved map, where a boolean gate refuses but a
+ * metered / lifetime cap PASSES THROUGH — a new cap silently unbounded.
+ * Checklist: `docs/PLANS_AND_ENTITLEMENTS.md` in the api repo.
+ */
+exports.FEATURE_KEYS = [
+    'afipInvoicing',
+    'suppliers',
+    'advancedReports',
+    'cashManagement',
+    'importExport',
+    'domesticPayments',
+    'stripePayments',
+    'whatsappCommerce',
+    'aiFeatures',
+    'mobileApp',
+    'customBranding',
+    'customDomain',
+    'prioritySupport',
+    'advancedPricing',
+    'marketplaceChannels',
+    'storefront',
+    'loyalty',
+    'marketing',
+    'mandatory2fa',
+    'maxUsers',
+    'maxProducts',
+    'maxCustomers',
+    'maxWarehouses',
+    'priceListsMax',
+    'webhooks',
+    'maxOrdersMonth',
+    'maxInvoicesMonth',
+    'whatsappMessages',
+];

package/dist/subscription.d.ts

@@ -62,9 +62,10 @@ declare global {
         source?: 'plan' | 'override' | 'trial';
     }
     /**
-     * All gated features. Add new keys here when a new feature becomes gateable;
-     * every existing plan in `FEATURE_MATRIX` must then declare the new key
-     * (TypeScript enforces this via `Record<FeatureKey, Entitlement>`).
+     * All gated features. Add new keys here when a new feature becomes gateable,
+     * and to the `FEATURE_KEYS` tuple below (`UncoveredFeatureKeys` fails
+     * `typecheck` naming the key until you do); the api's `PLAN_FEATURES` matrix
+     * must then grant it on every tier (typed total over `PlanTier` × `FeatureKey`).
      *
      * ⚠️ **`Record<FeatureKey, …>` is NOT the only construction a new member
      * breaks, and searching for it alone will tell you a consumer is unaffected
@@ -148,28 +149,84 @@ declare global {
      * booleans.
      */
     type PlanFeatureStatus = 'live' | 'planned' | 'future' | 'service';
+    /** Singular/plural es-AR noun for a numeric/metered feature's count (e.g. `{ one: 'usuario', other: 'usuarios' }`). */
+    type PlanFeatureUnit = {
+        one: string;
+        other: string;
+    };
+    /**
+     * The window a limit counts over: `month` — a metered counter that resets
+     * monthly (e.g. orders); `active` — a numeric cap on rows that exist right
+     * now (e.g. products, users, depósitos — disabling one frees a slot).
+     */
+    type PlanFeaturePeriod = 'month' | 'active';
     /**
-     * A single feature row in a Plan's `features[]` array. Matches the
-     * BE wire format from `GET /subscription/plans` exactly — boolean
-     * features carry `enabled`, numeric/metered carry `limit` (-1 =
-     * unlimited).
+     * Section a feature row renders under on a pricing table. Each key's label
+     * and sort position travel as a {@link PlanFeatureGroup} in
+     * `PlanCatalogue.groups`, so a consumer never hard-codes either.
      */
-    interface PlanFeature {
+    type PlanFeatureGroupKey = 'limits' | 'billing' | 'channels' | 'operations' | 'growth' | 'enterprise';
+    interface PlanFeatureGroup {
+        key: PlanFeatureGroupKey;
+        /** User-facing Spanish heading. */
+        label: string;
+        /** Sort position among groups (ascending). */
+        order: number;
+    }
+    /** Fields every feature row carries, whatever its `type`. */
+    interface PlanFeatureBase {
         key: FeatureKey;
-        type: EntitlementType;
         status: PlanFeatureStatus;
+        /** Short user-facing Spanish name (the row's title on a pricing table). */
+        label: string;
         /** User-facing Spanish description. */
         description: string;
-        /** Set on `boolean` features; `null` on numeric/metered. */
-        enabled: boolean | null;
-        /** Set on `numeric`/`metered` features; `null` on boolean. -1 = unlimited. */
-        limit: number | null;
+        group: PlanFeatureGroupKey;
+        /** Sort position within `group` (ascending). `features[]` arrives already sorted by group order, then this. */
+        order: number;
+        /** `null` on boolean keys. */
+        unit: PlanFeatureUnit | null;
+        /** `null` on boolean keys. */
+        period: PlanFeaturePeriod | null;
+        /**
+         * The grant rendered server-side as an es-AR noun phrase, ready to print:
+         * `Ilimitado` for `-1`, `1 usuario`, `Hasta 2.000 pedidos por mes`,
+         * `Incluido` / `No incluido` for a boolean. Display copy only — compare
+         * grants through `enabled` / `limit`, never by parsing this.
+         */
+        valueText: string;
     }
     /**
-     * A sellable plan in the catalog. Aligned with the BE wire format from
-     * `GET /subscription/plans`. Source of truth lives in
-     * DynamoDB (`PLAN#{tier}` partition), administered via `POST /sa/plans`
-     * + `PATCH /sa/plans/{tier}`.
+     * A single feature row in a Plan's `features[]` array, discriminated on
+     * `type`: a boolean row carries `enabled` and no `limit` key; a
+     * numeric/metered row carries `limit` and no `enabled` key. `limit: -1` =
+     * unlimited.
+     */
+    type PlanFeature = (PlanFeatureBase & {
+        type: 'boolean';
+        enabled: boolean;
+    }) | (PlanFeatureBase & {
+        type: 'numeric' | 'metered';
+        limit: number;
+    });
+    /**
+     * 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`.
+     * - `sales` — the plan charges some cycle, but not this one self-serve
+     *             (no price on it, or no `currency`); route to "Contactar ventas".
+     * - `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
+     * (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
+     * response time.
      *
      * Prices are integers in the `currency` smallest unit (centavos for ARS,
      * cents for USD). `null` = "Contactar ventas" (AVANZADO annual at launch
@@ -228,20 +285,51 @@ declare global {
          */
         color: string | null;
         /**
-         * Per-feature configuration. Every `FeatureKey` appears exactly once.
-         * Boolean features carry `enabled`; numeric/metered carry `limit`.
+         * Per-feature configuration. Every `FeatureKey` appears exactly once,
+         * whatever its `status` — a `planned` / `future` key is sent too, so
+         * filter on `status` to decide what to advertise. Sorted by group order,
+         * then `order`. Boolean features carry `enabled`; numeric/metered carry
+         * `limit`.
          */
         features: PlanFeature[];
         /**
          * Marketing-curated short bullets for the pricing card. Display order =
          * array order; up to 6 entries, 80 chars each. Always present — empty array
          * when unset (FE synthesizes a list from `features[]`). Lets marketing tweak
-         * copy via `/sa/plans` without a redeploy; replaces the FE-only `BULLET_LIST_BY_TIER`.
+         * copy via `PATCH /platform/billing/plans/{tier}` without a redeploy;
+         * replaces the FE-only `BULLET_LIST_BY_TIER`.
          */
         bullets: string[];
+        /**
+         * Keys worth calling out on this tier's card: highlight-eligible keys with
+         * status `live` or `service` whose grant improves on the next lower
+         * ACTIVE tier (by `displayOrder`; an `isActive: false` tier is skipped,
+         * as pricing pages hide it). The lowest active tier lists its own
+         * eligible keys. A `planned` / `future` key never appears. Each is a
+         * `features[]` key.
+         */
+        highlights: FeatureKey[];
+        /** How each billing cycle can be bought — see {@link PlanCheckoutMode}. */
+        checkout: {
+            monthly: PlanCheckoutMode;
+            annual: PlanCheckoutMode;
+        };
+        /** Whether a subscription on this tier can be cancelled: `true` exactly when at least one cycle is charged. */
+        cancellable: boolean;
+    }
+    /**
+     * `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.
+     */
+    interface PlanCatalogue {
+        plans: Plan[];
+        /** Every group a `features[].group` can name, with its label and sort position. */
+        groups: PlanFeatureGroup[];
     }
     /**
-     * One audit row per SUPER_ADMIN-driven plan mutation, returned by
+     * One audit row per MANAGER-driven plan mutation (`POST` / `PATCH
+     * /platform/billing/plans`, `asManager`), returned by
      * `GET /platform/billing/plans/{tier}/audit`. The store-subscription audit
      * shares this storage shape but is read as `SubscriptionAuditEntry`.
      * `before`/`after` carry only the fields that changed (diff slice).
@@ -648,3 +736,28 @@ declare global {
 }
 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 gated feature key.
+ *
+ * ⚠️ Adding a member here is not the whole change, and `typecheck` is what
+ * stops it shipping half-done. In the api, a new key needs a grant in **every
+ * tier** of `PLAN_FEATURES` (`stacks/services/planFeatureMatrix.ts`): that
+ * constant is typed total over every `PlanTier` × `FeatureKey` cell, so a tier
+ * missing the new key's grant, or a grant of the wrong shape for the key's
+ * declared `type`, fails `typecheck` at the `PLAN_FEATURES` declaration
+ * itself. It also widens the api's per-store override key schema, so a new key
+ * immediately becomes a valid override target.
+ *
+ * ⚠️ **A new member also obliges an api PLATFORM-STACK deploy.** Entitlements
+ * resolve inside the Lambda authorizer, built in `PlatformStack`. Deploying only
+ * the handler stacks leaves a STALE authorizer running the previous matrix: the
+ * key is absent from the resolved map, where a boolean gate refuses but a
+ * metered / lifetime cap PASSES THROUGH — a new cap silently unbounded.
+ * Checklist: `docs/PLANS_AND_ENTITLEMENTS.md` in the api repo.
+ */
+export declare const FEATURE_KEYS: readonly ["afipInvoicing", "suppliers", "advancedReports", "cashManagement", "importExport", "domesticPayments", "stripePayments", "whatsappCommerce", "aiFeatures", "mobileApp", "customBranding", "customDomain", "prioritySupport", "advancedPricing", "marketplaceChannels", "storefront", "loyalty", "marketing", "mandatory2fa", "maxUsers", "maxProducts", "maxCustomers", "maxWarehouses", "priceListsMax", "webhooks", "maxOrdersMonth", "maxInvoicesMonth", "whatsappMessages"];
+type AssertNoUncoveredFeatureKey<T extends never> = T;
+export type UncoveredFeatureKeys = AssertNoUncoveredFeatureKey<Exclude<FeatureKey, (typeof FEATURE_KEYS)[number]>>;
+export {};

package/dist/subscription.js

@@ -22,4 +22,71 @@
  *   declared here even when their epics haven't shipped — the matrix can set
  *   enabled:false until they do.
  */
-export {};
+/*
+ * Runtime tuples for the unions above.
+ *
+ * A union alone cannot be iterated, and any consumer that needs to enumerate
+ * every tier or key — zeroing a breakdown, fanning a query across tiers,
+ * rendering a pricing table's rows — otherwise hand-rolls its own copy that
+ * compiles fine while silently omitting a member. A missing member is not a
+ * visible break: it is a bucket that reads zero forever, or a row that never
+ * renders.
+ *
+ * ⚠️ `satisfies readonly PlanTier[]` alone does NOT catch that — it checks each
+ * element IS a tier, never that every tier is present. Hence `exhaustiveTuple`,
+ * whose second type parameter fails to resolve unless the tuple covers the
+ * union, making an omission a compile error at the tuple itself. Module-private
+ * on purpose: it is a type-level trick, not part of the published surface.
+ */
+const exhaustiveTuple = () => (tuple) => tuple;
+/** Every plan tier, in rank order (lowest first). */
+export const PLAN_TIERS = exhaustiveTuple()(['basico', 'emprendedor', 'profesional', 'avanzado']);
+/**
+ * Every gated feature key.
+ *
+ * ⚠️ Adding a member here is not the whole change, and `typecheck` is what
+ * stops it shipping half-done. In the api, a new key needs a grant in **every
+ * tier** of `PLAN_FEATURES` (`stacks/services/planFeatureMatrix.ts`): that
+ * constant is typed total over every `PlanTier` × `FeatureKey` cell, so a tier
+ * missing the new key's grant, or a grant of the wrong shape for the key's
+ * declared `type`, fails `typecheck` at the `PLAN_FEATURES` declaration
+ * itself. It also widens the api's per-store override key schema, so a new key
+ * immediately becomes a valid override target.
+ *
+ * ⚠️ **A new member also obliges an api PLATFORM-STACK deploy.** Entitlements
+ * resolve inside the Lambda authorizer, built in `PlatformStack`. Deploying only
+ * the handler stacks leaves a STALE authorizer running the previous matrix: the
+ * key is absent from the resolved map, where a boolean gate refuses but a
+ * metered / lifetime cap PASSES THROUGH — a new cap silently unbounded.
+ * Checklist: `docs/PLANS_AND_ENTITLEMENTS.md` in the api repo.
+ */
+export const FEATURE_KEYS = [
+    'afipInvoicing',
+    'suppliers',
+    'advancedReports',
+    'cashManagement',
+    'importExport',
+    'domesticPayments',
+    'stripePayments',
+    'whatsappCommerce',
+    'aiFeatures',
+    'mobileApp',
+    'customBranding',
+    'customDomain',
+    'prioritySupport',
+    'advancedPricing',
+    'marketplaceChannels',
+    'storefront',
+    'loyalty',
+    'marketing',
+    'mandatory2fa',
+    'maxUsers',
+    'maxProducts',
+    'maxCustomers',
+    'maxWarehouses',
+    'priceListsMax',
+    'webhooks',
+    'maxOrdersMonth',
+    'maxInvoicesMonth',
+    'whatsappMessages',
+];

package/package.json

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