@higher.archi/boe 1.0.28 → 1.0.30

package/src/engines/loyalty/strategy.ts

@@ -0,0 +1,532 @@
+/**
+ * Loyalty Engine Strategy
+ *
+ * Core execution logic for all loyalty strategies:
+ * - earning: compute points from purchase/activity events with category multipliers and promotion stacking
+ * - redemption: process point redemption with balance validation
+ * - tier-evaluation: evaluate members against tier thresholds with upgrade/downgrade detection
+ */
+
+import type { IWorkingMemory } from '../../core';
+
+import type {
+  CompiledLoyaltyRuleSet,
+  CompiledEarningRuleSet,
+  CompiledRedemptionRuleSet,
+  CompiledTierEvaluationRuleSet,
+  LoyaltyOptions,
+  EarningResult,
+  RedemptionResult,
+  TierEvaluationResult,
+  LoyaltyResult,
+  PointTransaction,
+  MemberBalance,
+  MemberTierResult,
+  TierStatus,
+  LoyaltyTierDefinition,
+  PromotionRule,
+  EarningRule
+} from './types';
+
+// ========================================
+// Helpers
+// ========================================
+
+function round(value: number, decimals: number): number {
+  const factor = Math.pow(10, decimals);
+  return Math.round(value * factor) / factor;
+}
+
+function generateTxId(): string {
+  return `tx-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function resolveDotPath(obj: any, path: string): any {
+  const parts = path.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current == null) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+function isPromotionActive(promo: PromotionRule, asOf: Date): boolean {
+  if (promo.startDate && new Date(promo.startDate) > asOf) return false;
+  if (promo.endDate && new Date(promo.endDate) < asOf) return false;
+  return true;
+}
+
+function matchesCategory(promo: PromotionRule, category?: string): boolean {
+  if (!promo.categories || promo.categories.length === 0) return true;
+  if (!category) return false;
+  return promo.categories.includes(category);
+}
+
+// ========================================
+// Strategy Executor
+// ========================================
+
+export class LoyaltyExecutor {
+  run(
+    ruleSet: CompiledLoyaltyRuleSet,
+    wm: IWorkingMemory,
+    ledger: Map<string, MemberBalance>,
+    options: LoyaltyOptions = {}
+  ): LoyaltyResult {
+    switch (ruleSet.strategy) {
+      case 'earning':
+        return this.runEarning(ruleSet, wm, ledger, options);
+      case 'redemption':
+        return this.runRedemption(ruleSet, wm, ledger, options);
+      case 'tier-evaluation':
+        return this.runTierEvaluation(ruleSet, wm, ledger, options);
+      default:
+        throw new Error(`Unknown loyalty strategy: '${(ruleSet as any).strategy}'`);
+    }
+  }
+
+  // ========================================
+  // Earning Strategy
+  // ========================================
+
+  runEarning(
+    ruleSet: CompiledEarningRuleSet,
+    wm: IWorkingMemory,
+    ledger: Map<string, MemberBalance>,
+    options: LoyaltyOptions = {}
+  ): EarningResult {
+    const startTime = performance.now();
+    const asOf = options.asOf ?? new Date();
+    const asOfIso = asOf.toISOString();
+
+    // Get all purchase/activity events from WM
+    const events = wm.getAll();
+    const allTransactions: PointTransaction[] = [];
+    let totalPointsEarned = 0;
+    let totalBonusPoints = 0;
+    const promotionsApplied = new Set<string>();
+    let memberId = '';
+
+    for (const event of events) {
+      const eventMemberId = resolveDotPath(event.data, 'memberId') as string | undefined;
+      if (!eventMemberId) continue;
+      memberId = eventMemberId;
+
+      const amount = (resolveDotPath(event.data, 'amount') as number) ?? 0;
+      const category = resolveDotPath(event.data, 'category') as string | undefined;
+
+      // Find matching earning rules
+      const matchingRules = this.findMatchingEarningRules(ruleSet.earningRules, category);
+      const rule = matchingRules.length > 0 ? matchingRules[0] : null;
+
+      // Calculate base points
+      const baseRate = rule ? rule.baseRate : ruleSet.defaultRate;
+      const multiplier = rule?.multiplier ?? 1;
+      let basePoints = round(amount * baseRate * multiplier, 0);
+      let bonusPoints = rule?.bonusPoints ?? 0;
+
+      // Apply active promotions
+      const activePromos = ruleSet.promotions.filter(
+        p => isPromotionActive(p, asOf) && matchesCategory(p, category)
+      );
+
+      let promoMultiplier = 1;
+      for (const promo of activePromos) {
+        if (promo.multiplier) {
+          promoMultiplier *= promo.multiplier;
+          promotionsApplied.add(promo.id);
+        }
+        if (promo.bonusPoints) {
+          bonusPoints += promo.bonusPoints;
+          promotionsApplied.add(promo.id);
+        }
+      }
+
+      // Apply tier multiplier bonus
+      const balance = this.getOrCreateBalance(ledger, memberId);
+      const tierBonus = this.getTierMultiplierBonus(balance.currentTier, ruleSet.tiers);
+      promoMultiplier *= (1 + tierBonus);
+
+      basePoints = round(basePoints * promoMultiplier, 0);
+      const totalForEvent = basePoints + bonusPoints;
+
+      if (totalForEvent > 0) {
+        const tx: PointTransaction = {
+          id: generateTxId(),
+          memberId,
+          type: 'earn',
+          points: totalForEvent,
+          category,
+          ruleId: rule?.id,
+          timestamp: asOfIso,
+          metadata: { amount, baseRate, multiplier: multiplier * promoMultiplier, bonusPoints }
+        };
+        allTransactions.push(tx);
+        totalPointsEarned += basePoints;
+        totalBonusPoints += bonusPoints;
+
+        // Update ledger
+        balance.totalEarned += totalForEvent;
+        balance.currentBalance += totalForEvent;
+        balance.qualifyingPoints += totalForEvent;
+      }
+    }
+
+    // Update tier if tiers are defined
+    if (memberId && ruleSet.tiers.length > 0) {
+      const balance = this.getOrCreateBalance(ledger, memberId);
+      this.evaluateMemberTier(balance, ruleSet.tiers, asOfIso);
+    }
+
+    const finalBalance = memberId ? this.getOrCreateBalance(ledger, memberId) : { currentBalance: 0 };
+    const executionTimeMs = round((performance.now() - startTime) * 100, 0) / 100;
+
+    return {
+      memberId,
+      transactions: allTransactions,
+      pointsEarned: totalPointsEarned,
+      bonusPointsEarned: totalBonusPoints,
+      promotionsApplied: Array.from(promotionsApplied),
+      newBalance: finalBalance.currentBalance,
+      executionTimeMs
+    };
+  }
+
+  /**
+   * Process a single earning event (for streaming ingest).
+   */
+  earnSingle(
+    eventData: Record<string, any>,
+    ruleSet: CompiledEarningRuleSet,
+    ledger: Map<string, MemberBalance>,
+    asOf: Date = new Date()
+  ): {
+    memberId: string;
+    pointsEarned: number;
+    bonusPointsEarned: number;
+    promotionsApplied: string[];
+    newBalance: number;
+    transactions: PointTransaction[];
+  } {
+    const asOfIso = asOf.toISOString();
+    const memberId = eventData.memberId as string;
+    if (!memberId) {
+      return { memberId: '', pointsEarned: 0, bonusPointsEarned: 0, promotionsApplied: [], newBalance: 0, transactions: [] };
+    }
+
+    const amount = (eventData.amount as number) ?? 0;
+    const category = eventData.category as string | undefined;
+
+    const matchingRules = this.findMatchingEarningRules(ruleSet.earningRules, category);
+    const rule = matchingRules.length > 0 ? matchingRules[0] : null;
+
+    const baseRate = rule ? rule.baseRate : ruleSet.defaultRate;
+    const multiplier = rule?.multiplier ?? 1;
+    let basePoints = round(amount * baseRate * multiplier, 0);
+    let bonusPoints = rule?.bonusPoints ?? 0;
+
+    const promotionsApplied: string[] = [];
+    const activePromos = ruleSet.promotions.filter(
+      p => isPromotionActive(p, asOf) && matchesCategory(p, category)
+    );
+
+    let promoMultiplier = 1;
+    for (const promo of activePromos) {
+      if (promo.multiplier) {
+        promoMultiplier *= promo.multiplier;
+        promotionsApplied.push(promo.id);
+      }
+      if (promo.bonusPoints) {
+        bonusPoints += promo.bonusPoints;
+        promotionsApplied.push(promo.id);
+      }
+    }
+
+    // Apply tier multiplier bonus
+    const balance = this.getOrCreateBalance(ledger, memberId);
+    const tierBonus = this.getTierMultiplierBonus(balance.currentTier, ruleSet.tiers);
+    promoMultiplier *= (1 + tierBonus);
+
+    basePoints = round(basePoints * promoMultiplier, 0);
+    const totalForEvent = basePoints + bonusPoints;
+
+    const transactions: PointTransaction[] = [];
+
+    if (totalForEvent > 0) {
+      const tx: PointTransaction = {
+        id: generateTxId(),
+        memberId,
+        type: 'earn',
+        points: totalForEvent,
+        category,
+        ruleId: rule?.id,
+        timestamp: asOfIso,
+        metadata: { amount, baseRate, multiplier: multiplier * promoMultiplier, bonusPoints }
+      };
+      transactions.push(tx);
+
+      balance.totalEarned += totalForEvent;
+      balance.currentBalance += totalForEvent;
+      balance.qualifyingPoints += totalForEvent;
+    }
+
+    // Update tier
+    if (ruleSet.tiers.length > 0) {
+      this.evaluateMemberTier(balance, ruleSet.tiers, asOfIso);
+    }
+
+    return {
+      memberId,
+      pointsEarned: basePoints,
+      bonusPointsEarned: bonusPoints,
+      promotionsApplied,
+      newBalance: balance.currentBalance,
+      transactions
+    };
+  }
+
+  // ========================================
+  // Redemption Strategy
+  // ========================================
+
+  private runRedemption(
+    ruleSet: CompiledRedemptionRuleSet,
+    wm: IWorkingMemory,
+    ledger: Map<string, MemberBalance>,
+    options: LoyaltyOptions = {}
+  ): RedemptionResult {
+    const startTime = performance.now();
+    const asOf = options.asOf ?? new Date();
+    const asOfIso = asOf.toISOString();
+
+    // Get redemption request from WM
+    const requests = wm.getAll();
+    if (requests.length === 0) {
+      throw new Error('No redemption request found in working memory');
+    }
+
+    const request = requests[0];
+    const memberId = resolveDotPath(request.data, 'memberId') as string;
+    const optionId = resolveDotPath(request.data, 'optionId') as string;
+
+    if (!memberId) throw new Error('Redemption request requires memberId');
+    if (!optionId) throw new Error('Redemption request requires optionId');
+
+    // Find matching redemption option
+    const option = ruleSet.redemptionOptions.find(o => o.id === optionId);
+    if (!option) {
+      throw new Error(`Unknown redemption option: '${optionId}'`);
+    }
+
+    // Validate sufficient balance
+    const balance = this.getOrCreateBalance(ledger, memberId);
+    if (balance.currentBalance < option.pointsRequired) {
+      throw new Error(
+        `Insufficient balance: ${balance.currentBalance} points available, ` +
+        `${option.pointsRequired} required for '${option.id}'`
+      );
+    }
+
+    // Build redemption transaction
+    const tx: PointTransaction = {
+      id: generateTxId(),
+      memberId,
+      type: 'redeem',
+      points: -option.pointsRequired,
+      ruleId: option.id,
+      timestamp: asOfIso,
+      metadata: { optionId: option.id, value: option.value, unit: option.unit }
+    };
+
+    // Update balance
+    balance.totalRedeemed += option.pointsRequired;
+    balance.currentBalance -= option.pointsRequired;
+
+    const executionTimeMs = round((performance.now() - startTime) * 100, 0) / 100;
+
+    return {
+      memberId,
+      redemption: tx,
+      pointsRedeemed: option.pointsRequired,
+      redemptionValue: option.value,
+      remainingBalance: balance.currentBalance,
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Tier Evaluation Strategy
+  // ========================================
+
+  private runTierEvaluation(
+    ruleSet: CompiledTierEvaluationRuleSet,
+    wm: IWorkingMemory,
+    ledger: Map<string, MemberBalance>,
+    _options: LoyaltyOptions = {}
+  ): TierEvaluationResult {
+    const startTime = performance.now();
+
+    // Get all members from WM
+    const memberFacts = wm.getAll();
+    const members: MemberTierResult[] = [];
+    const tierDistribution: Record<string, number> = {};
+
+    // Initialize tier distribution
+    for (const tier of ruleSet.tiers) {
+      tierDistribution[tier.id] = 0;
+    }
+    tierDistribution['none'] = 0;
+
+    for (const fact of memberFacts) {
+      const memberId = resolveDotPath(fact.data, 'memberId') as string;
+      if (!memberId) continue;
+
+      const balance = this.getOrCreateBalance(ledger, memberId);
+
+      // If qualifying points are provided in the fact, use them
+      const factQualifying = resolveDotPath(fact.data, 'qualifyingPoints') as number | undefined;
+      if (factQualifying !== undefined) {
+        balance.qualifyingPoints = factQualifying;
+      }
+
+      const previousTier = balance.currentTier;
+
+      // Find the highest qualifying tier
+      let matchedTier: LoyaltyTierDefinition | undefined;
+      for (let i = ruleSet.tiers.length - 1; i >= 0; i--) {
+        if (balance.qualifyingPoints >= ruleSet.tiers[i].qualifyingThreshold) {
+          matchedTier = ruleSet.tiers[i];
+          break;
+        }
+      }
+
+      const currentTierId = matchedTier?.id ?? 'none';
+      const status = this.resolveTierStatus(balance, matchedTier, previousTier, ruleSet.tiers);
+
+      // Find next tier
+      let nextTier: LoyaltyTierDefinition | undefined;
+      if (matchedTier) {
+        const currentIdx = ruleSet.tiers.findIndex(t => t.id === matchedTier!.id);
+        if (currentIdx < ruleSet.tiers.length - 1) {
+          nextTier = ruleSet.tiers[currentIdx + 1];
+        }
+      } else if (ruleSet.tiers.length > 0) {
+        nextTier = ruleSet.tiers[0];
+      }
+
+      const result: MemberTierResult = {
+        memberId,
+        currentTier: currentTierId,
+        previousTier: previousTier !== currentTierId ? previousTier : undefined,
+        qualifyingPoints: balance.qualifyingPoints,
+        nextTierThreshold: nextTier?.qualifyingThreshold,
+        pointsToNextTier: nextTier
+          ? Math.max(0, nextTier.qualifyingThreshold - balance.qualifyingPoints)
+          : undefined,
+        status,
+        benefits: matchedTier?.benefits ?? []
+      };
+
+      members.push(result);
+      tierDistribution[currentTierId] = (tierDistribution[currentTierId] ?? 0) + 1;
+
+      // Update ledger with new tier
+      balance.currentTier = currentTierId;
+    }
+
+    const executionTimeMs = round((performance.now() - startTime) * 100, 0) / 100;
+
+    return {
+      members,
+      tierDistribution,
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Shared Helpers
+  // ========================================
+
+  private findMatchingEarningRules(rules: EarningRule[], category?: string): EarningRule[] {
+    if (!category) {
+      return rules.filter(r => !r.category);
+    }
+    const categoryMatch = rules.filter(r => r.category === category);
+    if (categoryMatch.length > 0) return categoryMatch;
+    return rules.filter(r => !r.category);
+  }
+
+  getOrCreateBalance(ledger: Map<string, MemberBalance>, memberId: string): MemberBalance {
+    let balance = ledger.get(memberId);
+    if (!balance) {
+      balance = {
+        memberId,
+        totalEarned: 0,
+        totalRedeemed: 0,
+        totalExpired: 0,
+        currentBalance: 0,
+        qualifyingPoints: 0
+      };
+      ledger.set(memberId, balance);
+    }
+    return balance;
+  }
+
+  private evaluateMemberTier(
+    balance: MemberBalance,
+    tiers: LoyaltyTierDefinition[],
+    asOfIso: string
+  ): void {
+    let matchedTier: LoyaltyTierDefinition | undefined;
+    for (let i = tiers.length - 1; i >= 0; i--) {
+      if (balance.qualifyingPoints >= tiers[i].qualifyingThreshold) {
+        matchedTier = tiers[i];
+        break;
+      }
+    }
+
+    const newTierId = matchedTier?.id;
+    if (newTierId && newTierId !== balance.currentTier) {
+      balance.currentTier = newTierId;
+      balance.tierQualifiedAt = asOfIso;
+    }
+  }
+
+  private getTierMultiplierBonus(
+    currentTierId: string | undefined,
+    tiers: LoyaltyTierDefinition[]
+  ): number {
+    if (!currentTierId) return 0;
+    const tier = tiers.find(t => t.id === currentTierId);
+    return tier?.multiplierBonus ?? 0;
+  }
+
+  private resolveTierStatus(
+    balance: MemberBalance,
+    matchedTier: LoyaltyTierDefinition | undefined,
+    previousTier: string | undefined,
+    allTiers: LoyaltyTierDefinition[]
+  ): TierStatus {
+    if (!matchedTier) return 'at-risk';
+
+    // Check if this is a downgrade
+    if (previousTier) {
+      const prevIdx = allTiers.findIndex(t => t.id === previousTier);
+      const currIdx = allTiers.findIndex(t => t.id === matchedTier.id);
+      if (prevIdx > currIdx) return 'downgrade-pending';
+    }
+
+    // Check if near retention threshold
+    if (matchedTier.retentionThreshold !== undefined) {
+      if (balance.qualifyingPoints < matchedTier.retentionThreshold) {
+        return 'at-risk';
+      }
+    }
+
+    return 'qualified';
+  }
+}
+
+/** Singleton instance */
+export const loyaltyStrategy = new LoyaltyExecutor();