@etohq/connector-engine 1.5.1-alpha.4

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @etohq/connector-engine@0.0.1 build /Users/solarsoft0/workspace/obigtech/shopabox/shopabox-platform-api/eto/packages/core/connector-engine
+> tsc
+

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @etohq/connector-engine

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Etohq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# ETO Framework Connector Engine
+
+A universal, type-safe connector engine with operation groups for orchestrating cross-domain operations.
+
+## 🎯 Overview
+
+The ETO Connector Engine enables you to:
+- **Orchestrate operations** across multiple domains (meetings, logistics, commerce)
+- **Maintain full type safety** with compile-time validation
+- **Configure flexible behaviors** (execute all, route by domain, first success)
+- **Compose workflows** seamlessly with ETO framework
+- **Support union return types** (steps or promises) from plugins
+
+## 🏗️ Architecture
+
+### Two-Parameter Configuration
+```typescript
+const engine = ConnectorEngine(connectorTypes, operationGroups);
+```
+
+1. **Connector Types**: Define domain operations with input/output types
+2. **Operation Groups**: Define orchestration behavior across domains
+
+### Auto-Generated Methods
+The engine generates type-safe methods like:
+- `executeResourceCheckAvailability()` - Route by domain
+- `executeInternalCheckAvailability()` - Execute all domains
+- `executeExternalReserveResource()` - First success behavior
+
+## 🚀 Quick Start
+
+### 1. Define Connector Types
+```typescript
+const connectorTypes = {
+  meetings: {
+    checkAvailability: {
+      input: { resourceType: string; timeSlot: { start: Date; end: Date } },
+      output: { available: boolean; conflicts: any[] }
+    }
+  },
+  logistics: {
+    checkAvailability: {
+      input: { vehicleType: string; timeSlot: { start: Date; end: Date } },
+      output: { available: boolean; vehicles: any[] }
+    }
+  }
+} as const;
+```
+
+### 2. Define Operation Groups
+```typescript
+const operationGroups = {
+  resource: {
+    domains: ['meetings', 'logistics'],
+    operations: ['checkAvailability'],
+    options: { behavior: 'route_by_domain' }
+  }
+} as const;
+```
+
+### 3. Create Engine
+```typescript
+const engine = ConnectorEngine(connectorTypes, operationGroups);
+```
+
+### 4. Use Type-Safe Methods
+```typescript
+// ✅ Domain optional - uses operation group default
+const result = await engine.executeResourceCheckAvailability({
+  // No domain needed - operation group routes to default domain
+  resourceType: 'conference_room',
+  timeSlot: { start: new Date(), end: new Date() }
+});
+
+// ✅ Domain override when needed
+const specificResult = await engine.executeResourceCheckAvailability({
+  domain: 'logistics', // Optional override - takes precedence
+  resourceType: 'delivery_truck',
+  timeSlot: { start: new Date(), end: new Date() }
+});
+```
+
+## 📋 Operation Group Behaviors
+
+### `route_by_domain`
+Routes to specific domain. Domain is optional - uses group default or input override:
+```typescript
+{
+  behavior: 'route_by_domain',
+  connectorId?: 'specific-connector'
+}
+
+// Usage:
+await engine.executeResourceCheckAvailability({
+  // domain optional - uses group's first domain
+  resourceType: 'room'
+});
+
+await engine.executeResourceCheckAvailability({
+  domain: 'meetings', // Optional override
+  resourceType: 'room'
+});
+```
+
+### `execute_all`
+Executes all domains in parallel. No domain parameter needed:
+```typescript
+{
+  behavior: 'execute_all',
+  timeout: 30000,
+  retries: 2
+}
+
+// Usage:
+await engine.executeInternalCheckAvailability({
+  // No domain field - executes all group domains
+  resourceType: 'any_resource'
+});
+```
+
+### `first_success`
+Executes domains until first success. No domain parameter needed:
+```typescript
+{
+  behavior: 'first_success',
+  priority: 1
+}
+
+// Usage:
+await engine.executeExternalReserveResource({
+  // No domain field - tries domains until success
+  resourceType: 'resource'
+});
+```
+
+## 🔧 Plugin Development
+
+### Simple Plugin (Returns Promise)
+```typescript
+class SimplePlugin extends BaseConnectorPlugin {
+  async checkAvailability(config, input, { container }) {
+    const service = container.resolve(Modules.BOOKING);
+    return await service.findAvailability(input);
+  }
+}
+```
+
+### Advanced Plugin (Returns Step)
+```typescript
+class AdvancedPlugin extends BaseConnectorPlugin {
+  checkAvailability(config, input, { container }) {
+    return createStep("advanced-check", async (stepInput, { container }) => {
+      // Complex logic with compensation
+      const result = await this.complexCheck(stepInput, container);
+      return new StepResponse(result);
+    });
+  }
+}
+```
+
+## 📊 Type Safety Features
+
+### Input Type Inference
+- **route_by_domain**: Union of domain inputs + domain field
+- **execute_all**: Intersection of all domain inputs
+
+### Output Type Inference
+- **route_by_domain**: Single domain output
+- **execute_all**: OperationGroupResult with all domain results
+
+### Compile-Time Validation
+- Domain names are type-checked
+- Operation names are validated
+- Input/output types are enforced
+
+## 🎨 Advanced Examples
+
+See `/examples/booking-example.ts` for comprehensive usage examples including:
+- Multi-domain resource allocation
+- Cross-domain notifications
+- Priority-based execution
+- Error handling and retries
+
+## 🧪 Testing
+
+Run the test suite:
+```bash
+npm test
+# or
+node examples/booking-test.ts
+```
+
+## 📚 API Reference
+
+### ConnectorEngine Factory
+```typescript
+function ConnectorEngine<TConnectorTypes, TOperationGroups>(
+  connectorTypes: TConnectorTypes,
+  operationGroups?: TOperationGroups
+): ConnectorEngineImpl
+```
+
+### Operation Group Configuration
+```typescript
+interface OperationGroupsConfig {
+  [groupName: string]: {
+    domains: string[];
+    operations: string[];
+    options: {
+      behavior: 'execute_all' | 'route_by_domain' | 'first_success';
+      connectorId?: string;
+      priority?: number;
+      timeout?: number;
+      retries?: number;
+    };
+  };
+}
+```
+
+## 🔗 Integration with ETO Framework
+
+The connector engine seamlessly integrates with ETO workflows:
+
+```typescript
+const workflow = createWorkflow("booking", async (input) => {
+  const availability = await engine.executeResourceCheckAvailability({
+    domain: 'meetings',
+    resourceType: input.resourceType,
+    timeSlot: input.timeSlot
+  }).runAsStep({ input });
+  
+  return new WorkflowResponse(availability);
+});
+```
+
+## 🎯 Use Cases
+
+- **Resource Booking Systems**: Meetings, rooms, equipment
+- **Logistics Management**: Vehicle scheduling, route optimization
+- **E-commerce Operations**: Inventory, fulfillment, payments
+- **Multi-tenant Applications**: Domain-specific operations
+- **Microservices Orchestration**: Cross-service coordination
+
+## 🤝 Contributing
+
+1. Follow ETO framework patterns
+2. Maintain full type safety
+3. Add comprehensive tests
+4. Update documentation
+
+## 📄 License
+
+Part of the ETO Framework ecosystem.

