@aiteza/n8n-nodes-aiteza 0.3.0 → 0.4.0

package/dist/nodes/Aiteza/AitezaProgress.node.js

@@ -2,9 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AitezaProgress = void 0;
 const n8n_workflow_1 = require("n8n-workflow");
-// ---------------------------------------------------------------------------
-// Helpers for reading the AITEZA Trigger's webhook body
-// ---------------------------------------------------------------------------
 function isAitezaTriggerType(type) {
     return typeof type === 'string' && /(^|\.)aitezaTrigger$/i.test(type);
 }
@@ -17,11 +14,6 @@ function findAitezaTriggerParentName(ef) {
         return undefined;
     }
 }
-/**
- * Look up a value first on the current input item, then on the original
- * AITEZA Trigger output (so intermediate Set/IF/SplitOut nodes that strip
- * fields don't break callbacks).
- */
 function readFromTrigger(ef, itemIndex, picker) {
     try {
         const items = ef.getInputData();
@@ -65,9 +57,6 @@ function readTriggerBodyField(ef, itemIndex, field) {
         return undefined;
     });
 }
-// ---------------------------------------------------------------------------
-// Node
-// ---------------------------------------------------------------------------
 class AitezaProgress {
     description = {
         displayName: 'AITEZA Progress',
@@ -76,10 +65,7 @@ class AitezaProgress {
         group: ['transform'],
         version: 1,
         subtitle: '={{$parameter["step"]}}',
-        description: 'Reports workflow progress back to the AITEZA backend that triggered ' +
-            'this workflow. Reads callbackUrl / executionId / callbackToken from ' +
-            'the upstream AITEZA Trigger webhook body and POSTs to ' +
-            '{callbackUrl}/api/internal/workflow/{executionId}/progress.',
+        description: 'Reports workflow progress back to Aiteza while the workflow is running. Reads the callback details from the upstream Aiteza Trigger node automatically.',
         defaults: { name: 'AITEZA Progress' },
         inputs: ['main'],
         outputs: ['main'],
@@ -91,8 +77,8 @@ class AitezaProgress {
                 type: 'string',
                 default: '',
                 required: true,
-                placeholder: 'Fetching files',
-                description: 'Short, human-readable label for the current step',
+                placeholder: 'e.g. Fetching files',
+                description: 'Short label describing the current step shown to the user',
             },
             {
                 displayName: 'Step Index',
@@ -100,7 +86,7 @@ class AitezaProgress {
                 type: 'number',
                 default: 1,
                 typeOptions: { minValue: 0 },
-                description: '1-based index of the current step',
+                description: 'Position of the current step (1-based)',
             },
             {
                 displayName: 'Total Steps',
@@ -116,7 +102,8 @@ class AitezaProgress {
                 type: 'string',
                 default: '',
                 typeOptions: { rows: 2 },
-                description: 'Optional longer description of what is happening right now',
+                placeholder: 'e.g. Processing 5 of 20 documents',
+                description: 'Optional longer description of what is currently happening',
             },
             {
                 displayName: 'Additional Fields (JSON)',
@@ -124,7 +111,7 @@ class AitezaProgress {
                 type: 'json',
                 default: '',
                 placeholder: '{ "percent": 42 }',
-                description: 'Optional JSON object that will be merged into the progress payload (e.g. percent, items processed, etc.)',
+                description: 'Optional JSON object merged into the progress payload (e.g. percent complete, items processed)',
             },
             {
                 displayName: 'Options',
@@ -133,27 +120,36 @@ class AitezaProgress {
                 placeholder: 'Add Option',
                 default: {},
                 options: [
+                    {
+                        displayName: 'Callback Token Override',
+                        name: 'callbackTokenOverride',
+                        type: 'string',
+                        typeOptions: { password: true },
+                        default: '',
+                        description: 'Override the callback token read from the Aiteza Trigger',
+                    },
                     {
                         displayName: 'Callback URL Override',
                         name: 'callbackUrlOverride',
                         type: 'string',
                         default: '',
-                        description: 'Override the callback URL from the AITEZA Trigger. Without trailing slash.',
+                        placeholder: 'e.g. https://aiteza.example.com',
+                        description: 'Override the callback URL read from the Aiteza Trigger (without trailing slash)',
                     },
                     {
                         displayName: 'Execution ID Override',
                         name: 'executionIdOverride',
                         type: 'string',
                         default: '',
-                        description: 'Override the execution ID from the AITEZA Trigger',
+                        placeholder: 'e.g. exec-abc123',
+                        description: 'Override the execution ID read from the Aiteza Trigger',
                     },
                     {
-                        displayName: 'Callback Token Override',
-                        name: 'callbackTokenOverride',
-                        type: 'string',
-                        typeOptions: { password: true },
-                        default: '',
-                        description: 'Override the callback token from the AITEZA Trigger',
+                        displayName: 'Fail Workflow on Callback Failure',
+                        name: 'failOnError',
+                        type: 'boolean',
+                        default: false,
+                        description: 'Whether to stop the workflow if the progress callback cannot be delivered. Defaults to false so a failed report never blocks the main flow.',
                     },
                     {
                         displayName: 'Timeout (ms)',
@@ -161,13 +157,7 @@ class AitezaProgress {
                         type: 'number',
                         default: 5000,
                         typeOptions: { minValue: 100 },
-                    },
-                    {
-                        displayName: 'Fail Workflow on Error',
-                        name: 'failOnError',
-                        type: 'boolean',
-                        default: false,
-                        description: 'Whether to fail the workflow if the progress callback fails. Defaults to false so progress reports never break the main flow.',
+                        description: 'Maximum time in milliseconds to wait for the callback to complete',
                     },
                 ],
             },
@@ -207,7 +197,7 @@ class AitezaProgress {
                     }
                     catch (err) {
                         if (failOnError) {
-                            throw new n8n_workflow_1.NodeOperationError(this.getNode(), `"Additional Fields" is not valid JSON: ${err.message}`, { itemIndex: i });
+                            throw new n8n_workflow_1.NodeOperationError(this.getNode(), `The 'Additional Fields' value is not valid JSON: ${err.message}`, { itemIndex: i, description: 'Please provide a valid JSON object in the \'Additional Fields\' parameter, e.g. { "percent": 42 }.' });
                         }
                     }
                 }
@@ -226,10 +216,10 @@ class AitezaProgress {
             if (!callbackUrl || !executionId) {
                 reportMeta.skipped = true;
                 reportMeta.reason = !callbackUrl
-                    ? 'No callbackUrl on AITEZA Trigger body'
-                    : 'No executionId on AITEZA Trigger body';
+                    ? 'No callbackUrl on Aiteza Trigger body'
+                    : 'No executionId on Aiteza Trigger body';
                 if (failOnError) {
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Cannot send progress: ${reportMeta.reason}`, { itemIndex: i });
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Cannot send progress report: ${reportMeta.reason}`, { itemIndex: i, description: 'Make sure this node is downstream of an Aiteza Trigger node that provides \'callbackUrl\' and \'executionId\' in its body.' });
                 }
                 returnData.push({
                     json: { ...items[i].json, _progressReport: reportMeta },
@@ -255,9 +245,9 @@ class AitezaProgress {
             catch (error) {
                 reportMeta.sent = false;
                 reportMeta.error =
-                    error?.message ?? error?.response?.statusText ?? 'Unknown error';
+                    error?.message ?? error?.response?.statusText ?? 'The callback could not be delivered';
                 if (failOnError) {
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Progress callback failed: ${reportMeta.error}`, { itemIndex: i });
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Progress callback could not be delivered: ${reportMeta.error}`, { itemIndex: i, description: 'Check that the \'callbackUrl\' is reachable and the callback token is valid.' });
                 }
             }
             returnData.push({

package/dist/nodes/Aiteza/AitezaTrigger.node.js

@@ -8,16 +8,10 @@ class AitezaTrigger {
         icon: 'file:aiteza.svg',
         group: ['trigger'],
         version: 1,
-        description: 'Starts the workflow when an AITEZA event is received via webhook. ' +
-            'Forwards the calling user\'s bearer token (from body.user.bearerToken) to downstream AITEZA nodes ' +
-            'so they act on behalf of the triggering user. Falls back to the request\'s Authorization header if no user token is present.',
+        description: 'Starts the workflow when an Aiteza event is received via webhook. Forwards the calling user\'s token to downstream Aiteza nodes so they act on behalf of the triggering user.',
         defaults: { name: 'AITEZA Trigger' },
         inputs: [],
         outputs: ['main'],
-        // No credentials required – the trigger just receives webhooks.
-        // Downstream AITEZA nodes still need a base URL (taken from this trigger
-        // or from configured credentials) and will use the token from this
-        // trigger for actual authentication.
         credentials: [],
         webhooks: [
             {
@@ -35,7 +29,7 @@ class AitezaTrigger {
                 name: 'path',
                 type: 'string',
                 default: 'aiteza',
-                placeholder: 'aiteza',
+                placeholder: 'e.g. aiteza',
                 required: true,
                 description: 'The webhook path to listen on. The full URL will be /webhook/{path}.',
             },
@@ -48,8 +42,7 @@ class AitezaTrigger {
                     {
                         name: 'Immediately',
                         value: 'onReceived',
-                        description: 'Respond immediately with 200 OK as soon as the webhook is received. ' +
-                            'Use the "AITEZA Workflow Result" node at the end of your workflow to send results back.',
+                        description: 'Respond immediately with 200 OK as soon as the webhook is received. Use the Aiteza Workflow Result node at the end of your workflow to send results back.',
                     },
                     {
                         name: 'When Last Node Finishes',
@@ -58,16 +51,15 @@ class AitezaTrigger {
                     },
                 ],
                 default: 'onReceived',
-                description: 'When and how to respond to the webhook. Use "Immediately" together with the ' +
-                    '"AITEZA Workflow Result" node to send results asynchronously.',
+                description: 'When and how to respond to the webhook. Use "Immediately" together with the Aiteza Workflow Result node to send results asynchronously.',
             },
             {
                 displayName: 'AITEZA Base URL',
                 name: 'baseUrl',
                 type: 'string',
                 default: '',
-                placeholder: 'https://aiteza.example.com',
-                description: 'Optional. If set, this URL is forwarded to downstream AITEZA nodes (as _baseUrl) so they don\'t need to repeat it. Without trailing slash.',
+                placeholder: 'e.g. https://aiteza.example.com',
+                description: 'Optional. If set, this URL is forwarded to downstream Aiteza nodes as \'_baseUrl\' so they don\'t need to repeat it. Without trailing slash.',
             },
         ],
     };
@@ -75,16 +67,10 @@ class AitezaTrigger {
         const body = this.getBodyData();
         const headers = this.getHeaderData();
         const query = this.getQueryData();
-        // AITEZA places the calling user's bearer token inside the body (body.user.bearerToken)
-        // so that downstream nodes can act on behalf of the user. The request's own
-        // Authorization header is typically the service-account token used by AITEZA to
-        // call the webhook itself – not what we want for delegated calls.
         const user = body?.user ?? {};
         const userBearer = user.bearerToken ?? '';
         const authHeader = headers.authorization || headers.Authorization || '';
         const headerToken = authHeader.replace(/^Bearer\s+/i, '');
-        // Prefer the user-context token. Fall back to the header token (e.g. when the
-        // webhook is called by something other than AITEZA).
         const authToken = userBearer || headerToken;
         const baseUrl = this.getNodeParameter('baseUrl', '').replace(/\/+$/, '');
         const outputData = {
@@ -94,8 +80,6 @@ class AitezaTrigger {
         };
         if (authToken)
             outputData._authToken = authToken;
-        // Expose the service-account token separately in case a workflow explicitly
-        // needs to call AITEZA with elevated/service privileges.
         if (headerToken && headerToken !== authToken)
             outputData._serviceAuthToken = headerToken;
         if (baseUrl)

package/dist/nodes/Aiteza/AitezaWorkflowResult.node.js

@@ -2,9 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AitezaWorkflowResult = void 0;
 const n8n_workflow_1 = require("n8n-workflow");
-// ---------------------------------------------------------------------------
-// Helpers for reading the AITEZA Trigger's webhook body
-// ---------------------------------------------------------------------------
 function isAitezaTriggerType(type) {
     return typeof type === 'string' && /(^|\.)aitezaTrigger$/i.test(type);
 }
@@ -17,11 +14,6 @@ function findAitezaTriggerParentName(ef) {
         return undefined;
     }
 }
-/**
- * Look up a value first on the current input item, then on the original
- * AITEZA Trigger output (so intermediate Set/IF/SplitOut nodes that strip
- * fields don't break callbacks).
- */
 function readFromTrigger(ef, itemIndex, picker) {
     try {
         const items = ef.getInputData();
@@ -63,9 +55,6 @@ function readTriggerBodyField(ef, itemIndex, field) {
         return undefined;
     });
 }
-// ---------------------------------------------------------------------------
-// Node
-// ---------------------------------------------------------------------------
 class AitezaWorkflowResult {
     description = {
         displayName: 'AITEZA Workflow Result',
@@ -74,12 +63,7 @@ class AitezaWorkflowResult {
         group: ['output'],
         version: 1,
         subtitle: 'Send result to AITEZA',
-        description: 'Sends the final workflow result back to the AITEZA backend. ' +
-            'Reads callbackUrl / executionId / callbackToken from the upstream ' +
-            'AITEZA Trigger webhook body and POSTs to ' +
-            '{callbackUrl}/api/internal/workflow/{executionId}/result. ' +
-            'Use this instead of "Respond to Webhook" which is not compatible ' +
-            'with custom trigger nodes.',
+        description: 'Sends the final workflow result back to Aiteza. Use this node instead of "Respond to Webhook" when your workflow is triggered by an Aiteza Trigger node.',
         defaults: { name: 'AITEZA Workflow Result' },
         inputs: ['main'],
         outputs: ['main'],
@@ -91,7 +75,7 @@ class AitezaWorkflowResult {
                 type: 'json',
                 default: '',
                 placeholder: '={{ $json }}',
-                description: 'The result payload to send back to AITEZA. Can be a JSON object or an expression that resolves to one. If empty, the entire input item JSON is sent.',
+                description: 'The result payload to send back to Aiteza. Can be a JSON object or an expression. If left empty, the entire input item is sent.',
             },
             {
                 displayName: 'Status',
@@ -101,21 +85,23 @@ class AitezaWorkflowResult {
                     {
                         name: 'Success',
                         value: 'success',
+                        description: 'The workflow completed successfully',
                     },
                     {
                         name: 'Error',
                         value: 'error',
+                        description: 'The workflow encountered an issue',
                     },
                 ],
                 default: 'success',
-                description: 'The result status to report back to AITEZA',
+                description: 'The result status to report back to Aiteza',
             },
             {
                 displayName: 'Message',
                 name: 'message',
                 type: 'string',
                 default: '',
-                placeholder: 'Workflow completed successfully',
+                placeholder: 'e.g. Workflow completed successfully',
                 description: 'Optional human-readable message to include with the result',
             },
             {
@@ -125,27 +111,36 @@ class AitezaWorkflowResult {
                 placeholder: 'Add Option',
                 default: {},
                 options: [
+                    {
+                        displayName: 'Callback Token Override',
+                        name: 'callbackTokenOverride',
+                        type: 'string',
+                        typeOptions: { password: true },
+                        default: '',
+                        description: 'Override the callback token read from the Aiteza Trigger',
+                    },
                     {
                         displayName: 'Callback URL Override',
                         name: 'callbackUrlOverride',
                         type: 'string',
                         default: '',
-                        description: 'Override the callback URL from the AITEZA Trigger. Without trailing slash.',
+                        placeholder: 'e.g. https://aiteza.example.com',
+                        description: 'Override the callback URL read from the Aiteza Trigger (without trailing slash)',
                     },
                     {
                         displayName: 'Execution ID Override',
                         name: 'executionIdOverride',
                         type: 'string',
                         default: '',
-                        description: 'Override the execution ID from the AITEZA Trigger',
+                        placeholder: 'e.g. exec-abc123',
+                        description: 'Override the execution ID read from the Aiteza Trigger',
                     },
                     {
-                        displayName: 'Callback Token Override',
-                        name: 'callbackTokenOverride',
-                        type: 'string',
-                        typeOptions: { password: true },
-                        default: '',
-                        description: 'Override the callback token from the AITEZA Trigger',
+                        displayName: 'Fail Workflow on Callback Failure',
+                        name: 'failOnError',
+                        type: 'boolean',
+                        default: true,
+                        description: 'Whether to stop the workflow if the result callback cannot be delivered. Defaults to true since the result is typically critical.',
                     },
                     {
                         displayName: 'Timeout (ms)',
@@ -153,13 +148,7 @@ class AitezaWorkflowResult {
                         type: 'number',
                         default: 10000,
                         typeOptions: { minValue: 100 },
-                    },
-                    {
-                        displayName: 'Fail Workflow on Error',
-                        name: 'failOnError',
-                        type: 'boolean',
-                        default: true,
-                        description: 'Whether to fail the workflow if the result callback fails. Defaults to true since the result is typically critical.',
+                        description: 'Maximum time in milliseconds to wait for the callback to complete',
                     },
                 ],
             },
@@ -193,7 +182,7 @@ class AitezaWorkflowResult {
                 }
                 catch (err) {
                     if (failOnError) {
-                        throw new n8n_workflow_1.NodeOperationError(this.getNode(), `"Result Data" is not valid JSON: ${err.message}`, { itemIndex: i });
+                        throw new n8n_workflow_1.NodeOperationError(this.getNode(), `The 'Result Data' value is not valid JSON: ${err.message}`, { itemIndex: i, description: 'Please provide a valid JSON object in the \'Result Data\' field, or use an expression like ={{ $json }}.' });
                     }
                     resultPayload = { raw: resultDataRaw };
                 }
@@ -216,10 +205,10 @@ class AitezaWorkflowResult {
             if (!callbackUrl || !executionId) {
                 reportMeta.skipped = true;
                 reportMeta.reason = !callbackUrl
-                    ? 'No callbackUrl on AITEZA Trigger body'
-                    : 'No executionId on AITEZA Trigger body';
+                    ? 'No callbackUrl on Aiteza Trigger body'
+                    : 'No executionId on Aiteza Trigger body';
                 if (failOnError) {
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Cannot send workflow result: ${reportMeta.reason}`, { itemIndex: i });
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Cannot send workflow result: ${reportMeta.reason}`, { itemIndex: i, description: 'Make sure this node is downstream of an Aiteza Trigger node that provides \'callbackUrl\' and \'executionId\' in its body.' });
                 }
                 returnData.push({
                     json: { ...items[i].json, _workflowResult: reportMeta },
@@ -245,9 +234,9 @@ class AitezaWorkflowResult {
             catch (error) {
                 reportMeta.sent = false;
                 reportMeta.error =
-                    error?.message ?? error?.response?.statusText ?? 'Unknown error';
+                    error?.message ?? error?.response?.statusText ?? 'The callback could not be delivered';
                 if (failOnError) {
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Workflow result callback failed: ${reportMeta.error}`, { itemIndex: i });
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Workflow result could not be delivered: ${reportMeta.error}`, { itemIndex: i, description: 'Check that the \'callbackUrl\' is reachable and the callback token is valid.' });
                 }
             }
             returnData.push({

package/dist/nodes/Aiteza/GenericFunctions.d.ts

@@ -5,11 +5,6 @@ export interface AitezaAuthContext {
 }
 export declare function getUpstreamAuthToken(ef: IExecuteFunctions): string | undefined;
 export declare function getUpstreamBaseUrl(ef: IExecuteFunctions): string | undefined;
-/**
- * Returns true when the token is a JWT with an `exp` claim that is in the past
- * (with a small skew). Returns false when the token is not a parsable JWT or
- * has no `exp` (we assume valid in that case – the server is the source of truth).
- */
 export declare function isJwtExpired(token: string | undefined, skewSeconds?: number): boolean;
 export declare function aitezaApiRequest(this: IExecuteFunctions | ILoadOptionsFunctions, method: IHttpRequestMethods, endpoint: string, body?: IDataObject | IDataObject[], qs?: IDataObject, extraOpts?: Partial<IHttpRequestOptions>, authCtx?: AitezaAuthContext): Promise<any>;
 export declare function aitezaApiRequestFullResponse(this: IExecuteFunctions, method: IHttpRequestMethods, endpoint: string, body?: IDataObject, qs?: IDataObject, extraOpts?: Partial<IHttpRequestOptions>, authCtx?: AitezaAuthContext): Promise<{

package/dist/nodes/Aiteza/GenericFunctions.js

@@ -16,9 +16,6 @@ exports.loadStandaloneFiles = loadStandaloneFiles;
 exports.loadStandaloneImages = loadStandaloneImages;
 exports.validateRequiredField = validateRequiredField;
 const n8n_workflow_1 = require("n8n-workflow");
-// Match the AITEZA Trigger node by its type name. The full node-type string
-// includes the package namespace (e.g. "@aiteza/n8n-nodes-aiteza.aitezaTrigger"),
-// so we match on the suffix.
 function isAitezaTriggerType(type) {
     return typeof type === 'string' && /(^|\.)aitezaTrigger$/i.test(type);
 }
@@ -47,13 +44,10 @@ function readFromTriggerItems(ef, picker) {
         }
     }
     catch {
-        // proxy/items unavailable – ignore
     }
     return undefined;
 }
 function getUpstreamAuthToken(ef) {
-    // 1. Prefer the token on the immediate input items (cheap and matches the
-    //    documented contract of forwarding `_authToken`).
     try {
         const items = ef.getInputData();
         for (const item of items) {
@@ -63,11 +57,7 @@ function getUpstreamAuthToken(ef) {
         }
     }
     catch {
-        // getInputData may not be available in every context
     }
-    // 2. Fall back to the AITEZA Trigger node's original output. This makes the
-    //    node resilient to intermediate transformations (Set/Edit Fields, Split
-    //    Out, IF, etc.) that strip the `_authToken` field from items.
     return readFromTriggerItems(ef, (json) => json?._authToken);
 }
 function getUpstreamBaseUrl(ef) {
@@ -80,14 +70,11 @@ function getUpstreamBaseUrl(ef) {
         }
     }
     catch {
-        // ignore
     }
     const fromTrigger = readFromTriggerItems(ef, (json) => json?._baseUrl);
     return fromTrigger ? fromTrigger.replace(/\/+$/, '') : undefined;
 }
-// ---------------------------------------------------------------------------
 // JWT helpers
-// ---------------------------------------------------------------------------
 function decodeJwtPayload(token) {
     try {
         const payload = token.split('.')[1];
@@ -95,9 +82,6 @@ function decodeJwtPayload(token) {
             return undefined;
         const normalized = payload.replace(/-/g, '+').replace(/_/g, '/');
         const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
-        // atob is available in Node 16+ and the browser; decodes base64 to a
-        // binary string. JWT payloads are UTF-8 JSON; for the `exp` claim a
-        // binary-string decode is sufficient.
         const decoded = globalThis.atob
             ? globalThis.atob(padded)
             : '';
@@ -109,11 +93,6 @@ function decodeJwtPayload(token) {
         return undefined;
     }
 }
-/**
- * Returns true when the token is a JWT with an `exp` claim that is in the past
- * (with a small skew). Returns false when the token is not a parsable JWT or
- * has no `exp` (we assume valid in that case – the server is the source of truth).
- */
 function isJwtExpired(token, skewSeconds = 30) {
     if (!token)
         return true;
@@ -123,9 +102,7 @@ function isJwtExpired(token, skewSeconds = 30) {
     const nowSeconds = Math.floor(Date.now() / 1000);
     return payload.exp <= nowSeconds + skewSeconds;
 }
-// ---------------------------------------------------------------------------
 // Internal helpers
-// ---------------------------------------------------------------------------
 async function resolveBaseUrl(ctx, authCtx) {
     if (authCtx?.baseUrl)
         return authCtx.baseUrl;
@@ -142,20 +119,16 @@ async function executeRequest(ctx, options, authCtx) {
     }
     return ctx.helpers.httpRequestWithAuthentication.call(ctx, 'aitezaOAuth2Api', options);
 }
-/** Convert API response items to n8n dropdown options. */
 function toOptions(items, nameField = 'name') {
     return items.map((item) => ({
         name: item[nameField] ?? item.id,
         value: item.id,
     }));
 }
-/** Extract array from API response (handles both raw arrays and paginated `{ content: [...] }`). */
 function extractItems(data) {
     return Array.isArray(data) ? data : data?.content ?? [];
 }
-// ---------------------------------------------------------------------------
 // Generic authenticated request helper
-// ---------------------------------------------------------------------------
 async function aitezaApiRequest(method, endpoint, body = {}, qs = {}, extraOpts = {}, authCtx) {
     const baseUrl = await resolveBaseUrl(this, authCtx);
     const options = {
@@ -164,7 +137,6 @@ async function aitezaApiRequest(method, endpoint, body = {}, qs = {}, extraOpts
         json: true,
         ...extraOpts,
     };
-    // Only set qs when there are actual values – empty qs can strip URL params.
     if (Object.keys(qs).length > 0) {
         options.qs = qs;
     }
@@ -180,18 +152,16 @@ async function aitezaApiRequest(method, endpoint, body = {}, qs = {}, extraOpts
     catch (error) {
         const statusCode = error?.statusCode ?? error?.httpCode ?? error?.response?.status;
         const messages = {
-            401: 'OAuth2 token expired or invalid – check your AITEZA credentials',
-            403: 'Insufficient permissions for this resource',
-            404: 'Resource not found',
+            401: 'The OAuth2 token is expired or invalid – check your Aiteza credentials',
+            403: 'Your account does not have permission to access this resource',
+            404: 'The requested resource could not be found',
         };
         throw new n8n_workflow_1.NodeApiError(this.getNode(), error, {
-            message: messages[statusCode] ?? error.message ?? 'Unknown error',
+            message: messages[statusCode] ?? error.message ?? 'The request could not be completed',
         });
     }
 }
-// ---------------------------------------------------------------------------
 // Full-response variant (gives access to response headers, e.g. X-Chat-Id)
-// ---------------------------------------------------------------------------
 async function aitezaApiRequestFullResponse(method, endpoint, body = {}, qs = {}, extraOpts = {}, authCtx) {
     const baseUrl = await resolveBaseUrl(this, authCtx);
     const options = {
@@ -212,9 +182,7 @@ async function aitezaApiRequestFullResponse(method, endpoint, body = {}, qs = {}
         throw new n8n_workflow_1.NodeApiError(this.getNode(), error);
     }
 }
-// ---------------------------------------------------------------------------
 // loadOptions helpers
-// ---------------------------------------------------------------------------
 async function loadDatarooms() {
     try {
         const data = await aitezaApiRequest.call(this, 'GET', '/api/dataroom/search?q=&sortBy=recentlyUsed');
@@ -271,11 +239,11 @@ async function loadStandaloneImages() {
     const data = await aitezaApiRequest.call(this, 'GET', '/api/images', {}, { size: 100 });
     return toOptions(extractItems(data));
 }
-// ---------------------------------------------------------------------------
 // Validation helper
-// ---------------------------------------------------------------------------
 function validateRequiredField(ef, value, fieldName) {
     if (value === undefined || value === null || value === '') {
-        throw new n8n_workflow_1.NodeOperationError(ef.getNode(), `"${fieldName}" is required but was not provided`);
+        throw new n8n_workflow_1.NodeOperationError(ef.getNode(), `The '${fieldName}' field is required but was not provided.`, {
+            description: `Please fill in the '${fieldName}' field before running this node.`,
+        });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiteza/n8n-nodes-aiteza",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "n8n Community Node for the AITEZA REST API (Datarooms, Files, Chat, Search, Workflows)",
   "keywords": [
     "n8n-community-node-package",