n8n-nodes-chatads 0.1.2 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 ## ChatAds n8n Wrapper
 
-Custom n8n node + credential that call the FastAPI endpoint defined in `affiliate/chatads_backend.py`. The node wraps `/v1/chatads/messages`, handles authentication via the `x-api-key` header, and exposes every field from the `FunctionItem` Pydantic model so you can orchestrate ChatAds scoring inside n8n workflows.
+Custom n8n node + credential that calls the ChatAds API endpoint `/v1/chatads/messages`. Handles authentication via the `x-api-key` header and exposes all supported API fields so you can orchestrate ChatAds inside n8n workflows.
 
 ### Layout
 
@@ -19,20 +19,34 @@ Custom n8n node + credential that call the FastAPI endpoint defined in `affiliat
    ```
    This produces `dist/credentials/ChatAdsApi.credentials.js` and `dist/nodes/ChatAds/ChatAds.node.js`.
 2. Copy the compiled `dist` directory into your n8n custom nodes directory (for example `~/.n8n/custom/`) or publish the package to your internal npm registry and install it where your n8n instance can resolve it.
-3. Restart n8n. The new **ChatAds** node will appear under the “Transform” group. Add it to a workflow, select the `ChatAds API` credential, and supply either:
-   - A simple `message` plus optional fields (IP, domain, etc.), or
-   - A raw JSON payload that matches the server-side `FunctionItem` contract (only documented fields are accepted; unexpected keys are rejected to prevent tampering).
+3. Restart n8n. The new **ChatAds** node will appear under the "Transform" group. Add it to a workflow, select the `ChatAds API` credential, and supply either:
+   - A simple `message` plus optional fields (IP, country, etc.), or
+   - A raw JSON payload (only documented fields are accepted; unexpected keys are rejected to prevent tampering).
 4. Optionally tune `Max Concurrent Requests` (default 4) and `Request Timeout (seconds)` for high-volume workflows. The node keeps item ordering consistent even when issuing requests in parallel.
 5. When executed, the node sends a POST request to `{{baseUrl}}/v1/chatads/messages` (configurable via the `Endpoint Override` parameter) with your `x-api-key` header and returns the FastAPI response verbatim so downstream nodes can branch on `success`, `error`, or any ad copy the backend generated.
 
-Because the wrapper still uses `this.helpers.httpRequest`, it honors n8n’s retry/backoff settings and the `Continue On Fail` toggle while layering per-node timeouts and error payloads for easier debugging.
-`Extra Fields (JSON)` is validated and limited to the same keys exposed in `FunctionItem`, so untrusted workflows cannot inject credentials or arbitrary payload fields.
+Because the wrapper still uses `this.helpers.httpRequest`, it honors n8n's retry/backoff settings and the `Continue On Fail` toggle while layering per-node timeouts and error payloads for easier debugging.
+`Extra Fields (JSON)` is validated to prevent conflicts with reserved parameter keys, so untrusted workflows cannot silently override core fields.
 
 ### Releasing/Patching
 
 1. Bump the version in `package.json` whenever you change behavior (validation rules, new fields, etc.).
 2. Run `npm run build` to regenerate `dist/` artifacts—**these compiled files are what n8n loads**, so they must stay in sync with the TypeScript sources.
 3. Copy/publish the updated `dist/` directory to your custom nodes location or npm registry, then restart n8n.
-4. If the backend `FunctionItem` schema changes, update both the parameter list in `ChatAds.node.ts` and the `ALLOWED_PAYLOAD_FIELDS` set near the top of the file to keep validation in sync.
+4. If the backend `FunctionItem` schema changes, update both the parameter list in `ChatAds.node.ts` and the `OPTIONAL_FIELDS` set near the top of the file to keep validation in sync.
 
 Consider keeping a short changelog (GitHub release notes or a `CHANGELOG.md`) so downstream workflows know when to reinstall the node.
+
+### Request Fields
+
+The node accepts the following fields (via parameters or `Extra Fields (JSON)`):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `message` | string (required) | Message to analyze (1-5000 chars) |
+| `ip` | string | Client IP address for geo-detection |
+| `country` | string | ISO 3166-1 alpha-2 country code for geo-targeting |
+| `message_analysis` | string | Extraction method: `"fast"`, `"balanced"` (default), `"thorough"` |
+| `fill_priority` | string | URL resolution: `"speed"` or `"coverage"` (default) |
+| `min_intent` | string | Intent filter: `"any"`, `"low"` (default), `"medium"`, `"high"` |
+| `skip_message_analysis` | boolean | Skip NLP/LLM and use message directly as search query |

