@higher.archi/boe 1.0.28 → 1.0.30

package/src/engines/loyalty/compiler.ts

@@ -0,0 +1,174 @@
+/**
+ * Loyalty Engine Compiler
+ *
+ * Validates loyalty rulesets and resolves defaults.
+ */
+
+import { CompilationError } from '../../core/errors';
+
+import type {
+  LoyaltyRuleSet,
+  CompiledLoyaltyRuleSet,
+  CompiledEarningRuleSet,
+  CompiledRedemptionRuleSet,
+  CompiledTierEvaluationRuleSet
+} from './types';
+
+/**
+ * Compile and validate a loyalty ruleset.
+ */
+export function compileLoyaltyRuleSet(
+  ruleSet: LoyaltyRuleSet
+): CompiledLoyaltyRuleSet {
+  if (!ruleSet.id) {
+    throw new CompilationError('Loyalty ruleset requires an id');
+  }
+
+  if (ruleSet.mode !== 'loyalty') {
+    throw new CompilationError(`Expected mode 'loyalty', got '${ruleSet.mode}'`);
+  }
+
+  switch (ruleSet.strategy) {
+    case 'earning':
+      return compileEarning(ruleSet);
+    case 'redemption':
+      return compileRedemption(ruleSet);
+    case 'tier-evaluation':
+      return compileTierEvaluation(ruleSet);
+    default:
+      throw new CompilationError(`Unknown loyalty strategy: '${(ruleSet as any).strategy}'`);
+  }
+}
+
+function compileEarning(
+  ruleSet: LoyaltyRuleSet & { strategy: 'earning' }
+): CompiledEarningRuleSet {
+  if (!ruleSet.earningRules || ruleSet.earningRules.length === 0) {
+    throw new CompilationError('Earning strategy requires at least one earning rule');
+  }
+
+  // Validate unique rule IDs
+  const ruleIds = new Set<string>();
+  for (const rule of ruleSet.earningRules) {
+    if (!rule.id) {
+      throw new CompilationError('Each earning rule requires an id');
+    }
+    if (ruleIds.has(rule.id)) {
+      throw new CompilationError(`Duplicate earning rule id: '${rule.id}'`);
+    }
+    if (rule.baseRate < 0) {
+      throw new CompilationError(`Earning rule '${rule.id}' baseRate must be non-negative`);
+    }
+    ruleIds.add(rule.id);
+  }
+
+  // Validate tier IDs are unique
+  validateTierIds(ruleSet.tiers);
+
+  // Validate promotions
+  validatePromotions(ruleSet.promotions);
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'loyalty',
+    strategy: 'earning',
+    earningRules: ruleSet.earningRules,
+    defaultRate: ruleSet.defaultRate ?? 1,
+    tiers: ruleSet.tiers ?? [],
+    expirationPolicy: ruleSet.expirationPolicy ?? {},
+    promotions: ruleSet.promotions ?? []
+  };
+}
+
+function compileRedemption(
+  ruleSet: LoyaltyRuleSet & { strategy: 'redemption' }
+): CompiledRedemptionRuleSet {
+  if (!ruleSet.redemptionOptions || ruleSet.redemptionOptions.length === 0) {
+    throw new CompilationError('Redemption strategy requires at least one redemption option');
+  }
+
+  // Validate unique option IDs
+  const optionIds = new Set<string>();
+  for (const option of ruleSet.redemptionOptions) {
+    if (!option.id) {
+      throw new CompilationError('Each redemption option requires an id');
+    }
+    if (optionIds.has(option.id)) {
+      throw new CompilationError(`Duplicate redemption option id: '${option.id}'`);
+    }
+    if (option.pointsRequired <= 0) {
+      throw new CompilationError(`Redemption option '${option.id}' pointsRequired must be positive`);
+    }
+    optionIds.add(option.id);
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'loyalty',
+    strategy: 'redemption',
+    redemptionOptions: ruleSet.redemptionOptions,
+    tiers: ruleSet.tiers ?? [],
+    expirationPolicy: ruleSet.expirationPolicy ?? {},
+    promotions: ruleSet.promotions ?? []
+  };
+}
+
+function compileTierEvaluation(
+  ruleSet: LoyaltyRuleSet & { strategy: 'tier-evaluation' }
+): CompiledTierEvaluationRuleSet {
+  if (!ruleSet.tiers || ruleSet.tiers.length === 0) {
+    throw new CompilationError('Tier-evaluation strategy requires at least one tier definition');
+  }
+
+  // Validate tier IDs are unique
+  validateTierIds(ruleSet.tiers);
+
+  // Validate tiers are sorted by threshold ascending
+  for (let i = 1; i < ruleSet.tiers.length; i++) {
+    if (ruleSet.tiers[i].qualifyingThreshold < ruleSet.tiers[i - 1].qualifyingThreshold) {
+      throw new CompilationError(
+        `Tier '${ruleSet.tiers[i].id}' threshold (${ruleSet.tiers[i].qualifyingThreshold}) ` +
+        `is less than previous tier '${ruleSet.tiers[i - 1].id}' (${ruleSet.tiers[i - 1].qualifyingThreshold}). ` +
+        `Tiers must be ordered by ascending threshold.`
+      );
+    }
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'loyalty',
+    strategy: 'tier-evaluation',
+    evaluationPeriod: ruleSet.evaluationPeriod ?? 'rolling-12-months',
+    tiers: ruleSet.tiers,
+    expirationPolicy: ruleSet.expirationPolicy ?? {},
+    promotions: ruleSet.promotions ?? []
+  };
+}
+
+function validateTierIds(tiers?: { id: string }[]): void {
+  if (!tiers) return;
+  const tierIds = new Set<string>();
+  for (const tier of tiers) {
+    if (tierIds.has(tier.id)) {
+      throw new CompilationError(`Duplicate tier id: '${tier.id}'`);
+    }
+    tierIds.add(tier.id);
+  }
+}
+
+function validatePromotions(promotions?: { id: string }[]): void {
+  if (!promotions) return;
+  const promoIds = new Set<string>();
+  for (const promo of promotions) {
+    if (!promo.id) {
+      throw new CompilationError('Each promotion requires an id');
+    }
+    if (promoIds.has(promo.id)) {
+      throw new CompilationError(`Duplicate promotion id: '${promo.id}'`);
+    }
+    promoIds.add(promo.id);
+  }
+}

