platform-types 1.10.721 → 1.10.723

package/dist/appointment.d.ts

@@ -959,7 +959,7 @@ declare global {
  * `GET /availability`, an operator queuing a party against a full slot rather
  * than configuring the schedule — so its five refusals are listed above.
  */
-export declare const APPOINTMENT_ERROR_CODES: readonly ["APPOINTMENT_NOT_FOUND", "APPOINTMENT_ID_REQUIRED", "APPOINTMENT_TYPE_DISABLED", "APPOINTMENT_SLOT_UNAVAILABLE", "APPOINTMENT_LEAD_TIME_NOT_MET", "APPOINTMENT_SELF_BOOKING_BLOCKED", "APPOINTMENT_CANCEL_CUTOFF_PASSED", "APPOINTMENT_OUTSIDE_WORKING_HOURS", "APPOINTMENT_TOO_FAR_AHEAD", "APPOINTMENT_ORDER_NOT_FOUND", "APPOINTMENT_ORDER_NOT_SCHEDULABLE", "APPOINTMENT_ORDER_ALREADY_SCHEDULED", "APPOINTMENT_STATUS_TRANSITION_ILLEGAL", "APPOINTMENT_VERSION_CONFLICT", "APPOINTMENT_NOT_CANCELLABLE", "APPOINTMENT_RESCHEDULE_NOOP", "APPOINTMENT_WAITLIST_PARTY_REQUIRED", "APPOINTMENT_WAITLIST_SLOT_AVAILABLE", "APPOINTMENT_WAITLIST_ALREADY_JOINED", "APPOINTMENT_WAITLIST_FULL", "APPOINTMENT_WAITLIST_ENTRY_NOT_FOUND", "INVALID_CURSOR", "RECURRENCE_RULE_MALFORMED", "RECURRENCE_RULE_UNSUPPORTED", "RECURRENCE_UNBOUNDED", "RECURRENCE_TOO_MANY", "APPOINTMENT_NOT_IN_SERIES", "RECURRENCE_SCOPE_REQUIRES_RULE_EDIT", "APPOINTMENT_STATUS_NOT_SCOPEABLE", "RECURRENCE_EXCEPTIONS_UNSUPPORTED", "RECURRENCE_EXCEPTIONS_SCOPE_REQUIRED", "VALIDATION_FAILED", "ROLE_FORBIDDEN", "APPOINTMENT_FEED_SECRET_NOT_CONFIGURED", "APPOINTMENT_FEED_IDENTITY_INVALID"];
+export declare const APPOINTMENT_ERROR_CODES: readonly ["APPOINTMENT_NOT_FOUND", "APPOINTMENT_ID_REQUIRED", "APPOINTMENT_TYPE_DISABLED", "APPOINTMENT_SLOT_UNAVAILABLE", "APPOINTMENT_LEAD_TIME_NOT_MET", "APPOINTMENT_SELF_BOOKING_BLOCKED", "APPOINTMENT_CANCEL_CUTOFF_PASSED", "APPOINTMENT_OUTSIDE_WORKING_HOURS", "APPOINTMENT_TOO_FAR_AHEAD", "APPOINTMENT_ORDER_NOT_FOUND", "APPOINTMENT_ORDER_NOT_SCHEDULABLE", "APPOINTMENT_ORDER_ALREADY_SCHEDULED", "APPOINTMENT_STATUS_TRANSITION_ILLEGAL", "APPOINTMENT_VERSION_CONFLICT", "APPOINTMENT_NOT_CANCELLABLE", "APPOINTMENT_RESCHEDULE_NOOP", "APPOINTMENT_WAITLIST_PARTY_REQUIRED", "APPOINTMENT_WAITLIST_SLOT_AVAILABLE", "APPOINTMENT_WAITLIST_ALREADY_JOINED", "APPOINTMENT_WAITLIST_FULL", "APPOINTMENT_WAITLIST_ENTRY_NOT_FOUND", "INVALID_CURSOR", "RECURRENCE_RULE_MALFORMED", "RECURRENCE_RULE_UNSUPPORTED", "RECURRENCE_UNBOUNDED", "RECURRENCE_TOO_MANY", "APPOINTMENT_NOT_IN_SERIES", "RECURRENCE_SCOPE_REQUIRES_RULE_EDIT", "APPOINTMENT_STATUS_NOT_SCOPEABLE", "RECURRENCE_EXCEPTIONS_UNSUPPORTED", "RECURRENCE_EXCEPTIONS_SCOPE_REQUIRED", "VALIDATION_FAILED", "ROLE_FORBIDDEN", "APPOINTMENT_FEED_SECRET_NOT_CONFIGURED", "APPOINTMENT_FEED_IDENTITY_INVALID", "STORE_MODULE_DISABLED"];
 export type AppointmentErrorCode = (typeof APPOINTMENT_ERROR_CODES)[number];
 /**
  * Which occurrences of a recurring booking an edit applies to —

package/dist/appointment.js

@@ -141,6 +141,8 @@ export const APPOINTMENT_ERROR_CODES = [
     'ROLE_FORBIDDEN',
     'APPOINTMENT_FEED_SECRET_NOT_CONFIGURED',
     'APPOINTMENT_FEED_IDENTITY_INVALID',
+    // The storefront's self-booking surface, while the store has `modules.appointments` off.
+    'STORE_MODULE_DISABLED',
 ];
 /**
  * Which occurrences of a recurring booking an edit applies to —

package/dist/cjs/appointment.js

@@ -144,6 +144,8 @@ exports.APPOINTMENT_ERROR_CODES = [
     'ROLE_FORBIDDEN',
     'APPOINTMENT_FEED_SECRET_NOT_CONFIGURED',
     'APPOINTMENT_FEED_IDENTITY_INVALID',
+    // The storefront's self-booking surface, while the store has `modules.appointments` off.
+    'STORE_MODULE_DISABLED',
 ];
 /**
  * Which occurrences of a recurring booking an edit applies to —

package/dist/cjs/store.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CUSTOM_DOMAIN_ROW_LIMIT = exports.CUSTOM_DOMAIN_SLOT_LIMIT = void 0;
+exports.STORE_MODULE_ERROR_CODES = exports.isStoreModuleOn = exports.isStoreModuleKey = exports.STORE_MODULE_KEYS = exports.CUSTOM_DOMAIN_ROW_LIMIT = exports.CUSTOM_DOMAIN_SLOT_LIMIT = void 0;
 /**
  * How many custom-domain rows a store may hold that count: one active domain
  * and one spare, so a replacement can be verified and provisioned before the
@@ -18,3 +18,65 @@ exports.CUSTOM_DOMAIN_SLOT_LIMIT = 2;
  * `409 DOMAIN_ROW_LIMIT` with this value as `limit`.
  */
 exports.CUSTOM_DOMAIN_ROW_LIMIT = 10;
+/**
+ * Every `StoreModuleKey`, in catalogue order — the ONE list. The type is derived
+ * from it, so the `PATCH /store` validator and every client enumerate exactly
+ * the modules the type allows, and a module is added in one place.
+ */
+exports.STORE_MODULE_KEYS = [
+    'attendance',
+    'lots',
+    'stocktake',
+    'purchases',
+    'loyalty',
+    'surveys',
+    'customerZones',
+    'workshop',
+    'appointments',
+    'cash',
+    'multiWarehouse',
+    'quotes',
+    'promotions',
+    'marketing',
+    'fiscalInvoicing',
+    'customerAccounts',
+];
+/** Whether `value` names a module — narrows an untyped key (a request body, a stored row). */
+const isStoreModuleKey = (value) => typeof value === 'string' && exports.STORE_MODULE_KEYS.includes(value);
+exports.isStoreModuleKey = isStoreModuleKey;
+/**
+ * Whether `module` is on for a store whose `config.modules` is `modules`.
+ * ⚠️ Absent is ON: only an explicit `false` turns a module off, so a missing
+ * map, a missing key and `true` all answer `true`.
+ */
+const isStoreModuleOn = (modules, module) => modules?.[module] !== false;
+exports.isStoreModuleOn = isStoreModuleOn;
+/**
+ * Every refusal code the store-module switches put on the wire, beyond the
+ * platform-wide set (`VALIDATION_FAILED`, and `STORE_CONFIG_FORBIDDEN` for a
+ * plain USER writing the privileged leaf):
+ *
+ * - `STORE_MODULE_UNKNOWN` (400) — `PATCH /store` named a key outside
+ *   `STORE_MODULE_KEYS`; `data.module` carries it.
+ * - `STORE_MODULE_NOT_BOOLEAN` (400) — a module's value was not `true`/`false`.
+ * - `STORE_MODULE_WAREHOUSES_ACTIVE` (409) — `multiWarehouse` off while more
+ *   than one depósito is active; `data.activeWarehouses` carries the count.
+ * - `STORE_MODULE_TRANSFER_IN_FLIGHT` (409) — `multiWarehouse` off while a stock
+ *   transfer is in transit or partially received; `data.transferId` names one.
+ * - `STORE_MODULE_CUSTOMER_BALANCES` (409) — `customerAccounts` off while a
+ *   customer carries a non-zero balance; `data.customerId` names one.
+ * - `STORE_MODULE_BALANCE_CHECK_INCOMPLETE` (409) — the bounded balance read
+ *   stopped before it could prove every balance is zero. Retrying is harmless but
+ *   walks the same rows, so a very large customer book keeps answering it.
+ * - `STORE_MODULE_DISABLED` (403) — a server-enforced module is off (storefront
+ *   self-booking, storefront survey); `data.module` names it.
+ */
+exports.STORE_MODULE_ERROR_CODES = [
+    'STORE_MODULE_UNKNOWN',
+    'STORE_MODULE_NOT_BOOLEAN',
+    'STORE_MODULE_WAREHOUSES_ACTIVE',
+    'STORE_MODULE_TRANSFER_IN_FLIGHT',
+    'STORE_MODULE_CUSTOMER_BALANCES',
+    'STORE_MODULE_BALANCE_CHECK_INCOMPLETE',
+    'STORE_MODULE_DISABLED',
+];

package/dist/cjs/subscription.js

@@ -30,7 +30,7 @@
  *   enabled:false until they do.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEATURE_KEYS = exports.isPaidPlanTier = exports.PAID_PLAN_TIERS = exports.PLAN_TIERS = void 0;
+exports.FEATURE_KEYS = exports.isPaidPlanTier = exports.PLAN_CATALOGUE_ERROR_CODES = exports.PLAN_CATALOGUE_TEMPLATE_FIELDS = exports.PAID_PLAN_TIERS = exports.PLAN_TIERS = void 0;
 /*
  * Runtime tuples for the unions above.
  *
@@ -56,6 +56,29 @@ exports.PLAN_TIERS = exhaustiveTuple()(['basico', 'emprendedor', 'profesional',
  * grace sweep's tier fan-out and the provider plan seeders all read it.
  */
 exports.PAID_PLAN_TIERS = exhaustiveTuple()(['emprendedor', 'profesional', 'avanzado']);
+/** Every template field a plan catalogue draft carries, in the order a diff lists them. */
+exports.PLAN_CATALOGUE_TEMPLATE_FIELDS = exhaustiveTuple()([
+    'name',
+    'description',
+    'displayOrder',
+    'isActive',
+    'isPopular',
+    'color',
+    'priceMonthlyCents',
+    'priceAnnualCents',
+    'currency',
+]);
+/** Every `error` code the plan catalogue draft / publish routes add — the coverage test holds the handlers to it. */
+exports.PLAN_CATALOGUE_ERROR_CODES = exhaustiveTuple()([
+    'PLAN_CATALOGUE_REVISION_CONFLICT',
+    'PLAN_CATALOGUE_BUSY',
+    'PLAN_CATALOGUE_NO_CHANGES',
+    'PLAN_CATALOGUE_PUBLICATION_NOT_FOUND',
+    'PLAN_CATALOGUE_REQUEST_EXPIRED',
+    'PLAN_CATALOGUE_INVALID_CURSOR',
+    'PLAN_CATALOGUE_DRAFT_STALE',
+    'IDEMPOTENCY_CONFLICT',
+]);
 /** 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;

package/dist/store.d.ts

@@ -85,6 +85,19 @@ declare global {
         /** MercadoLibre orders. */
         mercadolibre?: string;
     }