package/dist/engine/clean-connector-engine.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Clean Connector Engine - First Principles Implementation
+ */
+import { ConnectorPlugin } from "../types/connector-plugin";
+import { RoutingConfig, RoutingContext } from "../types/routing-config";
+import { ReturnWorkflow } from "@etohq/framework/workflows-sdk";
+export interface CleanConnectorRegistry {
+    [connectorId: string]: ConnectorPlugin;
+}
+export interface CleanOperationGroup {
+    connectors: string[];
+    operations: string[];
+    options: {
+        behavior: "execute_all" | "first_success" | "route_by_domain";
+        timeout?: number;
+        retries?: number;
+    };
+}
+export interface CleanOperationGroups {
+    [groupName: string]: CleanOperationGroup;
+}
+export interface CleanEngineConfig {
+    configLoader: (connectorId: string) => Promise<any>;
+    routingConfigLoader?: (groupId: string) => Promise<RoutingConfig>;
+}
+export interface CleanGroupResult<T> {
+    groupName: string;
+    executedConnectors: string[];
+    results: Record<string, T>;
+    metadata: {
+        behavior: string;
+        executionTime: number;
+        errors?: Record<string, Error>;
+        routingDecision: any;
+        algorithm: any;
+        ruleApplied: string | undefined;
+    };
+}
+type AutoGroupMethods<TConnectors extends CleanConnectorRegistry> = {
+    [K in keyof TConnectors]: TConnectors[K] extends {
+        getName(): infer Domain;
+    } ? {
+        [Operation in keyof TConnectors[K]["operations"] as `execute${Capitalize<Domain & string>}${Capitalize<Operation & string>}`]: (input: TConnectors[K]["operations"][Operation] extends (input: infer I, config: any) => any ? I : never, context?: RoutingContext) => ReturnWorkflow<TConnectors[K]["operations"][Operation] extends (input: infer I, config: any) => any ? I : never, CleanGroupResult<TConnectors[K]["operations"][Operation] extends (input: any, config: any) => Promise<infer O> ? O : never>, [
+        ]>;
+    } : {};
+}[keyof TConnectors];
+type GroupMethods<TGroups extends CleanOperationGroups> = {
+    [GroupName in keyof TGroups]: {
+        [Operation in TGroups[GroupName]["operations"][number] as `execute${Capitalize<GroupName & string>}${Capitalize<Operation & string>}`]: (input: any, context?: RoutingContext) => ReturnWorkflow<any, CleanGroupResult<any>, []>;
+    };
+}[keyof TGroups];
+type ConnectorMethods<TConnectors extends CleanConnectorRegistry> = {
+    [ConnectorId in keyof TConnectors]: {
+        [Operation in keyof TConnectors[ConnectorId]["operations"] as `execute${Capitalize<ConnectorId & string>}${Capitalize<Operation & string>}`]: (input: TConnectors[ConnectorId]["operations"][Operation] extends (input: infer I, config: any) => any ? I : never) => ReturnWorkflow<TConnectors[ConnectorId]["operations"][Operation] extends (input: infer I, config: any) => any ? I : never, TConnectors[ConnectorId]["operations"][Operation] extends (input: any, config: any) => Promise<infer O> ? O : never, [
+        ]>;
+    };
+}[keyof TConnectors];
+declare class ConnectorEngineImpl<TConnectors extends CleanConnectorRegistry, TGroups extends CleanOperationGroups> {
+    private connectors;
+    private groups;
+    private configLoader;
+    private routingConfigLoader?;
+    private routingEngine;
+    constructor(connectors: TConnectors, groups: TGroups, config: CleanEngineConfig);
+    private generateDynamicMethods;
+    private generateConnectorMethods;
+    private generateGroupMethods;
+    private generateAutoGroups;
+    private createAutoGroupWorkflow;
+    private capitalize;
+    private createConnectorWorkflow;
+    private createSmartGroupWorkflow;
+    private extractRoutingContext;
+    private extractCustomFields;
+    private tryFallbackConnectors;
+    execute<ConnectorId extends keyof TConnectors, Operation extends keyof TConnectors[ConnectorId]["operations"]>(connectorId: ConnectorId, operation: Operation, input: any): Promise<any>;
+    executeGroup<GroupName extends keyof TGroups>(groupName: GroupName, operation: string, input: any): Promise<CleanGroupResult<any>>;
+}
+export declare function ConnectorEngine<TConnectors extends CleanConnectorRegistry, TGroups extends CleanOperationGroups = {}>(connectors: TConnectors, groups?: TGroups, config?: CleanEngineConfig): ConnectorEngineImpl<TConnectors, TGroups> & ConnectorMethods<TConnectors> & AutoGroupMethods<TConnectors> & GroupMethods<TGroups>;
+export type { CleanConnectorRegistry as ConnectorRegistry, CleanOperationGroup as OperationGroup, CleanOperationGroups as OperationGroups, CleanEngineConfig as EngineConfig, CleanGroupResult as GroupResult, };
+//# sourceMappingURL=clean-connector-engine.d.ts.map

