sinfactura-types 1.10.310 → 1.10.311

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/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/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/package.json

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