n8n-nodes-ethos 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# n8n-nodes-ethos
+
+An [n8n](https://n8n.io) community node for [ETHOS](https://ethos.so) — drop autonomous browser workflows into any n8n pipeline using a plain-English goal.
+
+## Installation
+
+1. In n8n, open **Settings → Community Nodes**.
+2. Click **Install**.
+3. Enter `n8n-nodes-ethos` and confirm.
+4. After install, restart n8n if prompted.
+
+## Credentials
+
+The node uses an **ETHOS API** credential with two fields:
+
+| Field      | Required | Description                                                             |
+|------------|----------|-------------------------------------------------------------------------|
+| API Key    | Yes      | Your ETHOS API key (starts with `ethos_sk_`). Get one at https://ethos.so/dashboard/api-keys. |
+| Base URL   | No       | Defaults to `https://api.ethos.so`. Override only for self-hosted ETHOS. |
+
+## Node inputs
+
+| Name           | Type     | Default   | Description                                          |
+|----------------|----------|-----------|------------------------------------------------------|
+| Goal           | string   | —         | Plain-English browser task (10–2000 chars)           |
+| Execution Mode | options  | headless  | Only `headless` is supported via API today           |
+| Poll Interval  | number   | 3000      | (Additional Options) Milliseconds between polls      |
+| Timeout        | number   | 120       | (Additional Options) Maximum wait time, in seconds   |
+
+## Node outputs
+
+Two output branches:
+
+| Branch    | When                                                        | Payload                                                              |
+|-----------|-------------------------------------------------------------|----------------------------------------------------------------------|
+| Success   | Workflow status is `completed`                              | `{ workflowId, status, result, taskCount, tasksDone }`               |
+| Error     | Status is `failed`, timed out, or hit an HTTP error         | `{ workflowId, status, error }`                                      |
+
+The Error branch is used instead of throwing, so downstream nodes can react.
+
+### Error messages
+
+- `Invalid ETHOS API key` — 401 from the API
+- `Quota exceeded` — 429 from the API
+- `Workflow timed out after Xs` — exceeded the configured timeout
+- Other HTTP errors are retried up to twice with a 2-second backoff before being routed to the Error branch
+
+## Example
+
+**Goal:**
+
+> Get the top 5 trending repositories from github.com/trending with name, stars, and description
+
+Drop the ETHOS node after a trigger, paste the goal, connect the Success branch to your data sink (Slack, Sheets, Notion, etc.), and the Error branch to a notification node.
+
+## Limitations
+
+- Headless execution only — extension mode is coming soon.
+- Maximum timeout is bounded by your n8n execution timeout; the node default cap is 120 seconds.
+- Each node execution submits and waits for one workflow; for high throughput, fan out with the n8n **Split In Batches** node.
+
+## License
+
+MIT

package/dist/EthosNode.node.d.ts

@@ -0,0 +1,5 @@
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class EthosNode implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/EthosNode.node.js

@@ -0,0 +1,241 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EthosNode = void 0;
+const TERMINAL_STATUSES = new Set(['completed', 'failed']);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function getStatusCode(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const e = err;
+    if (typeof e.statusCode === 'number')
+        return e.statusCode;
+    if (typeof e.httpCode === 'string') {
+        const parsed = parseInt(e.httpCode, 10);
+        if (!Number.isNaN(parsed))
+            return parsed;
+    }
+    const response = e.response;
+    if (response && typeof response.statusCode === 'number')
+        return response.statusCode;
+    if (response && typeof response.status === 'number')
+        return response.status;
+    return undefined;
+}
+function getErrorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    return 'Unknown error';
+}
+class EthosNode {
+    constructor() {
+        this.description = {
+            displayName: 'ETHOS',
+            name: 'ethosNode',
+            icon: 'file:ethos.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["goal"]}}',
+            description: 'Run an ETHOS autonomous browser workflow from a plain-English goal',
+            defaults: {
+                name: 'ETHOS',
+            },
+            inputs: ['main'],
+            outputs: ['main', 'main'],
+            outputNames: ['Success', 'Error'],
+            credentials: [
+                {
+                    name: 'ethosApi',
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: 'Goal',
+                    name: 'goal',
+                    type: 'string',
+                    typeOptions: {
+                        rows: 4,
+                    },
+                    default: '',
+                    required: true,
+                    placeholder: 'Get the top 5 trending repositories from github.com/trending',
+                    description: 'Plain-English browser task (10–2000 chars)',
+                },
+                {
+                    displayName: 'Execution Mode',
+                    name: 'executionMode',
+                    type: 'options',
+                    options: [
+                        {
+                            name: 'Headless',
+                            value: 'headless',
+                        },
+                    ],
+                    default: 'headless',
+                    description: 'How ETHOS executes the workflow. Only headless is supported via API today.',
+                },
+                {
+                    displayName: 'Additional Options',
+                    name: 'additionalOptions',
+                    type: 'collection',
+                    placeholder: 'Add Option',
+                    default: {},
+                    options: [
+                        {
+                            displayName: 'Poll Interval (ms)',
+                            name: 'pollInterval',
+                            type: 'number',
+                            typeOptions: {
+                                minValue: 1000,
+                            },
+                            default: 3000,
+                            description: 'How often to poll for workflow status, in milliseconds',
+                        },
+                        {
+                            displayName: 'Timeout (Seconds)',
+                            name: 'timeout',
+                            type: 'number',
+                            typeOptions: {
+                                minValue: 10,
+                            },
+                            default: 120,
+                            description: 'Maximum time to wait for the workflow to complete, in seconds',
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const successOut = [];
+        const errorOut = [];
+        const credentials = (await this.getCredentials('ethosApi'));
+        const baseUrl = (credentials.baseUrl || 'https://api.ethos.so').replace(/\/+$/, '');
+        for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+            const goal = this.getNodeParameter('goal', itemIndex);
+            const additionalOptions = this.getNodeParameter('additionalOptions', itemIndex, {});
+            const pollInterval = Math.max(1000, additionalOptions.pollInterval ?? 3000);
+            const timeoutSeconds = Math.max(10, additionalOptions.timeout ?? 120);
+            let workflowId = '';
+            try {
+                const submitOptions = {
+                    method: 'POST',
+                    url: `${baseUrl}/api/v1/workflow`,
+                    headers: {
+                        Authorization: `Bearer ${credentials.apiKey}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: {
+                        goal,
+                        execution_mode: 'headless',
+                    },
+                    json: true,
+                };
+                const submitResp = await requestWithRetry.call(this, submitOptions);
+                const submitted = submitResp;
+                workflowId = submitted.id;
+                const deadline = Date.now() + timeoutSeconds * 1000;
+                let finalStatus;
+                while (Date.now() < deadline) {
+                    await sleep(pollInterval);
+                    const pollOptions = {
+                        method: 'GET',
+                        url: `${baseUrl}/api/v1/workflow/${workflowId}`,
+                        headers: {
+                            Authorization: `Bearer ${credentials.apiKey}`,
+                        },
+                        json: true,
+                    };
+                    const pollResp = (await requestWithRetry.call(this, pollOptions));
+                    if (TERMINAL_STATUSES.has(pollResp.status)) {
+                        finalStatus = pollResp;
+                        break;
+                    }
+                }
+                if (!finalStatus) {
+                    errorOut.push({
+                        json: {
+                            workflowId,
+                            status: 'timeout',
+                            error: `Workflow timed out after ${timeoutSeconds}s`,
+                        },
+                        pairedItem: { item: itemIndex },
+                    });
+                    continue;
+                }
+                if (finalStatus.status === 'completed') {
+                    successOut.push({
+                        json: {
+                            workflowId: finalStatus.id,
+                            status: finalStatus.status,
+                            result: finalStatus.result,
+                            taskCount: finalStatus.task_count,
+                            tasksDone: finalStatus.tasks_done,
+                        },
+                        pairedItem: { item: itemIndex },
+                    });
+                }
+                else {
+                    errorOut.push({
+                        json: {
+                            workflowId: finalStatus.id,
+                            status: finalStatus.status,
+                            error: finalStatus.error ?? 'Workflow failed',
+                        },
+                        pairedItem: { item: itemIndex },
+                    });
+                }
+            }
+            catch (err) {
+                const statusCode = getStatusCode(err);
+                let message;
+                if (statusCode === 401) {
+                    message = 'Invalid ETHOS API key';
+                }
+                else if (statusCode === 429) {
+                    message = 'Quota exceeded';
+                }
+                else {
+                    message = getErrorMessage(err);
+                }
+                errorOut.push({
+                    json: {
+                        workflowId,
+                        status: 'error',
+                        error: message,
+                    },
+                    pairedItem: { item: itemIndex },
+                });
+            }
+        }
+        return [successOut, errorOut];
+    }
+}
+exports.EthosNode = EthosNode;
+async function requestWithRetry(options) {
+    const maxAttempts = 3;
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await this.helpers.httpRequest(options);
+        }
+        catch (err) {
+            lastErr = err;
+            const statusCode = getStatusCode(err);
+            if (statusCode === 401 || statusCode === 429) {
+                throw err;
+            }
+            const isRetryable = statusCode === undefined || (statusCode >= 500 && statusCode < 600);
+            if (!isRetryable || attempt === maxAttempts) {
+                throw err;
+            }
+            await sleep(2000);
+        }
+    }
+    throw lastErr;
+}

package/dist/EthosNode.node.json

@@ -0,0 +1,18 @@
+{
+	"node": "n8n-nodes-ethos.ethosNode",
+	"nodeVersion": "1.0",
+	"codexVersion": "1.0",
+	"categories": ["AI", "Productivity"],
+	"resources": {
+		"credentialDocumentation": [
+			{
+				"url": "https://ethos.so/docs/api"
+			}
+		],
+		"primaryDocumentation": [
+			{
+				"url": "https://ethos.so/docs"
+			}
+		]
+	}
+}

package/dist/credentials/EthosApi.credentials.d.ts

@@ -0,0 +1,9 @@
+import { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class EthosApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/EthosApi.credentials.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EthosApi = void 0;
+class EthosApi {
+    constructor() {
+        this.name = 'ethosApi';
+        this.displayName = 'ETHOS API';
+        this.documentationUrl = 'https://ethos.so/docs';
+        this.properties = [
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Your ETHOS API key (starts with ethos_sk_)',
+            },
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: 'https://api.ethos.so',
+                description: 'Override only if you are self-hosting ETHOS',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.apiKey}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl}}',
+                url: '/api/v1/health',
+                method: 'GET',
+            },
+        };
+    }
+}
+exports.EthosApi = EthosApi;

package/index.js

@@ -0,0 +1 @@
+module.exports = {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "n8n-nodes-ethos",
+  "version": "0.1.0",
+  "description": "n8n community node for ETHOS browser automation",
+  "keywords": [
+    "n8n-community-node-package"
+  ],
+  "license": "MIT",
+  "author": "ETHOS",
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/EthosApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/EthosNode.node.js"
+    ]
+  },
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc && cp src/EthosNode.node.json dist/",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^18.0.0",
+    "n8n-workflow": "^1.0.0"
+  },
+  "peerDependencies": {
+    "n8n-workflow": ">=0.5.0"
+  }
+}