@etohq/connector-engine 1.5.1-alpha.4 → 1.5.1-alpha.5

package/.turbo/turbo-build.log

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

package/README.md

@@ -1,253 +1,253 @@
-# ETO Framework Connector Engine
+# @etohq/connector-engine
 
-A universal, type-safe connector engine with operation groups for orchestrating cross-domain operations.
+Type-safe connector orchestration for Eto workflows.
 
-## 🎯 Overview
+## 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
+`@etohq/connector-engine` provides:
 
-## 🏗️ Architecture
+- registers connector plugins with typed operations,
+- auto-generates strongly typed execution methods,
+- supports grouped execution with routing and fallback,
+- composes directly with `@etohq/framework/workflows-sdk`.
+- includes a strict runtime API with middleware and schema validation.
 
-### Two-Parameter Configuration
-```typescript
-const engine = ConnectorEngine(connectorTypes, operationGroups);
+## Core Concepts
+
+- `ConnectorPlugin`: plugin contract (`getName`, `getVersion`, `operations`).
+- `operations`: map of async handlers `(input, config) => output`.
+- `ConnectorEngine(connectors, groups?, config?)`: engine factory.
+- `configLoader`: runtime connector config source.
+- `routingConfigLoader`: optional routing source for grouped execution.
+
+## Install
+
+```bash
+pnpm add @etohq/connector-engine
 ```
 
-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[] }
-    }
+## Plugin Contract
+
+```ts
+import {
+  AbstractConnectorPlugin,
+  type OperationType,
+} from "@etohq/connector-engine"
+
+type PaymentOps = {
+  createCustomer: {
+    input: { email: string; entity_id: string }
+    output: { customer_id: string; psp_customer_id: string }
   }
-} as const;
-```
+  createVirtualAccount: {
+    input: { customer_id: string; currency: string }
+    output: { account_id: string; account_number: string }
+  }
+}
 
-### 2. Define Operation Groups
-```typescript
-const operationGroups = {
-  resource: {
-    domains: ['meetings', 'logistics'],
-    operations: ['checkAvailability'],
-    options: { behavior: 'route_by_domain' }
+class PaystackPlugin extends AbstractConnectorPlugin<PaymentOps> {
+  getName() {
+    return "payment"
   }
-} as const;
-```
 
-### 3. Create Engine
-```typescript
-const engine = ConnectorEngine(connectorTypes, operationGroups);
+  getVersion() {
+    return "1.0.0"
+  }
+
+  operations = {
+    createCustomer: async (input, config) => {
+      return {
+        customer_id: "cust_123",
+        psp_customer_id: "CUS_abc123",
+      }
+    },
+    createVirtualAccount: async (input, config) => {
+      return {
+        account_id: "va_123",
+        account_number: "1234567890",
+      }
+    },
+  }
+}
 ```
 
-### 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() }
-});
+## Create Engine (Workflow-First API)
+
+```ts
+import { ConnectorEngine } from "@etohq/connector-engine"
+
+const engine = ConnectorEngine(
+  {
+    paystack: new PaystackPlugin(),
+  },
+  {
+    payment: {
+      connectors: ["paystack"],
+      operations: ["createCustomer", "createVirtualAccount"],
+      options: {
+        behavior: "route_by_domain",
+      },
+    },
+  },
+  {
+    configLoader: async (connectorId) => {
+      // Fetch connector secrets/settings from DB or vault.
+      return { provider: connectorId }
+    },
+    routingConfigLoader: async (groupId) => {
+      // Optional dynamic routing profile from DB.
+      return {
+        profile_id: "default",
+        name: "default",
+        algorithm: { type: "priority", data: [] },
+        created_at: new Date().toISOString(),
+        modified_at: new Date().toISOString(),
+        version: 1,
+      }
+    },
+  }
+)
 ```
 
-## 📋 Operation Group Behaviors
+## Execute Operations
 
-### `route_by_domain`
-Routes to specific domain. Domain is optional - uses group default or input override:
-```typescript
-{
-  behavior: 'route_by_domain',
-  connectorId?: 'specific-connector'
-}
+### Per Connector
+
+Engine auto-generates methods from connector id + operation name:
 
-// Usage:
-await engine.executeResourceCheckAvailability({
-  // domain optional - uses group's first domain
-  resourceType: 'room'
-});
+- `executePaystackCreateCustomer`
+- `executePaystackCreateVirtualAccount`
 
-await engine.executeResourceCheckAvailability({
-  domain: 'meetings', // Optional override
-  resourceType: 'room'
-});
+```ts
+const wf = engine.executePaystackCreateCustomer()
+const { result } = await wf.run({
+  input: { entity_id: "ent_1", email: "dev@eto.dev" },
+})
 ```
 
-### `execute_all`
-Executes all domains in parallel. No domain parameter needed:
-```typescript
-{
-  behavior: 'execute_all',
-  timeout: 30000,
-  retries: 2
-}
+### Per Group/Domain
 
-// Usage:
-await engine.executeInternalCheckAvailability({
-  // No domain field - executes all group domains
-  resourceType: 'any_resource'
-});
-```
+Engine auto-generates methods from domain (`plugin.getName()`) + operation:
 
-### `first_success`
-Executes domains until first success. No domain parameter needed:
-```typescript
-{
-  behavior: 'first_success',
-  priority: 1
-}
+- `executePaymentCreateCustomer`
+- `executePaymentCreateVirtualAccount`
 
-// Usage:
-await engine.executeExternalReserveResource({
-  // No domain field - tries domains until success
-  resourceType: 'resource'
-});
+```ts
+const wf = engine.executePaymentCreateCustomer(
+  { entity_id: "ent_1", email: "dev@eto.dev" },
+  { country: "NG" }
+)
+
+const { result } = await wf.run({
+  input: { entity_id: "ent_1", email: "dev@eto.dev" },
+})
 ```
 
-## 🔧 Plugin Development
+## Group Behaviors
 
-### 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);
-  }
-}
-```
+`options.behavior` supports:
+
+- `route_by_domain`: use routing config + fallback connectors.
+- `execute_all`: execute all connectors in the group.
+- `first_success`: try connectors until first success.
+
+## Integration in Eto Workflows
+
+Use generated connector workflows inside regular Eto workflows:
+
+```ts
+import { createWorkflow, WorkflowResponse } from "@etohq/framework/workflows-sdk"
 
-### 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);
-    });
+export const createCustomerWorkflow = createWorkflow(
+  "create-customer",
+  (input) => {
+    const customer = engine.executePaymentCreateCustomer(
+      { entity_id: input.entity_id, email: input.email },
+      { country: input.country }
+    )(input)
+
+    return new WorkflowResponse(customer)
   }
-}
+)
 ```
 
-## 📊 Type Safety Features
+## Runtime Notes
 
-### Input Type Inference
-- **route_by_domain**: Union of domain inputs + domain field
-- **execute_all**: Intersection of all domain inputs
+- The engine itself has no built-in database.
+- DB-backed behavior is provided by your `configLoader` and `routingConfigLoader`.
+- Keep provider secrets outside code; load at runtime.
 
-### Output Type Inference
-- **route_by_domain**: Single domain output
-- **execute_all**: OperationGroupResult with all domain results
+## Runtime API (Single Primitive)
 
-### Compile-Time Validation
-- Domain names are type-checked
-- Operation names are validated
-- Input/output types are enforced
+Use `createRuntimeConnectorEngine` when you want one canonical primitive:
+`execute({ domain, operation, input, ... })`.
 
-## 🎨 Advanced Examples
+```ts
+import {
+  createRuntimeConnectorEngine,
+  type ConnectorExecuteRequest,
+} from "@etohq/connector-engine"
 
-See `/examples/booking-example.ts` for comprehensive usage examples including:
-- Multi-domain resource allocation
-- Cross-domain notifications
-- Priority-based execution
-- Error handling and retries
+const runtime = createRuntimeConnectorEngine({
+  configLoader: async (connectorId) => ({ provider: connectorId }),
+})
 
-## 🧪 Testing
+runtime.register("paystack", new PaystackPlugin())
 
-Run the test suite:
-```bash
-npm test
-# or
-node examples/booking-test.ts
+const result = await runtime.execute({
+  domain: "payment",
+  operation: "createCustomer",
+  input: { entity_id: "ent_1", email: "dev@eto.dev" },
+})
 ```
 
-## 📚 API Reference
+### Schema Protocol (Any Schema Library)
 
-### ConnectorEngine Factory
-```typescript
-function ConnectorEngine<TConnectorTypes, TOperationGroups>(
-  connectorTypes: TConnectorTypes,
-  operationGroups?: TOperationGroups
-): ConnectorEngineImpl
-```
+`execute` accepts `inputSchema` and `outputSchema` using a schema protocol:
 
-### 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;
-    };
-  };
-}
+- `parse(input) => value`, or
+- `safeParse(input) => { success, data | error }`
+
+```ts
+const result = await runtime.execute({
+  domain: "payment",
+  operation: "createCustomer",
+  input: payload,
+  inputSchema: customerInputSchema,   // zod/valibot/custom adapter
+  outputSchema: customerOutputSchema,
+})
 ```
 
-## 🔗 Integration with ETO Framework
+When schemas are provided, `execute` infers input/output types from them automatically.
 
-The connector engine seamlessly integrates with ETO workflows:
+You can also pre-register schemas per connector operation:
 
-```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);
-});
+```ts
+runtime.registerOperationSchemas("paystack", "createCustomer", {
+  inputSchema: customerInputSchema,
+  outputSchema: customerOutputSchema,
+})
 ```
 
