@classytic/loyalty 0.6.0 → 0.10.0

package/CHANGELOG.md

@@ -3,6 +3,186 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.10.0 — 2026-10-18
+
+> 0.8.0 and 0.9.0 were never published: their changes (below) ship in this release.
+
+### Changed — peer floors
+
+`@classytic/mongokit` `>=3.41.0`, `@classytic/primitives` `>=0.32.0`, `@classytic/repo-core` `>=0.31.0`, `@classytic/validation` `>=0.6.0`, `mongoose` `>=9.11.0`.
+
+### Added — stamp cards ("buy 9, the 10th is free")
+- Three models (`LoyaltyStampProgram`, `LoyaltyStampEntry`, `LoyaltyStampAward`) and three
+  repositories: `stampProgram` (CRUD), `stamps` (`recordOrder`, `settle`, `reverseOrder`,
+  `progress`), `stampAward` (reads).
+- A program counts `order`, `visit` (one per business day in `timezone`), `item` (quantity) or
+  `spend` (`perMinor`), optionally narrowed by category slugs, products, branches and a window;
+  stamps may expire (`stampValidityDays`); awards repeat until `maxRewardsPerMember`.
+- Every guard is an index or a CAS: one entry per (program, member, order), one visit per day,
+  one award per sequence, each entry's `consumed` count claimed in the award's unit of work.
+- Rewards: points (earned with source `campaign` — a grant with no single sale behind it, so
+  `loyalty.points.earned` keeps its enum) or a voucher through the new REQUIRED-when-used
+  `LoyaltyRuntime.rewardIssuer` port, idempotent on `awardKey`. A voucher award is claimed
+  `pending` and issued after commit; `settle` resumes a pending one.
+- `reverseOrder` removes an undone order's unconsumed stamps; stamps already in an award are kept
+  and reported (`retainedInAwards`).
+- Refused at write: an empty allow-list, `spend` without `perMinor`, a window that ends before it
+  starts, and a voucher reward on an engine bound without `rewardIssuer`.
+  `stampProgramInputSchema` / `stampProgramPatchSchema` are the strict wire bodies.
+- `StampProgram`, `StampEntry` and `StampAward` type their stored ids as `Types.ObjectId` (what a
+  read returns); the progress, record and reversal results and event payloads stay strings.
+- Events: `loyalty.stamp.earned`, `loyalty.stamp.reversed`, `loyalty.stamp.award_issued`.
+
+### Added — `item` stamps on lines sold by measure
+`StampOrderLine.quantityStep` (optional; absent = 1). A line whose step is not a whole number (2.35 kg
+of rice on a 0.001 kg step) earns ONE `item` stamp, never `floor(kg)` or the gram count; whole-unit
+lines still count units. `recordOrder` refuses a fractional quantity on a line that declares no
+step (it used to be floored) and a non-positive step. Pinned by
+`tests/unit/stamp-fractional-quantity.test.ts`.
+
+## 0.8.0
+
+### Fixed — one expiry sweep expires every due lot
+
+`processExpirations` read ONE page of 100 due lots per call, and the hourly schedule calls it once,
+so a burst of due lots (a year-end lifetime) expired at 2,400 a day — members kept spending points
+already past their date. It now pages until no lot due by the call's `now` remains, in
+`(expiresAt, _id)` order, over a new partial index `expiry_sweep` that skips expired history and
+non-expiring rows (203 → 3 documents examined). Pinned by `tests/scenarios/point-expiry.scenario.test.ts`.
+
+### ⚠ Changed — string-key partial indexes are `{ $gte: '' }`, so lookups by key use them
+
+`{ $type: 'string' }` is never implied by an equality query, so lookups by point-transaction
+`idempotencyKey`, member `cardId` and `referralCode` were collection scans. `$gte: ''` admits the
+same rows. Renamed `idempotencyKey_str`, `cardId_str`, `referralCode_str`.
+**Deploy:** build, then `db:retire-type-string-indexes -- --apply`.
+
+### Changed (breaking) — every points fact carries what a ledger needs to book it
+- `earnPoints` REQUIRES `source: 'order' | 'action' | 'referral' | 'campaign'` (`EARN_SOURCES`),
+  refused at runtime when unknown. Only `order` has a sale behind it; a consumer may defer part of
+  that sale's price, and treat every other source as a grant. Stamped on the row and on
+  `loyalty.points.earned`. The kernel's own callers set it (rules → `order` / `action`,
+  referrals → `referral`, `awardBatch` → `campaign`).
+- `pointValueMinor` (what ONE point was worth at that moment) is stamped on earn, adjust,
+  reverse and expire rows and on their events; `loyalty.redemption.reversed` carries the
+  redemption's own rate. The RATE, not a product — a reversal has claimed/collected/shortfall
+  quantities and a consumer multiplies whichever it books.
+- New `loyalty.points.lot_expired`, one per expired lot, dispatched INSIDE the lot's unit of
+  work — a crash can no longer leave a lot stamped expired with no event. The aggregate
+  `loyalty.points.expired` summary is unchanged.
+- `loyalty.redemption.reversed.transactionId` is omitted when nothing was credited (was `''`,
+  which collides as a key).
+
+### Added — `redemption.outstandingLiability(ctx)`
+What the program owes: spendable balances plus points held by open reservations, at the current
+point value (`LoyaltyLiabilitySnapshot`). The figure a ledger's liability reconciles against.
+
+### Fixed — events carry string ids, as their catalog declares
+`createEvent` converts ObjectIds in the payload to strings. An in-process subscriber received
+ObjectIds while the outbox delivered strings, so a consumer validating against the published
+schema refused every live delivery. Pinned by a test that parses every emitted event with its
+own definition.
+
+### Changed — members are placed in a tier from the start
+`enroll` assigns the entry tier (the highest one 0 lifetime points qualifies for) unless one is
+given — was `null` until a sweep. `evaluateMember(id, ctx, { upgradeOnly })` promotes but never
+demotes (the earn path); `qualifiedTierName(programId, lifetime)` answers placement.
+
+### Added — `earnBase`, the one definition of what an order earns on
+`@classytic/loyalty/domain/earn-base` (zero imports): earning lines at the price charged,
+minus their pro-rata share of every order discount (promo, manual, points redeemed).
+Shipping, fee lines and tax added on top never earn; tax inside a shelf price is part of that
+price. Returns `{ orderTotal, items }` that sum exactly (largest remainder), so an `order` rule
+and a `category` rule read one base. Matches Smile.io / LoyaltyLion / Square / Odoo.
+
+### Added — undo loyalty for a refunded or canceled purchase
+
+- `pointTransaction.reverseEarned({ referenceType, referenceId, fraction, reason }, ctx)`
+  claws back `floor(earned × fraction)` of what a reference earned, minus what
+  earlier reversals claimed. Converges by state: replays and concurrent callers
+  reverse nothing extra (the idempotency key is derived from the target).
+  Points already spent are returned as `shortfall`, never driven below zero;
+  `lifetime` drops by the full claim.
+- `redemption.undoForOwner(ownerIds, ctx, { reason })` reverses confirmed and
+  releases reserved redemptions held against any of the owner's identities.
+- `redemption.confirmForOwner(ownerIds, ctx)` confirms holds still `reserved`
+  against an order that exists — the net for a checkout whose inline confirm
+  failed. `confirm(id, ctx, { ownerExists: true })` skips the TTL refusal for it.
+- **Behaviour change — tier `benefits.pointsMultiplier` is applied.** It was stored
+  and never read, so a Gold ×2 member earned like ×1. `evaluateOrder` now adds
+  `floor(rulePoints × (m − 1))` for m > 1 as its own `earn` row
+  (`Tier bonus: <tier> ×m`, idempotency `<order>:tier-multiplier`), using the
+  override tier when set. Programs with multipliers configured will award more
+  from this release on. `reverseEarned` reverses it with the rule points.
+- **Behaviour change — points expire when the program says so.** `expiry` was
+  resolved and read by nothing, so every earn had no `expiresAt` and the sweep
+  never expired anything. `earnPoints` now stamps `now + expiry.defaultDays`
+  when the caller sets none. `expiry.enabled` without a whole `defaultDays >= 1`
+  is refused at build.
+- **Live program settings.** `LoyaltyRuntime.programSettings()` supplies the
+  operator-owned settings (point value, redemption limits, expiry) PER OPERATION
+  over the shape's values; one rule set (`assertProgram`) validates boot and live
+  values alike, and an invalid live value fails the operation. A hold snapshots
+  the rate it was priced at.
+- **Behaviour change — redemption refuses what it used to wave through:** a 0%
+  cap ("switched off") and a cap that leaves fewer points than the minimum now
+  return `valid: false` with a reason; before they were a zero- or sub-minimum
+  "success" that `reserve` recorded.
+- Earning rules honour their schedule: `startsAt`/`endsAt` (what the admin form
+  writes) AND `conditions.dateRange`. Before, only `dateRange` was read, so an
+  ended rule kept earning. `isRuleInSchedule` — also at the light subpath
+  `@classytic/loyalty/domain/rule-schedule` — is the one predicate for earn and preview.
+- `LoyaltyRedemptionPort` / `LoyaltyRedemption` / `LoyaltyReserveInput` — the
+  checkout contract, owned here so till and web pipelines `import type` one shape.
+- Ledger type `reverse` (`TRANSACTION_TYPES` now has 7 values) and event
+  `loyalty.points.reversed` (`PointsReversed` in the catalog).
+
+## 0.7.0
+
+### Fixed — a `UnitOfWork` yielding a non-transactional session ran the body anyway
+
+`runLoyaltyUnit` asserted `inTransaction()` on the HOST-session branch and not on
+the `unitOfWork.withTransaction` branch, so only one of the two ways a body gets
+a session was guarded. The comment above that check already stated the rule —
+"guard before the body runs, not at the first emit: a verb can mutate before it
+dispatches" — and it was applied to one branch.
+
+It matters because the balance verbs compensate by THROWING to roll an `$inc`
+back. Without a real transaction that buys nothing: `redeem` decrements a
+member's points, sees the balance go negative, throws — and the points stay
+gone while the caller is told the redemption failed. A lying `withTransaction`
+was previously caught at the first event DISPATCH, by which time the write had
+landed.
+
+3 cases in `tests/unit/unit-of-work-transaction-guard.test.ts`, asserting the
+body did NOT run — the rejection alone would pass even if it had mutated first.
+Falsified: removing the guard fails 2 of 3.
+
+### Fixed — the transaction guard must not override `allowNonTransactional`
+
+The fix above asserted `inTransaction()` unconditionally, which also made it
+wrong: `allowNonTransactional` is an explicit host opt-in (loyalty already
+warns about it at boot) for a standalone-Mongo deployment where
+`withTransaction({ allowFallback })` runs the callback with no transaction ON
+PURPOSE. The guard turned that documented degradation into a hard failure, so
+a standalone-Mongo host lost point earn / redemption / reversal entirely — a
+general rule silently defeating a specific decision, the inverse of what the
+guard exists to catch.
+
+`UnitOfWork` now states whether it may degrade, and the consent travels on the
+internal context because the same guard also runs from `dispatchLoyaltyEvent`,
+which never sees the unit of work. Absent still means no: an implementation
+that yields a bare session without saying so is still refused, and a
+host-supplied `ctx.session` has no opt-in and always asserts. Falsified both
+ways in `unit-of-work-transaction-guard.test.ts`.
+
+### Changed — peer floors raised to current
+
+- `@classytic/mongokit` `>=3.33.0` → **`>=3.38.1`**
+- `@classytic/primitives` `>=0.23.0` → **`>=0.27.0`**
+- `@classytic/repo-core` `>=0.24.0` → **`>=0.27.1`**
+- `@classytic/validation` `>=0.2.0` → **`>=0.5.0`**
+
 ## [0.6.0] — 2026-08-17
 
 ### Added

