@classytic/loyalty 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,120 @@
 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.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

package/README.md

@@ -9,7 +9,8 @@ Framework-agnostic. Works with Fastify (Arc), Express, NestJS, Next.js, or any N
 ```bash
 npm install @classytic/loyalty
 # Peer deps:
-npm install mongoose@^9 @classytic/mongokit@^3.4
+npm install mongoose@^9 zod@^4 \
+  @classytic/mongokit@^3.16 @classytic/repo-core@^0.6 @classytic/primitives@^0.7
 ```
 
 ## Quick Start
@@ -26,15 +27,15 @@ const engine = createLoyaltyEngine({
   referral: { referrerRewardPoints: 200, refereeRewardPoints: 100 },
 });
 
-// 6 services ready to use
-const member = await engine.services.member.enroll(
+// Domain verbs live on the repositories (no service layer — PACKAGE_RULES §1–§3)
+const member = await engine.repositories.member.enroll(
   { externalId: 'cust_1', externalType: 'customer', cardId: 'MBR-001' },
-  { actorId: 'admin' },
+  { actorId: 'admin', organizationId: 'org_1' },
 );
 
-await engine.services.ledger.earnPoints(
+await engine.repositories.pointTransaction.earnPoints(
   { memberId: member._id, points: 500, description: 'Order #123' },
-  { actorId: 'system' },
+  { actorId: 'system', organizationId: 'org_1' },
 );
 ```
 
@@ -42,21 +43,29 @@ await engine.services.ledger.earnPoints(
 
 ```
 createLoyaltyEngine(config)
-  -> models         6 Mongoose models (auto-created, OverwriteModel-safe)
-  -> repositories   6 repos (tenant-scoped CRUD, pagination, atomic transitions)
-  -> services       6 services (the public API)
-  -> events         In-process event bus (or plug your own)
+  -> models         6 Mongoose models (auto-created, collision-safe)
+  -> repositories   6 repos = the public API (tenant-scoped CRUD + domain verbs)
+  -> events         Arc-compatible transport (in-process fallback, or plug your own)
+  -> syncIndexes()  deploy-time index builder
 ```
 
-### Services
+The capability boot gate asserts the backend supports multi-document
+`transactions` (MongoDB replica set / sharded cluster) — the point-mutation
+verbs are transactional. For local-dev on standalone Mongo, pass
+`allowNonTransactional: true` (accepts partial-write risk).
 
-| Service | Purpose |
-|---------|---------|
-| `member` | Enroll, deactivate, reactivate, suspend, getByCardId, getByExternalId |
-| `ledger` | Earn points, adjust points, transaction history, process expirations |
-| `earning` | CRUD earning rules (order, action, category, tier_bonus types) |
-| `tier` | CRUD tier definitions, evaluate members, set/clear overrides |
-| `redemption` | Validate, reserve, confirm, release, cleanup expired reservations |
+### Repositories (the public API)
+
+Domain verbs live on the repositories themselves — there is no service layer
+(PACKAGE_RULES §1–§3). Access via `engine.repositories.<name>`.
+
+| Repository | Purpose |
+|------------|---------|
+| `member` | Enroll, deactivate, reactivate, suspend |
+| `pointTransaction` | Earn points, adjust points, `awardBatch`, process expirations |
+| `earningRule` | CRUD earning rules (order, action, category, tier_bonus); `evaluateOrder` / `evaluateAction` |
+| `tierDefinition` | CRUD tier definitions, evaluate members, set/clear/sweep overrides |
+| `redemption` | Validate, reserve, confirm, release, reverse, cleanup expired reservations |
 | `referral` | Generate codes, record referrals, approve/reject, rate limiting |
 
 ### Key Design Decisions
@@ -148,42 +157,67 @@ as `PlatformConfig.membership.pointsPerAmount` or `amountPerPoint`. See
 
 ## Events
 
+`engine.events` is an arc-compatible `EventTransport` — subscribe glob-style.
+Drop in any arc transport (Memory/Redis/Kafka) via `eventTransport` in config.
+
 ```typescript
 import { LoyaltyEvents } from '@classytic/loyalty/events';
 
-engine.events.on(LoyaltyEvents.POINTS_EARNED, (payload) => { /* sync projection */ });
-engine.events.on(LoyaltyEvents.TIER_UPGRADED, (payload) => { /* notify customer */ });
-engine.events.on(LoyaltyEvents.REFERRAL_REWARDED, (payload) => { /* notify both */ });
+await engine.events.subscribe(LoyaltyEvents.POINTS_EARNED, (e) => { /* sync projection */ });
+await engine.events.subscribe('loyalty.tier.*', (e) => { /* notify customer */ });
+await engine.events.subscribe(LoyaltyEvents.REFERRAL_REWARDED, (e) => { /* notify both */ });
 ```
 
+For durable delivery, wire a host-owned `outbox` (PACKAGE_RULES §5.5 + §P8):
+the engine saves the event row inside the same transaction as the business
+write (atomic), then publishes after commit. Hosts that own the outer
+transaction must attach a `[PENDING_EVENTS]` queue and call
+`flushPendingLoyaltyEvents(transport, queue)` after their commit, or a bare
+`ctx.session` throws `UnmanagedSessionError`.
+
 ## Production Cron Jobs
 
+All cron loops accept `ctx.signal` (an `AbortSignal`) and check it between
+items, so a shutdown / timeout aborts cleanly between committed units of work.
+
 ```typescript
+const ctx = { actorId: 'cron', organizationId: 'org_1', signal: ac.signal };
+
 // Every 5 min — release expired point reservations
-await engine.services.redemption.cleanupExpired({ actorId: 'cron' });
+await engine.repositories.redemption.cleanupExpired(ctx);
 
 // Every hour — expire points past their expiresAt
-await engine.services.ledger.processExpirations({ actorId: 'cron' });
+await engine.repositories.pointTransaction.processExpirations(ctx);
 
 // Every 24h — re-evaluate all member tiers
-await engine.services.tier.evaluateAll({ actorId: 'cron' });
+await engine.repositories.tierDefinition.evaluateAll(ctx);
+
+// Hourly — clear expired tier overrides
+await engine.repositories.tierDefinition.sweepExpiredOverrides(ctx);
 ```
 
 ## Error Codes
 
+All domain errors implement `HttpError` from `@classytic/repo-core/errors`
+(arc serializes them to the canonical `ErrorContract`). Codes are hierarchical
+and lowercase.
+
 | Code | HTTP | When |
 |------|------|------|
-| `MEMBER_NOT_FOUND` | 404 | Member doesn't exist |
-| `MEMBER_ALREADY_ENROLLED` | 409 | Duplicate enrollment |
-| `MEMBER_INACTIVE` | 422 | Operating on inactive member |
-| `INSUFFICIENT_POINTS` | 400 | Not enough points to deduct |
-| `RULE_NOT_FOUND` | 404 | Earning rule doesn't exist |
-| `TIER_NOT_FOUND` | 404 | Tier definition doesn't exist |
-| `REDEMPTION_EXPIRED` | 410 | Reservation TTL exceeded |
-| `DUPLICATE_REFERRAL` | 409 | Referee already referred |
-| `SELF_REFERRAL` | 422 | Referring yourself |
-| `REFERRAL_LIMIT_EXCEEDED` | 429 | Max referrals per period |
-| `TENANT_ISOLATION` | 403 | Cross-tenant access attempt |
+| `loyalty.member.not_found` | 404 | Member doesn't exist |
+| `loyalty.member.already_enrolled` | 409 | Duplicate enrollment |
+| `loyalty.member.inactive` | 422 | Operating on inactive member |
+| `loyalty.points.insufficient` | 400 | Not enough points to deduct |
+| `loyalty.earning_rule.not_found` | 404 | Earning rule doesn't exist |
+| `loyalty.tier.not_found` | 404 | Tier definition doesn't exist |
+| `loyalty.redemption.expired` | 410 | Reservation TTL exceeded |
+| `loyalty.referral.duplicate` | 409 | Referee already referred |
+| `loyalty.referral.self` | 422 | Referring yourself |
+| `loyalty.referral.circular` | 422 | A↔B circular referral |
+| `loyalty.referral.limit_exceeded` | 429 | Max referrals per period |
+| `loyalty.tenant.isolation` | 403 | Missing tenant context |
+| `loyalty.transaction.unmanaged_session` | 400 | `ctx.session` passed without a `[PENDING_EVENTS]` queue |
+| `loyalty.engine.missing_capabilities` | 500 | Backend lacks `transactions` at boot |
 
 ## AI Agent Skill
 

package/dist/{config-96Sl6oNJ.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;
@@ -99,6 +110,16 @@ interface LoyaltyConfig {
   outbox?: OutboxStore | undefined;
   notifications?: NotificationAdapter | undefined;
   plugins?: RepositoryPlugins | undefined;
+  /**
+   * Skip the boot-time capability gate that asserts the backend supports
+   * multi-document `transactions`. Loyalty's point-mutation verbs (earn,
+   * adjust, reserve, confirm, release, reverse, processExpirations) run inside
+   * `withTransaction`; without a replica set those writes are NOT atomic.
+   * Leave `false` (default) in production — set `true` only for local-dev on
+   * standalone Mongo, accepting partial-write risk. See PACKAGE_RULES
+   * "Runtime capabilities".
+   */
+  allowNonTransactional?: boolean | undefined;
 }
 interface ResolvedTenant {
   enabled: boolean;
@@ -130,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-DArT4zkB.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/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-BtZOdiPw.mjs";
-import { n as createEvent, t as LoyaltyEvents } from "../loyalty-events-Cyt9TwX6.mjs";
+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-DN5_p6T0.mjs";
+import { n as createEvent, t as LoyaltyEvents } from "../loyalty-events-C38JA3cU.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 };

package/dist/{events-BtZOdiPw.mjs → events-DN5_p6T0.mjs}

@@ -1,4 +1,4 @@
-import { t as LoyaltyEvents } from "./loyalty-events-Cyt9TwX6.mjs";
+import { t as LoyaltyEvents } from "./loyalty-events-C38JA3cU.mjs";
 import { createEvent, matchEventPattern } from "@classytic/primitives/events";
 import { z } from "zod";
 //#region src/events/in-process-bus.ts

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

@@ -1,4 +1,4 @@
-import { o as LoyaltyContext } from "./index-DWarXsmw.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-Cl-WGBFJ.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-DWarXsmw.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-96Sl6oNJ.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";
 
@@ -65,6 +65,7 @@ declare class PointTransactionRepository extends Repository<PointTransaction> {
   constructor(model: Model<PointTransaction>, plugins?: PluginType[]);
   /** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
   private _dispatch;
+  private get _dispatchDeps();
   /**
    * Auto-inject tenant id from options into doc payload. Matches
    * `@classytic/order` / `@classytic/promo` — see MemberRepository.
@@ -158,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;
@@ -224,6 +237,7 @@ declare class RedemptionRepository extends Repository<Redemption> {
   createMany(docs: Parameters<Repository<Redemption>['createMany']>[0], options?: Parameters<Repository<Redemption>['createMany']>[1]): Promise<Redemption[]>;
   /** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
   private _dispatch;
+  private get _dispatchDeps();
   /**
    * Atomic compare-and-set status transition.
    * Returns null if the current status doesn't match `expectedStatus` (CAS mismatch).
@@ -366,8 +380,8 @@ interface LoyaltyRepositories {
 }
 interface CreateRepositoriesInput {
   models: LoyaltyModels;
-  plugins?: RepositoryPlugins;
-  tenant?: ResolvedTenant;
+  plugins?: RepositoryPlugins | undefined;
+  tenant?: ResolvedTenant | undefined;
   config: ResolvedConfig;
   events: EventTransport;
   outbox?: OutboxStore | undefined;

package/dist/{index-DWarXsmw.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;
@@ -217,6 +223,15 @@ interface LoyaltyContext extends OperationContext {
   organizationId?: string;
   /** Override program ID for multi-program setups. */
   programId?: string;
+  /**
+   * Cooperative cancellation for long-running cron loops (point expiry,
+   * reservation cleanup, tier evaluation, override sweeps, campaign award).
+   * Checked at each loop boundary via `throwIfAborted` — aborting between
+   * iterations never rolls back an already-committed transaction, and each
+   * per-item write is its own unit of work. Threaded to mongokit round-trips
+   * by hosts that pass it; mongokit (3.16+) honours it at every op boundary.
+   */
+  signal?: AbortSignal | undefined;
   /** Dynamic tenant key support — e.g. `{ companyId: '...' }` — when a host
    *  configured a custom `contextKey`. */
   [key: string]: unknown;

package/dist/index.d.mts

@@ -1,11 +1,159 @@
-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-DWarXsmw.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-96Sl6oNJ.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-DArT4zkB.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-Cl-WGBFJ.mjs";
-import { DomainEvent, EventHandler, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
+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";
 
+//#region src/domain/errors/base.d.ts
+/**
+ * Base for every loyalty throwable. Implements `HttpError` from
+ * `@classytic/repo-core/errors` (the org-canonical throwable contract) so arc
+ * catches and serializes them to `ErrorContract` via `toErrorContract()` with
+ * the right HTTP `status` and a stable, machine-readable `code`.
+ *
+ * Codes are hierarchical + lowercase per PACKAGE_RULES ("Errors and wire
+ * envelopes"): `loyalty.<entity>.<problem>`. The `status` field (not the old
+ * `httpStatus`) is what `HttpError` / arc read — a clean break, no alias.
+ */
+declare abstract class LoyaltyError extends Error implements HttpError {
+  abstract readonly code: string;
+  abstract readonly status: number;
+  constructor(message: string);
+  toJSON(): {
+    code: string;
+    message: string;
+    name: string;
+    status: number;
+  };
+}
+//#endregion
+//#region src/domain/errors/domain-errors.d.ts
+declare class InsufficientPointsError extends LoyaltyError {
+  readonly code = "loyalty.points.insufficient";
+  readonly status = 400;
+  constructor(available: number, requested: number);
+}
+declare class MemberNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.member.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class MemberAlreadyEnrolledError extends LoyaltyError {
+  readonly code = "loyalty.member.already_enrolled";
+  readonly status = 409;
+  constructor(externalId: string);
+}
+declare class MemberInactiveError extends LoyaltyError {
+  readonly code = "loyalty.member.inactive";
+  readonly status = 422;
+  constructor(id: string);
+}
+declare class RuleNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.earning_rule.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class TierNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.tier.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class RedemptionNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.redemption.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class RedemptionExpiredError extends LoyaltyError {
+  readonly code = "loyalty.redemption.expired";
+  readonly status = 410;
+  constructor(id: string);
+}
+declare class ReferralNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.referral.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class DuplicateReferralError extends LoyaltyError {
+  readonly code = "loyalty.referral.duplicate";
+  readonly status = 409;
+  constructor(refereeId: string);
+}
+declare class ReferralLimitExceededError extends LoyaltyError {
+  readonly code = "loyalty.referral.limit_exceeded";
+  readonly status = 429;
+  constructor(limit: number, periodDays: number);
+}
+declare class SelfReferralError extends LoyaltyError {
+  readonly code = "loyalty.referral.self";
+  readonly status = 422;
+  constructor();
+}
+declare class CircularReferralError extends LoyaltyError {
+  readonly code = "loyalty.referral.circular";
+  readonly status = 422;
+  constructor();
+}
+declare class ValidationError extends LoyaltyError {
+  readonly code = "loyalty.validation.invalid";
+  readonly status = 400;
+}
+declare class TenantIsolationError extends LoyaltyError {
+  readonly code = "loyalty.tenant.isolation";
+  readonly status = 403;
+  constructor();
+}
+/**
+ * A host passed `ctx.session` (it owns the outer transaction) but did NOT
+ * attach a `[PENDING_EVENTS]` queue. Publishing to in-process subscribers
+ * BEFORE the host's commit would leak ghost events on rollback, and the
+ * outbox save would not be coordinated with the host's unit of work.
+ *
+ * Two safe patterns: (1) let loyalty own the transaction — call the verb
+ * WITHOUT `ctx.session`; or (2) attach a fresh `[PENDING_EVENTS]` array via
+ * `{ ...ctx, [PENDING_EVENTS]: queue }` and call `flushPendingLoyaltyEvents`
+ * after your transaction commits. Both are exported from the package root.
+ */
+declare class UnmanagedSessionError extends LoyaltyError {
+  readonly code = "loyalty.transaction.unmanaged_session";
+  readonly status = 400;
+  constructor();
+}
+/**
+ * The backend doesn't declare the runtime capabilities loyalty's
+ * transactional verbs require (earn / adjust / reserve / confirm / release /
+ * reverse all run inside `withTransaction`). MongoDB must run as a replica set
+ * or sharded cluster. Thrown at engine creation — fail loud at boot, not with
+ * a cryptic driver error on the first transactional call.
+ */
+declare class LoyaltyCapabilityError extends LoyaltyError {
+  readonly code = "loyalty.engine.missing_capabilities";
+  readonly status = 500;
+  constructor(missing: readonly string[]);
+}
+//#endregion
+//#region src/events/dispatch.d.ts
+/**
+ * Internal key under which the post-commit event-publish queue is threaded
+ * through the context. When set, `dispatchLoyaltyEvent` APPENDS to this queue
+ * instead of publishing immediately — the verb that owns the transaction
+ * flushes it after commit. A `Symbol.for` so it never collides with
+ * host-supplied context fields and never appears in the public type.
+ */
+declare const PENDING_EVENTS: unique symbol;
+/**
+ * Drains a queue of deferred events (the one attached under `[PENDING_EVENTS]`)
+ * through the transport, swallowing per-event errors. Called by transactional
+ * verbs AFTER `withTransaction` commits, and exported so hosts that own the
+ * outer transaction can flush after their own commit.
+ */
+declare function flushPendingLoyaltyEvents(events: EventTransport$1 | undefined, queue: DomainEvent$1[], logger?: {
+  error(message: string, ...args: unknown[]): void;
+} | undefined): Promise<void>;
+//#endregion
 //#region src/index.d.ts
 declare function resolveConfig(config: LoyaltyConfig): ResolvedConfig;
 /**
@@ -34,4 +182,4 @@ interface LoyaltyEngine {
 }
 declare function createLoyaltyEngine(config: LoyaltyConfig): LoyaltyEngine;
 //#endregion
-export { type AdjustPointsInput, type BalanceSummary, type CreateEarningRuleInput, type CreateTierInput, type DomainEvent, type EarnPointsInput, type EarningResult, type EarningRule, EarningRuleRepository, type EnrollInput, type EventHandler, type EventTransport, InProcessLoyaltyBus, type InProcessLoyaltyBusOptions, type LoyaltyConfig, type LoyaltyContext, LoyaltyEngine, type LoyaltyEventDefinition, type LoyaltyEventMap, type LoyaltyEventName, type LoyaltyEventPayload, type LoyaltyEventPayloadOf, type LoyaltyEventSchema, LoyaltyEvents, type LoyaltyModelName, type LoyaltyModels, type LoyaltyRepositories, type Member, type MemberBalance, MemberDeactivated, MemberEnrolled, type MemberLifecyclePayload, MemberReactivated, MemberRepository, MemberSuspended, type NotificationAdapter, type PointTransaction, PointTransactionRepository, PointsAdjusted, type PointsAdjustedPayload, PointsEarned, type PointsEarnedPayload, PointsExpired, type PointsExpiredPayload, PointsExpiringSoon, PointsRedeemed, type Redemption, RedemptionConfirmed, type RedemptionPayload, RedemptionReleased, RedemptionRepository, RedemptionReserved, type RedemptionValidation, type Referral, ReferralApproved, type ReferralPayload, ReferralRecorded, ReferralRejected, ReferralRepository, ReferralRewarded, type ResolvedConfig, type ResolvedTenant, type TierChangedPayload, type TierDefinition, TierDefinitionRepository, TierDowngraded, type TierEvaluation, TierGraceStarted, TierUpgraded, type UnitOfWork, type UpdateEarningRuleInput, type UpdateTierInput, createEvent, createLoyaltyEngine, loyaltyEventDefinitions, resolveConfig };
+export { type AdjustPointsInput, type BalanceSummary, CircularReferralError, type CreateEarningRuleInput, type CreateTierInput, type DomainEvent, DuplicateReferralError, type EarnPointsInput, type EarningResult, type EarningRule, EarningRuleRepository, type EnrollInput, type EventHandler, type EventTransport, InProcessLoyaltyBus, type InProcessLoyaltyBusOptions, InsufficientPointsError, LoyaltyCapabilityError, type LoyaltyConfig, type LoyaltyContext, LoyaltyEngine, type LoyaltyEventDefinition, type LoyaltyEventMap, type LoyaltyEventName, type LoyaltyEventPayload, type LoyaltyEventPayloadOf, type LoyaltyEventSchema, LoyaltyEvents, type LoyaltyModelName, type LoyaltyModels, type LoyaltyRepositories, type Member, MemberAlreadyEnrolledError, type MemberBalance, MemberDeactivated, MemberEnrolled, MemberInactiveError, type MemberLifecyclePayload, MemberNotFoundError, MemberReactivated, MemberRepository, MemberSuspended, type NotificationAdapter, PENDING_EVENTS, type PointTransaction, PointTransactionRepository, PointsAdjusted, type PointsAdjustedPayload, PointsEarned, type PointsEarnedPayload, PointsExpired, type PointsExpiredPayload, PointsExpiringSoon, PointsRedeemed, type Redemption, RedemptionConfirmed, RedemptionExpiredError, RedemptionNotFoundError, type RedemptionPayload, RedemptionReleased, RedemptionRepository, RedemptionReserved, type RedemptionValidation, type Referral, ReferralApproved, ReferralLimitExceededError, ReferralNotFoundError, type ReferralPayload, ReferralRecorded, ReferralRejected, ReferralRepository, ReferralRewarded, type ResolvedConfig, type ResolvedTenant, RuleNotFoundError, SelfReferralError, TenantIsolationError, type TierChangedPayload, type TierDefinition, TierDefinitionRepository, TierDowngraded, type TierEvaluation, TierGraceStarted, TierNotFoundError, TierUpgraded, type UnitOfWork, UnmanagedSessionError, type UpdateEarningRuleInput, type UpdateTierInput, ValidationError, createEvent, createLoyaltyEngine, flushPendingLoyaltyEvents, loyaltyEventDefinitions, resolveConfig };