-## 🎯 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
+### Middleware
 
-1. Follow ETO framework patterns
-2. Maintain full type safety
-3. Add comprehensive tests
-4. Update documentation
+```ts
+runtime.use({
+  name: "trace",
+  run: async (req, next) => {
+    const started = Date.now()
+    const result = await next()
+    console.log(req.operation, Date.now() - started)
+    return result
+  },
+})
+```
 
-## 📄 License
+## Troubleshooting
 
-Part of the ETO Framework ecosystem.
+- Missing generated method:
+  check connector id/domain name and operation key spelling.
+- Operation not found on connector:
+  ensure plugin exposes it under `operations`.
+- Group routing errors:
+  validate `routingConfigLoader` output shape and connector ids.

package/dist/engine/index.d.ts

@@ -3,5 +3,7 @@
  * @description Clean plugin-first connector engine
  */
 export { ConnectorEngine } from "./clean-connector-engine";
+export { RuntimeConnectorEngine, createRuntimeConnectorEngine, } from "./runtime-engine";
 export type { ConnectorRegistry, OperationGroup, OperationGroups, EngineConfig, GroupResult } from "./clean-connector-engine";
+export type { RuntimeEngineConfig } from "./runtime-engine";
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,WAAW,EACZ,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EACL,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/engine/index.js

