@wesell/n8n-nodes-confirmx 0.1.0

package/nodes/ConfirmX/ConfirmXMessage.node.ts

@@ -0,0 +1,361 @@
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow'
+import { confirmxApiRequest, loadAccountOptions } from '../../transports/http'
+
+export class ConfirmXMessage implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'ConfirmX Message',
+    name: 'confirmXMessage',
+    icon: 'file:confirmx.svg',
+    group: ['transform'],
+    version: 1,
+    subtitle: '={{$parameter["operation"]}}',
+    description:
+      'Send WhatsApp messages, list messages in a conversation, start a new conversation with a template, or retry a failed message.',
+    defaults: { name: 'ConfirmX Message' },
+    inputs: ['main'],
+    outputs: ['main'],
+    credentials: [{ name: 'confirmXApi', required: true }],
+    properties: [
+      {
+        displayName: 'Operation',
+        name: 'operation',
+        type: 'options',
+        noDataExpression: true,
+        options: [
+          {
+            name: 'Send Text',
+            value: 'sendText',
+            action: 'Send text message',
+            description:
+              'Send a free-form text message in an existing conversation. Use ONLY when the conversation is open (within 24h of the customer\'s last inbound message); otherwise use `startConversation` with a template. Requires `conversationId` and `body`. Optional `replyToMessageId` to quote a previous message.',
+          },
+          {
+            name: 'Send Media',
+            value: 'sendMedia',
+            action: 'Send media message',
+            description:
+              'Send a media message (image, video, document, audio) inside an existing conversation. Requires `conversationId` and `mediaUrl` (publicly fetchable URL); for documents/audio/voice also supply `mediaFilename`. Use ONLY within the 24h messaging window.',
+          },
+          {
+            name: 'Start Conversation',
+            value: 'startConversation',
+            action: 'Start conversation with template',
+            description:
+              "Open a new WhatsApp conversation with a customer by sending an approved template. This bypasses the 24h messaging window — it's how you reach a customer proactively. Requires `accountId`, `phoneNumber` (E.164), and `templateName`. Returns the new conversation id you can use for follow-up messages.",
+          },
+          {
+            name: 'List Messages',
+            value: 'listMessages',
+            action: 'List messages in conversation',
+            description:
+              'Page through the messages in a conversation. Returns up to `limit` messages per page with an opaque `nextCursor` for the next page. Requires `conversationId`.',
+          },
+          {
+            name: 'Retry',
+            value: 'retry',
+            action: 'Retry a failed message',
+            description:
+              'Retry a previously failed outbound message. Requires `messageId`. Only failed messages can be retried — calling on a delivered/sent message returns 400.',
+          },
+        ],
+        default: 'sendText',
+      },
+      // --- Account (only for startConversation) ---
+      {
+        displayName: 'Account',
+        name: 'accountId',
+        type: 'resourceLocator',
+        default: { mode: 'list', value: '' },
+        required: true,
+        displayOptions: { show: { operation: ['startConversation'] } },
+        modes: [
+          { displayName: 'From List', name: 'list', type: 'list', typeOptions: { searchable: true } },
+          { displayName: 'By ID', name: 'id', type: 'string' },
+        ],
+        typeOptions: { loadOptionsMethod: 'getAccounts' },
+        description: 'WhatsApp account to send from',
+      },
+      // --- Send Text ---
+      {
+        displayName: 'Conversation ID',
+        name: 'sendConversationId',
+        type: 'string',
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['sendText', 'sendMedia'] } },
+      },
+      {
+        displayName: 'Body',
+        name: 'textBody',
+        type: 'string',
+        typeOptions: { rows: 4 },
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['sendText'] } },
+      },
+      {
+        displayName: 'Reply To Message ID',
+        name: 'replyToMessageId',
+        type: 'string',
+        default: '',
+        displayOptions: { show: { operation: ['sendText', 'sendMedia'] } },
+        description: 'Optional — quote an existing message',
+      },
+      // --- Send Media ---
+      {
+        displayName: 'Media Type',
+        name: 'mediaType',
+        type: 'options',
+        default: 'image',
+        required: true,
+        displayOptions: { show: { operation: ['sendMedia'] } },
+        options: [
+          { name: 'Image', value: 'image' },
+          { name: 'Video', value: 'video' },
+          { name: 'Document', value: 'document' },
+          { name: 'Audio', value: 'audio' },
+          { name: 'Voice', value: 'voice' },
+        ],
+      },
+      {
+        displayName: 'Media URL',
+        name: 'mediaUrl',
+        type: 'string',
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['sendMedia'] } },
+        description: 'Public URL of the media file',
+      },
+      {
+        displayName: 'Media Caption',
+        name: 'mediaCaption',
+        type: 'string',
+        default: '',
+        displayOptions: { show: { operation: ['sendMedia'] } },
+      },
+      {
+        displayName: 'Media Filename',
+        name: 'mediaFilename',
+        type: 'string',
+        default: '',
+        displayOptions: {
+          show: { operation: ['sendMedia'], mediaType: ['document', 'audio', 'voice'] },
+        },
+        description: 'Required for document/audio/voice; controls how the file is named on receipt.',
+      },
+      // --- Start Conversation ---
+      {
+        displayName: 'Phone Number (E.164)',
+        name: 'phoneNumber',
+        type: 'string',
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['startConversation'] } },
+        placeholder: '+201234567890',
+        description: 'Customer phone in E.164 format',
+      },
+      {
+        displayName: 'Template Name',
+        name: 'templateName',
+        type: 'string',
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['startConversation'] } },
+      },
+      {
+        displayName: 'Template Language',
+        name: 'templateLanguage',
+        type: 'string',
+        default: 'en',
+        displayOptions: { show: { operation: ['startConversation'] } },
+      },
+      {
+        displayName: 'Template Components (JSON)',
+        name: 'templateComponents',
+        type: 'json',
+        default: '[]',
+        displayOptions: { show: { operation: ['startConversation'] } },
+        description:
+          'Optional JSON array matching Meta template components. Example: `[{"type":"body","parameters":[{"type":"text","text":"Order #12345"}]}]`.',
+      },
+      // --- List Messages ---
+      {
+        displayName: 'Conversation ID',
+        name: 'listConversationId',
+        type: 'string',
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['listMessages'] } },
+      },
+      {
+        displayName: 'Cursor',
+        name: 'cursor',
+        type: 'string',
+        default: '',
+        displayOptions: { show: { operation: ['listMessages'] } },
+        description: 'Opaque cursor from previous page response',
+      },
+      {
+        displayName: 'Limit',
+        name: 'messagesLimit',
+        type: 'number',
+        default: 50,
+        typeOptions: { minValue: 1, maxValue: 100 },
+        displayOptions: { show: { operation: ['listMessages'] } },
+      },
+      // --- Retry ---
+      {
+        displayName: 'Message ID',
+        name: 'messageId',
+        type: 'string',
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['retry'] } },
+      },
+      // --- Common ---
+      {
+        displayName: 'Integration Label',
+        name: 'integrationLabel',
+        type: 'string',
+        default: '',
+        displayOptions: { show: { operation: ['sendText', 'sendMedia', 'startConversation'] } },
+        description:
+          'Optional human-readable label shown in inbox (max 64 chars). Example: "n8n: Order Confirmation".',
+      },
+      {
+        displayName: 'Idempotency Key (X-Request-Id)',
+        name: 'requestId',
+        type: 'string',
+        default: '',
+        displayOptions: { show: { operation: ['sendText', 'sendMedia', 'startConversation', 'retry'] } },
+        description:
+          'Optional UUID — replay-safe debits. Replays with the same id return the cached debit without re-charging.',
+      },
+    ],
+    usableAsTool: true,
+  }
+
+  methods = {
+    loadOptions: {
+      async getAccounts(this: any) {
+        return await loadAccountOptions(this)
+      },
+    },
+  }
+
+  async execute(this: any) {
+    const items = this.getInputData()
+    const returnData: any[] = []
+    const resolveAccountId = (i: number) => {
+      const v = this.getNodeParameter('accountId', i, '') as any
+      if (!v) return undefined
+      return typeof v === 'string' ? v : v?.value
+    }
+
+    for (let i = 0; i < items.length; i++) {
+      const operation = this.getNodeParameter('operation', i) as string
+      const extraHeaders: Record<string, string> = {}
+      const requestId = (this.getNodeParameter('requestId', i, '') as string).trim()
+      if (requestId) extraHeaders['X-Request-Id'] = requestId
+
+      if (operation === 'sendText') {
+        const conversationId = this.getNodeParameter('sendConversationId', i) as string
+        const body = this.getNodeParameter('textBody', i) as string
+        const replyToMessageId = (this.getNodeParameter('replyToMessageId', i, '') as string) || undefined
+        const integrationLabel = (this.getNodeParameter('integrationLabel', i, '') as string) || undefined
+        const payload: Record<string, any> = { conversationId, type: 'text', body }
+        if (replyToMessageId) payload.replyToMessageId = replyToMessageId
+        if (integrationLabel) payload.integrationLabel = integrationLabel
+
+        const res = await confirmxApiRequest<{ message: any }>(this, {
+          method: 'POST',
+          endpoint: '/messages/send',
+          body: payload,
+          headers: extraHeaders,
+        })
+        returnData.push({ json: res.message })
+      } else if (operation === 'sendMedia') {
+        const conversationId = this.getNodeParameter('sendConversationId', i) as string
+        const mediaType = this.getNodeParameter('mediaType', i) as string
+        const mediaUrl = this.getNodeParameter('mediaUrl', i) as string
+        const mediaCaption = (this.getNodeParameter('mediaCaption', i, '') as string) || undefined
+        const mediaFilename = (this.getNodeParameter('mediaFilename', i, '') as string) || undefined
+        const replyToMessageId = (this.getNodeParameter('replyToMessageId', i, '') as string) || undefined
+        const integrationLabel = (this.getNodeParameter('integrationLabel', i, '') as string) || undefined
+        const payload: Record<string, any> = {
+          conversationId,
+          type: mediaType,
+          mediaUrl,
+        }
+        if (mediaCaption) payload.mediaCaption = mediaCaption
+        if (mediaFilename) payload.mediaFilename = mediaFilename
+        if (replyToMessageId) payload.replyToMessageId = replyToMessageId
+        if (integrationLabel) payload.integrationLabel = integrationLabel
+
+        const res = await confirmxApiRequest<{ message: any }>(this, {
+          method: 'POST',
+          endpoint: '/messages/send',
+          body: payload,
+          headers: extraHeaders,
+        })
+        returnData.push({ json: res.message })
+      } else if (operation === 'startConversation') {
+        const accountId = resolveAccountId(i) as string
+        const phoneNumber = this.getNodeParameter('phoneNumber', i) as string
+        const templateName = this.getNodeParameter('templateName', i) as string
+        const templateLanguage = (this.getNodeParameter('templateLanguage', i) as string) || 'en'
+        const templateComponentsRaw = (this.getNodeParameter('templateComponents', i, '[]') as string) || '[]'
+        const integrationLabel = (this.getNodeParameter('integrationLabel', i, '') as string) || undefined
+
+        let templateComponents: any[] = []
+        try {
+          const parsed = JSON.parse(templateComponentsRaw)
+          if (Array.isArray(parsed) && parsed.length) templateComponents = parsed
+        } catch {
+          throw new Error('Template Components must be valid JSON array')
+        }
+
+        const payload: Record<string, any> = {
+          accountId,
+          phoneNumber,
+          templateName,
+          templateLanguage,
+        }
+        if (templateComponents.length) payload.templateComponents = templateComponents
+        if (integrationLabel) payload.integrationLabel = integrationLabel
+
+        const res = await confirmxApiRequest<{ conversation: any; message: any }>(this, {
+          method: 'POST',
+          endpoint: '/messages/start-conversation',
+          body: payload,
+          headers: extraHeaders,
+        })
+        returnData.push({ json: { conversation: res.conversation, message: res.message } })
+      } else if (operation === 'listMessages') {
+        const conversationId = this.getNodeParameter('listConversationId', i) as string
+        const cursor = (this.getNodeParameter('cursor', i, '') as string) || undefined
+        const limit = (this.getNodeParameter('messagesLimit', i) as number) || 50
+        const qs: Record<string, any> = { limit }
+        if (cursor) qs.cursor = cursor
+        const res = await confirmxApiRequest<{ messages: any[]; nextCursor: string | null }>(this, {
+          method: 'GET',
+          endpoint: `/conversations/${conversationId}/messages`,
+          qs,
+        })
+        for (const m of res.messages || []) {
+          returnData.push({ json: m })
+        }
+      } else if (operation === 'retry') {
+        const messageId = this.getNodeParameter('messageId', i) as string
+        const res = await confirmxApiRequest<{ ok?: boolean; message?: any }>(this, {
+          method: 'POST',
+          endpoint: `/messages/${messageId}/retry`,
+          headers: extraHeaders,
+        })
+        returnData.push({ json: { messageId, ...(res as any) } })
+      }
+    }
+
+    return [returnData]
+  }
+}

