@etohq/connector-engine 1.5.1-alpha.4

package/src/engine/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Core Connector Engine
+ * @description Clean plugin-first connector engine
+ */
+
+export { ConnectorEngine } from "./clean-connector-engine";
+export type { 
+  ConnectorRegistry,
+  OperationGroup,
+  OperationGroups,
+  EngineConfig,
+  GroupResult
+} from "./clean-connector-engine";

package/src/engine/routing-engine.ts

@@ -0,0 +1,394 @@
+/**
+ * @fileoverview Hyperswitch-Inspired Routing Engine
+ */
+
+import { 
+  RoutingConfig, 
+  RoutingContext, 
+  RoutingDecision, 
+  ConnectorMetrics,
+  RoutingRule,
+  RoutingEngine as IRoutingEngine
+} from "../types/routing-config";
+
+export class RoutingEngine implements IRoutingEngine {
+  private metrics: Map<string, ConnectorMetrics> = new Map();
+  private circuitBreakers: Map<string, { state: string; failures: number; lastFailure?: Date }> = new Map();
+
+  async route(context: RoutingContext, config: RoutingConfig): Promise<RoutingDecision> {
+    // 1. Check for routing override
+    if (context.forceConnector) {
+      return {
+        selected_connector: context.forceConnector,
+        algorithm_used: 'priority',
+        fallback_used: false,
+        decision_timestamp: new Date().toISOString(),
+        routing_profile_id: config.profile_id,
+        alternative_connectors: []
+      };
+    }
+
+    // 2. Apply routing algorithm
+    switch (config.algorithm.type) {
+      case 'priority':
+        return await this.routeByPriority(context, config);
+      
+      case 'volume_split':
+        return await this.routeByVolumeSplit(context, config);
+      
+      case 'advanced':
+        return await this.routeByRules(context, config);
+      
+      case 'performance':
+        return await this.routeByPerformance(context, config);
+      
+      case 'cost_optimization':
+        return await this.routeByCost(context, config);
+      
+      default:
+        throw new Error(`Unsupported routing algorithm: ${config.algorithm.type}`);
+    }
+  }
+
+  private async routeByPriority(context: RoutingContext, config: RoutingConfig): Promise<RoutingDecision> {
+    // Find applicable rules
+    const applicableRules = this.findApplicableRules(context, config.algorithm.data);
+    
+    if (applicableRules.length === 0) {
+      return this.fallbackRouting(context, config);
+    }
+
+    // Sort connectors by priority
+    const sortedConnectors = applicableRules[0].connectors
+      .filter(c => this.isConnectorHealthy(c.connector))
+      .sort((a, b) => (b.priority || 0) - (a.priority || 0));
+
+    if (sortedConnectors.length === 0) {
+      return this.fallbackRouting(context, config);
+    }
+
+    return {
+      selected_connector: sortedConnectors[0].connector,
+      merchant_connector_id: sortedConnectors[0].merchant_connector_id,
+      algorithm_used: 'priority',
+      rule_applied: applicableRules[0].name,
+      fallback_used: false,
+      decision_timestamp: new Date().toISOString(),
+      routing_profile_id: config.profile_id,
+      alternative_connectors: sortedConnectors.slice(1).map(c => c.connector)
+    };
+  }
+
+  private async routeByVolumeSplit(context: RoutingContext, config: RoutingConfig): Promise<RoutingDecision> {
+    const applicableRules = this.findApplicableRules(context, config.algorithm.data);
+    
+    if (applicableRules.length === 0) {
+      return this.fallbackRouting(context, config);
+    }
+
+    // Weighted random selection based on volume split
+    const connectors = applicableRules[0].connectors.filter(c => this.isConnectorHealthy(c.connector));
+    const totalWeight = connectors.reduce((sum, c) => sum + (c.weight || 1), 0);
+    const random = Math.random() * totalWeight;
+    
+    let currentWeight = 0;
+    for (const connector of connectors) {
+      currentWeight += connector.weight || 1;
+      if (random <= currentWeight) {
+        return {
+          selected_connector: connector.connector,
+          merchant_connector_id: connector.merchant_connector_id,
+          algorithm_used: 'volume_split',
+          rule_applied: applicableRules[0].name,
+          fallback_used: false,
+          decision_timestamp: new Date().toISOString(),
+          routing_profile_id: config.profile_id,
+          alternative_connectors: connectors.filter(c => c.connector !== connector.connector).map(c => c.connector)
+        };
+      }
+    }
+
+    return this.fallbackRouting(context, config);
+  }
+
+  private async routeByRules(context: RoutingContext, config: RoutingConfig): Promise<RoutingDecision> {
+    // Advanced rule-based routing with complex conditions
+    for (const rule of config.algorithm.data) {
+      if (this.evaluateRule(context, rule)) {
+        const healthyConnectors = rule.connectors.filter(c => this.isConnectorHealthy(c.connector));
+        
+        if (healthyConnectors.length > 0) {
+          // Use priority within the rule
+          const selectedConnector = healthyConnectors.sort((a, b) => (b.priority || 0) - (a.priority || 0))[0];
+          
+          return {
+            selected_connector: selectedConnector.connector,
+            merchant_connector_id: selectedConnector.merchant_connector_id,
+            algorithm_used: 'advanced',
+            rule_applied: rule.name,
+            fallback_used: false,
+            decision_timestamp: new Date().toISOString(),
+            routing_profile_id: config.profile_id,
+            alternative_connectors: healthyConnectors.slice(1).map(c => c.connector)
+          };
+        }
+      }
+    }
+
+    return this.fallbackRouting(context, config);
+  }
+
+  private async routeByPerformance(context: RoutingContext, config: RoutingConfig): Promise<RoutingDecision> {
+    const applicableRules = this.findApplicableRules(context, config.algorithm.data);
+    
+    if (applicableRules.length === 0) {
+      return this.fallbackRouting(context, config);
+    }
+
+    // Sort by success rate
+    const connectors = applicableRules[0].connectors
+      .filter(c => this.isConnectorHealthy(c.connector))
+      .sort((a, b) => {
+        const aMetrics = this.metrics.get(a.connector);
+        const bMetrics = this.metrics.get(b.connector);
+        return (bMetrics?.success_rate || 0) - (aMetrics?.success_rate || 0);
+      });
+
+    if (connectors.length === 0) {
+      return this.fallbackRouting(context, config);
+    }
+
+    return {
+      selected_connector: connectors[0].connector,
+      merchant_connector_id: connectors[0].merchant_connector_id,
+      algorithm_used: 'performance',
+      rule_applied: applicableRules[0].name,
+      fallback_used: false,
+      decision_timestamp: new Date().toISOString(),
+      routing_profile_id: config.profile_id,
+      alternative_connectors: connectors.slice(1).map(c => c.connector)
+    };
+  }
+
+  private async routeByCost(context: RoutingContext, config: RoutingConfig): Promise<RoutingDecision> {
+    // Cost-based routing (would need cost data from connectors)
+    return this.routeByPriority(context, config);
+  }
+
+  private findApplicableRules(context: RoutingContext, rules: RoutingRule[]): RoutingRule[] {
+    return rules.filter(rule => rule.enabled && this.evaluateRule(context, rule));
+  }
+
+  private evaluateRule(context: RoutingContext, rule: RoutingRule): boolean {
+    const conditions = rule.conditions;
+
+    // Resource type check
+    if (conditions.resourceType && context.resourceType && !conditions.resourceType.includes(context.resourceType)) {
+      return false;
+    }
+
+    // Region check
+    if (conditions.region && context.region && !conditions.region.includes(context.region)) {
+      return false;
+    }
+
+    // Resource size range check
+    if (conditions.resourceSize && context.resourceSize !== undefined) {
+      if (conditions.resourceSize.min && context.resourceSize < conditions.resourceSize.min) return false;
+      if (conditions.resourceSize.max && context.resourceSize > conditions.resourceSize.max) return false;
+    }
+
+    // Country check
+    if (conditions.country && context.country && !conditions.country.includes(context.country)) {
+      return false;
+    }
+
+    // Tenant check
+    if (conditions.tenantId && context.tenantId && !conditions.tenantId.includes(context.tenantId)) {
+      return false;
+    }
+
+    // Priority check
+    if (conditions.priority && context.priority && !conditions.priority.includes(context.priority)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  private isConnectorHealthy(connectorId: string): boolean {
+    const circuitBreaker = this.circuitBreakers.get(connectorId);
+    return !circuitBreaker || circuitBreaker.state !== 'open';
+  }
+
+  private fallbackRouting(context: RoutingContext, config: RoutingConfig): RoutingDecision {
+    if (!config.fallback_routing?.enabled || !config.fallback_routing.connectors.length) {
+      throw new Error('No healthy connectors available and fallback routing disabled');
+    }
+
+    const healthyFallbacks = config.fallback_routing.connectors.filter(c => this.isConnectorHealthy(c));
+    
+    if (healthyFallbacks.length === 0) {
+      throw new Error('No healthy fallback connectors available');
+    }
+
+    return {
+      selected_connector: healthyFallbacks[0],
+      algorithm_used: 'priority',
+      fallback_used: true,
+      decision_timestamp: new Date().toISOString(),
+      routing_profile_id: config.profile_id,
+      alternative_connectors: healthyFallbacks.slice(1)
+    };
+  }
+
+  async updateMetrics(connectorId: string, success: boolean, responseTime: number, resourceSize?: number): Promise<void> {
+    // Try to get the existing metrics or create a new, fully-typed record
+    const existing = this.metrics.get(connectorId) || {
+      connector_name: connectorId,
+      success_rate: 0,
+      total_volume: 0,
+      successful_payments: 0,
+      failed_payments: 0,
+      avg_response_time_ms: 0,
+      p95_response_time_ms: 0,
+      total_amount_processed: 0,
+      avg_ticket_size: 0,
+      window_start: new Date().toISOString(),
+      window_end: new Date().toISOString(),
+      circuit_breaker_status: 'closed' as const,
+      consecutive_failures: 0,
+      // Required additional properties to fulfill ConnectorMetrics interface
+      total_requests: 0,
+      successful_requests: 0,
+      failed_requests: 0,
+      total_resources_processed: 0,
+      avg_resource_size: 0,
+    };
+
+    // Incremental updates
+    existing.total_volume = (existing.total_volume || 0) + 1;
+    existing.total_requests = (existing.total_requests || 0) + 1;
+    existing.total_resources_processed = (existing.total_resources_processed || 0) + (resourceSize || 0);
+
+    existing.total_amount_processed = (existing.total_amount_processed || 0) + (resourceSize || 0);
+
+    if (success) {
+      existing.successful_payments = (existing.successful_payments || 0) + 1;
+      existing.successful_requests = (existing.successful_requests || 0) + 1;
+    } else {
+      existing.failed_payments = (existing.failed_payments || 0) + 1;
+      existing.failed_requests = (existing.failed_requests || 0) + 1;
+    }
+
+    existing.success_rate =
+      (existing.successful_payments || 0) / (existing.total_volume || 1);
+    existing.avg_ticket_size =
+      (existing.total_amount_processed || 0) / (existing.total_volume || 1);
+
+    existing.avg_resource_size =
+      (existing.total_resources_processed || 0) / (existing.total_requests || 1);
+
+    // For response times, maintain a very basic moving average
+    if (existing.avg_response_time_ms && existing.total_volume > 1) {
+      existing.avg_response_time_ms =
+        ((existing.avg_response_time_ms * (existing.total_volume - 1)) + responseTime) /
+        existing.total_volume;
+    } else {
+      existing.avg_response_time_ms = responseTime;
+    }
+
+    // For P95: This would need proper history tracking. Use the current value as a placeholder.
+    existing.p95_response_time_ms = existing.avg_response_time_ms;
+
+    // Optionally update window timestamps
+    existing.window_end = new Date().toISOString();
+
+    // The actual circuit breaker status and consecutive_failures will be updated in the updateCircuitBreaker call below
+    // but set them from existing state (if available)
+    const cb = this.circuitBreakers.get(connectorId);
+    if (cb) {
+      existing.circuit_breaker_status = cb.state as typeof existing.circuit_breaker_status;
+      existing.consecutive_failures = cb.failures || 0;
+    }
+
+    this.metrics.set(connectorId, existing);
+    
+
+    // Update circuit breaker after metrics
+    this.updateCircuitBreaker(connectorId, success);
+
+    // Set updated circuit breaker fields again after it might have changed
+    const cbUpdated = this.circuitBreakers.get(connectorId);
+    if (cbUpdated) {
+      existing.circuit_breaker_status = cbUpdated.state as typeof existing.circuit_breaker_status;
+      existing.consecutive_failures = cbUpdated.failures || 0;
+      this.metrics.set(connectorId, existing);
+    }
+  }
+
+  private updateCircuitBreaker(connectorId: string, success: boolean): void {
+    const cb = this.circuitBreakers.get(connectorId) || { state: 'closed', failures: 0 };
+
+    if (success) {
+      cb.failures = 0;
+      cb.state = 'closed';
+    } else {
+      cb.failures++;
+      cb.lastFailure = new Date();
+      
+      if (cb.failures >= 5) { // Configurable threshold
+        cb.state = 'open';
+      }
+    }
+
+    this.circuitBreakers.set(connectorId, cb);
+  }
+
+  async getConnectorHealth(connectorId: string): Promise<ConnectorMetrics> {
+    return this.metrics.get(connectorId) || {
+      connector_name: connectorId,
+      success_rate: 0,
+      total_volume: 0,
+      successful_payments: 0,
+      failed_payments: 0,
+      avg_response_time_ms: 0,
+      p95_response_time_ms: 0,
+      total_amount_processed: 0,
+      avg_ticket_size: 0,
+      window_start: new Date().toISOString(),
+      window_end: new Date().toISOString(),
+      circuit_breaker_status: 'closed' as const,
+      consecutive_failures: 0,
+
+      // Add missing required properties for ConnectorMetrics type
+      total_requests: 0,
+      successful_requests: 0,
+      failed_requests: 0,
+      total_resources_processed: 0,
+      avg_resource_size: 0,
+    };
+
+  }
+
+  async validateConfig(config: RoutingConfig): Promise<{ valid: boolean; errors: string[] }> {
+    const errors: string[] = [];
+
+    if (!config.profile_id) {
+      errors.push('Profile ID is required');
+    }
+
+    if (!config.algorithm?.type) {
+      errors.push('Routing algorithm type is required');
+    }
+
+    if (!config.algorithm?.data?.length) {
+      errors.push('At least one routing rule is required');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview ETO Framework Connector Engine
+ * @description Clean plugin-first connector engine with Hyperswitch-style routing
+ */
+
+// ===== CORE ENGINE =====
+export { ConnectorEngine } from "./engine/clean-connector-engine";
+export type { 
+  ConnectorRegistry,
+  OperationGroup,
+  OperationGroups,
+  EngineConfig,
+  GroupResult
+} from "./engine/clean-connector-engine";
+
+// ===== PLUGIN TYPES =====
+export {
+  type ConnectorPlugin,
+  type OperationType,
+  AbstractConnectorPlugin
+} from "./types/connector-plugin";
+
+// ===== ROUTING TYPES =====
+export type {
+  RoutingConfig,
+  RoutingContext,
+  RoutingDecision,
+  ConnectorMetrics,
+  RoutingRule,
+  ConnectorChoice,
+  RoutingAlgorithm
+} from "./types/routing-config";

package/src/types/connector-plugin.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Clean Connector Plugin Design - First Principles
+ */
+
+// ===== OPERATION TYPE =====
+export interface OperationType {
+  input: any;
+  output: any;
+}
+
+// ===== CONNECTOR PLUGIN =====
+export interface ConnectorPlugin<TOperations extends Record<string, OperationType> = Record<string, OperationType>> {
+  getName(): string;
+  getVersion(): string;
+  
+  // Operations receive config at execution time
+  operations: {
+    [K in keyof TOperations]: (
+      input: TOperations[K]['input'], 
+      config: any
+    ) => Promise<TOperations[K]['output']>
+  };
+}
+
+// ===== ABSTRACT BASE =====
+export abstract class AbstractConnectorPlugin<TOperations extends Record<string, OperationType> = Record<string, OperationType>> 
+  implements ConnectorPlugin<TOperations> {
+  
+  abstract getName(): string;
+  abstract getVersion(): string;
+  abstract operations: {
+    [K in keyof TOperations]: (input: TOperations[K]['input'], config: any) => Promise<TOperations[K]['output']>
+  };
+}

package/src/types/index.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Clean Connector Engine Types
+ */
+
+export { type ConnectorPlugin, type OperationType, AbstractConnectorPlugin } from "./connector-plugin";

package/src/types/routing-config.ts

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Generic Routing Configuration (Not Payment-Specific)
+ */
+
+// ===== GENERIC ROUTING CONTEXT =====
+export interface RoutingContext {
+  // Generic operation context
+  operation?: string;
+  domain?: string;
+  
+  // Geographic context
+  region?: string;
+  country?: string;
+  
+  // Business context  
+  userId?: string;
+  tenantId?: string;
+  priority?: 'low' | 'normal' | 'high';
+  
+  // Resource context
+  resourceType?: string;
+  resourceSize?: number;
+  
+  // Custom metadata for any domain
+  metadata?: Record<string, any>;
+  
+  // Routing overrides
+  forceConnector?: string;
+  skipRouting?: boolean;
+}
+
+// ===== GENERIC ROUTING RULE =====
+export interface RoutingRule {
+  name: string;
+  description?: string;
+  
+  // Generic conditions (not payment-specific)
+  conditions: {
+    // Resource conditions
+    resourceType?: string[];
+    resourceSize?: { min?: number; max?: number };
+    
+    // Geographic conditions
+    region?: string[];
+    country?: string[];
+    
+    // Business conditions
+    tenantId?: string[];
+    priority?: string[];
+    
+    // Time-based conditions
+    timeOfDay?: { start?: string; end?: string };
+    dayOfWeek?: string[];
+    
+    // Custom field conditions
+    customFields?: Record<string, any>;
+    
+    // Metadata conditions
+    metadata?: Record<string, any>;
+  };
+  
+  // Connector selection
+  connectors: ConnectorChoice[];
+  
+  // Rule metadata
+  enabled: boolean;
+  created_at: string;
+  modified_at: string;
+}
+
+// ===== CONNECTOR CHOICE =====
+export interface ConnectorChoice {
+  connector: string;
+  merchant_connector_id?: string;
+  
+  // Selection criteria
+  priority?: number;
+  weight?: number;
+  
+  // Resource constraints
+  maxConcurrency?: number;
+  maxResourceSize?: number;
+  
+  // Geographic constraints
+  supportedRegions?: string[];
+  supportedCountries?: string[];
+}
+
+// ===== ROUTING ALGORITHM =====
+export type RoutingAlgorithm = 
+  | 'priority'           // Priority-based routing
+  | 'volume_split'       // Volume-based distribution  
+  | 'advanced'           // Rule-based routing
+  | 'cost_optimization'  // Cost-aware routing
+  | 'performance'        // Performance-based routing
+  | 'load_balancing'     // Load balancing
+  | 'region_based'       // Geographic routing
+
+// ===== ROUTING CONFIGURATION =====
+export interface RoutingConfig {
+  profile_id: string;
+  name: string;
+  description?: string;
+  
+  // Generic routing algorithm
+  algorithm: {
+    type: RoutingAlgorithm;
+    data: RoutingRule[];
+  };
+  
+  // Fallback configuration
+  fallback_routing?: {
+    enabled: boolean;
+    connectors: string[];
+  };
+  
+  // Circuit breaker
+  circuit_breaker?: {
+    failure_threshold: number;
+    recovery_time_seconds: number;
+    max_retries: number;
+  };
+  
+  // Metadata
+  created_at: string;
+  modified_at: string;
+  version: number;
+}
+
+// ===== CONNECTOR METRICS =====
+export interface ConnectorMetrics {
+  connector_name: string;
+  
+  // Success metrics
+  success_rate: number;
+  total_requests: number;
+  successful_requests: number;
+  failed_requests: number;
+  
+  // Volume metrics (for payment-specific routing)
+  total_volume?: number;
+  successful_payments?: number;
+  failed_payments?: number;
+  total_amount_processed?: number;
+  avg_ticket_size?: number;
+  
+  // Performance metrics  
+  avg_response_time_ms: number;
+  p95_response_time_ms: number;
+  
+  // Resource metrics
+  total_resources_processed: number;
+  avg_resource_size: number;
+  
+  // Time window
+  window_start: string;
+  window_end: string;
+  
+  // Circuit breaker state
+  circuit_breaker_status: 'closed' | 'open' | 'half_open';
+  consecutive_failures: number;
+  last_failure_time?: string;
+}
+
+// ===== ROUTING DECISION =====
+export interface RoutingDecision {
+  selected_connector: string;
+  merchant_connector_id?: string;
+  
+  // Decision context
+  algorithm_used: RoutingAlgorithm;
+  rule_applied?: string;
+  fallback_used: boolean;
+  
+  // Routing metadata
+  decision_timestamp: string;
+  routing_profile_id: string;
+  
+  // Alternative connectors (for fallback)
+  alternative_connectors: string[];
+}
+
+// ===== ROUTING ENGINE INTERFACE =====
+export interface RoutingEngine {
+  // Route request to best connector
+  route(context: RoutingContext, config: RoutingConfig): Promise<RoutingDecision>;
+  
+  // Update connector metrics
+  updateMetrics(connectorId: string, success: boolean, responseTime: number, resourceSize?: number): Promise<void>;
+  
+  // Get connector health
+  getConnectorHealth(connectorId: string): Promise<ConnectorMetrics>;
+  
+  // Validate routing config
+  validateConfig(config: RoutingConfig): Promise<{ valid: boolean; errors: string[] }>;
+}

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../_tsconfig.base.json"
+}