@@ -4,7 +4,10 @@
  * @description Clean plugin-first connector engine
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConnectorEngine = void 0;
+exports.createRuntimeConnectorEngine = exports.RuntimeConnectorEngine = exports.ConnectorEngine = void 0;
 var clean_connector_engine_1 = require("./clean-connector-engine");
 Object.defineProperty(exports, "ConnectorEngine", { enumerable: true, get: function () { return clean_connector_engine_1.ConnectorEngine; } });
+var runtime_engine_1 = require("./runtime-engine");
+Object.defineProperty(exports, "RuntimeConnectorEngine", { enumerable: true, get: function () { return runtime_engine_1.RuntimeConnectorEngine; } });
+Object.defineProperty(exports, "createRuntimeConnectorEngine", { enumerable: true, get: function () { return runtime_engine_1.createRuntimeConnectorEngine; } });
 //# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,mEAA2D;AAAlD,yHAAA,eAAe,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,mEAA2D;AAAlD,yHAAA,eAAe,OAAA;AACxB,mDAG0B;AAFxB,wHAAA,sBAAsB,OAAA;AACtB,8HAAA,4BAA4B,OAAA"}

package/dist/engine/runtime-engine.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Runtime connector engine with middleware and schema protocol support.
+ */
+import { ConnectorPlugin } from "../types/connector-plugin";
+import { ConnectorExecuteRequest, ConnectorExecuteResult, ConnectorMiddleware, ConnectorOperationSchemas, InferSchemaOutput, SchemaProtocol } from "../types/runtime";
+export interface RuntimeEngineConfig {
+    configLoader?: (connectorId: string) => Promise<unknown>;
+}
+export declare class RuntimeConnectorEngine {
+    private connectors;
+    private middleware;
+    private configLoader;
+    private operationSchemas;
+    constructor(config?: RuntimeEngineConfig);
+    register(connectorId: string, plugin: ConnectorPlugin): this;
+    registerMany(connectors: Record<string, ConnectorPlugin>): this;
+    use(middleware: ConnectorMiddleware): this;
+    registerOperationSchemas<TInput, TOutput>(connectorId: string, operation: string, schemas: ConnectorOperationSchemas<TInput, TOutput>): this;
+    execute<TInputSchema extends SchemaProtocol<unknown> | undefined = undefined, TOutputSchema extends SchemaProtocol<unknown> | undefined = undefined, TInput = TInputSchema extends SchemaProtocol<unknown> ? InferSchemaOutput<TInputSchema> : unknown, TOutput = TOutputSchema extends SchemaProtocol<unknown> ? InferSchemaOutput<TOutputSchema> : unknown>(request: ConnectorExecuteRequest<TInput, TOutput> & {
+        inputSchema?: TInputSchema;
+        outputSchema?: TOutputSchema;
+    }): Promise<ConnectorExecuteResult<TOutput>>;
+    executeGroup<TInputSchema extends SchemaProtocol<unknown> | undefined = undefined, TOutputSchema extends SchemaProtocol<unknown> | undefined = undefined, TInput = TInputSchema extends SchemaProtocol<unknown> ? InferSchemaOutput<TInputSchema> : unknown, TOutput = TOutputSchema extends SchemaProtocol<unknown> ? InferSchemaOutput<TOutputSchema> : unknown>(request: Omit<ConnectorExecuteRequest<TInput, TOutput>, "connectorId"> & {
+        inputSchema?: TInputSchema;
+        outputSchema?: TOutputSchema;
+    }): Promise<ConnectorExecuteResult<TOutput>[]>;
+    private executeWithFallback;
+    private executeOnConnector;
+    private resolveSchemas;
+    private applySchema;
+    private selectConnectors;
+    private createErrorResult;
+    private makeRequestId;
+}
+export declare function createRuntimeConnectorEngine(config?: RuntimeEngineConfig): RuntimeConnectorEngine;
+//# sourceMappingURL=runtime-engine.d.ts.map

