@12-apps/discounts 1.13.0 → 1.15.0

package/README.md

@@ -474,6 +474,16 @@ language is a line in the host's diff rather than a silence.
 resolved (`{ clientId }`); authentication, tenant resolution, RBAC tiers and
 plan gates stay where they belong.
 
+**Who is buying for the first time.** A rule saved with `firstOrderOnly`
+(FUT-2825) applies only when the host sets `buyerIsFirstTime: true` on it —
+this package never reads an order, so "has this buyer bought here before" is
+the host's answer, the way `buyerUsageCount` already is. Unknown (`null` or
+omitted: an anonymous cart, a cached menu) is NOT first-time, on purpose: a
+discount the cart shows and checkout then takes back is worse than one that
+appears once the buyer is known. So a first-purchase rule is never badged or
+teased on a catalog card, and two concurrent first orders by one buyer can both
+pass, as with `perBuyerLimit`. Combos keep their own rules and never carry it.
+
 **The words on a pill.** The validity filter a promotions grid usually wants —
 running / scheduled / ended — compares two nullable columns against "now",
 which no `filterableField` expresses, and its values are words a host chose. So

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "type": "module",
   "sideEffects": [
     "**/e2e/**"
@@ -41,10 +41,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@12-apps/app-shell": "^5.7.0",
+    "@12-apps/app-shell": "^5.11.0",
     "@12-apps/forms-core": "^1.21.0",
     "@12-apps/shared-helpers": "^2.1.0",
-    "@12-apps/ui": "^6.15.1",
+    "@12-apps/ui": "^6.43.0",
     "@mui/icons-material": "^6.5.0",
     "zod": "^4.3.5"
   },

package/prisma/discounts.prisma