package/dist/constants-DfrENxFG.mjs

@@ -0,0 +1,75 @@
+//#region src/constants.ts
+const DEFAULT_PROGRAM_ID = "default";
+const TRANSACTION_TYPES = Object.freeze([
+	"earn",
+	"redeem",
+	"adjust",
+	"expire",
+	"transfer",
+	"referral_bonus",
+	"reverse"
+]);
+/**
+* Why points were EARNED — a closed set, required on every earn. `order` is points
+* granted with a sale (a consumer defers part of that sale's price); every other source
+* is a grant with no sale behind it.
+*/
+const EARN_SOURCES = Object.freeze([
+	"order",
+	"action",
+	"referral",
+	"campaign"
+]);
+const MEMBER_STATUSES = Object.freeze([
+	"active",
+	"inactive",
+	"suspended"
+]);
+const RULE_TYPES = Object.freeze([
+	"order",
+	"action",
+	"category",
+	"tier_bonus"
+]);
+const RULE_STATUSES = Object.freeze([
+	"active",
+	"paused",
+	"expired"
+]);
+const REFERRAL_STATUSES = Object.freeze([
+	"pending",
+	"approved",
+	"rejected",
+	"expired"
+]);
+const REDEMPTION_STATUSES = Object.freeze([
+	"reserved",
+	"confirmed",
+	"released",
+	"expired",
+	"reversed"
+]);
+const EARNING_ACTIONS = Object.freeze([
+	"signup",
+	"referral",
+	"birthday",
+	"review",
+	"profile_complete"
+]);
+const STAMP_PROGRAM_STATUSES = Object.freeze([
+	"active",
+	"paused",
+	"ended"
+]);
+/** What one stamp counts: a qualifying order, a business day with one, an item, or `perMinor` of spend. */
+const STAMP_EARN_UNITS = Object.freeze([
+	"order",
+	"visit",
+	"item",
+	"spend"
+]);
+const STAMP_REWARD_KINDS = Object.freeze(["points", "voucher"]);
+/** `pending` = claimed (stamps consumed) but the external reward not yet issued; settle resumes it. */
+const STAMP_AWARD_STATUSES = Object.freeze(["pending", "issued"]);
+//#endregion
+export { REDEMPTION_STATUSES as a, RULE_TYPES as c, STAMP_PROGRAM_STATUSES as d, STAMP_REWARD_KINDS as f, MEMBER_STATUSES as i, STAMP_AWARD_STATUSES as l, EARNING_ACTIONS as n, REFERRAL_STATUSES as o, TRANSACTION_TYPES as p, EARN_SOURCES as r, RULE_STATUSES as s, DEFAULT_PROGRAM_ID as t, STAMP_EARN_UNITS as u };

