@classytic/loyalty 0.6.0 → 0.10.0

package/dist/{index-CR2k7jQ8.d.mts → index-BvyzKU7R.d.mts}

@@ -1,8 +1,7 @@
-import { i as ReferralStatus, r as RedemptionStatus } from "./index-D_Oe3aDk.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-Cp_sXNpG.mjs";
+import { a as ReferralStatus, i as RedemptionStatus, t as EarnSource } from "./index-tjMMmPzU.mjs";
+import { A as RepositoryPlugins, I as TierDefinition, L as EarningRule, P as StampRewardIssuer, _ as RedemptionValidation, b as PointTransaction, f as EarningResult, h as LoyaltyLiabilitySnapshot, j as ResolvedConfig, o as LoyaltyContext, p as ExpirationResult, u as EarnReversalResult, v as TierEvaluation, x as Member, y as TierEvaluationBatch } from "./index-DRrEhE0r.mjs";
 import { t as NotificationAdapter } from "./notification.port-wY4IKimz.mjs";
-import { c as ResolvedConfig, s as RepositoryPlugins } from "./config-CtkGj3xZ.mjs";
-import { n as LoyaltyModels } from "./index-D6GvuvmF.mjs";
+import { c as StampOrderInput, d as StampProgress, f as StampRecordResult, i as StampAward, n as LoyaltyModels, p as StampReversal, s as StampEntry, u as StampProgram } from "./index-CorB0JL6.mjs";
 import { PluginType, Repository } from "@classytic/mongokit";
 import { ResolvedTenantConfig } from "@classytic/repo-core/tenant";
 import { ClientSession, Model } from "mongoose";
@@ -12,6 +11,74 @@ import { ApprovalChain } from "@classytic/primitives/approval";
 //#region src/domain/ports/unit-of-work.port.d.ts
 interface UnitOfWork {
   withTransaction<T>(callback: (session: ClientSession) => Promise<T>): Promise<T>;
+  /**
+   * This unit of work MAY hand the callback a session with no live transaction.
+   *
+   * True only where the host opted into `allowNonTransactional` — a standalone
+   * mongod accepts the degradation knowingly, and loyalty logs it at boot. The
+   * guard that otherwise refuses a transaction-less session reads this, so an
+   * accepted degradation is not re-refused one layer down. Absent means NO:
+   * an implementation that yields a bare session without saying so is a defect,
+   * and stays one.
+   */
+  readonly allowsNonTransactional?: boolean;
+}
+//#endregion
+//#region src/domain/program-settings.d.ts
+interface EffectiveProgram {
+  pointValueMinor: number;
+  redemption: {
+    minPoints: number;
+    minOrderAmount: number;
+    maxRedeemPercent: number;
+  };
+  expiry: {
+    enabled: boolean;
+    defaultDays?: number;
+  };
+}
+//#endregion
+//#region src/repositories/tier-definition.repository.d.ts
+declare class TierDefinitionRepository extends Repository<TierDefinition> {
+  memberRepo: MemberRepository;
+  events: EventTransport;
+  outbox: OutboxStore | undefined;
+  notifications: NotificationAdapter | null;
+  config: ResolvedConfig;
+  constructor(model: Model<TierDefinition>, plugins?: PluginType[]);
+  /** Auto-inject tenant id from options into doc payload. See MemberRepository. */
+  create(data: Parameters<Repository<TierDefinition>['create']>[0], options?: Parameters<Repository<TierDefinition>['create']>[1]): Promise<TierDefinition>;
+  createMany(docs: Parameters<Repository<TierDefinition>['createMany']>[0], options?: Parameters<Repository<TierDefinition>['createMany']>[1]): Promise<TierDefinition[]>;
+  /** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
+  private _dispatch;
+  /** The highest tier `lifetime` points qualify for in a program, or null. */
+  qualifiedTierName(programId: string, lifetime: number, tc: Record<string, unknown>): Promise<string | null>;
+  /**
+   * Re-place a member by lifetime points. `upgradeOnly` is the earn path: a credit
+   * may promote at once, while a downgrade waits for the periodic evaluation.
+   */
+  evaluateMember(memberId: string, ctx: LoyaltyContext, options?: {
+    upgradeOnly?: boolean;
+  }): Promise<TierEvaluation>;
+  evaluateAll(ctx: LoyaltyContext): Promise<TierEvaluationBatch>;
+  setOverride(memberId: string, tierName: string, reason: string, ctx: LoyaltyContext, options?: {
+    expiresAt?: Date;
+  }): Promise<Member>;
+  clearOverride(memberId: string, ctx: LoyaltyContext): Promise<TierEvaluation>;
+  /**
+   * Sweeps members whose `tierOverrideExpiresAt` is past `now` and clears
+   * the override. Emits `TIER_OVERRIDE_EXPIRED` per member — distinct from
+   * the explicit `TIER_OVERRIDE_CLEARED` event — so audit logs can tell
+   * admin-initiated clears from TTL sweeps.
+   *
+   * Hosts call this on a cron schedule (e.g. hourly). Returns the number
+   * of overrides cleared. No-op when nothing matches.
+   */
+  sweepExpiredOverrides(ctx: LoyaltyContext, now?: Date): Promise<{
+    cleared: number;
+  }>;
+  private applyUpgrade;
+  private applyDowngrade;
 }
 //#endregion
 //#region src/repositories/member.repository.d.ts