package/dist/nodes/ChatAds/ChatAds.node.js

@@ -3,25 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatAds = void 0;
 const n8n_workflow_1 = require("n8n-workflow");
 const DEFAULT_ENDPOINT = '/v1/chatads/messages';
-const ALLOWED_PAYLOAD_FIELDS = new Set([
-    'timestamp',
-    'pageUrl',
-    'pageTitle',
-    'referrer',
-    'address',
-    'email',
-    'type',
-    'domain',
-    'userAgent',
+const OPTIONAL_FIELDS = new Set([
     'ip',
-    'reason',
-    'company',
-    'name',
-    'message',
     'country',
-    'language',
-    'website',
+    'message_analysis',
+    'fill_priority',
+    'min_intent',
+    'skip_message_analysis',
 ]);
+const FIELD_ALIASES = {
+    messageanalysis: 'message_analysis',
+    message_analysis: 'message_analysis',
+    fillpriority: 'fill_priority',
+    fill_priority: 'fill_priority',
+    minintent: 'min_intent',
+    min_intent: 'min_intent',
+    skipmessageanalysis: 'skip_message_analysis',
+    skip_message_analysis: 'skip_message_analysis',
+};
+const RESERVED_PAYLOAD_KEYS = new Set(['message', ...OPTIONAL_FIELDS]);
 const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 const normalizeJsonPath = (path) => path.startsWith('/') ? path : `/${path}`;
 const parseJsonObject = (context, value, fieldName, itemIndex) => {
@@ -52,20 +52,6 @@ const coerceToString = (context, source, key, value, itemIndex) => {
     }
     throw new n8n_workflow_1.NodeOperationError(context.getNode(), `${source} field "${key}" must be a string or primitive`, { itemIndex });
 };
-const sanitizeRecord = (context, payload, source, itemIndex) => {
-    const sanitized = {};
-    for (const [key, value] of Object.entries(payload)) {
-        if (value === undefined || value === null) {
-            continue;
-        }
-        const normalized = coerceToString(context, source, key, value, itemIndex);
-        if (normalized === '') {
-            continue;
-        }
-        sanitized[key] = normalized;
-    }
-    return sanitized;
-};
 const ensureMessage = (context, value, itemIndex) => {
     if (typeof value !== 'string') {
         throw new n8n_workflow_1.NodeOperationError(context.getNode(), 'Field "message" must be provided as a string', { itemIndex });
@@ -76,6 +62,50 @@ const ensureMessage = (context, value, itemIndex) => {
     }
     return trimmed;
 };
+const normalizeFieldKey = (key) => { var _a; return (_a = FIELD_ALIASES[key.toLowerCase()]) !== null && _a !== void 0 ? _a : key; };
+const normalizeOptionalField = (key) => {
+    const normalized = normalizeFieldKey(key);
+    if (OPTIONAL_FIELDS.has(normalized)) {
+        return normalized;
+    }
+    return undefined;
+};
+const assertNoReservedConflicts = (context, source, extras, itemIndex) => {
+    const conflicts = Object.keys(extras).filter((key) => RESERVED_PAYLOAD_KEYS.has(normalizeFieldKey(key)));
+    if (conflicts.length > 0) {
+        throw new n8n_workflow_1.NodeOperationError(context.getNode(), `${source} contains reserved keys: ${conflicts.join(', ')}`, { itemIndex });
+    }
+};
+const buildPayloadFromObject = (context, input, source, itemIndex) => {
+    const payload = {};
+    const extras = {};
+    const message = ensureMessage(context, input.message, itemIndex);
+    payload.message = message;
+    for (const [rawKey, rawValue] of Object.entries(input)) {
+        if (rawKey === 'message') {
+            continue;
+        }
+        if (rawValue === undefined || rawValue === null || rawValue === '') {
+            continue;
+        }
+        const optionalKey = normalizeOptionalField(rawKey);
+        if (optionalKey) {
+            if (optionalKey === 'skip_message_analysis') {
+                if (typeof rawValue !== 'boolean') {
+                    throw new n8n_workflow_1.NodeOperationError(context.getNode(), `${source} field "${rawKey}" must be a boolean`, { itemIndex });
+                }
+                payload[optionalKey] = rawValue;
+                continue;
+            }
+            payload[optionalKey] = coerceToString(context, source, rawKey, rawValue, itemIndex);
+            continue;
+        }
+        extras[rawKey] = rawValue;
+    }
+    assertNoReservedConflicts(context, source, extras, itemIndex);
+    Object.assign(payload, extras);
+    return payload;
+};
 const buildErrorPayload = (error) => {
     const fallback = {
         message: 'Unknown error',
@@ -102,13 +132,6 @@ const buildErrorPayload = (error) => {
     }
     return fallback;
 };
-const assertAllowedFields = (context, source, payload, allowed, itemIndex) => {
-    for (const key of Object.keys(payload)) {
-        if (!allowed.has(key)) {
-            throw new n8n_workflow_1.NodeOperationError(context.getNode(), `${source} field "${key}" is not supported`, { itemIndex });
-        }
-    }
-};
 class ChatAds {
     constructor() {
         this.description = {
@@ -192,102 +215,62 @@ class ChatAds {
                         },
                     },
                     options: [
-                        {
-                            displayName: 'Timestamp',
-                            name: 'timestamp',
-                            type: 'string',
-                            default: '',
-                            description: 'ISO timestamp when the interaction occurred',
-                        },
-                        {
-                            displayName: 'Page URL',
-                            name: 'pageUrl',
-                            type: 'string',
-                            default: '',
-                        },
-                        {
-                            displayName: 'Page Title',
-                            name: 'pageTitle',
-                            type: 'string',
-                            default: '',
-                        },
-                        {
-                            displayName: 'Referrer',
-                            name: 'referrer',
-                            type: 'string',
-                            default: '',
-                        },
-                        {
-                            displayName: 'Address',
-                            name: 'address',
-                            type: 'string',
-                            default: '',
-                        },
-                        {
-                            displayName: 'Email',
-                            name: 'email',
-                            type: 'string',
-                            default: '',
-                        },
-                        {
-                            displayName: 'Type',
-                            name: 'type',
-                            type: 'string',
-                            default: '',
-                        },
-                        {
-                            displayName: 'Domain',
-                            name: 'domain',
-                            type: 'string',
-                            default: '',
-                        },
-                        {
-                            displayName: 'User Agent',
-                            name: 'userAgent',
-                            type: 'string',
-                            default: '',
-                        },
                         {
                             displayName: 'IP Address',
                             name: 'ip',
                             type: 'string',
                             default: '',
+                            description: 'Client IP address for geo-detection',
                         },
                         {
-                            displayName: 'Reason',
-                            name: 'reason',
-                            type: 'string',
-                            default: '',
-                        },
-                        {
-                            displayName: 'Company',
-                            name: 'company',
+                            displayName: 'Country',
+                            name: 'country',
                             type: 'string',
                             default: '',
+                            description: 'ISO 3166-1 alpha-2 country code for geo-targeting',
                         },
                         {
-                            displayName: 'Name',
-                            name: 'name',
-                            type: 'string',
-                            default: '',
+                            displayName: 'Message Analysis',
+                            name: 'message_analysis',
+                            type: 'options',
+                            options: [
+                                { name: 'Fast', value: 'fast' },
+                                { name: 'Balanced', value: 'balanced' },
+                                { name: 'Thorough', value: 'thorough' },
+                            ],
+                            default: 'balanced',
+                            description: 'Keyword extraction method. Fast uses NLP only (~50ms), others use LLM.',
                         },
                         {
-                            displayName: 'Country',
-                            name: 'country',
-                            type: 'string',
-                            default: '',
+                            displayName: 'Fill Priority',
+                            name: 'fill_priority',
+                            type: 'options',
+                            options: [
+                                { name: 'Speed', value: 'speed' },
+                                { name: 'Coverage', value: 'coverage' },
+                            ],
+                            default: 'coverage',
+                            description: 'URL resolution fallback strategy',
                         },
                         {
-                            displayName: 'Language',
-                            name: 'language',
-                            type: 'string',
-                            default: '',
+                            displayName: 'Min Intent',
+                            name: 'min_intent',
+                            type: 'options',
+                            options: [
+                                { name: 'Any', value: 'any' },
+                                { name: 'Low', value: 'low' },
+                                { name: 'Medium', value: 'medium' },
+                                { name: 'High', value: 'high' },
+                            ],
+                            default: 'low',
+                            description: 'Minimum purchase intent level for affiliate resolution',
                         },
                         {
-                            displayName: 'Website',
-                            name: 'website',
-                            type: 'string',
-                            default: '',
+                            displayName: 'Skip Message Analysis',
+                            name: 'skip_message_analysis',
+                            type: 'boolean',
+                            default: false,
+                            description: 'Skip NLP/LLM extraction and use message directly as search query. Overrides message_analysis, min_intent, and fill_priority.',
                         },
                         {
                             displayName: 'Extra Fields (JSON)',
@@ -297,7 +280,7 @@ class ChatAds {
                                 alwaysOpenEditWindow: true,
                             },
                             default: '{}',
-                            description: 'Raw JSON object merged into the payload as-is',
+                            description: 'JSON object containing additional fields to merge into the payload',
                         },
                     ],
                 },
@@ -364,38 +347,45 @@ class ChatAds {
                 if (jsonParameters) {
                     const bodyJson = this.getNodeParameter('bodyJson', itemIndex);
                     const parsedBody = parseJsonObject(this, bodyJson, 'Body JSON', itemIndex);
-                    const sanitizedBody = sanitizeRecord(this, parsedBody, 'Body JSON', itemIndex);
-                    const message = ensureMessage(this, parsedBody.message, itemIndex);
-                    sanitizedBody.message = message;
-                    assertAllowedFields(this, 'Body JSON', sanitizedBody, ALLOWED_PAYLOAD_FIELDS, itemIndex);
-                    body = sanitizedBody;
+                    body = buildPayloadFromObject(this, parsedBody, 'Body JSON', itemIndex);
                 }
                 else {
                     const rawMessage = this.getNodeParameter('message', itemIndex);
                     const message = ensureMessage(this, rawMessage, itemIndex);
                     const additionalFields = this.getNodeParameter('additionalFields', itemIndex, {});
-                    body = { message };
+                    const constructed = { message };
                     for (const [field, value] of Object.entries(additionalFields)) {
                         if (value === undefined || value === null || value === '') {
                             continue;
                         }
                         if (field === 'extraFieldsJson') {
                             const parsedExtras = parseJsonObject(this, value, 'Extra fields JSON', itemIndex);
-                            const sanitizedExtras = sanitizeRecord(this, parsedExtras, 'Extra fields JSON', itemIndex);
-                            assertAllowedFields(this, 'Extra fields JSON', sanitizedExtras, ALLOWED_PAYLOAD_FIELDS, itemIndex);
-                            for (const [extraKey, extraValue] of Object.entries(sanitizedExtras)) {
+                            assertNoReservedConflicts(this, 'Extra fields JSON', parsedExtras, itemIndex);
+                            for (const [extraKey, extraValue] of Object.entries(parsedExtras)) {
+                                if (extraValue === undefined || extraValue === null) {
+                                    continue;
+                                }
                                 if (extraKey === 'message') {
                                     continue;
                                 }
-                                body[extraKey] = extraValue;
+                                constructed[extraKey] = extraValue;
                             }
                             continue;
                         }
-                        if (typeof value !== 'string') {
-                            throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Field "${field}" must be provided as a string`, { itemIndex });
+                        const normalizedKey = normalizeOptionalField(field);
+                        if (!normalizedKey) {
+                            throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Field "${field}" is not supported`, { itemIndex });
+                        }
+                        if (normalizedKey === 'skip_message_analysis') {
+                            if (typeof value !== 'boolean') {
+                                throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Field "${field}" must be provided as a boolean`, { itemIndex });
+                            }
+                            constructed[normalizedKey] = value;
+                            continue;
                         }
-                        body[field] = value;
+                        constructed[normalizedKey] = coerceToString(this, 'Additional fields', field, value, itemIndex);
                     }
+                    body = buildPayloadFromObject(this, constructed, 'Additional fields', itemIndex);
                 }
                 const response = await this.helpers.httpRequestWithAuthentication.call(this, 'chatAdsApi', {
                     method: 'POST',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-nodes-chatads",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "n8n wrapper around the ChatAds FastAPI backend (affiliate/chatads_backend.py)",
   "license": "MIT",
   "main": "dist/index.js",