package/dist/engine/clean-connector-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-connector-engine.d.ts","sourceRoot":"","sources":["../../src/engine/clean-connector-engine.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAEvE,OAAO,EAKL,cAAc,EAEf,MAAM,gCAAgC,CAAA;AAIvC,MAAM,WAAW,sBAAsB;IACrC,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAAA;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,OAAO,EAAE;QACP,QAAQ,EAAE,aAAa,GAAG,eAAe,GAAG,iBAAiB,CAAA;QAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;CACF;AAED,MAAM,WAAW,oBAAoB;IACnC,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAAA;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;IACnD,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAA;CAClE;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,kBAAkB,EAAE,MAAM,EAAE,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAC1B,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAA;QAChB,aAAa,EAAE,MAAM,CAAA;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;QAC9B,eAAe,EAAE,GAAG,CAAA;QACpB,SAAS,EAAE,GAAG,CAAA;QACd,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;KAChC,CAAA;CACF;AAKD,KAAK,gBAAgB,CAAC,WAAW,SAAS,sBAAsB,IAAI;KACjE,CAAC,IAAI,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC,SAAS;QAAE,OAAO,IAAI,MAAM,MAAM,CAAA;KAAE,GACxE;SACG,SAAS,IAAI,MAAM,WAAW,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,UAAU,UAAU,CACtE,MAAM,GAAG,MAAM,CAChB,GAAG,UAAU,CAAC,SAAS,GAAG,MAAM,CAAC,EAAE,GAAG,CACrC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,SAAS,CACrD,KAAK,EAAE,MAAM,CAAC,EACd,MAAM,EAAE,GAAG,KACR,GAAG,GACJ,CAAC,GACD,KAAK,EACT,OAAO,CAAC,EAAE,cAAc,KACrB,cAAc,CACjB,WAAW,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,SAAS,CAC9C,KAAK,EAAE,MAAM,CAAC,EACd,MAAM,EAAE,GAAG,KACR,GAAG,GACJ,CAAC,GACD,KAAK,EACT,gBAAgB,CACd,WAAW,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,SAAS,CAC9C,KAAK,EAAE,GAAG,EACV,MAAM,EAAE,GAAG,KACR,OAAO,CAAC,MAAM,CAAC,CAAC,GACjB,CAAC,GACD,KAAK,CACV,EACD;SAAE,CACH;KACF,GACD,EAAE;CACP,CAAC,MAAM,WAAW,CAAC,CAAA;AAGpB,KAAK,YAAY,CAAC,OAAO,SAAS,oBAAoB,IAAI;KACvD,SAAS,IAAI,MAAM,OAAO,GAAG;SAC3B,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,IAAI,UAAU,UAAU,CAC5E,SAAS,GAAG,MAAM,CACnB,GAAG,UAAU,CAAC,SAAS,GAAG,MAAM,CAAC,EAAE,GAAG,CACrC,KAAK,EAAE,GAAG,EACV,OAAO,CAAC,EAAE,cAAc,KACrB,cAAc,CAAC,GAAG,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;KACpD;CACF,CAAC,MAAM,OAAO,CAAC,CAAA;AAEhB,KAAK,gBAAgB,CAAC,WAAW,SAAS,sBAAsB,IAAI;KACjE,WAAW,IAAI,MAAM,WAAW,GAAG;SACjC,SAAS,IAAI,MAAM,WAAW,CAAC,WAAW,CAAC,CAAC,YAAY,CAAC,IAAI,UAAU,UAAU,CAChF,WAAW,GAAG,MAAM,CACrB,GAAG,UAAU,CAAC,SAAS,GAAG,MAAM,CAAC,EAAE,GAAG,CACrC,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,SAAS,CAC/D,KAAK,EAAE,MAAM,CAAC,EACd,MAAM,EAAE,GAAG,KACR,GAAG,GACJ,CAAC,GACD,KAAK,KACN,cAAc,CACjB,WAAW,CAAC,WAAW,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,SAAS,CACxD,KAAK,EAAE,MAAM,CAAC,EACd,MAAM,EAAE,GAAG,KACR,GAAG,GACJ,CAAC,GACD,KAAK,EACT,WAAW,CAAC,WAAW,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,SAAS,CACxD,KAAK,EAAE,GAAG,EACV,MAAM,EAAE,GAAG,KACR,OAAO,CAAC,MAAM,CAAC,CAAC,GACjB,CAAC,GACD,KAAK,EACT;SAAE,CACH;KACF;CACF,CAAC,MAAM,WAAW,CAAC,CAAA;AAIpB,cAAM,mBAAmB,CACvB,WAAW,SAAS,sBAAsB,EAC1C,OAAO,SAAS,oBAAoB;IAEpC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAuC;IAC3D,OAAO,CAAC,mBAAmB,CAAC,CAA6C;IACzE,OAAO,CAAC,aAAa,CAAe;gBAGlC,UAAU,EAAE,WAAW,EACvB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,iBAAiB;IAa3B,OAAO,CAAC,sBAAsB;IAK9B,OAAO,CAAC,wBAAwB;IAchC,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,kBAAkB;IAmD1B,OAAO,CAAC,uBAAuB;IAyF/B,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,uBAAuB;IAgC/B,OAAO,CAAC,wBAAwB;IAkHhC,OAAO,CAAC,qBAAqB;IAqD7B,OAAO,CAAC,mBAAmB;YA2Bb,qBAAqB;IAkE7B,OAAO,CACX,WAAW,SAAS,MAAM,WAAW,EACrC,SAAS,SAAS,MAAM,WAAW,CAAC,WAAW,CAAC,CAAC,YAAY,CAAC,EAC9D,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAiBrE,YAAY,CAAC,SAAS,SAAS,MAAM,OAAO,EAChD,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,GAAG,GACT,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;CAWlC;AAID,wBAAgB,eAAe,CAC7B,WAAW,SAAS,sBAAsB,EAC1C,OAAO,SAAS,oBAAoB,GAAG,EAAE,EAEzC,UAAU,EAAE,WAAW,EACvB,MAAM,CAAC,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,iBAAiB,GACzB,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC,GAC1C,gBAAgB,CAAC,WAAW,CAAC,GAC7B,gBAAgB,CAAC,WAAW,CAAC,GAC7B,YAAY,CAAC,OAAO,CAAC,CAqBtB;AAID,YAAY,EACV,sBAAsB,IAAI,iBAAiB,EAC3C,mBAAmB,IAAI,cAAc,EACrC,oBAAoB,IAAI,eAAe,EACvC,iBAAiB,IAAI,YAAY,EACjC,gBAAgB,IAAI,WAAW,GAChC,CAAA"}