sinfactura-types 1.10.310 → 1.10.312

package/dist/cart.d.ts

@@ -67,6 +67,18 @@ declare global {
          * redemption. See `CartCoupon`.
          */
         coupon?: CartCoupon;
+        /**
+         * The promotion this cart carries, if any — at most one. Applied by
+         * `applyPromotion`, cleared by `removePromotion`, and, like the coupon,
+         * holding it is not a redemption. See {@link CartPromotion}.
+         */
+        promotion?: CartPromotion;
+        /**
+         * What `promotion` came to on this cart's current lines, re-derived on
+         * every write. Absent when no promotion is applied. See
+         * {@link CartPromotionEffect}.
+         */
+        promotionEffect?: CartPromotionEffect;
         /**
          * The CART-LEVEL cut this coupon produced, re-derived on every write from
          * `coupon`'s frozen grant against the current subtotal. Absent when no
@@ -410,6 +422,89 @@ declare global {
          */
         maxDiscountAmount?: number;
     }
+    /**
+     * The promotion a cart currently carries — the granted TERMS, frozen at
+     * apply time, exactly as {@link CartCoupon} freezes a coupon's.
+     *
+     * ⚠️ The terms are frozen, not a reference to the `Promotion` row, and
+     * for the same reason the coupon's are: a promotion the merchant edits or
+     * ends after a shopper applied it keeps working for that cart until checkout
+     * re-validates. Re-reading the row on every cart write would reprice a
+     * shopper mid-session from a change they never saw.
+     *
+     * ⚠️ A cart carries at most ONE of these, the same single slot the
+     * coupon has. Stacking two promotions of the same type on one cart is a
+     * question nobody has answered — what a second buy-2-get-1 does to units
+     * the first already rewarded has no obvious right answer — so applying one
+     * over another REPLACES it rather than quietly compounding a cut. When that
+     * question is answered, this becomes a list and the replace becomes an
+     * append; until then a single slot is the shape that cannot pay out twice
+     * for the same unit.
+     *
+     * ⚠️ `'coupon'` is absent from the union on purpose. A coupon promotion's
+     * money lives in the `Coupon` row, reaches the cart through `applyCoupon`,
+     * and sits in `Cart.coupon` — a cart that could hold it here as well would
+     * have two places to disagree about one cut.
+     */
+    type CartPromotion = {
+        promotionId: string;
+        /** The promotion's name at apply time, so a receipt can say what was given. */
+        name: string;
+        /** When the shopper applied it. */
+        appliedAt: number;
+    } & ({
+        type: 'buyXGetY';
+        buyXGetY: BuyXGetYTerms;
+    } | {
+        type: 'freeShipping';
+        freeShipping: FreeShippingTerms;
+    } | {
+        type: 'bundle';
+        bundle: BundleTerms;
+    });
+    /**
+     * What the frozen {@link CartPromotion} actually came to on THIS cart —
+     * re-derived on every write, never stored as the answer.
+     *
+     * ⚠️ Server-owned, like {@link CartDiscount}'s `amount`. The client may
+     * read it and must never send it: it is a function of the cart's current
+     * lines and their current prices, so a client-supplied value is a claim about
+     * money the server is about to recompute anyway.
+     */
+    interface CartPromotionEffect {
+        promotionId: string;
+        type: 'buyXGetY' | 'freeShipping' | 'bundle';
+        /**
+         * The DERIVED cut, in currency units, already included in
+         * `CartTotals.discount`.
+         *
+         * ⚠️ ALWAYS `0` for `'freeShipping'`, and that is the invariant, not
+         * an accident of the current numbers. Free shipping is not a discount —
+         * it zeroes `CartTotals.shipping`, which is a different term of the
+         * `grandTotal` formula. A free-shipping promotion that ever contributed
+         * here would be cutting the merchandise price for a delivery the merchant
+         * agreed to absorb, and the comprobante would discriminate a discount the
+         * customer was never given on the goods.
+         */
+        amount: number;
+        /**
+         * How many times the promotion applied. `1` for a promotion that has no
+         * repeat notion (`'freeShipping'`), and `0` when the cart carries the
+         * promotion but no longer qualifies — a shopper who applied a buy-2-get-1
+         * and then removed a line keeps the frozen grant and earns nothing by it.
+         */
+        applications: number;
+        /**
+         * Whether this promotion waives the cart's shipping.
+         *
+         * ⚠️ `CartTotals.shipping` is structurally `0` today — nothing in the
+         * api computes a shipping cost yet, by design, because it is chosen at
+         * checkout. So the waiver currently changes no money, and this flag is the
+         * only place the GRANT survives to be read by whoever lands the shipping
+         * quote. Do not read its absence as "shipping was charged".
+         */
+        shippingWaived?: boolean;
+    }
     /**
      * A redeemable coupon. `PK: COUPON#{storeId}`, `SK: <normalized code>`.
      *
@@ -622,7 +717,7 @@ declare global {
      *   at the DynamoDB marshaller instead of at validation.
      * - `merge.items` is `min(1).max(50)`.
      */