package/nodes/ConfirmX/ConfirmXShippingZone.node.d.ts

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

package/nodes/ConfirmX/ConfirmXShippingZone.node.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfirmXShippingZone = void 0;
+const http_1 = require("../../transports/http");
+class ConfirmXShippingZone {
+    constructor() {
+        this.description = {
+            displayName: 'ConfirmX Shipping Zone',
+            name: 'confirmXShippingZone',
+            icon: 'file:confirmx.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["operation"]}}',
+            description: 'Fuzzy-match an Egyptian governorate + optional area against the ConfirmX shipping-zone taxonomy (10k+ rows, Arabic + English, aliases). Useful for extracting shipping zones from free-text customer input.',
+            defaults: { name: 'ConfirmX Shipping Zone' },
+            inputs: ['main'],
+            outputs: ['main'],
+            credentials: [{ name: 'confirmXApi', required: true }],
+            properties: [
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    options: [
+                        {
+                            name: 'Match',
+                            value: 'match',
+                            action: 'Fuzzy-match a shipping zone',
+                            description: "Fuzzy-match an Egyptian governorate and (optionally) area from free-text customer input (Arabic or English, with typos / aliases tolerated). Returns the matched governorate + area with confidence scores and `externalId`s suitable for writing back to a shipping platform. If `area` is omitted, only the governorate is matched. On success returns `{governorate, area}`; on governorate-not-found returns `suggestions`; on ambiguous area returns `options[]` — present those options to the user and call again with the chosen governorate. Best for Egyptian e-commerce flows.",
+                        },
+                        {
+                            name: 'List Governorates',
+                            value: 'list',
+                            action: 'List governorates and areas',
+                            description: 'Return the full active governorate→areas tree. Reference data for orgs shipping to Egypt.',
+                        },
+                    ],
+                    default: 'match',
+                },
+                // --- Match parameters ---
+                {
+                    displayName: 'Governorate',
+                    name: 'governorate',
+                    type: 'string',
+                    default: '',
+                    required: true,
+                    displayOptions: { show: { operation: ['match'] } },
+                    description: 'Free-text governorate name. Examples: "Cairo", "القاهرة", "Giza". Typos and Arabic/English mixing are tolerated.',
+                },
+                {
+                    displayName: 'Area',
+                    name: 'area',
+                    type: 'string',
+                    default: '',
+                    displayOptions: { show: { operation: ['match'] } },
+                    description: 'Optional free-text area name (e.g. "Maadi", "المعادي"). If omitted, only the governorate is matched.',
+                },
+            ],
+            usableAsTool: true,
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        for (let i = 0; i < items.length; i++) {
+            const operation = this.getNodeParameter('operation', i);
+            if (operation === 'match') {
+                const governorate = this.getNodeParameter('governorate', i);
+                const areaRaw = this.getNodeParameter('area', i) || '';
+                const body = { governorate };
+                if (areaRaw.trim())
+                    body.area = areaRaw.trim();
+                const res = await (0, http_1.confirmxApiRequest)(this, {
+                    method: 'POST',
+                    endpoint: '/shipping-zones/match',
+                    body,
+                });
+                returnData.push({ json: res });
+            }
+            else if (operation === 'list') {
+                const res = await (0, http_1.confirmxApiRequest)(this, {
+                    method: 'GET',
+                    endpoint: '/shipping-zones',
+                });
+                const governorates = res.governorates || [];
+                // Emit one item per governorate so downstream nodes can iterate easily.
+                for (const g of governorates) {
+                    returnData.push({ json: g });
+                }
+                if (governorates.length === 0) {
+                    returnData.push({ json: { governorates: [] } });
+                }
+            }
+        }
+        return [returnData];
+    }
+}
+exports.ConfirmXShippingZone = ConfirmXShippingZone;
+//# sourceMappingURL=ConfirmXShippingZone.node.js.map

