@higher.archi/boe 1.0.0

package/src/engines/pricing/compiler.ts

@@ -0,0 +1,381 @@
+/**
+ * Pricing Engine Compiler
+ *
+ * Compiles pricing rulesets for efficient execution:
+ * - Validates product types and scenario schemas
+ * - Compiles expressions in pricing/quantity/metrics
+ * - Validates scenario values against product type schemas
+ */
+
+import {
+  compileCondition,
+  compileOperand
+} from '../../core';
+
+import {
+  PricingRuleSet,
+  PricingRule,
+  PricingComponent,
+  PricingMode,
+  PricingInput,
+  Adjustment,
+  Metric,
+  GraduatedTier,
+  VolumeBracket,
+  Meter,
+  ProductType,
+  CompiledPricingRuleSet,
+  CompiledPricingRule,
+  CompiledPricingComponent,
+  CompiledPricingMode,
+  CompiledPricingInput,
+  CompiledAdjustment,
+  CompiledMetric,
+  CompiledGraduatedTier,
+  CompiledVolumeBracket,
+  CompiledMeter,
+  getCurrencyInfo
+} from './types';
+
+// ========================================
+// Validation Helpers
+// ========================================
+
+/**
+ * Validate component's scenario values against product type schema.
+ */
+function validateScenarioValues(
+  component: PricingComponent,
+  productType: ProductType | undefined,
+  scenarioIds: string[],
+  strict: boolean
+): void {
+  if (!productType) return;
+
+  const { scenarioSchema } = productType;
+
+  for (const scenarioId of scenarioIds) {
+    const values = component.scenarioValues[scenarioId] || {};
+
+    // Check required fields
+    for (const [field, schema] of Object.entries(scenarioSchema)) {
+      if (schema.required && values[field] === undefined && schema.default === undefined) {
+        if (strict) {
+          throw new Error(
+            `Component '${component.sku}' missing required scenario value '${field}' for scenario '${scenarioId}'`
+          );
+        }
+      }
+    }
+
+    // Validate provided values
+    for (const [field, value] of Object.entries(values)) {
+      const schema = scenarioSchema[field];
+      if (!schema) {
+        throw new Error(
+          `Component '${component.sku}' has unknown scenario field '${field}' for scenario '${scenarioId}'`
+        );
+      }
+
+      validateValue(value, schema, `${component.sku}.${scenarioId}.${field}`);
+    }
+  }
+}
+
+/**
+ * Validate a value against its schema.
+ */
+function validateValue(
+  value: unknown,
+  schema: { type: string; min?: number; max?: number; enum?: string[] },
+  path: string
+): void {
+  if (value === undefined || value === null) return;
+
+  const actualType = Array.isArray(value) ? 'array' : typeof value;
+  if (actualType !== schema.type) {
+    throw new Error(
+      `Invalid type for '${path}': expected ${schema.type}, got ${actualType}`
+    );
+  }
+
+  if (schema.type === 'number' && typeof value === 'number') {
+    if (schema.min !== undefined && value < schema.min) {
+      throw new Error(
+        `Value for '${path}' is below minimum: ${value} < ${schema.min}`
+      );
+    }
+    if (schema.max !== undefined && value > schema.max) {
+      throw new Error(
+        `Value for '${path}' exceeds maximum: ${value} > ${schema.max}`
+      );
+    }
+  }
+
+  if (schema.type === 'string' && schema.enum && typeof value === 'string') {
+    if (!schema.enum.includes(value)) {
+      throw new Error(
+        `Invalid value for '${path}': '${value}' not in [${schema.enum.join(', ')}]`
+      );
+    }
+  }
+}
+
+// ========================================
+// Pricing Mode Compilation
+// ========================================
+
+function compileGraduatedTier(tier: GraduatedTier): CompiledGraduatedTier {
+  return {
+    upTo: tier.upTo,
+    pricePerUnit: compileOperand(tier.pricePerUnit)
+  };
+}
+
+function compileVolumeBracket(bracket: VolumeBracket): CompiledVolumeBracket {
+  return {
+    minVolume: bracket.minVolume,
+    pricePerUnit: compileOperand(bracket.pricePerUnit)
+  };
+}
+
+function compileMeter(meter: Meter): CompiledMeter {
+  return {
+    id: meter.id,
+    name: meter.name || meter.id,
+    quantity: compileOperand(meter.quantity),
+    unit: meter.unit || 'units',
+    pricing: compilePricingMode(meter.pricing)
+  };
+}
+
+function compilePricingMode(pricing: PricingMode): CompiledPricingMode {
+  switch (pricing.mode) {
+    case 'flat':
+      return {
+        mode: 'flat',
+        pricePerUnit: compileOperand(pricing.pricePerUnit)
+      };
+
+    case 'graduated':
+      // Validate tiers are in order
+      for (let i = 1; i < pricing.tiers.length; i++) {
+        if (pricing.tiers[i].upTo <= pricing.tiers[i - 1].upTo) {
+          throw new Error(
+            `Graduated tiers must be in ascending order by 'upTo' value`
+          );
+        }
+      }
+      return {
+        mode: 'graduated',
+        tiers: pricing.tiers.map(compileGraduatedTier)
+      };
+
+    case 'volume':
+      // Validate brackets are in order
+      for (let i = 1; i < pricing.brackets.length; i++) {
+        if (pricing.brackets[i].minVolume <= pricing.brackets[i - 1].minVolume) {
+          throw new Error(
+            `Volume brackets must be in ascending order by 'minVolume' value`
+          );
+        }
+      }
+      return {
+        mode: 'volume',
+        brackets: pricing.brackets.map(compileVolumeBracket)
+      };
+
+    case 'multi-meter':
+      return {
+        mode: 'multi-meter',
+        meters: pricing.meters.map(compileMeter)
+      };
+
+    case 'formula':
+      return {
+        mode: 'formula',
+        calculate: compileOperand(pricing.calculate)
+      };
+  }
+}
+
+// ========================================
+// Component Compilation
+// ========================================
+
+function compileComponent(
+  component: PricingComponent,
+  productTypes: Record<string, ProductType>,
+  scenarioIds: string[],
+  strict: boolean
+): CompiledPricingComponent {
+  const productType = component.productType
+    ? productTypes[component.productType]
+    : undefined;
+
+  // Validate scenario values if product type exists
+  if (productType) {
+    validateScenarioValues(component, productType, scenarioIds, strict);
+  }
+
+  // Compile attributes
+  const attributes: Record<string, any> = {};
+  for (const [key, value] of Object.entries(component.attributes)) {
+    attributes[key] = compileOperand(value);
+  }
+
+  return {
+    sku: component.sku,
+    name: component.name || component.sku,
+    productType: component.productType,
+    attributes,
+    scenarioValues: component.scenarioValues,
+    quantity: compileOperand(component.quantity),
+    unit: component.unit || productType?.defaultUnit || 'units',
+    pricing: compilePricingMode(component.pricing)
+  };
+}
+
+// ========================================
+// Adjustment Compilation
+// ========================================
+
+function compileAdjustment(adjustment: Adjustment): CompiledAdjustment {
+  switch (adjustment.type) {
+    case 'discount':
+      return {
+        type: 'discount',
+        name: adjustment.name,
+        percent: adjustment.percent,
+        amount: adjustment.amount,
+        condition: adjustment.condition
+          ? compileCondition(adjustment.condition)
+          : undefined
+      };
+
+    case 'minimum':
+      return {
+        type: 'minimum',
+        name: adjustment.name || 'Minimum charge',
+        amount: adjustment.amount
+      };
+
+    case 'maximum':
+      return {
+        type: 'maximum',
+        name: adjustment.name || 'Price cap',
+        amount: adjustment.amount
+      };
+  }
+}
+
+// ========================================
+// Metric Compilation
+// ========================================
+
+function compileMetric(metric: Metric): CompiledMetric {
+  return {
+    id: metric.id,
+    name: metric.name,
+    calculate: compileOperand(metric.calculate),
+    format: metric.format || 'number'
+  };
+}
+
+// ========================================
+// Input Compilation
+// ========================================
+
+function compileInput(input: PricingInput): CompiledPricingInput {
+  return {
+    name: input.name,
+    type: input.type,
+    where: input.where ? compileCondition(input.where) : undefined
+  };
+}
+
+// ========================================
+// Rule Compilation
+// ========================================
+
+function compileRule(
+  rule: PricingRule,
+  productTypes: Record<string, ProductType>,
+  scenarioIds: string[],
+  strict: boolean
+): CompiledPricingRule {
+  return {
+    id: rule.id,
+    name: rule.name || rule.id,
+    description: rule.description,
+    inputs: (rule.inputs || []).map(compileInput),
+    components: rule.pricing.components.map(c =>
+      compileComponent(c, productTypes, scenarioIds, strict)
+    ),
+    adjustments: (rule.pricing.adjustments || []).map(compileAdjustment),
+    metrics: (rule.pricing.metrics || []).map(compileMetric)
+  };
+}
+
+// ========================================
+// RuleSet Compilation
+// ========================================
+
+/**
+ * Compile a pricing ruleset.
+ */
+export function compilePricingRuleSet(ruleSet: PricingRuleSet): CompiledPricingRuleSet {
+  const scenarioDefinitions = ruleSet.scenarios?.definitions || {};
+  const scenarioIds = Object.keys(scenarioDefinitions);
+  const productTypes = ruleSet.productTypes || {};
+  const strict = ruleSet.scenarios?.strict ?? false;
+
+  // Find default scenario
+  let defaultScenario: string | undefined;
+  for (const [id, def] of Object.entries(scenarioDefinitions)) {
+    if (def.isDefault) {
+      defaultScenario = id;
+      break;
+    }
+  }
+  if (!defaultScenario && scenarioIds.length > 0) {
+    defaultScenario = scenarioIds[0];
+  }
+
+  // Resolve currency config
+  const currency = ruleSet.config?.currency ?? 'USD';
+  const currencyInfo = getCurrencyInfo(currency);
+  const precision = ruleSet.config?.precision ?? currencyInfo.decimals;
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'pricing',
+    scenarios: {
+      definitions: scenarioDefinitions,
+      defaultScenario,
+      strict
+    },
+    productTypes,
+    config: {
+      currency,
+      currencyInfo,
+      precision
+    },
+    rules: ruleSet.rules.map(rule =>
+      compileRule(rule, productTypes, scenarioIds, strict)
+    )
+  };
+}
+
+/**
+ * Compile a single pricing rule (for direct rule compilation).
+ */
+export function compilePricingRule(
+  rule: PricingRule,
+  productTypes: Record<string, ProductType> = {},
+  scenarioIds: string[] = [],
+  strict: boolean = false
+): CompiledPricingRule {
+  return compileRule(rule, productTypes, scenarioIds, strict);
+}