-    type CartActionRequest = CartActionAddLine | CartActionChangeQuantity | CartActionRemoveLine | CartActionClear | CartActionMerge | CartActionSaveLine | CartActionRestoreLine | CartActionRemoveSavedLine | CartActionApplyCoupon | CartActionRemoveCoupon | CartActionSetLineDiscount;
+    type CartActionRequest = CartActionAddLine | CartActionChangeQuantity | CartActionRemoveLine | CartActionClear | CartActionMerge | CartActionSaveLine | CartActionRestoreLine | CartActionRemoveSavedLine | CartActionApplyCoupon | CartActionRemoveCoupon | CartActionApplyPromotion | CartActionRemovePromotion | CartActionSetLineDiscount;
     /**
      * Fields common to every action.
      *
@@ -897,6 +992,35 @@ declare global {
     interface CartActionRemoveCoupon extends CartActionBase {
         mode: 'removeCoupon';
     }
+    /**
+     * Applies a promotion to the cart by id.
+     *
+     * ⚠️ A cart holds AT MOST ONE promotion. Applying a second REPLACES the
+     * first rather than stacking — the same rule, and the same reason, as
+     * {@link CartActionApplyCoupon}: nothing in the request says what a second
+     * buy-2-get-1 does to units the first already rewarded.
+     *
+     * ⚠️ The action names an ID and nothing else. Every term comes off the
+     * `Promotion` row, so a client cannot name its own cut.
+     *
+     * ⚠️ A promotion and a coupon can BOTH be on one cart. They are separate
+     * slots and both cuts land in `CartTotals.discount`, which is clamped at the
+     * subtotal — so the two together can take the cart to zero but never below.
+     */
+    interface CartActionApplyPromotion extends CartActionBase {
+        mode: 'applyPromotion';
+        promotionId: string;
+    }
+    /**
+     * Clears the cart's promotion and its derived effect.
+     *
+     * A cart carrying no promotion is a no-op `200`, matching every other removal
+     * verb here. Nothing is released, because a promotion has no redemption
+     * counter to consume in the first place.
+     */
+    interface CartActionRemovePromotion extends CartActionBase {
+        mode: 'removePromotion';
+    }
     /**
      * Sets or clears ONE line's discount — the operator's per-line cut.
      *

package/dist/cjs/marketing.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUTOMATION_RULE_STATUSES = exports.AUTOMATION_SEND_STATUSES = exports.ATTRIBUTION_WINDOW_HOURS = exports.RFM_SEGMENT_LABELS = exports.AUTOMATION_TRIGGERS = void 0;
+exports.CART_APPLICABLE_PROMOTION_TYPES = exports.PROMOTION_TYPES = exports.AUTOMATION_RULE_STATUSES = exports.AUTOMATION_SEND_STATUSES = exports.ATTRIBUTION_WINDOW_HOURS = exports.RFM_SEGMENT_LABELS = exports.AUTOMATION_TRIGGERS = void 0;
 /**
  * The {@link AutomationTrigger} vocabulary as a RUNTIME value, so the api's Zod
  * enum, the configuration screen's picker and the published union all derive
@@ -70,3 +70,31 @@ exports.AUTOMATION_RULE_STATUSES = [
     'active',
     'archived',
 ];
+/**
+ * {@link PromotionType} as a runtime value — see {@link AUTOMATION_TRIGGERS}.
+ *
+ * ⚠️ `'coupon'` is in the tuple even though a row may express it by carrying
+ * no `type` at all. The tuple is the vocabulary a writer may DECLARE; the absent
+ * spelling is a reader's concern, and conflating the two is how a CRUD schema
+ * comes to reject the one value every legacy row means.
+ */
+exports.PROMOTION_TYPES = [
+    'coupon',
+    'buyXGetY',
+    'freeShipping',
+    'bundle',
+];
+/**
+ * The promotion types a CART can freeze onto itself — every type but `'coupon'`.
+ *
+ * ⚠️ `'coupon'` is excluded on purpose, and not for tidiness. A coupon
+ * promotion's money lives in the `Coupon` row its `couponCode` names, and that
+ * row already reaches the cart through `applyCoupon` and sits in `Cart.coupon`.
+ * Letting it also occupy the promotion slot would give one cart two places to
+ * disagree about the same cut.
+ */
+exports.CART_APPLICABLE_PROMOTION_TYPES = [
+    'buyXGetY',
+    'freeShipping',
+    'bundle',
+];

package/dist/cjs/notification.js

@@ -7,9 +7,14 @@ exports.NotificationTypeEnum = void 0;
 // Stripe hook, propagate-fx). Exported as a real enum so `api`
 // (stacks/helpers/notificationType.ts) and `app`
 // (src/domain/notificationType.ts) can drop their hand-mirrored copies
