@classytic/loyalty 0.1.0

package/dist/services-CoTqC4E6.mjs

@@ -0,0 +1,1098 @@
+import { a as MemberInactiveError, c as RedemptionNotFoundError, d as RuleNotFoundError, f as SelfReferralError, h as ValidationError, i as MemberAlreadyEnrolledError, l as ReferralLimitExceededError, m as TierNotFoundError, n as DuplicateReferralError, o as MemberNotFoundError, p as TenantIsolationError, r as InsufficientPointsError, s as RedemptionExpiredError, t as CircularReferralError, u as ReferralNotFoundError } from "./domain-errors-D7q-2LYD.mjs";
+import { t as LoyaltyEvents } from "./event-types-xQBtYBbX.mjs";
+import { randomBytes } from "node:crypto";
+//#region src/utils/tenant-guard.ts
+function assertTenantContext(ctx, tenant) {
+	if (!tenant.enabled) return;
+	if (!ctx[tenant.contextKey]) throw new TenantIsolationError();
+}
+function getTenantValue(ctx, tenant) {
+	if (!tenant.enabled) return void 0;
+	return ctx[tenant.contextKey];
+}
+//#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/services/member-guard.ts
+/** Fetches a member by ID (tenant-scoped) or throws MemberNotFoundError. */
+async function requireMember(memberPort, memberId, tenantId) {
+	const member = await memberPort.getById(memberId, tenantId);
+	if (!member) throw new MemberNotFoundError(memberId);
+	return member;
+}
+/** Fetches an active member (tenant-scoped) or throws MemberNotFoundError / MemberInactiveError. */
+async function requireActiveMember(memberPort, memberId, tenantId) {
+	const member = await requireMember(memberPort, memberId, tenantId);
+	if (member.status !== "active") throw new MemberInactiveError(memberId);
+	return member;
+}
+//#endregion
+//#region src/services/earning.service.ts
+var EarningService = class {
+	constructor(rulePort, ledger, memberPort, config) {
+		this.rulePort = rulePort;
+		this.ledger = ledger;
+		this.memberPort = memberPort;
+		this.config = config;
+	}
+	async evaluateOrder(input, ctx) {
+		validateOrderTotal(input.orderTotal);
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const member = await requireActiveMember(this.memberPort, input.memberId, tenantId);
+		const orderRules = (await this.rulePort.findActive(tenantId, member.programId)).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.ledger.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 member = await requireActiveMember(this.memberPort, input.memberId, tenantId);
+		const actionRules = (await this.rulePort.findActive(tenantId, member.programId)).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.ledger.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
+		};
+	}
+	async createRule(input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const data = {
+			...input,
+			programId: input.programId ?? this.config.programId
+		};
+		if (tenantId) data[this.config.tenant.field] = tenantId;
+		return this.rulePort.create(data);
+	}
+	async updateRule(ruleId, input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		if (!await this.rulePort.getById(ruleId, tenantId)) throw new RuleNotFoundError(ruleId);
+		return this.rulePort.update(ruleId, { ...input }, tenantId);
+	}
+	async deactivateRule(ruleId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		if (!await this.rulePort.getById(ruleId, tenantId)) throw new RuleNotFoundError(ruleId);
+		return this.rulePort.update(ruleId, { status: "paused" }, tenantId);
+	}
+	async listRules(query, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const filter = {};
+		if (tenantId) filter[this.config.tenant.field] = tenantId;
+		const result = await this.rulePort.paginate(filter, {
+			page: query.page ?? 1,
+			limit: query.limit ?? 20,
+			sort: query.sort ?? { priority: 1 }
+		});
+		return {
+			docs: result.docs,
+			total: result.total,
+			page: result.page,
+			pages: result.pages,
+			hasNext: result.page < result.pages,
+			hasPrev: result.page > 1
+		};
+	}
+	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/services/ledger.service.ts
+var LedgerService = class {
+	constructor(txPort, memberPort, events, notifications, unitOfWork, config) {
+		this.txPort = txPort;
+		this.memberPort = memberPort;
+		this.events = events;
+		this.notifications = notifications;
+		this.unitOfWork = unitOfWork;
+		this.config = config;
+	}
+	async earnPoints(input, ctx) {
+		validatePositivePoints(input.points);
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		if (input.idempotencyKey) {
+			const existing = await this.txPort.getByIdempotencyKey(input.idempotencyKey, tenantId);
+			if (existing) return existing;
+		}
+		const member = await requireActiveMember(this.memberPort, input.memberId, tenantId);
+		try {
+			const tx = await this.unitOfWork.withTransaction(async (session) => {
+				if (input.idempotencyKey) {
+					const dup = await this.txPort.getByIdempotencyKey(input.idempotencyKey, tenantId);
+					if (dup) return dup;
+				}
+				const updatedMember = await this.memberPort.updateBalance(input.memberId, {
+					current: input.points,
+					lifetime: input.points
+				}, tenantId, session);
+				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;
+				if (tenantId) data[this.config.tenant.field] = tenantId;
+				return this.txPort.create(data, session);
+			});
+			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
+			};
+			this.events.emit(LoyaltyEvents.POINTS_EARNED, payload);
+			this.notifications?.notify(LoyaltyEvents.POINTS_EARNED, { ...payload });
+			return tx;
+		} catch (err) {
+			if (err?.code === 11e3 && input.idempotencyKey) {
+				const existing = await this.txPort.getByIdempotencyKey(input.idempotencyKey, tenantId);
+				if (existing) return existing;
+			}
+			throw err;
+		}
+	}
+	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);
+		if (input.idempotencyKey) {
+			const existing = await this.txPort.getByIdempotencyKey(input.idempotencyKey, tenantId);
+			if (existing) return existing;
+		}
+		const member = await requireActiveMember(this.memberPort, input.memberId, tenantId);
+		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.txPort.getByIdempotencyKey(input.idempotencyKey, tenantId);
+				if (dup) return dup;
+			}
+			const balanceUpdate = { current: input.points };
+			if (input.points > 0) balanceUpdate.lifetime = input.points;
+			const updatedMember = await this.memberPort.updateBalance(input.memberId, balanceUpdate, tenantId, session);
+			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;
+			if (tenantId) data[this.config.tenant.field] = tenantId;
+			return this.txPort.create(data, session);
+		});
+		const payload = {
+			memberId: member._id,
+			externalId: member.externalId,
+			points: input.points,
+			balanceAfter: tx.balanceAfter,
+			transactionId: tx._id,
+			description: input.description
+		};
+		this.events.emit(LoyaltyEvents.POINTS_ADJUSTED, payload);
+		this.notifications?.notify(LoyaltyEvents.POINTS_ADJUSTED, { ...payload });
+		return tx;
+	}
+	async getHistory(memberId, query, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		await requireActiveMember(this.memberPort, memberId, tenantId);
+		const filter = { memberId };
+		if (tenantId) filter[this.config.tenant.field] = tenantId;
+		const result = await this.txPort.paginate(filter, {
+			page: query.page ?? 1,
+			limit: query.limit ?? 20,
+			sort: query.sort ?? { createdAt: -1 }
+		});
+		return {
+			docs: result.docs,
+			total: result.total,
+			page: result.page,
+			pages: result.pages,
+			hasNext: result.page < result.pages,
+			hasPrev: result.page > 1
+		};
+	}
+	async getBalance(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		return (await requireActiveMember(this.memberPort, memberId, tenantId)).balance.current;
+	}
+	async processExpirations(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const now = /* @__PURE__ */ new Date();
+		const expiredTxs = await this.txPort.findExpired(now, tenantId);
+		let pointsExpired = 0;
+		let transactionCount = 0;
+		const affectedMemberIds = /* @__PURE__ */ new Set();
+		for (const tx of expiredTxs) {
+			await this.unitOfWork.withTransaction(async (session) => {
+				await this.txPort.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,
+					...tenantId ? { [this.config.tenant.field]: tenantId } : {}
+				}, session);
+				await this.txPort.update(tx._id, { expiredAt: now }, session);
+				await this.memberPort.updateBalance(tx.memberId, {
+					current: -tx.points,
+					expired: tx.points
+				}, tenantId, session);
+			});
+			affectedMemberIds.add(tx.memberId);
+			pointsExpired += tx.points;
+			transactionCount++;
+		}
+		if (pointsExpired > 0) this.events.emit(LoyaltyEvents.POINTS_EXPIRED, {
+			membersAffected: affectedMemberIds.size,
+			pointsExpired,
+			transactionCount
+		});
+		return {
+			membersAffected: affectedMemberIds.size,
+			pointsExpired,
+			transactionCount
+		};
+	}
+};
+//#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/services/member.service.ts
+var MemberService = class {
+	constructor(memberPort, events, notifications, unitOfWork, config) {
+		this.memberPort = memberPort;
+		this.events = events;
+		this.notifications = notifications;
+		this.unitOfWork = unitOfWork;
+		this.config = config;
+	}
+	async enroll(input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		if (await this.memberPort.getByExternalId(input.externalId, input.externalType, tenantId)) 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
+		};
+		if (tenantId) data[this.config.tenant.field] = tenantId;
+		const member = await this.memberPort.create(data);
+		const payload = {
+			memberId: member._id,
+			externalId: member.externalId,
+			externalType: member.externalType,
+			status: member.status
+		};
+		this.events.emit(LoyaltyEvents.MEMBER_ENROLLED, payload);
+		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);
+		await requireMember(this.memberPort, memberId, tenantId);
+		const updated = await this.memberPort.update(memberId, {
+			status: "inactive",
+			deactivatedAt: /* @__PURE__ */ new Date()
+		}, tenantId);
+		const payload = {
+			memberId: updated._id,
+			externalId: updated.externalId,
+			externalType: updated.externalType,
+			status: updated.status
+		};
+		this.events.emit(LoyaltyEvents.MEMBER_DEACTIVATED, payload);
+		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);
+		await requireMember(this.memberPort, memberId, tenantId);
+		const updated = await this.memberPort.update(memberId, {
+			status: "active",
+			deactivatedAt: null
+		}, tenantId);
+		const payload = {
+			memberId: updated._id,
+			externalId: updated.externalId,
+			externalType: updated.externalType,
+			status: updated.status
+		};
+		this.events.emit(LoyaltyEvents.MEMBER_REACTIVATED, payload);
+		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 member = await requireMember(this.memberPort, memberId, tenantId);
+		const updated = await this.memberPort.update(memberId, {
+			status: "suspended",
+			metadata: {
+				...member.metadata,
+				suspendReason: reason
+			}
+		}, tenantId);
+		const payload = {
+			memberId: updated._id,
+			externalId: updated.externalId,
+			externalType: updated.externalType,
+			status: updated.status
+		};
+		this.events.emit(LoyaltyEvents.MEMBER_SUSPENDED, payload);
+		this.notifications?.notify(LoyaltyEvents.MEMBER_SUSPENDED, { ...payload });
+		return updated;
+	}
+	async getById(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		return requireMember(this.memberPort, memberId, tenantId);
+	}
+	async getByExternalId(externalId, externalType, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		return this.memberPort.getByExternalId(externalId, externalType, tenantId);
+	}
+	async getByCardId(cardId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		return this.memberPort.getByCardId(cardId, tenantId);
+	}
+	async getBalance(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const member = await requireMember(this.memberPort, memberId, tenantId);
+		return {
+			...member.balance,
+			tier: member.tier,
+			tierOverride: member.tierOverride
+		};
+	}
+};
+//#endregion
+//#region src/services/redemption.service.ts
+var RedemptionService = class {
+	constructor(redemptionPort, memberPort, txPort, events, notifications, unitOfWork, config) {
+		this.redemptionPort = redemptionPort;
+		this.memberPort = memberPort;
+		this.txPort = txPort;
+		this.events = events;
+		this.notifications = notifications;
+		this.unitOfWork = unitOfWork;
+		this.config = config;
+	}
+	async validate(input, ctx) {
+		validatePositivePoints(input.pointsToRedeem, "pointsToRedeem");
+		validateOrderTotal(input.orderTotal);
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const member = await requireActiveMember(this.memberPort, input.memberId, tenantId);
+		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 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 requireActiveMember(this.memberPort, input.memberId, tenantId);
+		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.memberPort.updateBalance(input.memberId, { current: -validation.pointsToRedeem }, tenantId, session);
+			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
+			};
+			if (tenantId) data[this.config.tenant.field] = tenantId;
+			return this.redemptionPort.create(data, session);
+		});
+		const payload = {
+			memberId: member._id,
+			externalId: member.externalId,
+			redemptionId: redemption._id,
+			points: validation.pointsToRedeem,
+			discountAmount: validation.discountAmount,
+			ownerType: input.ownerType,
+			ownerId: input.ownerId
+		};
+		this.events.emit(LoyaltyEvents.REDEMPTION_RESERVED, payload);
+		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 redemption = await this.redemptionPort.getById(redemptionId, tenantId);
+		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.redemptionPort.atomicStatusTransition(redemptionId, "reserved", {
+				status: "confirmed",
+				pointsConfirmed: redemption.pointsReserved,
+				confirmedAt: /* @__PURE__ */ new Date()
+			}, tenantId, session)) throw new ValidationError(`Redemption status must be 'reserved', got '${redemption.status}'`);
+			const member = await requireActiveMember(this.memberPort, redemption.memberId, tenantId);
+			const tx = await this.txPort.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,
+				...tenantId ? { [this.config.tenant.field]: tenantId } : {}
+			}, session);
+			await this.memberPort.updateBalance(redemption.memberId, { redeemed: redemption.pointsReserved }, tenantId, session);
+			return this.redemptionPort.update(redemptionId, { transactionId: tx._id }, tenantId, session);
+		});
+		const member = await this.memberPort.getById(updated.memberId, tenantId);
+		const payload = {
+			memberId: updated.memberId,
+			externalId: member?.externalId ?? "",
+			redemptionId: updated._id,
+			points: updated.pointsConfirmed,
+			discountAmount: updated.discountAmount,
+			ownerType: updated.ownerType,
+			ownerId: updated.ownerId
+		};
+		this.events.emit(LoyaltyEvents.REDEMPTION_CONFIRMED, payload);
+		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 redemption = await this.redemptionPort.getById(redemptionId, tenantId);
+		if (!redemption) throw new RedemptionNotFoundError(redemptionId);
+		const updated = await this.unitOfWork.withTransaction(async (session) => {
+			const transitioned = await this.redemptionPort.atomicStatusTransition(redemptionId, "reserved", {
+				status: "released",
+				releasedAt: /* @__PURE__ */ new Date()
+			}, tenantId, session);
+			if (!transitioned) throw new ValidationError(`Redemption status must be 'reserved', got '${redemption.status}'`);
+			await this.memberPort.updateBalance(redemption.memberId, { current: redemption.pointsReserved }, tenantId, session);
+			return transitioned;
+		});
+		const member = await this.memberPort.getById(updated.memberId, tenantId);
+		const payload = {
+			memberId: updated.memberId,
+			externalId: member?.externalId ?? "",
+			redemptionId: updated._id,
+			points: updated.pointsReserved,
+			discountAmount: updated.discountAmount,
+			ownerType: updated.ownerType,
+			ownerId: updated.ownerId
+		};
+		this.events.emit(LoyaltyEvents.REDEMPTION_RELEASED, payload);
+		this.notifications?.notify(LoyaltyEvents.REDEMPTION_RELEASED, { ...payload });
+		return updated;
+	}
+	async cleanupExpired(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const now = /* @__PURE__ */ new Date();
+		const expired = await this.redemptionPort.findExpired(now, tenantId);
+		let released = 0;
+		for (const redemption of expired) {
+			await this.release(redemption._id, ctx);
+			released++;
+		}
+		return released;
+	}
+};
+//#endregion
+//#region src/services/referral.service.ts
+var ReferralService = class {
+	constructor(referralPort, memberPort, ledger, events, notifications, config) {
+		this.referralPort = referralPort;
+		this.memberPort = memberPort;
+		this.ledger = ledger;
+		this.events = events;
+		this.notifications = notifications;
+		this.config = config;
+	}
+	async generateCode(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const member = await requireMember(this.memberPort, memberId, tenantId);
+		if (member.referralCode) return member.referralCode;
+		const code = generateReferralCode(this.config.referral.codeLength);
+		await this.memberPort.update(memberId, { referralCode: code }, tenantId);
+		return code;
+	}
+	async lookupByCode(code, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		return this.memberPort.getByReferralCode(code, tenantId);
+	}
+	async recordReferral(input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const referrer = await this.memberPort.getByReferralCode(input.referralCode, tenantId);
+		if (!referrer) throw new MemberNotFoundError(`referral code: ${input.referralCode}`);
+		const referee = await this.memberPort.getByExternalId(input.refereeExternalId, input.refereeExternalType, tenantId);
+		if (!referee) throw new MemberNotFoundError(`referee: ${input.refereeExternalId}`);
+		if (String(referrer._id) === String(referee._id)) throw new SelfReferralError();
+		if (await this.referralPort.getByReferee(referee._id, tenantId)) throw new DuplicateReferralError(referee._id);
+		const reverseReferral = await this.referralPort.getByReferee(referrer._id, tenantId);
+		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.referralPort.countByReferrerInPeriod(referrer._id, periodStart, tenantId) >= 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 (tenantId) data[this.config.tenant.field] = tenantId;
+		if (autoApprove) data.approvedAt = /* @__PURE__ */ new Date();
+		const referral = await this.referralPort.create(data);
+		const payload = {
+			referralId: referral._id,
+			referrerId: referrer._id,
+			refereeId: referee._id,
+			referralCode: input.referralCode,
+			status: referral.status
+		};
+		this.events.emit(LoyaltyEvents.REFERRAL_RECORDED, payload);
+		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 referral = await this.requireReferral(referralId, tenantId);
+		const updated = await this.referralPort.atomicStatusTransition(referralId, "pending", {
+			status: "approved",
+			approvedAt: /* @__PURE__ */ new Date()
+		}, tenantId);
+		if (!updated) throw new ValidationError(`Referral status must be 'pending', got '${referral.status}'`);
+		const referrer = await requireMember(this.memberPort, referral.referrerId, tenantId);
+		const referee = await requireMember(this.memberPort, referral.refereeId, tenantId);
+		const payload = {
+			referralId: updated._id,
+			referrerId: referrer._id,
+			refereeId: referee._id,
+			referralCode: updated.referralCode,
+			status: updated.status
+		};
+		this.events.emit(LoyaltyEvents.REFERRAL_APPROVED, payload);
+		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 referral = await this.requireReferral(referralId, tenantId);
+		const updated = await this.referralPort.atomicStatusTransition(referralId, "pending", {
+			status: "rejected",
+			rejectedAt: /* @__PURE__ */ new Date(),
+			rejectionReason: reason
+		}, tenantId);
+		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
+		};
+		this.events.emit(LoyaltyEvents.REFERRAL_REJECTED, payload);
+		this.notifications?.notify(LoyaltyEvents.REFERRAL_REJECTED, { ...payload });
+		return updated;
+	}
+	async getReferralsByReferrer(memberId, query, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const result = await this.referralPort.findByReferrer(memberId, {
+			page: query.page ?? 1,
+			limit: query.limit ?? 20
+		}, tenantId);
+		return {
+			docs: result.docs,
+			total: result.total,
+			page: result.page,
+			pages: result.pages,
+			hasNext: result.page < result.pages,
+			hasPrev: result.page > 1
+		};
+	}
+	async cleanupExpired(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const now = /* @__PURE__ */ new Date();
+		const expired = await this.referralPort.findExpired(now, tenantId);
+		let count = 0;
+		for (const referral of expired) {
+			await this.referralPort.update(referral._id, { status: "expired" });
+			count++;
+		}
+		return count;
+	}
+	async rewardBothSides(referral, referrer, referee, ctx) {
+		const { referrerRewardPoints, refereeRewardPoints } = this.config.referral;
+		if (referrerRewardPoints > 0) {
+			const referrerTx = await this.ledger.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.referralPort.update(referral._id, { referrerTransactionId: referrerTx._id });
+		}
+		if (refereeRewardPoints > 0) {
+			const refereeTx = await this.ledger.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.referralPort.update(referral._id, { refereeTransactionId: refereeTx._id });
+		}
+		const rewardPayload = {
+			referralId: referral._id,
+			referrerId: referrer._id,
+			refereeId: referee._id,
+			referralCode: referral.referralCode,
+			status: "approved",
+			referrerRewardPoints,
+			refereeRewardPoints
+		};
+		this.events.emit(LoyaltyEvents.REFERRAL_REWARDED, rewardPayload);
+		this.notifications?.notify(LoyaltyEvents.REFERRAL_REWARDED, { ...rewardPayload });
+	}
+	async requireReferral(referralId, tenantId) {
+		const referral = await this.referralPort.getById(referralId, tenantId);
+		if (!referral) throw new ReferralNotFoundError(referralId);
+		return referral;
+	}
+};
+//#endregion
+//#region src/services/tier.service.ts
+var TierService = class {
+	constructor(tierPort, memberPort, events, notifications, config) {
+		this.tierPort = tierPort;
+		this.memberPort = memberPort;
+		this.events = events;
+		this.notifications = notifications;
+		this.config = config;
+	}
+	async evaluateMember(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const member = await requireMember(this.memberPort, memberId, tenantId);
+		const sortedTiers = [...await this.tierPort.findAll(tenantId, member.programId)].sort((a, b) => b.rank - a.rank);
+		if (member.tierOverride) 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, tenantId);
+		if (newRank < currentRank && currentTierDef) return this.applyDowngrade(memberId, member, currentTierDef, qualifiedTier?.name ?? null, tenantId);
+		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 query = { status: "active" };
+		if (tenantId) query[this.config.tenant.field] = tenantId;
+		const members = await this.memberPort.findMany(query);
+		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) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const member = await requireMember(this.memberPort, memberId, tenantId);
+		if (!(await this.tierPort.findAll(tenantId, member.programId)).some((t) => t.name === tierName)) throw new TierNotFoundError(tierName);
+		return this.memberPort.update(memberId, {
+			tierOverride: tierName,
+			tierOverrideReason: reason
+		}, tenantId);
+	}
+	async clearOverride(memberId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		await requireMember(this.memberPort, memberId, tenantId);
+		await this.memberPort.update(memberId, {
+			tierOverride: null,
+			tierOverrideReason: null
+		}, tenantId);
+		return this.evaluateMember(memberId, ctx);
+	}
+	async createTier(input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const data = {
+			...input,
+			programId: input.programId ?? this.config.programId
+		};
+		if (tenantId) data[this.config.tenant.field] = tenantId;
+		return this.tierPort.create(data);
+	}
+	async updateTier(tierId, input, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		if (!await this.tierPort.getById(tierId, tenantId)) throw new TierNotFoundError(tierId);
+		return this.tierPort.update(tierId, { ...input }, tenantId);
+	}
+	async deleteTier(tierId, ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		if (!await this.tierPort.getById(tierId, tenantId)) throw new TierNotFoundError(tierId);
+		return this.tierPort.delete(tierId, tenantId);
+	}
+	async listTiers(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		return [...await this.tierPort.findAll(tenantId, this.config.programId)].sort((a, b) => a.rank - b.rank);
+	}
+	async applyUpgrade(memberId, member, newTierName, tenantId) {
+		await this.memberPort.update(memberId, {
+			tier: newTierName,
+			tierQualifiedAt: /* @__PURE__ */ new Date(),
+			tierExpiresAt: null
+		}, tenantId);
+		const payload = {
+			memberId,
+			externalId: member.externalId,
+			previousTier: member.tier,
+			newTier: newTierName,
+			lifetimePoints: member.balance.lifetime
+		};
+		this.events.emit(LoyaltyEvents.TIER_UPGRADED, payload);
+		this.notifications?.notify(LoyaltyEvents.TIER_UPGRADED, { ...payload });
+		return {
+			memberId,
+			previousTier: member.tier,
+			newTier: newTierName,
+			action: "upgraded"
+		};
+	}
+	async applyDowngrade(memberId, member, currentTierDef, qualifiedTierName, tenantId) {
+		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.memberPort.update(memberId, { tierExpiresAt: graceExpiresAt }, tenantId);
+			const payload = {
+				memberId,
+				externalId: member.externalId,
+				previousTier: member.tier,
+				newTier: member.tier,
+				lifetimePoints: member.balance.lifetime
+			};
+			this.events.emit(LoyaltyEvents.TIER_GRACE_STARTED, payload);
+			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.memberPort.update(memberId, {
+			tier: qualifiedTierName,
+			tierQualifiedAt: qualifiedTierName ? /* @__PURE__ */ new Date() : null,
+			tierExpiresAt: null
+		}, tenantId);
+		const payload = {
+			memberId,
+			externalId: member.externalId,
+			previousTier: member.tier,
+			newTier: qualifiedTierName,
+			lifetimePoints: member.balance.lifetime
+		};
+		this.events.emit(LoyaltyEvents.TIER_DOWNGRADED, payload);
+		this.notifications?.notify(LoyaltyEvents.TIER_DOWNGRADED, { ...payload });
+		return {
+			memberId,
+			previousTier: member.tier,
+			newTier: qualifiedTierName,
+			action: "downgraded"
+		};
+	}
+};
+//#endregion
+//#region src/services/index.ts
+function createServices(input) {
+	const { repositories, unitOfWork, events, notifications, config } = input;
+	const member = new MemberService(repositories.member, events, notifications, unitOfWork, config);
+	const ledger = new LedgerService(repositories.pointTransaction, repositories.member, events, notifications, unitOfWork, config);
+	return {
+		member,
+		ledger,
+		earning: new EarningService(repositories.earningRule, ledger, repositories.member, config),
+		tier: new TierService(repositories.tierDefinition, repositories.member, events, notifications, config),
+		redemption: new RedemptionService(repositories.redemption, repositories.member, repositories.pointTransaction, events, notifications, unitOfWork, config),
+		referral: new ReferralService(repositories.referral, repositories.member, ledger, events, notifications, config)
+	};
+}
+//#endregion
+export { MemberService as a, RedemptionService as i, TierService as n, LedgerService as o, ReferralService as r, EarningService as s, createServices as t };