@12-apps/discounts 1.0.0

package/README.md

@@ -0,0 +1,110 @@
+# @12-apps/discounts
+
+The discount / promotion domain, extracted from its origin host and made
+host-agnostic: an **evaluator** that decides what a cart actually pays, and an
+**admin CRUD surface** shipped as wiring-contract route descriptors over a
+store port.
+
+No database, no framework, no clock, and **no baked user copy**.
+
+## What is in the box
+
+| entry | what it is |
+|---|---|
+| `@12-apps/discounts` | the engine: `evaluateDiscounts`, `previewItemDiscount`, the vocabulary, the rejection copy port |
+| `@12-apps/discounts/pt-BR` | the pt-BR rejection pack, imported by hand |
+| `@12-apps/discounts/server` | `createApiDiscounts`, the `DiscountStore` port, the permission contribution, the MCP tools |
+| `@12-apps/discounts/server/pt-BR` | the pt-BR pack for the admin surface's sentences |
+| `@12-apps/discounts/manifest` | the shared wiring manifest |
+| `@12-apps/discounts/manifest/server` | the `http` capability |
+
+## The model
+
+A discount is a **percentage** (basis points, 1..10000) or a **fixed amount**
+(integer cents), scoped to the whole **order**, to **categories**, or to
+specific **items**, fired either **automatically** when its conditions hold or
+by the buyer typing a **coupon code**. Money is integer cents throughout; a
+percentage is basis points, so "12,5%" needs no decimal column anywhere.
+
+The evaluator is a pure function of `{ lines, rules, couponCode, now }`:
+
+```ts
+import { evaluateDiscounts } from "@12-apps/discounts";
+
+const outcome = evaluateDiscounts({ lines, rules, couponCode, now: new Date() });
+// outcome.subtotalCents, .discountTotalCents, .totalCents
+// outcome.applied[]   — what removed money, frozen for the order snapshot
+// outcome.lines[]     — per-line cents removed; Σ equals discountTotalCents
+// outcome.rejections[] — only for what the buyer ASKED for, or lost a stack race
+```
+
+Three properties it holds to the cent, and the suite pins each:
+
+- `Σ applied[].amountCents === discountTotalCents === Σ lines[].discountCents`;
+- narrowest scope first, so an order-wide promo can never give away money an
+  item-level promo already removed;
+- a discounted order is never worth **less than one cent**. That is a payment
+  constraint, not a pricing one — providers reject a zero-amount charge, so an
+  order discounted to nothing could never be settled at all. The floor is
+  applied *during* allocation, never as a post-hoc trim, which is what keeps
+  the sum identity above true.
+
+`previewItemDiscount` answers the other question — what a catalog card should
+strike through *before* there is a cart — from the same rules, so a card and a
+cart cannot quote different numbers.
+
+## The admin surface
+
+`createApiDiscounts({ store, copy })` returns five `WireRoute` descriptors —
+list, read, create, re-state, archive — each **declaring the permission it
+needs** (`discounts:read` / `discounts:write`), so a host's coverage gates can
+read the policy off the assembled table instead of scanning route files.
+
+```ts
+import { createApiDiscounts } from "@12-apps/discounts/server";
+import { PT_BR_DISCOUNTS_SERVER_COPY } from "@12-apps/discounts/server/pt-BR";
+
+const { routes } = createApiDiscounts({ store, copy: PT_BR_DISCOUNTS_SERVER_COPY });
+```
+
+Or, through the contract:
+
+```ts
+import { discountsManifest } from "@12-apps/discounts/manifest";
+import { discountsServerManifest } from "@12-apps/discounts/manifest/server";
+
+host.adoptServer({
+  manifest: discountsManifest,
+  server: discountsServerManifest,
+  bindings: { http: { mountPath: "/api/admin/:tenantSlug", config: { store, copy } } },
+});
+```
+
+Delete is a **soft archive**, and that is a product decision: the orders that
+already redeemed a discount keep their snapshot, and its redemption counter
+stays readable for reporting.
+
+## What the host still owns
+
+**The database.** A discount's rows relate to a host's own catalog and orders —
+targets point at its categories and items, redemptions at its orders and its
+buyers — so neither wiring `db` mode qualifies and the manifest declares none.
+The host owns the schema, the tenant scoping, the transactions and the
+uniqueness conflicts, and answers the `DiscountStore` port. What travels is the
+RULE, not the storage.
+
+**Every sentence a human reads.** `DiscountRejectionCopy` (buyer-facing) and
+`DiscountsServerCopy` (operator-facing) are required config with **no
+defaults** — `createApiDiscounts` throws at construction naming every missing
+key. pt-BR packs ship as named exports a host passes by hand, so choosing a
+language is a line in the host's diff rather than a silence.
+
+**Who is calling, and whether the plan allows it.** The actor arrives already
+resolved (`{ clientId }`); authentication, tenant resolution, RBAC tiers and
+plan gates stay where they belong.
+
+**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
+a host extends the advertised list query and reads its own key back out in its
+store. See `DiscountListInput`.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@12-apps/discounts",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "The discount/promotion domain: a host-agnostic evaluator (percentage or fixed amount, order/category/item scope, automatic or coupon-triggered, stacking and exclusivity, integer-cent allocation) plus the admin CRUD surface as wiring-contract route descriptors over a store port. No database, no framework, no baked user copy.",
+  "exports": {
+    ".": "./src/index.ts",
+    "./pt-BR": "./src/engine/pt-BR.ts",
+    "./server": "./src/server/index.ts",
+    "./server/pt-BR": "./src/server/pt-BR.ts",
+    "./manifest": "./src/manifest/index.ts",
+    "./manifest/server": "./src/manifest/server.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules coverage dist",
+    "test": "node ../../scripts/vitest-with-teardown.mjs run",
+    "test:watch": "vitest watch",
+    "lint": "eslint src --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@12-apps/shared-helpers": "^2.0.1",
+    "zod": "^4.3.5"
+  },
+  "peerDependencies": {
+    "@12-apps/wiring": ">=1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@12-apps/wiring": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@12-apps/eslint-config": "^1.21.0",
+    "@12-apps/typescript-config": "^1.20.0",
+    "@12-apps/wiring": "^1.5.0",
+    "@types/node": "^22.10.6",
+    "eslint": "^9.39.1",
+    "eslint-plugin-test-flakiness": "^1.4.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/12-apps/shared-packages.git",
+    "directory": "packages/discounts"
+  },
+  "files": [
+    "src",
+    "dist",
+    "*.js",
+    "*.mjs",
+    "*.md",
+    "!eslint.config.js",
+    "!**/__tests__/**",
+    "!**/tests/**",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.stories.*",
+    "!**/*.test-story.*",
+    "!**/test-helpers.*"
+  ]
+}