+    /**
+     * One store-wide module a store can switch off for every user — the
+     * catalogue is the shared `domain/STORE_MODULES.md`. Enumerable at runtime as
+     * `STORE_MODULE_KEYS`; read a switch through `isStoreModuleOn`.
+     */
+    type StoreModuleKey = (typeof STORE_MODULE_KEYS)[number];
+    /**
+     * `Store.config.modules`. ⚠️ An ABSENT key is ON — only an explicit `false`
+     * turns a module off, so a store that never wrote the map (every store that
+     * predates it) has every module on. Off HIDES; it never deletes, and the
+     * module's existing records stay readable.
+     */
+    type StoreModules = Partial<Record<StoreModuleKey, boolean>>;
     interface Ecommerce {
         /**
          * The tenant's «Activar tienda online» switch. Written only by the api's
@@ -880,8 +893,50 @@ declare global {
              * Written through `PATCH /store` `config` (admin tier), merged per channel;
              * a channel sent as `null` clears it. Absent, or a channel absent inside
              * it, means that channel's sales use the primary depósito.
+             *
+             * ⚠️ Ignored while `modules.multiWarehouse` is `false`: sales and the
+             * MercadoLibre feed then resolve to the primary depósito (see `modules`),
+             * whatever this holds.
              */
             channelWarehouses?: StoreChannelWarehouses;
+            /**
+             * Store-wide module switches — see `StoreModules`. Written through
+             * `PATCH /store` `config` at the PRIVILEGED tier (ADMIN/SUPERVISOR/MANAGER;
+             * a plain USER is refused `STORE_CONFIG_FORBIDDEN`), merged per key. An
+             * unknown key is refused `400 STORE_MODULE_UNKNOWN`, a non-boolean value
+             * `400 STORE_MODULE_NOT_BOOLEAN`.
+             *
+             * Turning a module OFF is refused while it still carries state:
+             * `multiWarehouse` while more than one depósito is active
+             * (`409 STORE_MODULE_WAREHOUSES_ACTIVE`) or a transfer is in transit or
+             * partially received (`409 STORE_MODULE_TRANSFER_IN_FLIGHT`);
+             * `customerAccounts` while any customer carries a non-zero balance
+             * (`409 STORE_MODULE_CUSTOMER_BALANCES`, or
+             * `409 STORE_MODULE_BALANCE_CHECK_INCOMPLETE` when the bounded read could
+             * not finish).
+             *
+             * Enforced on the server for four modules only:
+             * - `promotions` — applying one is refused `PROMOTION_NOT_ACTIVE` (the
+             *   existing promotion refusal, not `STORE_MODULE_DISABLED`), a grant already
+             *   frozen on a cart stays on the row but derives no money (its
+             *   `promotionEffect` is removed), the storefront checkout and a service
+             *   delivery refuse it `409 CART_PROMOTION_UNAVAILABLE` with
+             *   `data.reason: 'PROMOTION_NOT_ACTIVE'` (removing the grant), and the
+             *   applicable list is empty. A till ticket last written while promotions
+             *   were on (it still carries its `promotionEffect`) converts at the price
+             *   it was sold at.
+             * - `appointments` — storefront availability, booking and rescheduling are
+             *   refused `403 STORE_MODULE_DISABLED`; the shopper's list and cancel stay.
+             * - `surveys` — a storefront survey is refused `403 STORE_MODULE_DISABLED`,
+             *   so none is recorded, broadcast or mailed.
+             * - `multiWarehouse` — every sale resolves to the primary depósito (a
+             *   scoped operator's sale to their own home depósito when the primary is
+             *   outside their scope), and only the primary feeds MercadoLibre.
+             * Every other module is hide-only: its endpoints stay reachable. Public
+             * reads carry only `appointments`, `surveys`, `promotions` and
+             * `customerAccounts`. `PUT /platform/stores/{storeId}` refuses the leaf.
+             */
+            modules?: StoreModules;
         };
         ecommerce?: Ecommerce;
         /**
@@ -1947,3 +2002,39 @@ export declare const CUSTOM_DOMAIN_SLOT_LIMIT = 2;
  * `409 DOMAIN_ROW_LIMIT` with this value as `limit`.
  */
 export declare const CUSTOM_DOMAIN_ROW_LIMIT = 10;
