n8n-nodes-onedesk 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# n8n-nodes-onedesk
+
+An [n8n](https://n8n.io) community node for **OneDesk**. Start workflows from
+OneDesk ticket activity (new tickets, replies, tag changes, and more) via
+OneDesk's outbound webhooks.
+
+This is a **trigger-only** node (OneDesk → n8n).
+
+## What's included
+
+- **OneDesk API credential** — an API key + base URL, sent as the `X-API-KEY`
+  header. Tested against `GET /api/integrations/me`.
+- **OneDesk Trigger node** — pick an event; when the workflow is activated the node
+  registers an outbound webhook with OneDesk (and removes it on deactivation). The
+  event payload becomes the node's output.
+
+### Events
+
+`ticket.created`, `ticket.updated`, `ticket.tags.updated`, `ticket.spam.updated`,
+`ticket.note.created`, `conversation.created`, `contact.updated`, `contact.deleted`,
+`automation.triggered`.
+
+Keep `src/events.ts` in sync with the backend's
+`apps/back-end/src/outbound-webhooks/webhook-events.ts`.
+
+## Backend endpoints it uses
+
+| n8n piece | OneDesk endpoint |
+| --- | --- |
+| Credential test | `GET /api/integrations/me` |
+| Trigger activate (`create`) | `POST /api/hooks/subscriptions` (with `via: "n8n"`) |
+| Trigger deactivate (`delete`) | `DELETE /api/hooks/subscriptions/:id` |
+| Event delivery | OneDesk POSTs to the node's webhook URL |
+
+## Develop
+
+```bash
+npm install
+npm run build          # tsc → dist/ (+ copies the icon)
+```
+
+### Test locally against a self-hosted n8n
+
+```bash
+# in this package
+npm run build
+npm link
+
+# in your n8n custom dir (~/.n8n/custom, create it if missing)
+npm link n8n-nodes-onedesk
+
+# start n8n; the OneDesk Trigger node + OneDesk API credential appear
+npx n8n
+```
+
+Point the credential's **Base URL** at your OneDesk API (ngrok for local dev, or
+production). Add the OneDesk Trigger node, pick an event, and activate the workflow —
+a subscription appears on OneDesk's **Settings → Integrations → n8n** page.
+
+## Publish
+
+```bash
+npm run build
+npm publish            # publishes n8n-nodes-onedesk to npm
+```
+
+Users then install it via n8n **Settings → Community Nodes → Install**
+(`n8n-nodes-onedesk`), or `npm install n8n-nodes-onedesk` in a self-hosted setup.
+
+> Verifying deliveries: each webhook request is signed with an
+> `X-OneDesk-Signature` header (HMAC-SHA256 of the body with the subscription
+> secret). Self-hosted receivers can verify it; see the OneDesk docs.

package/dist/credentials/OneDeskApi.credentials.d.ts

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

package/dist/credentials/OneDeskApi.credentials.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OneDeskApi = void 0;
+class OneDeskApi {
+    constructor() {
+        this.name = 'oneDeskApi';
+        this.displayName = 'OneDesk API';
+        this.documentationUrl = 'https://onedesk.so/docs/appIntegration';
+        this.properties = [
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Generate one in OneDesk under Settings → Integrations → API keys',
+            },
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: 'https://server.onedesk.so',
+                required: true,
+                description: 'The OneDesk API base URL (no trailing slash, no /api suffix)',
+            },
+        ];
+        // OneDesk's ApiKeyGuard reads the key from the X-API-KEY header.
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    'X-API-KEY': '={{$credentials.apiKey}}',
+                },
+            },
+        };
+        // The "Test" button in the credential dialog hits /integrations/me.
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl}}',
+                url: '/api/integrations/me',
+                method: 'GET',
+            },
+        };
+    }
+}
+exports.OneDeskApi = OneDeskApi;

package/dist/events.d.ts

@@ -0,0 +1,5 @@
+export declare const ONEDESK_EVENTS: {
+    name: string;
+    value: string;
+    description: string;
+}[];

package/dist/events.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ONEDESK_EVENTS = void 0;
+// Mirror of the backend's WEBHOOK_EVENTS
+// (apps/back-end/src/outbound-webhooks/webhook-events.ts). Keep in sync — each
+// entry becomes an option in the OneDesk Trigger node's event dropdown.
+exports.ONEDESK_EVENTS = [
+    { name: 'New Ticket', value: 'ticket.created', description: 'A new ticket is created' },
+    { name: 'Ticket Updated', value: 'ticket.updated', description: 'A ticket is updated (assignment, status, etc.)' },
+    { name: 'Ticket Tags Updated', value: 'ticket.tags.updated', description: "A ticket's tags change" },
+    { name: 'Ticket Spam Status Updated', value: 'ticket.spam.updated', description: 'A ticket is marked as (or unmarked from) spam' },
+    { name: 'New Ticket Note', value: 'ticket.note.created', description: 'A public note is added to a ticket' },
+    { name: 'New Conversation Message', value: 'conversation.created', description: 'A new reply/message is added to a ticket' },
+    { name: 'Contact Updated', value: 'contact.updated', description: 'A contact is updated' },
+    { name: 'Contact Deleted', value: 'contact.deleted', description: 'A contact is deleted' },
+    { name: 'Automation Triggered', value: 'automation.triggered', description: "An automation's Trigger Integration action fires" },
+];