package/dist/domain/earn-base.d.mts

@@ -0,0 +1,35 @@
+//#region src/domain/earn-base.d.ts
+/**
+ * The amount an order earns on — ONE definition for the award, the preview and
+ * every host: earning lines at the price charged, minus their pro-rata share of
+ * every order discount (promo, manual, points redeemed). Shipping, fee lines and
+ * tax added on top never earn; tax inside a shelf price is part of that price.
+ *
+ * Integer minor units in and out. Zero imports, so a client can share it.
+ */
+export interface EarnBaseLine {
+  /** What the line was charged before order-level discounts (`lineTotal`), minor units. */
+  amount: number;
+  /** False for a line that is not merchandise — a service fee, a surcharge. */
+  earns: boolean;
+  quantity?: number;
+  categoryId?: string;
+}
+export interface EarnBaseInput {
+  lines: readonly EarnBaseLine[];
+  /** Every order-level discount, minor units — spread over ALL lines, fees included. */
+  discount: number;
+}
+export interface EarnBaseItem {
+  amount: number;
+  quantity: number;
+  categoryId?: string;
+}
+export interface EarnBase {
+  /** Σ `items[].amount` — what an `order` rule reads. */
+  orderTotal: number;
+  /** Per earning line, net of its discount share — what a `category` rule reads. */
+  items: EarnBaseItem[];
+}
+export declare function earnBase({ lines, discount }: EarnBaseInput): EarnBase;
+//#endregion