@@ -109,6 +109,9 @@ model Discount {
   // Redemptions allowed across every buyer, and per buyer. Null = no cap.
   usageLimit           Int?      @map("usage_limit")
   perBuyerLimit        Int?      @map("per_buyer_limit")
+  // Only a buyer's FIRST purchase at the store (FUT-2825). Who that is, is the
+  // host's answer: this package never reads an order.
+  firstOrderOnly       Boolean   @default(false) @map("first_order_only")
   usageCount           Int       @default(0) @map("usage_count")
   // When false this rule stacks with nothing: if it wins it is the only one
   // applied to the order ("best single discount wins").

package/prisma/migrations/20260926230000_discount_first_order_only/migration.sql

@@ -0,0 +1,13 @@
+-- @12-apps/discounts: the first-purchase condition (FUT-2825).
+--
+-- "Só na primeira compra do cliente nesta loja" — a rule the engine screens
+-- against the host's answer to "has this buyer bought here before".
+--
+-- ── PURELY ADDITIVE ───────────────────────────────────────────────────────
+-- One NOT NULL column with a constant default, no backfill: FALSE is exactly
+-- what every existing row already means, so this migration cannot change the
+-- price of anything. Postgres adds a column with a constant default without
+-- rewriting the table.
+--
+-- Replay-safe like its predecessors: `IF NOT EXISTS`.
+ALTER TABLE "discounts" ADD COLUMN IF NOT EXISTS "first_order_only" BOOLEAN NOT NULL DEFAULT false;

package/src/engine/eligibility.ts

@@ -152,6 +152,9 @@ function screenLimits(rule: DiscountRule, ctx: ScreenContext): DiscountRejection
   if (rule.perBuyerLimit !== null && rule.buyerUsageCount >= rule.perBuyerLimit) {
     return "BUYER_LIMIT_REACHED";
   }
+  // Advisory in the same way `buyerUsageCount` is: two concurrent first orders
+  // by one buyer can both pass (FUT-2825).
+  if (rule.firstOrderOnly === true && rule.buyerIsFirstTime !== true) return "NOT_FIRST_ORDER";
   if (rule.minSubtotalCents !== null && ctx.subtotalCents < rule.minSubtotalCents) {
     return "MIN_SUBTOTAL_NOT_MET";
   }

package/src/engine/en-US.ts

@@ -29,6 +29,7 @@ export const EN_US_DISCOUNT_REJECTION_COPY: DiscountRejectionCopy = {
   MIN_SUBTOTAL_NOT_MET: `This coupon needs a minimum order of ${MIN_SUBTOTAL_TOKEN}.`,
   USAGE_LIMIT_REACHED: "This coupon has reached its usage limit.",
   BUYER_LIMIT_REACHED: "You have already used this coupon.",
+  NOT_FIRST_ORDER: "Only valid on your first purchase at this store.",
   NO_ELIGIBLE_ITEMS: "This coupon does not apply to the items in your cart.",
   COMBO_NOT_MATCHED: "Your cart does not have every item in this bundle yet.",
   ZERO_VALUE: "This coupon does not apply to the items in your cart.",

package/src/engine/kinds.ts

@@ -159,6 +159,7 @@ export const DISCOUNT_REJECTION_REASONS = [
   "MIN_SUBTOTAL_NOT_MET",
   "USAGE_LIMIT_REACHED",
   "BUYER_LIMIT_REACHED",
+  "NOT_FIRST_ORDER",
   "NO_ELIGIBLE_ITEMS",
   "COMBO_NOT_MATCHED",
   "ZERO_VALUE",

package/src/engine/preview.ts

@@ -60,6 +60,14 @@ import type { DiscountCartLine, DiscountRule } from "./types";
  * screens the same rule against a real `buyerUsageCount` and reports
  * `BUYER_LIMIT_REACHED`, before a single cent is charged.
  *
+ * `firstOrderOnly` (FUT-2825) goes the OTHER way, deliberately. A per-buyer
+ * cap is exhausted by a few; "first purchase only" excludes EVERY returning
+ * buyer, so an optimistic badge would be a wrong price for most of the people
+ * reading the menu. The screen settles it without a special case: a catalog
+ * read passes no `buyerIsFirstTime`, an unknown buyer is not first-time, and
+ * `screenRule` rejects `NOT_FIRST_ORDER` — so no badge. The host advertises the
+ * promotion to the buyers it CAN name as first-time, outside the menu.
+ *
  * Pure, like the rest of the engine: `now` is injected and the rules arrive
  * pre-loaded once per catalog request, never per product.
  */

package/src/engine/pt-BR.ts

@@ -33,6 +33,7 @@ export const PT_BR_DISCOUNT_REJECTION_COPY: DiscountRejectionCopy = {
   MIN_SUBTOTAL_NOT_MET: `Este cupom exige um pedido mínimo de ${MIN_SUBTOTAL_TOKEN}.`,
   USAGE_LIMIT_REACHED: "Este cupom já atingiu o limite de uso.",
   BUYER_LIMIT_REACHED: "Você já usou este cupom.",
+  NOT_FIRST_ORDER: "Só vale na primeira compra nesta loja.",
   NO_ELIGIBLE_ITEMS: "Este cupom não vale para os itens do seu carrinho.",
   COMBO_NOT_MATCHED: "Seu carrinho ainda não tem todos os itens deste combo.",
   ZERO_VALUE: "Este cupom não vale para os itens do seu carrinho.",

package/src/engine/teaser.ts

@@ -102,6 +102,9 @@ function isTeasable(rule: DiscountRule, now: Date, localNow: LocalClock | null):
  */
 function isTeasableShape(rule: DiscountRule): boolean {
   if (rule.trigger !== "AUTOMATIC" || !rule.active || rule.scope === "ORDER") return false;
+  // A first-purchase rule is never teased: a card cannot know the buyer, and a
+  // returning one would be promised a price the cart refuses (FUT-2825).
+  if (rule.firstOrderOnly === true) return false;
   return rule.schedule !== null && rule.schedule !== undefined;
 }
 

package/src/engine/types.ts

@@ -121,6 +121,23 @@ export interface DiscountRule {
   perBuyerLimit: number | null;
   /** Redemptions this buyer has already PAID for. 0 for an anonymous cart. */
   buyerUsageCount: number;
+  /**
+   * The rule applies only to a buyer's FIRST purchase at the store
+   * (FUT-2825). Omitted = false, which is every rule that predates it.
+   *
+   * OPTIONAL for the reason `schedule` is: an adopter that does not offer
+   * first-purchase promotions keeps compiling, and keeps pricing exactly as
+   * before.
+   */
+  firstOrderOnly?: boolean;
+  /**
+   * Whether THIS buyer has no purchase at the store yet — the host's answer,
+   * since only the host knows its orders. `null` or omitted = unknown (an
+   * anonymous cart, the cached menu), which is NOT first-time: a discount the
+   * cart shows and checkout then takes away is worse than one that appears
+   * once the buyer is known.
+   */
+  buyerIsFirstTime?: boolean | null;
   /** False ⇒ exclusive: if it wins, nothing else applies. */
   stackable: boolean;
   /** Deterministic tie-break key, ascending. */

package/src/react/api.ts

@@ -36,6 +36,8 @@ export interface DiscountWireRecord {
   minSubtotalCents: number | null;
   usageLimit: number | null;
   perBuyerLimit: number | null;
+  /** Only a buyer's first purchase at the store (FUT-2825); absent = false. */
+  firstOrderOnly?: boolean;
   usageCount: number;
   stackable: boolean;
   active: boolean;
@@ -98,6 +100,8 @@ export interface DiscountFormPayload {
   usageLimit: string;
   perBuyerLimit: string;
   stackable: boolean;
+  /** The first-purchase switch (FUT-2825); absent = false. */
+  firstOrderOnly?: boolean;
   active: boolean;
   categoryIds: string[];
   menuItemIds: string[];
@@ -182,6 +186,7 @@ export function toWriteBody(
     usageLimit: toCount(input.usageLimit, formatters),
     perBuyerLimit: toCount(input.perBuyerLimit, formatters),
     stackable: input.stackable,
+    firstOrderOnly: input.firstOrderOnly === true,
     active: input.active,
     // Narrowed to the scope on the way OUT as well as on the way in: leaving a
     // stale id list on a rule whose scope changed is how a promotion goes on

package/src/react/copy.ts

@@ -51,6 +51,8 @@ export interface DiscountsScreenCopy {
   readonly empty: string;
   /** The exported file's base name, without extension. */
   readonly exportFileName: string;
+  /** The header's export trigger. */
+  readonly exportAction: string;
   /** While the first page is loading. */
   readonly loading: string;
   /** The read failed: a heading, and the button that tries again. */
@@ -142,6 +144,9 @@ export interface DiscountsFormCopy {
   readonly activeHint: string;
   readonly stackable: string;
   readonly stackableHint: string;
+  /** The first-purchase condition (FUT-2825), and what it does to the menu. */
+  readonly firstOrderOnly: string;
+  readonly firstOrderOnlyHint: string;
   /** The banner over a form the operator must fix before it will send. */
   readonly reviewFields: string;
   /** The banner over a write the SERVER refused. */

package/src/react/discount-form.tsx

@@ -15,6 +15,7 @@ import { Stack } from "@12-apps/ui/mui/Stack";
 import type { DiscountSchedule } from "../engine/schedule";
 import type { ComboRequirement } from "../engine/types";
 
+import { FirstOrderField } from "./first-order-field";
 import type { DiscountFormPayload, DiscountsApiClient, DiscountWireRecord, WireTargetGroup } from "./api";
 import type { DiscountsWebCopy } from "./copy";
 import {
@@ -51,10 +52,16 @@ import type { DiscountsFormatters } from "./format";
  * `setFieldErrors` and paints the same inputs red.
  */
 
+/** A stored rule's first-purchase switch (FUT-2825); off for a new rule and an older record. */
+function savedFirstOrderOnly(editing: DiscountWireRecord | null): boolean {
+  return editing !== null && editing.firstOrderOnly === true;
+}
+
 /** The values `total-form` cannot hold, kept beside it and merged at submit. */
 function useNonStringState(editing: DiscountWireRecord | null) {
   const [active, setActive] = useState<boolean>(editing?.active ?? true);
   const [stackable, setStackable] = useState<boolean>(editing?.stackable ?? true);
+  const [firstOrderOnly, setFirstOrderOnly] = useState<boolean>(() => savedFirstOrderOnly(editing));
   const [categoryIds, setCategoryIds] = useState<string[]>(editing?.categoryIds ?? []);
   const [menuItemIds, setMenuItemIds] = useState<string[]>(editing?.menuItemIds ?? []);
   // The combo's groups are the third array, and the one whose ORDER matters:
@@ -81,6 +88,7 @@ function useNonStringState(editing: DiscountWireRecord | null) {
   return {
     active,
     stackable,
+    firstOrderOnly,
     categoryIds,
     menuItemIds,
     comboRequirements,
@@ -88,6 +96,7 @@ function useNonStringState(editing: DiscountWireRecord | null) {
     schedule,
     setActive,
     setStackable,
+    setFirstOrderOnly,
     setCategoryIds,
     setMenuItemIds,
     setComboRequirements,
@@ -153,6 +162,7 @@ function makeSubmit(
       ...typeAndScopeFor(values),
       ...targets,
       stackable: extra.stackable,
+      firstOrderOnly: extra.firstOrderOnly,
       active: extra.active,
     };
     const result = editing
@@ -211,6 +221,11 @@ export function DiscountForm(props: DiscountFormProps): JSX.Element {
           onScheduleEnabledChange={extra.setScheduleEnabled}
         />
         <LimitFields copy={copy} currencyField={currencyField} />
+        <FirstOrderField
+          copy={copy}
+          checked={extra.firstOrderOnly}
+          onChange={extra.setFirstOrderOnly}
+        />
         <DiscountSwitches
           copy={copy}
           active={extra.active}

package/src/react/discounts-screen.tsx

@@ -115,11 +115,12 @@ function HeaderControls({
 }): JSX.Element {
   return (
     <>
-      <Dashboard.Info title={copy.screen.aboutTitle}>
+      <Dashboard.Info title={copy.screen.aboutTitle} ariaLabel={copy.screen.aboutTitle}>
         {copy.screen.aboutBody}
       </Dashboard.Info>
       <Dashboard.Spacer />
       <Dashboard.Export
+        label={copy.screen.exportAction}
         formats={[
           { id: "csv", label: "CSV (.csv)" },
           { id: "json", label: "JSON (.json)" },

package/src/react/en-US.ts

@@ -31,6 +31,7 @@ export const EN_US_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     empty: "No discounts yet.",
     // A FILENAME, not a sentence: it is what the export lands on disk as.
     exportFileName: "discounts",
+    exportAction: "Export",
     loading: "Loading discounts…",
     loadFailed: "Could not load the discounts",
     retry: "Try again",
@@ -167,6 +168,9 @@ export const EN_US_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     stackable: "Stackable",
     stackableHint:
       "When off, this promotion is exclusive: if it wins, no other one is applied.",
+    firstOrderOnly: "Only on the customer's first purchase at this store",
+    firstOrderOnlyHint:
+      "Only for customers who have never bought here. Menu prices do not change: the discount shows in the cart of whoever can use it.",
     reviewFields: "Check the highlighted fields.",
     saveFailed: "Could not save the discount",
     nameRequired: "Give the promotion a name.",

package/src/react/first-order-field.tsx

@@ -0,0 +1,40 @@
+import type { JSX } from "react";
+
+import { Switch } from "@12-apps/ui/form/Switch";
+import { useFormContext } from "@12-apps/ui/form/total-form";
+
+import type { DiscountsWebCopy } from "./copy";
+import { isComboKind } from "./form-kind";
+
+/**
+ * "Só na primeira compra do cliente nesta loja" (FUT-2825).
+ *
+ * Offered at the ORDER, CATEGORY and ITEM scopes only. A combo keeps its own
+ * rules — "leve 3, pague 2" is a deal about the basket, not about who is
+ * buying — so the switch is not drawn for one, and the server folds a combo's
+ * value to false whatever a body sends.
+ *
+ * Its state is the parent's, like the two switches below it, so submit can
+ * send it: `total-form` holds strings.
+ */
+export function FirstOrderField({
+  copy,
+  checked,
+  onChange,
+}: {
+  copy: DiscountsWebCopy;
+  checked: boolean;
+  onChange: (next: boolean) => void;
+}): JSX.Element | null {
+  const { values } = useFormContext();
+  if (isComboKind(values.kind ?? "PERCENTAGE") || values.scope === "COMBO") return null;
+  return (
+    <Switch
+      checked={checked}
+      onChange={(event) => onChange(event.target.checked)}
+      label={copy.form.firstOrderOnly}
+      description={copy.form.firstOrderOnlyHint}
+      dataTestId="discount-first-order-only"
+    />
+  );
+}

package/src/react/pt-BR.ts

@@ -26,6 +26,7 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     create: "Novo desconto",
     empty: "Nenhum desconto cadastrado.",
     exportFileName: "descontos",
+    exportAction: "Exportar",
     loading: "Carregando descontos…",
     loadFailed: "Não foi possível carregar os descontos",
     retry: "Tentar novamente",
@@ -157,6 +158,9 @@ export const PT_BR_DISCOUNTS_WEB_COPY: DiscountsWebCopy = {
     stackable: "Acumulável",
     stackableHint:
       "Quando desligado, esta promoção é exclusiva: se vencer, nenhuma outra é aplicada.",
+    firstOrderOnly: "Só na primeira compra do cliente nesta loja",
+    firstOrderOnlyHint:
+      "Vale só para quem nunca comprou aqui. O preço do cardápio não muda: o desconto aparece no carrinho de quem pode usar.",
     reviewFields: "Revise os campos destacados.",
     saveFailed: "Não foi possível salvar o desconto",
     nameRequired: "Informe o nome da promoção.",

package/src/server/mcp.ts

@@ -127,6 +127,7 @@ export const discountSchema = z.object({
   minSubtotalCents: z.number().int().nullable(),
   usageLimit: z.number().int().nullable(),
   perBuyerLimit: z.number().int().nullable(),
+  firstOrderOnly: z.boolean().optional(),
   usageCount: z.number().int(),
   stackable: z.boolean(),
   active: z.boolean(),
@@ -185,6 +186,7 @@ const discountWriteShape = {
   minSubtotalCents: z.number().int().positive().nullable().optional(),
   usageLimit: z.number().int().positive().nullable().optional(),
   perBuyerLimit: z.number().int().positive().nullable().optional(),
+  firstOrderOnly: z.boolean().optional(),
   stackable: z.boolean(),
   active: z.boolean(),
   categoryIds: z.array(z.string().min(1)).optional(),

package/src/server/store.ts

@@ -44,6 +44,11 @@ export interface DiscountRecord {
   minSubtotalCents: number | null;
   usageLimit: number | null;
   perBuyerLimit: number | null;
+  /**
+   * Only a buyer's first purchase at the store (FUT-2825). OPTIONAL for the
+   * reason `schedule` is: a host without the column answers the same record.
+   */
+  firstOrderOnly?: boolean;
   usageCount: number;
   stackable: boolean;
   active: boolean;

package/src/server/validate.ts

@@ -63,6 +63,11 @@ export interface DiscountWriteInput {
   minSubtotalCents: number | null;
   usageLimit: number | null;
   perBuyerLimit: number | null;
+  /**
+   * Only a buyer's FIRST purchase at the store (FUT-2825). Optional for the
+   * reason `schedule` is; omitted = false.
+   */
+  firstOrderOnly?: boolean;
   stackable: boolean;
   active: boolean;
   /** Target category ids — read only when `scope === "CATEGORY"`. */
@@ -235,6 +240,8 @@ export interface DiscountScalars {
   minSubtotalCents: number | null;
   usageLimit: number | null;
   perBuyerLimit: number | null;
+  /** Only a buyer's first purchase at the store. Always false on a COMBO. */
+  firstOrderOnly: boolean;
   stackable: boolean;
   active: boolean;
 }
@@ -292,11 +299,21 @@ export function toDiscountScalars(
     minSubtotalCents: input.minSubtotalCents,
     usageLimit: input.usageLimit,
     perBuyerLimit: input.perBuyerLimit,
+    firstOrderOnly: firstOrderOnlyOf(input),
     stackable: input.stackable,
     active: input.active,
   };
 }
 
+/**
+ * A combo keeps its own rules (FUT-2825): the form never offers the condition
+ * there, and a body that sends it anyway is folded to false, the way a code
+ * left behind by flipping the trigger is folded to null.
+ */
+function firstOrderOnlyOf(input: DiscountWriteInput): boolean {
+  return input.scope !== "COMBO" && input.firstOrderOnly === true;
+}
+
 /**
  * The validated wire body as the routes receive it — every optional field is
  * `T | null | undefined` because the wire lets a client omit what does not
@@ -322,6 +339,7 @@ export interface DiscountWriteBody {
   minSubtotalCents?: number | null;
   usageLimit?: number | null;
   perBuyerLimit?: number | null;
+  firstOrderOnly?: boolean;
   stackable: boolean;
   active: boolean;
   categoryIds?: string[];
@@ -357,6 +375,7 @@ export function toDiscountWriteInput(body: DiscountWriteBody): DiscountWriteInpu
     minSubtotalCents: orNull(body.minSubtotalCents),
     usageLimit: orNull(body.usageLimit),
     perBuyerLimit: orNull(body.perBuyerLimit),
+    firstOrderOnly: body.firstOrderOnly === true,
     stackable: body.stackable,
     active: body.active,
     categoryIds: orEmpty(body.categoryIds),