n8n-nodes-connector-engine 1.0.0

package/README.md

@@ -0,0 +1,94 @@
+# n8n-nodes-connector-engine
+
+Universal **Connector Engine** node for n8n. Connects to your ERP Integration Execution API and runs connector capabilities (resources and operations) with schema-driven input fields.
+
+## Requirements
+
+- **Node.js 18+** (for building the package)
+- n8n instance (cloud or self-hosted)
+- Connector Engine API (base URL + API key from your ERP Integration app)
+
+## Build (required before install from path)
+
+From the package directory:
+
+```bash
+npm install
+npm run build
+```
+
+This produces the `dist/` folder that n8n loads.
+
+## Install in n8n
+
+### Option A: From zip (no build, ready to install)
+
+Use the pre-built zip so you don’t need Node 18 or to run `npm run build`.
+
+1. Get **n8n-nodes-connector-engine.zip** (from the repo or run `npm run zip` in the package folder to create it).
+2. Unzip it into a folder, e.g.:
+   ```bash
+   mkdir -p n8n-nodes-connector-engine
+   cd n8n-nodes-connector-engine
+   unzip /path/to/n8n-nodes-connector-engine.zip
+   ```
+   You should see `package.json`, `README.md`, and `dist/` in that folder.
+3. On the machine where n8n runs, install from that folder:
+   ```bash
+   mkdir -p ~/.n8n/nodes
+   cd ~/.n8n/nodes
+   npm install /path/to/n8n-nodes-connector-engine
+   ```
+4. Restart n8n. The **Connector Engine** node and **Connector Engine API** credential will be available.
+
+### Option B: From n8n UI (if published to npm)
+
+1. In n8n: **Settings** → **Community nodes** → **Install**.
+2. Enter: `n8n-nodes-connector-engine`.
+3. Install and restart if prompted.
+
+### Option C: Install from local path (self-hosted)
+
+1. Build the package (see above) so `dist/` exists.
+2. On the machine where n8n runs, install the package into n8n’s nodes directory:
+
+```bash
+mkdir -p ~/.n8n/nodes
+cd ~/.n8n/nodes
+npm install /path/to/n8n-nodes-connector-engine
+```
+
+3. Restart n8n.
+
+### Option D: Docker / queue mode
+
+1. Build the package locally (Node 18+) so `dist/` exists.
+2. Copy the built package (or the repo) into the container and install:
+
+```bash
+docker exec -it n8n sh
+mkdir -p ~/.n8n/nodes
+cd ~/.n8n/nodes
+npm install /path/to/n8n-nodes-connector-engine
+```
+
+3. Restart the n8n container.
+
+## Usage
+
+1. Add a **Connector Engine** node to your workflow.
+2. Create a **Connector Engine API** credential:
+   - **Base URL**: your Execution API base URL (e.g. `https://your-app.com/api` or `http://localhost/api`).
+   - **API Key**: an API key from your ERP Integration app (API Keys page).
+3. In the node, choose **Connector** → **Resource** → **Operation** (loaded from your API).
+4. Add **Fields** (key/value) as required by the operation; keys come from the capability schema.
+5. Run the workflow; the node calls `POST /execute` and returns the result data.
+
+## Credentials
+
+- **Name:** Connector Engine API  
+- **Fields:** Base URL (required), API Key (required, password).
+
+## License
+
+MIT

package/dist/credentials/ConnectorEngineApi.credentials.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectorEngineApi = void 0;
+class ConnectorEngineApi {
+  constructor() {
+    this.name = 'connectorEngineApi';
+    this.displayName = 'Connector Engine API';
+    this.documentationUrl = 'https://github.com/your-org/n8n-nodes-connector-engine';
+    this.properties = [
+      {
+        displayName: 'Base URL',
+        name: 'baseUrl',
+        type: 'string',
+        default: '',
+        required: true,
+        placeholder: 'https://api.example.com',
+      },
+      {
+        displayName: 'API Key',
+        name: 'apiKey',
+        type: 'string',
+        typeOptions: { password: true },
+        default: '',
+        required: true,
+      },
+    ];
+  }
+}
+exports.ConnectorEngineApi = ConnectorEngineApi;
+exports.default = ConnectorEngineApi;