package/src/engines/pricing/engine.ts

@@ -0,0 +1,152 @@
+/**
+ * Pricing Engine
+ *
+ * Calculates costs for tiered/graduated pricing, package-based pricing
+ * with multiple SKUs, and enables scenario comparisons.
+ *
+ * Unlike other engines, the Pricing Engine does NOT use working memory.
+ * It takes direct input (ruleset + rule ID + options) and returns pricing results.
+ */
+
+import {
+  CompiledPricingRuleSet,
+  PricingRuleSet,
+  PricingOptions,
+  PricingResult,
+  ScenarioComparisonResult
+} from './types';
+
+import { compilePricingRuleSet } from './compiler';
+import { PricingStrategy } from './strategy';
+
+/**
+ * Pricing Engine.
+ *
+ * Calculates pricing based on tiered/graduated models, supports multiple
+ * pricing modes, adjustments, and scenario comparisons.
+ *
+ * @example
+ * ```typescript
+ * const engine = new PricingEngine();
+ * const compiled = compilePricingRuleSet(pricingRuleSet);
+ *
+ * // Single scenario calculation
+ * const result = engine.calculate(compiled, 'api-pricing', { scenario: 'standard' });
+ * console.log(`Total: ${result.summary.total}`);
+ *
+ * // Compare all scenarios
+ * const comparison = engine.calculateScenarios(compiled, 'api-pricing');
+ * console.log(comparison.toString());
+ * ```
+ */
+export class PricingEngine {
+  private strategy: PricingStrategy;
+
+  constructor() {
+    this.strategy = new PricingStrategy();
+  }
+
+  /**
+   * Calculate pricing for a single scenario.
+   *
+   * @param ruleSet - Compiled or source pricing ruleset
+   * @param ruleId - ID of the rule to calculate
+   * @param options - Runtime options (scenario, overrides, callbacks)
+   * @returns Pricing result with component breakdown and totals
+   *
+   * @example
+   * ```typescript
+   * const result = engine.calculate(compiled, 'cloud-pricing', {
+   *   scenario: 'heavy-usage'
+   * });
+   *
+   * console.log(`Components Total: ${result.summary.componentsTotal}`);
+   * console.log(`After Adjustments: ${result.summary.total}`);
+   * console.log(result.toString());
+   * ```
+   */
+  calculate(
+    ruleSet: CompiledPricingRuleSet | PricingRuleSet,
+    ruleId: string,
+    options: PricingOptions = {}
+  ): PricingResult {
+    const compiled = this.ensureCompiled(ruleSet);
+    return this.strategy.calculate(compiled, ruleId, options);
+  }
+
+  /**
+   * Calculate pricing for multiple scenarios for comparison.
+   *
+   * @param ruleSet - Compiled or source pricing ruleset
+   * @param ruleId - ID of the rule to calculate
+   * @param scenarioIds - Optional array of scenario IDs (defaults to all scenarios)
+   * @returns Comparison result with all scenario results
+   *
+   * @example
+   * ```typescript
+   * const comparison = engine.calculateScenarios(compiled, 'saas-pricing');
+   *
+   * // Access individual scenario results
+   * const lightUsage = comparison.scenarios['light'];
+   * console.log(`Light: ${lightUsage.summary.total}`);
+   *
+   * // Print comparison table
+   * console.log(comparison.toString());
+   * ```
+   */
+  calculateScenarios(
+    ruleSet: CompiledPricingRuleSet | PricingRuleSet,
+    ruleId: string,
+    scenarioIds?: string[]
+  ): ScenarioComparisonResult {
+    const compiled = this.ensureCompiled(ruleSet);
+    return this.strategy.calculateScenarios(compiled, ruleId, scenarioIds);
+  }
+
+  /**
+   * Ensure ruleset is compiled.
+   */
+  private ensureCompiled(ruleSet: CompiledPricingRuleSet | PricingRuleSet): CompiledPricingRuleSet {
+    // Check if already compiled by looking for compiled-specific properties
+    if ('config' in ruleSet && typeof ruleSet.config === 'object' && 'currency' in ruleSet.config && 'precision' in ruleSet.config) {
+      return ruleSet as CompiledPricingRuleSet;
+    }
+    return compilePricingRuleSet(ruleSet as PricingRuleSet);
+  }
+
+  /**
+   * Get available scenario IDs from a ruleset.
+   *
+   * @param ruleSet - Compiled or source pricing ruleset
+   * @returns Array of scenario IDs
+   */
+  getScenarios(ruleSet: CompiledPricingRuleSet | PricingRuleSet): string[] {
+    const compiled = this.ensureCompiled(ruleSet);
+    return Object.keys(compiled.scenarios.definitions);
+  }
+
+  /**
+   * Get available rule IDs from a ruleset.
+   *
+   * @param ruleSet - Compiled or source pricing ruleset
+   * @returns Array of rule IDs
+   */
+  getRules(ruleSet: CompiledPricingRuleSet | PricingRuleSet): string[] {
+    const compiled = this.ensureCompiled(ruleSet);
+    return compiled.rules.map(r => r.id);
+  }
+
+  /**
+   * Get the default scenario ID for a ruleset.
+   *
+   * @param ruleSet - Compiled or source pricing ruleset
+   * @returns Default scenario ID or undefined
+   */
+  getDefaultScenario(ruleSet: CompiledPricingRuleSet | PricingRuleSet): string | undefined {
+    const compiled = this.ensureCompiled(ruleSet);
+    return compiled.scenarios.defaultScenario;
+  }
+}
+
+// Export singleton for convenience
+export const pricingEngine = new PricingEngine();