@@ -20,6 +87,7 @@ declare class MemberRepository extends Repository<Member> {
   outbox: OutboxStore | undefined;
   notifications: NotificationAdapter | null;
   config: ResolvedConfig;
+  tierRepo: TierDefinitionRepository;
   /** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
   private _dispatch;
   constructor(model: Model<Member>, plugins?: PluginType[]);
@@ -62,7 +130,10 @@ declare class PointTransactionRepository extends Repository<PointTransaction> {
   notifications: NotificationAdapter | null;
   unitOfWork: UnitOfWork;
   config: ResolvedConfig;
+  program: () => Promise<EffectiveProgram>;
   constructor(model: Model<PointTransaction>, plugins?: PluginType[]);
+  /** `now + expiry.defaultDays` when the program expires points, else none. */
+  private defaultExpiry;
   /** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
   private _dispatch;
   private get _dispatchDeps();
@@ -75,6 +146,8 @@ declare class PointTransactionRepository extends Repository<PointTransaction> {
   earnPoints(input: {
     memberId: string;
     points: number;
+    /** Why the points are granted — required, closed set (`EARN_SOURCES`). */
+    source: EarnSource;
     description: string;
     referenceType?: string;
     referenceId?: string;
@@ -127,6 +200,29 @@ declare class PointTransactionRepository extends Repository<PointTransaction> {
     idempotencyKey?: string;
     metadata?: Record<string, unknown>;
   }, ctx: LoyaltyContext): Promise<PointTransaction>;
+  /**
+   * Take back points earned on a reference (an order) once it is refunded or canceled.
+   *
+   * CONVERGES BY STATE. The caller says how much of the purchase is undone
+   * (`fraction`, 1 = all); this reverses `floor(earned × fraction)` minus what earlier
+   * reversals already claimed. A replayed event reverses nothing extra, and the
+   * idempotency key is derived from the target so concurrent callers collide on the
+   * unique index instead of both debiting.
+   *
+   * A member cannot go below zero: points already spent are reported as `shortfall`
+   * on the row and the event. `lifetime` drops by the full claim — tier status must
+   * not keep credit for a sale that was undone.
+   */
+  reverseEarned(input: {
+    referenceType: string;
+    referenceId: string;
+    fraction: number;
+    reason: string;
+  }, ctx: LoyaltyContext): Promise<EarnReversalResult[]>;
+  /** Per member: points earned on the reference, and points earlier reversals already claimed. */
+  private tallyReference;
+  /** Debit one member's `delta` in its own unit of work; a lost race on the target key has converged. */
+  private claimBack;
   processExpirations(ctx: LoyaltyContext): Promise<ExpirationResult>;
 }
 //#endregion
