@12-apps/discounts 1.0.0 → 1.1.0

package/src/engine/types.ts

@@ -10,6 +10,38 @@ import type {
  * `./evaluate.ts` and whatever loads a host's rows agree on.
  */
 
+/**
+ * One SLOT of a combo: what may fill it, and how many units it needs for ONE
+ * application of the combo.
+ *
+ * "1 large popcorn + 2 sodas" is two slots — `{ menuItemIds: ["popcorn-lg"],
+ * quantity: 1 }` and `{ categoryIds: ["sodas"], quantity: 2 }`. "3 burgers for
+ * the price of 2" is ONE slot of quantity 3, whose rule carries
+ * `type: "FREE_UNITS"`, `freeUnits: 1`.
+ *
+ * A slot is satisfied from either list — an item id OR a category — because a
+ * merchant thinks in both at once ("a soda" is a category, "the large popcorn"
+ * is an item). At least one of the two must be non-empty; a slot naming
+ * neither can never be filled, and `toDiscountScalars` refuses it rather than
+ * storing a combo that silently never fires.
+ */
+export interface ComboRequirement {
+  /**
+   * Menu-item ids that fill this slot, matched against a line's BASE item OR
+   * its chosen variation — the same reach an `ITEM`-scoped discount has, so
+   * "a Coke" still fills the slot when the buyer picked "Coke zero can".
+   */
+  menuItemIds: readonly string[];
+  /**
+   * Category ids that fill this slot, matched against a line's category PATH,
+   * so a slot naming a top-level category is filled by its subcategories' items
+   * — the same reach a `CATEGORY`-scoped discount has.
+   */
+  categoryIds: readonly string[];
+  /** Units this slot needs per application. An integer >= 1. */
+  quantity: number;
+}
+
 /**
  * One discount as the evaluator sees it: a plain value object with every
  * stored and every counted fact already resolved. The evaluator never touches
@@ -24,11 +56,42 @@ export interface DiscountRule {
   percentOffBp: number | null;
   /** Cents off, > 0. Non-null iff `type === "FIXED_AMOUNT"`. */
   amountOffCents: number | null;
+  /**
+   * What the matched combo group costs, in cents. Non-null iff
+   * `type === "BUNDLE_PRICE"`. The discount is the group's gross value minus
+   * this, per application.
+   */
+  bundlePriceCents?: number | null;
+  /**
+   * How many units of the matched group are free. Non-null iff
+   * `type === "FREE_UNITS"`. The CHEAPEST units of each application are the
+   * free ones, which is the buyer-favourable reading of "3 for the price of 2"
+   * and the one every merchant means by it.
+   */
+  freeUnits?: number | null;
   scope: DiscountScope;
   /** Target category ids. Non-empty iff `scope === "CATEGORY"`. */
   targetCategoryIds: readonly string[];
   /** Target menu-item ids. Non-empty iff `scope === "ITEM"`. */
   targetMenuItemIds: readonly string[];
+  /**
+   * The combo's slots, in the merchant's own declaration order. Non-empty iff
+   * `scope === "COMBO"`; ignored at every other scope.
+   *
+   * OPTIONAL, unlike the two target arrays above, and that asymmetry is the
+   * point: every discount has a scope and a type, so those fields are facts
+   * about all of them, while a combo is a CAPABILITY a host opts into. A host
+   * that does not sell combos never stores a `COMBO`-scoped rule, so it never
+   * has a value to put here, and requiring one would have made adding combos a
+   * breaking change for every adopter that does not want them.
+   */
+  comboRequirements?: readonly ComboRequirement[];
+  /**
+   * How many times this combo may apply to ONE cart; null or omitted means as
+   * often as the cart can fill its slots. A cart with six burgers takes "3 for
+   * the price of 2" twice unless this says otherwise.
+   */
+  maxComboApplications?: number | null;
   trigger: DiscountTrigger;
   /** Normalized (trimmed, upper-cased) code. Non-null iff `trigger === "CODE"`. */
   code: string | null;
@@ -110,6 +173,17 @@ export interface AppliedDiscount {
   amountOffCents: number | null;
   /** Cents removed from the order by THIS discount. Always > 0. */
   amountCents: number;
+  /**
+   * How many times a `COMBO`-scoped discount applied to this cart; absent for
+   * every other scope.
+   *
+   * It is on the SNAPSHOT rather than merely in the evaluation because it is
+   * the one combo fact an order cannot re-derive later: the rule's slots may
+   * have been re-stated, and the line quantities the combo consumed are not
+   * recoverable from the per-line cents alone. A receipt saying "Combo leve 3
+   * pague 2 (2x)" needs this number.
+   */
+  comboApplications?: number;
 }
 
 /** Per-line outcome. `Σ discountCents` equals the order's `discountTotalCents`. */

package/src/index.ts

@@ -12,6 +12,14 @@
  * browser bundle that only prices a cart never resolves it. The wiring
  * manifests are at `@12-apps/discounts/manifest` and `./manifest/server`.
  *
+ * COMBOS (FUT-268) live here too, as a SCOPE rather than as a catalog entity:
+ * a `COMBO`-scoped rule matches quantified slots against the cart's units and
+ * prices the group ("1 large popcorn + 2 sodas for R$ 25", "3 burgers for the
+ * price of 2"). What is NOT here — and cannot be, for the same reason the
+ * database is not — is a combo as a SELLABLE product: its own menu card, its
+ * own cart line, its own order snapshot. That is a host catalog entity with
+ * foreign keys into host tables. The pricing RULE travels; the product does not.
+ *
  * The DATABASE is deliberately NOT here, and the manifest declares no `db`
  * capability. A discount's rows relate to a host's own catalog and orders —
  * targets point at categories and items, redemptions at orders and buyers —
@@ -22,10 +30,13 @@
  */
 
 export {
+  COMBO_ONLY_DISCOUNT_TYPES,
   DISCOUNT_REJECTION_REASONS,
   DISCOUNT_SCOPES,
   DISCOUNT_TRIGGERS,
   DISCOUNT_TYPES,
+  MAX_COMBO_SLOTS,
+  MAX_COMBO_SLOT_QUANTITY,
   MAX_PERCENT_OFF_BP,
   MIN_PAYABLE_TOTAL_CENTS,
   normalizeDiscountCode,
@@ -37,6 +48,7 @@ export {
 
 export type {
   AppliedDiscount,
+  ComboRequirement,
   DiscountCartLine,
   DiscountEvaluation,
   DiscountEvaluationInput,
@@ -53,6 +65,31 @@ export {
   type ItemDiscountPreviewInput,
 } from "./engine/preview";
 
+/**
+ * The COMBO half of the catalog surface (FUT-268). A combo has no single-item
+ * price to badge, so a card advertises PARTICIPATION instead — see
+ * `./engine/combo-offer.ts` for why that is the only honest thing a card can
+ * say about one.
+ */
+export {
+  comboOffersForItem,
+  type ComboOffer,
+  type ComboOffersInput,
+} from "./engine/combo-offer";
+
+/**
+ * The combo matcher, exported because a host that wants to EXPLAIN a combo —
+ * "aplicado 2x", "faltam 2 refrigerantes" — needs the same match the evaluator
+ * priced, and re-deriving it host-side is how a receipt and a cart start
+ * disagreeing about what was in the bundle.
+ */
+export {
+  freshComboPool,
+  matchCombo,
+  type ComboMatch,
+  type ComboPool,
+} from "./engine/combo-match";
+
 export {
   discountRejectionMessage,
   missingRejectionCopy,

package/src/server/copy.ts

@@ -40,6 +40,22 @@ export interface DiscountsServerCopy {
   readonly invalidUsageLimit: string;
   /** 422 — a per-buyer redemption cap of zero or less. */
   readonly invalidPerBuyerLimit: string;
+  /** 422 — a BUNDLE_PRICE or FREE_UNITS reward on a discount that is not a combo. */
+  readonly comboScopeRequired: string;
+  /** 422 — a combo with no slots at all, or more than `MAX_COMBO_SLOTS`. */
+  readonly invalidComboSlots: string;
+  /** 422 — a combo slot naming neither a product nor a category. */
+  readonly comboTargetRequired: string;
+  /** 422 — a slot asking for zero units, or more than `MAX_COMBO_SLOT_QUANTITY`. */
+  readonly invalidComboQuantity: string;
+  /** 422 — a BUNDLE_PRICE combo without a positive price in cents. */
+  readonly invalidBundlePrice: string;
+  /** 422 — a FREE_UNITS combo without a positive count of free units. */
+  readonly invalidFreeUnits: string;
+  /** 422 — a combo giving away every unit it asks for, which sells nothing. */
+  readonly freeUnitsExceedCombo: string;
+  /** 422 — a per-cart combo cap of zero or less. */
+  readonly invalidMaxComboApplications: string;
 }
 
 const COPY_KEYS: readonly (keyof DiscountsServerCopy)[] = [
@@ -55,6 +71,14 @@ const COPY_KEYS: readonly (keyof DiscountsServerCopy)[] = [
   "invalidMinSubtotal",
   "invalidUsageLimit",
   "invalidPerBuyerLimit",
+  "comboScopeRequired",
+  "invalidComboSlots",
+  "comboTargetRequired",
+  "invalidComboQuantity",
+  "invalidBundlePrice",
+  "invalidFreeUnits",
+  "freeUnitsExceedCombo",
+  "invalidMaxComboApplications",
 ];
 
 /** Every key present and non-blank — checked at assembly, like the rest. */

package/src/server/index.ts

@@ -40,9 +40,12 @@ export {
   type DiscountWriteInput,
 } from "./validate";
 
+export { comboRequirementsForScope, toComboColumns, type ComboColumns } from "./validate-combo";
+
 export { discountSearchConfig } from "./search";
 
 export {
+  comboRequirementSchema,
   createDiscountBody,
   createDiscountListQuery,
   discountCollectionParams,

package/src/server/mcp.ts

@@ -8,7 +8,14 @@ import {
 } from "@12-apps/shared-helpers/search";
 import type { WireMcpTool } from "@12-apps/wiring";
 
-import { DISCOUNT_SCOPES, DISCOUNT_TRIGGERS, DISCOUNT_TYPES, MAX_PERCENT_OFF_BP } from "../engine/kinds";
+import {
+  DISCOUNT_SCOPES,
+  DISCOUNT_TRIGGERS,
+  DISCOUNT_TYPES,
+  MAX_COMBO_SLOTS,
+  MAX_COMBO_SLOT_QUANTITY,
+  MAX_PERCENT_OFF_BP,
+} from "../engine/kinds";
 import { discountSearchConfig } from "./search";
 
 /**
@@ -46,6 +53,18 @@ export const discountItemParams = z.object({
  */
 const calendarDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
 
+/**
+ * One combo slot: what fills it, and how many units of it one application
+ * needs. Both target lists default to empty and at least one must be
+ * non-empty — a rule `./validate-combo.ts` enforces with the host's own
+ * sentence, because a Zod refinement here could only answer in a Zod path.
+ */
+export const comboRequirementSchema = z.object({
+  menuItemIds: z.array(z.string().min(1)).default([]),
+  categoryIds: z.array(z.string().min(1)).default([]),
+  quantity: z.number().int().min(1).max(MAX_COMBO_SLOT_QUANTITY),
+});
+
 /**
  * A discount as the API returns it (JSON-serialized: dates become ISO
  * strings). The two join tables are flattened into id arrays.
@@ -58,6 +77,16 @@ export const discountSchema = z.object({
   percentOffBp: z.number().int().nullable(),
   /** Cents off. Non-null iff `type = FIXED_AMOUNT`. */
   amountOffCents: z.number().int().nullable(),
+  /**
+   * The COMBO half. OPTIONAL in the RESPONSE, unlike in the body, because the
+   * record is assembled by a host's store: an adopter that has not added the
+   * columns still answers a valid discount, and one that has says so. See
+   * `DiscountRecord` in `./store`.
+   */
+  bundlePriceCents: z.number().int().nullable().optional(),
+  freeUnits: z.number().int().nullable().optional(),
+  maxComboApplications: z.number().int().nullable().optional(),
+  comboRequirements: z.array(comboRequirementSchema).optional(),
   scope: z.enum(DISCOUNT_SCOPES),
   trigger: z.enum(DISCOUNT_TRIGGERS),
   code: z.string().nullable(),
@@ -101,15 +130,20 @@ export const listDiscountsQuery = createDiscountListQuery(searchConfigSchema.par
  * The write body, shared by create and update: a discount is always saved
  * WHOLE (the form re-states every field), so there is no partial-patch shape
  * to diverge from. The cross-field rules — a rate iff PERCENTAGE, a code iff
- * CODE, a target iff CATEGORY/ITEM, `endsAt` strictly after `startsAt` — are
- * enforced in `./validate`, where they produce a sentence naming the field
- * instead of a Zod path.
+ * CODE, a target iff CATEGORY/ITEM, a slot list iff COMBO, a combo reward ONLY
+ * at COMBO scope, `endsAt` strictly after `startsAt` — are enforced in
+ * `./validate` and `./validate-combo`, where they produce a sentence naming the
+ * field instead of a Zod path.
  */
 const discountWriteShape = {
   name: z.string().min(2).max(120),
   type: z.enum(DISCOUNT_TYPES),
   percentOffBp: z.number().int().min(1).max(MAX_PERCENT_OFF_BP).nullable().optional(),
   amountOffCents: z.number().int().positive().nullable().optional(),
+  bundlePriceCents: z.number().int().positive().nullable().optional(),
+  freeUnits: z.number().int().positive().nullable().optional(),
+  comboRequirements: z.array(comboRequirementSchema).max(MAX_COMBO_SLOTS).optional(),
+  maxComboApplications: z.number().int().positive().nullable().optional(),
   scope: z.enum(DISCOUNT_SCOPES),
   trigger: z.enum(DISCOUNT_TRIGGERS),
   code: z.string().min(1).max(64).nullable().optional(),
@@ -145,7 +179,7 @@ export const DISCOUNTS_MCP_TOOLS: readonly WireMcpTool<z.ZodType>[] = [
     method: "GET",
     path: "/discounts",
     summary:
-      "List a store's discounts and promotions (admin). Backend filter (`q` over name and coupon code, `type_in` PERCENTAGE|FIXED_AMOUNT, `scope_in` ORDER|CATEGORY|ITEM, `trigger_in` AUTOMATIC|CODE, `active`), `sort` (field:asc|desc), and pagination (`page`/`pageSize`). Returns the page plus `pagination` (total, pageCount, hasNextPage).",
+      "List a store's discounts and promotions (admin). Backend filter (`q` over name and coupon code, `type_in` PERCENTAGE|FIXED_AMOUNT|BUNDLE_PRICE|FREE_UNITS, `scope_in` ORDER|CATEGORY|ITEM|COMBO, `trigger_in` AUTOMATIC|CODE, `active`), `sort` (field:asc|desc), and pagination (`page`/`pageSize`). Returns the page plus `pagination` (total, pageCount, hasNextPage).",
     tags: ["discounts"],
     params: discountCollectionParams,
     query: listDiscountsQuery,
@@ -167,7 +201,7 @@ export const DISCOUNTS_MCP_TOOLS: readonly WireMcpTool<z.ZodType>[] = [
     method: "POST",
     path: "/discounts",
     summary:
-      "Create a discount for a store (admin). A percentage is basis points (1..10000); a fixed amount is integer cents. A CODE-triggered discount needs a coupon code, unique within the store; a CATEGORY/ITEM-scoped one needs at least one target.",
+      "Create a discount for a store (admin). A percentage is basis points (1..10000); a fixed amount is integer cents. A CODE-triggered discount needs a coupon code, unique within the store; a CATEGORY/ITEM-scoped one needs at least one target. A COMBO-scoped one is a bundle: `comboRequirements` lists its slots (products and/or categories, with a per-slot `quantity`), and the reward is either `BUNDLE_PRICE` (what the whole matched group costs, in cents) or `FREE_UNITS` (how many of its cheapest units are free — \"3 for the price of 2\" is one slot of quantity 3 with `freeUnits` 1), or an ordinary percentage/fixed amount off the group.",
     tags: ["discounts"],
     params: discountCollectionParams,
     body: createDiscountBody,

package/src/server/pt-BR.ts

@@ -23,4 +23,13 @@ export const PT_BR_DISCOUNTS_SERVER_COPY: DiscountsServerCopy = {
   invalidMinSubtotal: "O pedido mínimo deve ser maior que zero (ou deixe em branco).",
   invalidUsageLimit: "O limite de usos deve ser maior que zero (ou deixe em branco).",
   invalidPerBuyerLimit: "O limite por cliente deve ser maior que zero (ou deixe em branco).",
+  comboScopeRequired: "Preço de combo e itens grátis só valem para descontos do tipo combo.",
+  invalidComboSlots: "Um combo precisa de pelo menos um grupo de itens.",
+  comboTargetRequired: "Selecione ao menos um produto ou categoria para cada grupo do combo.",
+  invalidComboQuantity: "Informe uma quantidade maior que zero para cada grupo do combo.",
+  invalidBundlePrice: "Informe o preço do combo, maior que zero.",
+  invalidFreeUnits: "Informe quantos itens saem de graça, maior que zero.",
+  freeUnitsExceedCombo: "O combo precisa cobrar por pelo menos um item.",
+  invalidMaxComboApplications:
+    "O limite de combos por carrinho deve ser maior que zero (ou deixe em branco).",
 };

package/src/server/store.ts

@@ -1,6 +1,7 @@
 import type { PaginatedResult, ParsedSearchInput } from "@12-apps/shared-helpers/search";
 
 import type { DiscountScope, DiscountTrigger, DiscountType } from "../engine/kinds";
+import type { ComboRequirement } from "../engine/types";
 import type { DiscountScalars, DiscountTargets } from "./validate";
 
 /**
@@ -44,6 +45,21 @@ export interface DiscountRecord {
    */
   categoryIds: string[];
   menuItemIds: string[];
+  /**
+   * The COMBO half (FUT-268), OPTIONAL because this record is built by the
+   * HOST's store and combos are a capability a host opts into. A host that has
+   * not added the columns keeps compiling and keeps answering the same record
+   * it always did; one that has, fills them in.
+   *
+   * The asymmetry with {@link DiscountWrite} is deliberate and runs the other
+   * way for the same reason: what this package PRODUCES is always complete, so
+   * a store is handed every combo column whether it stores them or not, while
+   * what a host BUILDS may predate the feature.
+   */
+  bundlePriceCents?: number | null;
+  freeUnits?: number | null;
+  maxComboApplications?: number | null;
+  comboRequirements?: ComboRequirement[];
   createdAt: Date;
 }
 

package/src/server/validate-combo.ts

@@ -0,0 +1,161 @@
+import {
+  COMBO_ONLY_DISCOUNT_TYPES,
+  MAX_COMBO_SLOTS,
+  MAX_COMBO_SLOT_QUANTITY,
+} from "../engine/kinds";
+import type { ComboRequirement } from "../engine/types";
+import type { DiscountsServerCopy } from "./copy";
+import { DiscountValidationError, type DiscountWriteInput } from "./validate";
+
+/**
+ * The write-time rule set for the COMBO half of a discount (FUT-268).
+ *
+ * Split from `./validate.ts` for the 400-line file gate, and read as part of
+ * it: the same doctrine applies unchanged. Every rule here has a twin as a
+ * database CHECK where SQL can express it, this layer exists so the operator
+ * gets a sentence naming the FIELD, and the sentences themselves live in
+ * {@link DiscountsServerCopy} rather than here.
+ *
+ * Two of these rules have no SQL twin at all, for the same reason the "at least
+ * one target" rule does not: they count rows in another table. A CHECK cannot
+ * see whether a combo has any slots, nor add their quantities up to compare the
+ * total against `free_units`. This module is their only enforcement point, and
+ * both failures are silent ones — a combo with no slots never fires, and a
+ * combo giving away as many units as it requires charges the buyer nothing for
+ * a group the merchant meant to sell.
+ */
+
+function invalid(field: string, message: string): DiscountValidationError {
+  return new DiscountValidationError(field, message);
+}
+
+/** The combo columns of a discount row, validated and narrowed to the type. */
+export interface ComboColumns {
+  bundlePriceCents: number | null;
+  freeUnits: number | null;
+  maxComboApplications: number | null;
+}
+
+function isPositiveInteger(value: number | null): value is number {
+  return value !== null && Number.isInteger(value) && value > 0;
+}
+
+/**
+ * A combo reward only means something against a matched group, so the two
+ * types that express one are legal at exactly one scope. Checked BEFORE the
+ * value columns, so an operator who picked "bundle price" on an order-wide
+ * discount is told the real mistake rather than being asked for a price the
+ * discount could never use.
+ */
+function assertComboScope(input: DiscountWriteInput, copy: DiscountsServerCopy): void {
+  const isComboReward = COMBO_ONLY_DISCOUNT_TYPES.some((type) => type === input.type);
+  if (isComboReward && input.scope !== "COMBO") {
+    throw invalid("scope", copy.comboScopeRequired);
+  }
+}
+
+/** The slot list itself: present, and small enough to be a describable offer. */
+function assertSlotCount(requirements: readonly ComboRequirement[], copy: DiscountsServerCopy): void {
+  if (requirements.length === 0 || requirements.length > MAX_COMBO_SLOTS) {
+    throw invalid("comboRequirements", copy.invalidComboSlots);
+  }
+}
+
+/**
+ * One slot. A slot naming neither an item nor a category can never be filled,
+ * so the combo would exist, look live in the list, and never fire — the same
+ * failure `assertTargets` exists to refuse one level up.
+ */
+function assertSlot(requirement: ComboRequirement, copy: DiscountsServerCopy): void {
+  const quantity = requirement.quantity;
+  if (!Number.isInteger(quantity) || quantity <= 0 || quantity > MAX_COMBO_SLOT_QUANTITY) {
+    throw invalid("comboRequirements", copy.invalidComboQuantity);
+  }
+  if (requirement.menuItemIds.length === 0 && requirement.categoryIds.length === 0) {
+    throw invalid("comboRequirements", copy.comboTargetRequired);
+  }
+}
+
+/** How many units ONE application of this combo takes out of the cart. */
+function unitsPerApplication(requirements: readonly ComboRequirement[]): number {
+  return requirements.reduce((total, requirement) => total + requirement.quantity, 0);
+}
+
+/**
+ * The `FREE_UNITS` count, which is the one number in a combo that is bounded by
+ * another: "take 3, one free" is a promotion, "take 3, three free" is a
+ * giveaway the merchant almost certainly did not mean and that the payable
+ * floor would then have to rescue at checkout.
+ */
+function assertFreeUnits(input: DiscountWriteInput, copy: DiscountsServerCopy): number {
+  const freeUnits = input.freeUnits;
+  if (!isPositiveInteger(freeUnits)) throw invalid("freeUnits", copy.invalidFreeUnits);
+  if (freeUnits >= unitsPerApplication(input.comboRequirements)) {
+    throw invalid("freeUnits", copy.freeUnitsExceedCombo);
+  }
+  return freeUnits;
+}
+
+function assertBundlePrice(input: DiscountWriteInput, copy: DiscountsServerCopy): number {
+  if (!isPositiveInteger(input.bundlePriceCents)) {
+    throw invalid("bundlePrice", copy.invalidBundlePrice);
+  }
+  return input.bundlePriceCents;
+}
+
+/**
+ * The slots and the application cap — everything that describes the combo
+ * rather than its reward. Only runs at `COMBO` scope: at every other scope the
+ * fields are ignored on the way in and dropped on the way out
+ * ({@link comboRequirementsForScope}), exactly as `ORDER` drops its targets.
+ */
+function assertComboSpec(input: DiscountWriteInput, copy: DiscountsServerCopy): void {
+  assertSlotCount(input.comboRequirements, copy);
+  for (const requirement of input.comboRequirements) assertSlot(requirement, copy);
+  const cap = input.maxComboApplications;
+  if (cap !== null && !isPositiveInteger(cap)) {
+    throw invalid("maxComboApplications", copy.invalidMaxComboApplications);
+  }
+}
+
+/**
+ * Validate the combo half of one write and fold it into its columns.
+ *
+ * The unused reward column is forced to NULL rather than passed through, for
+ * the reason the scalar folder gives at length: a `BUNDLE_PRICE` combo that
+ * kept a leftover `freeUnits` from the form's other branch would violate the
+ * "exactly one value column" constraint at the database, and the operator would
+ * see a 500 for a form they filled in correctly.
+ */
+export function toComboColumns(
+  input: DiscountWriteInput,
+  copy: DiscountsServerCopy,
+): ComboColumns {
+  assertComboScope(input, copy);
+  if (input.scope !== "COMBO") {
+    return { bundlePriceCents: null, freeUnits: null, maxComboApplications: null };
+  }
+  assertComboSpec(input, copy);
+  return {
+    bundlePriceCents: input.type === "BUNDLE_PRICE" ? assertBundlePrice(input, copy) : null,
+    freeUnits: input.type === "FREE_UNITS" ? assertFreeUnits(input, copy) : null,
+    maxComboApplications: input.maxComboApplications,
+  };
+}
+
+/**
+ * The slots this scope actually stores, de-duplicated within each slot.
+ *
+ * Dropping them at every other scope (instead of trusting the caller) is what
+ * keeps a scope change from leaving orphan slot rows that would quietly turn
+ * the discount back into a combo if the scope were ever flipped back — the same
+ * argument `targetsForScope` makes about its two id arrays.
+ */
+export function comboRequirementsForScope(input: DiscountWriteInput): ComboRequirement[] {
+  if (input.scope !== "COMBO") return [];
+  return input.comboRequirements.map((requirement) => ({
+    menuItemIds: [...new Set(requirement.menuItemIds)],
+    categoryIds: [...new Set(requirement.categoryIds)],
+    quantity: requirement.quantity,
+  }));
+}

package/src/server/validate.ts

@@ -5,7 +5,9 @@ import {
   type DiscountTrigger,
   type DiscountType,
 } from "../engine/kinds";
+import type { ComboRequirement } from "../engine/types";
 import type { DiscountsServerCopy } from "./copy";
+import { comboRequirementsForScope, toComboColumns } from "./validate-combo";
 
 /**
  * The write-time rule set for a discount (FUT-244).
@@ -37,6 +39,10 @@ export interface DiscountWriteInput {
   percentOffBp: number | null;
   /** Cents, > 0. Required iff `type === "FIXED_AMOUNT"`. */
   amountOffCents: number | null;
+  /** Cents the matched group costs. Required iff `type === "BUNDLE_PRICE"`. */
+  bundlePriceCents: number | null;
+  /** Free units of the group. Required iff `type === "FREE_UNITS"`. */
+  freeUnits: number | null;
   scope: DiscountScope;
   trigger: DiscountTrigger;
   /** Raw code as typed; normalized here. Required iff `trigger === "CODE"`. */
@@ -53,6 +59,10 @@ export interface DiscountWriteInput {
   categoryIds: readonly string[];
   /** Target menu-item ids — read only when `scope === "ITEM"`. */
   menuItemIds: readonly string[];
+  /** The combo's slots — read only when `scope === "COMBO"`. */
+  comboRequirements: readonly ComboRequirement[];
+  /** Cap on how often one cart may take the combo; null = uncapped. */
+  maxComboApplications: number | null;
 }
 
 /**
@@ -81,7 +91,12 @@ function invalid(field: string, message: string): DiscountValidationError {
   return new DiscountValidationError(field, message);
 }
 
-/** The value half: exactly one of the two columns, inside its legal range. */
+/**
+ * The value half: exactly one of the FOUR value columns, inside its legal
+ * range. The two combo rewards are asserted in `./validate-combo.ts`, which
+ * also refuses them at any scope but `COMBO`; the two that read a plain base
+ * are asserted here.
+ */
 function assertValue(input: DiscountWriteInput, copy: DiscountsServerCopy): void {
   if (input.type === "PERCENTAGE") {
     const bp = input.percentOffBp;
@@ -90,6 +105,7 @@ function assertValue(input: DiscountWriteInput, copy: DiscountsServerCopy): void
     }
     return;
   }
+  if (input.type !== "FIXED_AMOUNT") return;
   const cents = input.amountOffCents;
   if (cents === null || !Number.isInteger(cents) || cents <= 0) {
     throw invalid("amountOff", copy.invalidAmount);
@@ -113,6 +129,9 @@ function assertTrigger(input: DiscountWriteInput, copy: DiscountsServerCopy): st
  * count rows in another table, so a CATEGORY-scoped discount with an empty
  * target list would be accepted by the database and then silently cover
  * NOTHING — a promotion that exists, looks live in the list, and never fires.
+ *
+ * `COMBO` has the same rule against a different table — its slots — and it
+ * lives in `./validate-combo.ts` beside the rest of the combo shape.
  */
 function assertTargets(input: DiscountWriteInput, copy: DiscountsServerCopy): void {
   if (input.scope === "CATEGORY" && input.categoryIds.length === 0) {
@@ -167,6 +186,9 @@ export interface DiscountScalars {
   type: DiscountType;
   percentOffBp: number | null;
   amountOffCents: number | null;
+  bundlePriceCents: number | null;
+  freeUnits: number | null;
+  maxComboApplications: number | null;
   scope: DiscountScope;
   trigger: DiscountTrigger;
   code: string | null;
@@ -179,10 +201,18 @@ export interface DiscountScalars {
   active: boolean;
 }
 
-/** The target ids of one write, de-duplicated and narrowed to the scope. */
+/**
+ * The targets of one write, de-duplicated and narrowed to the scope.
+ *
+ * The combo slots ride here rather than with the scalars because that is what
+ * they ARE: rows in a child table, like the two id arrays beside them, not
+ * columns on the discount row. A store persisting this writes three join
+ * tables and one row.
+ */
 export interface DiscountTargets {
   categoryIds: string[];
   menuItemIds: string[];
+  comboRequirements: ComboRequirement[];
 }
 
 /**
@@ -204,13 +234,16 @@ export function toDiscountScalars(
   assertTargets(input, copy);
   const { startsAt, endsAt } = assertWindow(input, copy);
   assertLimits(input, copy);
+  const combo = toComboColumns(input, copy);
 
-  const isPercentage = input.type === "PERCENTAGE";
   return {
     name: input.name.trim(),
     type: input.type,
-    percentOffBp: isPercentage ? input.percentOffBp : null,
-    amountOffCents: isPercentage ? null : input.amountOffCents,
+    percentOffBp: input.type === "PERCENTAGE" ? input.percentOffBp : null,
+    amountOffCents: input.type === "FIXED_AMOUNT" ? input.amountOffCents : null,
+    bundlePriceCents: combo.bundlePriceCents,
+    freeUnits: combo.freeUnits,
+    maxComboApplications: combo.maxComboApplications,
     scope: input.scope,
     trigger: input.trigger,
     code,
@@ -237,6 +270,8 @@ export interface DiscountWriteBody {
   type: DiscountType;
   percentOffBp?: number | null;
   amountOffCents?: number | null;
+  bundlePriceCents?: number | null;
+  freeUnits?: number | null;
   scope: DiscountScope;
   trigger: DiscountTrigger;
   code?: string | null;
@@ -249,6 +284,8 @@ export interface DiscountWriteBody {
   active: boolean;
   categoryIds?: string[];
   menuItemIds?: string[];
+  comboRequirements?: ComboRequirement[];
+  maxComboApplications?: number | null;
 }
 
 /**
@@ -267,6 +304,8 @@ export function toDiscountWriteInput(body: DiscountWriteBody): DiscountWriteInpu
     type: body.type,
     percentOffBp: orNull(body.percentOffBp),
     amountOffCents: orNull(body.amountOffCents),
+    bundlePriceCents: orNull(body.bundlePriceCents),
+    freeUnits: orNull(body.freeUnits),
     scope: body.scope,
     trigger: body.trigger,
     code: orNull(body.code),
@@ -279,6 +318,8 @@ export function toDiscountWriteInput(body: DiscountWriteBody): DiscountWriteInpu
     active: body.active,
     categoryIds: orEmpty(body.categoryIds),
     menuItemIds: orEmpty(body.menuItemIds),
+    comboRequirements: body.comboRequirements ?? [],
+    maxComboApplications: orNull(body.maxComboApplications),
   };
 }
 
@@ -292,5 +333,6 @@ export function targetsForScope(input: DiscountWriteInput): DiscountTargets {
   return {
     categoryIds: input.scope === "CATEGORY" ? [...new Set(input.categoryIds)] : [],
     menuItemIds: input.scope === "ITEM" ? [...new Set(input.menuItemIds)] : [],
+    comboRequirements: comboRequirementsForScope(input),
   };
 }