package/nodes/ConfirmX/ConfirmXShippingZone.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfirmXShippingZone.node.js","sourceRoot":"","sources":["ConfirmXShippingZone.node.ts"],"names":[],"mappings":"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"}

package/nodes/ConfirmX/ConfirmXShippingZone.node.ts

@@ -0,0 +1,103 @@
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow'
+import { confirmxApiRequest } from '../../transports/http'
+
+export class ConfirmXShippingZone implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'ConfirmX Shipping Zone',
+    name: 'confirmXShippingZone',
+    icon: 'file:confirmx.svg',
+    group: ['transform'],
+    version: 1,
+    subtitle: '={{$parameter["operation"]}}',
+    description:
+      'Fuzzy-match an Egyptian governorate + optional area against the ConfirmX shipping-zone taxonomy (10k+ rows, Arabic + English, aliases). Useful for extracting shipping zones from free-text customer input.',
+    defaults: { name: 'ConfirmX Shipping Zone' },
+    inputs: ['main'],
+    outputs: ['main'],
+    credentials: [{ name: 'confirmXApi', required: true }],
+    properties: [
+      {
+        displayName: 'Operation',
+        name: 'operation',
+        type: 'options',
+        noDataExpression: true,
+        options: [
+          {
+            name: 'Match',
+            value: 'match',
+            action: 'Fuzzy-match a shipping zone',
+            description:
+              "Fuzzy-match an Egyptian governorate and (optionally) area from free-text customer input (Arabic or English, with typos / aliases tolerated). Returns the matched governorate + area with confidence scores and `externalId`s suitable for writing back to a shipping platform. If `area` is omitted, only the governorate is matched. On success returns `{governorate, area}`; on governorate-not-found returns `suggestions`; on ambiguous area returns `options[]` — present those options to the user and call again with the chosen governorate. Best for Egyptian e-commerce flows.",
+          },
+          {
+            name: 'List Governorates',
+            value: 'list',
+            action: 'List governorates and areas',
+            description:
+              'Return the full active governorate→areas tree. Reference data for orgs shipping to Egypt.',
+          },
+        ],
+        default: 'match',
+      },
+      // --- Match parameters ---
+      {
+        displayName: 'Governorate',
+        name: 'governorate',
+        type: 'string',
+        default: '',
+        required: true,
+        displayOptions: { show: { operation: ['match'] } },
+        description:
+          'Free-text governorate name. Examples: "Cairo", "القاهرة", "Giza". Typos and Arabic/English mixing are tolerated.',
+      },
+      {
+        displayName: 'Area',
+        name: 'area',
+        type: 'string',
+        default: '',
+        displayOptions: { show: { operation: ['match'] } },
+        description:
+          'Optional free-text area name (e.g. "Maadi", "المعادي"). If omitted, only the governorate is matched.',
+      },
+    ],
+    usableAsTool: true,
+  }
+
+  async execute(this: any) {
+    const items = this.getInputData()
+    const returnData: any[] = []
+
+    for (let i = 0; i < items.length; i++) {
+      const operation = this.getNodeParameter('operation', i) as string
+
+      if (operation === 'match') {
+        const governorate = this.getNodeParameter('governorate', i) as string
+        const areaRaw = (this.getNodeParameter('area', i) as string) || ''
+        const body: Record<string, any> = { governorate }
+        if (areaRaw.trim()) body.area = areaRaw.trim()
+
+        const res = await confirmxApiRequest<any>(this, {
+          method: 'POST',
+          endpoint: '/shipping-zones/match',
+          body,
+        })
+        returnData.push({ json: res })
+      } else if (operation === 'list') {
+        const res = await confirmxApiRequest<any>(this, {
+          method: 'GET',
+          endpoint: '/shipping-zones',
+        })
+        const governorates = res.governorates || []
+        // Emit one item per governorate so downstream nodes can iterate easily.
+        for (const g of governorates) {
+          returnData.push({ json: g })
+        }
+        if (governorates.length === 0) {
+          returnData.push({ json: { governorates: [] } })
+        }
+      }
+    }
+
+    return [returnData]
+  }
+}

package/nodes/ConfirmX/ConfirmXTemplate.node.d.ts

@@ -0,0 +1,13 @@
+import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class ConfirmXTemplate implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            getAccounts(this: any): Promise<{
+                name: string;
+                value: string;
+            }[]>;
+        };
+    };
+    execute(this: any): Promise<any[][]>;
+}