+/**
+ * Every `StoreModuleKey`, in catalogue order — the ONE list. The type is derived
+ * from it, so the `PATCH /store` validator and every client enumerate exactly
+ * the modules the type allows, and a module is added in one place.
+ */
+export declare const STORE_MODULE_KEYS: readonly ["attendance", "lots", "stocktake", "purchases", "loyalty", "surveys", "customerZones", "workshop", "appointments", "cash", "multiWarehouse", "quotes", "promotions", "marketing", "fiscalInvoicing", "customerAccounts"];
+/** Whether `value` names a module — narrows an untyped key (a request body, a stored row). */
+export declare const isStoreModuleKey: (value: unknown) => value is StoreModuleKey;
+/**
+ * Whether `module` is on for a store whose `config.modules` is `modules`.
+ * ⚠️ Absent is ON: only an explicit `false` turns a module off, so a missing
+ * map, a missing key and `true` all answer `true`.
+ */
+export declare const isStoreModuleOn: (modules: StoreModules | null | undefined, module: StoreModuleKey) => boolean;
+/**
+ * Every refusal code the store-module switches put on the wire, beyond the
+ * platform-wide set (`VALIDATION_FAILED`, and `STORE_CONFIG_FORBIDDEN` for a
+ * plain USER writing the privileged leaf):
+ *
+ * - `STORE_MODULE_UNKNOWN` (400) — `PATCH /store` named a key outside
+ *   `STORE_MODULE_KEYS`; `data.module` carries it.
+ * - `STORE_MODULE_NOT_BOOLEAN` (400) — a module's value was not `true`/`false`.
+ * - `STORE_MODULE_WAREHOUSES_ACTIVE` (409) — `multiWarehouse` off while more
+ *   than one depósito is active; `data.activeWarehouses` carries the count.
+ * - `STORE_MODULE_TRANSFER_IN_FLIGHT` (409) — `multiWarehouse` off while a stock
+ *   transfer is in transit or partially received; `data.transferId` names one.
+ * - `STORE_MODULE_CUSTOMER_BALANCES` (409) — `customerAccounts` off while a
+ *   customer carries a non-zero balance; `data.customerId` names one.
+ * - `STORE_MODULE_BALANCE_CHECK_INCOMPLETE` (409) — the bounded balance read
+ *   stopped before it could prove every balance is zero. Retrying is harmless but
+ *   walks the same rows, so a very large customer book keeps answering it.
+ * - `STORE_MODULE_DISABLED` (403) — a server-enforced module is off (storefront
+ *   self-booking, storefront survey); `data.module` names it.
+ */
+export declare const STORE_MODULE_ERROR_CODES: readonly ["STORE_MODULE_UNKNOWN", "STORE_MODULE_NOT_BOOLEAN", "STORE_MODULE_WAREHOUSES_ACTIVE", "STORE_MODULE_TRANSFER_IN_FLIGHT", "STORE_MODULE_CUSTOMER_BALANCES", "STORE_MODULE_BALANCE_CHECK_INCOMPLETE", "STORE_MODULE_DISABLED"];
+export type StoreModuleErrorCode = (typeof STORE_MODULE_ERROR_CODES)[number];