package/dist/nodes/OneDesk/OneDeskTrigger.node.d.ts

@@ -0,0 +1,12 @@
+import { IHookFunctions, INodeType, INodeTypeDescription, IWebhookFunctions, IWebhookResponseData } from 'n8n-workflow';
+export declare class OneDeskTrigger implements INodeType {
+    description: INodeTypeDescription;
+    webhookMethods: {
+        default: {
+            checkExists(this: IHookFunctions): Promise<boolean>;
+            create(this: IHookFunctions): Promise<boolean>;
+            delete(this: IHookFunctions): Promise<boolean>;
+        };
+    };
+    webhook(this: IWebhookFunctions): Promise<IWebhookResponseData>;
+}

package/dist/nodes/OneDesk/OneDeskTrigger.node.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OneDeskTrigger = void 0;
+const MAIN_OUTPUT = 'main';
+const events_1 = require("../../events");
+class OneDeskTrigger {
+    constructor() {
+        this.description = {
+            displayName: 'OneDesk Trigger',
+            name: 'oneDeskTrigger',
+            icon: 'file:onedesk.svg',
+            group: ['trigger'],
+            version: 1,
+            subtitle: '={{$parameter["event"]}}',
+            description: 'Starts a workflow when a OneDesk event happens',
+            defaults: {
+                name: 'OneDesk Trigger',
+            },
+            // No input connections — it is a trigger.
+            inputs: [],
+            outputs: [MAIN_OUTPUT],
+            credentials: [
+                {
+                    name: 'oneDeskApi',
+                    required: true,
+                },
+            ],
+            webhooks: [
+                {
+                    name: 'default',
+                    httpMethod: 'POST',
+                    responseMode: 'onReceived',
+                    path: 'webhook',
+                },
+            ],
+            properties: [
+                {
+                    displayName: 'Event',
+                    name: 'event',
+                    type: 'options',
+                    required: true,
+                    default: 'ticket.created',
+                    description: 'The OneDesk event that triggers the workflow',
+                    options: events_1.ONEDESK_EVENTS.map((e) => ({
+                        name: e.name,
+                        value: e.value,
+                        description: e.description,
+                    })),
+                },
+            ],
+        };
+        this.webhookMethods = {
+            default: {
+                async checkExists() {
+                    const webhookData = this.getWorkflowStaticData('node');
+                    return Boolean(webhookData.subscriptionId);
+                },
+                async create() {
+                    const webhookUrl = this.getNodeWebhookUrl('default');
+                    const event = this.getNodeParameter('event');
+                    const workflowName = this.getWorkflow().name;
+                    const response = (await this.helpers.httpRequestWithAuthentication.call(this, 'oneDeskApi', {
+                        method: 'POST',
+                        baseURL: '={{$credentials.baseUrl}}',
+                        url: '/api/hooks/subscriptions',
+                        body: {
+                            event,
+                            targetUrl: webhookUrl,
+                            label: workflowName,
+                            via: 'n8n',
+                        },
+                        json: true,
+                    }));
+                    if (response.id === undefined) {
+                        return false;
+                    }
+                    this.getWorkflowStaticData('node').subscriptionId = response.id;
+                    return true;
+                },
+                async delete() {
+                    const webhookData = this.getWorkflowStaticData('node');
+                    if (!webhookData.subscriptionId) {
+                        return true;
+                    }
+                    try {
+                        await this.helpers.httpRequestWithAuthentication.call(this, 'oneDeskApi', {
+                            method: 'DELETE',
+                            baseURL: '={{$credentials.baseUrl}}',
+                            url: `/api/hooks/subscriptions/${webhookData.subscriptionId}`,
+                        });
+                    }
+                    catch {
+                        // If OneDesk already removed it, treat as success.
+                    }
+                    delete webhookData.subscriptionId;
+                    return true;
+                },
+            },
+        };
+    }
+    async webhook() {
+        const body = this.getBodyData();
+        return {
+            workflowData: [this.helpers.returnJsonArray(body)],
+        };
+    }
+}
+exports.OneDeskTrigger = OneDeskTrigger;

package/dist/nodes/OneDesk/onedesk.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
+  <rect width="24" height="24" rx="5" fill="#0969da"/>
+  <path d="M12 5.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13Zm0 3a3.5 3.5 0 1 1 0 7 3.5 3.5 0 0 1 0-7Z" fill="#fff"/>
+</svg>

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "n8n-nodes-onedesk",
+  "version": "1.0.0",
+  "description": "n8n community node for OneDesk — trigger workflows from ticket activity.",
+  "keywords": [
+    "n8n-community-node-package",
+    "onedesk",
+    "support",
+    "helpdesk"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc && npm run copy-icons",
+    "copy-icons": "node -e \"const fs=require('fs'),p=require('path');const src='src/nodes/OneDesk/onedesk.svg',dst='dist/nodes/OneDesk/onedesk.svg';fs.mkdirSync(p.dirname(dst),{recursive:true});fs.copyFileSync(src,dst)\"",
+    "dev": "tsc --watch",
+    "lint": "tsc --noEmit"
+  },
+  "files": [
+    "dist"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/OneDeskApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/OneDesk/OneDeskTrigger.node.js"
+    ]
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "devDependencies": {
+    "n8n-workflow": "^1.55.0",
+    "typescript": "^5.4.0"
+  }
+}