@classytic/promo 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -1,32 +1,1712 @@
-import { n as DEFAULT_TENANT_TYPE, t as DEFAULT_TENANT_FIELD } from "./constants-BVajdyL3.mjs";
-import { l as ValidationError } from "./domain-errors-BEkXvy5O.mjs";
-import { t as InProcessEventBus } from "./events-CprEWlN7.mjs";
-import { t as createModels } from "./models-DdBNae7h.mjs";
-import { t as createRepositories } from "./repositories-DgZIY9wD.mjs";
-import { t as PromoEvents } from "./event-types-CsTV1FKX.mjs";
-import { t as createServices } from "./services-Cz0gHrmX.mjs";
-//#region src/index.ts
-function resolveConfig(config) {
-	let tenant;
-	if (config.tenant === false) tenant = {
-		enabled: false,
-		field: "",
-		type: "ObjectId",
-		contextKey: ""
+import { a as PROGRAM_TYPES, c as TRIGGER_MODES, i as PROGRAM_TRANSITIONS, l as VOUCHER_STATUSES, n as DISCOUNT_SCOPES, o as REWARD_TYPES, r as PROGRAM_STATUSES, s as STACKING_MODES, t as DISCOUNT_MODES } from "./constants-D0Rntp2f.mjs";
+import { resolveTenantConfig } from "@classytic/primitives/tenant";
+import { createEvent, matchEventPattern } from "@classytic/primitives/events";
+import mongoose from "mongoose";
+import { Repository, multiTenantPlugin } from "@classytic/mongokit";
+import { createHash, randomBytes } from "node:crypto";
+import { z } from "zod";
+//#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");
+	}
+};
+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 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/events/in-process-bus.ts
+var InProcessPromoBus = class {
+	name = "in-process-promo";
+	handlers = /* @__PURE__ */ new Map();
+	logger;
+	constructor(options = {}) {
+		this.logger = options.logger ?? console;
+	}
+	async publish(event) {
+		const matched = /* @__PURE__ */ new Set();
+		for (const [pattern, set] of this.handlers.entries()) if (matchEventPattern(pattern, event.type)) for (const h of set) matched.add(h);
+		for (const handler of matched) try {
+			await handler(event);
+		} catch (err) {
+			this.logger.error(`[promo] handler error for ${event.type}:`, err);
+		}
+	}
+	async subscribe(pattern, handler) {
+		let set = this.handlers.get(pattern);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.handlers.set(pattern, set);
+		}
+		set.add(handler);
+		return () => {
+			const s = this.handlers.get(pattern);
+			if (!s) return;
+			s.delete(handler);
+			if (s.size === 0) this.handlers.delete(pattern);
+		};
+	}
+	async close() {
+		this.handlers.clear();
+	}
+};
+//#endregion
+//#region src/models/create-model.ts
+function injectTenantField(schema, tenant) {
+	schema.add({ [tenant.tenantField]: {
+		type: tenant.fieldType === "objectId" ? mongoose.Schema.Types.ObjectId : String,
+		index: true,
+		...tenant.ref ? { ref: tenant.ref } : {}
+	} });
+	if (!tenant.enabled) return;
+	const existingIndexes = schema._indexes;
+	if (existingIndexes && existingIndexes.length > 0) for (const indexEntry of existingIndexes) {
+		const fields = indexEntry[0];
+		const newFields = { [tenant.tenantField]: 1 };
+		for (const [key, val] of Object.entries(fields)) newFields[key] = val;
+		indexEntry[0] = newFields;
+	}
+}
+function applyUserIndexes(schema, indexes, tenant) {
+	for (const def of indexes) {
+		const fields = tenant.enabled ? {
+			[tenant.tenantField]: 1,
+			...def.fields
+		} : { ...def.fields };
+		schema.index(fields, def.options ?? {});
+	}
+}
+//#endregion
+//#region src/models/schemas/program.schema.ts
+const { Schema: Schema$3 } = mongoose;
+function createProgramSchema() {
+	const schema = new Schema$3({
+		name: {
+			type: String,
+			required: true
+		},
+		description: { type: String },
+		programType: {
+			type: String,
+			enum: PROGRAM_TYPES,
+			required: true
+		},
+		triggerMode: {
+			type: String,
+			enum: TRIGGER_MODES,
+			required: true
+		},
+		status: {
+			type: String,
+			enum: PROGRAM_STATUSES,
+			default: "draft"
+		},
+		stackingMode: {
+			type: String,
+			enum: STACKING_MODES,
+			default: "exclusive"
+		},
+		priority: {
+			type: Number,
+			default: 0
+		},
+		startsAt: { type: Date },
+		endsAt: { type: Date },
+		maxUsageTotal: { type: Number },
+		usedCount: {
+			type: Number,
+			default: 0
+		},
+		maxUsagePerCustomer: { type: Number },
+		applicableCustomerIds: [{ type: String }],
+		applicableCustomerTags: [{ type: String }],
+		customerUsageCounts: {
+			type: Map,
+			of: Number,
+			default: () => /* @__PURE__ */ new Map()
+		},
+		metadata: { type: Schema$3.Types.Mixed }
+	}, { timestamps: true });
+	schema.index({
+		status: 1,
+		programType: 1,
+		priority: -1
+	});
+	schema.index({
+		status: 1,
+		startsAt: 1,
+		endsAt: 1
+	});
+	schema.index({
+		status: 1,
+		priority: -1,
+		_id: -1
+	});
+	return schema;
+}
+//#endregion
+//#region src/models/schemas/reward.schema.ts
+const { Schema: Schema$2 } = mongoose;
+function createRewardSchema() {
+	const schema = new Schema$2({
+		programId: {
+			type: Schema$2.Types.ObjectId,
+			required: true
+		},
+		ruleId: { type: Schema$2.Types.ObjectId },
+		rewardType: {
+			type: String,
+			enum: REWARD_TYPES,
+			required: true
+		},
+		discountMode: {
+			type: String,
+			enum: DISCOUNT_MODES
+		},
+		discountAmount: { type: Number },
+		maxDiscountAmount: { type: Number },
+		discountScope: {
+			type: String,
+			enum: DISCOUNT_SCOPES,
+			default: "order"
+		},
+		applicableProductIds: [{ type: String }],
+		freeProductId: { type: String },
+		freeProductSku: { type: String },
+		freeQuantity: {
+			type: Number,
+			default: 1
+		},
+		giftCardAmount: { type: Number },
+		metadata: { type: Schema$2.Types.Mixed }
+	}, { timestamps: true });
+	schema.index({ programId: 1 });
+	schema.index({ ruleId: 1 }, { sparse: true });
+	return schema;
+}
+//#endregion
+//#region src/models/schemas/rule.schema.ts
+const { Schema: Schema$1 } = mongoose;
+function createRuleSchema() {
+	const schema = new Schema$1({
+		programId: {
+			type: Schema$1.Types.ObjectId,
+			required: true
+		},
+		name: { type: String },
+		minimumAmount: {
+			type: Number,
+			default: 0
+		},
+		minimumQuantity: {
+			type: Number,
+			default: 0
+		},
+		applicableProductIds: [{ type: String }],
+		applicableCategories: [{ type: String }],
+		applicableSkus: [{ type: String }],
+		buyQuantity: { type: Number },
+		code: {
+			type: String,
+			uppercase: true,
+			trim: true
+		},
+		startsAt: { type: Date },
+		endsAt: { type: Date },
+		metadata: { type: Schema$1.Types.Mixed }
+	}, { timestamps: true });
+	schema.index({ programId: 1 });
+	schema.index({ code: 1 }, { sparse: true });
+	return schema;
+}
+//#endregion
+//#region src/models/schemas/voucher.schema.ts
+const { Schema } = mongoose;
+function createVoucherSchema() {
+	const schema = new Schema({
+		programId: {
+			type: Schema.Types.ObjectId,
+			required: true,
+			index: true
+		},
+		code: {
+			type: String,
+			required: true,
+			uppercase: true,
+			trim: true
+		},
+		status: {
+			type: String,
+			enum: VOUCHER_STATUSES,
+			default: "active"
+		},
+		customerId: { type: String },
+		usageLimit: {
+			type: Number,
+			default: 1
+		},
+		usedCount: {
+			type: Number,
+			default: 0
+		},
+		initialBalance: { type: Number },
+		currentBalance: { type: Number },
+		balanceLedger: [{
+			amount: {
+				type: Number,
+				required: true
+			},
+			orderId: { type: String },
+			description: { type: String },
+			createdAt: {
+				type: Date,
+				default: Date.now
+			},
+			idempotencyKey: { type: String }
+		}],
+		expiresAt: { type: Date },
+		redemptions: [{
+			orderId: {
+				type: String,
+				required: true
+			},
+			customerId: { type: String },
+			discountAmount: {
+				type: Number,
+				required: true
+			},
+			redeemedAt: {
+				type: Date,
+				default: Date.now
+			},
+			idempotencyKey: { type: String }
+		}],
+		metadata: { type: Schema.Types.Mixed }
+	}, { timestamps: true });
+	schema.index({ code: 1 }, { unique: true });
+	schema.index({
+		programId: 1,
+		status: 1
+	});
+	schema.index({
+		customerId: 1,
+		status: 1
+	}, { sparse: true });
+	schema.index({ expiresAt: 1 }, { sparse: true });
+	return schema;
+}
+//#endregion
+//#region src/models/create-models.ts
+const MODEL_NAMES = [
+	"PromoProgram",
+	"PromoRule",
+	"PromoReward",
+	"PromoVoucher"
+];
+function applyAutoIndex(models, autoIndex) {
+	if (autoIndex === void 0) return;
+	for (const [configKey, modelKey] of [
+		["program", "Program"],
+		["rule", "Rule"],
+		["reward", "Reward"],
+		["voucher", "Voucher"]
+	]) {
+		const value = typeof autoIndex === "boolean" ? autoIndex : autoIndex[configKey] ?? void 0;
+		if (value !== void 0) models[modelKey].schema.set("autoIndex", value);
+	}
+}
+function createModels(connection, tenant, indexes, autoIndex) {
+	for (const name of MODEL_NAMES) if (connection.models[name]) connection.deleteModel(name);
+	const programSchema = createProgramSchema();
+	const ruleSchema = createRuleSchema();
+	const rewardSchema = createRewardSchema();
+	const voucherSchema = createVoucherSchema();
+	injectTenantField(programSchema, tenant);
+	injectTenantField(ruleSchema, tenant);
+	injectTenantField(rewardSchema, tenant);
+	injectTenantField(voucherSchema, tenant);
+	if (indexes?.program) applyUserIndexes(programSchema, indexes.program, tenant);
+	if (indexes?.rule) applyUserIndexes(ruleSchema, indexes.rule, tenant);
+	if (indexes?.reward) applyUserIndexes(rewardSchema, indexes.reward, tenant);
+	if (indexes?.voucher) applyUserIndexes(voucherSchema, indexes.voucher, tenant);
+	const result = {
+		Program: connection.model("PromoProgram", programSchema),
+		Rule: connection.model("PromoRule", ruleSchema),
+		Reward: connection.model("PromoReward", rewardSchema),
+		Voucher: connection.model("PromoVoucher", voucherSchema)
 	};
-	else if (config.tenant === void 0) tenant = {
-		enabled: true,
-		field: DEFAULT_TENANT_FIELD,
-		type: DEFAULT_TENANT_TYPE,
-		contextKey: DEFAULT_TENANT_FIELD
+	applyAutoIndex(result, autoIndex);
+	return result;
+}
+//#endregion
+//#region src/events/dispatch.ts
+/**
+* Canonical P8 shape — save to outbox first (with `ctx.session` when
+* present), then publish to transport. Both paths run independently.
+*/
+async function dispatchPromoEvent(deps, event, ctx) {
+	const logger = deps.logger ?? console;
+	if (deps.outbox) try {
+		const saveOptions = {};
+		if (ctx?.session !== void 0) saveOptions.session = ctx.session;
+		await deps.outbox.save(event, saveOptions);
+	} catch (err) {
+		logger.error(`[promo] outbox.save failed for ${event.type}:`, err);
+	}
+	if (deps.events) try {
+		await deps.events.publish(event);
+	} catch (err) {
+		logger.error(`[promo] events.publish failed for ${event.type}:`, err);
+	}
+}
+//#endregion
+//#region src/events/event-constants.ts
+const PromoEvents = {
+	PROGRAM_CREATED: "promo.program.created",
+	PROGRAM_ACTIVATED: "promo.program.activated",
+	PROGRAM_PAUSED: "promo.program.paused",
+	PROGRAM_ARCHIVED: "promo.program.archived",
+	RULE_ADDED: "promo.rule.added",
+	RULE_UPDATED: "promo.rule.updated",
+	RULE_REMOVED: "promo.rule.removed",
+	REWARD_ADDED: "promo.reward.added",
+	REWARD_UPDATED: "promo.reward.updated",
+	REWARD_REMOVED: "promo.reward.removed",
+	VOUCHER_GENERATED: "promo.voucher.generated",
+	VOUCHER_REDEEMED: "promo.voucher.redeemed",
+	VOUCHER_CANCELLED: "promo.voucher.cancelled",
+	VOUCHER_EXPIRED: "promo.voucher.expired",
+	GIFT_CARD_SPENT: "promo.gift_card.spent",
+	GIFT_CARD_TOPPED_UP: "promo.gift_card.topped_up",
+	GIFT_CARD_EXHAUSTED: "promo.gift_card.exhausted",
+	EVALUATION_COMPLETED: "promo.evaluation.completed",
+	EVALUATION_COMMITTED: "promo.evaluation.committed",
+	EVALUATION_ROLLED_BACK: "promo.evaluation.rolled_back"
+};
+//#endregion
+//#region src/events/helpers.ts
+function createEvent$1(type, payload, ctx, meta) {
+	return createEvent(type, payload, {
+		resource: "promo",
+		...ctx?.actorId !== void 0 ? { userId: ctx.actorId } : {},
+		...ctx?.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {},
+		...meta
+	});
+}
+//#endregion
+//#region src/repositories/program.repository.ts
+var ProgramRepository = class extends Repository {
+	dispatchDeps;
+	constructor(model, plugins = [], dispatchDeps = {}) {
+		super(model, plugins);
+		this.dispatchDeps = dispatchDeps;
+	}
+	async activate(id, ctx) {
+		return this._transition(id, "active", ctx);
+	}
+	async pause(id, ctx) {
+		return this._transition(id, "paused", ctx);
+	}
+	async archive(id, ctx) {
+		return this._transition(id, "archived", ctx);
+	}
+	async _transition(id, targetStatus, ctx) {
+		const program = await this.getById(id, {
+			throwOnNotFound: false,
+			lean: true,
+			...ctx
+		});
+		if (!program) throw new ProgramNotFoundError(id);
+		if (!PROGRAM_TRANSITIONS[program.status]?.includes(targetStatus)) throw new InvalidTransitionError(program.status, targetStatus);
+		const updated = await this.update(id, { status: targetStatus }, {
+			throwOnNotFound: true,
+			lean: true,
+			...ctx
+		});
+		if (!updated) throw new ProgramNotFoundError(id);
+		const eventName = {
+			active: PromoEvents.PROGRAM_ACTIVATED,
+			paused: PromoEvents.PROGRAM_PAUSED,
+			archived: PromoEvents.PROGRAM_ARCHIVED
+		}[targetStatus];
+		if (eventName) await dispatchPromoEvent(this.dispatchDeps, createEvent$1(eventName, {
+			programId: updated._id,
+			programType: updated.programType,
+			status: updated.status,
+			actorId: ctx.actorId
+		}, ctx), ctx);
+		return updated;
+	}
+	async incrementUsage(id, ctx) {
+		const updated = await this.update(id, { $inc: { usedCount: 1 } }, {
+			throwOnNotFound: true,
+			lean: true,
+			...ctx
+		});
+		if (!updated) throw new ProgramNotFoundError(id);
+		return updated;
+	}
+	async decrementUsage(id, ctx) {
+		const updated = await this.update(id, { $inc: { usedCount: -1 } }, {
+			throwOnNotFound: true,
+			lean: true,
+			...ctx
+		});
+		if (!updated) throw new ProgramNotFoundError(id);
+		return updated;
+	}
+	async getCustomerUsage(id, customerId, ctx) {
+		const doc = await this.getById(id, {
+			throwOnNotFound: false,
+			lean: true,
+			...ctx
+		});
+		if (!doc) return 0;
+		const counts = doc.customerUsageCounts;
+		if (!counts) return 0;
+		if (counts instanceof Map) return counts.get(customerId) ?? 0;
+		return counts[customerId] ?? 0;
+	}
+	async incrementCustomerUsage(id, customerId, ctx) {
+		const updated = await this.update(id, { $inc: { [`customerUsageCounts.${customerId}`]: 1 } }, {
+			throwOnNotFound: true,
+			lean: true,
+			...ctx
+		});
+		if (!updated) throw new ProgramNotFoundError(id);
+		return updated;
+	}
+	async findActive(now, ctx) {
+		const currentDate = now ?? /* @__PURE__ */ new Date();
+		const filters = {
+			status: "active",
+			$or: [
+				{ startsAt: { $lte: currentDate } },
+				{ startsAt: { $exists: false } },
+				{ startsAt: null }
+			]
+		};
+		return (await this.findAll(filters, {
+			sort: {
+				priority: -1,
+				_id: -1
+			},
+			lean: true,
+			...ctx
+		})).filter((p) => !p.endsAt || p.endsAt >= currentDate).slice(0, 200);
+	}
+};
+//#endregion
+//#region src/repositories/reward.repository.ts
+var RewardRepository = class extends Repository {
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+};
+//#endregion
+//#region src/repositories/rule.repository.ts
+var RuleRepository = class extends Repository {
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+};
+//#endregion
+//#region src/repositories/voucher.repository.ts
+var VoucherRepository = class extends Repository {
+	dispatchDeps;
+	tenantField;
+	constructor(model, plugins = [], dispatchDeps = {}, tenantField = "organizationId") {
+		super(model, plugins);
+		this.dispatchDeps = dispatchDeps;
+		this.tenantField = tenantField;
+	}
+	/**
+	* Copy the tenant id from `ctx` onto the write payload so the doc persists
+	* with the correct `organizationId` even when the host has opted OUT of the
+	* auto-wired `multiTenantPlugin` (e.g. arc hosts that scope at the
+	* framework layer — see `@classytic/order` CLAUDE.md: "Child repos set
+	* `organizationId` explicitly on the doc"). No-op when `ctx` omits the
+	* tenant id or the payload already carries it.
+	*/
+	_injectTenant(data, ctx) {
+		const tenantValue = ctx?.[this.tenantField];
+		if (tenantValue != null && data[this.tenantField] == null) data[this.tenantField] = tenantValue;
+		return data;
+	}
+	async create(data, options) {
+		this._injectTenant(data, options);
+		return super.create(data, options);
+	}
+	async createMany(docs, options) {
+		const ctx = options;
+		for (const doc of docs) this._injectTenant(doc, ctx);
+		return super.createMany(docs, options);
+	}
+	/** Domain verb: cancel a voucher (status transition + event). */
+	async cancel(id, ctx) {
+		const voucher = await this.getById(id, {
+			throwOnNotFound: false,
+			lean: true,
+			...ctx
+		});
+		if (!voucher) throw new VoucherNotFoundError(id);
+		const updated = await this.update(id, { status: "cancelled" }, {
+			throwOnNotFound: true,
+			lean: true,
+			...ctx
+		});
+		if (!updated) throw new VoucherNotFoundError(id);
+		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.VOUCHER_CANCELLED, {
+			voucherId: id,
+			code: voucher.code,
+			status: "cancelled"
+		}, ctx), ctx);
+		return updated;
+	}
+	/** Atomic usage increment + push redemption record. */
+	async incrementUsage(id, redemption, ctx) {
+		const updated = await this.update(id, {
+			$inc: { usedCount: 1 },
+			$push: { redemptions: redemption }
+		}, {
+			throwOnNotFound: true,
+			lean: true,
+			...ctx
+		});
+		if (!updated) throw new VoucherNotFoundError(id);
+		return updated;
+	}
+	/** Atomic balance delta + push ledger entry. */
+	async addLedgerEntry(id, entry, balanceDelta, ctx) {
+		const updated = await this.update(id, {
+			$inc: { currentBalance: balanceDelta },
+			$push: { balanceLedger: entry }
+		}, {
+			throwOnNotFound: true,
+			lean: true,
+			...ctx
+		});
+		if (!updated) throw new VoucherNotFoundError(id);
+		return updated;
+	}
+	/**
+	* Batch expire by date.
+	*
+	* Routes through `findAll` + per-doc `update` instead of a raw
+	* `this.Model.updateMany`. Rationale:
+	*  1. `findAll` casts the filter through the schema (so an ObjectId
+	*     tenant field on a write-time String context doesn't silently
+	*     return 0 rows the way a raw `$match` would).
+	*  2. `update` fires the full hook pipeline (multi-tenant, audit,
+	*     soft-delete) on every expiration — a bulk `updateMany` at the
+	*     Model layer bypasses all of them.
+	* Volume is bounded per tenant (active + past-expiry vouchers), so an
+	* N+1 loop is acceptable for correctness.
+	*/
+	async expireByDate(before, ctx) {
+		const filter = {
+			status: "active",
+			expiresAt: { $lte: before }
+		};
+		const docs = await this.findAll(filter, {
+			lean: true,
+			...ctx
+		});
+		let modified = 0;
+		for (const doc of docs) if (await this.update(doc._id, { status: "expired" }, {
+			throwOnNotFound: false,
+			lean: true,
+			...ctx
+		})) modified++;
+		return modified;
+	}
+	/**
+	* Lookup voucher by unique code, scoped to the tenant in `ctx` when
+	* tenant scoping is configured.
+	*
+	* Manual tenant injection mirrors `expireByDate` and `ProgramRepository.findActive`
+	* — it makes the method work whether the host opts into the auto-wired
+	* `multiTenantPlugin` or enforces scoping at its own framework layer
+	* (e.g. arc's preset + `BaseController`). Without this, a host that
+	* runs the plugin off would leak vouchers across branches at
+	* validate/redeem/spend/topUp call sites.
+	*/
+	async getByCode(code, ctx) {
+		const filter = { code: code.toUpperCase() };
+		const tenantValue = ctx?.[this.tenantField];
+		if (tenantValue != null) filter[this.tenantField] = tenantValue;
+		return this.getByQuery(filter, {
+			throwOnNotFound: false,
+			lean: true,
+			...ctx
+		});
+	}
+	/**
+	* Idempotency check on nested arrays. Routes through mongokit's `count`
+	* so `multiTenantPlugin` injects the configured tenant field from
+	* `ctx` — a non-tenant-scoped check would cross organization boundaries.
+	*/
+	async hasIdempotencyKey(id, key, ctx) {
+		const filter = {
+			_id: id,
+			$or: [{ "redemptions.idempotencyKey": key }, { "balanceLedger.idempotencyKey": key }]
+		};
+		return await this.count(filter, ctx) > 0;
+	}
+};
+//#endregion
+//#region src/repositories/create-repositories.ts
+function createRepositories(models, plugins, tenant, dispatchDeps = {}) {
+	const tenantPlugins = tenant?.enabled ? [multiTenantPlugin({
+		tenantField: tenant.tenantField,
+		contextKey: tenant.contextKey,
+		fieldType: tenant.fieldType
+	})] : [];
+	return {
+		program: new ProgramRepository(models.Program, [...tenantPlugins, ...plugins?.program ?? []], dispatchDeps),
+		rule: new RuleRepository(models.Rule, [...tenantPlugins, ...plugins?.rule ?? []]),
+		reward: new RewardRepository(models.Reward, [...tenantPlugins, ...plugins?.reward ?? []]),
+		voucher: new VoucherRepository(models.Voucher, [...tenantPlugins, ...plugins?.voucher ?? []], dispatchDeps, tenant?.tenantField)
 	};
-	else tenant = {
-		enabled: true,
-		field: config.tenant.field ?? "organizationId",
-		type: config.tenant.type ?? "ObjectId",
-		contextKey: config.tenant.contextKey ?? config.tenant.field ?? "organizationId",
-		...config.tenant.ref ? { ref: config.tenant.ref } : {}
+}
+//#endregion
+//#region src/services/evaluation.service.ts
+/**
+* Deterministic, collision-resistant hash of the evaluated cart. The hash
+* covers everything the evaluation algorithm depends on: normalized line
+* items (sorted), subtotal, applied codes, and customer identity. Two
+* evaluations over an identical cart yield the same hash; any mutation —
+* quantity, unit price, added/removed line, different code, different
+* customer — yields a different hash.
+*/
+function computeCartHash(input) {
+	const items = [...input.items].map((item) => ({
+		productId: item.productId ?? "",
+		sku: item.sku ?? "",
+		categoryId: item.categoryId ?? "",
+		quantity: item.quantity,
+		unitPrice: item.unitPrice,
+		lineTotal: item.lineTotal ?? item.quantity * item.unitPrice
+	})).sort((a, b) => {
+		if (a.productId !== b.productId) return a.productId < b.productId ? -1 : 1;
+		if (a.sku !== b.sku) return a.sku < b.sku ? -1 : 1;
+		if (a.unitPrice !== b.unitPrice) return a.unitPrice - b.unitPrice;
+		return a.quantity - b.quantity;
+	});
+	const codes = [...input.codes ?? []].map((c) => c.toUpperCase()).sort();
+	const tags = [...input.customerTags ?? []].sort();
+	const canonical = JSON.stringify({
+		items,
+		subtotal: input.subtotal,
+		codes,
+		customerId: input.customerId ?? null,
+		customerTags: tags
+	});
+	return createHash("sha256").update(canonical).digest("hex");
+}
+var EvaluationService = class {
+	pendingEvaluations = /* @__PURE__ */ new Map();
+	constructor(programRepo, ruleRepo, rewardRepo, voucherRepo, unitOfWork, dispatchDeps, config) {
+		this.programRepo = programRepo;
+		this.ruleRepo = ruleRepo;
+		this.rewardRepo = rewardRepo;
+		this.voucherRepo = voucherRepo;
+		this.unitOfWork = unitOfWork;
+		this.dispatchDeps = dispatchDeps;
+		this.config = config;
+	}
+	async evaluate(input, ctx) {
+		return this.doEvaluate(input, ctx, false);
+	}
+	async preview(input, ctx) {
+		return this.doEvaluate(input, ctx, true);
+	}
+	async commit(evaluationId, orderId, ctx, options = {}) {
+		const stored = this.pendingEvaluations.get(evaluationId);
+		if (!stored) throw new EvaluationNotFoundError(evaluationId);
+		if (options.cartHash !== void 0 && options.cartHash !== stored.cartHash) throw new CartHashMismatchError(evaluationId);
+		return this.unitOfWork.withTransaction(async (session) => {
+			for (const usage of stored.programUsages) {
+				await this.programRepo.incrementUsage(usage.programId, {
+					...ctx,
+					session
+				});
+				if (stored.customerId) await this.programRepo.incrementCustomerUsage(usage.programId, stored.customerId, {
+					...ctx,
+					session
+				});
+			}
+			for (const usage of stored.voucherUsages) await this.voucherRepo.incrementUsage(usage.voucherId, {
+				orderId,
+				discountAmount: usage.discountAmount,
+				redeemedAt: /* @__PURE__ */ new Date()
+			}, {
+				...ctx,
+				session
+			});
+			this.pendingEvaluations.delete(evaluationId);
+			const commitResult = {
+				evaluationId,
+				orderId,
+				totalDiscount: stored.result.totalDiscount,
+				programsCommitted: stored.programUsages.length,
+				vouchersUsed: stored.voucherUsages.length
+			};
+			await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.EVALUATION_COMMITTED, {
+				evaluationId,
+				orderId,
+				totalDiscount: stored.result.totalDiscount
+			}, ctx), {
+				...ctx,
+				session
+			});
+			return commitResult;
+		});
+	}
+	async rollback(evaluationId, ctx) {
+		if (!this.pendingEvaluations.get(evaluationId)) return;
+		this.pendingEvaluations.delete(evaluationId);
+		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.EVALUATION_ROLLED_BACK, { evaluationId }, ctx), ctx);
+	}
+	async doEvaluate(input, ctx, isPreview) {
+		const submittedCodes = (input.codes ?? []).map((c) => c.toUpperCase());
+		const programs = await this.programRepo.findActive(void 0, ctx);
+		const programIds = programs.map((p) => p._id);
+		const [allRules, allRewards] = await Promise.all([this.ruleRepo.findAll({ programId: { $in: programIds } }, ctx), this.rewardRepo.findAll({ programId: { $in: programIds } }, ctx)]);
+		const rulesByProgram = groupBy(allRules, (r) => r.programId);
+		const rewardsByProgram = groupBy(allRewards, (r) => r.programId);
+		const voucherMap = /* @__PURE__ */ new Map();
+		for (const code of submittedCodes) {
+			const voucher = await this.voucherRepo.getByCode(code, ctx);
+			if (voucher && voucher.status === "active" && voucher.usedCount < voucher.usageLimit) voucherMap.set(code, {
+				voucherId: voucher._id,
+				programId: voucher.programId,
+				balance: voucher.currentBalance
+			});
+		}
+		const appliedDiscounts = [];
+		const freeProducts = [];
+		const appliedCodes = [];
+		const rejectedCodes = [];
+		const warnings = [];
+		const programsApplied = [];
+		const programUsages = [];
+		const voucherUsages = [];
+		let runningSubtotal = input.subtotal;
+		let exclusiveApplied = false;
+		let stackableCount = 0;
+		for (const program of programs) {
+			if (program.maxUsageTotal && program.usedCount >= program.maxUsageTotal) continue;
+			if (!this.isCustomerEligible(program, input)) continue;
+			if (program.maxUsagePerCustomer && input.customerId) {
+				if (await this.programRepo.getCustomerUsage(program._id, input.customerId, ctx) >= program.maxUsagePerCustomer) {
+					warnings.push(`Customer has reached max usage (${program.maxUsagePerCustomer}) for "${program.name}"`);
+					continue;
+				}
+			}
+			if (program.stackingMode === "exclusive" && exclusiveApplied) continue;
+			if (program.stackingMode === "stackable" && stackableCount >= this.config.evaluation.maxStackablePromotions) {
+				warnings.push(`Max stackable promotions (${this.config.evaluation.maxStackablePromotions}) reached`);
+				continue;
+			}
+			const rules = rulesByProgram.get(String(program._id)) ?? [];
+			const rewards = rewardsByProgram.get(String(program._id)) ?? [];
+			if (rules.length === 0 || rewards.length === 0) continue;
+			const matchResult = this.matchBestRule(program, rules, input.items, input.subtotal, submittedCodes, voucherMap);
+			if (!matchResult.matched) {
+				if (matchResult.rejectedCode) rejectedCodes.push(matchResult.rejectedCode);
+				continue;
+			}
+			const applicableRewards = this.filterRewardsByRule(rewards, matchResult.matchedRuleId);
+			for (const reward of applicableRewards) if (reward.rewardType === "discount") {
+				const discount = this.computeDiscount(reward, input.items, runningSubtotal);
+				if (discount <= 0) continue;
+				appliedDiscounts.push({
+					programId: program._id,
+					programName: program.name,
+					rewardId: reward._id,
+					type: reward.discountMode ?? "fixed",
+					scope: reward.discountScope,
+					amount: discount,
+					description: this.describeDiscount(reward, program),
+					voucherCode: matchResult.matchedCode
+				});
+				runningSubtotal = Math.max(0, runningSubtotal - discount);
+			} else if (reward.rewardType === "free_product") freeProducts.push({
+				programId: program._id,
+				programName: program.name,
+				rewardId: reward._id,
+				productId: reward.freeProductId,
+				productSku: reward.freeProductSku,
+				quantity: reward.freeQuantity,
+				description: `Free product from "${program.name}"`
+			});
+			programsApplied.push(program._id);
+			programUsages.push({ programId: program._id });
+			if (matchResult.matchedCode) {
+				appliedCodes.push(matchResult.matchedCode);
+				const voucherInfo = voucherMap.get(matchResult.matchedCode);
+				if (voucherInfo) {
+					const totalProgramDiscount = appliedDiscounts.filter((d) => d.programId === program._id).reduce((sum, d) => sum + d.amount, 0);
+					voucherUsages.push({
+						voucherId: voucherInfo.voucherId,
+						code: matchResult.matchedCode,
+						discountAmount: totalProgramDiscount
+					});
+				}
+			}
+			if (program.stackingMode === "exclusive") exclusiveApplied = true;
+			else stackableCount++;
+		}
+		for (const code of submittedCodes) if (!appliedCodes.includes(code) && !rejectedCodes.some((r) => r.code === code)) rejectedCodes.push({
+			code,
+			reason: "No matching active program found for this code"
+		});
+		const totalDiscount = appliedDiscounts.reduce((sum, d) => sum + d.amount, 0);
+		const evaluationId = randomBytes(16).toString("hex");
+		const cartHash = computeCartHash(input);
+		const result = {
+			evaluationId,
+			cartHash,
+			appliedDiscounts,
+			freeProducts,
+			totalDiscount,
+			subtotalAfterDiscount: Math.max(0, input.subtotal - totalDiscount),
+			appliedCodes,
+			rejectedCodes,
+			warnings,
+			isPreview,
+			programsApplied
+		};
+		if (!isPreview) this.pendingEvaluations.set(evaluationId, {
+			result,
+			ctx,
+			customerId: input.customerId,
+			programUsages,
+			voucherUsages,
+			createdAt: Date.now(),
+			cartHash
+		});
+		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.EVALUATION_COMPLETED, {
+			evaluationId,
+			totalDiscount,
+			programsApplied: programsApplied.length,
+			codesUsed: appliedCodes,
+			isPreview
+		}, ctx), ctx);
+		return result;
+	}
+	isCustomerEligible(program, input) {
+		if (program.applicableCustomerIds.length > 0) {
+			if (!input.customerId) return false;
+			if (!program.applicableCustomerIds.includes(input.customerId)) return false;
+		}
+		if (program.applicableCustomerTags.length > 0) {
+			const customerTags = input.customerTags ?? [];
+			if (customerTags.length === 0) return false;
+			if (!program.applicableCustomerTags.some((tag) => customerTags.includes(tag))) return false;
+		}
+		return true;
+	}
+	matchBestRule(program, rules, items, subtotal, submittedCodes, voucherMap) {
+		let bestMatch = { matched: false };
+		let bestThreshold = -1;
+		let lastRejected;
+		for (const rule of rules) {
+			const singleResult = this.matchSingleRule(program, rule, items, subtotal, submittedCodes, voucherMap);
+			if (singleResult.rejectedCode) lastRejected = singleResult.rejectedCode;
+			if (!singleResult.matched) continue;
+			const threshold = (rule.minimumAmount ?? 0) * 1e3 + (rule.minimumQuantity ?? 0);
+			if (threshold > bestThreshold) {
+				bestThreshold = threshold;
+				bestMatch = singleResult;
+			}
+		}
+		if (!bestMatch.matched && lastRejected) bestMatch.rejectedCode = lastRejected;
+		return bestMatch;
+	}
+	matchSingleRule(program, rule, items, subtotal, submittedCodes, voucherMap) {
+		if (program.triggerMode === "code") {
+			if (rule.code) {
+				if (!submittedCodes.includes(rule.code)) return { matched: false };
+				if (program.programType === "coupon" || program.programType === "discount_code") {
+					const voucherInfo = voucherMap.get(rule.code);
+					if (!voucherInfo || String(voucherInfo.programId) !== String(program._id)) return {
+						matched: false,
+						rejectedCode: {
+							code: rule.code,
+							reason: "Invalid or exhausted voucher"
+						}
+					};
+				}
+			} else if (![...voucherMap.entries()].find(([code, info]) => String(info.programId) === String(program._id) && submittedCodes.includes(code))) return { matched: false };
+		}
+		const now = /* @__PURE__ */ new Date();
+		if (rule.startsAt && rule.startsAt > now) return { matched: false };
+		if (rule.endsAt && rule.endsAt < now) return { matched: false };
+		if (rule.minimumAmount > 0 && subtotal < rule.minimumAmount) return { matched: false };
+		if (rule.minimumQuantity > 0) {
+			if (items.reduce((sum, item) => sum + item.quantity, 0) < rule.minimumQuantity) return { matched: false };
+		}
+		if (rule.applicableProductIds.length > 0) {
+			if (!items.some((item) => rule.applicableProductIds.includes(item.productId))) return { matched: false };
+		}
+		if (rule.applicableCategories.length > 0) {
+			if (!items.some((item) => item.categoryId && rule.applicableCategories.includes(item.categoryId))) return { matched: false };
+		}
+		if (rule.applicableSkus.length > 0) {
+			if (!items.some((item) => item.sku && rule.applicableSkus.includes(item.sku))) return { matched: false };
+		}
+		if (rule.buyQuantity && rule.buyQuantity > 0) {
+			if (items.filter((item) => rule.applicableProductIds.length === 0 || rule.applicableProductIds.includes(item.productId)).reduce((sum, item) => sum + item.quantity, 0) < rule.buyQuantity) return { matched: false };
+		}
+		let matchedCode;
+		if (program.triggerMode === "code") if (rule.code && submittedCodes.includes(rule.code)) matchedCode = rule.code;
+		else matchedCode = [...voucherMap.entries()].find(([code, info]) => String(info.programId) === String(program._id) && submittedCodes.includes(code))?.[0];
+		return {
+			matched: true,
+			matchedCode,
+			matchedRuleId: rule._id
+		};
+	}
+	filterRewardsByRule(rewards, matchedRuleId) {
+		if (!matchedRuleId) return rewards;
+		if (rewards.filter((r) => r.ruleId).length === 0) return rewards;
+		return rewards.filter((r) => !r.ruleId || String(r.ruleId) === String(matchedRuleId));
+	}
+	computeDiscount(reward, items, runningSubtotal) {
+		if (!reward.discountAmount || reward.discountAmount <= 0) return 0;
+		let discount;
+		if (reward.discountScope === "cheapest") {
+			const eligibleItems = this.getEligibleItems(reward, items);
+			if (eligibleItems.length === 0) return 0;
+			const cheapest = Math.min(...eligibleItems.map((item) => item.unitPrice));
+			discount = reward.discountMode === "percentage" ? cheapest * (reward.discountAmount / 100) : Math.min(reward.discountAmount, cheapest);
+		} else if (reward.discountScope === "specific_products") {
+			const eligibleTotal = this.getEligibleItems(reward, items).reduce((sum, item) => sum + (item.lineTotal ?? item.unitPrice * item.quantity), 0);
+			if (eligibleTotal <= 0) return 0;
+			discount = reward.discountMode === "percentage" ? eligibleTotal * (reward.discountAmount / 100) : Math.min(reward.discountAmount, eligibleTotal);
+		} else discount = reward.discountMode === "percentage" ? runningSubtotal * (reward.discountAmount / 100) : Math.min(reward.discountAmount, runningSubtotal);
+		if (reward.maxDiscountAmount && discount > reward.maxDiscountAmount) discount = reward.maxDiscountAmount;
+		return Math.min(Math.round(discount * 100) / 100, runningSubtotal);
+	}
+	getEligibleItems(reward, items) {
+		if (reward.applicableProductIds.length === 0) return items;
+		return items.filter((item) => reward.applicableProductIds.includes(item.productId));
+	}
+	describeDiscount(reward, program) {
+		if (reward.discountMode === "percentage") return `${reward.discountAmount}% off from "${program.name}"`;
+		return `${reward.discountAmount} off from "${program.name}"`;
+	}
+};
+function groupBy(items, keyFn) {
+	const map = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const key = String(keyFn(item));
+		const group = map.get(key);
+		if (group) group.push(item);
+		else map.set(key, [item]);
+	}
+	return map;
+}
+//#endregion
+//#region src/utils/code-generator.ts
+const CHARSET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+function generateCode(length, prefix = "") {
+	const bytes = randomBytes(length);
+	let code = "";
+	for (let i = 0; i < length; i++) code += CHARSET[bytes[i] % 32];
+	return prefix ? `${prefix}${code}` : code;
+}
+function generateCodes(count, length, prefix = "") {
+	const codes = /* @__PURE__ */ new Set();
+	let attempts = 0;
+	const maxAttempts = count * 10;
+	while (codes.size < count && attempts < maxAttempts) {
+		codes.add(generateCode(length, prefix));
+		attempts++;
+	}
+	return [...codes];
+}
+//#endregion
+//#region src/services/voucher.service.ts
+/**
+* VoucherService — multi-repo domain orchestration only.
+*
+* Code generation, redemption (transactional + idempotency), gift card
+* spend/topUp, and validation live here because they need programRepo +
+* voucherRepo + config + transactions.
+*
+* Simple lookups (getById, getByCode, getAll) and the cancel domain verb
+* live on VoucherRepository directly — callers use the repo. §2/§3.
+*/
+var VoucherService = class {
+	constructor(voucherRepo, programRepo, unitOfWork, dispatchDeps, config) {
+		this.voucherRepo = voucherRepo;
+		this.programRepo = programRepo;
+		this.unitOfWork = unitOfWork;
+		this.dispatchDeps = dispatchDeps;
+		this.config = config;
+	}
+	async generateCodes(input, ctx) {
+		const program = await this.programRepo.getById(input.programId, {
+			throwOnNotFound: false,
+			lean: true,
+			...ctx
+		});
+		if (!program) throw new ProgramNotFoundError(input.programId);
+		const { codeLength, codePrefix } = this.config.voucher;
+		const codes = generateCodes(input.count, codeLength, codePrefix);
+		const expiresAt = input.expiresAt ?? (this.config.voucher.defaultExpiryDays ? new Date(Date.now() + this.config.voucher.defaultExpiryDays * 864e5) : void 0);
+		const isGiftCard = program.programType === "gift_card";
+		const data = codes.map((code) => ({
+			programId: input.programId,
+			code,
+			status: "active",
+			customerId: input.customerId,
+			usageLimit: isGiftCard ? 999999 : 1,
+			usedCount: 0,
+			...isGiftCard ? {
+				initialBalance: 0,
+				currentBalance: 0,
+				balanceLedger: []
+			} : {},
+			...expiresAt ? { expiresAt } : {},
+			redemptions: [],
+			...input.metadata ? { metadata: input.metadata } : {}
+		}));
+		const vouchers = await this.voucherRepo.createMany(data, ctx);
+		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.VOUCHER_GENERATED, {
+			programId: input.programId,
+			voucherIds: vouchers.map((v) => v._id),
+			codes: vouchers.map((v) => v.code),
+			count: vouchers.length,
+			actorId: ctx.actorId
+		}, ctx), ctx);
+		return vouchers;
+	}
+	async generateSingleCode(input, ctx) {
+		const program = await this.programRepo.getById(input.programId, {
+			throwOnNotFound: false,
+			lean: true,
+			...ctx
+		});
+		if (!program) throw new ProgramNotFoundError(input.programId);
+		const code = input.code?.toUpperCase() ?? generateCode(this.config.voucher.codeLength, this.config.voucher.codePrefix);
+		const isGiftCard = program.programType === "gift_card";
+		const balance = input.initialBalance ?? 0;
+		const expiresAt = input.expiresAt ?? (this.config.voucher.defaultExpiryDays ? new Date(Date.now() + this.config.voucher.defaultExpiryDays * 864e5) : void 0);
+		const data = {
+			programId: input.programId,
+			code,
+			status: "active",
+			customerId: input.customerId,
+			usageLimit: isGiftCard ? 999999 : 1,
+			usedCount: 0,
+			...isGiftCard ? {
+				initialBalance: balance,
+				currentBalance: balance,
+				balanceLedger: []
+			} : {},
+			...expiresAt ? { expiresAt } : {},
+			redemptions: [],
+			...input.metadata ? { metadata: input.metadata } : {}
+		};
+		const voucher = await this.voucherRepo.create(data, ctx);
+		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.VOUCHER_GENERATED, {
+			programId: input.programId,
+			voucherIds: [voucher._id],
+			codes: [voucher.code],
+			count: 1,
+			actorId: ctx.actorId
+		}, ctx), ctx);
+		return voucher;
+	}
+	async validateCode(code, ctx) {
+		const voucher = await this.voucherRepo.getByCode(code, ctx);
+		if (!voucher) return {
+			valid: false,
+			error: "Voucher not found"
+		};
+		if (voucher.status === "expired") return {
+			valid: false,
+			error: "Voucher has expired"
+		};
+		if (voucher.status === "cancelled") return {
+			valid: false,
+			error: "Voucher has been cancelled"
+		};
+		if (voucher.status === "used") return {
+			valid: false,
+			error: "Voucher has already been used"
+		};
+		if (voucher.expiresAt && voucher.expiresAt < /* @__PURE__ */ new Date()) return {
+			valid: false,
+			error: "Voucher has expired"
+		};
+		if (voucher.usedCount >= voucher.usageLimit) return {
+			valid: false,
+			error: "Voucher has reached its usage limit"
+		};
+		const program = await this.programRepo.getById(voucher.programId, {
+			throwOnNotFound: false,
+			lean: true,
+			...ctx
+		});
+		return {
+			valid: true,
+			voucher: {
+				code: voucher.code,
+				programId: voucher.programId,
+				programType: program?.programType ?? "unknown",
+				status: voucher.status,
+				remainingUses: voucher.usageLimit - voucher.usedCount,
+				...voucher.currentBalance !== void 0 ? { currentBalance: voucher.currentBalance } : {},
+				...voucher.expiresAt ? { expiresAt: voucher.expiresAt } : {}
+			}
+		};
+	}
+	async redeem(input, ctx) {
+		return this.unitOfWork.withTransaction(async (session) => {
+			const voucher = await this.voucherRepo.getByCode(input.code, {
+				...ctx,
+				session
+			});
+			if (!voucher) throw new VoucherNotFoundError(input.code);
+			this.assertVoucherUsable(voucher);
+			if (input.idempotencyKey) {
+				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey)) throw new DuplicateRedemptionError(input.idempotencyKey);
+			}
+			const redemption = {
+				orderId: input.orderId,
+				customerId: input.customerId,
+				discountAmount: input.discountAmount,
+				redeemedAt: /* @__PURE__ */ new Date(),
+				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+			};
+			const updated = await this.voucherRepo.incrementUsage(voucher._id, redemption, {
+				...ctx,
+				session
+			});
+			if (updated.usedCount >= updated.usageLimit) await this.voucherRepo.update(voucher._id, { status: "used" }, {
+				lean: true,
+				...ctx,
+				session
+			});
+			await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.VOUCHER_REDEEMED, {
+				voucherId: voucher._id,
+				code: voucher.code,
+				orderId: input.orderId,
+				discountAmount: input.discountAmount,
+				customerId: input.customerId
+			}, ctx), {
+				...ctx,
+				session
+			});
+			return updated;
+		});
+	}
+	async getBalance(code, ctx) {
+		const voucher = await this.voucherRepo.getByCode(code, ctx);
+		if (!voucher) throw new VoucherNotFoundError(code);
+		if (voucher.initialBalance === void 0) throw new ValidationError("Voucher is not a gift card");
+		return {
+			code: voucher.code,
+			initialBalance: voucher.initialBalance ?? 0,
+			currentBalance: voucher.currentBalance ?? 0,
+			spent: (voucher.initialBalance ?? 0) - (voucher.currentBalance ?? 0),
+			voucherId: voucher._id
+		};
+	}
+	async spend(input, ctx) {
+		if (input.amount <= 0) throw new ValidationError("Spend amount must be positive");
+		try {
+			return await this.spendInTransaction(input, ctx);
+		} catch (err) {
+			if (isWriteConflict(err)) throw new ConcurrencyConflictError("voucher", input.code, err);
+			throw err;
+		}
+	}
+	async spendInTransaction(input, ctx) {
+		return this.unitOfWork.withTransaction(async (session) => {
+			const voucher = await this.voucherRepo.getByCode(input.code, {
+				...ctx,
+				session
+			});
+			if (!voucher) throw new VoucherNotFoundError(input.code);
+			this.assertVoucherUsable(voucher);
+			const balance = voucher.currentBalance ?? 0;
+			if (!this.config.giftCard.allowNegativeBalance && balance < input.amount) throw new InsufficientBalanceError(input.code, balance, input.amount);
+			if (input.idempotencyKey) {
+				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey)) throw new DuplicateRedemptionError(input.idempotencyKey);
+			}
+			const entry = {
+				amount: -input.amount,
+				orderId: input.orderId,
+				description: input.description ?? `Spent on order ${input.orderId}`,
+				createdAt: /* @__PURE__ */ new Date(),
+				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+			};
+			const updated = await this.voucherRepo.addLedgerEntry(voucher._id, entry, -input.amount, {
+				...ctx,
+				session
+			});
+			const newBalance = updated.currentBalance ?? 0;
+			await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.GIFT_CARD_SPENT, {
+				voucherId: voucher._id,
+				code: voucher.code,
+				amount: input.amount,
+				remainingBalance: newBalance,
+				orderId: input.orderId
+			}, ctx), {
+				...ctx,
+				session
+			});
+			if (newBalance <= 0) {
+				await this.voucherRepo.update(voucher._id, { status: "used" }, {
+					lean: true,
+					...ctx,
+					session
+				});
+				await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.GIFT_CARD_EXHAUSTED, {
+					voucherId: voucher._id,
+					code: voucher.code,
+					status: "used"
+				}, ctx), {
+					...ctx,
+					session
+				});
+			}
+			return {
+				code: updated.code,
+				initialBalance: updated.initialBalance ?? 0,
+				currentBalance: newBalance,
+				spent: (updated.initialBalance ?? 0) - newBalance,
+				voucherId: updated._id
+			};
+		});
+	}
+	async topUp(input, ctx) {
+		if (input.amount <= 0) throw new ValidationError("Top-up amount must be positive");
+		const voucher = await this.voucherRepo.getByCode(input.code, ctx);
+		if (!voucher) throw new VoucherNotFoundError(input.code);
+		const maxBalance = this.config.giftCard.maxBalance;
+		if (maxBalance !== null && (voucher.currentBalance ?? 0) + input.amount > maxBalance) throw new ValidationError(`Top-up would exceed max balance of ${maxBalance}`);
+		if (input.idempotencyKey) {
+			if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey)) throw new DuplicateRedemptionError(input.idempotencyKey);
+		}
+		const entry = {
+			amount: input.amount,
+			description: input.description ?? "Top-up",
+			createdAt: /* @__PURE__ */ new Date(),
+			...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+		};
+		const updated = await this.voucherRepo.addLedgerEntry(voucher._id, entry, input.amount, ctx);
+		if (voucher.status === "used") await this.voucherRepo.update(voucher._id, { status: "active" }, {
+			lean: true,
+			...ctx
+		});
+		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.GIFT_CARD_TOPPED_UP, {
+			voucherId: voucher._id,
+			code: voucher.code,
+			amount: input.amount,
+			newBalance: updated.currentBalance ?? 0
+		}, ctx), ctx);
+		return {
+			code: updated.code,
+			initialBalance: updated.initialBalance ?? 0,
+			currentBalance: updated.currentBalance ?? 0,
+			spent: (updated.initialBalance ?? 0) - (updated.currentBalance ?? 0),
+			voucherId: updated._id
+		};
+	}
+	assertVoucherUsable(voucher) {
+		if (voucher.status === "expired") throw new VoucherExpiredError(voucher.code);
+		if (voucher.status === "cancelled") throw new VoucherExpiredError(voucher.code);
+		if (voucher.status === "used") {
+			if (voucher.initialBalance !== void 0) throw new GiftCardExhaustedError(voucher.code);
+			throw new VoucherExhaustedError(voucher.code);
+		}
+		if (voucher.expiresAt && voucher.expiresAt < /* @__PURE__ */ new Date()) throw new VoucherExpiredError(voucher.code);
+		if (voucher.usedCount >= voucher.usageLimit) throw new VoucherExhaustedError(voucher.code);
+	}
+};
+/**
+* Detect MongoDB's transient WriteConflict error across the shapes it
+* arrives in (raw driver error, mongoose-wrapped VersionError, mongokit
+* rethrows). Centralised so every contended write site can opt-in.
+*/
+function isWriteConflict(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const e = err;
+	if (e.code === 112 || e.codeName === "WriteConflict") return true;
+	if (e.name === "MongoServerError" && typeof e.message === "string" && /write conflict/i.test(e.message)) return true;
+	if (Array.isArray(e.errorLabels) && e.errorLabels.includes("TransientTransactionError")) return true;
+	if (typeof e.message === "string" && /write conflict/i.test(e.message)) return true;
+	if (e.cause !== void 0) return isWriteConflict(e.cause);
+	return false;
+}
+//#endregion
+//#region src/services/create-services.ts
+function createServices(deps) {
+	const { repositories, unitOfWork, dispatchDeps, config } = deps;
+	return {
+		voucher: new VoucherService(repositories.voucher, repositories.program, unitOfWork, dispatchDeps, config),
+		evaluation: new EvaluationService(repositories.program, repositories.rule, repositories.reward, repositories.voucher, unitOfWork, dispatchDeps, config)
 	};
+}
+//#endregion
+//#region src/events/promo-event-catalog.ts
+/**
+* Promo event catalog — Zod-source-of-truth definitions for every
+* `promo.*` event.
+*
+* Each definition exposes:
+*   - `.zodSchema`   — source of truth, used by host code's `.safeParse()`
+*   - `.schema`      — JSON Schema derived via `z.toJSONSchema()`, consumed
+*                     by Arc's EventRegistry + OpenAPI plugin
+*   - `.create(...)` — DomainEvent envelope builder, structurally compatible
+*                     with `@classytic/arc`'s `EventDefinitionOutput`
+*
+* Structurally compatible with Arc 2.10's `EventRegistry` — hosts register
+* `promoEventDefinitions` directly, no adapter code. Promo does NOT import
+* from `@classytic/arc` (PACKAGE_RULES §11); compatibility is purely
+* structural.
+*
+* Payload schemas mirror the typed interfaces in
+* [event-payloads.ts](./event-payloads.ts). See PACKAGE_RULES §18.5 for
+* the pattern.
+*
+* @example Wiring into an Arc app
+* ```ts
+* import { createEventRegistry } from '@classytic/arc/events';
+* import { promoEventDefinitions } from '@classytic/promo';
+*
+* const registry = createEventRegistry();
+* for (const def of promoEventDefinitions) registry.register(def);
+* ```
+*/
+function definePromoEvent(input) {
+	const { name, version = 1, description, zodSchema } = input;
+	const def = {
+		name,
+		version,
+		schema: z.toJSONSchema(zodSchema),
+		zodSchema,
+		create(payload, meta) {
+			return createEvent(name, payload, {
+				source: "promo",
+				...meta
+			});
+		}
+	};
+	if (description !== void 0) def.description = description;
+	return def;
+}
+/** Mirrors `ProgramLifecyclePayload`. */
+const programLifecycleSchema = z.object({
+	programId: z.string(),
+	programType: z.string(),
+	status: z.string(),
+	actorId: z.string().optional()
+});
+/** Mirrors `RulePayload`. */
+const ruleSchema = z.object({
+	programId: z.string(),
+	ruleId: z.string(),
+	actorId: z.string().optional()
+});
+/** Mirrors `RewardPayload`. */
+const rewardSchema = z.object({
+	programId: z.string(),
+	rewardId: z.string(),
+	actorId: z.string().optional()
+});
+/** Mirrors `VoucherGeneratedPayload`. */
+const voucherGeneratedSchema = z.object({
+	programId: z.string(),
+	voucherIds: z.array(z.string()),
+	codes: z.array(z.string()),
+	count: z.number().int().nonnegative(),
+	actorId: z.string().optional()
+});
+/** Mirrors `VoucherRedeemedPayload`. */
+const voucherRedeemedSchema = z.object({
+	voucherId: z.string(),
+	code: z.string(),
+	orderId: z.string(),
+	discountAmount: z.number(),
+	customerId: z.string().optional()
+});
+/**
+* Mirrors `VoucherLifecyclePayload` — shared by VOUCHER_CANCELLED,
+* VOUCHER_EXPIRED, and GIFT_CARD_EXHAUSTED (repo emits `status: 'cancelled'`
+* / `'used'` / host-supplied terminal value).
+*/
+const voucherLifecycleSchema = z.object({
+	voucherId: z.string(),
+	code: z.string(),
+	status: z.string()
+});
+/** Mirrors `GiftCardSpentPayload`. */
+const giftCardSpentSchema = z.object({
+	voucherId: z.string(),
+	code: z.string(),
+	amount: z.number(),
+	remainingBalance: z.number(),
+	orderId: z.string()
+});
+/** Mirrors `GiftCardToppedUpPayload`. */
+const giftCardToppedUpSchema = z.object({
+	voucherId: z.string(),
+	code: z.string(),
+	amount: z.number(),
+	newBalance: z.number()
+});
+/** Mirrors `EvaluationCompletedPayload`. */
+const evaluationCompletedSchema = z.object({
+	evaluationId: z.string(),
+	totalDiscount: z.number(),
+	programsApplied: z.number().int().nonnegative(),
+	codesUsed: z.array(z.string()),
+	isPreview: z.boolean()
+});
+/** Mirrors `EvaluationCommittedPayload`. */
+const evaluationCommittedSchema = z.object({
+	evaluationId: z.string(),
+	orderId: z.string(),
+	totalDiscount: z.number()
+});
+/** Single-field rollback payload — emitted by `evaluation.service.ts`. */
+const evaluationRolledBackSchema = z.object({ evaluationId: z.string() });
+const ProgramCreated = definePromoEvent({
+	name: PromoEvents.PROGRAM_CREATED,
+	description: "A new promo program was created (starts in draft).",
+	zodSchema: programLifecycleSchema
+});
+const ProgramActivated = definePromoEvent({
+	name: PromoEvents.PROGRAM_ACTIVATED,
+	description: "A draft or paused program was activated.",
+	zodSchema: programLifecycleSchema
+});
+const ProgramPaused = definePromoEvent({
+	name: PromoEvents.PROGRAM_PAUSED,
+	description: "An active program was paused.",
+	zodSchema: programLifecycleSchema
+});
+const ProgramArchived = definePromoEvent({
+	name: PromoEvents.PROGRAM_ARCHIVED,
+	description: "A program was archived (terminal — no further transitions).",
+	zodSchema: programLifecycleSchema
+});
+const RuleAdded = definePromoEvent({
+	name: PromoEvents.RULE_ADDED,
+	description: "A new rule was added to a program.",
+	zodSchema: ruleSchema
+});
+const RuleUpdated = definePromoEvent({
+	name: PromoEvents.RULE_UPDATED,
+	description: "An existing rule on a program was updated.",
+	zodSchema: ruleSchema
+});
+const RuleRemoved = definePromoEvent({
+	name: PromoEvents.RULE_REMOVED,
+	description: "A rule was removed from a program.",
+	zodSchema: ruleSchema
+});
+const RewardAdded = definePromoEvent({
+	name: PromoEvents.REWARD_ADDED,
+	description: "A reward was added to a program.",
+	zodSchema: rewardSchema
+});
+const RewardUpdated = definePromoEvent({
+	name: PromoEvents.REWARD_UPDATED,
+	description: "A reward on a program was updated.",
+	zodSchema: rewardSchema
+});
+const RewardRemoved = definePromoEvent({
+	name: PromoEvents.REWARD_REMOVED,
+	description: "A reward was removed from a program.",
+	zodSchema: rewardSchema
+});
+const VoucherGenerated = definePromoEvent({
+	name: PromoEvents.VOUCHER_GENERATED,
+	description: "One or more vouchers were generated for a program.",
+	zodSchema: voucherGeneratedSchema
+});
+const VoucherRedeemed = definePromoEvent({
+	name: PromoEvents.VOUCHER_REDEEMED,
+	description: "A voucher was redeemed against an order.",
+	zodSchema: voucherRedeemedSchema
+});
+const VoucherCancelled = definePromoEvent({
+	name: PromoEvents.VOUCHER_CANCELLED,
+	description: "A voucher was cancelled by an operator.",
+	zodSchema: voucherLifecycleSchema
+});
+const VoucherExpired = definePromoEvent({
+	name: PromoEvents.VOUCHER_EXPIRED,
+	description: "A voucher reached its expiry date and was transitioned to expired.",
+	zodSchema: voucherLifecycleSchema
+});
+const GiftCardSpent = definePromoEvent({
+	name: PromoEvents.GIFT_CARD_SPENT,
+	description: "A gift-card voucher was debited against an order — remaining balance reported.",
+	zodSchema: giftCardSpentSchema
+});
+const GiftCardToppedUp = definePromoEvent({
+	name: PromoEvents.GIFT_CARD_TOPPED_UP,
+	description: "A gift-card voucher received a top-up — new balance reported.",
+	zodSchema: giftCardToppedUpSchema
+});
+const GiftCardExhausted = definePromoEvent({
+	name: PromoEvents.GIFT_CARD_EXHAUSTED,
+	description: "A gift-card voucher reached a zero balance and was marked used.",
+	zodSchema: voucherLifecycleSchema
+});
+const EvaluationCompleted = definePromoEvent({
+	name: PromoEvents.EVALUATION_COMPLETED,
+	description: "A cart evaluation finished (preview or pre-commit) — totals and applied codes reported.",
+	zodSchema: evaluationCompletedSchema
+});
+const EvaluationCommitted = definePromoEvent({
+	name: PromoEvents.EVALUATION_COMMITTED,
+	description: "A stored evaluation was committed against an order — usage counters moved.",
+	zodSchema: evaluationCommittedSchema
+});
+const EvaluationRolledBack = definePromoEvent({
+	name: PromoEvents.EVALUATION_ROLLED_BACK,
+	description: "A stored evaluation was discarded without commit.",
+	zodSchema: evaluationRolledBackSchema
+});
+/**
+* Every promo event defined in the package — pass to Arc's
+* `EventRegistry`. Hosts wire ONE array; the whole `promo.*` namespace
+* becomes introspectable via OpenAPI and auto-validated at publish time
+* when `eventPlugin({ validateMode: 'reject' })` is set.
+*/
+const promoEventDefinitions = [
+	ProgramCreated,
+	ProgramActivated,
+	ProgramPaused,
+	ProgramArchived,
+	RuleAdded,
+	RuleUpdated,
+	RuleRemoved,
+	RewardAdded,
+	RewardUpdated,
+	RewardRemoved,
+	VoucherGenerated,
+	VoucherRedeemed,
+	VoucherCancelled,
+	VoucherExpired,
+	GiftCardSpent,
+	GiftCardToppedUp,
+	GiftCardExhausted,
+	EvaluationCompleted,
+	EvaluationCommitted,
+	EvaluationRolledBack
+];
+//#endregion
+//#region src/index.ts
+function resolveConfig(config) {
+	const tenant = resolveTenantConfig(config.tenant);
+	if (typeof config.tenant === "object" && config.tenant !== null) {
+		const explicit = config.tenant.contextKey ?? config.tenant.tenantField;
+		if (explicit) tenant.contextKey = explicit;
+	}
 	const resolved = {
 		evaluation: {
 			maxStackablePromotions: config.evaluation?.maxStackablePromotions ?? 5,
@@ -66,21 +1746,28 @@ var MongoUnitOfWork = class {
 };
 function createPromoEngine(config) {
 	const resolvedConfig = resolveConfig(config);
-	const models = createModels(config.mongoose, resolvedConfig.tenant, config.indexes);
-	const repositories = createRepositories(models, config.plugins, resolvedConfig.tenant.field);
-	const unitOfWork = new MongoUnitOfWork(config.mongoose);
-	const events = config.events?.adapter ?? new InProcessEventBus();
+	const models = createModels(config.mongoose, resolvedConfig.tenant, config.indexes, config.autoIndex);
+	const events = config.events?.transport ?? new InProcessPromoBus();
+	const dispatchDeps = {
+		events,
+		...config.outbox !== void 0 ? { outbox: config.outbox } : {},
+		...config.logger !== void 0 ? { logger: config.logger } : {}
+	};
+	const repositories = createRepositories(models, config.plugins, resolvedConfig.tenant, dispatchDeps);
 	return {
 		models,
 		repositories,
 		services: createServices({
 			repositories,
-			unitOfWork,
-			events,
+			unitOfWork: new MongoUnitOfWork(config.mongoose),
+			dispatchDeps,
 			config: resolvedConfig
 		}),
-		events
+		events,
+		async syncIndexes() {
+			await Promise.all(Object.values(models).map((m) => m.createIndexes()));
+		}
 	};
 }
 //#endregion
-export { PromoEvents, createPromoEngine, resolveConfig };
+export { EvaluationCommitted, EvaluationCompleted, EvaluationRolledBack, GiftCardExhausted, GiftCardSpent, GiftCardToppedUp, ProgramActivated, ProgramArchived, ProgramCreated, ProgramPaused, ProgramRepository, PromoEvents, RewardAdded, RewardRemoved, RewardRepository, RewardUpdated, RuleAdded, RuleRemoved, RuleRepository, RuleUpdated, VoucherCancelled, VoucherExpired, VoucherGenerated, VoucherRedeemed, VoucherRepository, createPromoEngine, promoEventDefinitions, resolveConfig };