package/src/engines/pricing/index.ts

@@ -0,0 +1,156 @@
+/**
+ * Pricing Engine - Tiered/Graduated Pricing & Scenario Comparison
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   PricingEngine,
+ *   compilePricingRuleSet,
+ *   PricingRuleSet
+ * } from '@higher.archi/boe';
+ *
+ * const ruleSet: PricingRuleSet = {
+ *   id: 'cloud-pricing',
+ *   mode: 'pricing',
+ *   scenarios: {
+ *     definitions: {
+ *       light: { name: 'Light Usage' },
+ *       standard: { name: 'Standard Usage', isDefault: true },
+ *       heavy: { name: 'Heavy Usage' }
+ *     }
+ *   },
+ *   rules: [{
+ *     id: 'api-pricing',
+ *     pricing: {
+ *       mode: 'package',
+ *       components: [{
+ *         sku: 'api-requests',
+ *         scenarioValues: {
+ *           light: { requests: 100_000 },
+ *           standard: { requests: 1_000_000 },
+ *           heavy: { requests: 10_000_000 }
+ *         },
+ *         quantity: '$requests',
+ *         pricing: {
+ *           mode: 'graduated',
+ *           tiers: [
+ *             { upTo: 1_000_000, pricePerUnit: 0.0002 },
+ *             { upTo: 5_000_000, pricePerUnit: 0.0001 },
+ *             { upTo: Infinity, pricePerUnit: 0.00005 }
+ *           ]
+ *         }
+ *       }]
+ *     }
+ *   }]
+ * };
+ *
+ * const compiled = compilePricingRuleSet(ruleSet);
+ * const engine = new PricingEngine();
+ *
+ * // Single scenario
+ * const result = engine.calculate(compiled, 'api-pricing', { scenario: 'standard' });
+ * console.log(result.toString());
+ *
+ * // Compare all scenarios
+ * const comparison = engine.calculateScenarios(compiled, 'api-pricing');
+ * console.log(comparison.toString());
+ * ```
+ */
+
+// Types
+export type {
+  // Currency types
+  CurrencyCode,
+  CurrencyInfo,
+
+  // Scenario types
+  ScenarioDefinition,
+  ScenarioDefinitions,
+
+  // Product type types
+  AttributeSchema,
+  ProductType,
+
+  // Pricing mode types
+  FlatPricing,
+  GraduatedTier,
+  GraduatedPricing,
+  VolumeBracket,
+  VolumePricing,
+  Meter,
+  MultiMeterPricing,
+  FormulaPricing,
+  PricingMode,
+
+  // Component types
+  PricingComponent,
+
+  // Adjustment types
+  DiscountAdjustment,
+  MinimumAdjustment,
+  MaximumAdjustment,
+  Adjustment,
+
+  // Metric types
+  Metric,
+
+  // Rule types
+  PricingInput,
+  PricingPackage,
+  PricingRule,
+  PricingConfig,
+  PricingRuleSet,
+
+  // Compiled types
+  CompiledGraduatedTier,
+  CompiledVolumeBracket,
+  CompiledMeter,
+  CompiledPricingMode,
+  CompiledPricingComponent,
+  CompiledAdjustment,
+  CompiledMetric,
+  CompiledPricingInput,
+  CompiledPricingRule,
+  ResolvedPricingConfig,
+  CompiledPricingRuleSet,
+
+  // Result types
+  TierBreakdown,
+  MeterResult,
+  ComponentResult,
+  AdjustmentResult,
+  PricingSummary,
+  ScenarioResult,
+  PricingResult,
+  ScenarioComparisonResult,
+
+  // Options
+  PricingOptions
+} from './types';
+
+// Currency utilities
+export { CURRENCIES, getCurrencyInfo } from './types';
+
+// Compiler
+export { compilePricingRuleSet, compilePricingRule } from './compiler';
+
+// Calculator utilities
+export {
+  calculateFlat,
+  calculateGraduated,
+  calculateVolume,
+  formatCurrency,
+  formatNumber,
+  formatPercent,
+  round,
+  calculateDiscount,
+  applyMinMax
+} from './calculator';
+
+export type { CalculatorContext, TierCalculationResult } from './calculator';
+
+// Strategy
+export { PricingStrategy, pricingStrategy } from './strategy';
+
+// Engine
+export { PricingEngine, pricingEngine } from './engine';