n8n-nodes-jitterflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jitterflow
+
+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,70 @@
+# 🔌 n8n-nodes-jitterflow
+
+An [n8n](https://n8n.io) community node for [Jitterflow](https://jitterflow.io) — jittered, rate-limited webhook delivery with a dead-letter queue, right inside your workflows.
+
+> **🔑 What this buys you:** send a webhook through Jitterflow's pacing/retry engine, then list, replay, or resolve anything that ends up in the dead-letter queue — without leaving n8n.
+
+All jitter math, TPS guarding, and DLQ decisioning happen server-side in Jitterflow. This node is a thin, typed client over the real REST API — the same contract [`@jitterflow/sdk-node`](https://jitterflow.io) uses.
+
+---
+
+## ✨ What it does
+
+| Resource | Operation | What happens |
+|---|---|---|
+| **Webhook** | Send | Queues a webhook for delayed, jittered redelivery via `POST /v1/ingest/:endpointKey` |
+| **DLQ** | List | Lists dead-letter queue entries, filterable by resolved/unresolved |
+| **DLQ** | Replay | One-click re-enqueues a failed job for immediate redelivery |
+| **DLQ** | Resolve | Marks an entry resolved without retrying it |
+
+**Two details worth knowing about Send:**
+
+- **Target Identifier** — optional; paces delivery per this identifier (a mailbox, a lead ID, whatever) instead of per endpoint. Defaults server-side to the endpoint key if left blank.
+- **Idempotency Key** — defaults to `{{$execution.id}}-{{$itemIndex}}`, so a workflow retry never double-sends the same item.
+
+---
+
+## 📦 Install
+
+| Platform | How |
+|---|---|
+| **Self-hosted n8n** | Settings → Community Nodes → install `n8n-nodes-jitterflow` |
+| **n8n Cloud** | Available once the node clears n8n's verification review (submitted via the [Creator Portal](https://creators.n8n.io/nodes)) |
+
+---
+
+## 🔑 Credential
+
+Create a **Jitterflow API** credential:
+
+- [ ] Grab your tenant API key from the Jitterflow dashboard → **API Keys** (starts with `wjg_`)
+- [ ] Paste it into the credential's **API Key** field
+- [ ] Hit **Test** — it calls `GET /v1/endpoints` to confirm the key actually works
+
+---
+
+## 🛠️ Development
+
+> This package was split out of the main [jitterflow-core-app](https://github.com/jitterflow/jitterflow-core-app) monorepo so it could be a public repo, per n8n's verification requirements. Day-to-day development — including integration/e2e tests against a real Jitterflow API instance — still happens there. This repo carries the standalone-buildable unit tests and is what actually gets published.
+
+```bash
+npm ci
+npm run build   # n8n-node build
+npm run lint    # n8n-node lint — the verification-readiness check
+npm test
+```
+
+---
+
+## 🚀 Release
+
+```bash
+npm run release
+```
+
+| Step | What it does |
+|---|---|
+| `npm run release` | Bumps the version, tags, and pushes |
+| `.github/workflows/publish.yml` | Takes it from there — build, `n8n-node lint`, publish to npm with provenance |
+
+> **⚠️ Requires** the `NPM_TOKEN` repo secret to be set.

package/dist/credentials/JitterflowApi.credentials.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JitterflowApi = void 0;
+class JitterflowApi {
+    name = 'jitterflowApi';
+    displayName = 'Jitterflow API';
+    icon = 'file:jitterflow.svg';
+    documentationUrl = 'https://jitterflow.io/docs';
+    properties = [
+        {
+            displayName: 'API Key',
+            name: 'apiKey',
+            type: 'string',
+            typeOptions: { password: true },
+            default: '',
+            required: true,
+            description: 'Your Jitterflow tenant API key (starts with wjg_). Find it in the Jitterflow dashboard under API Keys.',
+        },
+        {
+            displayName: 'Base URL',
+            name: 'baseUrl',
+            type: 'string',
+            default: 'https://jitterflow.io',
+            description: 'Override only for a self-hosted or non-production Jitterflow API origin.',
+        },
+    ];
+    // Generic (non-declarative-node) auth — every request this package makes
+    // goes through GenericFunctions.jitterflowApiRequest, which calls
+    // helpers.httpRequestWithAuthentication with this credential name, so
+    // this header injection is the single place API auth is applied.
+    authenticate = {
+        type: 'generic',
+        properties: {
+            headers: {
+                Authorization: '=Bearer {{$credentials.apiKey}}',
+            },
+        },
+    };
+    // Backs the "Test" button in the credential UI — GET /v1/endpoints is the
+    // cheapest authenticated read on the real API (see apps/api/src/routes/
+    // endpoints.ts), so a passing test here means the key genuinely works.
+    test = {
+        request: {
+            baseURL: '={{$credentials.baseUrl}}',
+            url: '/v1/endpoints',
+            method: 'GET',
+        },
+    };
+}
+exports.JitterflowApi = JitterflowApi;

package/dist/credentials/jitterflow.svg

@@ -0,0 +1,4 @@
+<svg width="60" height="60" viewBox="0 0 60 60" xmlns="http://www.w3.org/2000/svg">
+  <rect width="60" height="60" rx="12" fill="#4F46E5"/>
+  <path d="M14 38 L22 38 L26 24 L32 44 L36 30 L40 38 L46 38" stroke="#FFFFFF" stroke-width="4" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/dist/nodes/Jitterflow/GenericFunctions.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jitterflowApiRequest = jitterflowApiRequest;
+async function jitterflowApiRequest(method, path, body, qs) {
+    const credentials = await this.getCredentials('jitterflowApi');
+    const baseUrl = String(credentials.baseUrl || 'https://jitterflow.io').replace(/\/+$/, '');
+    const options = {
+        method,
+        url: `${baseUrl}${path}`,
+        body,
+        qs,
+        json: true,
+    };
+    return this.helpers.httpRequestWithAuthentication.call(this, 'jitterflowApi', options);
+}

package/dist/nodes/Jitterflow/Jitterflow.node.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Jitterflow = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const GenericFunctions_1 = require("./GenericFunctions");
+class Jitterflow {
+    description = {
+        displayName: 'Jitterflow',
+        name: 'jitterflow',
+        icon: 'file:jitterflow.svg',
+        group: ['transform'],
+        version: 1,
+        subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
+        description: 'Send webhooks through jittered, rate-limited delivery and manage the dead-letter queue',
+        defaults: { name: 'Jitterflow' },
+        usableAsTool: true,
+        inputs: [n8n_workflow_1.NodeConnectionTypes.Main],
+        outputs: [n8n_workflow_1.NodeConnectionTypes.Main],
+        credentials: [
+            {
+                name: 'jitterflowApi',
+                required: true,
+            },
+        ],
+        properties: [
+            {
+                displayName: 'Resource',
+                name: 'resource',
+                type: 'options',
+                noDataExpression: true,
+                options: [
+                    { name: 'Webhook', value: 'webhook' },
+                    { name: 'DLQ', value: 'dlq' },
+                ],
+                default: 'webhook',
+            },
+            // --- Webhook ---------------------------------------------------
+            {
+                displayName: 'Operation',
+                name: 'operation',
+                type: 'options',
+                noDataExpression: true,
+                displayOptions: { show: { resource: ['webhook'] } },
+                options: [
+                    {
+                        name: 'Send',
+                        value: 'send',
+                        description: 'Queue a webhook for jittered, rate-limited delivery',
+                        action: 'Send a webhook',
+                    },
+                ],
+                default: 'send',
+            },
+            {
+                displayName: 'Endpoint Key',
+                name: 'endpointKey',
+                type: 'string',
+                required: true,
+                default: '',
+                displayOptions: { show: { resource: ['webhook'], operation: ['send'] } },
+                description: 'The endpoint key from your Jitterflow dashboard (Endpoints -> Endpoint Key)',
+            },
+            {
+                displayName: 'Target Identifier',
+                name: 'targetIdentifier',
+                type: 'string',
+                default: '',
+                displayOptions: { show: { resource: ['webhook'], operation: ['send'] } },
+                description: 'Optional — paces delivery per this identifier (e.g. a mailbox or lead ID) instead of per endpoint. Defaults server-side to the endpoint key if left blank.',
+            },
+            {
+                displayName: 'Idempotency Key',
+                name: 'idempotencyKey',
+                type: 'string',
+                default: '={{$execution.id}}-{{$itemIndex}}',
+                displayOptions: { show: { resource: ['webhook'], operation: ['send'] } },
+                description: 'Repeating the same key returns the original job instead of creating a second one, so a workflow retry never double-sends. Defaults to the execution ID + item index.',
+            },
+            {
+                displayName: 'Payload',
+                name: 'payload',
+                type: 'json',
+                default: '={{ $json }}',
+                displayOptions: { show: { resource: ['webhook'], operation: ['send'] } },
+                description: "The JSON body to deliver to the endpoint's destination URL. Defaults to the whole input item.",
+            },
+            // --- DLQ ---------------------------------------------------------
+            {
+                displayName: 'Operation',
+                name: 'operation',
+                type: 'options',
+                noDataExpression: true,
+                displayOptions: { show: { resource: ['dlq'] } },
+                options: [
+                    {
+                        name: 'List',
+                        value: 'list',
+                        description: 'List dead-letter queue entries',
+                        action: 'List DLQ entries',
+                    },
+                    {
+                        name: 'Replay',
+                        value: 'replay',
+                        description: 'Re-enqueue a failed job for immediate delivery',
+                        action: 'Replay a DLQ job',
+                    },
+                    {
+                        name: 'Resolve',
+                        value: 'resolve',
+                        description: 'Mark a DLQ entry resolved without retrying it',
+                        action: 'Resolve a DLQ entry',
+                    },
+                ],
+                default: 'list',
+            },
+            {
+                displayName: 'Filter',
+                name: 'resolvedFilter',
+                type: 'options',
+                displayOptions: { show: { resource: ['dlq'], operation: ['list'] } },
+                options: [
+                    { name: 'All', value: 'all' },
+                    { name: 'Unresolved Only', value: 'unresolved' },
+                    { name: 'Resolved Only', value: 'resolved' },
+                ],
+                default: 'unresolved',
+            },
+            {
+                displayName: 'Job ID',
+                name: 'jobId',
+                type: 'string',
+                required: true,
+                default: '',
+                displayOptions: { show: { resource: ['dlq'], operation: ['replay', 'resolve'] } },
+                description: 'The WebhookJob ID to replay or resolve (from a prior List DLQ Entries call)',
+            },
+        ],
+    };
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        const resource = this.getNodeParameter('resource', 0);
+        const operation = this.getNodeParameter('operation', 0);
+        for (let i = 0; i < items.length; i++) {
+            try {
+                let responseData;
+                if (resource === 'webhook' && operation === 'send') {
+                    const endpointKey = this.getNodeParameter('endpointKey', i);
+                    const targetIdentifier = this.getNodeParameter('targetIdentifier', i);
+                    const idempotencyKey = this.getNodeParameter('idempotencyKey', i);
+                    const payloadRaw = this.getNodeParameter('payload', i);
+                    const payload = (typeof payloadRaw === 'string' ? JSON.parse(payloadRaw) : payloadRaw);
+                    const body = { payload };
+                    if (targetIdentifier)
+                        body.targetIdentifier = targetIdentifier;
+                    if (idempotencyKey)
+                        body.idempotencyKey = idempotencyKey;
+                    responseData = (await GenericFunctions_1.jitterflowApiRequest.call(this, 'POST', `/v1/ingest/${endpointKey}`, body));
+                }
+                else if (resource === 'dlq' && operation === 'list') {
+                    const resolvedFilter = this.getNodeParameter('resolvedFilter', i);
+                    const qs = {};
+                    if (resolvedFilter === 'resolved')
+                        qs.resolved = 'true';
+                    if (resolvedFilter === 'unresolved')
+                        qs.resolved = 'false';
+                    responseData = (await GenericFunctions_1.jitterflowApiRequest.call(this, 'GET', '/v1/dlq', undefined, qs));
+                }
+                else if (resource === 'dlq' && operation === 'replay') {
+                    const jobId = this.getNodeParameter('jobId', i);
+                    responseData = (await GenericFunctions_1.jitterflowApiRequest.call(this, 'POST', `/v1/dlq/${jobId}/retry`));
+                }
+                else if (resource === 'dlq' && operation === 'resolve') {
+                    const jobId = this.getNodeParameter('jobId', i);
+                    responseData = (await GenericFunctions_1.jitterflowApiRequest.call(this, 'POST', `/v1/dlq/${jobId}/resolve`));
+                }
+                else {
+                    throw new n8n_workflow_1.NodeApiError(this.getNode(), {
+                        message: `Unknown resource/operation combination: ${resource}/${operation}`,
+                    });
+                }
+                if (Array.isArray(responseData)) {
+                    returnData.push(...responseData.map((entry) => ({ json: entry, pairedItem: { item: i } })));
+                }
+                else {
+                    returnData.push({ json: responseData, pairedItem: { item: i } });
+                }
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({
+                        json: { error: error.message },
+                        pairedItem: { item: i },
+                    });
+                    continue;
+                }
+                throw new n8n_workflow_1.NodeApiError(this.getNode(), error);
+            }
+        }
+        return [returnData];
+    }
+}
+exports.Jitterflow = Jitterflow;

package/dist/nodes/Jitterflow/jitterflow.svg

@@ -0,0 +1,4 @@
+<svg width="60" height="60" viewBox="0 0 60 60" xmlns="http://www.w3.org/2000/svg">
+  <rect width="60" height="60" rx="12" fill="#4F46E5"/>
+  <path d="M14 38 L22 38 L26 24 L32 44 L36 30 L40 38 L46 38" stroke="#FFFFFF" stroke-width="4" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "n8n-nodes-jitterflow",
+  "version": "0.1.0",
+  "description": "n8n community node for Jitterflow — send webhooks through jittered, rate-limited delivery and manage the dead-letter queue (list, replay, resolve) from inside a workflow.",
+  "keywords": [
+    "n8n-community-node-package"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://jitterflow.io/integrations/n8n",
+  "bugs": {
+    "url": "https://github.com/jitterflow/n8n-nodes-jitterflow/issues"
+  },
+  "author": {
+    "name": "Jitterflow",
+    "email": "support@jitterflow.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jitterflow/n8n-nodes-jitterflow.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/JitterflowApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/Jitterflow/Jitterflow.node.js"
+    ]
+  },
+  "scripts": {
+    "build": "n8n-node build",
+    "dev": "n8n-node dev",
+    "lint": "n8n-node lint",
+    "release": "n8n-node release",
+    "test": "jest"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "devDependencies": {
+    "@n8n/node-cli": "^0.44.5",
+    "n8n-workflow": "^2.16.0",
+    "typescript": "^5.6.3",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "@types/jest": "^29.5.13",
+    "@types/node": "^20.16.10"
+  }
+}