package/dist/nodes/ConnectorEngine.node.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectorEngine = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const CapabilityService_1 = require("../services/CapabilityService");
+const FieldMapper_1 = require("../services/FieldMapper");
+const SchemaService_1 = require("../services/SchemaService");
+const TransportService_1 = require("../services/TransportService");
+function getCredentials() {
+  const creds = this.getCredentials('connectorEngineApi');
+  if (!creds || !creds.baseUrl || !creds.apiKey) {
+    throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Connector Engine API credentials (base URL and API key) are required.');
+  }
+  return { baseUrl: String(creds.baseUrl).replace(/\/$/, ''), apiKey: String(creds.apiKey) };
+}
+class ConnectorEngine {
+  constructor() {
+    this.description = {
+      displayName: 'Connector Engine',
+      name: 'connectorEngine',
+      group: ['transform'],
+      version: 1,
+      subtitle: '={{ $parameter["resource"] + "." + $parameter["operation"] }}',
+      description: 'Execute connector capabilities via schema-driven API',
+      defaults: { name: 'Connector Engine' },
+      inputs: ['main'],
+      outputs: ['main'],
+      credentials: [{ name: 'connectorEngineApi', required: true }],
+      properties: [
+        {
+          displayName: 'Connector',
+          name: 'connectorId',
+          type: 'options',
+          required: true,
+          default: '',
+          typeOptions: { loadOptionsMethod: 'getConnectors' },
+          description: 'Connector instance to use',
+        },
+        {
+          displayName: 'Resource',
+          name: 'resource',
+          type: 'options',
+          required: true,
+          default: '',
+          typeOptions: {
+            loadOptionsMethod: 'getResources',
+            loadOptionsDependsOn: ['connectorId'],
+          },
+          description: 'Resource (e.g. customer, order)',
+        },
+        {
+          displayName: 'Operation',
+          name: 'operation',
+          type: 'options',
+          required: true,
+          default: '',
+          typeOptions: {
+            loadOptionsMethod: 'getOperations',
+            loadOptionsDependsOn: ['connectorId', 'resource'],
+          },
+          description: 'Operation to perform',
+        },
+        {
+          displayName: 'Fields',
+          name: 'fields',
+          type: 'fixedCollection',
+          typeOptions: { multipleValues: true },
+          default: {},
+          placeholder: 'Add field',
+          description: 'Input fields for the capability',
+          options: [
+            {
+              name: 'values',
+              displayName: 'Field',
+              values: [
+                {
+                  displayName: 'Key',
+                  name: 'key',
+                  type: 'options',
+                  default: '',
+                  typeOptions: {
+                    loadOptionsMethod: 'getFieldKeys',
+                    loadOptionsDependsOn: ['connectorId', 'resource', 'operation'],
+                  },
+                  description: 'Field name from schema',
+                },
+                {
+                  displayName: 'Value',
+                  name: 'value',
+                  type: 'string',
+                  default: '',
+                  typeOptions: {
+                    loadOptionsMethod: 'getFieldValueOptions',
+                    loadOptionsDependsOn: ['connectorId', 'resource', 'operation', 'fields'],
+                  },
+                  description: 'Value for the field',
+                },
+              ],
+            },
+          ],
+        },
+      ],
+      methods: {
+        loadOptions: {
+          async getConnectors() {
+            const { baseUrl, apiKey } = getCredentials.call(this);
+            const transport = new TransportService_1.TransportService();
+            const response = await transport.getConnectors(baseUrl, apiKey);
+            const data = response && response.data;
+            if (!Array.isArray(data))
+              return [];
+            return data.map((c) => ({ name: `${c.name} (${c.type})`, value: c.id }));
+          },
+          async getResources() {
+            const connectorId = this.getCurrentNodeParameter('connectorId');
+            if (!connectorId)
+              return [];
+            const { baseUrl, apiKey } = getCredentials.call(this);
+            const transport = new TransportService_1.TransportService();
+            const capabilityService = new CapabilityService_1.CapabilityService(transport);
+            const structure = await capabilityService.getStructuredCapabilities(baseUrl, apiKey, connectorId);
+            return structure.resources.map((r) => ({ name: r, value: r }));
+          },
+          async getOperations() {
+            const connectorId = this.getCurrentNodeParameter('connectorId');
+            const resource = this.getCurrentNodeParameter('resource');
+            if (!connectorId || !resource)
+              return [];
+            const { baseUrl, apiKey } = getCredentials.call(this);
+            const transport = new TransportService_1.TransportService();
+            const capabilityService = new CapabilityService_1.CapabilityService(transport);
+            const structure = await capabilityService.getStructuredCapabilities(baseUrl, apiKey, connectorId);
+            const ops = structure.operationsByResource[resource];
+            if (!Array.isArray(ops))
+              return [];
+            return ops.map((o) => ({ name: o, value: o }));
+          },
+          async getFieldKeys() {
+            const connectorId = this.getCurrentNodeParameter('connectorId');
+            const resource = this.getCurrentNodeParameter('resource');
+            const operation = this.getCurrentNodeParameter('operation');
+            if (!connectorId || !resource || !operation)
+              return [];
+            const { baseUrl, apiKey } = getCredentials.call(this);
+            const transport = new TransportService_1.TransportService();
+            const context = {
+              getWorkflowStaticData: this.getWorkflowStaticData ? this.getWorkflowStaticData.bind(this) : () => ({ get: () => undefined, set: () => {} }),
+            };
+            const schemaService = new SchemaService_1.SchemaService(transport, context);
+            const schema = await schemaService.getInputDto(baseUrl, apiKey, connectorId, `${resource}.${operation}`);
+            const fieldMapper = new FieldMapper_1.FieldMapper();
+            return fieldMapper.schemaToKeyOptions(schema);
+          },
+          async getFieldValueOptions() {
+            const connectorId = this.getCurrentNodeParameter('connectorId');
+            const resource = this.getCurrentNodeParameter('resource');
+            const operation = this.getCurrentNodeParameter('operation');
+            if (!connectorId || !resource || !operation)
+              return [];
+            let key;
+            try {
+              key = this.getCurrentNodeParameter('key');
+            }
+            catch (_a) {
+              const fields = this.getNodeParameter('fields');
+              const values = fields && fields.values;
+              key = Array.isArray(values) && values.length > 0 ? (values[values.length - 1] && values[values.length - 1].key) : undefined;
+            }
+            if (!key)
+              return [];
+            const { baseUrl, apiKey } = getCredentials.call(this);
+            const transport = new TransportService_1.TransportService();
+            const context = {
+              getWorkflowStaticData: this.getWorkflowStaticData ? this.getWorkflowStaticData.bind(this) : () => ({ get: () => undefined, set: () => {} }),
+            };
+            const schemaService = new SchemaService_1.SchemaService(transport, context);
+            const schema = await schemaService.getInputDto(baseUrl, apiKey, connectorId, `${resource}.${operation}`);
+            const fieldMapper = new FieldMapper_1.FieldMapper();
+            return fieldMapper.schemaToValueOptionsForKey(schema, key);
+          },
+        },
+      },
+    };
+  }
+  async execute() {
+    const items = this.getInputData();
+    const returnData = [];
+    const transport = new TransportService_1.TransportService();
+    const fieldMapper = new FieldMapper_1.FieldMapper();
+    const { baseUrl, apiKey } = getCredentials.call(this);
+    const context = {
+      getWorkflowStaticData: this.getWorkflowStaticData ? this.getWorkflowStaticData.bind(this) : () => ({ get: () => undefined, set: () => {} }),
+    };
+    const schemaService = new SchemaService_1.SchemaService(transport, context);
+    for (let i = 0; i < items.length; i++) {
+      try {
+        const connectorId = this.getNodeParameter('connectorId', i);
+        const resource = this.getNodeParameter('resource', i);
+        const operation = this.getNodeParameter('operation', i);
+        const fieldsParam = this.getNodeParameter('fields', i);
+        if (!connectorId || !resource || !operation) {
+          throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Connector, Resource, and Operation are required.', { itemIndex: i });
+        }
+        const capabilityKey = `${resource}.${operation}`;
+        const schema = await schemaService.getInputDto(baseUrl, apiKey, connectorId, capabilityKey);
+        const fieldsEntries = Array.isArray(fieldsParam && fieldsParam.values) ? fieldsParam.values : [];
+        const input = fieldMapper.fieldsCollectionToInput(fieldsEntries, schema);
+        let response;
+        try {
+          response = await transport.execute(baseUrl, apiKey, connectorId, capabilityKey, input);
+        }
+        catch (err) {
+          if (err instanceof TransportService_1.TransportError) {
+            throw new n8n_workflow_1.NodeApiError(this.getNode(), err, {
+              message: err.message,
+              httpCode: err.httpCode,
+              description: err.details != null ? String(err.details) : undefined,
+            });
+          }
+          throw new n8n_workflow_1.NodeApiError(this.getNode(), err);
+        }
+        if (response && response.success === false) {
+          const msg = (response.error && response.error.message) || 'Execution failed';
+          throw new n8n_workflow_1.NodeOperationError(this.getNode(), msg, {
+            itemIndex: i,
+            description: response.error && response.error.code,
+          });
+        }
+        const data = response && response.success === true ? response.data : response;
+        returnData.push({
+          json: typeof data === 'object' && data !== null ? data : { data },
+          pairedItem: { item: i },
+        });
+      }
+      catch (err) {
+        if (this.continueOnFail()) {
+          returnData.push({
+            json: { error: err.message },
+            pairedItem: { item: i },
+          });
+          continue;
+        }
+        throw err;
+      }
+    }
+    return [returnData];
+  }
+}
+exports.ConnectorEngine = ConnectorEngine;
+exports.default = ConnectorEngine;

