@aiteza/n8n-nodes-aiteza 0.3.1 → 1.0.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',
                     },
                 ],
             },
@@ -188,7 +178,9 @@ class AitezaProgress {
             const callbackTokenOverride = options.callbackTokenOverride || '';
             const timeout = options.timeout ?? 5000;
             const failOnError = options.failOnError ?? false;
-            const callbackUrl = (callbackUrlOverride || readTriggerBodyField(this, i, 'callbackUrl') || '').replace(/\/+$/, '');
+            const callbackUrl = (callbackUrlOverride ||
+                readTriggerBodyField(this, i, 'callbackUrl') ||
+                '').replace(/\/+$/, '');
             const executionId = executionIdOverride || readTriggerBodyField(this, i, 'executionId') || '';
             const callbackToken = callbackTokenOverride || readTriggerBodyField(this, i, 'callbackToken') || '';
             // Build payload
@@ -207,7 +199,10 @@ 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 +221,13 @@ 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 +253,12 @@ 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',
                     },
                 ],
             },
@@ -178,7 +167,9 @@ class AitezaWorkflowResult {
             const callbackTokenOverride = options.callbackTokenOverride || '';
             const timeout = options.timeout ?? 10000;
             const failOnError = options.failOnError ?? true;
-            const callbackUrl = (callbackUrlOverride || readTriggerBodyField(this, i, 'callbackUrl') || '').replace(/\/+$/, '');
+            const callbackUrl = (callbackUrlOverride ||
+                readTriggerBodyField(this, i, 'callbackUrl') ||
+                '').replace(/\/+$/, '');
             const executionId = executionIdOverride || readTriggerBodyField(this, i, 'executionId') || '';
             const callbackToken = callbackTokenOverride || readTriggerBodyField(this, i, 'callbackToken') || '';
             // Build result payload
@@ -193,7 +184,10 @@ 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 +210,13 @@ 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 +242,12 @@ 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,17 +5,8 @@ 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<{
-    body: any;
-    headers: Record<string, string>;
-}>;
 export declare function loadDatarooms(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
 export declare function loadDataroomsOptional(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
 export declare function loadModels(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;