package/dist/store.js

@@ -15,3 +15,63 @@ export const CUSTOM_DOMAIN_SLOT_LIMIT = 2;
  * `409 DOMAIN_ROW_LIMIT` with this value as `limit`.
  */
 export const CUSTOM_DOMAIN_ROW_LIMIT = 10;
+/**
+ * Every `StoreModuleKey`, in catalogue order — the ONE list. The type is derived
+ * from it, so the `PATCH /store` validator and every client enumerate exactly
+ * the modules the type allows, and a module is added in one place.
+ */
+export const STORE_MODULE_KEYS = [
+    'attendance',
+    'lots',
+    'stocktake',
+    'purchases',
+    'loyalty',
+    'surveys',
+    'customerZones',
+    'workshop',
+    'appointments',
+    'cash',
+    'multiWarehouse',
+    'quotes',
+    'promotions',
+    'marketing',
+    'fiscalInvoicing',
+    'customerAccounts',
+];
+/** Whether `value` names a module — narrows an untyped key (a request body, a stored row). */
+export const isStoreModuleKey = (value) => typeof value === 'string' && STORE_MODULE_KEYS.includes(value);
+/**
+ * Whether `module` is on for a store whose `config.modules` is `modules`.
+ * ⚠️ Absent is ON: only an explicit `false` turns a module off, so a missing
+ * map, a missing key and `true` all answer `true`.
+ */
+export const isStoreModuleOn = (modules, module) => modules?.[module] !== false;
+/**
+ * Every refusal code the store-module switches put on the wire, beyond the
+ * platform-wide set (`VALIDATION_FAILED`, and `STORE_CONFIG_FORBIDDEN` for a
+ * plain USER writing the privileged leaf):
+ *
+ * - `STORE_MODULE_UNKNOWN` (400) — `PATCH /store` named a key outside
+ *   `STORE_MODULE_KEYS`; `data.module` carries it.
+ * - `STORE_MODULE_NOT_BOOLEAN` (400) — a module's value was not `true`/`false`.
+ * - `STORE_MODULE_WAREHOUSES_ACTIVE` (409) — `multiWarehouse` off while more
+ *   than one depósito is active; `data.activeWarehouses` carries the count.
+ * - `STORE_MODULE_TRANSFER_IN_FLIGHT` (409) — `multiWarehouse` off while a stock
+ *   transfer is in transit or partially received; `data.transferId` names one.
+ * - `STORE_MODULE_CUSTOMER_BALANCES` (409) — `customerAccounts` off while a
+ *   customer carries a non-zero balance; `data.customerId` names one.
+ * - `STORE_MODULE_BALANCE_CHECK_INCOMPLETE` (409) — the bounded balance read
+ *   stopped before it could prove every balance is zero. Retrying is harmless but
+ *   walks the same rows, so a very large customer book keeps answering it.
+ * - `STORE_MODULE_DISABLED` (403) — a server-enforced module is off (storefront
+ *   self-booking, storefront survey); `data.module` names it.
+ */
+export const STORE_MODULE_ERROR_CODES = [
+    'STORE_MODULE_UNKNOWN',
+    'STORE_MODULE_NOT_BOOLEAN',
+    'STORE_MODULE_WAREHOUSES_ACTIVE',
+    'STORE_MODULE_TRANSFER_IN_FLIGHT',
+    'STORE_MODULE_CUSTOMER_BALANCES',
+    'STORE_MODULE_BALANCE_CHECK_INCOMPLETE',
+    'STORE_MODULE_DISABLED',
+];

