platform-types 1.10.836 → 1.10.838

package/dist/cjs/customer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CUSTOMER_DISCOUNT_MAX = exports.CUSTOMER_ACQUISITION_CHANNELS = exports.CUSTOMER_LIFECYCLE_STAGES = exports.CUSTOMER_KINDS = void 0;
+exports.isWhatsappNoticesOptedIn = exports.CUSTOMER_DISCOUNT_MAX = exports.CUSTOMER_ACQUISITION_CHANNELS = exports.CUSTOMER_LIFECYCLE_STAGES = exports.CUSTOMER_KINDS = void 0;
 exports.CUSTOMER_KINDS = ['person', 'company'];
 exports.CUSTOMER_LIFECYCLE_STAGES = ['lead', 'active', 'inactive'];
 exports.CUSTOMER_ACQUISITION_CHANNELS = ['storefront', 'pos', 'marketplace', 'import', 'manual'];
@@ -11,3 +11,6 @@ exports.CUSTOMER_ACQUISITION_CHANNELS = ['storefront', 'pos', 'marketplace', 'im
  * `discount` unchanged (or omits it) still saves.
  */
 exports.CUSTOMER_DISCOUNT_MAX = 50;
+/** Whether `notices` records a standing transactional WhatsApp opt-in: `optIn` present and `optOut` absent. */
+const isWhatsappNoticesOptedIn = (notices) => notices?.optIn !== undefined && notices.optOut === undefined;
+exports.isWhatsappNoticesOptedIn = isWhatsappNoticesOptedIn;

package/dist/cjs/guestOrderStatus.js

@@ -1,13 +1,16 @@
 "use strict";
 /**
- * Guest order status link — the read-only page a buyer with no account opens
- * from the order email (`/pedido/{token}`), and the route that mails a fresh
- * link to the address stored on the order.
+ * Guest order status link — the page a buyer with no account opens from the
+ * order email (`/pedido/{token}`), the one consent it can give there, and the
+ * route that mails a fresh link to the address stored on the order.
  *
- * The token (`gs1.…`) is a bearer credential over exactly ONE order, read-only:
- * it authorises no cart write, payment, cancellation, withdrawal or export. It
- * carries no expiry; the read is refused once the order was delivered (or
- * cancelled) more than `guestStatusLinkDaysAfterDelivery` days ago — unless a
+ * The token (`gs1.…`) is a bearer credential over exactly ONE order. It
+ * authorises the read and exactly ONE write: the transactional WhatsApp consent
+ * grant for the order's own customer in that store
+ * (`POST /orders/status/whatsapp-opt-in`, {@link GuestOrderWhatsappOptInRequest}).
+ * Nothing else — no cart write, payment, cancellation, withdrawal or export.
+ * Both routes authorise it identically. It carries no expiry; it is refused
+ * once the order was delivered (or cancelled) more than `guestStatusLinkDaysAfterDelivery` days ago — unless a
  * purchase withdrawal on it is not final or a refund on it is not closed — and
  * every earlier link dies when a recovery or an operator revokes it.
  *
@@ -16,7 +19,7 @@
  * code mailed to the order's address, so the token still authorises none.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GUEST_ORDER_STATUS_LINK_TEMPLATE = exports.GUEST_ORDER_STATUS_ERROR_CODES = void 0;
+exports.GUEST_ORDER_STATUS_LINK_TEMPLATE = exports.GUEST_ORDER_WHATSAPP_OPT_IN_ERROR_CODES = exports.GUEST_ORDER_STATUS_ERROR_CODES = void 0;
 /**
  * The refusals the guest status routes answer themselves.
  *
@@ -28,5 +31,15 @@ exports.GUEST_ORDER_STATUS_LINK_TEMPLATE = exports.GUEST_ORDER_STATUS_ERROR_CODE
  *   `POST /orders/status/recover`.
  */
 exports.GUEST_ORDER_STATUS_ERROR_CODES = ['GUEST_STATUS_TOKEN_INVALID'];
+/**
+ * The refusals `POST /orders/status/whatsapp-opt-in` answers itself, past the
+ * token (which refuses `GUEST_STATUS_TOKEN_INVALID` exactly as the read does).
+ *
+ * - WHATSAPP_OPT_IN_UNAVAILABLE (409): the offer does not hold for this order —
+ *   the store's messaging is unavailable, the order is cancelled, delivered or
+ *   disabled, carries no phone, or its customer row is no longer live. Nothing
+ *   is written. One code for every reason.
+ */
+exports.GUEST_ORDER_WHATSAPP_OPT_IN_ERROR_CODES = ['WHATSAPP_OPT_IN_UNAVAILABLE'];
 /** The transactional email template that mails a guest their (new) status link. */
 exports.GUEST_ORDER_STATUS_LINK_TEMPLATE = 'guest-order-status-link';

package/dist/cjs/store.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CHANGE_OF_MIND_WINDOW_SOURCE = exports.CHANGE_OF_MIND_RETURN_DAYS_MAX = exports.CHANGE_OF_MIND_REFUND_AS = exports.CHANGE_OF_MIND_RETURN_SHIPPING_PAYERS = exports.STORE_PATCH_ERROR_CODES = exports.STORE_MODULE_ERROR_CODES = exports.isStoreModuleOn = exports.isStoreModuleKey = exports.STORE_MODULE_KEYS = exports.STOREFRONT_METHOD_KINDS = exports.STORE_ONBOARDING_REVIEW_AREAS = exports.CUSTOM_DOMAIN_ROW_LIMIT = exports.CUSTOM_DOMAIN_SLOT_LIMIT = void 0;
+exports.resolveStoreMessaging = exports.STORE_MESSAGING_SIGNATURE_MAX = exports.STORE_MESSAGING_DEFAULTS = exports.STORE_MESSAGE_NOTICES = exports.CHANGE_OF_MIND_WINDOW_SOURCE = exports.CHANGE_OF_MIND_RETURN_DAYS_MAX = exports.CHANGE_OF_MIND_REFUND_AS = exports.CHANGE_OF_MIND_RETURN_SHIPPING_PAYERS = exports.STORE_PATCH_ERROR_CODES = exports.STORE_MODULE_ERROR_CODES = exports.isStoreModuleOn = exports.isStoreModuleKey = exports.STORE_MODULE_KEYS = exports.STOREFRONT_METHOD_KINDS = exports.STORE_ONBOARDING_REVIEW_AREAS = 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
@@ -119,6 +119,7 @@ exports.STORE_MODULE_ERROR_CODES = [
  * - `AFIP_RELACION_FLAG_FORBIDDEN` — `afip.wscdcEnabled` / `afip.fceEnabled`.
  * - `FX_TABLE_FORBIDDEN` — the `currencies` exchange-rate table.
  * - `FX_AUTO_UPDATE_FORBIDDEN` — `fxAutoUpdate`.
+ * - `STORE_MESSAGING_FORBIDDEN` — the `messaging` customer-messaging settings.
  *
  * Request refusals, `400`:
  * - `FIELD_NOT_WRITABLE_HERE` — a field written through `POST /store`, not
@@ -197,6 +198,7 @@ exports.STORE_PATCH_ERROR_CODES = [
     'NET_PLUS_IVA_REQUIRES_RI',
     'DATA_FISCAL_URL_INVALID',
     'STORE_PUBLIC_HOST_MISSING',
+    'STORE_MESSAGING_FORBIDDEN',
     'FORBIDDEN',
     'STORE_NOT_FOUND',
 ];
@@ -208,3 +210,63 @@ exports.CHANGE_OF_MIND_REFUND_AS = ['refund', 'store-credit'];
 exports.CHANGE_OF_MIND_RETURN_DAYS_MAX = 365;
 /** The source of a change-of-mind deadline: the store's own setting, not a statutory row. */
 exports.CHANGE_OF_MIND_WINDOW_SOURCE = 'store:changeOfMindReturns';
+/**
+ * Every `StoreMessageNotice`, in the order the settings screen lists them —
+ * the keys `Store.integrations.messaging` switches. `UncoveredStoreMessageNotices`
+ * fails `typecheck` naming a notice the union gains and this tuple lacks.
+ */
+exports.STORE_MESSAGE_NOTICES = [
+    'orderReady',
+    'orderShipped',
+    'serviceOrderReceived',
+    'serviceOrderQuoted',
+    'serviceOrderApproved',
+    'serviceOrderReady',
+    'serviceOrderCancelled',
+    'serviceOrderReturnedUnrepaired',
+    'serviceOrderAbandoned',
+    'serviceOrderOnHold',
+    'serviceOrderResumed',
+    'appointmentReminder',
+    'paymentReminder',
+];
+/**
+ * What an ABSENT `messaging` key reads: status notices and appointment
+ * reminders on, payment reminders off, the SMS fallback on.
+ */
+exports.STORE_MESSAGING_DEFAULTS = {
+    orderReady: true,
+    orderShipped: true,
+    serviceOrderReceived: true,
+    serviceOrderQuoted: true,
+    serviceOrderApproved: true,
+    serviceOrderReady: true,
+    serviceOrderCancelled: true,
+    serviceOrderReturnedUnrepaired: true,
+    serviceOrderAbandoned: true,
+    serviceOrderOnHold: true,
+    serviceOrderResumed: true,
+    appointmentReminder: true,
+    paymentReminder: false,
+    smsFallback: true,
+};
+/** The firma cap — the same one `sms.signature` has. */
+exports.STORE_MESSAGING_SIGNATURE_MAX = 80;
+/**
+ * Every switch of a store's messaging settings, decided: per key, the stored
+ * boolean, else its `STORE_MESSAGING_DEFAULTS` value (a stored non-boolean
+ * reads as absent). `signature` falls back to `sms.signature` only when
+ * `messaging.signature` is absent; a stored `''` is kept and means no firma.
+ */
+const resolveStoreMessaging = (integrations) => {
+    const leaf = integrations?.messaging;
+    const resolved = { ...exports.STORE_MESSAGING_DEFAULTS };
+    for (const key of [...exports.STORE_MESSAGE_NOTICES, 'smsFallback']) {
+        const stored = leaf?.[key];
+        if (typeof stored === 'boolean')
+            resolved[key] = stored;
+    }
+    const signature = typeof leaf?.signature === 'string' ? leaf.signature : integrations?.sms?.signature;
+    return typeof signature === 'string' ? { ...resolved, signature } : resolved;
+};
+exports.resolveStoreMessaging = resolveStoreMessaging;

package/dist/cjs/subscription.js

@@ -132,4 +132,5 @@ exports.FEATURE_KEYS = [
     'webhooks',
     'maxOrdersMonth',
     'maxInvoicesMonth',
+    'monthlyMessageAllowance',
 ];

package/dist/customer.d.ts

@@ -8,6 +8,8 @@ export declare const CUSTOMER_ACQUISITION_CHANNELS: readonly ["storefront", "pos
  * `discount` unchanged (or omits it) still saves.
  */
 export declare const CUSTOMER_DISCOUNT_MAX = 50;
+/** Whether `notices` records a standing transactional WhatsApp opt-in: `optIn` present and `optOut` absent. */
+export declare const isWhatsappNoticesOptedIn: (notices: CustomerWhatsappNotices | undefined) => boolean;
 declare global {
     /** Exact identity matches within the token's store; no stored identity fields are returned. */
     interface CustomerDuplicateCandidate {
@@ -95,8 +97,62 @@ declare global {
         /** Per-customer, not per-channel — one unsubscribe link covers every channel. */
         unsubscribeToken?: string;
     }
-    /** Write shape for customer create/update — carries the transient photo controls. */
-    type CustomerUpsertInput = Partial<Customer> & PhotoUploadControls;
+    /**
+     * Where a transactional WhatsApp grant or withdrawal was given:
+     * `back-office` (staff, `POST /customers`), `storefront-post-purchase` (the
+     * one-tap offer after an order is placed — the signed-in banner through web
+     * `POST /user` with `whatsappOptInOrigin: 'post-purchase'`, or a guest's
+     * `POST /orders/status/whatsapp-opt-in`) and `storefront-profile` (the
+     * shopper's own profile toggle, web `POST /user`).
+     */
+    type WhatsappNoticeSource = 'back-office' | 'storefront-post-purchase' | 'storefront-profile';
+    /**
+     * Provenance of one transactional WhatsApp grant or withdrawal.
+     * Server-written only. Carries NO phone number and NO IP, unlike
+     * `ChannelConsentStamp` (deliberately not extended), and not who acted.
+     */
+    interface WhatsappNoticeStamp {
+        /** ms epoch. */
+        ts: number;
+        source: WhatsappNoticeSource;
+    }
+    /**
+     * `Customer.whatsappNotices`: the customer's consent to the store's
+     * transactional WhatsApp notices (order and service-order status,
+     * reminders). Per customer per store, since the CUSTOMER row is
+     * store-scoped. Separate from `CustomerMarketing`, and never marketing
+     * consent.
+     *
+     * Opted in ⇔ `optIn` present AND `optOut` absent; read it through
+     * `isWhatsappNoticesOptedIn`. A grant SETs `optIn` and REMOVEs `optOut`; a
+     * withdrawal SETs `optOut` and keeps `optIn`. Resending the current state
+     * changes nothing and does not re-stamp; a withdrawal from a customer who
+     * never opted in is recorded. Not a history: it holds the latest grant and
+     * the latest withdrawal only. ⚠️ Absent is NOT consent.
+     */
+    interface CustomerWhatsappNotices {
+        optIn?: WhatsappNoticeStamp;
+        optOut?: WhatsappNoticeStamp;
+    }
+    /** Write shape: `whatsappNotices` is server-owned, and `whatsappOptIn` is the directive that moves it. */
+    type CustomerUpsertInput = Partial<Omit<Customer, 'whatsappNotices'>> & PhotoUploadControls & {
+        /**
+         * `POST /customers` (source `back-office`) and web `POST /user` (source
+         * `storefront-profile`): `true` grants, `false` withdraws, absent changes
+         * nothing. Never stored. Staff MAY grant, because this is not marketing
+         * consent. A storefront grant acts only while `Store.messagingAvailable`
+         * holds and is otherwise dropped; a withdrawal always acts.
+         */
+        whatsappOptIn?: boolean;
+        /**
+         * Web `POST /user` only: `'post-purchase'` names the grant as the one-tap
+         * offer after an order (`whatsappOptInOffer` on the order read), so the
+         * stamp's source is `storefront-post-purchase` instead of
+         * `storefront-profile`. A directive, never stored, and ignored unless
+         * `whatsappOptIn` is `true`.
+         */
+        whatsappOptInOrigin?: 'post-purchase';
+    };
     /**
      * The query string of the customers LIST read — `GET /customers` with no
      * `customerId`, `list` or `email`. Every present filter AND-composes: a row is
@@ -568,6 +624,8 @@ declare global {
          */
         mergeBalanceCarried?: boolean;
         marketing?: CustomerMarketing;
+        /** Transactional WhatsApp consent for this store — see `CustomerWhatsappNotices`. Server-written. */
+        whatsappNotices?: CustomerWhatsappNotices;
         /** Optional notification mail only; transactional mail cannot be disabled. */
         notificationPreferences?: CustomerNotificationPreferences;
         minBuy?: number;

package/dist/customer.js

@@ -8,3 +8,5 @@ export const CUSTOMER_ACQUISITION_CHANNELS = ['storefront', 'pos', 'marketplace'
  * `discount` unchanged (or omits it) still saves.
  */
 export const CUSTOMER_DISCOUNT_MAX = 50;
+/** Whether `notices` records a standing transactional WhatsApp opt-in: `optIn` present and `optOut` absent. */
+export const isWhatsappNoticesOptedIn = (notices) => notices?.optIn !== undefined && notices.optOut === undefined;

package/dist/guestOrderStatus.d.ts

@@ -1,12 +1,15 @@
 /**
- * Guest order status link — the read-only page a buyer with no account opens
- * from the order email (`/pedido/{token}`), and the route that mails a fresh
- * link to the address stored on the order.
+ * Guest order status link — the page a buyer with no account opens from the
+ * order email (`/pedido/{token}`), the one consent it can give there, and the
+ * route that mails a fresh link to the address stored on the order.
  *
- * The token (`gs1.…`) is a bearer credential over exactly ONE order, read-only:
- * it authorises no cart write, payment, cancellation, withdrawal or export. It
- * carries no expiry; the read is refused once the order was delivered (or
- * cancelled) more than `guestStatusLinkDaysAfterDelivery` days ago — unless a
+ * The token (`gs1.…`) is a bearer credential over exactly ONE order. It
+ * authorises the read and exactly ONE write: the transactional WhatsApp consent
+ * grant for the order's own customer in that store
+ * (`POST /orders/status/whatsapp-opt-in`, {@link GuestOrderWhatsappOptInRequest}).
+ * Nothing else — no cart write, payment, cancellation, withdrawal or export.
+ * Both routes authorise it identically. It carries no expiry; it is refused
+ * once the order was delivered (or cancelled) more than `guestStatusLinkDaysAfterDelivery` days ago — unless a
  * purchase withdrawal on it is not final or a refund on it is not closed — and
  * every earlier link dies when a recovery or an operator revokes it.
  *
@@ -26,6 +29,17 @@
  */
 export declare const GUEST_ORDER_STATUS_ERROR_CODES: readonly ["GUEST_STATUS_TOKEN_INVALID"];
 export type GuestOrderStatusErrorCode = (typeof GUEST_ORDER_STATUS_ERROR_CODES)[number];
+/**
+ * The refusals `POST /orders/status/whatsapp-opt-in` answers itself, past the
+ * token (which refuses `GUEST_STATUS_TOKEN_INVALID` exactly as the read does).
+ *
+ * - WHATSAPP_OPT_IN_UNAVAILABLE (409): the offer does not hold for this order —
+ *   the store's messaging is unavailable, the order is cancelled, delivered or
+ *   disabled, carries no phone, or its customer row is no longer live. Nothing
+ *   is written. One code for every reason.
+ */
+export declare const GUEST_ORDER_WHATSAPP_OPT_IN_ERROR_CODES: readonly ["WHATSAPP_OPT_IN_UNAVAILABLE"];
+export type GuestOrderWhatsappOptInErrorCode = (typeof GUEST_ORDER_WHATSAPP_OPT_IN_ERROR_CODES)[number];
 /** The transactional email template that mails a guest their (new) status link. */
 export declare const GUEST_ORDER_STATUS_LINK_TEMPLATE: "guest-order-status-link";
 declare global {
@@ -115,6 +129,17 @@ declare global {
         returnRequests?: OrderReturnRequestView[];
         /** Whether a return request can be opened now. Absent only when the return requests could not be read whole. */
         returnRequestEligibility?: OrderReturnRequestEligibility;
+        /**
+         * Present, and `true`, only when the post-purchase «Avisarme por WhatsApp
+         * sobre este pedido» may be offered: the store's messaging is available
+         * (`Store.messagingAvailable`), the order is not cancelled, delivered or
+         * disabled, it carries a phone (its customer's or the guest contact's),
+         * and its customer row is live and NOT opted in
+         * (`Customer.whatsappNotices`). Accept it with
+         * `POST /orders/status/whatsapp-opt-in`. Carries no phone. Absent too when
+         * the offer could not be computed — the read never fails for it.
+         */
+        whatsappOptInOffer?: true;
         contact: {
             /** The stored address, masked (e.g. `j***@d***.com`). */
             emailMasked: string;
@@ -131,4 +156,21 @@ declare global {
         orderId: string;
         email: string;
     }
+    /**
+     * `POST /orders/status/whatsapp-opt-in` body (strict): the guest status token
+     * of the order whose post-purchase WhatsApp offer (`whatsappOptInOffer`) is
+     * accepted. The token is authorised exactly as `GET /orders/status` does it
+     * (one `401 GUEST_STATUS_TOKEN_INVALID` for every refusal; a malformed body
+     * too). Then the grant: `200` {@link GuestOrderWhatsappOptInResult} when the
+     * customer is now opted in — freshly stamped `{ ts, source:
+     * 'storefront-post-purchase' }`, or already opted in (nothing written, never
+     * re-stamped) — else `409 WHATSAPP_OPT_IN_UNAVAILABLE`, nothing written.
+     */
+    interface GuestOrderWhatsappOptInRequest {
+        token: string;
+    }
+    /** `data` of a `200` `POST /orders/status/whatsapp-opt-in`. */
+    interface GuestOrderWhatsappOptInResult {
+        whatsappNoticesOptedIn: true;
+    }
 }

package/dist/guestOrderStatus.js

@@ -1,12 +1,15 @@
 /**
- * Guest order status link — the read-only page a buyer with no account opens
- * from the order email (`/pedido/{token}`), and the route that mails a fresh
- * link to the address stored on the order.
+ * Guest order status link — the page a buyer with no account opens from the
+ * order email (`/pedido/{token}`), the one consent it can give there, and the
+ * route that mails a fresh link to the address stored on the order.
  *
- * The token (`gs1.…`) is a bearer credential over exactly ONE order, read-only:
- * it authorises no cart write, payment, cancellation, withdrawal or export. It
- * carries no expiry; the read is refused once the order was delivered (or
- * cancelled) more than `guestStatusLinkDaysAfterDelivery` days ago — unless a
+ * The token (`gs1.…`) is a bearer credential over exactly ONE order. It
+ * authorises the read and exactly ONE write: the transactional WhatsApp consent
+ * grant for the order's own customer in that store
+ * (`POST /orders/status/whatsapp-opt-in`, {@link GuestOrderWhatsappOptInRequest}).
+ * Nothing else — no cart write, payment, cancellation, withdrawal or export.
+ * Both routes authorise it identically. It carries no expiry; it is refused
+ * once the order was delivered (or cancelled) more than `guestStatusLinkDaysAfterDelivery` days ago — unless a
  * purchase withdrawal on it is not final or a refund on it is not closed — and
  * every earlier link dies when a recovery or an operator revokes it.
  *
@@ -25,5 +28,15 @@
  *   `POST /orders/status/recover`.
  */
 export const GUEST_ORDER_STATUS_ERROR_CODES = ['GUEST_STATUS_TOKEN_INVALID'];
+/**
+ * The refusals `POST /orders/status/whatsapp-opt-in` answers itself, past the
+ * token (which refuses `GUEST_STATUS_TOKEN_INVALID` exactly as the read does).
+ *
+ * - WHATSAPP_OPT_IN_UNAVAILABLE (409): the offer does not hold for this order —
+ *   the store's messaging is unavailable, the order is cancelled, delivered or
+ *   disabled, carries no phone, or its customer row is no longer live. Nothing
+ *   is written. One code for every reason.
+ */
+export const GUEST_ORDER_WHATSAPP_OPT_IN_ERROR_CODES = ['WHATSAPP_OPT_IN_UNAVAILABLE'];
 /** The transactional email template that mails a guest their (new) status link. */
 export const GUEST_ORDER_STATUS_LINK_TEMPLATE = 'guest-order-status-link';

package/dist/paymentAttempt.d.ts

@@ -145,6 +145,18 @@ declare global {
         returnRequests?: OrderReturnRequestView[];
         /** Whether a return request can be opened now. Absent only when the return requests could not be read whole. */
         returnRequestEligibility?: OrderReturnRequestEligibility;
+        /**
+         * Point read (`?orderId=`) only, never the list. Present, and `true`, only
+         * when the post-purchase «Avisarme por WhatsApp sobre este pedido» may be
+         * offered: the store's messaging is available (`Store.messagingAvailable`),
+         * the order is not cancelled, delivered or disabled, it carries a phone
+         * (`customer.phone` or the guest contact's), and the order's customer row
+         * is live and NOT opted in (`Customer.whatsappNotices`). Accept it with web
+         * `POST /user` `{ whatsappOptIn: true, whatsappOptInOrigin: 'post-purchase' }`.
+         * Carries no phone. Absent too when the offer could not be computed — the
+         * order read never fails for it.
+         */
+        whatsappOptInOffer?: true;
     };
     /**
      * `data` of an `orderPaymentAttempt` socket frame, sent to the order's own

package/dist/return.d.ts

@@ -771,6 +771,13 @@ declare global {
         cashRefund?: ReturnCashRefund;
         /** Mirrors Return.owedReduction: the unpaid part of a walk-in return, which lowered what the order owes. */
         owedReduction?: number;
+        /**
+         * Mirrors `Return.freight`, written in the same transaction: the freight line a
+         * `purchase-withdrawal` return gave back, already inside `total`. Shown to the shopper as well
+         * (the money is theirs). ⚠️ Optional permanently: absent on every return that keeps the freight and on
+         * every summary written before it existed — read the RETURN row for those.
+         */
+        freight?: ReturnFreight;
         reason: ReturnReason;
         /**
          * Mirrors `Return.flow`, written in the same transaction. Operator-only:

package/dist/store.d.ts

@@ -298,7 +298,8 @@ declare global {
          * Platform switch for store-paid customer messaging (SMS today). `false`
          * or absent: no store-paid message is sent, and the app hides every store
          * messaging surface. App-only (`forwardToTenants: 'app'`), so absent from
-         * the storefront's unauthenticated response.
+         * the storefront's unauthenticated response: the storefront reads
+         * `Store.messagingAvailable` instead, which folds this switch in.
          */
         tenantMessagingEnabled?: boolean;
     }
@@ -634,6 +635,16 @@ declare global {
          * first such removal. No request body may set it.
          */
         adminRemovalGeneration?: number;
+        /**
+         * Web `GET /store` only, always a boolean on a 200: `true` when the
+         * `tenantMessagingEnabled` platform global is on and at least one
+         * `StoreMessageNotice` resolves on (`resolveStoreMessaging`). Computed when
+         * the route is read, never stored or writable. Not on `stores` frames or the
+         * preview frame, where absent reads `false`. Checkout hides «Avisarme por
+         * WhatsApp» when it is `false`, and a storefront opt-in sent while it is
+         * `false` is dropped.
+         */
+        messagingAvailable?: boolean;
         storeId: string;
         createdAt: number;
         /** Unix ms — BE-stamped on every `POST`/`PATCH /store` write. Always present on written rows. */
@@ -1417,7 +1428,15 @@ declare global {
     interface StoreIntegrations {
         afip?: Afip;
         mercadopago?: Mercadopago;
+        /**
+         * Per-store SMS entitlement and firma. Kept READABLE for migration: the
+         * app writes `messaging` instead, and `PATCH /store` still accepts `sms`
+         * for builds that have not moved. `messaging` never reads `sms.enabled`;
+         * it falls back to `sms.signature` only while its own `signature` is absent.
+         */
         sms?: SmsIntegration;
+        /** The store's customer-messaging settings — see `StoreMessagingIntegration`. */
+        messaging?: StoreMessagingIntegration;
         gmail?: Gmail;
         mercadolibre?: Mercadolibre;
         tiendanube?: Tiendanube;
@@ -1427,6 +1446,37 @@ declare global {
         enabled?: boolean;
         signature?: string;
     }
+    /**
+     * One store-paid customer message a store switches on or off — one of
+     * `STORE_MESSAGE_NOTICES`. Each maps to exactly one notice the api emits.
+     * `orderShipped` covers dispatch (shipped and delivered); `serviceOrderQuoted`
+     * covers the quote-sent notice and the `quoted` status fallback alike.
+     */
+    type StoreMessageNotice = 'orderReady' | 'orderShipped' | 'serviceOrderReceived' | 'serviceOrderQuoted' | 'serviceOrderApproved' | 'serviceOrderReady' | 'serviceOrderCancelled' | 'serviceOrderReturnedUnrepaired' | 'serviceOrderAbandoned' | 'serviceOrderOnHold' | 'serviceOrderResumed' | 'appointmentReminder' | 'paymentReminder';
+    /**
+     * `Store.integrations.messaging`. Written by `PATCH /store` only (ADMIN,
+     * SUPERVISOR, MANAGER; a PRINTER claim is refused), merged key by key, so a
+     * body naming one switch leaves the others as stored. An absent key reads
+     * its `STORE_MESSAGING_DEFAULTS` value: status notices and appointment
+     * reminders on, payment reminders off, `smsFallback` on. Read it through
+     * `resolveStoreMessaging`, never off the raw keys. Sending is gated by the
+     * `tenantMessagingEnabled` platform global as well.
+     */
+    interface StoreMessagingIntegration extends Partial<Record<StoreMessageNotice, boolean>> {
+        /** «Si WhatsApp falla, enviar por SMS». The SMS goes out only on a WhatsApp `failed`/`undelivered` status. */
+        smsFallback?: boolean;
+        /**
+         * Firma, at most 80 characters after trimming (the cap `sms.signature`
+         * has). Absent falls back to `sms.signature`; `''` means no firma.
+         */
+        signature?: string;
+    }
+    /** `resolveStoreMessaging`'s answer: every switch decided. */
+    interface ResolvedStoreMessaging extends Record<StoreMessageNotice, boolean> {
+        smsFallback: boolean;
+        /** Absent when neither `messaging.signature` nor `sms.signature` is stored. */
+        signature?: string;
+    }
     interface Gmail {
         connected?: boolean;
         senderEmail?: string;
@@ -1962,6 +2012,13 @@ declare global {
          * still broadcasts the row as it stands.
          */
         onboardingReviewAdd?: StoreOnboardingReviewArea[];
+        /**
+         * `PATCH /store` only (the closed `POST /store` refuses it
+         * `FIELD_NOT_WRITABLE_HERE`). Merged key by key over the stored leaf; an
+         * undeclared key is a 400. A plain USER is refused 403
+         * `STORE_MESSAGING_FORBIDDEN`.
+         */
+        messaging?: StoreMessagingIntegration;
     }
     /**
      * How the storefront offers a `paymentMethods` row — one of
@@ -2639,6 +2696,7 @@ export type StoreModuleRefusalBody = {
  * - `AFIP_RELACION_FLAG_FORBIDDEN` — `afip.wscdcEnabled` / `afip.fceEnabled`.
  * - `FX_TABLE_FORBIDDEN` — the `currencies` exchange-rate table.
  * - `FX_AUTO_UPDATE_FORBIDDEN` — `fxAutoUpdate`.
+ * - `STORE_MESSAGING_FORBIDDEN` — the `messaging` customer-messaging settings.
  *
  * Request refusals, `400`:
  * - `FIELD_NOT_WRITABLE_HERE` — a field written through `POST /store`, not
@@ -2694,7 +2752,7 @@ export type StoreModuleRefusalBody = {
  * checks, the display-currency lock, the storefront fence) are not listed
  * either. Cross-cutting refusals: check `GATING_ERROR_CODES` as well.
  */
-export declare const STORE_PATCH_ERROR_CODES: readonly ["STORE_CONFIG_FORBIDDEN", "STORE_ECOMMERCE_FORBIDDEN", "STORE_FISCAL_FIELD_FORBIDDEN", "STORE_JURISDICTION_FORBIDDEN", "AFIP_RELACION_FLAG_FORBIDDEN", "FX_TABLE_FORBIDDEN", "FX_AUTO_UPDATE_FORBIDDEN", "FIELD_NOT_WRITABLE_HERE", "AFIP_POINT_OF_SALE_NOT_CLEARABLE", "CURRENCY_CATALOG_ID_UNKNOWN", "ARS_RATE_MUST_BE_ONE", "CURRENCY_RATE_ABOVE_CEILING", "FX_CATALOG_ID_UNKNOWN", "FX_SOURCE_ID_UNKNOWN", "DISPLAY_CURRENCY_NOT_INVOICEABLE", "PRODUCT_CURRENCY_NOT_INVOICEABLE", "PRICE_LIST_NOT_FOUND", "DELIVERY_FEE_INVALID", "WHOLESALE_LIST_REQUIRED", "NET_PLUS_IVA_REQUIRES_RI", "DATA_FISCAL_URL_INVALID", "STORE_PUBLIC_HOST_MISSING", "FORBIDDEN", "STORE_NOT_FOUND"];
+export declare const STORE_PATCH_ERROR_CODES: readonly ["STORE_CONFIG_FORBIDDEN", "STORE_ECOMMERCE_FORBIDDEN", "STORE_FISCAL_FIELD_FORBIDDEN", "STORE_JURISDICTION_FORBIDDEN", "AFIP_RELACION_FLAG_FORBIDDEN", "FX_TABLE_FORBIDDEN", "FX_AUTO_UPDATE_FORBIDDEN", "FIELD_NOT_WRITABLE_HERE", "AFIP_POINT_OF_SALE_NOT_CLEARABLE", "CURRENCY_CATALOG_ID_UNKNOWN", "ARS_RATE_MUST_BE_ONE", "CURRENCY_RATE_ABOVE_CEILING", "FX_CATALOG_ID_UNKNOWN", "FX_SOURCE_ID_UNKNOWN", "DISPLAY_CURRENCY_NOT_INVOICEABLE", "PRODUCT_CURRENCY_NOT_INVOICEABLE", "PRICE_LIST_NOT_FOUND", "DELIVERY_FEE_INVALID", "WHOLESALE_LIST_REQUIRED", "NET_PLUS_IVA_REQUIRES_RI", "DATA_FISCAL_URL_INVALID", "STORE_PUBLIC_HOST_MISSING", "STORE_MESSAGING_FORBIDDEN", "FORBIDDEN", "STORE_NOT_FOUND"];
 export type StorePatchErrorCode = (typeof STORE_PATCH_ERROR_CODES)[number];
 /** Who pays the return shipping under a store's change-of-mind policy. */
 export declare const CHANGE_OF_MIND_RETURN_SHIPPING_PAYERS: readonly ["merchant", "shopper"];
@@ -2716,3 +2774,41 @@ declare global {
         refundAs: ChangeOfMindRefundAs;
     }
 }
+/**
+ * Every `StoreMessageNotice`, in the order the settings screen lists them —
+ * the keys `Store.integrations.messaging` switches. `UncoveredStoreMessageNotices`
+ * fails `typecheck` naming a notice the union gains and this tuple lacks.
+ */
+export declare const STORE_MESSAGE_NOTICES: readonly ["orderReady", "orderShipped", "serviceOrderReceived", "serviceOrderQuoted", "serviceOrderApproved", "serviceOrderReady", "serviceOrderCancelled", "serviceOrderReturnedUnrepaired", "serviceOrderAbandoned", "serviceOrderOnHold", "serviceOrderResumed", "appointmentReminder", "paymentReminder"];
+type AssertNoUncoveredStoreMessageNotice<T extends never> = T;
+export type UncoveredStoreMessageNotices = AssertNoUncoveredStoreMessageNotice<Exclude<StoreMessageNotice, (typeof STORE_MESSAGE_NOTICES)[number]>>;
+/**
+ * What an ABSENT `messaging` key reads: status notices and appointment
+ * reminders on, payment reminders off, the SMS fallback on.
+ */
+export declare const STORE_MESSAGING_DEFAULTS: {
+    readonly orderReady: true;
+    readonly orderShipped: true;
+    readonly serviceOrderReceived: true;
+    readonly serviceOrderQuoted: true;
+    readonly serviceOrderApproved: true;
+    readonly serviceOrderReady: true;
+    readonly serviceOrderCancelled: true;
+    readonly serviceOrderReturnedUnrepaired: true;
+    readonly serviceOrderAbandoned: true;
+    readonly serviceOrderOnHold: true;
+    readonly serviceOrderResumed: true;
+    readonly appointmentReminder: true;
+    readonly paymentReminder: false;
+    readonly smsFallback: true;
+};
+/** The firma cap — the same one `sms.signature` has. */
+export declare const STORE_MESSAGING_SIGNATURE_MAX = 80;
+/**
+ * Every switch of a store's messaging settings, decided: per key, the stored
+ * boolean, else its `STORE_MESSAGING_DEFAULTS` value (a stored non-boolean
+ * reads as absent). `signature` falls back to `sms.signature` only when
+ * `messaging.signature` is absent; a stored `''` is kept and means no firma.
+ */
+export declare const resolveStoreMessaging: (integrations: Pick<StoreIntegrations, "messaging" | "sms"> | undefined) => ResolvedStoreMessaging;
+export {};

package/dist/store.js

@@ -114,6 +114,7 @@ export const STORE_MODULE_ERROR_CODES = [
  * - `AFIP_RELACION_FLAG_FORBIDDEN` — `afip.wscdcEnabled` / `afip.fceEnabled`.
  * - `FX_TABLE_FORBIDDEN` — the `currencies` exchange-rate table.
  * - `FX_AUTO_UPDATE_FORBIDDEN` — `fxAutoUpdate`.
+ * - `STORE_MESSAGING_FORBIDDEN` — the `messaging` customer-messaging settings.
  *
  * Request refusals, `400`:
  * - `FIELD_NOT_WRITABLE_HERE` — a field written through `POST /store`, not
@@ -192,6 +193,7 @@ export const STORE_PATCH_ERROR_CODES = [
     'NET_PLUS_IVA_REQUIRES_RI',
     'DATA_FISCAL_URL_INVALID',
     'STORE_PUBLIC_HOST_MISSING',
+    'STORE_MESSAGING_FORBIDDEN',
     'FORBIDDEN',
     'STORE_NOT_FOUND',
 ];
@@ -203,3 +205,62 @@ export const CHANGE_OF_MIND_REFUND_AS = ['refund', 'store-credit'];
 export const CHANGE_OF_MIND_RETURN_DAYS_MAX = 365;
 /** The source of a change-of-mind deadline: the store's own setting, not a statutory row. */
 export const CHANGE_OF_MIND_WINDOW_SOURCE = 'store:changeOfMindReturns';
+/**
+ * Every `StoreMessageNotice`, in the order the settings screen lists them —
+ * the keys `Store.integrations.messaging` switches. `UncoveredStoreMessageNotices`
+ * fails `typecheck` naming a notice the union gains and this tuple lacks.
+ */
+export const STORE_MESSAGE_NOTICES = [
+    'orderReady',
+    'orderShipped',
+    'serviceOrderReceived',
+    'serviceOrderQuoted',
+    'serviceOrderApproved',
+    'serviceOrderReady',
+    'serviceOrderCancelled',
+    'serviceOrderReturnedUnrepaired',
+    'serviceOrderAbandoned',
+    'serviceOrderOnHold',
+    'serviceOrderResumed',
+    'appointmentReminder',
+    'paymentReminder',
+];
+/**
+ * What an ABSENT `messaging` key reads: status notices and appointment
+ * reminders on, payment reminders off, the SMS fallback on.
+ */
+export const STORE_MESSAGING_DEFAULTS = {
+    orderReady: true,
+    orderShipped: true,
+    serviceOrderReceived: true,
+    serviceOrderQuoted: true,
+    serviceOrderApproved: true,
+    serviceOrderReady: true,
+    serviceOrderCancelled: true,
+    serviceOrderReturnedUnrepaired: true,
+    serviceOrderAbandoned: true,
+    serviceOrderOnHold: true,
+    serviceOrderResumed: true,
+    appointmentReminder: true,
+    paymentReminder: false,
+    smsFallback: true,
+};
+/** The firma cap — the same one `sms.signature` has. */
+export const STORE_MESSAGING_SIGNATURE_MAX = 80;
+/**
+ * Every switch of a store's messaging settings, decided: per key, the stored
+ * boolean, else its `STORE_MESSAGING_DEFAULTS` value (a stored non-boolean
+ * reads as absent). `signature` falls back to `sms.signature` only when
+ * `messaging.signature` is absent; a stored `''` is kept and means no firma.
+ */
+export const resolveStoreMessaging = (integrations) => {
+    const leaf = integrations?.messaging;
+    const resolved = { ...STORE_MESSAGING_DEFAULTS };
+    for (const key of [...STORE_MESSAGE_NOTICES, 'smsFallback']) {
+        const stored = leaf?.[key];
+        if (typeof stored === 'boolean')
+            resolved[key] = stored;
+    }
+    const signature = typeof leaf?.signature === 'string' ? leaf.signature : integrations?.sms?.signature;
+    return typeof signature === 'string' ? { ...resolved, signature } : resolved;
+};

package/dist/subscription.d.ts

@@ -100,7 +100,7 @@ declare global {
      * exhausts this union (a `switch`, a `Record<FeatureKey, …>`) still has to
      * handle the new member in the same change.
      */
-    type FeatureKey = 'maxOrdersMonth' | 'maxInvoicesMonth' | 'maxProducts' | 'maxUsers' | 'maxCustomers' | 'maxWarehouses' | 'priceListsMax' | 'webhooks' | 'afipInvoicing' | 'suppliers' | 'domesticPayments' | 'stripePayments' | 'cashManagement' | 'importExport' | 'advancedReports' | 'customBranding' | 'prioritySupport' | 'aiFeatures' | 'mobileApp' | 'customDomain' | 'advancedPricing' | 'marketplaceChannels' | 'storefront' | 'loyalty' | 'marketing' | 'mandatory2fa';
+    type FeatureKey = 'maxOrdersMonth' | 'maxInvoicesMonth' | 'maxProducts' | 'maxUsers' | 'maxCustomers' | 'maxWarehouses' | 'priceListsMax' | 'webhooks' | 'monthlyMessageAllowance' | 'afipInvoicing' | 'suppliers' | 'domesticPayments' | 'stripePayments' | 'cashManagement' | 'importExport' | 'advancedReports' | 'customBranding' | 'prioritySupport' | 'aiFeatures' | 'mobileApp' | 'customDomain' | 'advancedPricing' | 'marketplaceChannels' | 'storefront' | 'loyalty' | 'marketing' | 'mandatory2fa';
     /** Resolved entitlements for a specific tenant (matrix + overrides applied). */
     type ResolvedEntitlements = Record<FeatureKey, Entitlement>;
     /**
@@ -1238,7 +1238,7 @@ export declare const isPaidPlanTier: (value: unknown) => value is PaidPlanTier;
  * 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", "aiFeatures", "mobileApp", "customBranding", "customDomain", "prioritySupport", "advancedPricing", "marketplaceChannels", "storefront", "loyalty", "marketing", "mandatory2fa", "maxUsers", "maxProducts", "maxCustomers", "maxWarehouses", "priceListsMax", "webhooks", "maxOrdersMonth", "maxInvoicesMonth"];
+export declare const FEATURE_KEYS: readonly ["afipInvoicing", "suppliers", "advancedReports", "cashManagement", "importExport", "domesticPayments", "stripePayments", "aiFeatures", "mobileApp", "customBranding", "customDomain", "prioritySupport", "advancedPricing", "marketplaceChannels", "storefront", "loyalty", "marketing", "mandatory2fa", "maxUsers", "maxProducts", "maxCustomers", "maxWarehouses", "priceListsMax", "webhooks", "maxOrdersMonth", "maxInvoicesMonth", "monthlyMessageAllowance"];
 type AssertNoUncoveredFeatureKey<T extends never> = T;
 export type UncoveredFeatureKeys = AssertNoUncoveredFeatureKey<Exclude<FeatureKey, (typeof FEATURE_KEYS)[number]>>;
 export {};

package/dist/subscription.js

@@ -128,4 +128,5 @@ export const FEATURE_KEYS = [
     'webhooks',
     'maxOrdersMonth',
     'maxInvoicesMonth',
+    'monthlyMessageAllowance',
 ];

package/package.json

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