@12-apps/discounts 1.0.0 → 1.2.0

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),
   };
 }