package/src/engine/allocate.ts

@@ -0,0 +1,133 @@
+import { MAX_PERCENT_OFF_BP, MIN_PAYABLE_TOTAL_CENTS } from "./kinds";
+import type { DiscountRule } from "./types";
+
+/**
+ * MONEY side of the discount evaluator (FUT-245): rules R5 (how many cents one
+ * discount is worth against a base) and R7 (how those cents are split across
+ * the lines it covers), from the numbered rule set in `./evaluate.ts`.
+ *
+ * Everything here is integer cents. The single float division lives in the
+ * largest-remainder method and is bounded — both operands are well under 2^31,
+ * so `amount * remaining` never leaves the exactly-representable integer range
+ * and the fraction is only ever used as a SORT KEY, never as money.
+ *
+ * Kept in its own module because it is the part a reviewer wants to read (and
+ * a test wants to drive) on its own, without a cart around it.
+ */
+
+/**
+ * R5 — the raw value of one discount against a base.
+ *
+ * `PERCENTAGE` FLOORS: the house absorbs the sub-cent, never the buyer's total
+ * drifting negative. `FIXED_AMOUNT` is clamped to the base, so "R$ 20 off" on a
+ * base of R$ 12 removes R$ 12 and never issues a credit. A result of 0 means
+ * the discount must NOT be applied — an `R$ 0,00` line is not a promotion.
+ */
+export function rawAmountCents(rule: DiscountRule, baseCents: number): number {
+  if (baseCents <= 0) return 0;
+  const raw =
+    rule.type === "PERCENTAGE"
+      ? Math.floor((baseCents * (rule.percentOffBp ?? 0)) / MAX_PERCENT_OFF_BP)
+      : (rule.amountOffCents ?? 0);
+  return Math.max(0, Math.min(raw, baseCents));
+}
+
+/**
+ * R9 — the most that may ever be taken off a gross amount: everything above
+ * `MIN_PAYABLE_TOTAL_CENTS`, because an order the provider cannot charge is
+ * worse for the buyer than an order that costs one cent more (see the constant's
+ * own prose for the payment-path reason).
+ *
+ * A gross of zero returns zero, not a negative number: an empty cart, or one
+ * holding only free items, stays at zero and simply gets no discount. The floor
+ * caps what a promotion may remove; it never manufactures a total out of
+ * nothing, and it can never push a total ABOVE its own subtotal.
+ *
+ * This is the ONE place the floor becomes a number. The evaluator measures its
+ * per-application headroom against it (`./evaluate-passes.ts`), the final total
+ * is re-clamped with it (`./evaluate.ts`) and the menu badge caps its previewed
+ * price with it (`./preview.ts`) — three surfaces, one rule, so a card can never
+ * advertise a price the cart would refuse to honour.
+ */
+export function maxDiscountableCents(grossCents: number): number {
+  if (grossCents <= 0) return 0;
+  return Math.max(0, grossCents - MIN_PAYABLE_TOTAL_CENTS);
+}
+
+interface AllocationPart {
+  lineId: string;
+  /** Position in the input map — the last, stable tie-break. */
+  index: number;
+  remainingCents: number;
+  flooredCents: number;
+  /** `exact - floor`, a sort key only. */
+  fraction: number;
+}
+
+function toParts(
+  amountCents: number,
+  entries: readonly (readonly [string, number])[],
+  baseTotalCents: number,
+): AllocationPart[] {
+  return entries.map(([lineId, remainingCents], index) => {
+    const exact = (amountCents * remainingCents) / baseTotalCents;
+    const flooredCents = Math.floor(exact);
+    return { lineId, index, remainingCents, flooredCents, fraction: exact - flooredCents };
+  });
+}
+
+/** Largest remainder first, then the bigger line, then input order. */
+function compareParts(a: AllocationPart, b: AllocationPart): number {
+  if (a.fraction !== b.fraction) return b.fraction - a.fraction;
+  if (a.remainingCents !== b.remainingCents) return b.remainingCents - a.remainingCents;
+  return a.index - b.index;
+}
+
+/**
+ * The invariant this whole module exists for: the parts must reconstitute the
+ * whole. A leak here would show up as an order whose `discount_total_cents`
+ * disagrees with the sum of its `order_items.discount_cents`, which is exactly
+ * the reconciliation the COGS engine already refuses to let drift.
+ */
+function assertAllocationSums(
+  allocation: ReadonlyMap<string, number>,
+  amountCents: number,
+): void {
+  let total = 0;
+  for (const cents of allocation.values()) total += cents;
+  if (total !== amountCents) {
+    throw new Error(`Discount allocation summed to ${total}, expected ${amountCents}`);
+  }
+}
+
+/**
+ * R7 — split `amountCents` across the covered lines in proportion to what is
+ * still discountable on each of them, by the LARGEST-REMAINDER method: floor
+ * every share, then hand the leftover cents one at a time to the lines with the
+ * biggest discarded fraction. The parts therefore sum to `amountCents` exactly,
+ * with no per-line rounding leak, and no line is ever allocated more than it had
+ * remaining (a line's exact share can only reach its remaining when the discount
+ * takes the whole base, in which case there is no leftover cent to hand out).
+ *
+ * A base of zero — every covered line already fully discounted, or free — gives
+ * an all-zero allocation; R5 has already turned that case into a rejection.
+ */
+export function allocateByLargestRemainder(
+  amountCents: number,
+  remaining: ReadonlyMap<string, number>,
+): Map<string, number> {
+  const entries = [...remaining.entries()];
+  const allocation = new Map<string, number>(entries.map(([lineId]) => [lineId, 0]));
+  const baseTotalCents = entries.reduce((sum, [, cents]) => sum + cents, 0);
+  if (amountCents <= 0 || baseTotalCents <= 0) return allocation;
+
+  const parts = toParts(amountCents, entries, baseTotalCents);
+  let deficit = amountCents - parts.reduce((sum, part) => sum + part.flooredCents, 0);
+  for (const part of [...parts].sort(compareParts)) {
+    const bonus = deficit > 0 ? 1 : 0;
+    deficit -= bonus;
+    allocation.set(part.lineId, part.flooredCents + bonus);
+  }
+  assertAllocationSums(allocation, amountCents);
+  return allocation;
+}