@@ -134,6 +230,7 @@ declare class PointTransactionRepository extends Repository<PointTransaction> {
 declare class EarningRuleRepository extends Repository<EarningRule> {
   memberRepo: MemberRepository;
   txRepo: PointTransactionRepository;
+  tierRepo: TierDefinitionRepository;
   config: ResolvedConfig;
   constructor(model: Model<EarningRule>, plugins?: PluginType[]);
   private applyCreateDefaults;
@@ -162,6 +259,12 @@ declare class EarningRuleRepository extends Repository<EarningRule> {
       quantity: number;
     }>;
   }, ctx: LoyaltyContext): Promise<EarningResult>;
+  /**
+   * The member's tier benefit `benefits.pointsMultiplier`: above 1, the order earns
+   * (m − 1) × what the rules awarded, as its own ledger row. Keyed on the order
+   * alone, so a retry after a tier change cannot award a second bonus.
+   */
+  private tierMultiplierBonus;
   evaluateAction(input: {
     memberId: string;
     action: string;
@@ -254,6 +357,60 @@ interface Redemption {
   updatedAt: Date;
 }
 //#endregion
+//#region src/domain/ports/redemption.port.d.ts
+/**
+ * The points-redemption contract a checkout pipeline drives: reserve before the
+ * order is written, then confirm or release.
+ *
+ * Declared by the kernel that owns redemption so every channel (till, web)
+ * speaks one contract; pipelines `import type` it, adding nothing at runtime.
+ *
+ * The host binds it per request, so there is no context parameter. `reserve`
+ * DEBITS the balance: the caller must `release` on every failure path before the
+ * order exists, or the member loses points to an order that never did.
+ */
+/** A reserved redemption, as a pipeline needs it. */
+interface LoyaltyRedemption {
+  /** Redemption id — needed to confirm or release. */
+  id: string;
+  /** Discount granted, integer MINOR units (same unit as order totals). */
+  discountAmount: number;
+  /** Points actually held — the kernel may cap the request at the redeemable maximum. */
+  pointsReserved?: number;
+}
+interface LoyaltyReserveInput {
+  memberId: string;
+  pointsToRedeem: number;
+  /** Amount the redemption is computed against, integer minor units. */
+  orderTotal: number;
+  ownerType: 'order';
+  /** Stable owner id, so a retry reuses the hold instead of spending twice. */
+  ownerId: string;
+}
+/** Who a redemption is held against. */
+interface RedemptionOwner {
+  ownerType: string;
+  ownerId: string;
+}
+/** The confirm-time handover: the hold moves from the owner it was reserved under to the one it paid for. */
+interface RedemptionOwnerRebind {
+  /** The CURRENT owner — the confirm CAS refuses any other. */
+  from: RedemptionOwner;
+  to: RedemptionOwner;
+}
+interface LoyaltyRedemptionPort {
+  /** The member id behind a customer, or null when they are not enrolled. */
+  findMemberId(customerId: string): Promise<string | null>;
+  reserve(input: LoyaltyReserveInput): Promise<LoyaltyRedemption>;
+  /**
+   * Finalize points already debited at reserve time. `owner`: hand the hold to the
+   * placed order (from the owner it was reserved under); absent ⇒ the reserve-time owner stays.
+   */
+  confirm(redemptionId: string, owner?: RedemptionOwnerRebind): Promise<void>;
+  /** Return the points. MUST be best-effort — never masks the original error. */
+  release(redemptionId: string): Promise<void>;
+}
+//#endregion
 //#region src/repositories/redemption.repository.d.ts
 declare class RedemptionRepository extends Repository<Redemption> {
   memberRepo: MemberRepository;
@@ -263,6 +420,7 @@ declare class RedemptionRepository extends Repository<Redemption> {
   notifications: NotificationAdapter | null;
   unitOfWork: UnitOfWork;
   config: ResolvedConfig;
+  program: () => Promise<EffectiveProgram>;
   constructor(model: Model<Redemption>, plugins?: PluginType[]);
   /** Auto-inject tenant id from options into doc payload. See MemberRepository. */
   create(data: Parameters<Repository<Redemption>['create']>[0], options?: Parameters<Repository<Redemption>['create']>[1]): Promise<Redemption>;
@@ -270,6 +428,12 @@ declare class RedemptionRepository extends Repository<Redemption> {
   /** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
   private _dispatch;
   private get _dispatchDeps();
+  /**
+   * The points the program owes right now: every member's spendable balance plus the points
+   * held by open reservations (a reservation has left the balance but not yet been used), at
+   * the program's current point value. The measure a ledger's liability reconciles against.
+   */
+  outstandingLiability(ctx: LoyaltyContext): Promise<LoyaltyLiabilitySnapshot>;
   /**
    * Atomic compare-and-set status transition.
    *
@@ -289,7 +453,9 @@ declare class RedemptionRepository extends Repository<Redemption> {
    *
    * Anything that throws in here is a real error and must propagate.
    */
-  atomicStatusTransition(id: string, expectedStatus: string, data: Record<string, unknown>, ctx?: Record<string, unknown>): Promise<Redemption | null>;
+  atomicStatusTransition(id: string, expectedStatus: string, data: Record<string, unknown>, ctx?: Record<string, unknown>,
+  /** Extra predicates the CAS must also match (e.g. the current owner of a rebind). */
+  guard?: Record<string, unknown>): Promise<Redemption | null>;
   /**
    * Validates a redemption request. `orderTotal` is an **integer in the
    * host's minor currency unit** (paisa for BDT); the returned
@@ -314,7 +480,20 @@ declare class RedemptionRepository extends Repository<Redemption> {
     ownerId: string;
     expiresAt?: Date;
   }, ctx: LoyaltyContext): Promise<Redemption>;
-  confirm(redemptionId: string, ctx: LoyaltyContext): Promise<Redemption>;
+  /**
+   * `ownerExists: true` skips the reservation-expiry refusal — for a caller that
+   * knows the order was committed, where refusing would return points the customer
+   * already spent as a discount.
+   *
+   * `rebind` hands the hold to the document it paid for (a checkout reserves under its
+   * request key, the placed order owns it), inside the same CAS as the confirm; the CAS
+   * also matches `rebind.from`, so a caller holding only an id cannot re-home another
+   * owner's points. Absent ⇒ the reserve-time owner stays.
+   */
+  confirm(redemptionId: string, ctx: LoyaltyContext, options?: {
+    ownerExists?: boolean;
+    rebind?: RedemptionOwnerRebind;
+  }): Promise<Redemption>;
   release(redemptionId: string, ctx: LoyaltyContext): Promise<Redemption>;
   /**
    * Reverses a confirmed redemption. Credits points back to the member as
@@ -335,6 +514,36 @@ declare class RedemptionRepository extends Repository<Redemption> {
     proportional?: boolean;
     reason?: string;
   }): Promise<Redemption>;
+  /**
+   * Confirm every redemption still `reserved` against an owner that now exists.
+   *
+   * The convergence net for a checkout whose inline confirm failed after the order
+   * was committed: left `reserved`, the expiry sweep would RELEASE it and the
+   * member would keep both the discount and the points. Safe to repeat — a status
+   * CAS, and a redemption another caller already settled is skipped.
+   */
+  confirmForOwner(ownerIds: readonly string[], ctx: LoyaltyContext,
+  /** Hand each confirmed hold to this owner (the order), guarded on the owner it matched under. */
+  options?: {
+    rebindTo?: RedemptionOwner;
+  }): Promise<{
+    confirmed: number;
+  }>;
+  /**
+   * Undo every redemption held against an owner that was refunded or canceled:
+   * confirmed ones credit their points back, reserved ones release their hold.
+   *
+   * `ownerIds` lists every identity the owner was reserved under (a till reserves
+   * against its idempotency key, not the order number). Safe to repeat: each step is
+   * a status CAS, and a redemption another caller already settled is skipped.
+   */
+  undoForOwner(ownerIds: readonly string[], ctx: LoyaltyContext, options: {
+    reason: string;
+  }): Promise<{
+    reversed: number;
+    released: number;
+    pointsReturned: number;
+  }>;
   cleanupExpired(ctx: LoyaltyContext): Promise<number>;
 }
 //#endregion
@@ -401,39 +610,82 @@ declare class ReferralRepository extends Repository<Referral> {
   private requireReferral;
 }
 //#endregion
-//#region src/repositories/tier-definition.repository.d.ts
-declare class TierDefinitionRepository extends Repository<TierDefinition> {
+//#region src/repositories/stamp-award.repository.d.ts
+/** Awards are written only by `stamps.settle`; this repository is their read surface. */
+declare class StampAwardRepository extends Repository<StampAward> {
+  config: ResolvedConfig;
+  constructor(model: Model<StampAward>, plugins?: PluginType[]);
+  create(data: Parameters<Repository<StampAward>['create']>[0], options?: Parameters<Repository<StampAward>['create']>[1]): Promise<StampAward>;
+}
+//#endregion
+//#region src/repositories/stamp-program.repository.d.ts
+/**
+ * Stamp-card programs. Every write is judged whole by `assertStampProgram` — a create, and a patch
+ * merged over the stored program — so no path (HTTP or direct) stores a program that cannot award.
+ */
+declare class StampProgramRepository extends Repository<StampProgram> {
+  config: ResolvedConfig;
+  rewardIssuer: StampRewardIssuer | undefined;
+  constructor(model: Model<StampProgram>, plugins?: PluginType[]);
+  create(data: Parameters<Repository<StampProgram>['create']>[0], options?: Parameters<Repository<StampProgram>['create']>[1]): Promise<StampProgram>;
+  createMany(docs: Parameters<Repository<StampProgram>['createMany']>[0], options?: Parameters<Repository<StampProgram>['createMany']>[1]): Promise<StampProgram[]>;
+  /** A flat patch only: nested `earn` / `reward` are replaced whole, then the result is judged. */
+  update(id: Parameters<Repository<StampProgram>['update']>[0], data: Parameters<Repository<StampProgram>['update']>[1], options?: Parameters<Repository<StampProgram>['update']>[2]): Promise<StampProgram | null>;
+}
+//#endregion
+//#region src/repositories/stamp.repository.d.ts
+/**
+ * Stamp-card ledger: one entry per (program, member, order), consumed oldest-first into awards.
+ *
+ * Every guard is an index or a CAS filter, never an `if` above a write: the order entry, the visit
+ * day, the award sequence and each entry's `consumed` count.
+ */
+declare class StampRepository extends Repository<StampEntry> {
   memberRepo: MemberRepository;
+  txRepo: PointTransactionRepository;
+  programRepo: StampProgramRepository;
+  awardRepo: StampAwardRepository;
   events: EventTransport;
   outbox: OutboxStore | undefined;
-  notifications: NotificationAdapter | null;
+  unitOfWork: UnitOfWork;
   config: ResolvedConfig;
-  constructor(model: Model<TierDefinition>, plugins?: PluginType[]);
-  /** Auto-inject tenant id from options into doc payload. See MemberRepository. */
-  create(data: Parameters<Repository<TierDefinition>['create']>[0], options?: Parameters<Repository<TierDefinition>['create']>[1]): Promise<TierDefinition>;
-  createMany(docs: Parameters<Repository<TierDefinition>['createMany']>[0], options?: Parameters<Repository<TierDefinition>['createMany']>[1]): Promise<TierDefinition[]>;
-  /** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
-  private _dispatch;
-  evaluateMember(memberId: string, ctx: LoyaltyContext): Promise<TierEvaluation>;
-  evaluateAll(ctx: LoyaltyContext): Promise<TierEvaluationBatch>;
-  setOverride(memberId: string, tierName: string, reason: string, ctx: LoyaltyContext, options?: {
-    expiresAt?: Date;
-  }): Promise<Member>;
-  clearOverride(memberId: string, ctx: LoyaltyContext): Promise<TierEvaluation>;
+  rewardIssuer: StampRewardIssuer | undefined;
+  constructor(model: Model<StampEntry>, plugins?: PluginType[]);
+  private get deps();
+  private tc;
+  create(data: Parameters<Repository<StampEntry>['create']>[0], options?: Parameters<Repository<StampEntry>['create']>[1]): Promise<StampEntry>;
   /**
-   * Sweeps members whose `tierOverrideExpiresAt` is past `now` and clears
-   * the override. Emits `TIER_OVERRIDE_EXPIRED` per member — distinct from
-   * the explicit `TIER_OVERRIDE_CLEARED` event — so audit logs can tell
-   * admin-initiated clears from TTL sweeps.
-   *
-   * Hosts call this on a cron schedule (e.g. hourly). Returns the number
-   * of overrides cleared. No-op when nothing matches.
+   * Record one paid order against every active stamp program of the member's loyalty program,
+   * then settle each. Re-recording the same order is a no-op that still settles, so a redelivery
+   * after a crash finishes the award the first delivery started.
    */
-  sweepExpiredOverrides(ctx: LoyaltyContext, now?: Date): Promise<{
-    cleared: number;
-  }>;
-  private applyUpgrade;
-  private applyDowngrade;
+  recordOrder(input: StampOrderInput, ctx: LoyaltyContext): Promise<StampRecordResult[]>;
+  /** Insert the order's entry; `false` when the unique index says it (or its visit day) exists. */
+  private insertEntry;
+  /**
+   * Exchange full cards for rewards until the member's stamps (or `maxRewardsPerMember`) run out.
+   * Voucher awards claimed earlier but not yet issued are resumed first.
+   */
+  settle(stampProgramId: string, memberId: string, ctx: LoyaltyContext): Promise<StampAward[]>;
+  /**
+   * ONE award in ONE unit of work: consume the oldest stamps (CAS per entry), insert the award at
+   * the next sequence (unique — the race fence), and for points credit them in the same
+   * transaction. A voucher award commits as `pending`; its issuance happens after commit.
+   */
+  private claimAward;
+  /** Issue a claimed voucher award through the host port (idempotent on `awardKey`), then mark it. */
+  private issueVoucher;
+  private dispatchAwardIssued;
+  /**
+   * Reverse an undone order's stamps. Policy: unconsumed stamps are removed; stamps already
+   * consumed into an award are kept (`retainedInAwards`, on the result and the event) — never clawed back.
+   */
+  reverseOrder(orderRef: string, ctx: LoyaltyContext): Promise<StampReversal[]>;
+  private reverseEntry;
+  /** The member's card on every active program of their loyalty program. */
+  progress(memberId: string, ctx: LoyaltyContext): Promise<StampProgress[]>;
+  /** Unreversed, unexpired entries with stamps left, oldest first. */
+  private openEntries;
 }
 //#endregion
 //#region src/repositories/index.d.ts
@@ -444,6 +696,10 @@ interface LoyaltyRepositories {
   tierDefinition: TierDefinitionRepository;
   redemption: RedemptionRepository;
   referral: ReferralRepository;
+  stampProgram: StampProgramRepository;
+  /** Stamp-card verbs: `recordOrder`, `settle`, `reverseOrder`, `progress`. */
+  stamps: StampRepository;
+  stampAward: StampAwardRepository;
 }
 interface CreateRepositoriesInput {
   models: LoyaltyModels;
@@ -454,7 +710,11 @@ interface CreateRepositoriesInput {
   outbox?: OutboxStore | undefined;
   notifications: NotificationAdapter | null;
   unitOfWork: UnitOfWork;
+  /** Per-operation program settings — see `createProgramSettings`. */
+  programSettings: () => Promise<EffectiveProgram>;
+  /** Host port for stamp-card voucher rewards. */
+  rewardIssuer?: StampRewardIssuer | undefined;
 }
 declare function createRepositories(input: CreateRepositoriesInput): LoyaltyRepositories;
 //#endregion
-export { ReferralRepository as a, Redemption as c, MemberRepository as d, UnitOfWork as f, TierDefinitionRepository as i, EarningRuleRepository as l, LoyaltyRepositories as n, Referral as o, createRepositories as r, RedemptionRepository as s, CreateRepositoriesInput as t, PointTransactionRepository as u };
+export { PointTransactionRepository as _, StampProgramRepository as a, UnitOfWork as b, Referral as c, LoyaltyRedemptionPort as d, LoyaltyReserveInput as f, EarningRuleRepository as g, Redemption as h, StampRepository as i, RedemptionRepository as l, RedemptionOwnerRebind as m, LoyaltyRepositories as n, StampAwardRepository as o, RedemptionOwner as p, createRepositories as r, ReferralRepository as s, CreateRepositoriesInput as t, LoyaltyRedemption as u, MemberRepository as v, TierDefinitionRepository as y };