package/dist/subscription.d.ts

@@ -357,6 +357,12 @@ declare global {
             tier: PaidPlanTier;
             days: number;
         };
+        /**
+         * The publication these plans are, from `POST /platform/billing/plans/publish`
+         * — so a consumer (the landing snapshot) can tell which version it rendered.
+         * `null` until the catalogue's first publication, or when the rows read are not one publication.
+         */
+        publicationId: string | null;
     }
     /**
      * One audit row per MANAGER-driven plan mutation (`POST` / `PATCH
@@ -879,10 +885,8 @@ declare global {
         /** 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.
+         * Accepted and NOT checked: a grant edit writes the draft, and the echo that
+         * gates what readers see is the publish's (`PlanCataloguePublishInput.confirm`).
          */
         confirm?: string;
         /** `true` writes nothing and returns the impact plus the `confirm` string. */
@@ -920,7 +924,9 @@ declare global {
          * 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`.
+         * when `truncated`. ⚠️ Always `0` on a grant edit, which writes the draft
+         * only: the store counts and the impact are the publish dry run's
+         * (`PlanCataloguePublishTierResult`).
          */
         subscribedStores: number;
         /** Dry run only: per reduced key, the stores it bites. Empty when nothing on this tier is reduced. */
@@ -953,10 +959,174 @@ declare global {
         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. */
+        /** The comma-joined sorted changed keys. Informational on a draft edit — the publish computes its own. */
         confirm: string;
         tiers: PlanGrantsTierResult[];
+        /**
+         * The draft catalogue after the write. Grant edits land in the DRAFT and
+         * reach no reader until `POST /platform/billing/plans/publish`; absent on a
+         * dry run and on an identical replay.
+         */
+        draft?: PlanCatalogueDraftSummary;
+    }
+    /** The template fields a draft carries per tier; provider ids and bookkeeping are never part of it. */
+    type PlanCatalogueTemplateField = 'name' | 'description' | 'displayOrder' | 'isActive' | 'isPopular' | 'color' | 'priceMonthlyCents' | 'priceAnnualCents' | 'currency';
+    /** One template field that differs between the published catalogue and the draft. `null` = absent. */
+    interface PlanCatalogueFieldChange {
+        field: PlanCatalogueTemplateField;
+        before: string | number | boolean | null;
+        after: string | number | boolean | null;
+    }
+    /** One tier the draft changes: its template fields and its effective grants, published → draft. */
+    interface PlanCatalogueTierDiff {
+        tier: PlanTier;
+        fields: PlanCatalogueFieldChange[];
+        changes: PlanGrantChange[];
+    }
+    /**
+     * The two revisions every draft mutation and publish is guarded on. `draftRevision`
+     * is `null` while no draft exists; `publishedRevision` is the current
+     * `publicationId`, `null` before the first publication. A request naming a stale
+     * pair is `409 PLAN_CATALOGUE_REVISION_CONFLICT` and writes nothing.
+     */
+    interface PlanCatalogueRevisions {
+        draftRevision: string | null;
+        publishedRevision: string | null;
+    }
+    /** What a draft write answers alongside its own result. */
+    interface PlanCatalogueDraftSummary extends PlanCatalogueRevisions {
+        /** Whether the draft differs from the published catalogue at all. */
+        dirty: boolean;
+    }
+    /** `data` of `GET /platform/billing/plans/draft` and of the discard / restore mutations. */
+    interface PlanCatalogueDraftResult extends PlanCatalogueDraftSummary {
+        /** The published version number the draft would replace; `null` before the first publication. */
+        publishedVersion: number | null;
+        /** The publication the draft was restored from, until the next edit or publish. */
+        restoredFrom: string | null;
+        /**
+         * Tiers whose published row changed since the draft was started (a direct
+         * row write, or a publication racing the draft's first write). Non-empty means a publish is refused
+         * `409 PLAN_CATALOGUE_DRAFT_STALE`: discard the draft, or restore a
+         * publication into it.
+         */
+        staleTiers: PlanTier[];
+        /** Every operator who wrote this draft, first edit first. */
+        editors: {
+            userId: string;
+            fullName: string;
+        }[];
+        /**
+         * The draft rendered exactly as `GET /public/plans` would serve it once published. Its
+         * `publicationId` is `null` while a draft exists (unpublished content is no publication; the
+         * base it stands on is `publishedRevision`) and the published one when there is no draft.
+         */
+        catalogue: PlanCatalogue;
+        /** Per changed tier, published → draft. Empty when the draft is clean. */
+        diff: PlanCatalogueTierDiff[];
+    }
+    /** Body of `POST /platform/billing/plans/draft/discard`. */
+    interface PlanCatalogueDiscardInput {
+        expectedDraftRevision: string | null;
+        expectedPublishedRevision: string | null;
+    }
+    /** Body of `POST /platform/billing/plans/draft/restore`: copy a past publication into the draft. */
+    interface PlanCatalogueRestoreInput extends PlanCatalogueDiscardInput {
+        publicationId: string;
     }
+    /** Body of `POST /platform/billing/plans/publish`. */
+    interface PlanCataloguePublishInput extends PlanCatalogueDiscardInput {
+        /** Idempotency key, a UUID: a retry with the same body answers the first result; a different body is `409 IDEMPOTENCY_CONFLICT`. */
+        requestId: string;
+        /** Screened operator reason (10-500 characters, no personal data); lands on the publication, the publication-level audit row, every changed tier's audit row and, on the first publish ever, version 1's `recordedReason`. */
+        reason: string;
+        /** Required on a live publish: the `confirm` string the dry run of the same draft returned. */
+        confirm?: string;
+        /** `true` writes nothing and returns the diff, the store counts, the impact and the `confirm` string. */
+        dryRun?: boolean;
+    }
+    /** One changed tier in a publish result. */
+    interface PlanCataloguePublishTierResult extends PlanCatalogueTierDiff {
+        /** Stores on the tier, as `PlanGrantsTierResult.subscribedStores`. */
+        subscribedStores: number;
+        /** Dry run only: per reduced key, the stores it bites. */
+        impact?: PlanGrantImpact[];
+        /** As `PlanGrantsTierResult.truncated`, for the dry run's impact or the live follow-up. */
+        truncated?: boolean;
+        /** Live publish only: stores the `subscription` socket frame reached. */
+        notifiedStores?: number;
+        /** Live publish only, when `storefront` or `customDomain` changed: stores whose shop grace a reconcile settled. */
+        reconciledStores?: number;
+        /**
+         * A paid tier whose price, currency or name changed, with a currency set on the draft being
+         * published (never `basico`, never when that currency is absent): run the provider seeders
+         * to mint its new prices.
+         */
+        stripeSyncRequired: boolean;
+    }
+    /** `data` of `POST /platform/billing/plans/publish`. */
+    interface PlanCataloguePublishResult {
+        dryRun: boolean;
+        written: boolean;
+        /**
+         * The comma-joined sorted changes a live publish must echo: each changed grant
+         * key, and `<tier>.<field>` for each changed template field. Empty when only
+         * the bootstrap would be written.
+         */
+        confirm: string;
+        /** The new current publication; `null` on a dry run. */
+        publicationId: string | null;
+        version: number | null;
+        committedAt: string | null;
+        /** `true` when this publish also recorded the pre-existing live catalogue as version 1. */
+        bootstrapped: boolean;
+        tiers: PlanCataloguePublishTierResult[];
+    }
+    /** One immutable publication in `GET /platform/billing/plans/publications`, newest first. */
+    interface PlanCataloguePublicationEntry {
+        publicationId: string;
+        version: number;
+        committedAt: string;
+        actor: {
+            userId: string;
+            fullName: string;
+        };
+        reason: string;
+        restoredFrom: string | null;
+        /** Who wrote the draft this publication was made from; empty for the bootstrap (version 1). */
+        draftEditors: {
+            userId: string;
+            fullName: string;
+        }[];
+        /**
+         * Version 1 only: the operator whose publish captured the live rows, and
+         * their reason — `actor` there is the system. `null` on every later
+         * publication.
+         */
+        recordedBy: {
+            userId: string;
+            fullName: string;
+        } | null;
+        recordedReason: string | null;
+        /** The publication every reader serves now. */
+        current: boolean;
+    }
+    interface PlanCataloguePublicationPage {
+        items: PlanCataloguePublicationEntry[];
+        cursor?: string;
+    }
+    /** `data` of a `409 PLAN_CATALOGUE_DRAFT_STALE`: the tiers whose published row changed since the draft started. */
+    interface PlanCatalogueDraftStaleData {
+        tiers: PlanTier[];
+    }
+    /** The `error` codes the plan catalogue draft / publish routes add. */
+    type PlanCatalogueErrorCode = 'PLAN_CATALOGUE_REVISION_CONFLICT'
+    /**
+     * 409 · the publish commit was cancelled by a concurrent transaction
+     * alone, on its attempt and its one retry. Nothing was written and no
+     * revision moved: send the same request again.
+     */
+     | 'PLAN_CATALOGUE_BUSY' | 'PLAN_CATALOGUE_NO_CHANGES' | 'PLAN_CATALOGUE_PUBLICATION_NOT_FOUND' | 'PLAN_CATALOGUE_REQUEST_EXPIRED' | 'PLAN_CATALOGUE_INVALID_CURSOR' | 'PLAN_CATALOGUE_DRAFT_STALE' | 'IDEMPOTENCY_CONFLICT';
 }
 export type BillingProviderName = SubscriptionProvider;
 export type InvoiceSummary = globalThis.InvoiceSummary;
@@ -968,6 +1138,10 @@ export declare const PLAN_TIERS: readonly ["basico", "emprendedor", "profesional
  * grace sweep's tier fan-out and the provider plan seeders all read it.
  */
 export declare const PAID_PLAN_TIERS: readonly ["emprendedor", "profesional", "avanzado"];
+/** Every template field a plan catalogue draft carries, in the order a diff lists them. */
+export declare const PLAN_CATALOGUE_TEMPLATE_FIELDS: readonly ["name", "description", "displayOrder", "isActive", "isPopular", "color", "priceMonthlyCents", "priceAnnualCents", "currency"];
+/** Every `error` code the plan catalogue draft / publish routes add — the coverage test holds the handlers to it. */
+export declare const PLAN_CATALOGUE_ERROR_CODES: readonly ["PLAN_CATALOGUE_REVISION_CONFLICT", "PLAN_CATALOGUE_BUSY", "PLAN_CATALOGUE_NO_CHANGES", "PLAN_CATALOGUE_PUBLICATION_NOT_FOUND", "PLAN_CATALOGUE_REQUEST_EXPIRED", "PLAN_CATALOGUE_INVALID_CURSOR", "PLAN_CATALOGUE_DRAFT_STALE", "IDEMPOTENCY_CONFLICT"];
 /** 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;
 /**

package/dist/subscription.js

@@ -53,6 +53,29 @@ export const PLAN_TIERS = exhaustiveTuple()(['basico', 'emprendedor', 'profesion
  * grace sweep's tier fan-out and the provider plan seeders all read it.
  */
 export const PAID_PLAN_TIERS = exhaustiveTuple()(['emprendedor', 'profesional', 'avanzado']);
+/** Every template field a plan catalogue draft carries, in the order a diff lists them. */
+export const PLAN_CATALOGUE_TEMPLATE_FIELDS = exhaustiveTuple()([
+    'name',
+    'description',
+    'displayOrder',
+    'isActive',
+    'isPopular',
+    'color',
+    'priceMonthlyCents',
+    'priceAnnualCents',
+    'currency',
+]);
+/** Every `error` code the plan catalogue draft / publish routes add — the coverage test holds the handlers to it. */
+export const PLAN_CATALOGUE_ERROR_CODES = exhaustiveTuple()([
+    'PLAN_CATALOGUE_REVISION_CONFLICT',
+    'PLAN_CATALOGUE_BUSY',
+    'PLAN_CATALOGUE_NO_CHANGES',
+    'PLAN_CATALOGUE_PUBLICATION_NOT_FOUND',
+    'PLAN_CATALOGUE_REQUEST_EXPIRED',
+    'PLAN_CATALOGUE_INVALID_CURSOR',
+    'PLAN_CATALOGUE_DRAFT_STALE',
+    'IDEMPOTENCY_CONFLICT',
+]);
 /** 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);
 /**

package/package.json

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