-// in follow-ups. DOLARBNA / ERROR / AFIP_CERT_EXPIRY have no User-row
-// read path — enum members only (AFIP_CERT_EXPIRY = the cert-expiry
-// alert type).
+// in follow-ups. DOLARBNA / ERROR / ML_FACTURADOR_COLLISION have no
+// User-row read path — enum members only. AFIP_CERT_EXPIRY (the
+// cert-expiry alert type) was in that list and no longer belongs to it:
+// `createStore` seeds it on the founding user and `afipCertMonitor`
+// reads `getNotificationSubscribers` for it, so it is an ordinary opt-in
+// key. Which members are opt-in is not cosmetic — it decides whether a
+// producer may read subscribers at all, and a member seeded nowhere that
+// does so fans out to an empty list on every store.
 var NotificationTypeEnum;
 (function (NotificationTypeEnum) {
     NotificationTypeEnum["ORDER"] = "ORDER";
@@ -23,6 +28,27 @@ var NotificationTypeEnum;
     // ML order-ingestion fanout — User-row read path
     // added by the orders_v2 worker.
     NotificationTypeEnum["MERCADOLIBRE"] = "MERCADOLIBRE";
+    /**
+     * A fiscal-document upload that failed with a signal saying the pack
+     * already carries one — the tenant's own Mercado Libre Facturador is
+     * probably active and issuing invoices against the same orders we are.
+     *
+     * ⚠️ Additive, on the same grounds as `ABANDONED_CART`:
+     * `UserNotifications` is `Partial<Record<NotificationTypeEnum, boolean>>`,
+     * so every existing preferences row stays valid and an absent key already
+     * reads as "not opted in". No consumer migration is owed.
+     *
+     * ⚠️ **No User-row read path, deliberately — the `ERROR` / `DOLARBNA`
+     * category, not the opt-in one.** Two independent reasons, and the second
+     * is the one that bites: a collision means invoices may be issued twice
+     * against one order, which no tenant would sensibly hold an opt-out for;
+     * and a NEW key is seeded nowhere, so an opt-in read path would deliver it
+     * to nobody. `createStore`'s `FOUNDING_USER_NOTIFICATIONS` is a fixed
+     * seven-key literal written to the founding user alone, and this repo is
+     * forward-only — no backfill will ever add this key to an existing row.
+     * The producer therefore fans out to every ADMIN of the store.
+     */
+    NotificationTypeEnum["ML_FACTURADOR_COLLISION"] = "ML_FACTURADOR_COLLISION";
     // Stock alerts — fired when a sale crosses a product's stock
     // threshold. LOW_STOCK at stock <= `Product.minStock`; OUT_OF_STOCK at
     // stock <= 0. Both have User-row opt-in read paths.

package/dist/cjs/webhook.js

@@ -70,6 +70,7 @@ exports.WEBHOOK_EVENT_TYPES = [
     'product.stock_low',
     'product.stock_out',
     'order.created',
+    'order.status_changed',
     'invoice.generated',
 ];
 /** Terminal outcomes for a print job. Closed union — a job printed, or it failed. */
@@ -80,8 +81,16 @@ exports.PRINT_JOB_SETTLED_OUTCOMES = ['printed', 'failed'];
  * ⚠️ A CLOSED union, and rule 1 above applies to it with full force: a fifth
  * order-minting path cannot be added here without breaking every subscriber
  * that switches exhaustively — it mints `order.created.v2` instead. The four
- * members are the complete set of paths that write an ORDER row today, each
- * verified at its own post-commit fan-out, not a sample.
+ * members are the paths that EMIT — which is no longer the same thing as the
+ * paths that WRITE an ORDER row.
+ *
+ * ⚠️ Converting an approved presupuesto (`convertPresupuestoToOrder`) mints an
+ * ordinary order through the same `createOrder` every member above uses, and
+ * emits nothing here — precisely BECAUSE adding a fifth member is the breaking
+ * change the paragraph above forbids. The gap is known and deliberate, not an
+ * oversight to be tidied: do not close it by quietly widening this tuple. The
+ * rest of that path's fan-out (stock webhooks, notifications, the ML push) does
+ * run; it is only this event that waits on the v2 decision.
  *
  * `service_delivery` is the repair-shop handover: a `ready` → `delivered`
  * transition mints an ordinary sale out of the counter lines the operator

package/dist/marketing.d.ts

@@ -221,25 +221,155 @@ declare global {
         updatedAt?: number;
     }
     /**
-     * A marketing wrapper around a coupon that already exists.
+     * How a promotion cuts money — the discriminant on {@link Promotion}.
      *
-     * ⚠️ It carries NO discount mechanics of its own. `couponCode` is the only
-     * link, and every money field — type, value, minimum subtotal, cap, currency
-     * — stays owned by `Coupon`. A second place that can disagree with the
-     * coupon on terms is a second answer to "what did the customer actually get".
+     * ⚠️ `'coupon'` is the ABSENT value, not merely the first one. Every row
+     * written before this union existed carries no `type` at all, and
+     * forward-only means none of them is ever rewritten — so a reader that asks
+     * `promotion.type === 'coupon'` gets `false` on every one of them.
+     *
+     * ⚠️ The move, for EVERY consumer of this package, is `promotion.type ??
+     * 'coupon'` — or a `switch` whose `default` arm is the coupon arm. The api
+     * has a `promotionType()` (`stacks/services/promotions.ts`) that does exactly
+     * this, but it lives under `stacks/` and nothing importing these types can
+     * reach it: it is named here so a reader stops looking for it, not so one
+     * goes hunting.
      */
-    interface Promotion {
+    type PromotionType = 'coupon' | 'buyXGetY' | 'freeShipping' | 'bundle';
+    /** What every promotion carries, whatever it does to the money. */
+    interface PromotionBase {
         storeId: string;
         promotionId: string;
         name: string;
-        /** FK into the existing `Coupon` entity. */
-        couponCode?: string;
         status: 'draft' | 'active' | 'ended';
         startsAt?: number;
         endsAt?: number;
         createdAt: number;
         updatedAt?: number;
     }
+    /**
+     * A marketing wrapper around a coupon that already exists — the original
+     * shape, and the one every unmigrated row still has.
+     *
+     * ⚠️ It carries NO discount mechanics of its own. `couponCode` is the only
+     * link, and every money field — type, value, minimum subtotal, cap, currency
+     * — stays owned by `Coupon`. A second place that can disagree with the
+     * coupon on terms is a second answer to "what did the customer actually get".
+     *
+     * ⚠️ This variant's discriminant is OPTIONAL, and it is the only one that
+     * is. That is what keeps every pre-union row readable with no migration, and
+     * it is why narrowing reaches this arm through a `switch`'s `default` rather
+     * than through `case 'coupon'`.
+     */
+    interface CouponPromotion extends PromotionBase {
+        type?: 'coupon';
+        /** FK into the existing `Coupon` entity. */
+        couponCode?: string;
+    }
+    /**
+     * "Buy X, get Y" — a quantity of one product arms a cut on another.
+     *
+     * ⚠️ The reward is a PERCENT, never money, for the same reason
+     * {@link CartDiscount} carries the grant and not the cut: it is re-derived on
+     * every cart write against the unit price the rewarded line actually has at
+     * that moment, which moves whenever a quantity break re-resolves `basePrice`.
+     * A frozen money amount would keep paying out the price the cart had when the
+     * shopper applied it.
+     */
+    interface BuyXGetYTerms {
+        /** The product whose quantity ARMS the promotion. */
+        buyProductId: string;
+        /** How many units of `buyProductId` one application consumes. At least 1. */
+        buyQuantity: number;
+        /** The product the reward is taken on. May be the same as `buyProductId`. */
+        getProductId: string;
+        /** How many units of `getProductId` one application rewards. At least 1. */
+        getQuantity: number;
+        /**
+         * The cut on the rewarded units, as a percent of their line's unit price.
+         * `100` is the plain "get one free" shape; `50` is "get one half price".
+         */
+        getDiscountPercent: number;
+        /**
+         * How many times one cart may apply this promotion. Absent means as often
+         * as the cart's own quantities allow.
+         */
+        maxApplications?: number;
+    }
+    /**
+     * What a bundle charges once its members are all present.
+     *
+     * ⚠️ A discriminated pair rather than two optional fields, because "both
+     * set" and "neither set" are both unanswerable at money time and neither
+     * should be representable. The CRUD schema does not have to refuse a shape
+     * the type cannot express.
+     */
+    type BundlePricing = {
+        mode: 'fixedPrice';
+        /** What the whole bundle costs, in the cart's currency. */
+        amount: number;
+    } | {
+        mode: 'percentOff';
+        /** The cut on the summed member lines, as a percent. */
+        percent: number;
+    };
+    /** A set of products that, bought together, price as one. */
+    interface BundleTerms {
+        /**
+         * Every product that must be present, at one unit each, for a single
+         * application. Order is not significant.
+         */
+        productIds: readonly string[];
+        pricing: BundlePricing;
+        /**
+         * How many times one cart may apply this bundle. Absent means as often as
+         * the cart's own quantities allow.
+         */
+        maxApplications?: number;
+    }
+    /**
+     * When shipping is waived.
+     *
+     * ⚠️ Eligibility ONLY — there is deliberately no money field here.
+     * Free shipping does not grant a discount, it zeroes a total the cart already
+     * carries, so a value on this object would be a second, disagreeing answer to
+     * what the shipping costs.
+     */
+    interface FreeShippingTerms {
+        /** The cart subtotal that qualifies. Absent means any subtotal does. */
+        minSubtotal?: number;
+        /**
+         * At least one of these products must be on the cart. Absent means any
+         * cart qualifies.
+         */
+        productIds?: readonly string[];
+    }
+    interface BuyXGetYPromotion extends PromotionBase {
+        type: 'buyXGetY';
+        buyXGetY: BuyXGetYTerms;
+    }
+    interface FreeShippingPromotion extends PromotionBase {
+        type: 'freeShipping';
+        freeShipping: FreeShippingTerms;
+    }
+    interface BundlePromotion extends PromotionBase {
+        type: 'bundle';
+        bundle: BundleTerms;
+    }
+    /**
+     * A promotion a store runs — one of four mechanics, discriminated on `type`.
+     *
+     * ⚠️ Each variant carries its terms under a key NAMED FOR ITS TYPE
+     * (`buyXGetY`, `freeShipping`, `bundle`) rather than a shared `terms` key.
+     * That is what lets the union narrow: a shared key would have to be the union
+     * of every terms shape, so a `bundle` row could typecheck while carrying
+     * buy-X-get-Y terms and nothing but a runtime check would object.
+     *
+     * ⚠️ The `'coupon'` variant is the ONLY one whose money lives elsewhere
+     * — in the `Coupon` row its `couponCode` names. The other three carry their
+     * own mechanics, and are the only three a cart can freeze onto itself.
+     */
+    type Promotion = CouponPromotion | BuyXGetYPromotion | FreeShippingPromotion | BundlePromotion;
     /**
      * What arms an {@link AutomationRule} — the SIGNAL a rule listens for.
      *
@@ -724,4 +854,23 @@ export declare const ATTRIBUTION_WINDOW_HOURS = 72;
 export declare const AUTOMATION_SEND_STATUSES: readonly ["queued", "sent", "failed", "skipped"];
 /** {@link AutomationRuleStatus} as a runtime value — see {@link AUTOMATION_TRIGGERS}. */
 export declare const AUTOMATION_RULE_STATUSES: readonly ["paused", "active", "archived"];
+/**
+ * {@link PromotionType} as a runtime value — see {@link AUTOMATION_TRIGGERS}.
+ *
+ * ⚠️ `'coupon'` is in the tuple even though a row may express it by carrying
+ * no `type` at all. The tuple is the vocabulary a writer may DECLARE; the absent
+ * spelling is a reader's concern, and conflating the two is how a CRUD schema
+ * comes to reject the one value every legacy row means.
+ */
+export declare const PROMOTION_TYPES: readonly ["coupon", "buyXGetY", "freeShipping", "bundle"];
+/**
+ * The promotion types a CART can freeze onto itself — every type but `'coupon'`.
+ *
+ * ⚠️ `'coupon'` is excluded on purpose, and not for tidiness. A coupon
+ * promotion's money lives in the `Coupon` row its `couponCode` names, and that
+ * row already reaches the cart through `applyCoupon` and sits in `Cart.coupon`.
+ * Letting it also occupy the promotion slot would give one cart two places to
+ * disagree about the same cut.
+ */
+export declare const CART_APPLICABLE_PROMOTION_TYPES: readonly ["buyXGetY", "freeShipping", "bundle"];
 export {};

package/dist/marketing.js

@@ -67,3 +67,31 @@ export const AUTOMATION_RULE_STATUSES = [
     'active',
     'archived',
 ];
+/**
+ * {@link PromotionType} as a runtime value — see {@link AUTOMATION_TRIGGERS}.
+ *
+ * ⚠️ `'coupon'` is in the tuple even though a row may express it by carrying
+ * no `type` at all. The tuple is the vocabulary a writer may DECLARE; the absent
+ * spelling is a reader's concern, and conflating the two is how a CRUD schema
+ * comes to reject the one value every legacy row means.
+ */
+export const PROMOTION_TYPES = [
+    'coupon',
+    'buyXGetY',
+    'freeShipping',
+    'bundle',
+];
+/**
+ * The promotion types a CART can freeze onto itself — every type but `'coupon'`.
+ *
+ * ⚠️ `'coupon'` is excluded on purpose, and not for tidiness. A coupon
+ * promotion's money lives in the `Coupon` row its `couponCode` names, and that
+ * row already reaches the cart through `applyCoupon` and sits in `Cart.coupon`.
+ * Letting it also occupy the promotion slot would give one cart two places to
+ * disagree about the same cut.
+ */
+export const CART_APPLICABLE_PROMOTION_TYPES = [
+    'buyXGetY',
+    'freeShipping',
+    'bundle',
+];

package/dist/notification.d.ts

@@ -8,6 +8,27 @@ export declare enum NotificationTypeEnum {
     ERROR = "ERROR",
     AFIP_CERT_EXPIRY = "AFIP_CERT_EXPIRY",
     MERCADOLIBRE = "MERCADOLIBRE",
+    /**
+     * A fiscal-document upload that failed with a signal saying the pack
+     * already carries one — the tenant's own Mercado Libre Facturador is
+     * probably active and issuing invoices against the same orders we are.
+     *
+     * ⚠️ Additive, on the same grounds as `ABANDONED_CART`:
+     * `UserNotifications` is `Partial<Record<NotificationTypeEnum, boolean>>`,
+     * so every existing preferences row stays valid and an absent key already
+     * reads as "not opted in". No consumer migration is owed.
+     *
+     * ⚠️ **No User-row read path, deliberately — the `ERROR` / `DOLARBNA`
+     * category, not the opt-in one.** Two independent reasons, and the second
+     * is the one that bites: a collision means invoices may be issued twice
+     * against one order, which no tenant would sensibly hold an opt-out for;
+     * and a NEW key is seeded nowhere, so an opt-in read path would deliver it
+     * to nobody. `createStore`'s `FOUNDING_USER_NOTIFICATIONS` is a fixed
+     * seven-key literal written to the founding user alone, and this repo is
+     * forward-only — no backfill will ever add this key to an existing row.
+     * The producer therefore fans out to every ADMIN of the store.
+     */
+    ML_FACTURADOR_COLLISION = "ML_FACTURADOR_COLLISION",
     LOW_STOCK = "LOW_STOCK",
     OUT_OF_STOCK = "OUT_OF_STOCK",
     SUPPORT = "SUPPORT",

package/dist/notification.js

@@ -4,9 +4,14 @@
 // Stripe hook, propagate-fx). Exported as a real enum so `api`
 // (stacks/helpers/notificationType.ts) and `app`
 // (src/domain/notificationType.ts) can drop their hand-mirrored copies
-// in follow-ups. DOLARBNA / ERROR / AFIP_CERT_EXPIRY have no User-row
-// read path — enum members only (AFIP_CERT_EXPIRY = the cert-expiry
-// alert type).
+// in follow-ups. DOLARBNA / ERROR / ML_FACTURADOR_COLLISION have no
+// User-row read path — enum members only. AFIP_CERT_EXPIRY (the
+// cert-expiry alert type) was in that list and no longer belongs to it:
+// `createStore` seeds it on the founding user and `afipCertMonitor`
+// reads `getNotificationSubscribers` for it, so it is an ordinary opt-in
+// key. Which members are opt-in is not cosmetic — it decides whether a
+// producer may read subscribers at all, and a member seeded nowhere that
+// does so fans out to an empty list on every store.
 export var NotificationTypeEnum;
 (function (NotificationTypeEnum) {
     NotificationTypeEnum["ORDER"] = "ORDER";
@@ -20,6 +25,27 @@ export var NotificationTypeEnum;
     // ML order-ingestion fanout — User-row read path
     // added by the orders_v2 worker.
     NotificationTypeEnum["MERCADOLIBRE"] = "MERCADOLIBRE";
+    /**
+     * A fiscal-document upload that failed with a signal saying the pack
+     * already carries one — the tenant's own Mercado Libre Facturador is
+     * probably active and issuing invoices against the same orders we are.
+     *
+     * ⚠️ Additive, on the same grounds as `ABANDONED_CART`:
+     * `UserNotifications` is `Partial<Record<NotificationTypeEnum, boolean>>`,
+     * so every existing preferences row stays valid and an absent key already
+     * reads as "not opted in". No consumer migration is owed.
+     *
+     * ⚠️ **No User-row read path, deliberately — the `ERROR` / `DOLARBNA`
+     * category, not the opt-in one.** Two independent reasons, and the second
+     * is the one that bites: a collision means invoices may be issued twice
+     * against one order, which no tenant would sensibly hold an opt-out for;
+     * and a NEW key is seeded nowhere, so an opt-in read path would deliver it
+     * to nobody. `createStore`'s `FOUNDING_USER_NOTIFICATIONS` is a fixed
+     * seven-key literal written to the founding user alone, and this repo is
+     * forward-only — no backfill will ever add this key to an existing row.
+     * The producer therefore fans out to every ADMIN of the store.
+     */
+    NotificationTypeEnum["ML_FACTURADOR_COLLISION"] = "ML_FACTURADOR_COLLISION";
     // Stock alerts — fired when a sale crosses a product's stock
     // threshold. LOW_STOCK at stock <= `Product.minStock`; OUT_OF_STOCK at
     // stock <= 0. Both have User-row opt-in read paths.

package/dist/store.d.ts

@@ -713,6 +713,33 @@ declare global {
          * `Mercadopago.expiresAt` is.
          */
         accessTokenExpiresAt?: number;
+        /**
+         * unix ms of the last SUCCESSFUL connect-time send verification
+         * (`POST /gmail/test-send`) — the tenant asked us to prove the send path
+         * works, and it did.
+         *
+         * ⚠️ **Written on SUCCESS ONLY, and there is deliberately no
+         * `lastFailedAt` sibling.** A failure is a transient condition the
+         * operator is already looking at; persisting it invites a screen that
+         * renders stale alarm about a problem reconnecting fixed five minutes
+         * later. This stays a FRESHNESS signal — `status` already carries status,
+         * and two representations of status is how they drift.
+         *
+         * ⚠️ **Absent means "never verified", NEVER "verification failed".** The
+         * platform is forward-only and never backfills, so every tenant who
+         * connected before this shipped reads as absent. A consumer rendering
+         * absence as an error state puts a red badge on all of them.
+         *
+         * ⚠️ **Staleness is the consumer's call.** There is no server-computed
+         * "verified recently" boolean and there must not be one — the threshold
+         * is a product decision that will change, and a boolean freezes it into
+         * the wire where every consumer inherits it.
+         *
+         * Distinct from `lastTokenRefreshAt`, which is token-level truth: a
+         * token can refresh perfectly while delivery is broken, and that state
+         * is exactly what the verification endpoint exists to detect.
+         */
+        gmailLastVerifiedAt?: number;
     }
     type FxAutoUpdateStrategy = 'overwrite' | 'overwrite-if-stale' | 'notify-only';
     interface FxAutoUpdateBinding {

package/dist/userActivity.d.ts

@@ -494,10 +494,18 @@ declare global {
     interface BasketDiscountGrantedEvent extends UserActivityEventBase {
         event: 'Basket Discount Granted';
         /** Which verb — a withdrawal is as worth auditing as a grant. */
-        verb: 'setLineDiscount' | 'applyCoupon' | 'removeCoupon';
+        verb: 'setLineDiscount' | 'applyCoupon' | 'removeCoupon' | 'applyPromotion' | 'removePromotion';
         /**
-         * The grant's unit. Absent on `removeCoupon`, which withdraws rather than
-         * grants and therefore has no terms of its own.
+         * The grant's unit. Absent on `removeCoupon` and `removePromotion`, which
+         * withdraw rather than grant and therefore have no terms of their own.
+         *
+         * ⚠️ Also absent on `applyPromotion`, which GRANTS — and that is the
+         * one case where absence does not mean withdrawal. A promotion's grant is a
+         * whole terms object (a trigger, a reward, a repeat cap); there is no
+         * `(type, value)` pair that states it without lying by omission, so `code`
+         * carries the promotion id and the row holds the terms. A review reading
+         * this trail for abuse gets `amount` — the money — either way, which is
+         * the figure the review is actually made of.
          */
         type?: 'percent' | 'amount';
         /** The GRANT, in the unit `type` names — NOT money. See `amount`. */
@@ -515,6 +523,16 @@ declare global {
         amount?: number;
         /** The coupon code, on the two coupon verbs. Absent for a line discount. */
         code?: string;
+        /**
+         * The promotion, on `applyPromotion`.
+         *
+         * ⚠️ Its OWN field rather than a promotion id shipped in `code`. They
+         * are different identifiers into different entities, and a trail that put
+         * both in one column would make "which coupon was granted most often"
+         * unanswerable without knowing each row's verb — which is exactly the kind
+         * of join a review does not do before drawing a conclusion.
+         */
+        promotion_id?: string;
         /** The line the cut was applied to, on `setLineDiscount`. */
         line_id?: string;
         /** ⚠️ Optional for the same reason as `BasketUpdatedEvent.customer_id`: a

package/dist/webhook.d.ts

@@ -10,7 +10,7 @@
  * immediately subscribable — and a store that subscribes to an event with no
  * emit site gets silence it cannot distinguish from "nothing happened".
  */
-export declare const WEBHOOK_EVENT_TYPES: readonly ["print.queued", "print.received", "print.printed", "print.failed", "print.agent.connected", "print.agent.disconnected", "print.printer.online", "print.printer.offline", "print.job.settled", "payment.received", "product.stock_low", "product.stock_out", "order.created", "invoice.generated"];
+export declare const WEBHOOK_EVENT_TYPES: readonly ["print.queued", "print.received", "print.printed", "print.failed", "print.agent.connected", "print.agent.disconnected", "print.printer.online", "print.printer.offline", "print.job.settled", "payment.received", "product.stock_low", "product.stock_out", "order.created", "order.status_changed", "invoice.generated"];
 export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
 /** Terminal outcomes for a print job. Closed union — a job printed, or it failed. */
 export declare const PRINT_JOB_SETTLED_OUTCOMES: readonly ["printed", "failed"];
@@ -194,8 +194,16 @@ export interface ProductStockOutPayload {
  * ⚠️ A CLOSED union, and rule 1 above applies to it with full force: a fifth
  * order-minting path cannot be added here without breaking every subscriber
  * that switches exhaustively — it mints `order.created.v2` instead. The four
- * members are the complete set of paths that write an ORDER row today, each
- * verified at its own post-commit fan-out, not a sample.
+ * members are the paths that EMIT — which is no longer the same thing as the
+ * paths that WRITE an ORDER row.
+ *
+ * ⚠️ Converting an approved presupuesto (`convertPresupuestoToOrder`) mints an
+ * ordinary order through the same `createOrder` every member above uses, and
+ * emits nothing here — precisely BECAUSE adding a fifth member is the breaking
+ * change the paragraph above forbids. The gap is known and deliberate, not an
+ * oversight to be tidied: do not close it by quietly widening this tuple. The
+ * rest of that path's fan-out (stock webhooks, notifications, the ML push) does
+ * run; it is only this event that waits on the v2 decision.
  *
  * `service_delivery` is the repair-shop handover: a `ready` → `delivered`
  * transition mints an ordinary sale out of the counter lines the operator
@@ -277,6 +285,103 @@ export interface OrderCreatedPayload {
      */
     customerId?: string;
 }
+/**
+ * Payload for `order.status_changed` — an order MOVED along one of its status
+ * axes, and the move is durable.
+ *
+ * ── WHY THERE IS AN `axis` FIELD AT ALL ──────────────────────────────────
+ *
+ * `Order` has **no single `status` field**. It carries `fulfilmentStatus`
+ * (`pending | ready | delivered | not_delivered`) and `financialStatus`
+ * (`pending | partial | paid`) as independent axes, plus a third cancellation
+ * axis (`cancelledAt`/`cancelledBy`/`cancellationSource`) that moves neither.
+ *
+ * ⚠️ **`'pending'` is a member of BOTH unions.** A payload carrying only
+ * `from`/`to` is therefore genuinely ambiguous — `to: 'pending'` alone cannot
+ * tell a subscriber whether an order became unfulfilled or became unpaid, and
+ * those are opposite operational signals. The axis is what disambiguates them,
+ * so it is REQUIRED and is never inferred from the status spelling.
+ *
+ * ── WHY `axis` HAS EXACTLY ONE MEMBER TODAY ──────────────────────────────
+ *
+ * Only the FULFILMENT axis is shipped. `'financial'` is deliberately NOT
+ * declared here, and this is the line most likely to be "helpfully" widened by
+ * someone who reads the three-axis description above and assumes the union was
+ * simply left unfinished.
+ *
+ * Rule 3 above is the reason: a declared value means "this can occur on a real
+ * event", never "we intend to emit this later". Declaring `'financial'` before
+ * a financial seam emits would publish a value no subscriber can ever observe
+ * — the union equivalent of publishing an event nothing emits, and it would
+ * read to an integrator as a branch worth writing and testing against.
+ *
+ * ⚠️ Adding `'financial'` LATER is a BREAKING change under rule 1 (it widens a
+ * union an integrator may exhaustively switch on) and it is breaking whether or
+ * not it was pre-announced here — pre-declaring buys nothing and costs honesty.
+ * The financial axis ships behind rule 2 instead: either an announced widen, or
+ * a new `order.status_changed.v2`. That decision belongs to whoever builds the
+ * financial seam, with the settlement and payment-linking writers in front of
+ * them; it is not owed in advance.
+ *
+ * ── WHICH MOVES REACH THE WIRE ───────────────────────────────────────────
+ *
+ * REAL moves only, from the two single-order fulfilment seams: the operator
+ * delivery/un-delivery toggle, and the MercadoLibre shipment sync. Two writers
+ * touch `fulfilmentStatus` and are deliberately SILENT, because neither is a
+ * transition:
+ *
+ *   - the soft-delete hide path, which rewrites the field wholesale and
+ *     deliberately writes no `statusHistory` entry either;
+ *   - the order-edit heal branch, which writes a status where none was stored.
+ *     A back-catalogue row acquiring the field it always implied is a data
+ *     repair, and announcing it as a status change would tell an integrator an
+ *     order moved on a day nobody touched it.
+ *
+ * A self-edge never emits. Both seams gate on the stored value differing from
+ * the computed one, so a redundant write — a repeated delivery toggle, a
+ * shipment webhook replayed at the same state — is silence, not a duplicate.
+ *
+ * ⚠️ **No `total` and no `currency`**, for the same denomination reason set out
+ * on {@link OrderCreatedPayload}: `Order.currency` is a catalogId, not ISO
+ * 4217. A fulfilment move does not change either figure in any case.
+ *
+ * ⚠️ **Enumerated, never spread from the row.** `getOrderById` does not delete
+ * `search`, which embeds the customer's `fullName` (Ley 25.326).
+ */
+export interface OrderStatusChangedPayload {
+    orderId: string;
+    /**
+     * Which of the order's independent status axes moved.
+     *
+     * Single-member today. See the block above before widening it — the widen
+     * is the breaking change, not the pre-declaration.
+     */
+    axis: 'fulfilment';
+    /**
+     * The state moved FROM.
+     *
+     * ⚠️ **Genuinely optional, and it is not a "we might add it later".** Every
+     * order written before `fulfilmentStatus` existed carries no such field, and
+     * this platform is forward-only — nothing backfills. So the first real move
+     * on a back-catalogue order has no prior state to name, and a subscriber
+     * must handle its absence rather than treating it as a malformed event.
+     *
+     * Absent is never the same as equal to {@link to}: a self-edge does not
+     * emit at all.
+     */
+    from?: OrderFulfilmentStatus;
+    /** The state moved TO. Always the value the committed row now carries. */
+    to: OrderFulfilmentStatus;
+    /**
+     * Server-stamped Unix milliseconds, taken at the post-commit emit — the
+     * moment the api ANNOUNCED the move, on the same convention and for the same
+     * reason as {@link OrderCreatedPayload.occurredAt}.
+     *
+     * ⚠️ NOT the `statusHistory` entry's own `timestamp`. The two are within
+     * milliseconds of each other and they are not the same clock reading.
+     */
+    occurredAt: number;
+}
 /**
  * Payload for `invoice.generated` — ARCA authorised a fiscal voucher and its
  * `INVOICE#{storeId}` row is durable.

package/dist/webhook.js

@@ -67,6 +67,7 @@ export const WEBHOOK_EVENT_TYPES = [
     'product.stock_low',
     'product.stock_out',
     'order.created',
+    'order.status_changed',
     'invoice.generated',
 ];
 /** Terminal outcomes for a print job. Closed union — a job printed, or it failed. */
@@ -77,8 +78,16 @@ export const PRINT_JOB_SETTLED_OUTCOMES = ['printed', 'failed'];
  * ⚠️ A CLOSED union, and rule 1 above applies to it with full force: a fifth
  * order-minting path cannot be added here without breaking every subscriber
  * that switches exhaustively — it mints `order.created.v2` instead. The four
- * members are the complete set of paths that write an ORDER row today, each
- * verified at its own post-commit fan-out, not a sample.
+ * members are the paths that EMIT — which is no longer the same thing as the
+ * paths that WRITE an ORDER row.
+ *
+ * ⚠️ Converting an approved presupuesto (`convertPresupuestoToOrder`) mints an
+ * ordinary order through the same `createOrder` every member above uses, and
+ * emits nothing here — precisely BECAUSE adding a fifth member is the breaking
+ * change the paragraph above forbids. The gap is known and deliberate, not an
+ * oversight to be tidied: do not close it by quietly widening this tuple. The
+ * rest of that path's fan-out (stock webhooks, notifications, the ML push) does
+ * run; it is only this event that waits on the v2 decision.
  *
  * `service_delivery` is the repair-shop handover: a `ready` → `delivered`
  * transition mints an ordinary sale out of the counter lines the operator

package/package.json

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