package/dist/services/CapabilityService.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapabilityService = void 0;
+class CapabilityService {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async getStructuredCapabilities(baseUrl, apiKey, connectorId) {
+    const list = await this.transport.getCapabilities(baseUrl, apiKey, connectorId);
+    const resourceSet = new Set();
+    const operationsByResource = {};
+    for (const item of list) {
+      const key = typeof item === 'object' && item !== null && 'key' in item ? String(item.key) : String(item);
+      const dot = key.indexOf('.');
+      const resource = dot >= 0 ? key.slice(0, dot) : key;
+      const operation = dot >= 0 ? key.slice(dot + 1) : key;
+      if (!resource || !operation)
+        continue;
+      resourceSet.add(resource);
+      if (!operationsByResource[resource]) {
+        operationsByResource[resource] = [];
+      }
+      const ops = operationsByResource[resource];
+      if (!ops.includes(operation)) {
+        ops.push(operation);
+      }
+    }
+    return {
+      resources: Array.from(resourceSet).sort(),
+      operationsByResource,
+    };
+  }
+}
+exports.CapabilityService = CapabilityService;

package/dist/services/FieldMapper.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldMapper = void 0;
+class FieldMapper {
+  schemaToKeyOptions(schema) {
+    return Object.keys(schema).map((key) => ({ name: key, value: key }));
+  }
+  schemaToValueOptionsForKey(schema, key) {
+    const desc = schema[key];
+    if (!desc)
+      return [];
+    if (Array.isArray(desc.enum) && desc.enum.length > 0) {
+      return desc.enum.map((v) => ({ name: String(v), value: String(v) }));
+    }
+    if (desc.type === 'boolean') {
+      return [
+        { name: 'True', value: 'true' },
+        { name: 'False', value: 'false' },
+      ];
+    }
+    return [];
+  }
+  fieldsCollectionToInput(fieldsEntries, schema) {
+    const input = {};
+    for (const entry of fieldsEntries) {
+      const key = entry && entry.key;
+      if (key === undefined || key === null || key === '')
+        continue;
+      const descriptor = schema[key];
+      let raw = entry && entry.value;
+      if (raw === undefined || (typeof raw === 'string' && raw.trim() === '')) {
+        if (descriptor && descriptor.required) {
+          input[key] = descriptor.default !== undefined && descriptor.default !== null ? descriptor.default : '';
+        }
+        continue;
+      }
+      if (descriptor) {
+        input[key] = this.coerceValue(raw, descriptor);
+      }
+      else {
+        input[key] = raw;
+      }
+    }
+    return input;
+  }
+  coerceValue(raw, descriptor) {
+    if (raw === undefined || raw === null) {
+      return descriptor.default;
+    }
+    const type = descriptor.type || 'string';
+    if (type === 'boolean') {
+      if (typeof raw === 'boolean')
+        return raw;
+      const s = String(raw).toLowerCase();
+      if (s === 'true' || s === '1')
+        return true;
+      if (s === 'false' || s === '0')
+        return false;
+      return Boolean(raw);
+    }
+    if (type === 'number' || type === 'integer') {
+      if (typeof raw === 'number' && !Number.isNaN(raw))
+        return type === 'integer' ? Math.floor(raw) : raw;
+      const n = Number(raw);
+      return Number.isNaN(n) ? descriptor.default : (type === 'integer' ? Math.floor(n) : n);
+    }
+    if (type === 'object' || type === 'array') {
+      if (typeof raw === 'object')
+        return raw;
+      try {
+        return JSON.parse(String(raw));
+      }
+      catch (_a) {
+        return descriptor.default !== undefined && descriptor.default !== null ? descriptor.default : (type === 'array' ? [] : {});
+      }
+    }
+    return String(raw);
+  }
+}
+exports.FieldMapper = FieldMapper;

