@higher.archi/boe 1.0.28 → 1.0.30

package/src/engines/loyalty/types.ts

@@ -0,0 +1,252 @@
+/**
+ * Loyalty Engine Types
+ *
+ * Point ledger engine that manages earning rules with category multipliers,
+ * point transactions (earn/redeem/transfer/expire), tier-qualified balances,
+ * and promotion stacking. Unlike other BOE engines, the Loyalty engine
+ * maintains running balance state across operations.
+ */
+
+import type { Condition } from '../../core/types/condition';
+
+// ========================================
+// Semantic Types
+// ========================================
+
+/** Loyalty strategy to use */
+export type LoyaltyStrategy = 'earning' | 'redemption' | 'tier-evaluation';
+
+/** Point transaction type */
+export type PointTransactionType = 'earn' | 'redeem' | 'expire' | 'transfer' | 'adjust';
+
+/** Member tier status */
+export type TierStatus = 'qualified' | 'at-risk' | 'downgrade-pending' | 'locked';
+
+/** Qualifying metric for tier evaluation */
+export type QualifyingMetric = 'points-earned' | 'qualifying-spend' | 'qualifying-nights' | 'qualifying-flights';
+
+/** Evaluation period for tier assessment */
+export type EvaluationPeriod = 'rolling-12-months' | 'calendar-year' | 'custom';
+
+// ========================================
+// Core Domain Types
+// ========================================
+
+/** An earning rule that maps activities to points */
+export type EarningRule = {
+  id: string;
+  name?: string;
+  category?: string;
+  baseRate: number;
+  multiplier?: number;
+  conditions?: Condition[];
+  bonusPoints?: number;
+  promotionId?: string;
+};
+
+/** A redemption option specifying how points can be spent */
+export type RedemptionOption = {
+  id: string;
+  name?: string;
+  type: string;
+  pointsRequired: number;
+  value: number;
+  unit?: string;
+  conditions?: Condition[];
+};
+
+/** A tier definition with qualifying thresholds and benefits */
+export type LoyaltyTierDefinition = {
+  id: string;
+  name: string;
+  qualifyingThreshold: number;
+  qualifyingMetric: QualifyingMetric;
+  benefits: string[];
+  multiplierBonus?: number;
+  retentionThreshold?: number;
+};
+
+/** A promotion rule that stacks multipliers or bonus points */
+export type PromotionRule = {
+  id: string;
+  name?: string;
+  multiplier?: number;
+  bonusPoints?: number;
+  categories?: string[];
+  startDate?: string;
+  endDate?: string;
+};
+
+/** Expiration policy for points */
+export type ExpirationPolicy = {
+  inactivityDays?: number;
+  absoluteMonths?: number;
+  graceDays?: number;
+};
+
+// ========================================
+// Ledger Types (First-Class State)
+// ========================================
+
+/** A single point transaction record */
+export type PointTransaction = {
+  id: string;
+  memberId: string;
+  type: PointTransactionType;
+  points: number;
+  category?: string;
+  ruleId?: string;
+  timestamp: string;
+  metadata?: Record<string, any>;
+};
+
+/** Running balance for a member */
+export type MemberBalance = {
+  memberId: string;
+  totalEarned: number;
+  totalRedeemed: number;
+  totalExpired: number;
+  currentBalance: number;
+  qualifyingPoints: number;
+  currentTier?: string;
+  tierQualifiedAt?: string;
+};
+
+// ========================================
+// Source RuleSet Types (Discriminated Union)
+// ========================================
+
+type LoyaltyRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'loyalty';
+  tiers?: LoyaltyTierDefinition[];
+  expirationPolicy?: ExpirationPolicy;
+  promotions?: PromotionRule[];
+};
+
+/** Earning strategy: compute points earned from purchase/activity events */
+export type EarningRuleSet = LoyaltyRuleSetBase & {
+  strategy: 'earning';
+  earningRules: EarningRule[];
+  defaultRate?: number;
+};
+
+/** Redemption strategy: process point redemption requests */
+export type RedemptionRuleSet = LoyaltyRuleSetBase & {
+  strategy: 'redemption';
+  redemptionOptions: RedemptionOption[];
+};
+
+/** Tier evaluation strategy: evaluate members against tier thresholds */
+export type TierEvaluationRuleSet = LoyaltyRuleSetBase & {
+  strategy: 'tier-evaluation';
+  evaluationPeriod?: EvaluationPeriod;
+  tiers: LoyaltyTierDefinition[];
+};
+
+export type LoyaltyRuleSet =
+  | EarningRuleSet
+  | RedemptionRuleSet
+  | TierEvaluationRuleSet;
+
+// ========================================
+// Compiled RuleSet Types
+// ========================================
+
+type CompiledLoyaltyRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'loyalty';
+  tiers: LoyaltyTierDefinition[];
+  expirationPolicy: ExpirationPolicy;
+  promotions: PromotionRule[];
+};
+
+export type CompiledEarningRuleSet = CompiledLoyaltyRuleSetBase & {
+  strategy: 'earning';
+  earningRules: EarningRule[];
+  defaultRate: number;
+};
+
+export type CompiledRedemptionRuleSet = CompiledLoyaltyRuleSetBase & {
+  strategy: 'redemption';
+  redemptionOptions: RedemptionOption[];
+};
+
+export type CompiledTierEvaluationRuleSet = CompiledLoyaltyRuleSetBase & {
+  strategy: 'tier-evaluation';
+  evaluationPeriod: EvaluationPeriod;
+  tiers: LoyaltyTierDefinition[];
+};
+
+export type CompiledLoyaltyRuleSet =
+  | CompiledEarningRuleSet
+  | CompiledRedemptionRuleSet
+  | CompiledTierEvaluationRuleSet;
+
+// ========================================
+// Result Types
+// ========================================
+
+/** Result from earning strategy execution */
+export type EarningResult = {
+  memberId: string;
+  transactions: PointTransaction[];
+  pointsEarned: number;
+  bonusPointsEarned: number;
+  promotionsApplied: string[];
+  newBalance: number;
+  executionTimeMs: number;
+};
+
+/** Result from redemption strategy execution */
+export type RedemptionResult = {
+  memberId: string;
+  redemption: PointTransaction;
+  pointsRedeemed: number;
+  redemptionValue: number;
+  remainingBalance: number;
+  executionTimeMs: number;
+};
+
+/** Per-member tier evaluation result */
+export type MemberTierResult = {
+  memberId: string;
+  currentTier: string;
+  previousTier?: string;
+  qualifyingPoints: number;
+  nextTierThreshold?: number;
+  pointsToNextTier?: number;
+  status: TierStatus;
+  benefits: string[];
+};
+
+/** Result from tier-evaluation strategy execution */
+export type TierEvaluationResult = {
+  members: MemberTierResult[];
+  tierDistribution: Record<string, number>;
+  executionTimeMs: number;
+};
+
+/** Union of all loyalty results */
+export type LoyaltyResult = EarningResult | RedemptionResult | TierEvaluationResult;
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/** Options for earning execution */
+export type LoyaltyOptions = {
+  asOf?: Date;
+};
+
+/** Result from ingest() -- streaming earning with running balance */
+export type LoyaltyIngestResult = {
+  memberId: string;
+  pointsEarned: number;
+  bonusPointsEarned: number;
+  promotionsApplied: string[];
+  newBalance: number;
+  transactions: PointTransaction[];
+};

package/src/index.ts

@@ -34,6 +34,7 @@ export { EnsembleEngine } from './engines/ensemble';
 export { SentimentEngine } from './engines/sentiment';
 export { NegotiationEngine } from './engines/negotiation';
 export { DecayEngine } from './engines/decay';
+export { LoyaltyEngine } from './engines/loyalty';
 
 // ========================================
 // Core Types & Utilities
@@ -581,9 +582,46 @@ export type {
   ReEngagementEvent,
   EntityDecayResult,
   DecayResult,
-  DecayOptions
+  DecayOptions,
+  DecayIngestResult
 } from './engines/decay';
 
+// Loyalty
+export {
+  LoyaltyExecutor,
+  compileLoyaltyRuleSet,
+  loyaltyStrategy
+} from './engines/loyalty';
+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 './engines/loyalty';
+
 // ========================================
 // Utility Functions (from old modules, re-exported for convenience)
 // ========================================