package/dist/domain/earn-base.mjs

@@ -0,0 +1,37 @@
+//#region src/domain/earn-base.ts
+const whole = (n) => Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+function earnBase({ lines, discount }) {
+	const priced = lines.map((l) => ({
+		...l,
+		amount: whole(l.amount)
+	}));
+	const gross = priced.reduce((s, l) => s + l.amount, 0);
+	const off = Math.min(whole(discount), gross);
+	const earning = priced.filter((l) => l.earns && l.amount > 0);
+	if (gross === 0 || earning.length === 0) return {
+		orderTotal: 0,
+		items: []
+	};
+	const earningGross = earning.reduce((s, l) => s + l.amount, 0);
+	const target = earningGross - Math.round(off * earningGross / gross);
+	const shares = earning.map((l) => l.amount * target / earningGross);
+	const nets = shares.map(Math.floor);
+	let left = target - nets.reduce((s, n) => s + n, 0);
+	const byRemainder = shares.map((s, i) => [s - Math.floor(s), i]).sort((a, b) => b[0] - a[0]);
+	for (const [, i] of byRemainder) {
+		if (left <= 0) break;
+		nets[i] = (nets[i] ?? 0) + 1;
+		left -= 1;
+	}
+	const items = earning.map((l, i) => ({
+		amount: nets[i] ?? 0,
+		quantity: l.quantity ?? 1,
+		...l.categoryId ? { categoryId: l.categoryId } : {}
+	})).filter((it) => it.amount > 0);
+	return {
+		orderTotal: items.reduce((s, it) => s + it.amount, 0),
+		items
+	};
+}
+//#endregion
+export { earnBase };

package/dist/domain/enums/index.d.mts

@@ -1,2 +1,2 @@
-import { a as RuleStatus, c as EARNING_ACTIONS, d as REFERRAL_STATUSES, f as RULE_STATUSES, i as ReferralStatus, l as MEMBER_STATUSES, m as TRANSACTION_TYPES, n as MemberStatus, o as RuleType, p as RULE_TYPES, r as RedemptionStatus, s as TransactionType, t as EarningAction, u as REDEMPTION_STATUSES } from "../../index-D_Oe3aDk.mjs";
-export { EARNING_ACTIONS, EarningAction, MEMBER_STATUSES, MemberStatus, REDEMPTION_STATUSES, REFERRAL_STATUSES, RULE_STATUSES, RULE_TYPES, RedemptionStatus, ReferralStatus, RuleStatus, RuleType, TRANSACTION_TYPES, TransactionType };
+import { C as STAMP_REWARD_KINDS, S as STAMP_PROGRAM_STATUSES, _ as REFERRAL_STATUSES, a as ReferralStatus, b as STAMP_AWARD_STATUSES, c as StampAwardStatus, d as StampRewardKind, f as TransactionType, g as REDEMPTION_STATUSES, h as MEMBER_STATUSES, i as RedemptionStatus, l as StampEarnUnit, m as EARN_SOURCES, n as EarningAction, o as RuleStatus, p as EARNING_ACTIONS, r as MemberStatus, s as RuleType, t as EarnSource, u as StampProgramStatus, v as RULE_STATUSES, w as TRANSACTION_TYPES, x as STAMP_EARN_UNITS, y as RULE_TYPES } from "../../index-tjMMmPzU.mjs";
+export { EARNING_ACTIONS, EARN_SOURCES, EarnSource, EarningAction, MEMBER_STATUSES, MemberStatus, REDEMPTION_STATUSES, REFERRAL_STATUSES, RULE_STATUSES, RULE_TYPES, RedemptionStatus, ReferralStatus, RuleStatus, RuleType, STAMP_AWARD_STATUSES, STAMP_EARN_UNITS, STAMP_PROGRAM_STATUSES, STAMP_REWARD_KINDS, StampAwardStatus, StampEarnUnit, StampProgramStatus, StampRewardKind, TRANSACTION_TYPES, TransactionType };

package/dist/domain/enums/index.mjs

@@ -1,2 +1 @@
-import { a as REFERRAL_STATUSES, c as TRANSACTION_TYPES, i as REDEMPTION_STATUSES, n as EARNING_ACTIONS, o as RULE_STATUSES, r as MEMBER_STATUSES, s as RULE_TYPES } from "../../constants-DOPBh6kt.mjs";
-export { EARNING_ACTIONS, MEMBER_STATUSES, REDEMPTION_STATUSES, REFERRAL_STATUSES, RULE_STATUSES, RULE_TYPES, TRANSACTION_TYPES };
+export { n as EARNING_ACTIONS, r as EARN_SOURCES, i as MEMBER_STATUSES, a as REDEMPTION_STATUSES, o as REFERRAL_STATUSES, s as RULE_STATUSES, c as RULE_TYPES, l as STAMP_AWARD_STATUSES, u as STAMP_EARN_UNITS, d as STAMP_PROGRAM_STATUSES, f as STAMP_REWARD_KINDS, p as TRANSACTION_TYPES } from "../../constants-DfrENxFG.mjs";

