@classytic/loyalty 0.5.0 → 0.7.0

package/dist/{repositories-CjWfUlrA.mjs → repositories-DErtHQou.mjs}

@@ -1,4 +1,4 @@
-import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-C38JA3cU.mjs";
+import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-DXirolM_.mjs";
 import { Repository, appendOnlyPlugin, multiTenantPlugin } from "@classytic/mongokit";
 import { localTimeParts } from "@classytic/primitives/timezone";
 import { addDays, isoWeekday } from "@classytic/primitives/calendar";
@@ -152,6 +152,27 @@ var UnmanagedSessionError = class extends LoyaltyError {
 	}
 };
 /**
+* A host passed `ctx.session`, but that session has no ACTIVE transaction.
+*
+* A bare `startSession()` provides NO atomicity — every write inside it
+* commits independently. Accepting it as proof of a unit of work is the
+* silent-permissiveness failure in its purest form: loyalty then saves the
+* outbox row "in-session" and applies the balance `$inc` "in-session", and
+* if the outbox save fails the balance mutation still stands with no ledger
+* row behind it. Nothing throws; the points are simply wrong.
+*
+* `session.inTransaction()` is the driver's own answer, so this check cannot
+* drift from what MongoDB actually thinks. `@classytic/access` refuses
+* exactly this at `entitlement.repository.ts` — same rule, same reason.
+*/
+var SessionNotInTransactionError = class extends LoyaltyError {
+	code = "loyalty.transaction.session_not_in_transaction";
+	status = 409;
+	constructor() {
+		super("[loyalty] ctx.session was supplied but has no ACTIVE transaction — a bare session provides no atomicity (each write commits independently), so a failing outbox.save would leave the points mutation standing with the event lost. Drive it with session.withTransaction(...) / startTransaction(), or omit ctx.session and let loyalty open its own transaction.");
+	}
+};
+/**
 * The backend doesn't declare the runtime capabilities loyalty's
 * transactional verbs require (earn / adjust / reserve / confirm / release /
 * reverse all run inside `withTransaction`). MongoDB must run as a replica set
@@ -161,8 +182,18 @@ var UnmanagedSessionError = class extends LoyaltyError {
 var LoyaltyCapabilityError = class extends LoyaltyError {
 	code = "loyalty.engine.missing_capabilities";
 	status = 500;
-	constructor(missing) {
-		super(`[loyalty] backend missing required capabilities: ${missing.join(", ")}. Point earn / redemption / reversal paths are transactional — MongoDB must run as a replica set or sharded cluster.`);
+	/**
+	* `true` when the backend never ANSWERED (bound before the connection
+	* opened, a driver exposing no topology) rather than answering "no". Both
+	* refuse — an unobserved outcome is never a positive one (AGENTS.md FAIL
+	* LOUD rule 3) — but the operator's fix differs, so the message must.
+	*/
+	indeterminate;
+	constructor(missing, opts = {}) {
+		const indeterminate = opts.indeterminate === true;
+		const backendMissing = missing.filter((flag) => !flag.startsWith("outbox."));
+		super(indeterminate ? `[loyalty] could NOT determine whether the backend supports: ${missing.join(", ")}. An unconfirmed answer is treated as unsupported — point earn / redemption / reversal paths are transactional. Bind AFTER \`await mongoose.connect(...)\`, or call \`await probeMongoCapabilities(connection)\` first, or set \`allowNonTransactional: true\`.` : `[loyalty] missing required capabilities: ${missing.join(", ")}.` + (backendMissing.length > 0 ? " Point earn / redemption / reversal paths are transactional — MongoDB must run as a replica set or sharded cluster, or set `allowNonTransactional: true`." : ""));
+		this.indeterminate = indeterminate;
 	}
 };
 //#endregion
@@ -234,8 +265,9 @@ function validatePositivePoints(points, label = "points") {
 	validatePoints(points, label);
 	if (points <= 0) throw new ValidationError(`${label} must be positive`);
 }