package/dist/services/SchemaService.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaService = void 0;
+const PRIMITIVE_TYPES = ['string', 'number', 'integer', 'boolean', 'object', 'array'];
+function normalizePropertySchema(value, required) {
+  if (value === undefined || value === null)
+    return null;
+  let type = 'string';
+  let enumValues;
+  let defaultVal;
+  if (typeof value === 'string') {
+    const t = value.toLowerCase();
+    type = PRIMITIVE_TYPES.includes(t) ? t : 'string';
+  }
+  else if (typeof value === 'object' && value !== null && 'type' in value) {
+    const v = value;
+    type = PRIMITIVE_TYPES.includes(v.type) ? v.type : 'string';
+    if (Array.isArray(v.enum))
+      enumValues = v.enum.map(String);
+    defaultVal = v.default;
+  }
+  return { type, enum: enumValues, default: defaultVal, required };
+}
+class SchemaService {
+  constructor(transport, context) {
+    this.transport = transport;
+    this.context = context;
+  }
+  async getInputDto(baseUrl, apiKey, connectorId, capabilityKey) {
+    const cacheKey = `schema:${connectorId}:${capabilityKey}`;
+    const staticData = this.context.getWorkflowStaticData('node');
+    const cached = staticData.get(cacheKey);
+    if (cached && typeof cached === 'object') {
+      return cached;
+    }
+    let response;
+    try {
+      response = await this.transport.getCapabilitySchema(baseUrl, apiKey, connectorId, capabilityKey);
+    }
+    catch (_a) {
+      return {};
+    }
+    const inputDto = response && response.input_dto;
+    if (!inputDto || typeof inputDto !== 'object' || !inputDto.properties) {
+      return {};
+    }
+    const requiredSet = new Set(Array.isArray(inputDto.required) ? inputDto.required : []);
+    const result = {};
+    for (const [propName, propSchema] of Object.entries(inputDto.properties)) {
+      const normalized = normalizePropertySchema(propSchema, requiredSet.has(propName));
+      if (normalized)
+        result[propName] = normalized;
+    }
+    staticData.set(cacheKey, result);
+    return result;
+  }
+}
+exports.SchemaService = SchemaService;