package/dist/domain/rule-schedule.d.mts

@@ -0,0 +1,24 @@
+//#region src/domain/rule-schedule.d.ts
+/**
+ * Is an earning rule live at `now`? The ONE schedule predicate — the earn path
+ * and any preview call this, so the two cannot disagree.
+ *
+ * A rule carries its window twice: top-level `startsAt`/`endsAt` (what the admin
+ * form writes) and `conditions.dateRange` (older rules, the API). It is live only
+ * inside BOTH. Ignoring the top-level pair is how an "Ends At" date never stopped
+ * a rule.
+ */
+type Instant = Date | string | null | undefined;
+export interface ScheduledRuleLike {
+  startsAt?: Instant;
+  endsAt?: Instant;
+  conditions?: {
+    dateRange?: {
+      start?: Instant;
+      end?: Instant;
+    } | undefined;
+  } | undefined;
+}
+export declare function isRuleInSchedule(rule: ScheduledRuleLike, now: Date): boolean;
+//#endregion
+export {};

package/dist/domain/rule-schedule.mjs

@@ -0,0 +1,12 @@
+//#region src/domain/rule-schedule.ts
+const at = (v) => v ? new Date(v).getTime() : null;
+function isRuleInSchedule(rule, now) {
+	const t = now.getTime();
+	const starts = [at(rule.startsAt), at(rule.conditions?.dateRange?.start)];
+	const ends = [at(rule.endsAt), at(rule.conditions?.dateRange?.end)];
+	if (starts.some((s) => s !== null && t < s)) return false;
+	if (ends.some((e) => e !== null && t > e)) return false;
+	return true;
+}
+//#endregion
+export { isRuleInSchedule };

package/dist/events/index.d.mts

@@ -1,2 +1,2 @@
-import { A as PointsExpired, B as ReferralRewarded, C as MemberDeactivated, D as MultiTierReferralAwarded, E as MemberSuspended, F as RedemptionReserved, G as TierUpgraded, H as TierGraceStarted, I as RedemptionReversed, J as InProcessLoyaltyBusOptions, K as loyaltyEventDefinitions, L as ReferralApproved, M as PointsRedeemed, N as RedemptionConfirmed, O as PointsAdjusted, P as RedemptionReleased, R as ReferralRecorded, S as LoyaltyEventSchema, T as MemberReactivated, U as TierOverrideCleared, V as TierDowngraded, W as TierOverrideExpired, Y as createEvent, _ as TierChangedPayload, a as LoyaltyEventMap, b as LoyaltyEventDefinition, c as LoyaltyEvents, d as PointsAdjustedPayload, f as PointsEarnedPayload, g as ReferralPayload, h as RedemptionReversedPayload, i as CampaignAwardedPayload, j as PointsExpiringSoon, k as PointsEarned, l as MemberLifecyclePayload, m as RedemptionPayload, n as EventHandler, o as LoyaltyEventName, p as PointsExpiredPayload, q as InProcessLoyaltyBus, r as EventTransport, s as LoyaltyEventPayload, t as DomainEvent, u as MultiTierReferralAwardedPayload, v as TierOverrideLifecyclePayload, w as MemberEnrolled, x as LoyaltyEventPayloadOf, y as CampaignAwarded, z as ReferralRejected } from "../index-YUFamhDk.mjs";
-export { CampaignAwarded, type CampaignAwardedPayload, type DomainEvent, type EventHandler, type EventTransport, InProcessLoyaltyBus, type InProcessLoyaltyBusOptions, type LoyaltyEventDefinition, type LoyaltyEventMap, type LoyaltyEventName, type LoyaltyEventPayload, type LoyaltyEventPayloadOf, type LoyaltyEventSchema, LoyaltyEvents, MemberDeactivated, MemberEnrolled, type MemberLifecyclePayload, MemberReactivated, MemberSuspended, MultiTierReferralAwarded, type MultiTierReferralAwardedPayload, PointsAdjusted, type PointsAdjustedPayload, PointsEarned, type PointsEarnedPayload, PointsExpired, type PointsExpiredPayload, PointsExpiringSoon, PointsRedeemed, RedemptionConfirmed, type RedemptionPayload, RedemptionReleased, RedemptionReserved, RedemptionReversed, type RedemptionReversedPayload, ReferralApproved, type ReferralPayload, ReferralRecorded, ReferralRejected, ReferralRewarded, type TierChangedPayload, TierDowngraded, TierGraceStarted, TierOverrideCleared, TierOverrideExpired, type TierOverrideLifecyclePayload, TierUpgraded, createEvent, loyaltyEventDefinitions };
+import { $ as TierOverrideCleared, A as MemberReactivated, B as RedemptionConfirmed, C as TierOverrideLifecyclePayload, D as LoyaltyEventSchema, E as LoyaltyEventPayloadOf, F as PointsExpired, G as ReferralRecorded, H as RedemptionReserved, I as PointsExpiringSoon, J as StampAwardIssued, K as ReferralRejected, L as PointsLotExpired, M as MultiTierReferralAwarded, N as PointsAdjusted, O as MemberDeactivated, P as PointsEarned, Q as TierGraceStarted, R as PointsRedeemed, S as TierChangedPayload, T as LoyaltyEventDefinition, U as RedemptionReversed, V as RedemptionReleased, W as ReferralApproved, X as StampReversed, Y as StampEarned, Z as TierDowngraded, _ as RedemptionReversedPayload, a as LoyaltyEventMap, at as createEvent, b as StampEarnedPayload, c as LoyaltyEvents, d as PointsAdjustedPayload, et as TierOverrideExpired, f as PointsEarnedPayload, g as RedemptionPayload, h as PointsReversedPayload, i as CampaignAwardedPayload, it as InProcessLoyaltyBusOptions, j as MemberSuspended, k as MemberEnrolled, l as MemberLifecyclePayload, m as PointsLotExpiredPayload, n as EventHandler, nt as loyaltyEventDefinitions, o as LoyaltyEventName, p as PointsExpiredPayload, q as ReferralRewarded, r as EventTransport, rt as InProcessLoyaltyBus, s as LoyaltyEventPayload, t as DomainEvent, tt as TierUpgraded, u as MultiTierReferralAwardedPayload, v as ReferralPayload, w as CampaignAwarded, x as StampReversedPayload, y as StampAwardIssuedPayload, z as PointsReversed } from "../index-Db5Gb7x_.mjs";
+export { CampaignAwarded, type CampaignAwardedPayload, type DomainEvent, type EventHandler, type EventTransport, InProcessLoyaltyBus, type InProcessLoyaltyBusOptions, type LoyaltyEventDefinition, type LoyaltyEventMap, type LoyaltyEventName, type LoyaltyEventPayload, type LoyaltyEventPayloadOf, type LoyaltyEventSchema, LoyaltyEvents, MemberDeactivated, MemberEnrolled, type MemberLifecyclePayload, MemberReactivated, MemberSuspended, MultiTierReferralAwarded, type MultiTierReferralAwardedPayload, PointsAdjusted, type PointsAdjustedPayload, PointsEarned, type PointsEarnedPayload, PointsExpired, type PointsExpiredPayload, PointsExpiringSoon, PointsLotExpired, type PointsLotExpiredPayload, PointsRedeemed, PointsReversed, type PointsReversedPayload, RedemptionConfirmed, type RedemptionPayload, RedemptionReleased, RedemptionReserved, RedemptionReversed, type RedemptionReversedPayload, ReferralApproved, type ReferralPayload, ReferralRecorded, ReferralRejected, ReferralRewarded, StampAwardIssued, type StampAwardIssuedPayload, StampEarned, type StampEarnedPayload, StampReversed, type StampReversedPayload, type TierChangedPayload, TierDowngraded, TierGraceStarted, TierOverrideCleared, TierOverrideExpired, type TierOverrideLifecyclePayload, TierUpgraded, createEvent, loyaltyEventDefinitions };

