@classytic/promo 0.2.0 → 0.2.2

package/README.md

@@ -151,7 +151,7 @@ if (result.appliedDiscounts.length > 0) {
    - stacking cap (`stackingMode: 'exclusive'` blocks subsequent programs; `maxStackablePromotions` caps the stackable chain).
 5. **Best-rule matching** — for each program, `matchBestRule` picks the highest-threshold rule whose gates all pass (code, date range, minimumAmount, minimumQuantity, product/category/SKU filters, `buyQuantity`). Scoring: `minimumAmount * 1000 + minimumQuantity`.
 6. **Reward computation** — linked rewards run through `computeDiscount` (scope-aware: `order`, `cheapest`, or `specific_products`; `maxDiscountAmount` capped; never exceeds running subtotal) or emit a `FreeProductLine`. The `runningSubtotal` decreases as each discount stacks.
-7. **Cart-hash + evaluation stash** — a SHA-256 hash of the normalized items + subtotal + codes + customer identity is computed and returned on the `EvaluationResult`. Non-preview evaluations are stashed in an in-memory pending map keyed by `evaluationId` so `commit()` can replay program + voucher usage writes inside a single transaction.
+7. **Cart-hash + evaluation snapshot** — a SHA-256 hash of the normalized items + subtotal + codes + customer identity is computed and returned on the `EvaluationResult`. Non-preview evaluations are persisted via the configured `EvaluationStore` (Mongo by default; hosts can plug Redis / DynamoDB / custom by implementing the port) so `commit()` can replay program + voucher usage writes inside a single transaction. Snapshots survive process restart, horizontal scaling, serverless cold starts, and worker handoff. The default Mongo store applies a TTL index so abandoned snapshots auto-expire (default 30 min).
 8. **Dispatch `EVALUATION_COMPLETED`** via `dispatchPromoEvent` — routed through the configured `events.transport` and optionally persisted via the host `outbox` inside `ctx.session`.
 
 `commit(evaluationId, orderId, ctx, { cartHash })` (same service) consumes the stash: it optionally re-verifies the submitted `cartHash` (throws `CartHashMismatchError` on mismatch), opens a transaction, increments `program.usedCount` + per-customer usage on every applied program, increments voucher usage + appends a redemption record per applied voucher, emits `EVALUATION_COMMITTED`, and returns a `CommitResult`. `rollback(evaluationId, ctx)` drops the stash and emits `EVALUATION_ROLLED_BACK`.
@@ -171,7 +171,7 @@ All four repositories extend mongokit's `Repository<T>` directly — no wrapper
 | `reward` | (inherited only) |
 | `voucher` | `cancel`, `incrementUsage` (atomic `$inc` + `$push`), `addLedgerEntry` (atomic balance delta + ledger push), `expireByDate`, `getByCode`, `hasIdempotencyKey` |
 
-The two services (`engine.services.voucher`, `engine.services.evaluation`) exist because they coordinate multiple repositories + transactions + config: code generation + redemption + gift-card spend/top-up for vouchers, and the multi-program evaluation algorithm + in-memory pending-commit stash for evaluations.
+The two services (`engine.services.voucher`, `engine.services.evaluation`) exist because they coordinate multiple repositories + transactions + config: code generation + redemption + gift-card spend/top-up for vouchers, and the multi-program evaluation algorithm + persistent evaluation snapshot store for evaluations.
 
 ---
 
@@ -203,7 +203,7 @@ engine.events.subscribe?.(PromoEvents.VOUCHER_REDEEMED, async (evt) => {
 });
 ```
 
-Representative event names: `promo:program.created` / `.activated` / `.paused` / `.archived`, `promo:rule.added` / `.updated` / `.removed`, `promo:reward.added` / `.updated` / `.removed`, `promo:voucher.generated` / `.redeemed` / `.cancelled` / `.expired`, `promo:gift_card.spent` / `.topped_up` / `.exhausted`, `promo:evaluation.completed` / `.committed` / `.rolled_back`.
+Representative event names: `promo.program.created` / `.activated` / `.paused` / `.archived`, `promo.rule.added` / `.updated` / `.removed`, `promo.reward.added` / `.updated` / `.removed`, `promo.voucher.generated` / `.redeemed` / `.cancelled` / `.expired`, `promo.gift_card.spent` / `.topped_up` / `.exhausted`, `promo.evaluation.completed` / `.committed` / `.rolled_back`. The full canonical list is exported as `PromoEvents` from the package root.
 
 ---
 

package/dist/constants-BB5O8zlN.mjs

@@ -0,0 +1,192 @@
+import { defineStateMachine } from "@classytic/primitives/state-machine";
+//#region src/domain/errors/base.ts
+var PromoError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = this.constructor.name;
+	}
+};
+//#endregion
+//#region src/domain/errors/domain-errors.ts
+var ValidationError = class extends PromoError {
+	code = "VALIDATION_ERROR";
+};
+var ProgramNotFoundError = class extends PromoError {
+	code = "PROGRAM_NOT_FOUND";
+	constructor(id) {
+		super(id ? `Program '${id}' not found` : "Program not found");
+	}
+};
+/**
+* Raised when a commit-time atomic CAS on `usedCount < maxUsageTotal`
+* fails — i.e. the program's cap was exhausted by another concurrent
+* commit between this caller's evaluate and its commit. The host should
+* surface this as a "promo no longer available" failure to the user; the
+* order itself can still proceed without the discount if the host wishes.
+*/
+var ProgramUsageCapExceededError = class extends PromoError {
+	code = "PROGRAM_USAGE_CAP_EXCEEDED";
+	constructor(programId, maxUsageTotal) {
+		super(`Program '${programId}' has reached its usage cap of ${maxUsageTotal}`);
+		this.programId = programId;
+		this.maxUsageTotal = maxUsageTotal;
+	}
+};
+var RuleNotFoundError = class extends PromoError {
+	code = "RULE_NOT_FOUND";
+	constructor(id) {
+		super(id ? `Rule '${id}' not found` : "Rule not found");
+	}
+};
+var RewardNotFoundError = class extends PromoError {
+	code = "REWARD_NOT_FOUND";
+	constructor(id) {
+		super(id ? `Reward '${id}' not found` : "Reward not found");
+	}
+};
+var VoucherNotFoundError = class extends PromoError {
+	code = "VOUCHER_NOT_FOUND";
+	constructor(codeOrId) {
+		super(codeOrId ? `Voucher '${codeOrId}' not found` : "Voucher not found");
+	}
+};
+var InvalidTransitionError = class extends PromoError {
+	code = "INVALID_TRANSITION";
+	constructor(from, to) {
+		super(`Cannot transition from '${from}' to '${to}'`);
+	}
+};
+var VoucherExpiredError = class extends PromoError {
+	code = "VOUCHER_EXPIRED";
+	constructor(code) {
+		super(`Voucher '${code}' has expired`);
+	}
+};
+var VoucherExhaustedError = class extends PromoError {
+	code = "VOUCHER_EXHAUSTED";
+	constructor(code) {
+		super(`Voucher '${code}' has reached its usage limit`);
+	}
+};
+/**
+* Thrown when a gift card's balance has been fully spent and its status
+* flipped to `'used'`. Distinct from `VoucherExhaustedError` (usage-limit
+* exhaustion on a discount voucher) so hosts can show "top up" vs "retry
+* later" messaging.
+*/
+var GiftCardExhaustedError = class extends PromoError {
+	code = "GIFT_CARD_EXHAUSTED";
+	constructor(code) {
+		super(`Gift card '${code}' has been fully spent`);
+	}
+};
+/**
+* Thrown when a MongoDB WriteConflict surfaces under voucher-spend
+* contention. Losers see a stable domain shape rather than the raw
+* `"Write conflict during plan execution"` string. Hosts can translate
+* this to HTTP 409 + retry.
+*/
+var ConcurrencyConflictError = class extends PromoError {
+	code = "CONCURRENCY_CONFLICT";
+	status = 409;
+	constructor(resource, resourceId, cause) {
+		super(`Concurrent modification on ${resource} '${resourceId}'`);
+		this.resource = resource;
+		this.resourceId = resourceId;
+		this.cause = cause;
+	}
+};
+var InsufficientBalanceError = class extends PromoError {
+	code = "INSUFFICIENT_BALANCE";
+	constructor(code, available, requested) {
+		super(`Voucher '${code}' has insufficient balance: ${available} available, ${requested} requested`);
+	}
+};
+var TenantIsolationError = class extends PromoError {
+	code = "TENANT_ISOLATION";
+	constructor() {
+		super("Tenant context is required but was not provided");
+	}
+};
+var DuplicateRedemptionError = class extends PromoError {
+	code = "DUPLICATE_REDEMPTION";
+	constructor(key) {
+		super(`Duplicate redemption detected for idempotency key '${key}'`);
+	}
+};
+var EvaluationNotFoundError = class extends PromoError {
+	code = "EVALUATION_NOT_FOUND";
+	constructor(id) {
+		super(`Evaluation '${id}' not found or already committed`);
+	}
+};
+/**
+* Thrown by `EvaluationService.commit` when the cart hash provided by the
+* caller does not match the cart hash computed at evaluation time. Guards
+* against cart-tampering attacks where a user previews a large discount on
+* a heavy cart, mutates the cart to something cheaper before committing, and
+* tries to apply the stale discount to the altered order.
+*/
+var CartHashMismatchError = class extends PromoError {
+	code = "CART_HASH_MISMATCH";
+	constructor(evaluationId) {
+		super(`Evaluation '${evaluationId}' cart hash mismatch — the cart changed between evaluate and commit. Re-evaluate with the current cart.`);
+	}
+};
+//#endregion
+//#region src/constants.ts
+const PROGRAM_TYPES = [
+	"promotion",
+	"coupon",
+	"discount_code",
+	"buy_x_get_y",
+	"gift_card"
+];
+const TRIGGER_MODES = ["auto", "code"];
+const PROGRAM_STATUSES = [
+	"draft",
+	"active",
+	"paused",
+	"expired",
+	"archived"
+];
+const STACKING_MODES = ["exclusive", "stackable"];
+const REWARD_TYPES = ["discount", "free_product"];
+const DISCOUNT_MODES = ["percentage", "fixed"];
+const DISCOUNT_SCOPES = [
+	"order",
+	"cheapest",
+	"specific_products"
+];
+const VOUCHER_STATUSES = [
+	"active",
+	"used",
+	"expired",
+	"cancelled"
+];
+/**
+* Program status machine — single throw site, declarative table.
+*
+* Wires promo's domain `InvalidTransitionError` (carries `from` + `to`)
+* via `errorFactory` so existing catch sites keep working. The
+* primitive's `entityId` field is dropped at the boundary — promo's
+* error doesn't include it. If a future caller needs structured entity
+* fields, extend the error first.
+*/
+const PROGRAM_MACHINE = defineStateMachine({
+	name: "Program",
+	transitions: {
+		draft: ["active", "archived"],
+		active: [
+			"paused",
+			"expired",
+			"archived"
+		],
+		paused: ["active", "archived"],
+		expired: ["archived"],
+		archived: []
+	},
+	errorFactory: ({ from, to }) => new InvalidTransitionError(from, to)
+});
+//#endregion
+export { VoucherExhaustedError as C, PromoError as E, ValidationError as S, VoucherNotFoundError as T, ProgramNotFoundError as _, PROGRAM_TYPES as a, RuleNotFoundError as b, TRIGGER_MODES as c, ConcurrencyConflictError as d, DuplicateRedemptionError as f, InvalidTransitionError as g, InsufficientBalanceError as h, PROGRAM_STATUSES as i, VOUCHER_STATUSES as l, GiftCardExhaustedError as m, DISCOUNT_SCOPES as n, REWARD_TYPES as o, EvaluationNotFoundError as p, PROGRAM_MACHINE as r, STACKING_MODES as s, DISCOUNT_MODES as t, CartHashMismatchError as u, ProgramUsageCapExceededError as v, VoucherExpiredError as w, TenantIsolationError as x, RewardNotFoundError as y };