@higher.archi/boe 1.0.0

package/src/engines/pricing/types.ts

@@ -0,0 +1,782 @@
+/**
+ * Pricing Engine Types
+ *
+ * The Pricing Engine calculates costs for tiered/graduated pricing,
+ * package-based pricing with multiple SKUs, and enables scenario comparisons.
+ *
+ * Key Concepts:
+ * - Product Types: Schema definitions for SKU attributes and scenario values
+ * - Pricing Modes: flat, graduated, volume, multi-meter, formula
+ * - Scenarios: Usage profiles for comparison (light/standard/heavy)
+ * - Components: Individual SKUs within a pricing package
+ * - Adjustments: Discounts, minimums, maximums applied to totals
+ * - Metrics: Computed values for comparison (cost per 1K, effective rate)
+ */
+
+import {
+  Condition,
+  Operand,
+  CompiledCondition,
+  CompiledOperand
+} from '../../core';
+
+// ========================================
+// Currency Types
+// ========================================
+
+/**
+ * ISO 4217 currency codes supported by the pricing engine.
+ */
+export type CurrencyCode =
+  | 'USD'  // US Dollar
+  | 'EUR'  // Euro
+  | 'GBP'  // British Pound
+  | 'JPY'  // Japanese Yen
+  | 'AUD'  // Australian Dollar
+  | 'CAD'  // Canadian Dollar
+  | 'CHF'  // Swiss Franc
+  | 'CNY'  // Chinese Yuan
+  | 'INR'  // Indian Rupee
+  | 'MXN'  // Mexican Peso
+  | 'BRL'  // Brazilian Real
+  | 'KRW'  // South Korean Won
+  | 'SGD'  // Singapore Dollar
+  | 'HKD'  // Hong Kong Dollar
+  | 'NZD'  // New Zealand Dollar
+  | 'SEK'  // Swedish Krona
+  | 'NOK'  // Norwegian Krone
+  | 'DKK'  // Danish Krone
+  | 'ZAR'  // South African Rand
+  | 'AED'  // UAE Dirham
+  | 'SAR'  // Saudi Riyal
+  | 'PLN'  // Polish Zloty
+  | 'THB'  // Thai Baht
+  | 'IDR'  // Indonesian Rupiah
+  | 'MYR'  // Malaysian Ringgit
+  | 'PHP'  // Philippine Peso
+  | 'TWD'  // Taiwan Dollar
+  | 'VND'  // Vietnamese Dong
+  | 'ILS'  // Israeli Shekel
+  | 'CZK'  // Czech Koruna
+  | 'HUF'  // Hungarian Forint
+  | 'RUB'  // Russian Ruble
+  | 'TRY'  // Turkish Lira
+  | 'ARS'  // Argentine Peso
+  | 'CLP'  // Chilean Peso
+  | 'COP'  // Colombian Peso
+  | 'PEN';  // Peruvian Sol
+
+/**
+ * Currency information with code, name, and symbol.
+ */
+export type CurrencyInfo = {
+  /** ISO 4217 3-letter currency code */
+  code: CurrencyCode;
+  /** Full currency name */
+  name: string;
+  /** Currency symbol (e.g., $, €, £) */
+  symbol: string;
+  /** Number of decimal places (e.g., 2 for USD, 0 for JPY) */
+  decimals: number;
+};
+
+/**
+ * Map of currency codes to their information.
+ */
+export const CURRENCIES: Record<CurrencyCode, CurrencyInfo> = {
+  USD: { code: 'USD', name: 'US Dollar', symbol: '$', decimals: 2 },
+  EUR: { code: 'EUR', name: 'Euro', symbol: '€', decimals: 2 },
+  GBP: { code: 'GBP', name: 'British Pound', symbol: '£', decimals: 2 },
+  JPY: { code: 'JPY', name: 'Japanese Yen', symbol: '¥', decimals: 0 },
+  AUD: { code: 'AUD', name: 'Australian Dollar', symbol: 'A$', decimals: 2 },
+  CAD: { code: 'CAD', name: 'Canadian Dollar', symbol: 'C$', decimals: 2 },
+  CHF: { code: 'CHF', name: 'Swiss Franc', symbol: 'CHF', decimals: 2 },
+  CNY: { code: 'CNY', name: 'Chinese Yuan', symbol: '¥', decimals: 2 },
+  INR: { code: 'INR', name: 'Indian Rupee', symbol: '₹', decimals: 2 },
+  MXN: { code: 'MXN', name: 'Mexican Peso', symbol: 'MX$', decimals: 2 },
+  BRL: { code: 'BRL', name: 'Brazilian Real', symbol: 'R$', decimals: 2 },
+  KRW: { code: 'KRW', name: 'South Korean Won', symbol: '₩', decimals: 0 },
+  SGD: { code: 'SGD', name: 'Singapore Dollar', symbol: 'S$', decimals: 2 },
+  HKD: { code: 'HKD', name: 'Hong Kong Dollar', symbol: 'HK$', decimals: 2 },
+  NZD: { code: 'NZD', name: 'New Zealand Dollar', symbol: 'NZ$', decimals: 2 },
+  SEK: { code: 'SEK', name: 'Swedish Krona', symbol: 'kr', decimals: 2 },
+  NOK: { code: 'NOK', name: 'Norwegian Krone', symbol: 'kr', decimals: 2 },
+  DKK: { code: 'DKK', name: 'Danish Krone', symbol: 'kr', decimals: 2 },
+  ZAR: { code: 'ZAR', name: 'South African Rand', symbol: 'R', decimals: 2 },
+  AED: { code: 'AED', name: 'UAE Dirham', symbol: 'د.إ', decimals: 2 },
+  SAR: { code: 'SAR', name: 'Saudi Riyal', symbol: '﷼', decimals: 2 },
+  PLN: { code: 'PLN', name: 'Polish Zloty', symbol: 'zł', decimals: 2 },
+  THB: { code: 'THB', name: 'Thai Baht', symbol: '฿', decimals: 2 },
+  IDR: { code: 'IDR', name: 'Indonesian Rupiah', symbol: 'Rp', decimals: 0 },
+  MYR: { code: 'MYR', name: 'Malaysian Ringgit', symbol: 'RM', decimals: 2 },
+  PHP: { code: 'PHP', name: 'Philippine Peso', symbol: '₱', decimals: 2 },
+  TWD: { code: 'TWD', name: 'Taiwan Dollar', symbol: 'NT$', decimals: 0 },
+  VND: { code: 'VND', name: 'Vietnamese Dong', symbol: '₫', decimals: 0 },
+  ILS: { code: 'ILS', name: 'Israeli Shekel', symbol: '₪', decimals: 2 },
+  CZK: { code: 'CZK', name: 'Czech Koruna', symbol: 'Kč', decimals: 2 },
+  HUF: { code: 'HUF', name: 'Hungarian Forint', symbol: 'Ft', decimals: 0 },
+  RUB: { code: 'RUB', name: 'Russian Ruble', symbol: '₽', decimals: 2 },
+  TRY: { code: 'TRY', name: 'Turkish Lira', symbol: '₺', decimals: 2 },
+  ARS: { code: 'ARS', name: 'Argentine Peso', symbol: 'ARS$', decimals: 2 },
+  CLP: { code: 'CLP', name: 'Chilean Peso', symbol: 'CLP$', decimals: 0 },
+  COP: { code: 'COP', name: 'Colombian Peso', symbol: 'COP$', decimals: 0 },
+  PEN: { code: 'PEN', name: 'Peruvian Sol', symbol: 'S/', decimals: 2 },
+};
+
+/**
+ * Get currency info by code.
+ * Returns USD info if code not found.
+ */
+export function getCurrencyInfo(code: CurrencyCode | string): CurrencyInfo {
+  return CURRENCIES[code as CurrencyCode] || CURRENCIES.USD;
+}
+
+// ========================================
+// Scenario Types
+// ========================================
+
+/**
+ * Scenario definition - a named usage profile for comparison.
+ * Scenarios are defined at the ruleset level and referenced by components.
+ */
+export type ScenarioDefinition = {
+  /** Human-readable scenario name */
+  name: string;
+  /** Description of this usage profile */
+  description?: string;
+  /** Whether this is the default scenario */
+  isDefault?: boolean;
+};
+
+/**
+ * Map of scenario IDs to their definitions.
+ */
+export type ScenarioDefinitions = Record<string, ScenarioDefinition>;
+
+// ========================================
+// Product Type Schema
+// ========================================
+
+/**
+ * Schema definition for a single attribute.
+ */
+export type AttributeSchema = {
+  /** Data type of the attribute */
+  type: 'string' | 'number' | 'boolean' | 'array';
+  /** Whether this attribute is required */
+  required?: boolean;
+  /** Default value if not provided */
+  default?: unknown;
+  /** Allowed string values (for string type) */
+  enum?: string[];
+  /** Minimum value (for number type) */
+  min?: number;
+  /** Maximum value (for number type) */
+  max?: number;
+};
+
+/**
+ * Product type definition - describes a category of SKUs.
+ *
+ * Each product type defines:
+ * - Its own attribute schema (region, tier, etc.)
+ * - Its own scenario schema (what values change per scenario)
+ */
+export type ProductType = {
+  /** Human-readable description */
+  description?: string;
+  /** Schema for SKU attributes (static properties) */
+  attributes: Record<string, AttributeSchema>;
+  /** Schema for scenario values (what varies per usage profile) */
+  scenarioSchema: Record<string, AttributeSchema>;
+  /** Default unit of measurement */
+  defaultUnit?: string;
+};
+
+// ========================================
+// Pricing Modes
+// ========================================
+
+/**
+ * Flat pricing - single price per unit regardless of quantity.
+ */
+export type FlatPricing = {
+  mode: 'flat';
+  /** Price per unit (constant or expression) */
+  pricePerUnit: Operand;
+};
+
+/**
+ * Graduated tier - defines pricing for a range of units.
+ * In graduated pricing, each tier applies only to units within its range.
+ */
+export type GraduatedTier = {
+  /** Upper bound of this tier (use Infinity for unlimited) */
+  upTo: number;
+  /** Price per unit within this tier */
+  pricePerUnit: Operand;
+};
+
+/**
+ * Graduated pricing - different rates for different quantity ranges.
+ *
+ * Example: First 1M requests at $0.20/1K, next 4M at $0.10/1K
+ * For 3M requests: (1M * $0.20) + (2M * $0.10) = $400
+ */
+export type GraduatedPricing = {
+  mode: 'graduated';
+  /** Tiers in ascending order by upTo value */
+  tiers: GraduatedTier[];
+};
+
+/**
+ * Volume bracket - defines pricing for a volume threshold.
+ * In volume pricing, total volume determines the single rate for ALL units.
+ */
+export type VolumeBracket = {
+  /** Minimum volume for this bracket to apply */
+  minVolume: number;
+  /** Price per unit for entire volume */
+  pricePerUnit: Operand;
+};
+
+/**
+ * Volume pricing - total volume determines rate for all units.
+ *
+ * Example: <1M at $0.20/1K, 1M-5M at $0.15/1K, >5M at $0.10/1K
+ * For 3M requests: 3M * $0.15 = $450 (single rate)
+ */
+export type VolumePricing = {
+  mode: 'volume';
+  /** Brackets in ascending order by minVolume */
+  brackets: VolumeBracket[];
+};
+
+/**
+ * Individual meter within multi-meter pricing.
+ */
+export type Meter = {
+  /** Unique meter identifier */
+  id: string;
+  /** Human-readable meter name */
+  name?: string;
+  /** Quantity expression (from scenario values) */
+  quantity: Operand;
+  /** Unit of measurement */
+  unit?: string;
+  /** Pricing for this meter */
+  pricing: FlatPricing | GraduatedPricing | VolumePricing;
+};
+
+/**
+ * Multi-meter pricing - multiple independent meters summed together.
+ *
+ * Example: AWS Lambda pricing with requests + compute (GB-seconds)
+ */
+export type MultiMeterPricing = {
+  mode: 'multi-meter';
+  /** Individual meters */
+  meters: Meter[];
+};
+
+/**
+ * Formula pricing - custom calculation expression.
+ */
+export type FormulaPricing = {
+  mode: 'formula';
+  /** Expression to calculate total price */
+  calculate: Operand;
+};
+
+/**
+ * All pricing modes.
+ */
+export type PricingMode =
+  | FlatPricing
+  | GraduatedPricing
+  | VolumePricing
+  | MultiMeterPricing
+  | FormulaPricing;
+
+// ========================================
+// Component (SKU)
+// ========================================
+
+/**
+ * Pricing component - represents a single SKU within a pricing package.
+ */
+export type PricingComponent = {
+  /** SKU identifier */
+  sku: string;
+  /** Human-readable name */
+  name?: string;
+  /** Reference to product type for validation */
+  productType?: string;
+  /** Static attributes for this SKU */
+  attributes: Record<string, Operand>;
+  /**
+   * Scenario-specific values.
+   * Map of scenario ID to values that vary per usage profile.
+   */
+  scenarioValues: Record<string, Record<string, unknown>>;
+  /** Quantity expression (often references scenario values) */
+  quantity: Operand;
+  /** Unit of measurement */
+  unit?: string;
+  /** How this component is priced */
+  pricing: PricingMode;
+};
+
+// ========================================
+// Adjustments
+// ========================================
+
+/**
+ * Discount adjustment - percentage or fixed amount discount.
+ */
+export type DiscountAdjustment = {
+  type: 'discount';
+  /** Name of the discount */
+  name: string;
+  /** Percentage discount (0-100) */
+  percent?: number;
+  /** Fixed amount discount */
+  amount?: number;
+  /** Condition for applying this discount */
+  condition?: Condition;
+};
+
+/**
+ * Minimum adjustment - ensures total doesn't go below a threshold.
+ */
+export type MinimumAdjustment = {
+  type: 'minimum';
+  /** Name of the minimum charge */
+  name?: string;
+  /** Minimum amount */
+  amount: number;
+};
+
+/**
+ * Maximum adjustment - caps total at a threshold.
+ */
+export type MaximumAdjustment = {
+  type: 'maximum';
+  /** Name of the cap */
+  name?: string;
+  /** Maximum amount */
+  amount: number;
+};
+
+/**
+ * All adjustment types.
+ */
+export type Adjustment = DiscountAdjustment | MinimumAdjustment | MaximumAdjustment;
+
+// ========================================
+// Metrics
+// ========================================
+
+/**
+ * Computed metric for comparison.
+ */
+export type Metric = {
+  /** Metric identifier */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Expression to compute the metric value */
+  calculate: Operand;
+  /** Display format */
+  format?: 'currency' | 'percent' | 'number';
+};
+
+// ========================================
+// Rule & Ruleset (Source Types)
+// ========================================
+
+/**
+ * Input parameter for pricing rule.
+ */
+export type PricingInput = {
+  /** Binding name */
+  name: string;
+  /** Type name (for validation) */
+  type: string;
+  /** Filter condition */
+  where?: Condition;
+};
+
+/**
+ * Pricing package definition.
+ */
+export type PricingPackage = {
+  mode: 'package';
+  /** Components (SKUs) in this package */
+  components: PricingComponent[];
+  /** Adjustments applied to total */
+  adjustments?: Adjustment[];
+  /** Computed metrics for comparison */
+  metrics?: Metric[];
+};
+
+/**
+ * Pricing rule - defines a pricing package.
+ */
+export type PricingRule = {
+  /** Unique rule identifier */
+  id: string;
+  /** Human-readable name */
+  name?: string;
+  /** Description */
+  description?: string;
+  /** Input bindings (for potential future filtering) */
+  inputs?: PricingInput[];
+  /** The pricing package */
+  pricing: PricingPackage;
+};
+
+/**
+ * Pricing engine configuration.
+ */
+export type PricingConfig = {
+  /** ISO 4217 currency code (default: 'USD') */
+  currency?: CurrencyCode;
+  /**
+   * Decimal precision for rounding.
+   * If not specified, uses the currency's default decimals (e.g., 2 for USD, 0 for JPY).
+   */
+  precision?: number;
+};
+
+/**
+ * Pricing ruleset.
+ */
+export type PricingRuleSet = {
+  /** Unique ruleset identifier */
+  id: string;
+  /** Human-readable name */
+  name?: string;
+  /** Engine mode */
+  mode: 'pricing';
+  /** Scenario definitions */
+  scenarios?: {
+    /** Map of scenario ID to definition */
+    definitions: ScenarioDefinitions;
+    /** If true, components must provide values for ALL scenarios */
+    strict?: boolean;
+  };
+  /** Product type definitions for validation */
+  productTypes?: Record<string, ProductType>;
+  /** Engine configuration */
+  config?: PricingConfig;
+  /** Pricing rules */
+  rules: PricingRule[];
+};
+
+// ========================================
+// Compiled Types
+// ========================================
+
+/**
+ * Compiled graduated tier.
+ */
+export type CompiledGraduatedTier = {
+  upTo: number;
+  pricePerUnit: CompiledOperand;
+};
+
+/**
+ * Compiled volume bracket.
+ */
+export type CompiledVolumeBracket = {
+  minVolume: number;
+  pricePerUnit: CompiledOperand;
+};
+
+/**
+ * Compiled meter.
+ */
+export type CompiledMeter = {
+  id: string;
+  name: string;
+  quantity: CompiledOperand;
+  unit: string;
+  pricing: CompiledPricingMode;
+};
+
+/**
+ * Compiled pricing mode.
+ */
+export type CompiledPricingMode =
+  | { mode: 'flat'; pricePerUnit: CompiledOperand }
+  | { mode: 'graduated'; tiers: CompiledGraduatedTier[] }
+  | { mode: 'volume'; brackets: CompiledVolumeBracket[] }
+  | { mode: 'multi-meter'; meters: CompiledMeter[] }
+  | { mode: 'formula'; calculate: CompiledOperand };
+
+/**
+ * Compiled pricing component.
+ */
+export type CompiledPricingComponent = {
+  sku: string;
+  name: string;
+  productType?: string;
+  attributes: Record<string, CompiledOperand>;
+  scenarioValues: Record<string, Record<string, unknown>>;
+  quantity: CompiledOperand;
+  unit: string;
+  pricing: CompiledPricingMode;
+};
+
+/**
+ * Compiled adjustment.
+ */
+export type CompiledAdjustment =
+  | { type: 'discount'; name: string; percent?: number; amount?: number; condition?: CompiledCondition }
+  | { type: 'minimum'; name: string; amount: number }
+  | { type: 'maximum'; name: string; amount: number };
+
+/**
+ * Compiled metric.
+ */
+export type CompiledMetric = {
+  id: string;
+  name: string;
+  calculate: CompiledOperand;
+  format: 'currency' | 'percent' | 'number';
+};
+
+/**
+ * Compiled pricing input.
+ */
+export type CompiledPricingInput = {
+  name: string;
+  type: string;
+  where?: CompiledCondition;
+};
+
+/**
+ * Compiled pricing rule.
+ */
+export type CompiledPricingRule = {
+  id: string;
+  name: string;
+  description?: string;
+  inputs: CompiledPricingInput[];
+  components: CompiledPricingComponent[];
+  adjustments: CompiledAdjustment[];
+  metrics: CompiledMetric[];
+};
+
+/**
+ * Resolved config with full currency info.
+ */
+export type ResolvedPricingConfig = {
+  /** ISO 4217 currency code */
+  currency: CurrencyCode;
+  /** Full currency information */
+  currencyInfo: CurrencyInfo;
+  /** Decimal precision for rounding */
+  precision: number;
+};
+
+/**
+ * Compiled pricing ruleset.
+ */
+export type CompiledPricingRuleSet = {
+  id: string;
+  name?: string;
+  mode: 'pricing';
+  scenarios: {
+    definitions: ScenarioDefinitions;
+    defaultScenario?: string;
+    strict: boolean;
+  };
+  productTypes: Record<string, ProductType>;
+  config: ResolvedPricingConfig;
+  rules: CompiledPricingRule[];
+};
+
+// ========================================
+// Result Types
+// ========================================
+
+/**
+ * Tier breakdown in result.
+ */
+export type TierBreakdown = {
+  /** Tier identifier (e.g., "Tier 1", "0-1M") */
+  tier: string;
+  /** Range description (e.g., "0 - 1,000,000") */
+  range: string;
+  /** Units in this tier */
+  units: number;
+  /** Rate per unit in this tier */
+  rate: number;
+  /** Subtotal for this tier */
+  subtotal: number;
+};
+
+/**
+ * Meter result in multi-meter pricing.
+ */
+export type MeterResult = {
+  /** Meter identifier */
+  id: string;
+  /** Meter name */
+  name: string;
+  /** Quantity used */
+  quantity: number;
+  /** Unit of measurement */
+  unit: string;
+  /** Tier breakdown (if graduated/volume) */
+  tierBreakdown?: TierBreakdown[];
+  /** Meter subtotal */
+  subtotal: number;
+};
+
+/**
+ * Component result in pricing output.
+ */
+export type ComponentResult = {
+  /** SKU identifier */
+  sku: string;
+  /** Component name */
+  name: string;
+  /** Resolved attributes */
+  attributes: Record<string, unknown>;
+  /** Quantity */
+  quantity: number;
+  /** Unit */
+  unit: string;
+  /** Tier breakdown (for graduated/volume pricing) */
+  tierBreakdown?: TierBreakdown[];
+  /** Meter results (for multi-meter pricing) */
+  meters?: MeterResult[];
+  /** Component subtotal */
+  subtotal: number;
+};
+
+/**
+ * Adjustment result.
+ */
+export type AdjustmentResult = {
+  /** Adjustment type */
+  type: 'discount' | 'minimum' | 'maximum';
+  /** Adjustment name */
+  name: string;
+  /** Percentage (for discounts) */
+  percent?: number;
+  /** Amount applied */
+  amount: number;
+};
+
+/**
+ * Summary section of pricing result.
+ */
+export type PricingSummary = {
+  /** Total from all components */
+  componentsTotal: number;
+  /** Total from all adjustments */
+  adjustmentsTotal: number;
+  /** Final total */
+  total: number;
+};
+
+/**
+ * Single scenario result (for comparison).
+ */
+export type ScenarioResult = {
+  /** Scenario name */
+  name: string;
+  /** Scenario description */
+  description?: string;
+  /** Input values for this scenario */
+  inputs: Record<string, unknown>;
+  /** Component results */
+  components: ComponentResult[];
+  /** Adjustment results */
+  adjustments: AdjustmentResult[];
+  /** Summary totals */
+  summary: PricingSummary;
+  /** Computed metrics */
+  metrics: Record<string, number>;
+};
+
+/**
+ * Main pricing result.
+ */
+export type PricingResult = {
+  /** Rule that was executed */
+  ruleId: string;
+  /** Rule name */
+  ruleName?: string;
+  /** Scenario (if single scenario execution) */
+  scenario?: string;
+  /** Component results */
+  components: ComponentResult[];
+  /** Adjustment results */
+  adjustments: AdjustmentResult[];
+  /** Summary totals */
+  summary: PricingSummary;
+  /** Computed metrics */
+  metrics: Record<string, number>;
+  /** Processing time in milliseconds */
+  executionTimeMs: number;
+  /** Format as string */
+  toString: () => string;
+};
+
+/**
+ * Scenario comparison result.
+ */
+export type ScenarioComparisonResult = {
+  /** Ruleset ID */
+  rulesetId: string;
+  /** Rule that was executed */
+  ruleId: string;
+  /** Results per scenario */
+  scenarios: Record<string, ScenarioResult>;
+  /** Processing time in milliseconds */
+  executionTimeMs: number;
+  /** Format as string */
+  toString: () => string;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * Options for pricing engine execution.
+ */
+export type PricingOptions = {
+  /**
+   * Specific scenario to calculate.
+   * If not provided, uses default scenario or first defined.
+   */
+  scenario?: string;
+
+  /**
+   * Override scenario values at runtime.
+   * Merged with component-defined scenario values.
+   */
+  overrides?: Record<string, unknown>;
+
+  /**
+   * Callback when a component is calculated.
+   */
+  onComponent?: (sku: string, result: ComponentResult) => void;
+
+  /**
+   * Callback when an adjustment is applied.
+   */
+  onAdjustment?: (adjustment: AdjustmentResult) => void;
+
+  /**
+   * Whether to include detailed tier breakdowns.
+   * @default true
+   */
+  includeBreakdowns?: boolean;
+};