package/src/engines/loyalty/engine.ts

@@ -0,0 +1,174 @@
+/**
+ * Loyalty Engine
+ *
+ * Point ledger engine that manages earning rules with category multipliers,
+ * point transactions, tier-qualified balances, and promotion stacking.
+ * Unlike other BOE engines, the Loyalty engine maintains a running balance
+ * ledger across operations.
+ *
+ * @example
+ * ```typescript
+ * const engine = new LoyaltyEngine();
+ * const compiled = compileLoyaltyRuleSet({ ... });
+ *
+ * // Stream purchases as they arrive
+ * const r1 = engine.ingest({ memberId: 'M001', amount: 250, category: 'dining' }, compiled);
+ * // r1.pointsEarned: 500, r1.newBalance: 500
+ *
+ * engine.getBalance('M001'); // { currentBalance: 500, ... }
+ * ```
+ */
+
+import {
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import type {
+  CompiledLoyaltyRuleSet,
+  CompiledEarningRuleSet,
+  LoyaltyOptions,
+  LoyaltyResult,
+  LoyaltyIngestResult,
+  MemberBalance
+} from './types';
+
+import { LoyaltyExecutor } from './strategy';
+
+export class LoyaltyEngine {
+  private wm: WorkingMemory;
+  private strategy: LoyaltyExecutor;
+  private _ledger: Map<string, MemberBalance> = new Map();
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new LoyaltyExecutor();
+  }
+
+  // ========================================
+  // IWorkingMemory Implementation
+  // ========================================
+
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    return this.wm.add(input);
+  }
+
+  remove(factId: string): Fact | undefined {
+    return this.wm.remove(factId);
+  }
+
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    return this.wm.update(input);
+  }
+
+  get(factId: string): Fact | undefined {
+    return this.wm.get(factId);
+  }
+
+  getByType(type: string): Fact[] {
+    return this.wm.getByType(type);
+  }
+
+  getAll(): Fact[] {
+    return this.wm.getAll();
+  }
+
+  has(factId: string): boolean {
+    return this.wm.has(factId);
+  }
+
+  size(): number {
+    return this.wm.size();
+  }
+
+  clear(): void {
+    this.wm.clear();
+  }
+
+  getChanges(): FactChange[] {
+    return this.wm.getChanges();
+  }
+
+  clearChanges(): void {
+    this.wm.clearChanges();
+  }
+
+  // ========================================
+  // Engine Execution
+  // ========================================
+
+  /**
+   * Execute a loyalty ruleset against all facts in working memory.
+   *
+   * @param ruleSet - Compiled loyalty ruleset
+   * @param options - Runtime options (asOf date)
+   * @returns Loyalty result (earning, redemption, or tier-evaluation)
+   */
+  execute(
+    ruleSet: CompiledLoyaltyRuleSet,
+    options: LoyaltyOptions = {}
+  ): LoyaltyResult {
+    return this.strategy.run(ruleSet, this.wm, this._ledger, options);
+  }
+
+  // ========================================
+  // Streaming Ingest
+  // ========================================
+
+  /**
+   * Process a single purchase/activity event incrementally.
+   *
+   * Each call computes points earned, updates the internal ledger,
+   * evaluates tier status, and returns the result with the new balance.
+   * Only works with earning strategy rulesets.
+   *
+   * @param eventData - Event data with memberId, amount, and optional category
+   * @param ruleSet - Compiled earning ruleset
+   * @param asOf - Reference time (default: now)
+   * @returns Earning result with updated balance
+   */
+  ingest(
+    eventData: Record<string, any>,
+    ruleSet: CompiledEarningRuleSet,
+    asOf: Date = new Date()
+  ): LoyaltyIngestResult {
+    return this.strategy.earnSingle(eventData, ruleSet, this._ledger, asOf);
+  }
+
+  // ========================================
+  // Ledger Operations
+  // ========================================
+
+  /**
+   * Get the current balance for a member.
+   * Returns undefined if the member has no transactions.
+   */
+  getBalance(memberId: string): MemberBalance | undefined {
+    return this._ledger.get(memberId);
+  }
+
+  /**
+   * Get the full ledger state (all member balances).
+   */
+  getLedger(): Map<string, MemberBalance> {
+    return new Map(this._ledger);
+  }
+
+  /**
+   * Reset the ledger, clearing all member balances.
+   * Does not affect working memory.
+   */
+  resetLedger(): void {
+    this._ledger.clear();
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}

package/src/engines/loyalty/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Loyalty Engine -- Point Ledger Management
+ */
+
+// Types
+export type {
+  LoyaltyStrategy,
+  PointTransactionType,
+  TierStatus,
+  QualifyingMetric,
+  EvaluationPeriod,
+  EarningRule,
+  RedemptionOption,
+  LoyaltyTierDefinition,
+  PromotionRule,
+  ExpirationPolicy,
+  PointTransaction,
+  MemberBalance,
+  EarningRuleSet,
+  RedemptionRuleSet,
+  TierEvaluationRuleSet,
+  LoyaltyRuleSet,
+  CompiledEarningRuleSet,
+  CompiledRedemptionRuleSet,
+  CompiledTierEvaluationRuleSet,
+  CompiledLoyaltyRuleSet,
+  EarningResult,
+  RedemptionResult,
+  MemberTierResult,
+  TierEvaluationResult,
+  LoyaltyResult,
+  LoyaltyOptions,
+  LoyaltyIngestResult
+} from './types';
+
+// Compiler
+export { compileLoyaltyRuleSet } from './compiler';
+
+// Strategy
+export { LoyaltyExecutor, loyaltyStrategy } from './strategy';
+
+// Engine
+export { LoyaltyEngine } from './engine';