@classytic/loyalty 0.1.0 → 0.2.1

package/dist/repositories-DBSxe9st.mjs

@@ -0,0 +1,1919 @@
+import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-Cyt9TwX6.mjs";
+import { Repository, multiTenantPlugin } from "@classytic/mongokit";
+import { randomBytes } from "node:crypto";
+//#region src/domain/errors/base.ts
+var LoyaltyError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = this.constructor.name;
+	}
+	toJSON() {
+		return {
+			code: this.code,
+			message: this.message,
+			name: this.name
+		};
+	}
+};
+//#endregion
+//#region src/domain/errors/domain-errors.ts
+var InsufficientPointsError = class extends LoyaltyError {
+	code = "INSUFFICIENT_POINTS";
+	httpStatus = 400;
+	constructor(available, requested) {
+		super(`Insufficient points. Available: ${available}, requested: ${requested}`);
+	}
+};
+var MemberNotFoundError = class extends LoyaltyError {
+	code = "MEMBER_NOT_FOUND";
+	httpStatus = 404;
+	constructor(id) {
+		super(`Member not found: ${id}`);
+	}
+};
+var MemberAlreadyEnrolledError = class extends LoyaltyError {
+	code = "MEMBER_ALREADY_ENROLLED";
+	httpStatus = 409;
+	constructor(externalId) {
+		super(`Member already enrolled: ${externalId}`);
+	}
+};
+var MemberInactiveError = class extends LoyaltyError {
+	code = "MEMBER_INACTIVE";
+	httpStatus = 422;
+	constructor(id) {
+		super(`Member is not active: ${id}`);
+	}
+};
+var TierNotFoundError = class extends LoyaltyError {
+	code = "TIER_NOT_FOUND";
+	httpStatus = 404;
+	constructor(id) {
+		super(`Tier not found: ${id}`);
+	}
+};
+var RedemptionNotFoundError = class extends LoyaltyError {
+	code = "REDEMPTION_NOT_FOUND";
+	httpStatus = 404;
+	constructor(id) {
+		super(`Redemption not found: ${id}`);
+	}
+};
+var RedemptionExpiredError = class extends LoyaltyError {
+	code = "REDEMPTION_EXPIRED";
+	httpStatus = 410;
+	constructor(id) {
+		super(`Redemption expired: ${id}`);
+	}
+};
+var ReferralNotFoundError = class extends LoyaltyError {
+	code = "REFERRAL_NOT_FOUND";
+	httpStatus = 404;
+	constructor(id) {
+		super(`Referral not found: ${id}`);
+	}
+};
+var DuplicateReferralError = class extends LoyaltyError {
+	code = "DUPLICATE_REFERRAL";
+	httpStatus = 409;
+	constructor(refereeId) {
+		super(`Referee already has a referral: ${refereeId}`);
+	}
+};
+var ReferralLimitExceededError = class extends LoyaltyError {
+	code = "REFERRAL_LIMIT_EXCEEDED";
+	httpStatus = 429;
+	constructor(limit, periodDays) {
+		super(`Referral limit of ${limit} per ${periodDays} days exceeded`);
+	}
+};
+var SelfReferralError = class extends LoyaltyError {
+	code = "SELF_REFERRAL";
+	httpStatus = 422;
+	constructor() {
+		super("Cannot refer yourself");
+	}
+};
+var CircularReferralError = class extends LoyaltyError {
+	code = "CIRCULAR_REFERRAL";
+	httpStatus = 422;
+	constructor() {
+		super("Circular referral detected");
+	}
+};
+var ValidationError = class extends LoyaltyError {
+	code = "VALIDATION_ERROR";
+	httpStatus = 400;
+};
+var TenantIsolationError = class extends LoyaltyError {
+	code = "TENANT_ISOLATION";
+	httpStatus = 403;
+	constructor() {
+		super("Tenant context is required but not provided");
+	}
+};
+//#endregion
+//#region src/utils/tenant-guard.ts
+/**
+* Throw `TenantIsolationError` when the mongokit-layer multi-tenant plugin
+* is wired and the caller didn't provide the tenant id. Host-layer scoping
+* (arc preset + BaseController) runs independently with `tenant.enabled:
+* false`, so we skip the assertion in that mode.
+*/
+function assertTenantContext(ctx, tenant) {
+	if (!tenant.enabled) return;
+	if (!ctx[tenant.contextKey]) throw new TenantIsolationError();
+}
+/**
+* Extract the tenant id from ctx, regardless of whether the mongokit plugin
+* is enabled. The `tenantField` / `contextKey` on `ResolvedTenant` is
+* always populated by `resolveConfig`, so this safely reaches the value
+* whether the host opts into the auto-wired plugin or scopes at its own
+* framework layer (arc's preset + BaseController).
+*/
+function getTenantValue(ctx, tenant) {
+	return ctx[tenant.contextKey];
+}
+/**
+* Build a repo-level context object carrying the tenant id.
+*
+* Spread into mongokit options. When the mongokit `multiTenantPlugin` is
+* wired it auto-reads the value from `options.organizationId`. When the
+* plugin is OFF (arc-host pattern), the repo-level `create`/`createMany`
+* overrides and the `tenantField`-aware lookups (see `memberRepo.loadByX`,
+* etc.) still pick it up — matching the `@classytic/order` /
+* `@classytic/promo` pattern where "child repos set `organizationId`
+* explicitly on the doc".
+*/
+function tenantCtx(tenant, tenantId) {
+	if (!tenantId) return {};
+	return { [tenant.contextKey]: tenantId };
+}
+/**
+* Copy the tenant id from the repo options into the write payload.
+*
+* Called from repository `create` / `createMany` overrides so the document
+* persists with the correct tenant id even when the host has opted OUT
+* of the auto-wired `multiTenantPlugin`. The options object is populated
+* by `tenantCtx()` which writes under `tenant.contextKey`, so the read
+* here MUST use `contextKey` — not `tenantField`. They coincide in the
+* default config (`organizationId === organizationId`) which masked the
+* mismatch; with a divergent contextKey the copy silently never fired
+* and writes landed without a tenant on the doc.
+*
+* When the payload already has the field (e.g. arc's `BaseController.create`
+* pre-writes it under `tenantField`), this is a no-op.
+*/
+function injectTenantIntoData(data, options, tenant) {
+	const field = tenant.tenantField;
+	if (!field) return;
+	if (data[field] != null) return;
+	const value = options?.[tenant.contextKey] ?? options?.[field];
+	if (value != null) data[field] = value;
+}
+//#endregion
+//#region src/utils/validation.ts
+function validatePoints(points, label = "points") {
+	if (!Number.isFinite(points)) throw new ValidationError(`${label} must be a finite number`);
+	if (!Number.isSafeInteger(points)) throw new ValidationError(`${label} must be a safe integer`);
+}
+function validatePositivePoints(points, label = "points") {
+	validatePoints(points, label);
+	if (points <= 0) throw new ValidationError(`${label} must be positive`);
+}
+function validateOrderTotal(total) {
+	if (!Number.isFinite(total) || total < 0) throw new ValidationError("orderTotal must be a non-negative finite number");
+}
+//#endregion
+//#region src/repositories/earning-rule.repository.ts
+var EarningRuleRepository = class extends Repository {
+	memberRepo;
+	txRepo;
+	config;
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	/** Auto-inject tenant id from options into doc payload. See MemberRepository. */
+	async create(data, options) {
+		injectTenantIntoData(data, options, this.config.tenant);
+		return super.create(data, options);
+	}
+	async createMany(docs, options) {
+		const opts = options;
+		for (const doc of docs) injectTenantIntoData(doc, opts, this.config.tenant);
+		return super.createMany(docs, options);
+	}
+	async evaluateOrder(input, ctx) {
+		validateOrderTotal(input.orderTotal);
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
+		const orderRules = (await this.findAll({
+			status: "active",
+			programId: member.programId
+		}, {
+			sort: { priority: 1 },
+			...tc
+		})).filter((r) => [
+			"order",
+			"category",
+			"tier_bonus"
+		].includes(r.type)).sort((a, b) => a.priority - b.priority);
+		const breakdown = [];
+		const transactions = [];
+		let accumulatedPoints = 0;
+		for (const rule of orderRules) {
+			if (!this.matchesConditions(rule, member, input.orderTotal)) continue;
+			let points = 0;
+			if (rule.type === "order") points = this.calculateOrderPoints(rule, input.orderTotal);
+			else if (rule.type === "category" && input.items) points = this.calculateCategoryPoints(rule, input.items);
+			else if (rule.type === "tier_bonus") {
+				const multiplier = rule.reward.multiplier ?? 1;
+				points = Math.floor(accumulatedPoints * (multiplier - 1));
+			}
+			if (points <= 0) continue;
+			if (rule.reward.maxPointsPerTransaction && points > rule.reward.maxPointsPerTransaction) points = rule.reward.maxPointsPerTransaction;
+			const idempotencyKey = `${input.orderId}:${rule._id}`;
+			const tx = await this.txRepo.earnPoints({
+				memberId: input.memberId,
+				points,
+				description: `Earning rule: ${rule.name}`,
+				referenceType: "order",
+				referenceId: input.orderId,
+				earningRuleId: rule._id,
+				idempotencyKey
+			}, ctx);
+			accumulatedPoints += points;
+			breakdown.push({
+				ruleId: rule._id,
+				ruleName: rule.name,
+				points
+			});
+			transactions.push(tx);
+		}
+		return {
+			totalPoints: accumulatedPoints,
+			breakdown,
+			transactions
+		};
+	}
+	async evaluateAction(input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
+		const actionRules = (await this.findAll({
+			status: "active",
+			programId: member.programId
+		}, {
+			sort: { priority: 1 },
+			...tc
+		})).filter((r) => r.type === "action" && r.conditions.actions?.includes(input.action));
+		const breakdown = [];
+		const transactions = [];
+		let totalPoints = 0;
+		for (const rule of actionRules) {
+			const points = rule.reward.fixedPoints ?? 0;
+			if (points <= 0) continue;
+			const tx = await this.txRepo.earnPoints({
+				memberId: input.memberId,
+				points,
+				description: `Action: ${input.action} (${rule.name})`,
+				referenceType: "action",
+				referenceId: input.referenceId,
+				earningRuleId: rule._id
+			}, ctx);
+			totalPoints += points;
+			breakdown.push({
+				ruleId: rule._id,
+				ruleName: rule.name,
+				points
+			});
+			transactions.push(tx);
+		}
+		return {
+			totalPoints,
+			breakdown,
+			transactions
+		};
+	}
+	matchesConditions(rule, member, orderTotal) {
+		const { conditions } = rule;
+		const now = /* @__PURE__ */ new Date();
+		if (conditions.minOrderAmount && orderTotal < conditions.minOrderAmount) return false;
+		if (conditions.tiers && conditions.tiers.length > 0) {
+			const memberTier = member.tierOverride ?? member.tier;
+			if (!memberTier || !conditions.tiers.includes(memberTier)) return false;
+		}
+		if (conditions.dateRange) {
+			if (conditions.dateRange.start && now < conditions.dateRange.start) return false;
+			if (conditions.dateRange.end && now > conditions.dateRange.end) return false;
+		}
+		if (conditions.dayOfWeek && conditions.dayOfWeek.length > 0) {
+			if (!conditions.dayOfWeek.includes(now.getDay())) return false;
+		}
+		return true;
+	}
+	calculateOrderPoints(rule, orderTotal) {
+		const { reward } = rule;
+		let points = 0;
+		if (reward.pointsPerAmount) points = orderTotal * reward.pointsPerAmount;
+		else if (reward.amountPerPoint && reward.amountPerPoint > 0) points = orderTotal / reward.amountPerPoint;
+		return this.applyRounding(points, reward.roundingMode);
+	}
+	calculateCategoryPoints(rule, items) {
+		const { conditions, reward } = rule;
+		let points = 0;
+		for (const item of items) if (conditions.categories && item.categoryId && conditions.categories.includes(item.categoryId)) {
+			if (reward.pointsPerAmount) points += item.amount * reward.pointsPerAmount;
+			else if (reward.amountPerPoint) points += item.amount / reward.amountPerPoint;
+		}
+		return this.applyRounding(points, reward.roundingMode);
+	}
+	applyRounding(value, mode) {
+		switch (mode) {
+			case "ceil": return Math.ceil(value);
+			case "round": return Math.round(value);
+			default: return Math.floor(value);
+		}
+	}
+};
+//#endregion
+//#region src/events/dispatch.ts
+async function dispatchLoyaltyEvent(deps, event, ctx) {
+	if (deps.outbox) try {
+		const saveOptions = {};
+		if (ctx.session !== void 0) saveOptions.session = ctx.session;
+		await deps.outbox.save(event, saveOptions);
+	} catch (_err) {}
+	if (deps.events) try {
+		await deps.events.publish(event);
+	} catch (_err) {}
+}
+//#endregion
+//#region src/utils/code-generator.ts
+const CHARSET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+function generateReferralCode(length) {
+	if (!Number.isInteger(length) || length < 4 || length > 32) throw new Error("Referral code length must be an integer between 4 and 32");
+	const bytes = randomBytes(length);
+	let code = "";
+	for (let i = 0; i < length; i++) code += CHARSET[bytes[i] % 32];
+	return code;
+}
+//#endregion
+//#region src/repositories/member.repository.ts
+var MemberRepository = class extends Repository {
+	events;
+	outbox;
+	notifications = null;
+	config;
+	/** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
+	async _dispatch(event, ctx) {
+		await dispatchLoyaltyEvent({
+			events: this.events,
+			outbox: this.outbox
+		}, event, ctx);
+	}
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	/**
+	* Auto-inject the tenant id from the repo options into the doc so writes
+	* persist 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). Matches `@classytic/order` / `@classytic/promo`.
+	* No-op when the payload already carries the field.
+	*/
+	async create(data, options) {
+		injectTenantIntoData(data, options, this.config.tenant);
+		return super.create(data, options);
+	}
+	async createMany(docs, options) {
+		const opts = options;
+		for (const doc of docs) injectTenantIntoData(doc, opts, this.config.tenant);
+		return super.createMany(docs, options);
+	}
+	/**
+	* Atomic balance increment -- uses $inc to prevent TOCTOU races.
+	* Returns the updated member document.
+	*/
+	async updateBalance(id, balanceUpdate, ctx) {
+		const inc = {};
+		for (const [key, val] of Object.entries(balanceUpdate)) inc[`balance.${key}`] = val;
+		const updated = await this.update(id, { $inc: inc }, {
+			throwOnNotFound: true,
+			lean: true,
+			...ctx
+		});
+		if (!updated) throw new MemberNotFoundError(id);
+		return updated;
+	}
+	/** Fetches a member by ID (tenant-scoped via plugin) or throws MemberNotFoundError. */
+	async requireMember(memberId, ctx) {
+		const member = await this.getById(memberId, {
+			throwOnNotFound: false,
+			...ctx
+		});
+		if (!member) throw new MemberNotFoundError(memberId);
+		return member;
+	}
+	/** Fetches an active member (tenant-scoped via plugin) or throws MemberNotFoundError / MemberInactiveError. */
+	async requireActiveMember(memberId, ctx) {
+		const member = await this.requireMember(memberId, ctx);
+		if (member.status !== "active") throw new MemberInactiveError(memberId);
+		return member;
+	}
+	async enroll(input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		if (await this.getByQuery({
+			externalId: input.externalId,
+			externalType: input.externalType
+		}, {
+			throwOnNotFound: false,
+			...tc
+		})) throw new MemberAlreadyEnrolledError(input.externalId);
+		const referralCode = generateReferralCode(this.config.referral.codeLength);
+		const now = /* @__PURE__ */ new Date();
+		const data = {
+			programId: input.programId ?? this.config.programId,
+			externalId: input.externalId,
+			externalType: input.externalType,
+			status: "active",
+			cardId: input.cardId,
+			referralCode,
+			tier: input.tier ?? null,
+			tierOverride: null,
+			balance: {
+				current: 0,
+				lifetime: 0,
+				redeemed: 0,
+				expired: 0
+			},
+			enrolledAt: now,
+			metadata: input.metadata
+		};
+		const member = await this.create(data, tc);
+		const payload = {
+			memberId: member._id,
+			externalId: member.externalId,
+			externalType: member.externalType,
+			status: member.status
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.MEMBER_ENROLLED, payload, ctx, {
+			resource: "member",
+			resourceId: member._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.MEMBER_ENROLLED, { ...payload });
+		return member;
+	}
+	async deactivate(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		await this.requireMember(memberId, tc);
+		const updated = await this.update(memberId, {
+			status: "inactive",
+			deactivatedAt: /* @__PURE__ */ new Date()
+		}, {
+			throwOnNotFound: true,
+			lean: true,
+			...tc
+		});
+		if (!updated) throw new MemberNotFoundError(memberId);
+		const payload = {
+			memberId: updated._id,
+			externalId: updated.externalId,
+			externalType: updated.externalType,
+			status: updated.status
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.MEMBER_DEACTIVATED, payload, ctx, {
+			resource: "member",
+			resourceId: updated._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.MEMBER_DEACTIVATED, { ...payload });
+		return updated;
+	}
+	async reactivate(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		await this.requireMember(memberId, tc);
+		const updated = await this.update(memberId, {
+			status: "active",
+			deactivatedAt: null
+		}, {
+			throwOnNotFound: true,
+			lean: true,
+			...tc
+		});
+		if (!updated) throw new MemberNotFoundError(memberId);
+		const payload = {
+			memberId: updated._id,
+			externalId: updated.externalId,
+			externalType: updated.externalType,
+			status: updated.status
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.MEMBER_REACTIVATED, payload, ctx, {
+			resource: "member",
+			resourceId: updated._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.MEMBER_REACTIVATED, { ...payload });
+		return updated;
+	}
+	async suspend(memberId, reason, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const member = await this.requireMember(memberId, tc);
+		const updated = await this.update(memberId, {
+			status: "suspended",
+			metadata: {
+				...member.metadata,
+				suspendReason: reason
+			}
+		}, {
+			throwOnNotFound: true,
+			lean: true,
+			...tc
+		});
+		if (!updated) throw new MemberNotFoundError(memberId);
+		const payload = {
+			memberId: updated._id,
+			externalId: updated.externalId,
+			externalType: updated.externalType,
+			status: updated.status
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.MEMBER_SUSPENDED, payload, ctx, {
+			resource: "member",
+			resourceId: updated._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.MEMBER_SUSPENDED, { ...payload });
+		return updated;
+	}
+};
+//#endregion
+//#region src/repositories/point-transaction.repository.ts
+var PointTransactionRepository = class extends Repository {
+	memberRepo;
+	events;
+	outbox;
+	notifications = null;
+	unitOfWork;
+	config;
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	/** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
+	async _dispatch(event, ctx) {
+		await dispatchLoyaltyEvent({
+			events: this.events,
+			outbox: this.outbox
+		}, event, ctx);
+	}
+	/**
+	* Auto-inject tenant id from options into doc payload. Matches
+	* `@classytic/order` / `@classytic/promo` — see MemberRepository.
+	*/
+	async create(data, options) {
+		injectTenantIntoData(data, options, this.config.tenant);
+		return super.create(data, options);
+	}
+	async createMany(docs, options) {
+		const opts = options;
+		for (const doc of docs) injectTenantIntoData(doc, opts, this.config.tenant);
+		return super.createMany(docs, options);
+	}
+	async earnPoints(input, ctx) {
+		validatePositivePoints(input.points);
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		if (input.idempotencyKey) {
+			const existing = await this.getByQuery({ idempotencyKey: input.idempotencyKey }, {
+				throwOnNotFound: false,
+				...tc
+			});
+			if (existing) return existing;
+		}
+		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
+		try {
+			const tx = await this.unitOfWork.withTransaction(async (session) => {
+				if (input.idempotencyKey) {
+					const dup = await this.getByQuery({ idempotencyKey: input.idempotencyKey }, {
+						throwOnNotFound: false,
+						...tc
+					});
+					if (dup) return dup;
+				}
+				const updatedMember = await this.memberRepo.updateBalance(input.memberId, {
+					current: input.points,
+					lifetime: input.points
+				}, {
+					session,
+					...tc
+				});
+				const data = {
+					memberId: input.memberId,
+					programId: member.programId,
+					type: "earn",
+					points: input.points,
+					balanceAfter: updatedMember.balance.current,
+					description: input.description,
+					referenceType: input.referenceType,
+					referenceId: input.referenceId,
+					earningRuleId: input.earningRuleId,
+					expiresAt: input.expiresAt,
+					actorId: ctx.actorId,
+					...input.metadata ? { metadata: input.metadata } : {}
+				};
+				if (input.idempotencyKey) data.idempotencyKey = input.idempotencyKey;
+				return this.create(data, {
+					session,
+					...tc
+				});
+			});
+			const payload = {
+				memberId: member._id,
+				externalId: member.externalId,
+				externalType: member.externalType,
+				points: input.points,
+				balanceAfter: tx.balanceAfter,
+				transactionId: tx._id,
+				referenceType: input.referenceType,
+				referenceId: input.referenceId
+			};
+			await this._dispatch(createEvent(LoyaltyEvents.POINTS_EARNED, payload, ctx, {
+				resource: "pointTransaction",
+				resourceId: tx._id
+			}), ctx);
+			this.notifications?.notify(LoyaltyEvents.POINTS_EARNED, { ...payload });
+			return tx;
+		} catch (err) {
+			if (input.idempotencyKey && (isDuplicateKey(err) || isWriteConflict(err))) {
+				const existing = await this.getByQuery({ idempotencyKey: input.idempotencyKey }, {
+					throwOnNotFound: false,
+					...tc
+				});
+				if (existing) return existing;
+			}
+			throw err;
+		}
+	}
+	/**
+	* Fans out `earnPoints` across many members for bulk-issuance campaigns
+	* (welcome bonuses, holiday boosts, win-back). Per-member failures do
+	* NOT abort the batch — they surface in `errors[]` with the memberId +
+	* message, matching `@classytic/commission`'s `ingestSplit` shape.
+	*
+	* Idempotency: each row derives its key as `${source.eventId}:${memberId}`
+	* so retrying the whole batch collapses onto the same transactions.
+	*
+	* Events: emits exactly ONE `CAMPAIGN_AWARDED` with aggregate counts —
+	* NOT one-per-member, to avoid an event storm for large batches. The
+	* underlying `POINTS_EARNED` events still fire (one per successful row)
+	* for ledger consumers that need per-member granularity.
+	*/
+	async awardBatch(members, source, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		let awarded = 0;
+		let skipped = 0;
+		let totalPoints = 0;
+		const errors = [];
+		for (const row of members) {
+			try {
+				validatePositivePoints(row.points);
+			} catch (err) {
+				errors.push({
+					memberId: row.memberId,
+					error: err instanceof Error ? err.message : String(err)
+				});
+				skipped++;
+				continue;
+			}
+			try {
+				const input = {
+					memberId: row.memberId,
+					points: row.points,
+					description: source.description,
+					idempotencyKey: `${source.eventId}:${row.memberId}`,
+					metadata: {
+						campaignId: source.campaignId,
+						...source.metadata ?? {}
+					}
+				};
+				if (source.referenceType !== void 0) input.referenceType = source.referenceType;
+				if (source.referenceId !== void 0) input.referenceId = source.referenceId;
+				if (source.expiresAt !== void 0) input.expiresAt = source.expiresAt;
+				await this.earnPoints(input, ctx);
+				awarded++;
+				totalPoints += row.points;
+			} catch (err) {
+				errors.push({
+					memberId: row.memberId,
+					error: err instanceof Error ? err.message : String(err)
+				});
+				skipped++;
+			}
+		}
+		await this._dispatch(createEvent(LoyaltyEvents.CAMPAIGN_AWARDED, {
+			campaignId: source.campaignId,
+			memberCount: members.length,
+			awarded,
+			skipped,
+			totalPoints
+		}, ctx, {
+			resource: "campaign",
+			resourceId: source.campaignId
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.CAMPAIGN_AWARDED, {
+			campaignId: source.campaignId,
+			memberCount: members.length,
+			awarded,
+			skipped,
+			totalPoints
+		});
+		return {
+			awarded,
+			skipped,
+			errors,
+			totalPoints
+		};
+	}
+	async adjustPoints(input, ctx) {
+		validatePoints(input.points);
+		if (input.points === 0) throw new ValidationError("Adjustment points cannot be zero");
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		if (input.idempotencyKey) {
+			const existing = await this.getByQuery({ idempotencyKey: input.idempotencyKey }, {
+				throwOnNotFound: false,
+				...tc
+			});
+			if (existing) return existing;
+		}
+		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
+		if (input.points < 0 && member.balance.current < Math.abs(input.points)) throw new InsufficientPointsError(member.balance.current, Math.abs(input.points));
+		const tx = await this.unitOfWork.withTransaction(async (session) => {
+			if (input.idempotencyKey) {
+				const dup = await this.getByQuery({ idempotencyKey: input.idempotencyKey }, {
+					throwOnNotFound: false,
+					...tc
+				});
+				if (dup) return dup;
+			}
+			const balanceUpdate = { current: input.points };
+			if (input.points > 0) balanceUpdate.lifetime = input.points;
+			const updatedMember = await this.memberRepo.updateBalance(input.memberId, balanceUpdate, {
+				session,
+				...tc
+			});
+			if (updatedMember.balance.current < 0) throw new InsufficientPointsError(updatedMember.balance.current - input.points, Math.abs(input.points));
+			const data = {
+				memberId: input.memberId,
+				programId: member.programId,
+				type: "adjust",
+				points: input.points,
+				balanceAfter: updatedMember.balance.current,
+				description: input.description,
+				referenceType: input.referenceType,
+				referenceId: input.referenceId,
+				metadata: {
+					reason: input.reason,
+					...input.metadata || {}
+				},
+				actorId: ctx.actorId
+			};
+			if (input.idempotencyKey) data.idempotencyKey = input.idempotencyKey;
+			return this.create(data, {
+				session,
+				...tc
+			});
+		});
+		const payload = {
+			memberId: member._id,
+			externalId: member.externalId,
+			points: input.points,
+			balanceAfter: tx.balanceAfter,
+			transactionId: tx._id,
+			description: input.description
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.POINTS_ADJUSTED, payload, ctx, {
+			resource: "pointTransaction",
+			resourceId: tx._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.POINTS_ADJUSTED, { ...payload });
+		return tx;
+	}
+	async processExpirations(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const now = /* @__PURE__ */ new Date();
+		const expiredTxs = await this.findAll({
+			expiresAt: { $lte: now },
+			expiredAt: { $exists: false }
+		}, {
+			sort: { createdAt: 1 },
+			limit: 100,
+			...tc
+		});
+		let totalExpired = 0;
+		let transactionCount = 0;
+		const affectedMemberIds = /* @__PURE__ */ new Set();
+		for (const tx of expiredTxs) {
+			await this.unitOfWork.withTransaction(async (session) => {
+				await this.create({
+					memberId: tx.memberId,
+					programId: tx.programId,
+					type: "expire",
+					points: -tx.points,
+					balanceAfter: 0,
+					description: `Points expired from transaction ${tx._id}`,
+					referenceType: "expiration",
+					referenceId: tx._id,
+					actorId: ctx.actorId
+				}, {
+					session,
+					...tc
+				});
+				await this.update(tx._id, { expiredAt: now }, {
+					session,
+					...tc
+				});
+				await this.memberRepo.updateBalance(tx.memberId, {
+					current: -tx.points,
+					expired: tx.points
+				}, {
+					session,
+					...tc
+				});
+			});
+			affectedMemberIds.add(tx.memberId);
+			totalExpired += tx.points;
+			transactionCount++;
+		}
+		if (totalExpired > 0) await this._dispatch(createEvent(LoyaltyEvents.POINTS_EXPIRED, {
+			membersAffected: affectedMemberIds.size,
+			pointsExpired: totalExpired,
+			transactionCount
+		}, ctx), ctx);
+		return {
+			membersAffected: affectedMemberIds.size,
+			pointsExpired: totalExpired,
+			transactionCount
+		};
+	}
+};
+/** E11000 across the raw driver + mongokit wrapper shapes. */
+function isDuplicateKey(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const e = err;
+	if (e.code === 11e3) return true;
+	if (e.status === 409) return true;
+	if (e.cause !== void 0) return isDuplicateKey(e.cause);
+	return false;
+}
+/**
+* Transient MongoDB WriteConflict — surfaces under concurrent webhook
+* replay when two transactions try to update the same member balance.
+* With an idempotency key present, the winning insert is the source of
+* truth; losers are short-circuited to its doc rather than leaking the
+* raw driver error.
+*/
+function isWriteConflict(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const e = err;
+	if (e.code === 112 || e.codeName === "WriteConflict") 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/repositories/redemption.repository.ts
+var RedemptionRepository = class extends Repository {
+	memberRepo;
+	txRepo;
+	events;
+	outbox;
+	notifications = null;
+	unitOfWork;
+	config;
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	/** Auto-inject tenant id from options into doc payload. See MemberRepository. */
+	async create(data, options) {
+		injectTenantIntoData(data, options, this.config.tenant);
+		return super.create(data, options);
+	}
+	async createMany(docs, options) {
+		const opts = options;
+		for (const doc of docs) injectTenantIntoData(doc, opts, this.config.tenant);
+		return super.createMany(docs, options);
+	}
+	/** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
+	async _dispatch(event, ctx) {
+		await dispatchLoyaltyEvent({
+			events: this.events,
+			outbox: this.outbox
+		}, event, ctx);
+	}
+	/**
+	* Atomic compare-and-set status transition.
+	* Returns null if the current status doesn't match `expectedStatus` (CAS mismatch).
+	*/
+	async atomicStatusTransition(id, expectedStatus, data, ctx) {
+		try {
+			return await this.update(id, data, {
+				lean: true,
+				query: { status: expectedStatus },
+				throwOnNotFound: false,
+				...ctx
+			});
+		} catch {
+			return null;
+		}
+	}
+	async validate(input, ctx) {
+		validatePositivePoints(input.pointsToRedeem, "pointsToRedeem");
+		validateOrderTotal(input.orderTotal);
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
+		const { minPoints, minOrderAmount, maxRedeemPercent } = this.config.redemption;
+		const { conversionRate } = this.config;
+		if (input.pointsToRedeem < minPoints) return {
+			valid: false,
+			error: `Minimum ${minPoints} points required`,
+			pointsToRedeem: 0,
+			discountAmount: 0,
+			maxAllowedPoints: 0
+		};
+		if (input.orderTotal < minOrderAmount) return {
+			valid: false,
+			error: `Minimum order amount of ${minOrderAmount} required`,
+			pointsToRedeem: 0,
+			discountAmount: 0,
+			maxAllowedPoints: 0
+		};
+		if (input.pointsToRedeem > member.balance.current) return {
+			valid: false,
+			error: `Insufficient points. Available: ${member.balance.current}`,
+			pointsToRedeem: 0,
+			discountAmount: 0,
+			maxAllowedPoints: member.balance.current
+		};
+		const maxDiscount = Math.floor(input.orderTotal * maxRedeemPercent / 100);
+		const requestedDiscount = Math.floor(input.pointsToRedeem / conversionRate);
+		const discountAmount = Math.min(requestedDiscount, maxDiscount);
+		const maxAllowedPoints = Math.floor(maxDiscount * conversionRate);
+		return {
+			valid: true,
+			pointsToRedeem: discountAmount < requestedDiscount ? Math.floor(discountAmount * conversionRate) : input.pointsToRedeem,
+			discountAmount,
+			maxAllowedPoints
+		};
+	}
+	async reserve(input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const validation = await this.validate({
+			memberId: input.memberId,
+			pointsToRedeem: input.pointsToRedeem,
+			orderTotal: input.orderTotal
+		}, ctx);
+		if (!validation.valid) throw new ValidationError(validation.error ?? "Redemption validation failed");
+		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
+		const expiresAt = input.expiresAt ?? new Date(Date.now() + this.config.redemption.reservationTtlMinutes * 60 * 1e3);
+		const redemption = await this.unitOfWork.withTransaction(async (session) => {
+			const updatedMember = await this.memberRepo.updateBalance(input.memberId, { current: -validation.pointsToRedeem }, {
+				session,
+				...tc
+			});
+			if (updatedMember.balance.current < 0) throw new ValidationError(`Insufficient points after concurrent reservation. Available: ${updatedMember.balance.current + validation.pointsToRedeem}`);
+			const data = {
+				memberId: input.memberId,
+				programId: member.programId,
+				pointsReserved: validation.pointsToRedeem,
+				pointsConfirmed: 0,
+				discountAmount: validation.discountAmount,
+				conversionRate: this.config.conversionRate,
+				status: "reserved",
+				ownerType: input.ownerType,
+				ownerId: input.ownerId,
+				expiresAt
+			};
+			return this.create(data, {
+				session,
+				...tc
+			});
+		});
+		const payload = {
+			memberId: member._id,
+			externalId: member.externalId,
+			redemptionId: redemption._id,
+			points: validation.pointsToRedeem,
+			discountAmount: validation.discountAmount,
+			ownerType: input.ownerType,
+			ownerId: input.ownerId
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.REDEMPTION_RESERVED, payload, ctx, {
+			resource: "redemption",
+			resourceId: redemption._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.REDEMPTION_RESERVED, { ...payload });
+		return redemption;
+	}
+	async confirm(redemptionId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const redemption = await this.getById(redemptionId, {
+			throwOnNotFound: false,
+			...tc
+		});
+		if (!redemption) throw new RedemptionNotFoundError(redemptionId);
+		if (redemption.expiresAt && redemption.expiresAt < /* @__PURE__ */ new Date()) throw new RedemptionExpiredError(redemptionId);
+		const updated = await this.unitOfWork.withTransaction(async (session) => {
+			if (!await this.atomicStatusTransition(redemptionId, "reserved", {
+				status: "confirmed",
+				pointsConfirmed: redemption.pointsReserved,
+				confirmedAt: /* @__PURE__ */ new Date()
+			}, {
+				session,
+				...tc
+			})) throw new ValidationError(`Redemption status must be 'reserved', got '${redemption.status}'`);
+			const member = await this.memberRepo.requireActiveMember(redemption.memberId, tc);
+			const tx = await this.txRepo.create({
+				memberId: redemption.memberId,
+				programId: member.programId,
+				type: "redeem",
+				points: -redemption.pointsReserved,
+				balanceAfter: member.balance.current,
+				description: `Redemption confirmed: ${redemptionId}`,
+				referenceType: redemption.ownerType,
+				referenceId: redemption.ownerId,
+				actorId: ctx.actorId
+			}, {
+				session,
+				...tc
+			});
+			await this.memberRepo.updateBalance(redemption.memberId, { redeemed: redemption.pointsReserved }, {
+				session,
+				...tc
+			});
+			const confirmed = await this.update(redemptionId, { transactionId: tx._id }, {
+				throwOnNotFound: true,
+				lean: true,
+				session,
+				...tc
+			});
+			if (!confirmed) throw new RedemptionNotFoundError(redemptionId);
+			return confirmed;
+		});
+		const member = await this.memberRepo.getById(updated.memberId, {
+			throwOnNotFound: false,
+			...tc
+		});
+		const payload = {
+			memberId: updated.memberId,
+			externalId: member?.externalId ?? "",
+			redemptionId: updated._id,
+			points: updated.pointsConfirmed,
+			discountAmount: updated.discountAmount,
+			ownerType: updated.ownerType,
+			ownerId: updated.ownerId
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.REDEMPTION_CONFIRMED, payload, ctx, {
+			resource: "redemption",
+			resourceId: updated._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.REDEMPTION_CONFIRMED, { ...payload });
+		return updated;
+	}
+	async release(redemptionId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const redemption = await this.getById(redemptionId, {
+			throwOnNotFound: false,
+			...tc
+		});
+		if (!redemption) throw new RedemptionNotFoundError(redemptionId);
+		const updated = await this.unitOfWork.withTransaction(async (session) => {
+			const transitioned = await this.atomicStatusTransition(redemptionId, "reserved", {
+				status: "released",
+				releasedAt: /* @__PURE__ */ new Date()
+			}, {
+				session,
+				...tc
+			});
+			if (!transitioned) throw new ValidationError(`Redemption status must be 'reserved', got '${redemption.status}'`);
+			await this.memberRepo.updateBalance(redemption.memberId, { current: redemption.pointsReserved }, {
+				session,
+				...tc
+			});
+			return transitioned;
+		});
+		const member = await this.memberRepo.getById(updated.memberId, {
+			throwOnNotFound: false,
+			...tc
+		});
+		const payload = {
+			memberId: updated.memberId,
+			externalId: member?.externalId ?? "",
+			redemptionId: updated._id,
+			points: updated.pointsReserved,
+			discountAmount: updated.discountAmount,
+			ownerType: updated.ownerType,
+			ownerId: updated.ownerId
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.REDEMPTION_RELEASED, payload, ctx, {
+			resource: "redemption",
+			resourceId: updated._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.REDEMPTION_RELEASED, { ...payload });
+		return updated;
+	}
+	/**
+	* Reverses a confirmed redemption. Credits points back to the member as
+	* a compensating `adjust` transaction, marks the redemption `reversed`,
+	* and emits `REDEMPTION_REVERSED`. Guarded by an atomic CAS on
+	* `status === 'confirmed'` so idempotent callers never double-credit.
+	*
+	* @param options.proportional - when true + the redemption has a
+	*   `remainingBalance` + `initialBalance` (voucher-backed), credits
+	*   back `(remainingBalance / initialBalance) × pointsConfirmed`.
+	*   When false (default), credits back the full `pointsConfirmed`.
+	*   When true but the redemption has no voucher metadata, falls back
+	*   to a full reversal and stamps `metadata.proportional_fallback`.
+	* @param options.reason - free-text audit note; persisted on the
+	*   redemption + the compensating point_transaction metadata.
+	*/
+	async reverseConfirmed(redemptionId, ctx, options) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const redemption = await this.getById(redemptionId, {
+			throwOnNotFound: false,
+			...tc
+		});
+		if (!redemption) throw new RedemptionNotFoundError(redemptionId);
+		if (redemption.status !== "confirmed") throw new ValidationError(`Redemption status must be 'confirmed', got '${redemption.status}'`);
+		const proportional = options?.proportional === true;
+		const originalPoints = redemption.pointsConfirmed;
+		let pointsToCredit = originalPoints;
+		let usedProportional = false;
+		let proportionalFallback = false;
+		if (proportional) {
+			const { initialBalance, remainingBalance } = redemption;
+			if (typeof initialBalance === "number" && initialBalance > 0 && typeof remainingBalance === "number" && remainingBalance >= 0) {
+				const ratio = Math.min(1, remainingBalance / initialBalance);
+				pointsToCredit = Math.floor(originalPoints * ratio);
+				usedProportional = true;
+			} else proportionalFallback = true;
+		}
+		const reversed = await this.unitOfWork.withTransaction(async (session) => {
+			const transitioned = await this.atomicStatusTransition(redemptionId, "confirmed", {
+				status: "reversed",
+				reversedAt: /* @__PURE__ */ new Date(),
+				...options?.reason ? { reversalReason: options.reason } : {}
+			}, {
+				session,
+				...tc
+			});
+			if (!transitioned) throw new ValidationError(`Redemption status must be 'confirmed', got '${redemption.status}'`);
+			let creditTxId = "";
+			if (pointsToCredit > 0) {
+				const member = await this.memberRepo.requireMember(redemption.memberId, tc);
+				const updatedMember = await this.memberRepo.updateBalance(redemption.memberId, {
+					current: pointsToCredit,
+					redeemed: -pointsToCredit
+				}, {
+					session,
+					...tc
+				});
+				const txData = {
+					memberId: redemption.memberId,
+					programId: member.programId,
+					type: "adjust",
+					points: pointsToCredit,
+					balanceAfter: updatedMember.balance.current,
+					description: `Redemption reversed: ${redemptionId}`,
+					referenceType: "redemption_reversal",
+					referenceId: redemptionId,
+					actorId: ctx.actorId,
+					metadata: {
+						reverses: redemptionId,
+						originalPoints,
+						proportional: usedProportional,
+						...proportionalFallback ? { proportional_fallback: true } : {},
+						...options?.reason ? { reason: options.reason } : {}
+					}
+				};
+				creditTxId = (await this.txRepo.create(txData, {
+					session,
+					...tc
+				}))._id;
+			}
+			const finalUpdate = {};
+			if (creditTxId) finalUpdate.reversalTransactionId = creditTxId;
+			if (Object.keys(finalUpdate).length > 0) {
+				const updated = await this.update(redemptionId, finalUpdate, {
+					throwOnNotFound: true,
+					lean: true,
+					session,
+					...tc
+				});
+				if (!updated) throw new RedemptionNotFoundError(redemptionId);
+				return updated;
+			}
+			return transitioned;
+		});
+		const member = await this.memberRepo.getById(reversed.memberId, {
+			throwOnNotFound: false,
+			...tc
+		});
+		const payload = {
+			memberId: reversed.memberId,
+			externalId: member?.externalId ?? "",
+			redemptionId: reversed._id,
+			pointsCredited: pointsToCredit,
+			originalPoints,
+			proportional: usedProportional,
+			transactionId: reversed.reversalTransactionId ?? ""
+		};
+		if (options?.reason) payload.reason = options.reason;
+		await this._dispatch(createEvent(LoyaltyEvents.REDEMPTION_REVERSED, payload, ctx, {
+			resource: "redemption",
+			resourceId: reversed._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.REDEMPTION_REVERSED, { ...payload });
+		return reversed;
+	}
+	async cleanupExpired(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const now = /* @__PURE__ */ new Date();
+		const expired = await this.findAll({
+			status: "reserved",
+			expiresAt: { $lte: now }
+		}, tc);
+		let released = 0;
+		for (const redemption of expired) {
+			await this.release(redemption._id, ctx);
+			released++;
+		}
+		return released;
+	}
+};
+//#endregion
+//#region src/repositories/referral.repository.ts
+var ReferralRepository = class extends Repository {
+	memberRepo;
+	txRepo;
+	events;
+	outbox;
+	notifications = null;
+	config;
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	/** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
+	async _dispatch(event, ctx) {
+		await dispatchLoyaltyEvent({
+			events: this.events,
+			outbox: this.outbox
+		}, event, ctx);
+	}
+	/** Auto-inject tenant id from options into doc payload. See MemberRepository. */
+	async create(data, options) {
+		injectTenantIntoData(data, options, this.config.tenant);
+		return super.create(data, options);
+	}
+	async createMany(docs, options) {
+		const opts = options;
+		for (const doc of docs) injectTenantIntoData(doc, opts, this.config.tenant);
+		return super.createMany(docs, options);
+	}
+	/**
+	* Atomic compare-and-set status transition.
+	* Returns null if the current status doesn't match `expectedStatus`.
+	*/
+	async atomicStatusTransition(id, expectedStatus, data, ctx) {
+		try {
+			return await this.update(id, data, {
+				lean: true,
+				query: { status: expectedStatus },
+				throwOnNotFound: false,
+				...ctx
+			});
+		} catch {
+			return null;
+		}
+	}
+	async generateCode(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const member = await this.memberRepo.requireMember(memberId, tc);
+		if (member.referralCode) return member.referralCode;
+		const code = generateReferralCode(this.config.referral.codeLength);
+		await this.memberRepo.update(memberId, { referralCode: code }, {
+			lean: true,
+			...tc
+		});
+		return code;
+	}
+	async lookupByCode(code, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		return this.memberRepo.getByQuery({ referralCode: code }, {
+			throwOnNotFound: false,
+			...tc
+		});
+	}
+	async recordReferral(input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const referrer = await this.memberRepo.getByQuery({ referralCode: input.referralCode }, {
+			throwOnNotFound: false,
+			...tc
+		});
+		if (!referrer) throw new MemberNotFoundError(`referral code: ${input.referralCode}`);
+		const referee = await this.memberRepo.getByQuery({
+			externalId: input.refereeExternalId,
+			externalType: input.refereeExternalType
+		}, {
+			throwOnNotFound: false,
+			...tc
+		});
+		if (!referee) throw new MemberNotFoundError(`referee: ${input.refereeExternalId}`);
+		if (String(referrer._id) === String(referee._id)) throw new SelfReferralError();
+		if (await this.getByQuery({ refereeId: referee._id }, {
+			throwOnNotFound: false,
+			...tc
+		})) throw new DuplicateReferralError(referee._id);
+		const reverseReferral = await this.getByQuery({ refereeId: referrer._id }, {
+			throwOnNotFound: false,
+			...tc
+		});
+		if (reverseReferral && String(reverseReferral.referrerId) === String(referee._id)) throw new CircularReferralError();
+		const periodStart = /* @__PURE__ */ new Date();
+		periodStart.setDate(periodStart.getDate() - this.config.referral.periodDays);
+		if (await this.count({
+			referrerId: referrer._id,
+			createdAt: { $gte: periodStart }
+		}, tc) >= this.config.referral.maxPerPeriod) throw new ReferralLimitExceededError(this.config.referral.maxPerPeriod, this.config.referral.periodDays);
+		const autoApprove = !this.config.referral.requireApproval;
+		const status = autoApprove ? "approved" : "pending";
+		const data = {
+			programId: referrer.programId,
+			referrerId: referrer._id,
+			refereeId: referee._id,
+			referralCode: input.referralCode,
+			status,
+			referrerRewardPoints: this.config.referral.referrerRewardPoints,
+			refereeRewardPoints: this.config.referral.refereeRewardPoints
+		};
+		if (autoApprove) data.approvedAt = /* @__PURE__ */ new Date();
+		const referral = await this.create(data, tc);
+		if (!referee.referredBy) await this.memberRepo.update(referee._id, { referredBy: referrer._id }, {
+			lean: true,
+			...tc
+		});
+		const payload = {
+			referralId: referral._id,
+			referrerId: referrer._id,
+			refereeId: referee._id,
+			referralCode: input.referralCode,
+			status: referral.status
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.REFERRAL_RECORDED, payload, ctx, {
+			resource: "referral",
+			resourceId: referral._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.REFERRAL_RECORDED, { ...payload });
+		if (autoApprove) await this.rewardBothSides(referral, referrer, referee, ctx);
+		return referral;
+	}
+	async approve(referralId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const referral = await this.requireReferral(referralId, tc);
+		const updated = await this.atomicStatusTransition(referralId, "pending", {
+			status: "approved",
+			approvedAt: /* @__PURE__ */ new Date()
+		}, tc);
+		if (!updated) throw new ValidationError(`Referral status must be 'pending', got '${referral.status}'`);
+		const referrer = await this.memberRepo.requireMember(referral.referrerId, tc);
+		const referee = await this.memberRepo.requireMember(referral.refereeId, tc);
+		const payload = {
+			referralId: updated._id,
+			referrerId: referrer._id,
+			refereeId: referee._id,
+			referralCode: updated.referralCode,
+			status: updated.status
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.REFERRAL_APPROVED, payload, ctx, {
+			resource: "referral",
+			resourceId: updated._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.REFERRAL_APPROVED, { ...payload });
+		await this.rewardBothSides(updated, referrer, referee, ctx);
+		return updated;
+	}
+	async reject(referralId, reason, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const referral = await this.requireReferral(referralId, tc);
+		const updated = await this.atomicStatusTransition(referralId, "pending", {
+			status: "rejected",
+			rejectedAt: /* @__PURE__ */ new Date(),
+			rejectionReason: reason
+		}, tc);
+		if (!updated) throw new ValidationError(`Referral status must be 'pending', got '${referral.status}'`);
+		const payload = {
+			referralId: updated._id,
+			referrerId: referral.referrerId,
+			refereeId: referral.refereeId,
+			referralCode: updated.referralCode,
+			status: updated.status
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.REFERRAL_REJECTED, payload, ctx, {
+			resource: "referral",
+			resourceId: updated._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.REFERRAL_REJECTED, { ...payload });
+		return updated;
+	}
+	async cleanupExpired(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const now = /* @__PURE__ */ new Date();
+		const expired = await this.findAll({
+			status: "pending",
+			expiresAt: { $lte: now }
+		}, tc);
+		let count = 0;
+		for (const referral of expired) {
+			await this.update(referral._id, { status: "expired" }, tc);
+			count++;
+		}
+		return count;
+	}
+	async rewardBothSides(referral, referrer, referee, ctx) {
+		const { referrerRewardPoints, refereeRewardPoints, maxDepth, tierRates } = this.config.referral;
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		if (referrerRewardPoints > 0) {
+			const referrerTx = await this.txRepo.earnPoints({
+				memberId: referrer._id,
+				points: referrerRewardPoints,
+				description: `Referral reward: referred ${referee.externalId}`,
+				referenceType: "referral",
+				referenceId: referral._id,
+				idempotencyKey: `referral:${referral._id}:referrer`
+			}, ctx);
+			await this.update(referral._id, { referrerTransactionId: referrerTx._id }, tc);
+		}
+		if (refereeRewardPoints > 0) {
+			const refereeTx = await this.txRepo.earnPoints({
+				memberId: referee._id,
+				points: refereeRewardPoints,
+				description: `Referral welcome bonus from ${referrer.externalId}`,
+				referenceType: "referral",
+				referenceId: referral._id,
+				idempotencyKey: `referral:${referral._id}:referee`
+			}, ctx);
+			await this.update(referral._id, { refereeTransactionId: refereeTx._id }, tc);
+		}
+		const rewardPayload = {
+			referralId: referral._id,
+			referrerId: referrer._id,
+			refereeId: referee._id,
+			referralCode: referral.referralCode,
+			status: "approved",
+			referrerRewardPoints,
+			refereeRewardPoints
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.REFERRAL_REWARDED, rewardPayload, ctx, {
+			resource: "referral",
+			resourceId: referral._id
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.REFERRAL_REWARDED, { ...rewardPayload });
+		if (maxDepth > 1 && referrerRewardPoints > 0) {
+			const awards = [];
+			let currentId = referrer.referredBy;
+			const visited = new Set([referrer._id, referee._id]);
+			for (let depth = 2; depth <= maxDepth && currentId; depth++) {
+				if (visited.has(currentId)) break;
+				visited.add(currentId);
+				const ancestor = await this.memberRepo.getById(currentId, {
+					throwOnNotFound: false,
+					...tc
+				});
+				if (!ancestor || ancestor.status !== "active") break;
+				const ratePct = tierRates[depth - 1];
+				if (typeof ratePct === "number" && ratePct > 0) {
+					const points = Math.floor(referrerRewardPoints * (ratePct / 100));
+					if (points > 0) {
+						const tx = await this.txRepo.earnPoints({
+							memberId: ancestor._id,
+							points,
+							description: `Multi-tier referral reward (depth ${depth})`,
+							referenceType: "referral",
+							referenceId: referral._id,
+							idempotencyKey: `referral:${referral._id}:ancestor:${depth}`,
+							metadata: {
+								depth,
+								descendantId: referee._id
+							}
+						}, ctx);
+						awards.push({
+							memberId: ancestor._id,
+							depth,
+							points,
+							transactionId: tx._id
+						});
+					}
+				}
+				currentId = ancestor.referredBy;
+			}
+			if (awards.length > 0) {
+				await this._dispatch(createEvent(LoyaltyEvents.MULTI_TIER_REFERRAL_AWARDED, {
+					referralId: referral._id,
+					refereeId: referee._id,
+					awards
+				}, ctx, {
+					resource: "referral",
+					resourceId: referral._id
+				}), ctx);
+				this.notifications?.notify(LoyaltyEvents.MULTI_TIER_REFERRAL_AWARDED, {
+					referralId: referral._id,
+					refereeId: referee._id,
+					awards
+				});
+			}
+		}
+	}
+	async requireReferral(referralId, tc) {
+		const referral = await this.getById(referralId, {
+			throwOnNotFound: false,
+			...tc
+		});
+		if (!referral) throw new ReferralNotFoundError(referralId);
+		return referral;
+	}
+};
+//#endregion
+//#region src/repositories/tier-definition.repository.ts
+var TierDefinitionRepository = class extends Repository {
+	memberRepo;
+	events;
+	outbox;
+	notifications = null;
+	config;
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	/** Auto-inject tenant id from options into doc payload. See MemberRepository. */
+	async create(data, options) {
+		injectTenantIntoData(data, options, this.config.tenant);
+		return super.create(data, options);
+	}
+	async createMany(docs, options) {
+		const opts = options;
+		for (const doc of docs) injectTenantIntoData(doc, opts, this.config.tenant);
+		return super.createMany(docs, options);
+	}
+	/** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
+	async _dispatch(event, ctx) {
+		await dispatchLoyaltyEvent({
+			events: this.events,
+			outbox: this.outbox
+		}, event, ctx);
+	}
+	async evaluateMember(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const member = await this.memberRepo.requireMember(memberId, tc);
+		const sortedTiers = [...await this.findAll({ programId: member.programId }, {
+			sort: { rank: 1 },
+			...tc
+		})].sort((a, b) => b.rank - a.rank);
+		const ttl = member.tierOverrideExpiresAt;
+		if (member.tierOverride !== null && member.tierOverride !== void 0 && !(ttl !== void 0 && ttl !== null && ttl.getTime() <= Date.now())) return {
+			memberId,
+			previousTier: member.tier,
+			newTier: member.tier,
+			action: "unchanged"
+		};
+		const qualifiedTier = sortedTiers.find((t) => t.qualificationCriteria.minLifetimePoints !== void 0 && member.balance.lifetime >= t.qualificationCriteria.minLifetimePoints) ?? null;
+		const currentTierDef = member.tier ? sortedTiers.find((t) => t.name === member.tier) ?? null : null;
+		const currentRank = currentTierDef?.rank ?? -1;
+		const newRank = qualifiedTier?.rank ?? -1;
+		if (newRank > currentRank && qualifiedTier) return this.applyUpgrade(memberId, member, qualifiedTier.name, tc, ctx);
+		if (newRank < currentRank && currentTierDef) return this.applyDowngrade(memberId, member, currentTierDef, qualifiedTier?.name ?? null, tc, ctx);
+		return {
+			memberId,
+			previousTier: member.tier,
+			newTier: member.tier,
+			action: "unchanged"
+		};
+	}
+	async evaluateAll(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const members = await this.memberRepo.findAll({ status: "active" }, tc);
+		let upgraded = 0;
+		let downgraded = 0;
+		let unchanged = 0;
+		for (const member of members) switch ((await this.evaluateMember(member._id, ctx)).action) {
+			case "upgraded":
+				upgraded++;
+				break;
+			case "downgraded":
+				downgraded++;
+				break;
+			default:
+				unchanged++;
+				break;
+		}
+		return {
+			upgraded,
+			downgraded,
+			unchanged
+		};
+	}
+	async setOverride(memberId, tierName, reason, ctx, options) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const member = await this.memberRepo.requireMember(memberId, tc);
+		if (!(await this.findAll({ programId: member.programId }, {
+			sort: { rank: 1 },
+			...tc
+		})).some((t) => t.name === tierName)) throw new TierNotFoundError(tierName);
+		const update = {
+			tierOverride: tierName,
+			tierOverrideReason: reason,
+			tierOverrideExpiresAt: options?.expiresAt ?? null
+		};
+		const updated = await this.memberRepo.update(memberId, update, {
+			throwOnNotFound: true,
+			lean: true,
+			...tc
+		});
+		if (!updated) throw new MemberNotFoundError(memberId);
+		return updated;
+	}
+	async clearOverride(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const member = await this.memberRepo.requireMember(memberId, tc);
+		const previousOverride = member.tierOverride;
+		const previousReason = member.tierOverrideReason;
+		await this.memberRepo.update(memberId, {
+			tierOverride: null,
+			tierOverrideReason: null,
+			tierOverrideExpiresAt: null
+		}, {
+			lean: true,
+			...tc
+		});
+		if (previousOverride) {
+			const payload = {
+				memberId,
+				externalId: member.externalId,
+				tier: previousOverride
+			};
+			if (previousReason !== void 0) payload.reason = previousReason;
+			await this._dispatch(createEvent(LoyaltyEvents.TIER_OVERRIDE_CLEARED, payload, ctx, {
+				resource: "member",
+				resourceId: memberId
+			}), ctx);
+			this.notifications?.notify(LoyaltyEvents.TIER_OVERRIDE_CLEARED, { ...payload });
+		}
+		return this.evaluateMember(memberId, ctx);
+	}
+	/**
+	* Sweeps members whose `tierOverrideExpiresAt` is past `now` and clears
+	* the override. Emits `TIER_OVERRIDE_EXPIRED` per member — distinct from
+	* the explicit `TIER_OVERRIDE_CLEARED` event — so audit logs can tell
+	* admin-initiated clears from TTL sweeps.
+	*
+	* Hosts call this on a cron schedule (e.g. hourly). Returns the number
+	* of overrides cleared. No-op when nothing matches.
+	*/
+	async sweepExpiredOverrides(ctx, now = /* @__PURE__ */ new Date()) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const expired = await this.memberRepo.findAll({
+			tierOverride: { $ne: null },
+			tierOverrideExpiresAt: { $lte: now }
+		}, tc);
+		let cleared = 0;
+		for (const member of expired) {
+			const previousOverride = member.tierOverride;
+			if (!previousOverride) continue;
+			await this.memberRepo.update(member._id, {
+				tierOverride: null,
+				tierOverrideReason: null,
+				tierOverrideExpiresAt: null
+			}, {
+				lean: true,
+				...tc
+			});
+			const payload = {
+				memberId: member._id,
+				externalId: member.externalId,
+				tier: previousOverride,
+				expiredAt: now.toISOString()
+			};
+			if (member.tierOverrideReason !== void 0) payload.reason = member.tierOverrideReason;
+			await this._dispatch(createEvent(LoyaltyEvents.TIER_OVERRIDE_EXPIRED, payload, ctx, {
+				resource: "member",
+				resourceId: member._id
+			}), ctx);
+			this.notifications?.notify(LoyaltyEvents.TIER_OVERRIDE_EXPIRED, { ...payload });
+			await this.evaluateMember(member._id, ctx);
+			cleared++;
+		}
+		return { cleared };
+	}
+	async applyUpgrade(memberId, member, newTierName, tc, ctx) {
+		await this.memberRepo.update(memberId, {
+			tier: newTierName,
+			tierQualifiedAt: /* @__PURE__ */ new Date(),
+			tierExpiresAt: null
+		}, {
+			lean: true,
+			...tc
+		});
+		const payload = {
+			memberId,
+			externalId: member.externalId,
+			previousTier: member.tier,
+			newTier: newTierName,
+			lifetimePoints: member.balance.lifetime
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.TIER_UPGRADED, payload, ctx, {
+			resource: "member",
+			resourceId: memberId
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.TIER_UPGRADED, { ...payload });
+		return {
+			memberId,
+			previousTier: member.tier,
+			newTier: newTierName,
+			action: "upgraded"
+		};
+	}
+	async applyDowngrade(memberId, member, currentTierDef, qualifiedTierName, tc, ctx) {
+		const { downgrade } = currentTierDef;
+		if (!downgrade.enabled) return {
+			memberId,
+			previousTier: member.tier,
+			newTier: member.tier,
+			action: "unchanged"
+		};
+		if (downgrade.gracePeriodDays > 0 && !member.tierExpiresAt) {
+			const graceExpiresAt = /* @__PURE__ */ new Date();
+			graceExpiresAt.setDate(graceExpiresAt.getDate() + downgrade.gracePeriodDays);
+			await this.memberRepo.update(memberId, { tierExpiresAt: graceExpiresAt }, {
+				lean: true,
+				...tc
+			});
+			const payload = {
+				memberId,
+				externalId: member.externalId,
+				previousTier: member.tier,
+				newTier: member.tier,
+				lifetimePoints: member.balance.lifetime
+			};
+			await this._dispatch(createEvent(LoyaltyEvents.TIER_GRACE_STARTED, payload, ctx, {
+				resource: "member",
+				resourceId: memberId
+			}), ctx);
+			this.notifications?.notify(LoyaltyEvents.TIER_GRACE_STARTED, { ...payload });
+			return {
+				memberId,
+				previousTier: member.tier,
+				newTier: member.tier,
+				action: "grace_period",
+				graceExpiresAt
+			};
+		}
+		if (!(downgrade.gracePeriodDays === 0 || member.tierExpiresAt && member.tierExpiresAt <= /* @__PURE__ */ new Date())) return {
+			memberId,
+			previousTier: member.tier,
+			newTier: member.tier,
+			action: "unchanged"
+		};
+		await this.memberRepo.update(memberId, {
+			tier: qualifiedTierName,
+			tierQualifiedAt: qualifiedTierName ? /* @__PURE__ */ new Date() : null,
+			tierExpiresAt: null
+		}, {
+			lean: true,
+			...tc
+		});
+		const payload = {
+			memberId,
+			externalId: member.externalId,
+			previousTier: member.tier,
+			newTier: qualifiedTierName,
+			lifetimePoints: member.balance.lifetime
+		};
+		await this._dispatch(createEvent(LoyaltyEvents.TIER_DOWNGRADED, payload, ctx, {
+			resource: "member",
+			resourceId: memberId
+		}), ctx);
+		this.notifications?.notify(LoyaltyEvents.TIER_DOWNGRADED, { ...payload });
+		return {
+			memberId,
+			previousTier: member.tier,
+			newTier: qualifiedTierName,
+			action: "downgraded"
+		};
+	}
+};
+//#endregion
+//#region src/repositories/index.ts
+function asPlugins(p) {
+	return p ?? [];
+}
+function createRepositories(input) {
+	const { models, plugins, tenant, config, events, outbox, notifications, unitOfWork } = input;
+	const tenantPlugins = tenant?.enabled ? [multiTenantPlugin({
+		tenantField: tenant.tenantField,
+		contextKey: tenant.contextKey,
+		fieldType: tenant.fieldType
+	})] : [];
+	const withTenant = (userPlugins) => [...tenantPlugins, ...asPlugins(userPlugins)];
+	const member = new MemberRepository(models.Member, withTenant(plugins?.member));
+	const pointTransaction = new PointTransactionRepository(models.PointTransaction, withTenant(plugins?.pointTransaction));
+	const earningRule = new EarningRuleRepository(models.EarningRule, withTenant(plugins?.earningRule));
+	const tierDefinition = new TierDefinitionRepository(models.TierDefinition, withTenant(plugins?.tierDefinition));
+	const redemption = new RedemptionRepository(models.Redemption, withTenant(plugins?.redemption));
+	const referral = new ReferralRepository(models.Referral, withTenant(plugins?.referral));
+	member.events = events;
+	member.outbox = outbox;
+	member.notifications = notifications;
+	member.config = config;
+	pointTransaction.memberRepo = member;
+	pointTransaction.events = events;
+	pointTransaction.outbox = outbox;
+	pointTransaction.notifications = notifications;
+	pointTransaction.unitOfWork = unitOfWork;
+	pointTransaction.config = config;
+	earningRule.memberRepo = member;
+	earningRule.txRepo = pointTransaction;
+	earningRule.config = config;
+	tierDefinition.memberRepo = member;
+	tierDefinition.events = events;
+	tierDefinition.outbox = outbox;
+	tierDefinition.notifications = notifications;
+	tierDefinition.config = config;
+	redemption.memberRepo = member;
+	redemption.txRepo = pointTransaction;
+	redemption.events = events;
+	redemption.outbox = outbox;
+	redemption.notifications = notifications;
+	redemption.unitOfWork = unitOfWork;
+	redemption.config = config;
+	referral.memberRepo = member;
+	referral.txRepo = pointTransaction;
+	referral.events = events;
+	referral.outbox = outbox;
+	referral.notifications = notifications;
+	referral.config = config;
+	return {
+		member,
+		pointTransaction,
+		earningRule,
+		tierDefinition,
+		redemption,
+		referral
+	};
+}
+//#endregion
+export { PointTransactionRepository as a, ValidationError as c, RedemptionRepository as i, TierDefinitionRepository as n, MemberRepository as o, ReferralRepository as r, EarningRuleRepository as s, createRepositories as t };