package/dist/events/index.mjs

@@ -1,3 +1,3 @@
-import { C as TierOverrideExpired, E as InProcessLoyaltyBus, S as TierOverrideCleared, T as loyaltyEventDefinitions, _ as ReferralRecorded, a as MemberSuspended, b as TierDowngraded, c as PointsEarned, d as PointsRedeemed, f as RedemptionConfirmed, g as ReferralApproved, h as RedemptionReversed, i as MemberReactivated, l as PointsExpired, m as RedemptionReserved, n as MemberDeactivated, o as MultiTierReferralAwarded, p as RedemptionReleased, r as MemberEnrolled, s as PointsAdjusted, t as CampaignAwarded, u as PointsExpiringSoon, v as ReferralRejected, w as TierUpgraded, x as TierGraceStarted, y as ReferralRewarded } from "../events-BLjg3uLA.mjs";
-import { n as createEvent, t as LoyaltyEvents } from "../loyalty-events-DXirolM_.mjs";
-export { CampaignAwarded, InProcessLoyaltyBus, LoyaltyEvents, MemberDeactivated, MemberEnrolled, MemberReactivated, MemberSuspended, MultiTierReferralAwarded, PointsAdjusted, PointsEarned, PointsExpired, PointsExpiringSoon, PointsRedeemed, RedemptionConfirmed, RedemptionReleased, RedemptionReserved, RedemptionReversed, ReferralApproved, ReferralRecorded, ReferralRejected, ReferralRewarded, TierDowngraded, TierGraceStarted, TierOverrideCleared, TierOverrideExpired, TierUpgraded, createEvent, loyaltyEventDefinitions };
+import { A as loyaltyEventDefinitions, C as StampEarned, D as TierOverrideCleared, E as TierGraceStarted, O as TierOverrideExpired, S as StampAwardIssued, T as TierDowngraded, _ as RedemptionReversed, a as MemberSuspended, b as ReferralRejected, c as PointsEarned, d as PointsLotExpired, f as PointsRedeemed, g as RedemptionReserved, h as RedemptionReleased, i as MemberReactivated, j as InProcessLoyaltyBus, k as TierUpgraded, l as PointsExpired, m as RedemptionConfirmed, n as MemberDeactivated, o as MultiTierReferralAwarded, p as PointsReversed, r as MemberEnrolled, s as PointsAdjusted, t as CampaignAwarded, u as PointsExpiringSoon, v as ReferralApproved, w as StampReversed, x as ReferralRewarded, y as ReferralRecorded } from "../events-DhZolW61.mjs";
+import { n as createEvent, t as LoyaltyEvents } from "../loyalty-events-j29B66YW.mjs";
+export { CampaignAwarded, InProcessLoyaltyBus, LoyaltyEvents, MemberDeactivated, MemberEnrolled, MemberReactivated, MemberSuspended, MultiTierReferralAwarded, PointsAdjusted, PointsEarned, PointsExpired, PointsExpiringSoon, PointsLotExpired, PointsRedeemed, PointsReversed, RedemptionConfirmed, RedemptionReleased, RedemptionReserved, RedemptionReversed, ReferralApproved, ReferralRecorded, ReferralRejected, ReferralRewarded, StampAwardIssued, StampEarned, StampReversed, TierDowngraded, TierGraceStarted, TierOverrideCleared, TierOverrideExpired, TierUpgraded, createEvent, loyaltyEventDefinitions };

