@classytic/loyalty 0.6.0 → 0.10.0

package/dist/index-DRrEhE0r.d.mts

@@ -0,0 +1,604 @@
+import { f as TransactionType, o as RuleStatus, r as MemberStatus, s as RuleType, t as EarnSource } from "./index-tjMMmPzU.mjs";
+import { t as NotificationAdapter } from "./notification.port-wY4IKimz.mjs";
+import { ResolvedTenantConfig, TenantConfig } from "@classytic/repo-core/tenant";
+import { EventTransport } from "@classytic/primitives/events";
+import { OperationContext } from "@classytic/primitives/context";
+import { OutboxStore } from "@classytic/primitives/outbox";
+import { ApprovalChain } from "@classytic/primitives/approval";
+//#region src/domain/entities/earning-rule.d.ts
+interface EarningConditions {
+  /**
+   * Minimum order total for the rule to apply — **integer minor units** of the
+   * host's ambient currency (paisa for BDT). `10000` = ৳100. Compared against
+   * `evaluateOrder`'s `orderTotal` (also minor units).
+   */
+  minOrderAmount?: number;
+  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 `LoyaltyShape.timezone`.
+   */
+  dayOfWeek?: number[];
+  dateRange?: {
+    start?: Date;
+    end?: Date;
+  };
+}
+interface EarningReward {
+  /**
+   * Points awarded per `rateBasis` minor units of spend:
+   * `points = pointsPerAmount × (orderTotalMinor / rateBasis)` (rounded once
+   * per `roundingMode`). REQUIRES `rateBasis` — there is no implicit
+   * "per 1 major unit" basis anymore (that ambiguity was the bug).
+   * "5 points per ৳100" = `{ pointsPerAmount: 5, rateBasis: 10000 }`.
+   */
+  pointsPerAmount?: number;
+  /**
+   * RATE: the explicit integer minor-unit basis `pointsPerAmount` is quoted
+   * against (≥ 1). Required whenever `pointsPerAmount` is set.
+   */
+  rateBasis?: number;
+  /**
+   * RATE: integer minor units of spend per single point (≥ 1).
+   * `points = orderTotalMinor / amountPerPoint` (rounded per `roundingMode`).
+   * "1 point per ৳100" = `amountPerPoint: 10000`.
+   */
+  amountPerPoint?: number;
+  fixedPoints?: number;
+  multiplier?: number;
+  roundingMode?: 'floor' | 'round' | 'ceil';
+  maxPointsPerTransaction?: number;
+}
+interface EarningRule {
+  _id: string;
+  programId: string;
+  name: string;
+  description?: string;
+  type: RuleType;
+  status: RuleStatus;
+  priority: number;
+  conditions: EarningConditions;
+  reward: EarningReward;
+  startsAt?: Date;
+  endsAt?: Date;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/domain/entities/tier-definition.d.ts
+interface TierQualification {
+  minLifetimePoints?: number;
+  /**
+   * Minimum lifetime spend — **integer minor units** (paisa for BDT).
+   * Declared for host-side qualification logic only: the in-package tier
+   * evaluation checks lifetime POINTS exclusively and never reads this field.
+   */
+  minLifetimeSpend?: number;
+  evaluationPeriodDays?: number;
+}
+interface TierBenefits {
+  pointsMultiplier?: number;
+  discountPercent?: number;
+  freeShipping?: boolean;
+  customBenefits?: Record<string, unknown>;
+}
+interface TierDowngrade {
+  enabled: boolean;
+  gracePeriodDays: number;
+}
+interface TierDefinition {
+  _id: string;
+  programId: string;
+  name: string;
+  rank: number;
+  qualificationCriteria: TierQualification;
+  benefits: TierBenefits;
+  downgrade: TierDowngrade;
+  color?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/domain/ports/reward-issuer.port.d.ts
+interface StampVoucherRequest {
+  voucherProgramId: string;
+  stampProgramId: string;
+  memberId: string;
+  /** The member's external subject — what the host keys its customers by. */
+  externalId: string;
+  externalType: string;
+  /** Deterministic per award: the SAME key must return the SAME voucher, however often it is retried. */
+  awardKey: string;
+}
+/**
+ * Issues a stamp card's non-points reward. Host-supplied (`LoyaltyRuntime.rewardIssuer`) — loyalty
+ * never imports a promo engine. Required by any program whose reward is a voucher: such a program
+ * is refused at write when none is bound.
+ */
+interface StampRewardIssuer {
+  issueVoucher(request: StampVoucherRequest, ctx: LoyaltyContext): Promise<{
+    voucherId: string;
+    code: string;
+  }>;
+}
+//#endregion
+//#region src/types/config.d.ts
+type LoyaltyModelName = 'Member' | 'PointTransaction' | 'EarningRule' | 'TierDefinition' | 'Redemption' | 'Referral' | 'StampProgram' | 'StampEntry' | 'StampAward';
+type TenantConfig$1 = TenantConfig | boolean;
+/** @deprecated Use `ResolvedTenantConfig` from `@classytic/repo-core/tenant`. */
+type ResolvedTenant = ResolvedTenantConfig;
+interface IndexDefinition {
+  fields: Record<string, 1 | -1>;
+  options?: Record<string, unknown> | undefined;
+}
+type ModelName = 'member' | 'pointTransaction' | 'earningRule' | 'tierDefinition' | 'redemption' | 'referral' | 'stampProgram' | 'stampEntry' | 'stampAward';
+type PluginType = unknown;
+interface RepositoryPlugins {
+  member?: PluginType[] | undefined;
+  pointTransaction?: PluginType[] | undefined;
+  earningRule?: PluginType[] | undefined;
+  tierDefinition?: PluginType[] | undefined;
+  redemption?: PluginType[] | undefined;
+  referral?: PluginType[] | undefined;
+  stampProgram?: PluginType[] | undefined;
+  stampEntry?: PluginType[] | undefined;
+  stampAward?: PluginType[] | undefined;
+}
+interface LoyaltyShape {
+  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;
+    /**
+     * RATE: integer minor units ONE point redeems for (≥ 1) in the host's
+     * ambient currency. `pointValueMinor: 10` = 1 point → 10 paisa
+     * (৳0.10, i.e. the old `conversionRate: 10` "10 points per ৳1").
+     * Replaces `conversionRate` (0.5.x), whose implicit per-1-MAJOR-unit
+     * basis was ambiguous.
+     */
+    pointValueMinor?: number | undefined;
+  } | undefined;
+  redemption?: {
+    minPoints?: number | undefined;
+    /**
+     * Minimum order total eligible for redemption — **integer minor
+     * units** (paisa for BDT). Compared against `validate()`'s
+     * `orderTotal` (also minor units).
+     */
+    minOrderAmount?: number | undefined;
+    maxRedeemPercent?: number | undefined;
+    reservationTtlMinutes?: number | undefined;
+  } | undefined;
+  referral?: {
+    referrerRewardPoints?: number | undefined;
+    refereeRewardPoints?: number | undefined;
+    maxPerPeriod?: number | undefined;
+    periodDays?: number | undefined;
+    requireApproval?: boolean | undefined;
+    codeLength?: number | undefined;
+    /**
+     * Maximum ancestor depth for multi-tier referral rewards. When >= 2,
+     * the direct referrer gets `tierRates[0]` percent of
+     * `referrerRewardPoints`, the 2nd-tier ancestor gets `tierRates[1]`,
+     * etc. Depth 1 = direct referrer (matches single-hop legacy path).
+     * Default: 1 (single-hop, preserves prior behaviour).
+     */
+    maxDepth?: number | undefined;
+    /**
+     * Percent rates (0–100) per depth. `tierRates[0]` is the direct
+     * referrer's share. Omitted depths fall back to 0. Example:
+     * `{ maxDepth: 3, tierRates: [100, 50, 25] }` — direct gets 100%,
+     * grand-referrer 50%, great-grand 25%.
+     */
+    tierRates?: number[] | undefined;
+  } | undefined;
+  expiry?: {
+    enabled?: boolean | undefined;
+    defaultDays?: number | undefined;
+  } | undefined;
+  indexes?: Partial<Record<ModelName, IndexDefinition[]>> | undefined;
+  autoIndex?: boolean | Partial<Record<LoyaltyModelName, boolean>> | undefined;
+  /**
+   * Optional prefix prepended to every physical collection this package
+   * creates (see PACKAGE_RULES.md §20.1). Unset → default names
+   * (`loyalty_members`, `loyalty_point_transactions`, `loyalty_earning_rules`,
+   * `loyalty_tier_definitions`, `loyalty_redemptions`, `loyalty_referrals`).
+   * Model names and `ref:` populate are unaffected.
+   */
+  collectionPrefix?: string | undefined;
+  /**
+   * When true, existing Mongoose models with loyalty's names are deleted
+   * from the connection before re-registering. Hot-reload / test fixtures
+   * only. Default `false` — collision throws mongokit's `ModelCollisionError`.
+   * Hosts that need two loyalty engines should use two Mongoose connections
+   * (`mongoose.createConnection(...)`). See PACKAGE_RULES.md §21.
+   */
+  forceRecreate?: boolean | undefined;
+}
+/** Settings an operator changes while the program runs. Unset = the shape's value. */
+interface LiveProgramSettings {
+  pointValueMinor?: number | undefined;
+  redemption?: {
+    minPoints?: number | undefined;
+    minOrderAmount?: number | undefined;
+    maxRedeemPercent?: number | undefined;
+  } | undefined;
+  /** Days until earned points expire; `null` switches expiry off. */
+  expiryDays?: number | null | undefined;
+}
+interface LoyaltyRuntime {
+  /**
+   * Arc-compatible event transport. When omitted, the engine creates (and
+   * OWNS, so `close()` closes) an `InProcessLoyaltyBus` — a ~60-line structural
+   * match of arc's `MemoryEventTransport`. A host-supplied transport is the
+   * host's to close. See PACKAGE_RULES §13.
+   */
+  eventTransport?: EventTransport | undefined;
+  /**
+   * Host-owned outbox store (PACKAGE_RULES §5.5 + P8). When present, every
+   * domain event is persisted via `outbox.save(event, { session })` **before**
+   * `eventTransport.publish(event)`. `session` is threaded from `ctx.session`
+   * so the outbox row commits atomically with the business write.
+   *
+   * Loyalty does NOT ship a store. Hosts wire arc's `repositoryAsOutboxStore(mongokitRepo)`
+   * over their own `event_outbox` collection, arc's `MemoryOutboxStore`, or any
+   * custom Postgres / Redis / Kafka implementation of the contract. When
+   * omitted, events flow through `eventTransport` only (no durable log).
+   */
+  outbox?: OutboxStore | undefined;
+  notifications?: NotificationAdapter | undefined;
+  plugins?: RepositoryPlugins | undefined;
+  /**
+   * The operator-owned program settings, read PER OPERATION. Supply it when an
+   * admin can change them while the program runs; the shape's values are the
+   * fallback for anything it leaves unset. Without it they are fixed at bind,
+   * so a saved change does nothing until restart.
+   */
+  programSettings?: (() => LiveProgramSettings | Promise<LiveProgramSettings>) | 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;
+  /**
+   * Issues stamp-card voucher rewards. Required by any stamp program whose reward is a voucher —
+   * creating one on an engine bound without it is refused.
+   */
+  rewardIssuer?: StampRewardIssuer | undefined;
+  /**
+   * Where the engine's boot warnings go — today, the `allowNonTransactional`
+   * downgrade notice. Defaults to `console`. A downgrade that carries
+   * partial-write risk on stored value must be VISIBLE, and a host that routes
+   * logs elsewhere would otherwise never see it.
+   */
+  logger?: {
+    warn?(message: string, ...args: unknown[]): void;
+    error?(message: string, ...args: unknown[]): void;
+  } | undefined;
+}
+interface ResolvedConfig {
+  programId: string;
+  /** Integer minor units one point redeems for (≥ 1). See `LoyaltyShape.program.pointValueMinor`. */
+  pointValueMinor: number;
+  redemption: {
+    minPoints: number;
+    /** Integer minor units. */
+    minOrderAmount: number;
+    maxRedeemPercent: number;
+    reservationTtlMinutes: number;
+  };
+  referral: {
+    referrerRewardPoints: number;
+    refereeRewardPoints: number;
+    maxPerPeriod: number;
+    periodDays: number;
+    requireApproval: boolean;
+    codeLength: number;
+    maxDepth: number;
+    tierRates: number[];
+  };
+  expiry: {
+    enabled: boolean;
+    defaultDays?: number;
+  };
+  /** Resolved IANA zone for wall-clock rule evaluation; `undefined` = UTC. */
+  timezone?: string;
+  tenant: ResolvedTenantConfig;
+}
+//#endregion
+//#region src/domain/entities/member.d.ts
+interface MemberBalance {
+  current: number;
+  lifetime: number;
+  redeemed: number;
+  expired: number;
+}
+interface Member {
+  _id: string;
+  programId: string;
+  externalId: string;
+  externalType: string;
+  status: MemberStatus;
+  /** Public loyalty card identifier (e.g., MBR-DHK-00004821-8). Set by the integration layer. */
+  cardId?: string;
+  /** Referral code for the referral system (separate from cardId). Auto-generated on enrollment. */
+  referralCode: string;
+  tier: string | null;
+  tierOverride: string | null;
+  tierOverrideReason?: string;
+  /**
+   * Optional TTL on a manual tier override. When set, `evaluateMember`
+   * treats the override as already cleared once `tierOverrideExpiresAt <=
+   * now`, and a host-scheduled `sweepExpiredOverrides` cron clears the
+   * field + emits a `TIER_OVERRIDE_EXPIRED` audit event.
+   */
+  tierOverrideExpiresAt?: Date;
+  /** Optional upstream referrer for multi-tier referral chains. */
+  referredBy?: string;
+  tierQualifiedAt?: Date;
+  tierExpiresAt?: Date;
+  balance: MemberBalance;
+  enrolledAt: Date;
+  deactivatedAt?: Date;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/domain/entities/point-transaction.d.ts
+interface PointTransaction {
+  _id: string;
+  memberId: string;
+  programId: string;
+  type: TransactionType;
+  points: number;
+  balanceAfter: number;
+  description: string;
+  /** Earn rows: why the points were granted. */
+  source?: EarnSource;
+  /** Minor units one point was worth when this row was written. Absent on rows written before it existed. */
+  pointValueMinor?: number;
+  referenceType?: string;
+  referenceId?: string;
+  idempotencyKey?: string;
+  earningRuleId?: string;
+  expiresAt?: Date;
+  expiredAt?: Date;
+  metadata?: Record<string, unknown>;
+  actorId: string;
+  /**
+   * Optional multi-step approval chain (P7 canonical — same shape as
+   * `@classytic/purchase` / `@classytic/order`). Manual `adjustment` /
+   * `bonus` transactions above a host-defined threshold gate on
+   * `isApproved(approvals)` before the journal entry is committed.
+   * Automatic transactions (earn from purchase, expiry sweeps) skip the
+   * chain entirely — single-tier flows leave this null.
+   */
+  approvals?: ApprovalChain | null;
+  /** Snapshot of the matrix policy id that produced this chain (host-managed). */
+  approvalPolicyId?: string | null;
+  /** Version of the matrix policy at submit time — frozen for audit. */
+  approvalPolicyVersion?: number | null;
+  createdAt: Date;
+}
+//#endregion
+//#region src/types/results.d.ts
+interface BalanceSummary extends MemberBalance {
+  tier: string | null;
+  tierOverride: string | null;
+}
+interface EarningBreakdown {
+  ruleId: string;
+  ruleName: string;
+  points: number;
+}
+interface EarningResult {
+  totalPoints: number;
+  breakdown: EarningBreakdown[];
+  transactions: PointTransaction[];
+}
+interface TierEvaluation {
+  memberId: string;
+  previousTier: string | null;
+  newTier: string | null;
+  action: 'upgraded' | 'downgraded' | 'grace_period' | 'unchanged';
+  graceExpiresAt?: Date;
+}
+interface TierEvaluationBatch {
+  upgraded: number;
+  downgraded: number;
+  unchanged: number;
+}
+interface RedemptionValidation {
+  valid: boolean;
+  error?: string;
+  pointsToRedeem: number;
+  /**
+   * Discount in **integer minor units** (paisa for BDT) — always exactly
+   * `pointsToRedeem × pointValueMinor`.
+   */
+  discountAmount: number;
+  maxAllowedPoints: number;
+}
+/** What the program owes, in points and in integer minor units at the current point value. */
+interface LoyaltyLiabilitySnapshot {
+  spendablePoints: number;
+  /** Held by open reservations — out of the balance, not yet used. */
+  reservedPoints: number;
+  outstandingPoints: number;
+  pointValueMinor: number;
+  valueMinor: number;
+}
+interface ExpirationResult {
+  membersAffected: number;
+  pointsExpired: number;
+  transactionCount: number;
+}
+/**
+ * Outcome of `PointTransactionRepository.reverseEarned` for one member.
+ * `claimed` is what the refund entitles the program to take back; `collected` is
+ * what was actually debited. A non-zero `shortfall` means the member had already
+ * spent those points — reported, never silently written off.
+ */
+interface EarnReversalResult {
+  memberId: string | null;
+  earned: number;
+  /** Points that should stand reversed after this call (`floor(earned × fraction)`). */
+  target: number;
+  alreadyClaimed: number;
+  claimed: number;
+  collected: number;
+  shortfall: number;
+  transactionId: string | null;
+}
+interface PaginatedResult<T> {
+  docs: T[];
+  total: number;
+  page: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+interface ListQuery {
+  page?: number;
+  limit?: number;
+  sort?: Record<string, 1 | -1>;
+}
+//#endregion
+//#region src/types/index.d.ts
+/**
+ * Context passed to every loyalty operation.
+ *
+ * The tenant key is dynamic — if you configured `tenant: { field: 'companyId', contextKey: 'companyId' }`,
+ * pass `{ companyId: '...' }` in the context. The `[key: string]: unknown` index allows this.
+ *
+ * For the default config (`tenant: true` or `tenant: undefined`), pass `organizationId`.
+ * For `tenant: false`, the tenant key is ignored.
+ */
+/**
+ * Extends `@classytic/primitives`' {@link OperationContext} with loyalty-
+ * specific fields. `actorId` is narrowed to a required `string` since every
+ * loyalty mutation is attributed; other primitives fields (`correlationId`,
+ * `traceId`, `requestId`, `session`, `metadata`) flow through unchanged.
+ */
+interface LoyaltyContext extends OperationContext {
+  /** Required for loyalty: who is performing this operation. Narrowed to string. */
+  actorId: string;
+  /** Narrowed from primitives' `IdLike` to string. */
+  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;
+}
+interface EnrollInput {
+  externalId: string;
+  externalType: string;
+  programId?: string;
+  tier?: string;
+  cardId?: string;
+  metadata?: Record<string, unknown>;
+}
+interface EarnPointsInput {
+  memberId: string;
+  points: number;
+  description: string;
+  referenceType?: string;
+  referenceId?: string;
+  earningRuleId?: string;
+  expiresAt?: Date;
+  idempotencyKey?: string;
+  metadata?: Record<string, unknown>;
+}
+interface AdjustPointsInput {
+  memberId: string;
+  points: number;
+  description: string;
+  reason: string;
+  referenceType?: string;
+  referenceId?: string;
+  idempotencyKey?: string;
+  metadata?: Record<string, unknown>;
+}
+interface CreateEarningRuleInput {
+  name: string;
+  type: 'order' | 'action' | 'category' | 'tier_bonus';
+  priority?: number;
+  description?: string;
+  conditions?: EarningConditions;
+  reward: EarningReward;
+  startsAt?: Date | string;
+  endsAt?: Date | string;
+  /**
+   * Loyalty program this rule belongs to.
+   *
+   * Optional for repository-created rules: `EarningRuleRepository.create(...)`
+   * and `createMany(...)` fill this from `LoyaltyShape.program.id`, matching
+   * the default used by `MemberRepository.enroll(...)`. Pass explicitly only
+   * when creating a rule for a different program.
+   */
+  programId?: string;
+  metadata?: Record<string, unknown>;
+}
+interface UpdateEarningRuleInput {
+  name?: string;
+  priority?: number;
+  description?: string;
+  conditions?: EarningConditions;
+  reward?: EarningReward;
+  startsAt?: Date | string;
+  endsAt?: Date | string;
+  metadata?: Record<string, unknown>;
+}
+interface CreateTierInput {
+  name: string;
+  rank: number;
+  qualificationCriteria?: TierQualification;
+  benefits?: TierBenefits;
+  downgrade?: TierDowngrade;
+  color?: string;
+  programId?: string;
+  metadata?: Record<string, unknown>;
+}
+interface UpdateTierInput {
+  name?: string;
+  rank?: number;
+  qualificationCriteria?: TierQualification;
+  benefits?: TierBenefits;
+  downgrade?: TierDowngrade;
+  color?: string;
+  metadata?: Record<string, unknown>;
+}
+//#endregion
+export { RepositoryPlugins as A, IndexDefinition as C, LoyaltyShape as D, LoyaltyRuntime as E, StampVoucherRequest as F, TierDefinition as I, EarningRule as L, ResolvedTenant as M, TenantConfig$1 as N, ModelName as O, StampRewardIssuer as P, MemberBalance as S, LoyaltyModelName as T, RedemptionValidation as _, EnrollInput as a, PointTransaction as b, UpdateTierInput as c, EarningBreakdown as d, EarningResult as f, PaginatedResult as g, LoyaltyLiabilitySnapshot as h, EarnPointsInput as i, ResolvedConfig as j, PluginType as k, BalanceSummary as l, ListQuery as m, CreateEarningRuleInput as n, LoyaltyContext as o, ExpirationResult as p, CreateTierInput as r, UpdateEarningRuleInput as s, AdjustPointsInput as t, EarnReversalResult as u, TierEvaluation as v, LiveProgramSettings as w, Member as x, TierEvaluationBatch as y };