package/dist/engine/runtime-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-engine.d.ts","sourceRoot":"","sources":["../../src/engine/runtime-engine.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EACf,MAAM,kBAAkB,CAAA;AAEzB,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACzD;AAKD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,YAAY,CAA2C;IAC/D,OAAO,CAAC,gBAAgB,CAAoC;gBAEhD,MAAM,CAAC,EAAE,mBAAmB;IAIxC,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAK5D,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,IAAI;IAO/D,GAAG,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI;IAK1C,wBAAwB,CAAC,MAAM,EAAE,OAAO,EACtC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,yBAAyB,CAAC,MAAM,EAAE,OAAO,CAAC,GAClD,IAAI;IAUD,OAAO,CACX,YAAY,SAAS,cAAc,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,EACpE,aAAa,SAAS,cAAc,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,EACrE,MAAM,GAAG,YAAY,SAAS,cAAc,CAAC,OAAO,CAAC,GACjD,iBAAiB,CAAC,YAAY,CAAC,GAC/B,OAAO,EACX,OAAO,GAAG,aAAa,SAAS,cAAc,CAAC,OAAO,CAAC,GACnD,iBAAiB,CAAC,aAAa,CAAC,GAChC,OAAO,EAEX,OAAO,EAAE,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAClD,WAAW,CAAC,EAAE,YAAY,CAAA;QAC1B,YAAY,CAAC,EAAE,aAAa,CAAA;KAC7B,GACA,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAkBrC,YAAY,CAChB,YAAY,SAAS,cAAc,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,EACpE,aAAa,SAAS,cAAc,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,EACrE,MAAM,GAAG,YAAY,SAAS,cAAc,CAAC,OAAO,CAAC,GACjD,iBAAiB,CAAC,YAAY,CAAC,GAC/B,OAAO,EACX,OAAO,GAAG,aAAa,SAAS,cAAc,CAAC,OAAO,CAAC,GACnD,iBAAiB,CAAC,aAAa,CAAC,GAChC,OAAO,EAEX,OAAO,EAAE,IAAI,CAAC,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,GAAG;QACvE,WAAW,CAAC,EAAE,YAAY,CAAA;QAC1B,YAAY,CAAC,EAAE,aAAa,CAAA;KAC7B,GACA,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,EAAE,CAAC;YAiC/B,mBAAmB;YAsDnB,kBAAkB;IA4EhC,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,iBAAiB;IA0BzB,OAAO,CAAC,aAAa;CAGtB;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,CAAC,EAAE,mBAAmB,GAC3B,sBAAsB,CAExB"}