@classytic/loyalty 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,169 +1,231 @@
-# Changelog
-
-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.3.0] — 2026-06-13
-
-Stack upgrade to mongokit 3.16 / repo-core 0.6 / primitives 0.7.2 plus
-verified correctness + PACKAGE_RULES compliance fixes. No new features.
-
-### Fixed
-
-- **Stack actually resolves the new floor now (CRITICAL).** The committed
-  lockfile silently served `@classytic/mongokit@3.13.0` +
-  `@classytic/repo-core@0.4.0` despite the `^3.13.3` / `^0.4.2` pins, so the
-  whole test suite ran against the OLD stack. Clean reinstall + peer/dev bumps
-  pin the resolved tree to mongokit **3.16.0**, repo-core **0.6.0**, primitives
-  **0.7.2** (verified with `npm ls`).
-- **§P8 outbox is now session-bound on the transactional verbs.** `earnPoints`,
-  `adjustPoints`, `reserve`, `confirm`, `release`, and `reverseConfirmed`
-  previously dispatched the event AFTER `withTransaction` committed, so
-  `outbox.save` ran OUTSIDE the unit of work — the business doc could commit
-  while the durable event row was lost (or vice-versa). Dispatch now runs
-  INSIDE the transaction (outbox row commits atomically with the write) and the
-  transport publish is deferred to a post-commit flush (`runLoyaltyUnit` +
-  `[PENDING_EVENTS]`), so in-process subscribers never see a state that may roll
-  back. A new integration test asserts the save is session-bound and that a
-  failing `outbox.save` rolls the `$inc` balance write back.
-- **Redemption slot no longer permanently blocked after release.** The
-  `{ ownerType, ownerId }` unique index spanned ALL statuses, so a released /
-  reversed reservation E11000-blocked any retry on the same order (payment
-  retry, cart re-attempt) forever. It is now a **partial** unique index scoped
-  to active statuses (`reserved`, `confirmed`) — terminal states free the slot
-  (PACKAGE_RULES rule 32/38/39). Re-reserve-after-release and second-active-
-  reserve-blocked tests added.
-
-### Added
-
-- **`UnmanagedSessionError` guard (§P8).** When a host passes `ctx.session`
-  (it owns the outer transaction) without attaching a `[PENDING_EVENTS]` queue,
-  dispatch throws BEFORE any side effect instead of publishing / saving outside
-  the host's unit of work (which would leak ghost events on rollback).
-  `PENDING_EVENTS` and `flushPendingLoyaltyEvents` are exported for hosts that
-  manage their own transaction.
-- **Capability boot gate.** `createLoyaltyEngine()` asserts the backend declares
-  the `transactions` capability (repo-core 0.6 / mongokit 3.16+) at engine
-  creation — fail loud at boot rather than with a cryptic driver error on the
-  first transactional call. `allowNonTransactional: true` opts out for local-dev
-  on standalone Mongo. New `LoyaltyCapabilityError`.
-- **Cooperative cancellation in cron loops.** `processExpirations`, `awardBatch`,
-  `cleanupExpired` (redemption + referral), `evaluateAll`, and
-  `sweepExpiredOverrides` check `ctx.signal` via `throwIfAborted` between items —
-  abortable batches; each per-item write is its own committed unit of work, so
-  aborting never rolls back already-processed rows. `LoyaltyContext` gained
-  `signal?: AbortSignal`.
-
-### Changed
-
-- **Domain errors implement `HttpError`** from `@classytic/repo-core/errors`
-  (was a bespoke `httpStatus` shape). Clean break: `httpStatus` → `status`,
-  and codes are now hierarchical + lowercase (`loyalty.<entity>.<problem>`,
-  e.g. `loyalty.member.not_found`, `loyalty.points.insufficient`) so arc
-  serializes them to `ErrorContract` correctly. No deprecation alias.
-- **Peer-dep ranges raised** — `@classytic/mongokit >=3.16.0`,
-  `@classytic/repo-core >=0.6.0` (`>=` style). devDeps bumped to match and
-  primitives devDep pinned to `^0.7.2`.
-- **`exactOptionalPropertyTypes: true`** enabled in tsconfig (mandatory per
-  PACKAGE_RULES Build Hygiene / P10); fixed the three pre-existing optional-vs-
-  undefined violations it surfaced.
-- **tsconfig no longer emits sourcemaps or declaration maps**
-  (`sourceMap: false`, `declarationMap: false`) — both leaked source. tsdown
-  was already correct; tsconfig now matches.
-
-## [0.2.3] — 2026-05-08
-
-### Fixed
-
-- **§P8 dispatch — `outbox.save` failures now propagate.** [src/events/dispatch.ts](src/events/dispatch.ts)
-  previously caught `outbox.save` errors and swallowed them silently. Per
-  PACKAGE_RULES §P8 the outbox row is the durability anchor for the
-  transactional-outbox pattern: if the save fails, the caller's transaction
-  MUST roll back so the business doc and the event row land atomically.
-  Swallowing the failure meant a parent doc could commit while the event
-  vanished, with no relay row to recover from. Fix re-throws after logging.
-  `events.publish` failures continue to be swallowed (correctly, per §P8 —
-  the host's outbox relay re-publishes from the durable row), but now log
-  before swallowing so failures are observable.
-- **`DispatchDeps.logger` field added.** Optional. Both arms of the
-  dispatch helper log through it when set, surfacing failures in the host's
-  observability stack without coupling the package to a specific logger.
-
-### Changed
-
-- **Peer-dep ranges tightened** — `@classytic/mongokit` `>=3.13.3`
-  (was `>=3.13.0`) and `@classytic/repo-core` `>=0.4.2` (was `>=0.4.0`).
-  3.13.3 preserves `errorLabels` on `MongoServerError` so concurrent
-  transactional writes (the `claim()`-based redemption + tier-eval paths)
-  retry correctly under contention; 0.4.2 adds the typed `FindAllOptions`
-  shape with `limit?` for callers that need a bounded non-paginated read.
-
-### Internal
-
-- Replaced 4 `arr.find()!` non-null assertions in [src/index.ts](src/index.ts)
-  + scenario tests with explicit narrowing — TS now proves what the runtime
-  shape already guaranteed.
-
-## [0.2.0]
-
-Structural rewrite on top of the 0.1.0 shape. The public API is now a
-smaller, sharper surface organized around seven subpath exports
-(`/domain/enums`, `/models`, `/repositories`, `/events`, `/types`,
-`/notifications`, plus the root engine factory). Legacy barrel + service
-layers were removed; hosts wire business flows directly against the
-repositories and the engine factory.
-
-### Changed
-
-- **Domain restructure.** Dropped the `src/domain/ports/` + `src/services/`
-  layer in favor of thin repositories that expose exactly the operations
-  hosts need — `earn`, `redeem`, `adjust`, `expire`, referral credit,
-  tier recomputation. No more `earning.service` / `redemption.service` /
-  `tier.service` / `referral.service` / `ledger.service` / `member.service`
-  / `member-guard` indirections; the equivalent logic lives on the
-  repositories where it's naturally atomic.
-- **Events subsystem simplified.** Removed `events/event-bus.ts` +
-  `events/event-types.ts` (both are internal indirection that the engine
-  didn't need). Event payloads are now colocated with the repository
-  that emits them.
-- **Repositories updated to mongokit 3.11 + repo-core 0.2 conventions.**
-  Every repo extends `Repository<T>` directly, uses the tenant plugin via
-  `injectTenant`, and atomic state changes go through CAS guards.
-- **Peer deps** unchanged in spirit, tightened in range:
-  - `@classytic/mongokit >= 3.11`
-  - `@classytic/primitives >= 0.1`
-  - `@classytic/repo-core >= 0.2`
-  - `mongoose >= 9.4`, `zod >= 4`
-- **DevDeps:** `@classytic/primitives` devDep moved from `file:` to `>=0.1.0`
-  (now that primitives ships on npm); all `@classytic/*` dev ranges
-  standardized on `>=`.
-
-### Removed
-
-- `src/services/*` — logic folded into repositories.
-- `src/domain/ports/*` barrels and per-port files — structural types
-  now live with the repositories they describe.
-- Event-bus indirection — repositories emit via the engine's configured
-  transport directly.
-
-### Added
-
-- Subpath export `/notifications` — notification port + built-in
-  lifecycle payloads (tier up/down, points expiring, referral credit).
-- Test restructure — 257 tests across unit + integration projects; the
-  deleted legacy suites were collapsed into focused scenario files that
-  exercise the new public API.
-
-### Peer compatibility
-
-Anyone on 0.1.0 wiring against the old `*.service.ts` modules will need
-to migrate to the repository methods. Signatures are similar — earn /
-redeem / adjust remain the nouns — but the call sites move from
-`services.earning.earnPoints(...)` to `repositories.pointTransaction.earn(...)`
-and similar. No behavior changes in the ledger semantics.
-
-## [0.1.0]
-
-Initial release. Loyalty points, tiers, earning rules, referrals, and
-redemption engine for MongoDB. Tenant-scoped, event-emitting, atomic
-point-ledger with CAS guards.
+# Changelog
+
+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.5.0] — unpublished (2026-07-15)
+
+### Changed — mongokit 3.22 adopted (peer floors: mongokit >=3.22.0, repo-core >=0.13.0, primitives >=0.11.0)
+
+- **Points ledger fence enforced** — `PointTransaction` rows are the
+  balance audit trail; `appendOnlyPlugin` now refuses every mutation
+  path (405 `APPEND_ONLY_VIOLATION`). Previously nothing enforced it —
+  a stray `update()` could rewrite an earn/burn row and silently
+  desync the audit trail from member balances. The expiry sweeper's
+  `expiredAt` stamp is the one engine-owned lifecycle write and passes
+  the audited `bypassAppendOnly` escape.
+- No FSM boilerplate existed (no assert+claim sites, no
+  read-modify-write history) — loyalty was already clean there; this
+  release is the fence + kit refresh (clean registry install, no
+  legacy flags).
+
+## [0.4.0] — addendum (2026-07-05)
+
+### Changed (behavioral)
+
+- **§P8.1 relay-only session guard** — `UnmanagedSessionError` now throws
+  only when a host session arrives with NEITHER a `[PENDING_EVENTS]`
+  queue NOR an outbox. Session + outbox + no queue is legal
+  durable-relay-only mode: the row commits with the host transaction, the
+  relay delivers post-commit, the immediate transport publish is skipped.
+  (Previously the guard was stricter than spec and threw even with an
+  outbox wired.) Aligns loyalty with invoice / catalog / order /
+  purchase / transfer / promo / payrun.
+- **Stack floors raised** — peers `@classytic/mongokit >=3.18.0`,
+  `@classytic/repo-core >=0.7.0`; full suite verified against those
+  versions.
+
+## [0.4.0] — 2026-07-03
+
+### Fixed
+
+- **`evaluateAction` is now idempotent per recurrence key.** The order path
+  dedupes with `${orderId}:${ruleId}`, but the action path (signup /
+  referral / birthday / review) never set an `idempotencyKey` — a retried
+  sweep or double-fired event double-awarded points. When `referenceId` is
+  supplied, each rule award now carries `${referenceId}:${ruleId}`; callers
+  encode the recurrence period in `referenceId` (e.g.
+  `birthday:2026:<memberId>`) and the unique partial index on
+  `idempotencyKey` becomes the authoritative once-only guard.
+- **Action rules honor `conditions` now.** `evaluateAction` skipped
+  `matchesConditions` entirely, silently ignoring admin-authored
+  `tiers` / `dateRange` / `dayOfWeek` on action-type rules ("only gold
+  members get birthday points" did nothing). Conditions now apply;
+  `minOrderAmount` is skipped for actions (no order to measure).
+- **`allowNonTransactional` now actually works at runtime.** The flag
+  silenced the boot capability gate but `MongoUnitOfWork.withTransaction`
+  still opened a real transaction unconditionally — on standalone Mongo
+  every `earnPoints`/`redeem` unit failed with "does not support retryable
+  writes" despite the documented escape hatch. The unit of work now
+  delegates to mongokit's `withTransaction` with `allowFallback` so the
+  transactions-unsupported error re-runs the unit on a plain session
+  (partial-write risk accepted, exactly what the flag opts into).
+- Day arithmetic (tier-downgrade grace expiry, referral rate-limit window)
+  now uses `addDays` from `@classytic/primitives/calendar` — exact 24h × n
+  durations instead of local `setDate`, which shifted with the deploy
+  machine's `TZ` env. Primitives peer bumped to `>=0.9.0`.
+
+## [0.3.0] — 2026-06-13
+
+Stack upgrade to mongokit 3.16 / repo-core 0.6 / primitives 0.7.2 plus
+verified correctness + PACKAGE_RULES compliance fixes. No new features.
+
+### Fixed
+
+- **Stack actually resolves the new floor now (CRITICAL).** The committed
+  lockfile silently served `@classytic/mongokit@3.13.0` +
+  `@classytic/repo-core@0.4.0` despite the `^3.13.3` / `^0.4.2` pins, so the
+  whole test suite ran against the OLD stack. Clean reinstall + peer/dev bumps
+  pin the resolved tree to mongokit **3.16.0**, repo-core **0.6.0**, primitives
+  **0.7.2** (verified with `npm ls`).
+- **§P8 outbox is now session-bound on the transactional verbs.** `earnPoints`,
+  `adjustPoints`, `reserve`, `confirm`, `release`, and `reverseConfirmed`
+  previously dispatched the event AFTER `withTransaction` committed, so
+  `outbox.save` ran OUTSIDE the unit of work — the business doc could commit
+  while the durable event row was lost (or vice-versa). Dispatch now runs
+  INSIDE the transaction (outbox row commits atomically with the write) and the
+  transport publish is deferred to a post-commit flush (`runLoyaltyUnit` +
+  `[PENDING_EVENTS]`), so in-process subscribers never see a state that may roll
+  back. A new integration test asserts the save is session-bound and that a
+  failing `outbox.save` rolls the `$inc` balance write back.
+- **Redemption slot no longer permanently blocked after release.** The
+  `{ ownerType, ownerId }` unique index spanned ALL statuses, so a released /
+  reversed reservation E11000-blocked any retry on the same order (payment
+  retry, cart re-attempt) forever. It is now a **partial** unique index scoped
+  to active statuses (`reserved`, `confirmed`) — terminal states free the slot
+  (PACKAGE_RULES rule 32/38/39). Re-reserve-after-release and second-active-
+  reserve-blocked tests added.
+
+### Added
+
+- **`UnmanagedSessionError` guard (§P8).** When a host passes `ctx.session`
+  (it owns the outer transaction) without attaching a `[PENDING_EVENTS]` queue,
+  dispatch throws BEFORE any side effect instead of publishing / saving outside
+  the host's unit of work (which would leak ghost events on rollback).
+  `PENDING_EVENTS` and `flushPendingLoyaltyEvents` are exported for hosts that
+  manage their own transaction.
+- **Capability boot gate.** `createLoyaltyEngine()` asserts the backend declares
+  the `transactions` capability (repo-core 0.6 / mongokit 3.16+) at engine
+  creation — fail loud at boot rather than with a cryptic driver error on the
+  first transactional call. `allowNonTransactional: true` opts out for local-dev
+  on standalone Mongo. New `LoyaltyCapabilityError`.
+- **Cooperative cancellation in cron loops.** `processExpirations`, `awardBatch`,
+  `cleanupExpired` (redemption + referral), `evaluateAll`, and
+  `sweepExpiredOverrides` check `ctx.signal` via `throwIfAborted` between items —
+  abortable batches; each per-item write is its own committed unit of work, so
+  aborting never rolls back already-processed rows. `LoyaltyContext` gained
+  `signal?: AbortSignal`.
+
+### Changed
+
+- **Domain errors implement `HttpError`** from `@classytic/repo-core/errors`
+  (was a bespoke `httpStatus` shape). Clean break: `httpStatus` → `status`,
+  and codes are now hierarchical + lowercase (`loyalty.<entity>.<problem>`,
+  e.g. `loyalty.member.not_found`, `loyalty.points.insufficient`) so arc
+  serializes them to `ErrorContract` correctly. No deprecation alias.
+- **Peer-dep ranges raised** — `@classytic/mongokit >=3.16.0`,
+  `@classytic/repo-core >=0.6.0` (`>=` style). devDeps bumped to match and
+  primitives devDep pinned to `^0.7.2`.
+- **`exactOptionalPropertyTypes: true`** enabled in tsconfig (mandatory per
+  PACKAGE_RULES Build Hygiene / P10); fixed the three pre-existing optional-vs-
+  undefined violations it surfaced.
+- **tsconfig no longer emits sourcemaps or declaration maps**
+  (`sourceMap: false`, `declarationMap: false`) — both leaked source. tsdown
+  was already correct; tsconfig now matches.
+
+## [0.2.3] — 2026-05-08
+
+### Fixed
+
+- **§P8 dispatch — `outbox.save` failures now propagate.** [src/events/dispatch.ts](src/events/dispatch.ts)
+  previously caught `outbox.save` errors and swallowed them silently. Per
+  PACKAGE_RULES §P8 the outbox row is the durability anchor for the
+  transactional-outbox pattern: if the save fails, the caller's transaction
+  MUST roll back so the business doc and the event row land atomically.
+  Swallowing the failure meant a parent doc could commit while the event
+  vanished, with no relay row to recover from. Fix re-throws after logging.
+  `events.publish` failures continue to be swallowed (correctly, per §P8 —
+  the host's outbox relay re-publishes from the durable row), but now log
+  before swallowing so failures are observable.
+- **`DispatchDeps.logger` field added.** Optional. Both arms of the
+  dispatch helper log through it when set, surfacing failures in the host's
+  observability stack without coupling the package to a specific logger.
+
+### Changed
+
+- **Peer-dep ranges tightened** — `@classytic/mongokit` `>=3.13.3`
+  (was `>=3.13.0`) and `@classytic/repo-core` `>=0.4.2` (was `>=0.4.0`).
+  3.13.3 preserves `errorLabels` on `MongoServerError` so concurrent
+  transactional writes (the `claim()`-based redemption + tier-eval paths)
+  retry correctly under contention; 0.4.2 adds the typed `FindAllOptions`
+  shape with `limit?` for callers that need a bounded non-paginated read.
+
+### Internal
+
+- Replaced 4 `arr.find()!` non-null assertions in [src/index.ts](src/index.ts)
+  + scenario tests with explicit narrowing — TS now proves what the runtime
+  shape already guaranteed.
+
+## [0.2.0]
+
+Structural rewrite on top of the 0.1.0 shape. The public API is now a
+smaller, sharper surface organized around seven subpath exports
+(`/domain/enums`, `/models`, `/repositories`, `/events`, `/types`,
+`/notifications`, plus the root engine factory). Legacy barrel + service
+layers were removed; hosts wire business flows directly against the
+repositories and the engine factory.
+
+### Changed
+
+- **Domain restructure.** Dropped the `src/domain/ports/` + `src/services/`
+  layer in favor of thin repositories that expose exactly the operations
+  hosts need — `earn`, `redeem`, `adjust`, `expire`, referral credit,
+  tier recomputation. No more `earning.service` / `redemption.service` /
+  `tier.service` / `referral.service` / `ledger.service` / `member.service`
+  / `member-guard` indirections; the equivalent logic lives on the
+  repositories where it's naturally atomic.
+- **Events subsystem simplified.** Removed `events/event-bus.ts` +
+  `events/event-types.ts` (both are internal indirection that the engine
+  didn't need). Event payloads are now colocated with the repository
+  that emits them.
+- **Repositories updated to mongokit 3.11 + repo-core 0.2 conventions.**
+  Every repo extends `Repository<T>` directly, uses the tenant plugin via
+  `injectTenant`, and atomic state changes go through CAS guards.
+- **Peer deps** unchanged in spirit, tightened in range:
+  - `@classytic/mongokit >= 3.11`
+  - `@classytic/primitives >= 0.1`
+  - `@classytic/repo-core >= 0.2`
+  - `mongoose >= 9.4`, `zod >= 4`
+- **DevDeps:** `@classytic/primitives` devDep moved from `file:` to `>=0.1.0`
+  (now that primitives ships on npm); all `@classytic/*` dev ranges
+  standardized on `>=`.
+
+### Removed
+
+- `src/services/*` — logic folded into repositories.
+- `src/domain/ports/*` barrels and per-port files — structural types
+  now live with the repositories they describe.
+- Event-bus indirection — repositories emit via the engine's configured
+  transport directly.
+
+### Added
+
+- Subpath export `/notifications` — notification port + built-in
+  lifecycle payloads (tier up/down, points expiring, referral credit).
+- Test restructure — 257 tests across unit + integration projects; the
+  deleted legacy suites were collapsed into focused scenario files that
+  exercise the new public API.
+
+### Peer compatibility
+
+Anyone on 0.1.0 wiring against the old `*.service.ts` modules will need
+to migrate to the repository methods. Signatures are similar — earn /
+redeem / adjust remain the nouns — but the call sites move from
+`services.earning.earnPoints(...)` to `repositories.pointTransaction.earn(...)`
+and similar. No behavior changes in the ledger semantics.
+
+## [0.1.0]
+
+Initial release. Loyalty points, tiers, earning rules, referrals, and
+redemption engine for MongoDB. Tenant-scoped, event-emitting, atomic
+point-ledger with CAS guards.

package/dist/{config-BdSyAdnF.d.mts → config-Dtun1duw.d.mts}

@@ -24,6 +24,17 @@ interface RepositoryPlugins {
 interface LoyaltyConfig {
   mongoose: Connection;
   tenant?: TenantConfig$1 | undefined;
+  /**
+   * IANA timezone name (e.g. `'Asia/Dhaka'`, `'America/New_York'`) used to
+   * evaluate wall-clock rule conditions — currently `EarningConditions.dayOfWeek`
+   * ("2× points on Fridays"). Resolved DST-exact per instant via
+   * `@classytic/primitives/timezone`. Validated at boot: an unknown zone throws
+   * `ValidationError`, never a silent mis-evaluation.
+   *
+   * Omitted → **UTC** (the day boundary is the UTC calendar day). Either way the
+   * result NEVER depends on the deploy machine's `TZ` env. PACKAGE_RULES P12.
+   */
+  timezone?: string | undefined;
   program?: {
     id?: string | undefined;
     conversionRate?: number | undefined;
@@ -140,6 +151,8 @@ interface ResolvedConfig {
     enabled: boolean;
     defaultDays?: number;
   };
+  /** Resolved IANA zone for wall-clock rule evaluation; `undefined` = UTC. */
+  timezone?: string;
   tenant: ResolvedTenant;
 }
 //#endregion

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-CnESLipu.mjs";
+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-D_5Ojc2c.mjs";
 export { CampaignAwarded, CampaignAwardedPayload, DomainEvent, EventHandler, EventTransport, InProcessLoyaltyBus, InProcessLoyaltyBusOptions, LoyaltyEventDefinition, LoyaltyEventMap, LoyaltyEventName, LoyaltyEventPayload, LoyaltyEventPayloadOf, LoyaltyEventSchema, LoyaltyEvents, MemberDeactivated, MemberEnrolled, MemberLifecyclePayload, MemberReactivated, MemberSuspended, MultiTierReferralAwarded, MultiTierReferralAwardedPayload, PointsAdjusted, PointsAdjustedPayload, PointsEarned, PointsEarnedPayload, PointsExpired, PointsExpiredPayload, PointsExpiringSoon, PointsRedeemed, RedemptionConfirmed, RedemptionPayload, RedemptionReleased, RedemptionReserved, RedemptionReversed, RedemptionReversedPayload, ReferralApproved, ReferralPayload, ReferralRecorded, ReferralRejected, ReferralRewarded, TierChangedPayload, TierDowngraded, TierGraceStarted, TierOverrideCleared, TierOverrideExpired, TierOverrideLifecyclePayload, TierUpgraded, createEvent, loyaltyEventDefinitions };

package/dist/{index-CnESLipu.d.mts → index-D_5Ojc2c.d.mts}

@@ -1,4 +1,4 @@
-import { o as LoyaltyContext } from "./index-D20Cn4KB.mjs";
+import { o as LoyaltyContext } from "./index-YSsi4e_G.mjs";
 import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventHandler as EventHandler$1, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
 import { z } from "zod";
 

package/dist/{index-BN96EDac.d.mts → index-Dngaj21_.d.mts}

@@ -1,11 +1,11 @@
 import { i as ReferralStatus, r as RedemptionStatus } from "./index-DMK8a98J.mjs";
-import { S as EarningRule, _ as TierEvaluationBatch, d as EarningResult, f as ExpirationResult, g as TierEvaluation, h as RedemptionValidation, o as LoyaltyContext, v as PointTransaction, x as TierDefinition, y as Member } from "./index-D20Cn4KB.mjs";
+import { S as EarningRule, _ as TierEvaluationBatch, d as EarningResult, f as ExpirationResult, g as TierEvaluation, h as RedemptionValidation, o as LoyaltyContext, v as PointTransaction, x as TierDefinition, y as Member } from "./index-YSsi4e_G.mjs";
 import { t as NotificationAdapter } from "./notification.port-CJ9nXj0k.mjs";
-import { c as ResolvedTenant, o as RepositoryPlugins, s as ResolvedConfig } from "./config-BdSyAdnF.mjs";
+import { c as ResolvedTenant, o as RepositoryPlugins, s as ResolvedConfig } from "./config-Dtun1duw.mjs";
 import { LoyaltyModels } from "./models/index.mjs";
+import { PluginType, Repository } from "@classytic/mongokit";
 import { EventTransport } from "@classytic/primitives/events";
 import { ClientSession, Model } from "mongoose";
-import { PluginType, Repository } from "@classytic/mongokit";
 import { OutboxStore } from "@classytic/primitives/outbox";
 import { ApprovalChain } from "@classytic/primitives/approval";
 
@@ -159,7 +159,19 @@ declare class EarningRuleRepository extends Repository<EarningRule> {
     action: string;
     referenceId?: string;
   }, ctx: LoyaltyContext): Promise<EarningResult>;
+  /**
+   * `orderTotal` is optional — action-type evaluations have no order, so
+   * `minOrderAmount` only applies when a total is supplied (order paths).
+   */
   private matchesConditions;
+  /**
+   * The wall-clock weekday of `instant` in JS `getDay()` convention
+   * (0=Sun … 6=Sat — what `EarningConditions.dayOfWeek` is authored in),
+   * evaluated in the engine's configured `timezone` (DST-exact) or UTC when
+   * unset. NEVER server-local `Date.getDay()`, which shifts with the deploy
+   * machine's `TZ` env (PACKAGE_RULES P12).
+   */
+  private weekday;
   private calculateOrderPoints;
   private calculateCategoryPoints;
   private applyRounding;

package/dist/{index-D20Cn4KB.d.mts → index-YSsi4e_G.d.mts}

@@ -8,6 +8,12 @@ interface EarningConditions {
   categories?: string[];
   tiers?: string[];
   actions?: string[];
+  /**
+   * Days the rule applies, JS `getDay()` convention: 0=Sun … 6=Sat. Empty /
+   * omitted = every day. Evaluated against the wall-clock weekday in the
+   * engine's configured `timezone` (UTC when unset), never the server's local
+   * clock. See `LoyaltyConfig.timezone`.
+   */
   dayOfWeek?: number[];
   dateRange?: {
     start?: Date;

package/dist/index.d.mts

@@ -1,9 +1,9 @@
-import { S as EarningRule, a as EnrollInput, b as MemberBalance, c as UpdateTierInput, d as EarningResult, g as TierEvaluation, h as RedemptionValidation, i as EarnPointsInput, l as BalanceSummary, n as CreateEarningRuleInput, o as LoyaltyContext, r as CreateTierInput, s as UpdateEarningRuleInput, t as AdjustPointsInput, v as PointTransaction, x as TierDefinition, y as Member } from "./index-D20Cn4KB.mjs";
+import { S as EarningRule, a as EnrollInput, b as MemberBalance, c as UpdateTierInput, d as EarningResult, g as TierEvaluation, h as RedemptionValidation, i as EarnPointsInput, l as BalanceSummary, n as CreateEarningRuleInput, o as LoyaltyContext, r as CreateTierInput, s as UpdateEarningRuleInput, t as AdjustPointsInput, v as PointTransaction, x as TierDefinition, y as Member } from "./index-YSsi4e_G.mjs";
 import { t as NotificationAdapter } from "./notification.port-CJ9nXj0k.mjs";
-import { c as ResolvedTenant, n as LoyaltyConfig, r as LoyaltyModelName, s as ResolvedConfig } from "./config-BdSyAdnF.mjs";
-import { A as PointsExpired, B as ReferralRewarded, C as MemberDeactivated, E as MemberSuspended, F as RedemptionReserved, G as TierUpgraded, H as TierGraceStarted, 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, V as TierDowngraded, Y as createEvent, _ as TierChangedPayload, a as LoyaltyEventMap, b as LoyaltyEventDefinition, c as LoyaltyEvents, d as PointsAdjustedPayload, f as PointsEarnedPayload, g as ReferralPayload, j as PointsExpiringSoon, k as PointsEarned, l as MemberLifecyclePayload, m as RedemptionPayload, o as LoyaltyEventName, p as PointsExpiredPayload, q as InProcessLoyaltyBus, s as LoyaltyEventPayload, w as MemberEnrolled, x as LoyaltyEventPayloadOf, z as ReferralRejected } from "./index-CnESLipu.mjs";
+import { c as ResolvedTenant, n as LoyaltyConfig, r as LoyaltyModelName, s as ResolvedConfig } from "./config-Dtun1duw.mjs";
+import { A as PointsExpired, B as ReferralRewarded, C as MemberDeactivated, E as MemberSuspended, F as RedemptionReserved, G as TierUpgraded, H as TierGraceStarted, 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, V as TierDowngraded, Y as createEvent, _ as TierChangedPayload, a as LoyaltyEventMap, b as LoyaltyEventDefinition, c as LoyaltyEvents, d as PointsAdjustedPayload, f as PointsEarnedPayload, g as ReferralPayload, j as PointsExpiringSoon, k as PointsEarned, l as MemberLifecyclePayload, m as RedemptionPayload, o as LoyaltyEventName, p as PointsExpiredPayload, q as InProcessLoyaltyBus, s as LoyaltyEventPayload, w as MemberEnrolled, x as LoyaltyEventPayloadOf, z as ReferralRejected } from "./index-D_5Ojc2c.mjs";
 import { LoyaltyModels } from "./models/index.mjs";
-import { a as ReferralRepository, c as Redemption, d as MemberRepository, f as UnitOfWork, i as TierDefinitionRepository, l as EarningRuleRepository, n as LoyaltyRepositories, o as Referral, s as RedemptionRepository, u as PointTransactionRepository } from "./index-BN96EDac.mjs";
+import { a as ReferralRepository, c as Redemption, d as MemberRepository, f as UnitOfWork, i as TierDefinitionRepository, l as EarningRuleRepository, n as LoyaltyRepositories, o as Referral, s as RedemptionRepository, u as PointTransactionRepository } from "./index-Dngaj21_.mjs";
 import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
 import { OutboxStore } from "@classytic/primitives/outbox";
 import { HttpError } from "@classytic/repo-core/errors";

package/dist/index.mjs

@@ -1,8 +1,10 @@
 import { n as DEFAULT_TENANT_FIELD, r as DEFAULT_TENANT_TYPE } from "./constants-DkQYkOK1.mjs";
-import { C as TenantIsolationError, E as ValidationError, S as SelfReferralError, T as UnmanagedSessionError, _ as RedemptionExpiredError, a as PointTransactionRepository, b as ReferralNotFoundError, c as flushPendingLoyaltyEvents, d as DuplicateReferralError, f as InsufficientPointsError, g as MemberNotFoundError, h as MemberInactiveError, i as RedemptionRepository, l as EarningRuleRepository, m as MemberAlreadyEnrolledError, n as TierDefinitionRepository, o as MemberRepository, p as LoyaltyCapabilityError, r as ReferralRepository, s as PENDING_EVENTS, t as createRepositories, u as CircularReferralError, v as RedemptionNotFoundError, w as TierNotFoundError, x as RuleNotFoundError, y as ReferralLimitExceededError } from "./repositories-C_p8asCn.mjs";
+import { C as TenantIsolationError, E as ValidationError, S as SelfReferralError, T as UnmanagedSessionError, _ as RedemptionExpiredError, a as PointTransactionRepository, b as ReferralNotFoundError, c as flushPendingLoyaltyEvents, d as DuplicateReferralError, f as InsufficientPointsError, g as MemberNotFoundError, h as MemberInactiveError, i as RedemptionRepository, l as EarningRuleRepository, m as MemberAlreadyEnrolledError, n as TierDefinitionRepository, o as MemberRepository, p as LoyaltyCapabilityError, r as ReferralRepository, s as PENDING_EVENTS, t as createRepositories, u as CircularReferralError, v as RedemptionNotFoundError, w as TierNotFoundError, x as RuleNotFoundError, y as ReferralLimitExceededError } from "./repositories-CjWfUlrA.mjs";
 import { E as InProcessLoyaltyBus, T as loyaltyEventDefinitions, _ as ReferralRecorded, a as MemberSuspended, b as TierDowngraded, c as PointsEarned, d as PointsRedeemed, f as RedemptionConfirmed, g as ReferralApproved, i as MemberReactivated, l as PointsExpired, m as RedemptionReserved, n as MemberDeactivated, p as RedemptionReleased, r as MemberEnrolled, s as PointsAdjusted, u as PointsExpiringSoon, v as ReferralRejected, w as TierUpgraded, x as TierGraceStarted, y as ReferralRewarded } from "./events-DN5_p6T0.mjs";
 import { n as createModels } from "./models-Ddh62lgO.mjs";
 import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-C38JA3cU.mjs";
+import { withTransaction } from "@classytic/mongokit";
+import { isValidTimeZone } from "@classytic/primitives/timezone";
 //#region src/index.ts
 function resolveConfig(config) {
 	let tenant;
@@ -48,36 +50,28 @@ function resolveConfig(config) {
 			enabled: config.expiry?.enabled ?? false,
 			...config.expiry?.defaultDays !== void 0 ? { defaultDays: config.expiry.defaultDays } : {}
 		},
+		...config.timezone !== void 0 ? { timezone: config.timezone } : {},
 		tenant
 	};
+	if (config.timezone !== void 0 && !isValidTimeZone(config.timezone)) throw new ValidationError(`Invalid IANA timezone: '${config.timezone}'`);
 	if (resolved.conversionRate <= 0) throw new ValidationError("conversionRate must be positive");
 	if (resolved.referral.codeLength < 4) throw new ValidationError("referral codeLength must be >= 4");
 	if (resolved.redemption.maxRedeemPercent < 0 || resolved.redemption.maxRedeemPercent > 100) throw new ValidationError("maxRedeemPercent must be between 0 and 100");
 	return resolved;
 }
 var MongoUnitOfWork = class {
-	constructor(connection) {
+	constructor(connection, allowFallback) {
 		this.connection = connection;
+		this.allowFallback = allowFallback;
 	}
 	async withTransaction(cb) {
-		const session = await this.connection.startSession();
-		try {
-			const slot = { assigned: false };
-			await session.withTransaction(async () => {
-				slot.value = await cb(session);
-				slot.assigned = true;
-			});
-			if (!slot.assigned) throw new Error("withTransaction: callback did not assign a result");
-			return slot.value;
-		} finally {
-			await session.endSession();
-		}
+		return withTransaction(this.connection, cb, this.allowFallback ? { allowFallback: true } : {});
 	}
 };
 function createLoyaltyEngine(config) {
 	const resolvedConfig = resolveConfig(config);
 	const models = createModels(config.mongoose, resolvedConfig.tenant, config.indexes, config.autoIndex, config.collectionPrefix, config.forceRecreate);
-	const unitOfWork = new MongoUnitOfWork(config.mongoose);
+	const unitOfWork = new MongoUnitOfWork(config.mongoose, config.allowNonTransactional ?? false);
 	const events = config.eventTransport ?? new InProcessLoyaltyBus();
 	const repositories = createRepositories({
 		models,

package/dist/models/index.d.mts

@@ -1,4 +1,4 @@
-import { c as ResolvedTenant, i as ModelName, r as LoyaltyModelName, t as IndexDefinition } from "../config-BdSyAdnF.mjs";
+import { c as ResolvedTenant, i as ModelName, r as LoyaltyModelName, t as IndexDefinition } from "../config-Dtun1duw.mjs";
 import * as _$mongoose from "mongoose";
 import { Connection, Model } from "mongoose";
 
@@ -86,9 +86,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -167,9 +167,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     externalId: string;
     externalType: string;
@@ -298,9 +298,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: {
       createdAt: true;
       updatedAt: false;
@@ -373,9 +373,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     type: "earn" | "redeem" | "adjust" | "expire" | "transfer" | "referral_bonus";
     description: string;
@@ -519,9 +519,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -618,9 +618,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     type: "order" | "action" | "category" | "tier_bonus";
     name: string;
@@ -764,9 +764,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -839,9 +839,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     name: string;
     rank: number;
@@ -972,9 +972,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -1050,9 +1050,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     status: "expired" | "reserved" | "confirmed" | "released" | "reversed";
     memberId: _$mongoose.Types.ObjectId;
@@ -1164,9 +1164,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -1221,9 +1221,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     status: "expired" | "pending" | "approved" | "rejected";
     referralCode: string;

package/dist/repositories/index.d.mts

@@ -1,2 +1,2 @@
-import { a as ReferralRepository, d as MemberRepository, i as TierDefinitionRepository, l as EarningRuleRepository, n as LoyaltyRepositories, r as createRepositories, s as RedemptionRepository, t as CreateRepositoriesInput, u as PointTransactionRepository } from "../index-BN96EDac.mjs";
+import { a as ReferralRepository, d as MemberRepository, i as TierDefinitionRepository, l as EarningRuleRepository, n as LoyaltyRepositories, r as createRepositories, s as RedemptionRepository, t as CreateRepositoriesInput, u as PointTransactionRepository } from "../index-Dngaj21_.mjs";
 export { CreateRepositoriesInput, EarningRuleRepository, LoyaltyRepositories, MemberRepository, PointTransactionRepository, RedemptionRepository, ReferralRepository, TierDefinitionRepository, createRepositories };

package/dist/repositories/index.mjs

@@ -1,2 +1,2 @@
-import { a as PointTransactionRepository, i as RedemptionRepository, l as EarningRuleRepository, n as TierDefinitionRepository, o as MemberRepository, r as ReferralRepository, t as createRepositories } from "../repositories-C_p8asCn.mjs";
+import { a as PointTransactionRepository, i as RedemptionRepository, l as EarningRuleRepository, n as TierDefinitionRepository, o as MemberRepository, r as ReferralRepository, t as createRepositories } from "../repositories-CjWfUlrA.mjs";
 export { EarningRuleRepository, MemberRepository, PointTransactionRepository, RedemptionRepository, ReferralRepository, TierDefinitionRepository, createRepositories };

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

@@ -1,5 +1,7 @@
 import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-C38JA3cU.mjs";
-import { Repository, multiTenantPlugin } from "@classytic/mongokit";
+import { Repository, appendOnlyPlugin, multiTenantPlugin } from "@classytic/mongokit";
+import { localTimeParts } from "@classytic/primitives/timezone";
+import { addDays, isoWeekday } from "@classytic/primitives/calendar";
 import { randomBytes } from "node:crypto";
 import { throwIfAborted } from "@classytic/repo-core/repository";
 //#region src/domain/errors/base.ts
@@ -333,6 +335,7 @@ var EarningRuleRepository = class extends Repository {
 		const transactions = [];
 		let totalPoints = 0;
 		for (const rule of actionRules) {
+			if (!this.matchesConditions(rule, member)) continue;
 			const points = rule.reward.fixedPoints ?? 0;
 			if (points <= 0) continue;
 			const tx = await this.txRepo.earnPoints({
@@ -341,7 +344,10 @@ var EarningRuleRepository = class extends Repository {
 				description: `Action: ${input.action} (${rule.name})`,
 				referenceType: "action",
 				earningRuleId: rule._id,
-				...input.referenceId !== void 0 ? { referenceId: input.referenceId } : {}
+				...input.referenceId !== void 0 ? {
+					referenceId: input.referenceId,
+					idempotencyKey: `${input.referenceId}:${rule._id}`
+				} : {}
 			}, ctx);
 			totalPoints += points;
 			breakdown.push({
@@ -357,10 +363,14 @@ var EarningRuleRepository = class extends Repository {
 			transactions
 		};
 	}
+	/**
+	* `orderTotal` is optional — action-type evaluations have no order, so
+	* `minOrderAmount` only applies when a total is supplied (order paths).
+	*/
 	matchesConditions(rule, member, orderTotal) {
 		const { conditions } = rule;
 		const now = /* @__PURE__ */ new Date();
-		if (conditions.minOrderAmount && orderTotal < conditions.minOrderAmount) return false;
+		if (conditions.minOrderAmount && orderTotal !== void 0 && 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;
@@ -370,10 +380,20 @@ var EarningRuleRepository = class extends Repository {
 			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;
+			if (!conditions.dayOfWeek.includes(this.weekday(now))) return false;
 		}
 		return true;
 	}
+	/**
+	* The wall-clock weekday of `instant` in JS `getDay()` convention
+	* (0=Sun … 6=Sat — what `EarningConditions.dayOfWeek` is authored in),
+	* evaluated in the engine's configured `timezone` (DST-exact) or UTC when
+	* unset. NEVER server-local `Date.getDay()`, which shifts with the deploy
+	* machine's `TZ` env (PACKAGE_RULES P12).
+	*/
+	weekday(instant) {
+		return (this.config.timezone ? localTimeParts(instant, this.config.timezone).isoWeekday : isoWeekday(instant)) % 7;
+	}
 	calculateOrderPoints(rule, orderTotal) {
 		const { reward } = rule;
 		let points = 0;
@@ -410,7 +430,6 @@ var EarningRuleRepository = class extends Repository {
 const PENDING_EVENTS = Symbol.for("@classytic/loyalty:pendingEvents");
 async function dispatchLoyaltyEvent(deps, event, ctx) {
 	const pending = ctx[PENDING_EVENTS];
-	if (ctx.session && !pending) throw new UnmanagedSessionError();
 	if (deps.outbox) try {
 		const saveOptions = {};
 		if (ctx.session !== void 0) saveOptions.session = ctx.session;
@@ -419,11 +438,12 @@ async function dispatchLoyaltyEvent(deps, event, ctx) {
 		deps.logger?.error(`[loyalty] outbox.save failed for ${event.type}:`, err);
 		throw err;
 	}
+	else if (ctx.session && !pending) throw new UnmanagedSessionError();
 	if (pending) {
 		pending.push(event);
 		return;
 	}
-	if (deps.events) try {
+	if (deps.events && !ctx.session) try {
 		await deps.events.publish(event);
 	} catch (err) {
 		deps.logger?.error(`[loyalty] events.publish failed for ${event.type}:`, err);
@@ -689,7 +709,7 @@ var PointTransactionRepository = class extends Repository {
 	unitOfWork;
 	config;
 	constructor(model, plugins = []) {
-		super(model, plugins);
+		super(model, [...plugins, appendOnlyPlugin()]);
 	}
 	/** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
 	async _dispatch(event, ctx) {
@@ -981,7 +1001,8 @@ var PointTransactionRepository = class extends Repository {
 				});
 				await this.update(tx._id, { expiredAt: now }, {
 					session,
-					...tc
+					...tc,
+					bypassAppendOnly: true
 				});
 				await this.memberRepo.updateBalance(tx.memberId, {
 					current: -tx.points,
@@ -1524,8 +1545,7 @@ var ReferralRepository = class extends Repository {
 			...tc
 		});
 		if (reverseReferral && String(reverseReferral.referrerId) === String(referee._id)) throw new CircularReferralError();
-		const periodStart = /* @__PURE__ */ new Date();
-		periodStart.setDate(periodStart.getDate() - this.config.referral.periodDays);
+		const periodStart = addDays(/* @__PURE__ */ new Date(), -this.config.referral.periodDays);
 		if (await this.count({
 			referrerId: referrer._id,
 			createdAt: { $gte: periodStart }
@@ -1956,8 +1976,7 @@ var TierDefinitionRepository = class extends Repository {
 			action: "unchanged"
 		};
 		if (downgrade.gracePeriodDays > 0 && !member.tierExpiresAt) {
-			const graceExpiresAt = /* @__PURE__ */ new Date();
-			graceExpiresAt.setDate(graceExpiresAt.getDate() + downgrade.gracePeriodDays);
+			const graceExpiresAt = addDays(/* @__PURE__ */ new Date(), downgrade.gracePeriodDays);
 			await this.memberRepo.update(memberId, { tierExpiresAt: graceExpiresAt }, {
 				lean: true,
 				...tc

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-D20Cn4KB.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-BdSyAdnF.mjs";
+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 };

package/package.json

@@ -1,116 +1,116 @@
-{
-  "name": "@classytic/loyalty",
-  "version": "0.3.0",
-  "description": "Loyalty points, tiers, earning rules, referrals, and redemption engine for MongoDB",
-  "author": "Classytic",
-  "homepage": "https://www.npmjs.com/package/@classytic/loyalty",
-  "bugs": {
-    "url": "https://github.com/classytic/loyalty/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/classytic/loyalty.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.mts",
-      "default": "./dist/index.mjs"
-    },
-    "./domain/enums": {
-      "types": "./dist/domain/enums/index.d.mts",
-      "default": "./dist/domain/enums/index.mjs"
-    },
-    "./models": {
-      "types": "./dist/models/index.d.mts",
-      "default": "./dist/models/index.mjs"
-    },
-    "./repositories": {
-      "types": "./dist/repositories/index.d.mts",
-      "default": "./dist/repositories/index.mjs"
-    },
-    "./events": {
-      "types": "./dist/events/index.d.mts",
-      "default": "./dist/events/index.mjs"
-    },
-    "./types": {
-      "types": "./dist/types/index.d.mts",
-      "default": "./dist/types/index.mjs"
-    },
-    "./notifications": {
-      "types": "./dist/notifications/index.d.mts",
-      "default": "./dist/notifications/index.mjs"
-    }
-  },
-  "main": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest run --project unit --project integration",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "vitest run --project integration",
-    "test:scenarios": "vitest run --project scenarios",
-    "test:all": "vitest run",
-    "test:watch": "vitest --project unit --project integration",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check src/ tests/",
-    "lint:fix": "biome check --write src/ tests/",
-    "format": "biome format --write src/ tests/",
-    "check": "biome check --write --unsafe src/ tests/",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
-    "push": "classytic-push",
-    "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
-    "release": "npm run push -- main && npm run release:tag && npm publish"
-  },
-  "peerDependencies": {
-    "@classytic/mongokit": ">=3.16.0",
-    "@classytic/primitives": ">=0.5.0",
-    "@classytic/repo-core": ">=0.6.0",
-    "mongoose": ">=9.4.1",
-    "zod": ">=4.0.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.9",
-    "@classytic/dev-tools": "^0.2.0",
-    "@classytic/mongokit": "^3.16.0",
-    "@classytic/primitives": "^0.7.2",
-    "@classytic/repo-core": "^0.6.0",
-    "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "knip": "^6.3.0",
-    "mongodb-memory-server": "^10.2.3",
-    "mongoose": "^9.4.1",
-    "tsdown": "^0.21.5",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0",
-    "zod": "^4.3.6"
-  },
-  "keywords": [
-    "loyalty",
-    "points",
-    "rewards",
-    "tiers",
-    "referral",
-    "membership",
-    "earning-rules",
-    "redemption",
-    "mongodb",
-    "mongoose"
-  ],
-  "license": "MIT"
-}
+{
+  "name": "@classytic/loyalty",
+  "version": "0.5.0",
+  "description": "Loyalty points, tiers, earning rules, referrals, and redemption engine for MongoDB",
+  "author": "Classytic",
+  "homepage": "https://www.npmjs.com/package/@classytic/loyalty",
+  "bugs": {
+    "url": "https://github.com/classytic/loyalty/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/loyalty.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./domain/enums": {
+      "types": "./dist/domain/enums/index.d.mts",
+      "default": "./dist/domain/enums/index.mjs"
+    },
+    "./models": {
+      "types": "./dist/models/index.d.mts",
+      "default": "./dist/models/index.mjs"
+    },
+    "./repositories": {
+      "types": "./dist/repositories/index.d.mts",
+      "default": "./dist/repositories/index.mjs"
+    },
+    "./events": {
+      "types": "./dist/events/index.d.mts",
+      "default": "./dist/events/index.mjs"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.mts",
+      "default": "./dist/types/index.mjs"
+    },
+    "./notifications": {
+      "types": "./dist/notifications/index.d.mts",
+      "default": "./dist/notifications/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --project unit --project integration",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:scenarios": "vitest run --project scenarios",
+    "test:all": "vitest run",
+    "test:watch": "vitest --project unit --project integration",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ tests/",
+    "lint:fix": "biome check --write src/ tests/",
+    "format": "biome format --write src/ tests/",
+    "check": "biome check --write --unsafe src/ tests/",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
+    "push": "classytic-push",
+    "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
+    "release": "npm run push -- main && npm run release:tag && npm publish"
+  },
+  "peerDependencies": {
+    "@classytic/mongokit": ">=3.22.0",
+    "@classytic/primitives": ">=0.11.0",
+    "@classytic/repo-core": ">=0.13.0",
+    "mongoose": ">=9.4.1",
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.9",
+    "@classytic/dev-tools": "^0.2.0",
+    "@classytic/mongokit": "^3.22.0",
+    "@classytic/primitives": "^0.11.0",
+    "@classytic/repo-core": "^0.13.0",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "knip": "^6.3.0",
+    "mongodb-memory-server": "^10.2.3",
+    "mongoose": "^9.4.1",
+    "tsdown": "^0.21.5",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "zod": "^4.3.6"
+  },
+  "keywords": [
+    "loyalty",
+    "points",
+    "rewards",
+    "tiers",
+    "referral",
+    "membership",
+    "earning-rules",
+    "redemption",
+    "mongodb",
+    "mongoose"
+  ],
+  "license": "MIT"
+}