package/dist/{events-BLjg3uLA.mjs → events-DhZolW61.mjs}

@@ -1,4 +1,5 @@
-import { t as LoyaltyEvents } from "./loyalty-events-DXirolM_.mjs";
+import { r as EARN_SOURCES } from "./constants-DfrENxFG.mjs";
+import { t as LoyaltyEvents } from "./loyalty-events-j29B66YW.mjs";
 import { InProcessEventBus } from "@classytic/primitives/event-infra";
 import { createEvent } from "@classytic/primitives/events";
 import { z } from "zod";
@@ -50,11 +51,15 @@ const memberLifecycleSchema = z.object({
 	status: z.string()
 });
 /** Mirrors `PointsEarnedPayload`. */
+/** Minor units one point was worth at the fact — integer, at least 1. */
+const pointValue = z.number().int().min(1);
 const pointsEarnedSchema = z.object({
 	memberId: z.string(),
 	externalId: z.string(),
 	externalType: z.string(),
 	points: z.number(),
+	source: z.enum(EARN_SOURCES),
+	pointValueMinor: pointValue,
 	balanceAfter: z.number(),
 	transactionId: z.string(),
 	earningRuleName: z.string().optional(),
@@ -66,16 +71,41 @@ const pointsAdjustedSchema = z.object({
 	memberId: z.string(),
 	externalId: z.string(),
 	points: z.number(),
+	pointValueMinor: pointValue,
 	balanceAfter: z.number(),
 	transactionId: z.string(),
 	description: z.string()
 });
+/** Mirrors `PointsReversedPayload`. */
+const pointsReversedSchema = z.object({
+	memberId: z.string(),
+	externalId: z.string(),
+	referenceType: z.string(),
+	referenceId: z.string(),
+	claimed: z.number().int().nonnegative(),
+	collected: z.number().int().nonnegative(),
+	shortfall: z.number().int().nonnegative(),
+	pointValueMinor: pointValue,
+	balanceAfter: z.number(),
+	transactionId: z.string(),
+	reason: z.string()
+});
 /** Mirrors `PointsExpiredPayload` — reused by EXPIRED + EXPIRING_SOON. */
 const pointsExpiredSchema = z.object({
 	membersAffected: z.number().int().nonnegative(),
 	pointsExpired: z.number().int().nonnegative(),
 	transactionCount: z.number().int().nonnegative()
 });
+/** Mirrors `PointsLotExpiredPayload`. */
+const pointsLotExpiredSchema = z.object({
+	memberId: z.string(),
+	externalId: z.string(),
+	transactionId: z.string(),
+	lotTransactionId: z.string(),
+	points: z.number().int().positive(),
+	pointValueMinor: pointValue,
+	balanceAfter: z.number()
+});
 /** Mirrors `TierChangedPayload` — reused by UPGRADED + DOWNGRADED + GRACE_STARTED. */
 const tierChangedSchema = z.object({
 	memberId: z.string(),
@@ -125,7 +155,8 @@ const redemptionReversedSchema = z.object({
 	originalPoints: z.number(),
 	proportional: z.boolean(),
 	reason: z.string().optional(),
-	transactionId: z.string()
+	pointValueMinor: pointValue,
+	transactionId: z.string().optional()
 });
 /** Mirrors `CampaignAwardedPayload`. */
 const campaignAwardedSchema = z.object({
@@ -146,6 +177,45 @@ const multiTierReferralAwardedSchema = z.object({
 		transactionId: z.string()
 	}))
 });
+/** Mirrors `StampEarnedPayload`. */
+const stampEarnedSchema = z.object({
+	stampProgramId: z.string(),
+	memberId: z.string(),
+	externalId: z.string(),
+	entryId: z.string(),
+	orderRef: z.string(),
+	stamps: z.number().int().positive(),
+	businessDay: z.string(),
+	expiresAt: z.string().optional()
+});
+/** Mirrors `StampReversedPayload`. */
+const stampReversedSchema = z.object({
+	stampProgramId: z.string(),
+	memberId: z.string(),
+	entryId: z.string(),
+	orderRef: z.string(),
+	reversed: z.number().int().nonnegative(),
+	retainedInAwards: z.number().int().nonnegative()
+});
+/** Mirrors `StampAwardIssuedPayload`. */
+const stampAwardIssuedSchema = z.object({
+	stampProgramId: z.string(),
+	memberId: z.string(),
+	externalId: z.string(),
+	awardId: z.string(),
+	sequence: z.number().int().positive(),
+	stampsConsumed: z.number().int().positive(),
+	reward: z.discriminatedUnion("kind", [z.object({
+		kind: z.literal("points"),
+		points: z.number().int().positive(),
+		pointTransactionId: z.string()
+	}), z.object({
+		kind: z.literal("voucher"),
+		voucherProgramId: z.string(),
+		voucherId: z.string(),
+		code: z.string()
+	})])
+});
 const MemberEnrolled = defineLoyaltyEvent({
 	name: LoyaltyEvents.MEMBER_ENROLLED,
 	description: "A new loyalty member was enrolled in a program.",
@@ -181,11 +251,21 @@ const PointsAdjusted = defineLoyaltyEvent({
 	description: "Points were manually adjusted (admin correction / override).",
 	zodSchema: pointsAdjustedSchema
 });
+const PointsReversed = defineLoyaltyEvent({
+	name: LoyaltyEvents.POINTS_REVERSED,
+	description: "Earned points were clawed back because the purchase that earned them was refunded or canceled.",
+	zodSchema: pointsReversedSchema
+});
 const PointsExpired = defineLoyaltyEvent({
 	name: LoyaltyEvents.POINTS_EXPIRED,
 	description: "A batch of points expired across one or more members.",
 	zodSchema: pointsExpiredSchema
 });
+const PointsLotExpired = defineLoyaltyEvent({
+	name: LoyaltyEvents.POINTS_LOT_EXPIRED,
+	description: "One lot of earned points expired — dispatched atomically with the expiry.",
+	zodSchema: pointsLotExpiredSchema
+});
 const PointsExpiringSoon = defineLoyaltyEvent({
 	name: LoyaltyEvents.POINTS_EXPIRING_SOON,
 	description: "Points are approaching their expiry window — host can notify members.",
@@ -266,6 +346,21 @@ const MultiTierReferralAwarded = defineLoyaltyEvent({
 	description: "Ancestor referrers were awarded points via a multi-tier referral chain.",
 	zodSchema: multiTierReferralAwardedSchema
 });
+const StampEarned = defineLoyaltyEvent({
+	name: LoyaltyEvents.STAMP_EARNED,
+	description: "An order earned stamps on a stamp-card program.",
+	zodSchema: stampEarnedSchema
+});
+const StampReversed = defineLoyaltyEvent({
+	name: LoyaltyEvents.STAMP_REVERSED,
+	description: "An undone order's unconsumed stamps were reversed; stamps already awarded are kept.",
+	zodSchema: stampReversedSchema
+});
+const StampAwardIssued = defineLoyaltyEvent({
+	name: LoyaltyEvents.STAMP_AWARD_ISSUED,
+	description: "A full stamp card was exchanged for its reward (points or a voucher).",
+	zodSchema: stampAwardIssuedSchema
+});
 /**
 * Every loyalty event defined in the package — pass to Arc's
 * `EventRegistry`. Hosts wire ONE array; the whole `loyalty.*` namespace
@@ -280,7 +375,9 @@ const loyaltyEventDefinitions = [
 	PointsEarned,
 	PointsRedeemed,
 	PointsAdjusted,
+	PointsReversed,
 	PointsExpired,
+	PointsLotExpired,
 	PointsExpiringSoon,
 	TierUpgraded,
 	TierDowngraded,
@@ -296,7 +393,10 @@ const loyaltyEventDefinitions = [
 	ReferralApproved,
 	ReferralRejected,
 	ReferralRewarded,
-	MultiTierReferralAwarded
+	MultiTierReferralAwarded,
+	StampEarned,
+	StampReversed,
+	StampAwardIssued
 ];
 //#endregion
-export { TierOverrideExpired as C, InProcessLoyaltyBus as E, TierOverrideCleared as S, loyaltyEventDefinitions as T, ReferralRecorded as _, MemberSuspended as a, TierDowngraded as b, PointsEarned as c, PointsRedeemed as d, RedemptionConfirmed as f, ReferralApproved as g, RedemptionReversed as h, MemberReactivated as i, PointsExpired as l, RedemptionReserved as m, MemberDeactivated as n, MultiTierReferralAwarded as o, RedemptionReleased as p, MemberEnrolled as r, PointsAdjusted as s, CampaignAwarded as t, PointsExpiringSoon as u, ReferralRejected as v, TierUpgraded as w, TierGraceStarted as x, ReferralRewarded as y };
+export { loyaltyEventDefinitions as A, StampEarned as C, TierOverrideCleared as D, TierGraceStarted as E, TierOverrideExpired as O, StampAwardIssued as S, TierDowngraded as T, RedemptionReversed as _, MemberSuspended as a, ReferralRejected as b, PointsEarned as c, PointsLotExpired as d, PointsRedeemed as f, RedemptionReserved as g, RedemptionReleased as h, MemberReactivated as i, InProcessLoyaltyBus as j, TierUpgraded as k, PointsExpired as l, RedemptionConfirmed as m, MemberDeactivated as n, MultiTierReferralAwarded as o, PointsReversed as p, MemberEnrolled as r, PointsAdjusted as s, CampaignAwarded as t, PointsExpiringSoon as u, ReferralApproved as v, StampReversed as w, ReferralRewarded as x, ReferralRecorded as y };