package/dist/services/TransportService.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransportService = exports.TransportError = void 0;
+class TransportError extends Error {
+  constructor(message, httpCode, code, details) {
+    super(message);
+    this.httpCode = httpCode;
+    this.code = code;
+    this.details = details;
+    this.name = 'TransportError';
+  }
+}
+exports.TransportError = TransportError;
+class TransportService {
+  buildUrl(baseUrl, path) {
+    const base = baseUrl.replace(/\/$/, '');
+    const p = path.startsWith('/') ? path : `/${path}`;
+    return `${base}${p}`;
+  }
+  async request(baseUrl, apiKey, path, options = {}) {
+    const url = this.buildUrl(baseUrl, path);
+    const headers = Object.assign({
+      'X-API-KEY': apiKey,
+      'Content-Type': 'application/json',
+    }, options.headers || {});
+    const response = await fetch(url, Object.assign(Object.assign({}, options), { headers: Object.assign(Object.assign({}, headers), options.headers || {}) }));
+    const text = await response.text();
+    let body = null;
+    try {
+      body = text ? JSON.parse(text) : null;
+    }
+    catch (_a) {
+      body = text;
+    }
+    if (!response.ok) {
+      const err = body && typeof body === 'object' && 'error' in body ? body.error : null;
+      const message = err && typeof err === 'object' && typeof err.message === 'string' ? err.message : `Request failed with status ${response.status}`;
+      const code = err && typeof err === 'object' && typeof err.code === 'string' ? err.code : undefined;
+      const details = err && typeof err === 'object' && 'details' in err ? err.details : undefined;
+      throw new TransportError(message, response.status, code, details);
+    }
+    return body;
+  }
+  async getConnectors(baseUrl, apiKey) {
+    return this.request(baseUrl, apiKey, '/execute/connectors', { method: 'GET' });
+  }
+  async getCapabilities(baseUrl, apiKey, connectorId) {
+    const path = '/execute/capabilities';
+    const body = { connector_id: connectorId };
+    const result = await this.request(baseUrl, apiKey, path, {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+    return Array.isArray(result) ? result : [];
+  }
+  async getCapabilitySchema(baseUrl, apiKey, connectorId, capabilityKey) {
+    return this.request(baseUrl, apiKey, '/execute/capability-schema', {
+      method: 'POST',
+      body: JSON.stringify({ connector_id: connectorId, key: capabilityKey }),
+    });
+  }
+  async execute(baseUrl, apiKey, connectorId, capabilityKey, input) {
+    return this.request(baseUrl, apiKey, '/execute', {
+      method: 'POST',
+      body: JSON.stringify({
+        connector_id: connectorId,
+        capability_key: capabilityKey,
+        input,
+      }),
+    });
+  }
+}
+exports.TransportService = TransportService;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "n8n-nodes-connector-engine",
+  "version": "1.0.0",
+  "description": "Universal Connector Engine node for n8n - schema-driven, backend-driven capabilities",
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "connector-engine",
+    "erp",
+    "integration"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/your-org/n8n-nodes-connector-engine#readme",
+  "author": {},
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/n8n-nodes-connector-engine.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "zip": "zip -r n8n-nodes-connector-engine.zip package.json README.md dist"
+  },
+  "files": [
+    "dist",
+    "*.d.ts"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/ConnectorEngineApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/ConnectorEngine.node.js"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "n8n-workflow": "*",
+    "typescript": "~5.3.0"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}