package/src/engine/eligibility.ts

@@ -0,0 +1,160 @@
+import type { DiscountRejectionReason } from "./kinds";
+import type { DiscountCartLine, DiscountRule } from "./types";
+
+/**
+ * ELIGIBILITY side of the discount evaluator (FUT-245): rules R2 (the screen)
+ * and R3 (the covered set) of the numbered rule set documented in
+ * `./evaluate.ts`. Pure — no database, no clock, no I/O; `now` arrives inside the
+ * context the caller builds, exactly like `composeSelection` takes its live
+ * catalog config rather than reading it.
+ *
+ * R3 is deliberately expressed as a REVERSE index built once per evaluation
+ * (`buildLineIndex`) and then read with `Map`/`Set` lookups: matching every
+ * target against every line would be the loop-inside-a-loop the quality gate
+ * bans, and a whole menu page's badge preview (FUT-246) walks this path.
+ */
+
+/**
+ * The cart facts R2 screens a rule against. All resolved by the caller.
+ *
+ * Not exported: callers pass an object literal, and knip fails the build on an
+ * export nothing imports (`quality:knip` — "ship the consumer with the export").
+ */
+interface ScreenContext {
+  /** Evaluation instant. Injected — this module never calls `new Date()`. */
+  now: Date;
+  /**
+   * The PRE-discount cart subtotal. Always the untouched subtotal, never a
+   * running total: that is what makes the result independent of the order the
+   * discounts happen to be applied in.
+   */
+  subtotalCents: number;
+  /** Whether R3's covered set came back non-empty for this rule. */
+  hasEligibleItems: boolean;
+}
+
+/**
+ * Lines of the cart indexed by everything a discount can target, so R3 is a
+ * `Map` read per target instead of a scan per line.
+ */
+export interface LineIndex {
+  /** Category id (own or any ancestor) → the lines filed under it. */
+  byCategory: ReadonlyMap<string, readonly string[]>;
+  /** Menu-item id (base or chosen variation) → the lines carrying it. */
+  byMenuItem: ReadonlyMap<string, readonly string[]>;
+}
+
+type IndexPair = readonly [key: string, lineId: string];
+
+function groupLineIds(pairs: readonly IndexPair[]): Map<string, string[]> {
+  const grouped = new Map<string, string[]>();
+  for (const [key, lineId] of pairs) {
+    const bucket = grouped.get(key);
+    if (bucket) bucket.push(lineId);
+    else grouped.set(key, [lineId]);
+  }
+  return grouped;
+}
+
+/**
+ * A line is reachable by an ITEM-scoped discount through its BASE (grouping)
+ * item — the card the admin actually picked — or through the variation the
+ * buyer chose, so "50% off Coca" still fires on "Coca zero lata".
+ */
+function menuItemPairs(line: DiscountCartLine): IndexPair[] {
+  return [line.menuItemId, line.variationMenuItemId]
+    .filter((id): id is string => id !== null)
+    .map((id) => [id, line.lineId] as const);
+}
+
+function categoryPairs(line: DiscountCartLine): IndexPair[] {
+  return line.categoryPath.map((categoryId) => [categoryId, line.lineId] as const);
+}
+
+/** Build the per-evaluation reverse index R3 reads. */
+export function buildLineIndex(lines: readonly DiscountCartLine[]): LineIndex {
+  return {
+    byCategory: groupLineIds(lines.flatMap(categoryPairs)),
+    byMenuItem: groupLineIds(lines.flatMap(menuItemPairs)),
+  };
+}
+
+function addAll(target: Set<string>, lineIds: readonly string[] | undefined): void {
+  for (const lineId of lineIds ?? []) target.add(lineId);
+}
+
+/**
+ * R3 — the covered set: which of the cart's lines this discount is allowed to
+ * touch. `ORDER` covers everything; `CATEGORY` covers every line whose category
+ * PATH (own category followed by its ancestors) intersects the targets, so a
+ * discount on a top-level category automatically reaches items filed under its
+ * subcategories; `ITEM` covers every line whose base or variation menu item is
+ * targeted.
+ */
+export function coveredLineIds(
+  rule: DiscountRule,
+  lines: readonly DiscountCartLine[],
+  index: LineIndex,
+): ReadonlySet<string> {
+  if (rule.scope === "ORDER") return new Set(lines.map((line) => line.lineId));
+  const byCategory = rule.scope === "CATEGORY";
+  const targets = byCategory ? rule.targetCategoryIds : rule.targetMenuItemIds;
+  const bucket = byCategory ? index.byCategory : index.byMenuItem;
+  const covered = new Set<string>();
+  for (const target of targets) addAll(covered, bucket.get(target));
+  return covered;
+}
+
+/**
+ * The scheduling half of R2: switched off, not started yet, or already over.
+ * The window is the HALF-OPEN interval `[startsAt, endsAt)` — `endsAt` is
+ * exclusive, so an admin who sets it to midnight of the next day means exactly
+ * that and not "one more day".
+ */
+function screenWindow(rule: DiscountRule, now: Date): DiscountRejectionReason | null {
+  if (!rule.active) return "INACTIVE";
+  if (rule.startsAt !== null && now.getTime() < rule.startsAt.getTime()) return "NOT_STARTED";
+  if (rule.endsAt !== null && now.getTime() >= rule.endsAt.getTime()) return "EXPIRED";
+  return null;
+}
+
+/**
+ * The counting half of R2: the two redemption caps and the minimum-subtotal
+ * threshold. `buyerUsageCount` is advisory — it is counted from PAID orders at
+ * evaluation time, so two concurrent first-time orders by the same buyer can
+ * both pass; the global cap is what the PAID-time predicated UPDATE enforces.
+ */
+function screenLimits(rule: DiscountRule, ctx: ScreenContext): DiscountRejectionReason | null {
+  if (rule.usageLimit !== null && rule.usageCount >= rule.usageLimit) {
+    return "USAGE_LIMIT_REACHED";
+  }
+  if (rule.perBuyerLimit !== null && rule.buyerUsageCount >= rule.perBuyerLimit) {
+    return "BUYER_LIMIT_REACHED";
+  }
+  if (rule.minSubtotalCents !== null && ctx.subtotalCents < rule.minSubtotalCents) {
+    return "MIN_SUBTOTAL_NOT_MET";
+  }
+  return null;
+}
+
+/**
+ * R2 — the eligibility screen. Returns the FIRST failing predicate's reason, or
+ * null when the rule is a live candidate. The order is not arbitrary: it runs
+ * from the least to the most cart-specific reason so the message the buyer ends
+ * up seeing is the most useful one ("expirado" beats "não vale para os itens do
+ * seu carrinho" for a coupon that is both).
+ *
+ * The coupon-match predicate is NOT here: a CODE-triggered rule the buyer did
+ * not type is not a rejection, it is simply not a candidate, and the caller
+ * drops it silently.
+ */
+export function screenRule(
+  rule: DiscountRule,
+  ctx: ScreenContext,
+): DiscountRejectionReason | null {
+  const scheduling = screenWindow(rule, ctx.now);
+  if (scheduling !== null) return scheduling;
+  const limits = screenLimits(rule, ctx);
+  if (limits !== null) return limits;
+  return ctx.hasEligibleItems ? null : "NO_ELIGIBLE_ITEMS";
+}