@endora-commerce/mod-promotions 0.100.0

package/dist/migrations/index.js

@@ -0,0 +1,44 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent — *"the `./migrations` export of
+ * @endora-commerce/mod-promotions exports no 'migrations' array"* (D-168).
+ *
+ * **Listed in ascending timestamp, which orders this module's own migrations and
+ * nothing else** (feature 081). Where this block sits relative to
+ * every other module's is decided by the manifest `dependencies` graph:
+ * `promotions` declares `orders`, and
+ * `…T081251_…_promotion_usage_order_fk` is why — it adds
+ * `promotion_usages_order_fk` (`promotion_usages.order_id` -> `orders.id`,
+ * `on delete restrict`), so `orders`' tables must already exist when this block
+ * runs. A foreign key needs the **table**, never the owner's entity class
+ * (D-169), which is what lets that constraint stand while `./backend` publishes
+ * no entity class by name.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no named class (D-168) — is deliberate.
+ * `db/migrations-registry.generated.ts` imports each class by name from this
+ * specifier and hands it to `migration('promotions', …)`, and a migration class
+ * name is contract in a way an entity class name is not:
+ * `mikro_orm_migrations` persists it, so it is a string every already-migrated
+ * database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260505T074605PromotionsCriteria } from './20260505T074605_promotions_criteria.js';
+import { Migration20260618T100727PromotionsEngine } from './20260618T100727_promotions_engine.js';
+import { Migration20260818T081251PromotionsPromotionUsageOrderFk } from './20260818T081251_promotions_promotion_usage_order_fk.js';
+import { Migration20260912T094715PromotionsSalesChannelPromotions } from './20260912T094715_promotions_sales_channel_promotions.js';
+export const migrations = [
+    Migration20260505T074605PromotionsCriteria,
+    Migration20260618T100727PromotionsEngine,
+    Migration20260818T081251PromotionsPromotionUsageOrderFk,
+    Migration20260912T094715PromotionsSalesChannelPromotions,
+];
+export { Migration20260505T074605PromotionsCriteria, Migration20260618T100727PromotionsEngine, Migration20260818T081251PromotionsPromotionUsageOrderFk, Migration20260912T094715PromotionsSalesChannelPromotions, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,0CAA0C,EAAE,MAAM,0CAA0C,CAAC;AACtG,OAAO,EAAE,wCAAwC,EAAE,MAAM,wCAAwC,CAAC;AAClG,OAAO,EAAE,uDAAuD,EAAE,MAAM,0DAA0D,CAAC;AACnI,OAAO,EAAE,wDAAwD,EAAE,MAAM,0DAA0D,CAAC;AAEpI,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,0CAA0C;IAC1C,wCAAwC;IACxC,uDAAuD;IACvD,wDAAwD;CACzD,CAAC;AAEF,OAAO,EACL,0CAA0C,EAC1C,wCAAwC,EACxC,uDAAuD,EACvD,wDAAwD,GACzD,CAAC"}

package/dist/ports/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The `./ports` subpath — the port interfaces this module publishes, and
+ * **nothing that exists at runtime** (layout contract R8, D-169).
+ *
+ * `tsc` compiles this file to `export {};`, and that emitted empty module is the
+ * `default` condition's target. A `types`-only `exports` entry type-checks and
+ * then answers `ERR_PACKAGE_PATH_NOT_EXPORTED` to any consumer whose toolchain
+ * emits the import, which is every consumer that cannot prove the import is a
+ * type. The implementation stays in `../backend/services/promotion-service.ts`
+ * and is reached through the container name `promotionUsageFinalizer`, never
+ * through this subpath.
+ *
+ * No entity class leaves by this door either, type-only included: D-168 shut
+ * that door on `./backend` precisely so that a stranger's
+ * `import type { Promotion } from '<pkg>/backend'` is a compile error in the
+ * stranger's own tree, and erasure would make re-opening it free at runtime and
+ * permanent at compile time.
+ *
+ * `backend/test/unit/packages/module-package-ports-surface.test.ts` holds this
+ * file to all of that, over the real package.
+ */
+import type { EntityManager } from '@mikro-orm/postgresql';
+/**
+ * Who redeemed a promotion, as the usage row records it.
+ *
+ * It lives here rather than beside the implementation because
+ * {@link PromotionUsageFinalizer.finalizeUsage} names it: a published signature
+ * whose argument type is only reachable at a private path is a method a
+ * consumer cannot write a variable for. It carries no ORM type of its own and
+ * would be perfectly at home in `@endora-commerce/contracts` — it is here
+ * because the interface that names it cannot be, and splitting one signature
+ * across two packages buys nothing.
+ */
+export interface UsageContext {
+    organizationId: string | null;
+    customerAccountId: string | null;
+    customerGroupId: string | null;
+    /**
+     * The channel the order was placed through. Non-nullable (D-48): the one
+     * caller is `placeOrder`, which stamps the same id onto the order, and
+     * `promotion_usages.sales_channel_id` is `uuid not null`. It used to be
+     * `string | null` with a `?? randomUUID()` at the insert — issue #85's shape,
+     * one table over: a fabricated id in a column the statistics aggregates
+     * group by, so a usage row could never be joined back to a channel.
+     */
+    salesChannelId: string;
+}
+/** One promotion the placement applied, as the redemption row records it. */
+export interface FinalizeAppliedPromotion {
+    promotionId: string;
+    couponId: string | null;
+    amount: number;
+}
+/**
+ * The co-transactional half of the promotion seam, typed by its owner (D-94.5).
+ *
+ * `orders` used to declare this method itself, on a `PromotionPort` interface
+ * it wrote in `order-service.ts` and satisfied structurally. That is the shape
+ * D-77 rejected: `lazyPort<T>` is an unchecked cast, so with `T` on the
+ * consumer's side **nothing verifies that the provider still satisfies it** —
+ * `PromotionService.finalizeUsage` could have changed its parameter shape and
+ * `orders` would still have compiled. The interface therefore belongs to the
+ * provider, and until this module became a package "the provider" meant a
+ * relative import into `promotions/services/`, which is a reach into internals
+ * the owner never offered. It is the same interface on a subpath its owner
+ * declared: contract surface (D-171), which is what retires the
+ * `permanent: true` ledger entry that stood for it.
+ *
+ * It stays **out of `@endora-commerce/contracts`** on purpose. The first
+ * parameter is the caller's MikroORM `EntityManager`, and FR-034 forbids a
+ * MikroORM type in the contracts package — `admin` and `storefront` both
+ * compile it, which is why it holds zero `@mikro-orm` imports. That is what
+ * qualifies this interface for `./ports` rather than for the contracts package:
+ * the test is not *"is this a real published port"* but *"does this signature
+ * stop the interface living in `packages/contracts`"* (D-171).
+ *
+ * The seam is not a defect in the design, it *is* the design:
+ * `promotion_usages_order_fk` (`promotion_usages.order_id` -> `orders.id`,
+ * `on delete restrict`) means the redemption row cannot exist before the order
+ * does, and the order does not commit until `placeOrder` returns. A port that
+ * opened its own transaction could not satisfy a foreign key against a row it
+ * cannot see, and a cap hit at the last moment could no longer roll the order
+ * back with it. A foreign key needs the **table** and never the class (D-169),
+ * so that constraint stands while `./backend` publishes no entity class by
+ * name.
+ *
+ * The read half is not here. `applyToCart` is `PromotionApplyPort` in
+ * `@endora-commerce/contracts`, which `carts` already resolves under the same
+ * container name; the consumer-declared duplicate of it was deleted with
+ * `PromotionPort`.
+ */
+export interface PromotionUsageFinalizer {
+    /**
+     * Finalize usage for a placed order. **Must** run on the placement
+     * `EntityManager`: counters are bumped with `update … where count < limit`,
+     * so two carts racing for the final use can never both succeed, and a cap
+     * hit here throws 409 so the transaction rolls back.
+     */
+    finalizeUsage(em: EntityManager, input: {
+        orderId: string;
+        currency: string;
+        ctx: UsageContext;
+        applied: FinalizeAppliedPromotion[];
+    }): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/ports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,aAAa,CACX,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,GAAG,EAAE,YAAY,CAAC;QAClB,OAAO,EAAE,wBAAwB,EAAE,CAAC;KACrC,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/ports/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":""}

package/docs/promotions.md

@@ -0,0 +1,96 @@
+---
+title: promotions
+description: Cart-level percentage / amount / free-delivery discounts with eligibility filters
+---
+
+# `promotions`
+
+The promotions module is a configurable, rule-driven discount engine
+built on the original cart-discount slice. A **Promotion**
+pairs an eligibility **Rule** with an **Action**; the engine evaluates every
+active promotion against a cart, applies the matching ones in priority order,
+and surfaces the result in the cart and on the placed order.
+
+## Concepts
+
+- **Rule** — a typed AST (`all` | `condition` | `group`) over built-in cart
+  fields (cart total, payment method, delivery method, delivery country,
+  delivery postal code, organization, customer group, product category) and
+  promo-eligible product attributes. Conditions carry an operator
+  (`eq`/`neq`/`gt`/`gte`/`lt`/`lte`/`between`/`in`/`notIn`/`contains`/
+  `startsWith`) and values; groups combine children with `AND`/`OR` (max depth
+  5). A rule may be authored inline or referenced from the **named-rule**
+  library (`promotion_rules`).
+- **Action** — one configured effect from the registry. Built-ins:
+  `free_delivery`, `percentage_off_cart`, `amount_off_cart`,
+  `buy_x_get_y_free` (cheapest/most-expensive target), `spend_x_percent_off`,
+  `spend_x_amount_off`, `every_nth_product_percent_off`, `buy_x_units_y_free`,
+  `buy_x_units_percent_off`, `buy_x_units_amount_off`. Other modules register
+  additional action types via `PromotionActionRegistry.register(...)`.
+- **Priority & stacking** — eligible promotions apply in `priority` DESC order
+  (deterministic tie-break: `createdAt`, then `id`). A promotion flagged
+  `stopFurther` halts any lower-priority promotion. Discounts never push a
+  line, subtotal, delivery, or total below zero.
+- **Coupons** — a promotion may carry coupons (`promotion_coupons`): a single
+  specified code or a generated batch (`coupon_batches`). A couponed promotion
+  applies only when a matching code is presented. The legacy `promotions.code`
+  column is still honored.
+- **Usage limits** — optional global / per-organization / per-customer caps.
+  Coupon batches choose `per_coupon` vs `shared_batch` scoping for the global
+  pool. Usage is counted only on successful order placement.
+- **Statistics** — `promotion_usages` records each finalized redemption with
+  denormalized dimensions, aggregated into totals + breakdowns by customer,
+  customer group, organization, and sales channel.
+
+## Application flow
+
+1. `PromotionService.applyToCart(snapshot)` loads active promotions, resolves
+   any presented coupon code, soft-excludes exhausted promotions, evaluates
+   each rule, runs the action through the registry against running totals, and
+   returns the adjusted totals plus a per-promotion breakdown.
+2. The cart read path calls this on every read so the cart shows the real
+   discount amount and `appliedPromotions[]`.
+3. On order placement, the order service recomputes the application, stamps
+   `order_applied_promotions` + `orders.discount_total`, and **finalizes
+   usage** inside the placement transaction.
+
+## Usage finalization (race-safe)
+
+`finalizeUsage` runs inside the order-placement transaction. Each applicable
+scope counter is bumped with `UPDATE promotion_usage_counters SET count =
+count + 1 WHERE (scope_type, scope_key) = … AND count < :limit`. Zero rows
+affected means the cap was reached, so a `409 promotion_unavailable` is thrown
+and the whole placement rolls back. Two carts racing for the final use can
+never both succeed.
+
+## Public surface (admin, gated by `promotions:read|write|delete`)
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `GET/POST/PUT/DELETE /api/v1/admin/promotions[/:id]` | Promotion CRUD |
+| `GET /api/v1/admin/promotions/action-types` | Action catalogue for the editor |
+| `GET /api/v1/admin/promotions/rule-targets/attributes` | Promo-eligible attributes |
+| `POST /api/v1/admin/promotions/preview` | Apply against a `CartSnapshot` |
+| `GET/POST /api/v1/admin/promotions/:id/coupons` | Single-coupon management |
+| `POST /api/v1/admin/promotions/:id/coupon-batches` | Bulk generator |
+| `GET .../coupon-batches/:batchId/export` | CSV export of generated codes |
+| `GET /api/v1/admin/promotions/:id/stats` | Usage statistics |
+| `GET/POST/PUT/DELETE /api/v1/admin/promotion-rules[/:id]` | Named-rule library |
+
+Coupon redemption on the storefront flows through the existing cart coupon
+endpoints (`POST /api/v1/cart/coupon`), which resolve the code via the coupon
+table or the legacy column.
+
+## Permissions
+
+- `promotions:read` — view promotions, rules, coupons, statistics.
+- `promotions:write` — create + edit promotions and rules, manage coupons.
+- `promotions:delete` — delete promotions and rules.
+
+## Performance note
+
+Cart pricing loads active promotions with a single indexed query plus a
+coupon/counters lookup. At the platform's target scale this is sufficient; a
+Redis per-channel candidate cache (invalidated via the module-lifecycle
+pub/sub channel) is the documented next optimization if profiling shows the
+per-request load becomes hot — deliberately deferred under YAGNI until then.

package/i18n/en.json

@@ -0,0 +1,34 @@
+{
+  "actions.openPromotions.label": "Promotions",
+  "actions.openPromotions.description": "Manage promotions, discounts, coupons, and rules",
+  "actions.newPromotion.label": "New promotion",
+  "actions.newPromotion.description": "Create a new promotion",
+  "list.title": "Promotions",
+  "list.new": "New promotion",
+  "fields.name": "Name",
+  "fields.description": "Description",
+  "fields.active": "Active",
+  "fields.priority": "Priority",
+  "fields.stopFurther": "Stop further promotions",
+  "fields.salesChannels": "Sales channels",
+  "fields.validFrom": "Start date",
+  "fields.validUntil": "End date",
+  "rule.title": "Rule",
+  "action.title": "Action",
+  "action.free_delivery": "Apply free delivery",
+  "action.percentage_off_cart": "X% off the whole cart",
+  "action.amount_off_cart": "Y off the whole cart",
+  "action.buy_x_get_y_free": "Buy X get Y free",
+  "action.spend_x_percent_off": "For every X spent, Y% off the cart",
+  "action.spend_x_amount_off": "For every X spent, Y off the cart",
+  "action.every_nth_product_percent_off": "Every Nth product Y% cheaper",
+  "action.buy_x_units_y_free": "Buy X units of a product, Y free",
+  "action.buy_x_units_percent_off": "Buy X units of a product, Y% off the cart",
+  "action.buy_x_units_amount_off": "Buy X units of a product, Y off the cart",
+  "limits.title": "Usage limits",
+  "limits.global": "Global limit",
+  "limits.perOrganization": "Per organization",
+  "limits.perCustomer": "Per customer",
+  "nav.promotions.label": "Promotions",
+  "nav.promotionRules.label": "Promotion rules"
+}

package/i18n/pl.json

@@ -0,0 +1,34 @@
+{
+  "actions.openPromotions.label": "Promocje",
+  "actions.openPromotions.description": "Zarządzaj promocjami, rabatami, kuponami i regułami",
+  "actions.newPromotion.label": "Nowa promocja",
+  "actions.newPromotion.description": "Utwórz nową promocję",
+  "list.title": "Promocje",
+  "list.new": "Nowa promocja",
+  "fields.name": "Nazwa",
+  "fields.description": "Opis",
+  "fields.active": "Aktywna",
+  "fields.priority": "Priorytet",
+  "fields.stopFurther": "Zatrzymaj kolejne promocje",
+  "fields.salesChannels": "Kanały sprzedaży",
+  "fields.validFrom": "Data startu",
+  "fields.validUntil": "Data końca",
+  "rule.title": "Reguła",
+  "action.title": "Akcja",
+  "action.free_delivery": "Zaaplikuj darmową dostawę",
+  "action.percentage_off_cart": "Zniżka X% na cały koszyk",
+  "action.amount_off_cart": "Zniżka Y zł na cały koszyk",
+  "action.buy_x_get_y_free": "Kup X otrzymaj Y za darmo",
+  "action.spend_x_percent_off": "Za każde wydane X zniżka Y% na koszyk",
+  "action.spend_x_amount_off": "Za każde wydane X zniżka Y zł na koszyk",
+  "action.every_nth_product_percent_off": "Co X-ty produkt Y% taniej",
+  "action.buy_x_units_y_free": "Kup X sztuk produktu, Y gratis",
+  "action.buy_x_units_percent_off": "Kup X sztuk produktu, Y% zniżki na koszyk",
+  "action.buy_x_units_amount_off": "Kup X sztuk produktu, Y zł zniżki na koszyk",
+  "limits.title": "Limity użyć",
+  "limits.global": "Limit globalny",
+  "limits.perOrganization": "Na organizację",
+  "limits.perCustomer": "Na klienta",
+  "nav.promotions.label": "Promocje",
+  "nav.promotionRules.label": "Reguły promocji"
+}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@endora-commerce/mod-promotions",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Promotion rules engine: rule builder, actions, coupons, limits, statistics.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "promotions"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/promotions"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./ports": {
+      "types": "./dist/ports/index.d.ts",
+      "default": "./dist/ports/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs",
+    "tailwind.css"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "lucide-react": "^1",
+    "react": "^19",
+    "react-router-dom": "^7",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "peerDependenciesMeta": {
+    "@endora-commerce/admin-kit": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "@types/react": "^19.2.14",
+    "fastify": "^5.12.5",
+    "lucide-react": "^1.11.0",
+    "react": "^19.2.5",
+    "react-router-dom": "^7.18.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}

package/tailwind.css

@@ -0,0 +1,14 @@
+/* @endora-commerce/mod-promotions — AUTO-GENERATED by `pnpm --filter backend run manifests:generate`.
+ *
+ * The `@source` directives this package asks its host to scan
+ * (`specs/110-instance-repository/contracts/admin-stylesheet-composition.md` R1).
+ * They resolve relative to **this file**, so they hold wherever the package is
+ * installed — a workspace link here, `node_modules` in a client's instance.
+ *
+ * The `dist` line is what a published tarball ships and is what an instance
+ * scans; the `src` line is inert there and is what keeps `pnpm --filter admin
+ * run dev` reading source in this repository. Do not edit: run
+ * `pnpm --filter backend run manifests:generate`.
+ */
+@source "./dist/admin";
+@source "./src/admin";