+/** `orderTotal` is an integer in the host's minor currency unit (paisa for BDT). */
 function validateOrderTotal(total) {
-	if (!Number.isFinite(total) || total < 0) throw new ValidationError("orderTotal must be a non-negative finite number");
+	if (!Number.isSafeInteger(total) || total < 0) throw new ValidationError("orderTotal must be a non-negative safe integer (minor units)");
 }
 //#endregion
 //#region src/repositories/earning-rule.repository.ts
@@ -251,7 +283,7 @@ var EarningRuleRepository = class extends Repository {
 		injectTenantIntoData(data, options, this.config.tenant);
 	}
 	/**
-	* Auto-injects `programId` from `LoyaltyConfig.program.id` and the tenant id
+	* Auto-injects `programId` from `LoyaltyShape.program.id` and the tenant id
 	* from repo options when omitted. This keeps custom-program engines aligned
 	* with `MemberRepository.enroll(...)`, which uses the same config default.
 	*/
@@ -264,6 +296,14 @@ var EarningRuleRepository = class extends Repository {
 		for (const doc of docs) this.applyCreateDefaults(doc, opts);
 		return super.createMany(docs, options);
 	}
+	/**
+	* Evaluates every active order/category/tier_bonus rule against an order.
+	*
+	* `orderTotal` and `items[].amount` are **integers in the host's minor
+	* currency unit** (paisa for BDT) — `50000` = ৳500. Rates on the rule
+	* (`amountPerPoint`, `pointsPerAmount` + `rateBasis`) are quoted in the
+	* same minor units.
+	*/
 	async evaluateOrder(input, ctx) {
 		validateOrderTotal(input.orderTotal);
 		assertTenantContext(ctx, this.config.tenant);
@@ -394,18 +434,34 @@ var EarningRuleRepository = class extends Repository {
 	weekday(instant) {
 		return (this.config.timezone ? localTimeParts(instant, this.config.timezone).isoWeekday : isoWeekday(instant)) % 7;
 	}
+	/**
+	* `orderTotal` is integer minor units. Two rate shapes:
+	* - `pointsPerAmount` + `rateBasis`: `points = pointsPerAmount × (orderTotal / rateBasis)`
+	* - `amountPerPoint` (minor units per point): `points = orderTotal / amountPerPoint`
+	* Rounding is applied ONCE at the end, per the rule's `roundingMode`.
+	*/
 	calculateOrderPoints(rule, orderTotal) {
 		const { reward } = rule;
 		let points = 0;
-		if (reward.pointsPerAmount) points = orderTotal * reward.pointsPerAmount;
+		if (reward.pointsPerAmount) points = reward.pointsPerAmount * (orderTotal / this.requireRateBasis(rule));
 		else if (reward.amountPerPoint && reward.amountPerPoint > 0) points = orderTotal / reward.amountPerPoint;
 		return this.applyRounding(points, reward.roundingMode);
 	}
+	/**
+	* `pointsPerAmount` has NO implicit basis — a rule that carries it without
+	* an explicit integer minor-unit `rateBasis` is malformed (the schema
+	* enforces the pairing on write; this guards legacy/hand-written docs).
+	*/
+	requireRateBasis(rule) {
+		const rateBasis = rule.reward.rateBasis;
+		if (typeof rateBasis !== "number" || !Number.isInteger(rateBasis) || rateBasis < 1) throw new ValidationError(`Earning rule '${rule.name}' (${rule._id}) sets reward.pointsPerAmount without a valid integer reward.rateBasis (minor units) — points = pointsPerAmount × (orderTotal / rateBasis)`);
+		return rateBasis;
+	}
 	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;
+			if (reward.pointsPerAmount) points += reward.pointsPerAmount * (item.amount / this.requireRateBasis(rule));
 			else if (reward.amountPerPoint) points += item.amount / reward.amountPerPoint;
 		}
 		return this.applyRounding(points, reward.roundingMode);
@@ -428,7 +484,35 @@ var EarningRuleRepository = class extends Repository {
 * host-supplied context fields and never appears in the public type.
 */
 const PENDING_EVENTS = Symbol.for("@classytic/loyalty:pendingEvents");
+/**
+* Set when the unit of work was PERMITTED to run without a transaction
+* (`allowNonTransactional`), so the session-in-transaction guard knows the
+* degradation was chosen rather than stumbled into.
+*
+* Carried on the context because the guard also runs from
+* `dispatchLoyaltyEvent`, which never sees the unit of work. Internal and
+* `Symbol.for`, so no host can set it by accident or on purpose.
+*/
+const NON_TRANSACTIONAL_CONSENTED = Symbol.for("@classytic/loyalty:nonTransactionalConsented");
+/**
+* A caller-supplied `ctx.session` is only evidence of a unit of work if it
+* has an ACTIVE transaction. A bare `startSession()` commits every write
+* independently, so treating it as atomic is how a balance `$inc` lands with
+* no ledger row behind it when the outbox save fails — silently, because the
+* business write already succeeded.
+*
+* `inTransaction()` is the driver's own answer, so this cannot drift from
+* what Mongo actually thinks. Same guard, same rationale as
+* `@classytic/access`'s `atomically()`.
+*/
+function assertSessionInTransaction(ctx) {
+	if (!ctx.session) return;
+	if (ctx[NON_TRANSACTIONAL_CONSENTED]) return;
+	const session = ctx.session;
+	if (typeof session.inTransaction !== "function" || !session.inTransaction()) throw new SessionNotInTransactionError();
+}
 async function dispatchLoyaltyEvent(deps, event, ctx) {
+	assertSessionInTransaction(ctx);
 	const pending = ctx[PENDING_EVENTS];
 	if (deps.outbox) try {
 		const saveOptions = {};
@@ -469,15 +553,21 @@ async function dispatchLoyaltyEvent(deps, event, ctx) {
 */
 async function runLoyaltyUnit(unitOfWork, deps, ctx, body) {
 	const internalCtx = ctx;
-	if (ctx.session) return body(internalCtx);
+	if (ctx.session) {
+		assertSessionInTransaction(ctx);
+		return body(internalCtx);
+	}
 	const pending = [];
 	const result = await unitOfWork.withTransaction(async (session) => {
 		pending.length = 0;
-		return body({
+		const innerCtx = {
 			...internalCtx,
 			session,
-			[PENDING_EVENTS]: pending
-		});
+			[PENDING_EVENTS]: pending,
+			...unitOfWork.allowsNonTransactional ? { [NON_TRANSACTIONAL_CONSENTED]: true } : {}
+		};
+		assertSessionInTransaction(innerCtx);
+		return body(innerCtx);
 	});
 	await flushPendingLoyaltyEvents(deps.events, pending, deps.logger);
 	return result;
@@ -984,43 +1074,56 @@ var PointTransactionRepository = class extends Repository {
 		const affectedMemberIds = /* @__PURE__ */ new Set();
 		for (const tx of expiredTxs) {
 			throwIfAborted(ctx.signal);
-			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
-				}, {
+			const expiredAmount = await this.unitOfWork.withTransaction(async (session) => {
+				const member = await this.memberRepo.requireMember(tx.memberId, {
 					session,
 					...tc
 				});
+				const available = Math.max(0, member.balance.current);
+				const amount = Math.min(tx.points, available);
 				await this.update(tx._id, { expiredAt: now }, {
 					session,
 					...tc,
 					bypassAppendOnly: true
 				});
-				await this.memberRepo.updateBalance(tx.memberId, {
-					current: -tx.points,
-					expired: tx.points
+				if (amount <= 0) return 0;
+				const updatedMember = await this.memberRepo.updateBalance(tx.memberId, {
+					current: -amount,
+					expired: amount
 				}, {
 					session,
 					...tc
 				});
+				if (updatedMember.balance.current < 0) throw new InsufficientPointsError(updatedMember.balance.current + amount, amount);
+				await this.create({
+					memberId: tx.memberId,
+					programId: tx.programId,
+					type: "expire",
+					points: -amount,
+					balanceAfter: updatedMember.balance.current,
+					description: `Points expired from transaction ${tx._id}`,
+					referenceType: "expiration",
+					referenceId: tx._id,
+					actorId: ctx.actorId
+				}, {
+					session,
+					...tc
+				});
+				return amount;
 			});
-			affectedMemberIds.add(tx.memberId);
-			totalExpired += tx.points;
-			transactionCount++;
+			if (expiredAmount > 0) {
+				affectedMemberIds.add(tx.memberId);
+				totalExpired += expiredAmount;
+				transactionCount++;
+			}
 		}
-		if (totalExpired > 0) await this._dispatch(createEvent(LoyaltyEvents.POINTS_EXPIRED, {
-			membersAffected: affectedMemberIds.size,
-			pointsExpired: totalExpired,
-			transactionCount
-		}, ctx), ctx);
+		if (totalExpired > 0) await runLoyaltyUnit(this.unitOfWork, this._dispatchDeps, ctx, async (txCtx) => {
+			await this._dispatch(createEvent(LoyaltyEvents.POINTS_EXPIRED, {
+				membersAffected: affectedMemberIds.size,
+				pointsExpired: totalExpired,
+				transactionCount
+			}, txCtx), txCtx);
+		});
 		return {
 			membersAffected: affectedMemberIds.size,
 			pointsExpired: totalExpired,
@@ -1091,20 +1194,36 @@ var RedemptionRepository = class extends Repository {
 	}
 	/**
 	* Atomic compare-and-set status transition.
-	* Returns null if the current status doesn't match `expectedStatus` (CAS mismatch).
+	*
+	* `null` means ONE thing and one thing only: the guarded update matched
+	* no document, i.e. the status was not `expectedStatus`. `throwOnNotFound:
+	* false` already produces that `null`, so there is nothing legitimate left
+	* for a `catch` to convert.
+	*
+	* There used to be a bare `} catch { return null; }` here. It laundered
+	* every real failure into a CAS miss, and callers map a CAS miss to
+	* `ValidationError("Redemption status must be 'reserved', got '<status>'")`
+	* — a NON-retryable 4xx built from the status read BEFORE the write. So a
+	* routine Mongo `WriteConflict` (a retryable transient, the normal outcome
+	* of two concurrent confirms) surfaced as a client error whose message
+	* could literally read "must be 'reserved', got 'reserved'": an operator
+	* chasing a contradiction while the actual fix was to retry.
+	*
+	* Anything that throws in here is a real error and must propagate.
 	*/
 	async atomicStatusTransition(id, expectedStatus, data, ctx) {
-		try {
-			return await this.update(id, data, {
-				lean: true,
-				query: { status: expectedStatus },
-				throwOnNotFound: false,
-				...ctx
-			});
-		} catch {
-			return null;
-		}
+		return this.update(id, data, {
+			lean: true,
+			query: { status: expectedStatus },
+			throwOnNotFound: false,
+			...ctx
+		});
 	}
+	/**
+	* Validates a redemption request. `orderTotal` is an **integer in the
+	* host's minor currency unit** (paisa for BDT); the returned
+	* `discountAmount` is in the same minor units.
+	*/
 	async validate(input, ctx) {
 		validatePositivePoints(input.pointsToRedeem, "pointsToRedeem");
 		validateOrderTotal(input.orderTotal);
@@ -1113,7 +1232,7 @@ var RedemptionRepository = class extends Repository {
 		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;
+		const { pointValueMinor } = this.config;
 		if (input.pointsToRedeem < minPoints) return {
 			valid: false,
 			error: `Minimum ${minPoints} points required`,
@@ -1135,17 +1254,24 @@ var RedemptionRepository = class extends Repository {
 			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);
+		const maxDiscountMinor = Math.floor(input.orderTotal * maxRedeemPercent / 100);
+		const requestedDiscountMinor = input.pointsToRedeem * pointValueMinor;
+		const cappedDiscountMinor = Math.min(requestedDiscountMinor, maxDiscountMinor);
+		const maxAllowedPoints = Math.floor(maxDiscountMinor / pointValueMinor);
+		const actualPoints = cappedDiscountMinor < requestedDiscountMinor ? Math.floor(cappedDiscountMinor / pointValueMinor) : input.pointsToRedeem;
 		return {
 			valid: true,
-			pointsToRedeem: discountAmount < requestedDiscount ? Math.floor(discountAmount * conversionRate) : input.pointsToRedeem,
-			discountAmount,
+			pointsToRedeem: actualPoints,
+			discountAmount: actualPoints * pointValueMinor,
 			maxAllowedPoints
 		};
 	}
+	/**
+	* Reserves points against an order. `orderTotal` is an **integer in the
+	* host's minor currency unit** (paisa for BDT). The persisted
+	* `discountAmount` is minor units and the reserve-time `pointValueMinor`
+	* rate is snapshotted on the doc.
+	*/
 	async reserve(input, ctx) {
 		assertTenantContext(ctx, this.config.tenant);
 		const tenantId = getTenantValue(ctx, this.config.tenant);
@@ -1172,7 +1298,7 @@ var RedemptionRepository = class extends Repository {
 				pointsReserved: validation.pointsToRedeem,
 				pointsConfirmed: 0,
 				discountAmount: validation.discountAmount,
-				conversionRate: this.config.conversionRate,
+				pointValueMinor: this.config.pointValueMinor,
 				status: "reserved",
 				ownerType: input.ownerType,
 				ownerId: input.ownerId,
@@ -1482,19 +1608,24 @@ var ReferralRepository = class extends Repository {
 	}
 	/**
 	* Atomic compare-and-set status transition.
-	* Returns null if the current status doesn't match `expectedStatus`.
+	*
+	* `null` means ONE thing: the guarded update matched no document, i.e.
+	* the status was not `expectedStatus`. `throwOnNotFound: false` already
+	* returns that `null`, so the bare `} catch { return null; }` that used
+	* to sit here could only ever hide REAL errors — most damagingly a
+	* retryable Mongo `WriteConflict`, which callers then re-threw as a
+	* non-retryable `ValidationError` describing a status that had not
+	* actually gone stale.
+	*
+	* Anything that throws in here is a real error and must propagate.
 	*/
 	async atomicStatusTransition(id, expectedStatus, data, ctx) {
-		try {
-			return await this.update(id, data, {
-				lean: true,
-				query: { status: expectedStatus },
-				throwOnNotFound: false,
-				...ctx
-			});
-		} catch {
-			return null;
-		}
+		return this.update(id, data, {
+			lean: true,
+			query: { status: expectedStatus },
+			throwOnNotFound: false,
+			...ctx
+		});
 	}
 	async generateCode(memberId, ctx) {
 		assertTenantContext(ctx, this.config.tenant);
@@ -1694,7 +1825,7 @@ var ReferralRepository = class extends Repository {
 		if (maxDepth > 1 && referrerRewardPoints > 0) {
 			const awards = [];
 			let currentId = referrer.referredBy;
-			const visited = new Set([referrer._id, referee._id]);
+			const visited = /* @__PURE__ */ new Set([referrer._id, referee._id]);
 			for (let depth = 2; depth <= maxDepth && currentId; depth++) {
 				if (visited.has(currentId)) break;
 				visited.add(currentId);
@@ -1829,9 +1960,7 @@ var TierDefinitionRepository = class extends Repository {
 				case "downgraded":
 					downgraded++;
 					break;
-				default:
-					unchanged++;
-					break;
+				default: unchanged++;
 			}
 		}
 		return {
@@ -2095,4 +2224,4 @@ function createRepositories(input) {
 	};
 }
 //#endregion
-export { TenantIsolationError as C, ValidationError as E, SelfReferralError as S, UnmanagedSessionError as T, RedemptionExpiredError as _, PointTransactionRepository as a, ReferralNotFoundError as b, flushPendingLoyaltyEvents as c, DuplicateReferralError as d, InsufficientPointsError as f, MemberNotFoundError as g, MemberInactiveError as h, RedemptionRepository as i, EarningRuleRepository as l, MemberAlreadyEnrolledError as m, TierDefinitionRepository as n, MemberRepository as o, LoyaltyCapabilityError as p, ReferralRepository as r, PENDING_EVENTS as s, createRepositories as t, CircularReferralError as u, RedemptionNotFoundError as v, TierNotFoundError as w, RuleNotFoundError as x, ReferralLimitExceededError as y };
+export { SessionNotInTransactionError as C, ValidationError as D, UnmanagedSessionError as E, SelfReferralError as S, TierNotFoundError as T, RedemptionExpiredError as _, PointTransactionRepository as a, ReferralNotFoundError as b, flushPendingLoyaltyEvents as c, DuplicateReferralError as d, InsufficientPointsError as f, MemberNotFoundError as g, MemberInactiveError as h, RedemptionRepository as i, EarningRuleRepository as l, MemberAlreadyEnrolledError as m, TierDefinitionRepository as n, MemberRepository as o, LoyaltyCapabilityError as p, ReferralRepository as r, PENDING_EVENTS as s, createRepositories as t, CircularReferralError as u, RedemptionNotFoundError as v, TenantIsolationError as w, RuleNotFoundError as x, ReferralLimitExceededError as y };

package/dist/types/index.d.mts

@@ -1,3 +1,3 @@
-import { _ as TierEvaluationBatch, a as EnrollInput, c as UpdateTierInput, d as EarningResult, f as ExpirationResult, g as TierEvaluation, h as RedemptionValidation, i as EarnPointsInput, l as BalanceSummary, m as PaginatedResult, n as CreateEarningRuleInput, o as LoyaltyContext, p as ListQuery, r as CreateTierInput, s as UpdateEarningRuleInput, t as AdjustPointsInput, u as EarningBreakdown } from "../index-YSsi4e_G.mjs";
-import { a as PluginType, c as ResolvedTenant, i as ModelName, l as TenantConfig, n as LoyaltyConfig, o as RepositoryPlugins, s as ResolvedConfig, t as IndexDefinition } from "../config-Dtun1duw.mjs";
-export { AdjustPointsInput, BalanceSummary, CreateEarningRuleInput, CreateTierInput, EarnPointsInput, EarningBreakdown, EarningResult, EnrollInput, ExpirationResult, IndexDefinition, ListQuery, LoyaltyConfig, LoyaltyContext, ModelName, PaginatedResult, PluginType, RedemptionValidation, RepositoryPlugins, ResolvedConfig, ResolvedTenant, TenantConfig, TierEvaluation, TierEvaluationBatch, UpdateEarningRuleInput, UpdateTierInput };
+import { _ as TierEvaluationBatch, a as EnrollInput, c as UpdateTierInput, d as EarningResult, f as ExpirationResult, g as TierEvaluation, h as RedemptionValidation, i as EarnPointsInput, l as BalanceSummary, m as PaginatedResult, n as CreateEarningRuleInput, o as LoyaltyContext, p as ListQuery, r as CreateTierInput, s as UpdateEarningRuleInput, t as AdjustPointsInput, u as EarningBreakdown } from "../index-Cp_sXNpG.mjs";
+import { a as ModelName, c as ResolvedConfig, i as LoyaltyShape, l as ResolvedTenant, o as PluginType, r as LoyaltyRuntime, s as RepositoryPlugins, t as IndexDefinition, u as TenantConfig } from "../config-CtkGj3xZ.mjs";
+export { AdjustPointsInput, type BalanceSummary, CreateEarningRuleInput, CreateTierInput, EarnPointsInput, type EarningBreakdown, type EarningResult, EnrollInput, type ExpirationResult, type IndexDefinition, type ListQuery, LoyaltyContext, type LoyaltyRuntime, type LoyaltyShape, type ModelName, type PaginatedResult, type PluginType, type RedemptionValidation, type RepositoryPlugins, type ResolvedConfig, type ResolvedTenant, type TenantConfig, type TierEvaluation, type TierEvaluationBatch, UpdateEarningRuleInput, UpdateTierInput };