n8n-nodes-formfex 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Formfex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# n8n-nodes-formfex
+
+[n8n](https://n8n.io/) community node for [Formfex](https://formfex.com) — AI-powered form builder.
+
+Create forms, collect responses, trigger automations, and generate forms with AI directly from your n8n workflows.
+
+![License](https://img.shields.io/npm/l/n8n-nodes-formfex)
+![n8n](https://img.shields.io/badge/n8n-community--node-orange)
+
+## Installation
+
+### Community Nodes (Recommended)
+
+1. Go to **Settings > Community Nodes** in your n8n instance
+2. Click **Install a community node**
+3. Enter `n8n-nodes-formfex`
+4. Click **Install**
+
+### Manual Installation
+
+```bash
+cd ~/.n8n/nodes
+npm install n8n-nodes-formfex
+```
+
+Restart n8n after installation.
+
+## Credentials
+
+You need a Formfex API key to use this node.
+
+1. Log in to [Formfex](https://formfex.com)
+2. Go to **Account > Integrations > API Keys**
+3. Click **Create** and select the permissions you need
+4. Copy the key (format: `fxk_live_<keyId>.<secret>`)
+5. In n8n, add a new **Formfex API** credential and paste the key
+
+> API keys require a **Starter plan** or higher.
+
+## Nodes
+
+### Formfex
+
+Regular node with three resources:
+
+#### Form Operations
+
+| Operation | Description |
+|-----------|-------------|
+| **Create** | Create a new form |
+| **Get** | Get a form by ID |
+| **Get Many** | List forms (with pagination and search) |
+| **Update** | Update a form |
+| **Delete** | Delete a form |
+| **Publish** | Publish a form |
+| **Unpublish** | Unpublish a form |
+
+#### Response Operations
+
+| Operation | Description |
+|-----------|-------------|
+| **Get** | Get a single response by ID |
+| **Get Many** | List responses (with date filters and pagination) |
+
+#### AI Operations
+
+| Operation | Description |
+|-----------|-------------|
+| **Generate Form** | Generate a form from a text prompt using AI (polls until complete) |
+| **Get Job Status** | Check the status of an AI generation job |
+| **Smart Analytics** | Dispatch an async smart analytics report (results sent to callback URL) |
+| **Analytics Chat** | Ask natural language questions about form analytics data |
+
+### Formfex Trigger
+
+Polling trigger that watches for new form responses.
+
+| Parameter | Description |
+|-----------|-------------|
+| **Form ID** | The UUID of the form to watch |
+
+The trigger polls periodically and returns any new responses since the last check. Configure the polling interval in your n8n workflow settings.
+
+## AI Agent Tool Mode
+
+The Formfex node has `usableAsTool: true`, which means it can be used as a tool inside **n8n AI Agent** nodes. This allows AI agents to autonomously create forms, fetch responses, and generate analytics.
+
+## Supported Languages
+
+Formfex supports 6 languages for form generation and content:
+
+- English (`en`)
+- Turkish (`tr`)
+- Spanish (`es`)
+- Italian (`it`)
+- German (`de`)
+- Dutch (`nl`)
+
+## API Scopes
+
+When creating an API key, select the scopes your workflow needs:
+
+| Scope | Description |
+|-------|-------------|
+| `FORMS_READ` | List and view forms |
+| `FORMS_WRITE` | Create, edit, delete forms |
+| `RESPONSES_READ` | List and view form submissions |
+| `WEBHOOKS_READ` | List and view webhooks |
+| `WEBHOOKS_WRITE` | Create, edit, delete webhooks |
+| `AI_GENERATE` | Generate forms with AI |
+| `ANALYTICS_READ` | Access smart analytics and analytics chat |
+
+## Resources
+
+- [Formfex Website](https://formfex.com)
+- [Formfex API Documentation](https://docs.formfex.com/api)
+- [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/)
+
+## License
+
+[MIT](LICENSE)

package/dist/credentials/FormfexApi.credentials.d.ts

@@ -0,0 +1,21 @@
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class FormfexApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: {
+        type: "generic";
+        properties: {
+            headers: {
+                Authorization: string;
+            };
+        };
+    };
+    test: {
+        request: {
+            baseURL: string;
+            url: string;
+        };
+    };
+}

package/dist/credentials/FormfexApi.credentials.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormfexApi = void 0;
+const FORMFEX_API_BASE_URL = 'https://api.formfex.com';
+class FormfexApi {
+    constructor() {
+        this.name = 'formfexApi';
+        this.displayName = 'Formfex API';
+        this.documentationUrl = 'https://docs.formfex.com/api';
+        this.properties = [
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                placeholder: 'fxk_live_...',
+                description: 'Your Formfex API key (format: fxk_live_{keyId}.{secret}). Get it from Account > Integrations > API Keys.',
+            },
+            // No baseUrl field — hardcoded to prevent SSRF on shared n8n instances
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.apiKey}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: FORMFEX_API_BASE_URL,
+                url: '/api/v1/public/me',
+            },
+        };
+    }
+}
+exports.FormfexApi = FormfexApi;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { FormfexApi } from './credentials/FormfexApi.credentials';
+export { Formfex } from './nodes/Formfex/Formfex.node';
+export { FormfexTrigger } from './nodes/Formfex/FormfexTrigger.node';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormfexTrigger = exports.Formfex = exports.FormfexApi = void 0;
+var FormfexApi_credentials_1 = require("./credentials/FormfexApi.credentials");
+Object.defineProperty(exports, "FormfexApi", { enumerable: true, get: function () { return FormfexApi_credentials_1.FormfexApi; } });
+var Formfex_node_1 = require("./nodes/Formfex/Formfex.node");
+Object.defineProperty(exports, "Formfex", { enumerable: true, get: function () { return Formfex_node_1.Formfex; } });
+var FormfexTrigger_node_1 = require("./nodes/Formfex/FormfexTrigger.node");
+Object.defineProperty(exports, "FormfexTrigger", { enumerable: true, get: function () { return FormfexTrigger_node_1.FormfexTrigger; } });

package/dist/nodes/Formfex/Formfex.node.d.ts

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

package/dist/nodes/Formfex/Formfex.node.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Formfex = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const form_description_1 = require("./descriptions/form.description");
+const response_description_1 = require("./descriptions/response.description");
+const ai_description_1 = require("./descriptions/ai.description");
+const helpers_1 = require("./helpers");
+class Formfex {
+    constructor() {
+        this.description = {
+            displayName: 'Formfex',
+            name: 'formfex',
+            icon: 'file:Formfex.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
+            description: 'Interact with Formfex forms, responses, and AI features',
+            defaults: { name: 'Formfex' },
+            inputs: ['main'],
+            outputs: ['main'],
+            usableAsTool: true,
+            credentials: [{ name: 'formfexApi', required: true }],
+            requestDefaults: {
+                baseURL: 'https://api.formfex.com',
+                headers: { 'Content-Type': 'application/json' },
+            },
+            properties: [
+                {
+                    displayName: 'Resource',
+                    name: 'resource',
+                    type: 'options',
+                    noDataExpression: true,
+                    options: [
+                        { name: 'AI', value: 'ai' },
+                        { name: 'Form', value: 'form' },
+                        { name: 'Response', value: 'response' },
+                    ],
+                    default: 'form',
+                },
+                ...form_description_1.formOperations,
+                ...form_description_1.formFields,
+                ...response_description_1.responseOperations,
+                ...response_description_1.responseFields,
+                ...ai_description_1.aiOperations,
+                ...ai_description_1.aiFields,
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        const resource = this.getNodeParameter('resource', 0);
+        const operation = this.getNodeParameter('operation', 0);
+        for (let i = 0; i < items.length; i++) {
+            try {
+                let responseData;
+                if (resource === 'form') {
+                    responseData = await executeFormOperation.call(this, operation, i);
+                }
+                else if (resource === 'response') {
+                    responseData = await executeResponseOperation.call(this, operation, i);
+                }
+                else if (resource === 'ai') {
+                    responseData = await executeAiOperation.call(this, operation, i);
+                }
+                if (Array.isArray(responseData)) {
+                    returnData.push(...responseData.map((item) => ({ json: item })));
+                }
+                else if (responseData) {
+                    returnData.push({ json: responseData });
+                }
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({ json: { error: error.message }, pairedItem: { item: i } });
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return [returnData];
+    }
+}
+exports.Formfex = Formfex;
+async function executeFormOperation(operation, i) {
+    if (operation === 'create') {
+        const title = this.getNodeParameter('title', i);
+        const additionalFields = this.getNodeParameter('additionalFields', i, {});
+        const body = { title };
+        if (additionalFields.description)
+            body.description = additionalFields.description;
+        if (additionalFields.language)
+            body.language = additionalFields.language;
+        const result = await helpers_1.formfexApiRequest.call(this, 'POST', '/forms', body);
+        return result.data;
+    }
+    if (operation === 'get') {
+        const formId = this.getNodeParameter('formId', i);
+        (0, helpers_1.validateUuid)(this, formId, 'Form ID');
+        const result = await helpers_1.formfexApiRequest.call(this, 'GET', `/forms/${(0, helpers_1.safePath)(formId)}`);
+        return result.data;
+    }
+    if (operation === 'getMany') {
+        const returnAll = this.getNodeParameter('returnAll', i);
+        const filters = this.getNodeParameter('filters', i, {});
+        const limit = returnAll ? 100 : this.getNodeParameter('limit', i);
+        const query = { limit, page: 1 };
+        if (filters.search)
+            query.search = filters.search;
+        if (filters.since)
+            query.since = filters.since;
+        if (!returnAll) {
+            const result = await helpers_1.formfexApiRequest.call(this, 'GET', '/forms', undefined, query);
+            return result.data.forms ?? result.data;
+        }
+        // Paginate
+        const allItems = [];
+        let page = 1;
+        let hasMore = true;
+        while (hasMore && page <= helpers_1.MAX_PAGES) {
+            query.page = page;
+            const result = await helpers_1.formfexApiRequest.call(this, 'GET', '/forms', undefined, query);
+            const items = result.data.forms ?? result.data ?? [];
+            allItems.push(...items);
+            hasMore = result.data.hasMore ?? items.length === limit;
+            page++;
+        }
+        if (page > helpers_1.MAX_PAGES) {
+            allItems.push({ _warning: `Return All truncated at ${helpers_1.MAX_PAGES * limit} records. Use filters to narrow the dataset.` });
+        }
+        return allItems;
+    }
+    if (operation === 'update') {
+        const formId = this.getNodeParameter('formId', i);
+        (0, helpers_1.validateUuid)(this, formId, 'Form ID');
+        const updateFields = this.getNodeParameter('updateFields', i, {});
+        const result = await helpers_1.formfexApiRequest.call(this, 'PATCH', `/forms/${(0, helpers_1.safePath)(formId)}`, updateFields);
+        return result.data;
+    }
+    if (operation === 'delete') {
+        const formId = this.getNodeParameter('formId', i);
+        (0, helpers_1.validateUuid)(this, formId, 'Form ID');
+        const result = await helpers_1.formfexApiRequest.call(this, 'DELETE', `/forms/${(0, helpers_1.safePath)(formId)}`);
+        return result.data ?? { success: true };
+    }
+    if (operation === 'publish') {
+        const formId = this.getNodeParameter('formId', i);
+        (0, helpers_1.validateUuid)(this, formId, 'Form ID');
+        const publishFields = this.getNodeParameter('publishFields', i, {});
+        const body = {};
+        if (publishFields.visibility)
+            body.visibility = publishFields.visibility;
+        const result = await helpers_1.formfexApiRequest.call(this, 'POST', `/forms/${(0, helpers_1.safePath)(formId)}/publish`, body);
+        return result.data;
+    }
+    if (operation === 'unpublish') {
+        const formId = this.getNodeParameter('formId', i);
+        (0, helpers_1.validateUuid)(this, formId, 'Form ID');
+        const result = await helpers_1.formfexApiRequest.call(this, 'POST', `/forms/${(0, helpers_1.safePath)(formId)}/unpublish`);
+        return result.data;
+    }
+    throw new n8n_workflow_1.NodeApiError(this.getNode(), { message: `Unknown operation: ${operation}` });
+}
+async function executeResponseOperation(operation, i) {
+    const formId = this.getNodeParameter('formId', i);
+    (0, helpers_1.validateUuid)(this, formId, 'Form ID');
+    if (operation === 'get') {
+        const responseId = this.getNodeParameter('responseId', i);
+        (0, helpers_1.validateUuid)(this, responseId, 'Response ID');
+        const result = await helpers_1.formfexApiRequest.call(this, 'GET', `/forms/${(0, helpers_1.safePath)(formId)}/responses/${(0, helpers_1.safePath)(responseId)}`);
+        return result.data;
+    }
+    if (operation === 'getMany') {
+        const returnAll = this.getNodeParameter('returnAll', i);
+        const filters = this.getNodeParameter('filters', i, {});
+        const limit = returnAll ? 100 : this.getNodeParameter('limit', i);
+        const query = { limit, page: 1 };
+        if (filters.startDate)
+            query.startDate = filters.startDate;
+        if (filters.endDate)
+            query.endDate = filters.endDate;
+        if (filters.since)
+            query.since = filters.since;
+        if (filters.order)
+            query.order = filters.order;
+        if (!returnAll) {
+            const result = await helpers_1.formfexApiRequest.call(this, 'GET', `/forms/${(0, helpers_1.safePath)(formId)}/responses`, undefined, query);
+            return result.data.items ?? result.data;
+        }
+        // Paginate
+        const allItems = [];
+        let page = 1;
+        let hasMore = true;
+        while (hasMore && page <= helpers_1.MAX_PAGES) {
+            query.page = page;
+            const result = await helpers_1.formfexApiRequest.call(this, 'GET', `/forms/${(0, helpers_1.safePath)(formId)}/responses`, undefined, query);
+            const items = result.data.items ?? result.data ?? [];
+            allItems.push(...items);
+            hasMore = result.data.hasMore ?? items.length === limit;
+            page++;
+        }
+        if (page > helpers_1.MAX_PAGES) {
+            allItems.push({ _warning: `Return All truncated at ${helpers_1.MAX_PAGES * limit} records. Use date filters to narrow the dataset.` });
+        }
+        return allItems;
+    }
+    throw new n8n_workflow_1.NodeApiError(this.getNode(), { message: `Unknown operation: ${operation}` });
+}
+async function executeAiOperation(operation, i) {
+    if (operation === 'generateForm') {
+        const prompt = this.getNodeParameter('prompt', i);
+        const language = this.getNodeParameter('language', i, 'en');
+        // Dispatch the job
+        const dispatchResult = await helpers_1.formfexApiRequest.call(this, 'POST', '/ai/generate-form', { prompt, language });
+        const jobId = dispatchResult.data.jobId;
+        // Poll until done (max 20 attempts, 3s interval = 60s max)
+        const MAX_POLL_ATTEMPTS = 20;
+        const POLL_INTERVAL_MS = 3000;
+        for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
+            await sleep(POLL_INTERVAL_MS);
+            const jobResult = await helpers_1.formfexApiRequest.call(this, 'GET', `/ai/jobs/${(0, helpers_1.safePath)(jobId)}`);
+            const job = jobResult.data;
+            if (job.status === 'DONE') {
+                return job;
+            }
+            if (job.status === 'FAILED') {
+                throw new n8n_workflow_1.NodeApiError(this.getNode(), {
+                    message: 'AI form generation failed',
+                    description: job.error ?? 'Unknown error',
+                });
+            }
+            // PENDING or PROCESSING — keep polling
+        }
+        throw new n8n_workflow_1.NodeApiError(this.getNode(), {
+            message: 'AI form generation timed out',
+            description: `Job ${jobId} did not complete within ${MAX_POLL_ATTEMPTS * POLL_INTERVAL_MS / 1000} seconds`,
+        });
+    }
+    if (operation === 'getJobStatus') {
+        const jobId = this.getNodeParameter('jobId', i);
+        (0, helpers_1.validateUuid)(this, jobId, 'Job ID');
+        const result = await helpers_1.formfexApiRequest.call(this, 'GET', `/ai/jobs/${(0, helpers_1.safePath)(jobId)}`);
+        return result.data;
+    }
+    if (operation === 'smartAnalytics') {
+        const formId = this.getNodeParameter('formId', i);
+        (0, helpers_1.validateUuid)(this, formId, 'Form ID');
+        const callbackUrl = this.getNodeParameter('callbackUrl', i);
+        const result = await helpers_1.formfexApiRequest.call(this, 'POST', `/forms/${(0, helpers_1.safePath)(formId)}/smart-analytics`, { callbackUrl });
+        return result.data;
+    }
+    if (operation === 'analyticsChat') {
+        const formId = this.getNodeParameter('formId', i);
+        (0, helpers_1.validateUuid)(this, formId, 'Form ID');
+        const message = this.getNodeParameter('message', i);
+        const sessionId = this.getNodeParameter('sessionId', i, '');
+        const body = { message };
+        if (sessionId)
+            body.sessionId = sessionId;
+        const result = await helpers_1.formfexApiRequest.call(this, 'POST', `/forms/${(0, helpers_1.safePath)(formId)}/analytics-chat`, body);
+        return result.data;
+    }
+    throw new n8n_workflow_1.NodeApiError(this.getNode(), { message: `Unknown operation: ${operation}` });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/nodes/Formfex/FormfexTrigger.node.d.ts

@@ -0,0 +1,5 @@
+import type { IPollFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class FormfexTrigger implements INodeType {
+    description: INodeTypeDescription;
+    poll(this: IPollFunctions): Promise<INodeExecutionData[][] | null>;
+}

package/dist/nodes/Formfex/FormfexTrigger.node.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormfexTrigger = void 0;
+const helpers_1 = require("./helpers");
+class FormfexTrigger {
+    constructor() {
+        this.description = {
+            displayName: 'Formfex Trigger',
+            name: 'formfexTrigger',
+            icon: 'file:Formfex.svg',
+            group: ['trigger'],
+            version: 1,
+            subtitle: '=New Response on Form',
+            description: 'Triggers when a new form response is submitted',
+            defaults: { name: 'Formfex Trigger' },
+            inputs: [],
+            outputs: ['main'],
+            credentials: [{ name: 'formfexApi', required: true }],
+            polling: true,
+            properties: [
+                {
+                    displayName: 'Form ID',
+                    name: 'formId',
+                    type: 'string',
+                    required: true,
+                    default: '',
+                    description: 'The UUID of the form to watch for new responses',
+                },
+            ],
+        };
+    }
+    async poll() {
+        const formId = this.getNodeParameter('formId');
+        (0, helpers_1.validateUuid)(this, formId, 'Form ID');
+        const staticData = this.getWorkflowStaticData('node');
+        const lastTimeChecked = staticData.lastTimeChecked ?? new Date().toISOString();
+        const query = {
+            since: lastTimeChecked,
+            order: 'newest_first',
+            limit: 100,
+            page: 1,
+        };
+        const allItems = [];
+        let hasMore = true;
+        let page = 1;
+        const MAX_POLL_PAGES = 10; // Safety cap for polling
+        while (hasMore && page <= MAX_POLL_PAGES) {
+            query.page = page;
+            const result = await helpers_1.formfexApiRequest.call(this, 'GET', `/forms/${(0, helpers_1.safePath)(formId)}/responses`, undefined, query);
+            const items = result.data?.items ?? [];
+            allItems.push(...items);
+            hasMore = result.data?.hasMore ?? items.length === 100;
+            page++;
+        }
+        // Update the checkpoint
+        staticData.lastTimeChecked = new Date().toISOString();
+        if (allItems.length === 0) {
+            return null;
+        }
+        return [allItems.map((item) => ({ json: item }))];
+    }
+}
+exports.FormfexTrigger = FormfexTrigger;

package/dist/nodes/Formfex/descriptions/ai.description.d.ts

@@ -0,0 +1,3 @@
+import type { INodeProperties } from 'n8n-workflow';
+export declare const aiOperations: INodeProperties[];
+export declare const aiFields: INodeProperties[];

package/dist/nodes/Formfex/descriptions/ai.description.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiFields = exports.aiOperations = void 0;
+exports.aiOperations = [
+    {
+        displayName: 'Operation',
+        name: 'operation',
+        type: 'options',
+        noDataExpression: true,
+        displayOptions: { show: { resource: ['ai'] } },
+        options: [
+            { name: 'Analytics Chat', value: 'analyticsChat', action: 'Chat about analytics', description: 'Ask questions about form analytics data' },
+            { name: 'Generate Form', value: 'generateForm', action: 'Generate form with AI', description: 'Generate a form from a text prompt using AI' },
+            { name: 'Get Job Status', value: 'getJobStatus', action: 'Get AI job status', description: 'Check the status of an AI generation job' },
+            { name: 'Smart Analytics', value: 'smartAnalytics', action: 'Dispatch smart analytics', description: 'Generate a smart analytics report' },
+        ],
+        default: 'generateForm',
+    },
+];
+exports.aiFields = [
+    // ── Generate Form ──
+    {
+        displayName: 'Prompt',
+        name: 'prompt',
+        type: 'string',
+        typeOptions: { rows: 4 },
+        required: true,
+        default: '',
+        placeholder: 'A customer satisfaction survey with rating scales and open-ended feedback',
+        description: 'Describe the form you want AI to generate (max 400 characters)',
+        displayOptions: { show: { resource: ['ai'], operation: ['generateForm'] } },
+    },
+    {
+        displayName: 'Language',
+        name: 'language',
+        type: 'options',
+        options: [
+            { name: 'English', value: 'en' },
+            { name: 'Turkish', value: 'tr' },
+            { name: 'Spanish', value: 'es' },
+            { name: 'Italian', value: 'it' },
+            { name: 'German', value: 'de' },
+            { name: 'Dutch', value: 'nl' },
+        ],
+        default: 'en',
+        description: 'Language for the generated form',
+        displayOptions: { show: { resource: ['ai'], operation: ['generateForm'] } },
+    },
+    // ── Get Job Status ──
+    {
+        displayName: 'Job ID',
+        name: 'jobId',
+        type: 'string',
+        required: true,
+        default: '',
+        description: 'The UUID of the AI job to check',
+        displayOptions: { show: { resource: ['ai'], operation: ['getJobStatus'] } },
+    },
+    // ── Smart Analytics ──
+    {
+        displayName: 'Form ID',
+        name: 'formId',
+        type: 'string',
+        required: true,
+        default: '',
+        description: 'The UUID of the form to analyze',
+        displayOptions: { show: { resource: ['ai'], operation: ['smartAnalytics'] } },
+    },
+    {
+        displayName: 'Callback URL',
+        name: 'callbackUrl',
+        type: 'string',
+        required: true,
+        default: '',
+        placeholder: 'https://your-server.com/webhook/formfex-analytics',
+        description: 'HTTPS URL where the analytics results will be sent when ready',
+        displayOptions: { show: { resource: ['ai'], operation: ['smartAnalytics'] } },
+    },
+    // ── Analytics Chat ──
+    {
+        displayName: 'Form ID',
+        name: 'formId',
+        type: 'string',
+        required: true,
+        default: '',
+        description: 'The UUID of the form to chat about',
+        displayOptions: { show: { resource: ['ai'], operation: ['analyticsChat'] } },
+    },
+    {
+        displayName: 'Message',
+        name: 'message',
+        type: 'string',
+        typeOptions: { rows: 2 },
+        required: true,
+        default: '',
+        placeholder: 'What are the most common responses?',
+        description: 'Your question about the form analytics data',
+        displayOptions: { show: { resource: ['ai'], operation: ['analyticsChat'] } },
+    },
+    {
+        displayName: 'Session ID',
+        name: 'sessionId',
+        type: 'string',
+        default: '',
+        description: 'Session ID for multi-turn conversation. Leave empty to start a new session.',
+        displayOptions: { show: { resource: ['ai'], operation: ['analyticsChat'] } },
+    },
+];

package/dist/nodes/Formfex/descriptions/form.description.d.ts

@@ -0,0 +1,3 @@
+import type { INodeProperties } from 'n8n-workflow';
+export declare const formOperations: INodeProperties[];
+export declare const formFields: INodeProperties[];

package/dist/nodes/Formfex/descriptions/form.description.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formFields = exports.formOperations = void 0;
+exports.formOperations = [
+    {
+        displayName: 'Operation',
+        name: 'operation',
+        type: 'options',
+        noDataExpression: true,
+        displayOptions: { show: { resource: ['form'] } },
+        options: [
+            { name: 'Create', value: 'create', action: 'Create a form', description: 'Create a new form' },
+            { name: 'Delete', value: 'delete', action: 'Delete a form', description: 'Delete a form' },
+            { name: 'Get', value: 'get', action: 'Get a form', description: 'Get a form by ID' },
+            { name: 'Get Many', value: 'getMany', action: 'Get many forms', description: 'List forms (paginated)' },
+            { name: 'Publish', value: 'publish', action: 'Publish a form', description: 'Publish a form' },
+            { name: 'Unpublish', value: 'unpublish', action: 'Unpublish a form', description: 'Unpublish a form' },
+            { name: 'Update', value: 'update', action: 'Update a form', description: 'Update a form' },
+        ],
+        default: 'getMany',
+    },
+];
+exports.formFields = [
+    // ── Form ID (shared) ──
+    {
+        displayName: 'Form ID',
+        name: 'formId',
+        type: 'string',
+        required: true,
+        default: '',
+        description: 'The UUID of the form',
+        displayOptions: {
+            show: { resource: ['form'], operation: ['get', 'update', 'delete', 'publish', 'unpublish'] },
+        },
+    },
+    // ── Create Fields ──
+    {
+        displayName: 'Title',
+        name: 'title',
+        type: 'string',
+        required: true,
+        default: '',
+        description: 'Form title',
+        displayOptions: { show: { resource: ['form'], operation: ['create'] } },
+    },
+    {
+        displayName: 'Additional Fields',
+        name: 'additionalFields',
+        type: 'collection',
+        placeholder: 'Add Field',
+        default: {},
+        displayOptions: { show: { resource: ['form'], operation: ['create'] } },
+        options: [
+            { displayName: 'Description', name: 'description', type: 'string', default: '' },
+            { displayName: 'Language', name: 'language', type: 'string', default: 'en', description: 'Form language code (en, tr, es, it, de, nl)' },
+        ],
+    },
+    // ── Update Fields ──
+    {
+        displayName: 'Update Fields',
+        name: 'updateFields',
+        type: 'collection',
+        placeholder: 'Add Field',
+        default: {},
+        displayOptions: { show: { resource: ['form'], operation: ['update'] } },
+        options: [
+            { displayName: 'Title', name: 'title', type: 'string', default: '' },
+        ],
+    },
+    // ── Publish Fields ──
+    {
+        displayName: 'Additional Fields',
+        name: 'publishFields',
+        type: 'collection',
+        placeholder: 'Add Field',
+        default: {},
+        displayOptions: { show: { resource: ['form'], operation: ['publish'] } },
+        options: [
+            {
+                displayName: 'Visibility',
+                name: 'visibility',
+                type: 'options',
+                options: [
+                    { name: 'Public', value: 'PUBLIC' },
+                    { name: 'Private', value: 'PRIVATE' },
+                ],
+                default: 'PUBLIC',
+            },
+        ],
+    },
+    // ── Get Many Fields ──
+    {
+        displayName: 'Return All',
+        name: 'returnAll',
+        type: 'boolean',
+        default: false,
+        description: 'Whether to return all results or only up to a given limit',
+        displayOptions: { show: { resource: ['form'], operation: ['getMany'] } },
+    },
+    {
+        displayName: 'Limit',
+        name: 'limit',
+        type: 'number',
+        default: 50,
+        typeOptions: { minValue: 1, maxValue: 100 },
+        description: 'Max number of results to return',
+        displayOptions: { show: { resource: ['form'], operation: ['getMany'], returnAll: [false] } },
+    },
+    {
+        displayName: 'Filters',
+        name: 'filters',
+        type: 'collection',
+        placeholder: 'Add Filter',
+        default: {},
+        displayOptions: { show: { resource: ['form'], operation: ['getMany'] } },
+        options: [
+            { displayName: 'Search', name: 'search', type: 'string', default: '', description: 'Search by form title' },
+            { displayName: 'Since', name: 'since', type: 'dateTime', default: '', description: 'Only return forms updated after this time (ISO 8601)' },
+        ],
+    },
+];

package/dist/nodes/Formfex/descriptions/response.description.d.ts

@@ -0,0 +1,3 @@
+import type { INodeProperties } from 'n8n-workflow';
+export declare const responseOperations: INodeProperties[];
+export declare const responseFields: INodeProperties[];

package/dist/nodes/Formfex/descriptions/response.description.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.responseFields = exports.responseOperations = void 0;
+exports.responseOperations = [
+    {
+        displayName: 'Operation',
+        name: 'operation',
+        type: 'options',
+        noDataExpression: true,
+        displayOptions: { show: { resource: ['response'] } },
+        options: [
+            { name: 'Get', value: 'get', action: 'Get a response', description: 'Get a single form response' },
+            { name: 'Get Many', value: 'getMany', action: 'Get many responses', description: 'List form responses (paginated)' },
+        ],
+        default: 'getMany',
+    },
+];
+exports.responseFields = [
+    // ── Form ID (shared) ──
+    {
+        displayName: 'Form ID',
+        name: 'formId',
+        type: 'string',
+        required: true,
+        default: '',
+        description: 'The UUID of the form',
+        displayOptions: { show: { resource: ['response'] } },
+    },
+    // ── Response ID (Get) ──
+    {
+        displayName: 'Response ID',
+        name: 'responseId',
+        type: 'string',
+        required: true,
+        default: '',
+        description: 'The UUID of the response',
+        displayOptions: { show: { resource: ['response'], operation: ['get'] } },
+    },
+    // ── Get Many Fields ──
+    {
+        displayName: 'Return All',
+        name: 'returnAll',
+        type: 'boolean',
+        default: false,
+        description: 'Whether to return all results or only up to a given limit',
+        displayOptions: { show: { resource: ['response'], operation: ['getMany'] } },
+    },
+    {
+        displayName: 'Limit',
+        name: 'limit',
+        type: 'number',
+        default: 50,
+        typeOptions: { minValue: 1, maxValue: 100 },
+        description: 'Max number of results to return',
+        displayOptions: { show: { resource: ['response'], operation: ['getMany'], returnAll: [false] } },
+    },
+    {
+        displayName: 'Filters',
+        name: 'filters',
+        type: 'collection',
+        placeholder: 'Add Filter',
+        default: {},
+        displayOptions: { show: { resource: ['response'], operation: ['getMany'] } },
+        options: [
+            { displayName: 'Start Date', name: 'startDate', type: 'dateTime', default: '', description: 'Only return responses submitted after this date' },
+            { displayName: 'End Date', name: 'endDate', type: 'dateTime', default: '', description: 'Only return responses submitted before this date' },
+            { displayName: 'Since', name: 'since', type: 'dateTime', default: '', description: 'Only return responses submitted after this time (for polling)' },
+            {
+                displayName: 'Order',
+                name: 'order',
+                type: 'options',
+                options: [
+                    { name: 'Newest First', value: 'newest_first' },
+                    { name: 'Oldest First', value: 'oldest_first' },
+                ],
+                default: 'newest_first',
+            },
+        ],
+    },
+];

package/dist/nodes/Formfex/helpers.d.ts

@@ -0,0 +1,12 @@
+import type { IExecuteFunctions, IHookFunctions, ILoadOptionsFunctions, IPollFunctions } from 'n8n-workflow';
+export declare const BASE_URL = "https://api.formfex.com";
+export declare const API_PREFIX = "/api/v1/public";
+export declare const MAX_PAGES = 50;
+/** Validates a string is a UUID. Throws NodeApiError if not. */
+export declare function validateUuid(context: IExecuteFunctions | IHookFunctions | ILoadOptionsFunctions | IPollFunctions, value: string, fieldName: string): void;
+/** Safe URL path encoding for user-supplied IDs. */
+export declare function safePath(id: string): string;
+/** Make an authenticated API request to Formfex. */
+export declare function formfexApiRequest(this: IExecuteFunctions | IHookFunctions | ILoadOptionsFunctions | IPollFunctions, method: 'GET' | 'POST' | 'PATCH' | 'DELETE', endpoint: string, body?: object, query?: Record<string, string | number | boolean>): Promise<any>;
+/** Strip internal details from error messages before showing to user. */
+export declare function sanitizeError(message: string): string;

package/dist/nodes/Formfex/helpers.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PAGES = exports.API_PREFIX = exports.BASE_URL = void 0;
+exports.validateUuid = validateUuid;
+exports.safePath = safePath;
+exports.formfexApiRequest = formfexApiRequest;
+exports.sanitizeError = sanitizeError;
+const n8n_workflow_1 = require("n8n-workflow");
+exports.BASE_URL = 'https://api.formfex.com';
+exports.API_PREFIX = '/api/v1/public';
+exports.MAX_PAGES = 50;
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Validates a string is a UUID. Throws NodeApiError if not. */
+function validateUuid(context, value, fieldName) {
+    if (!UUID_REGEX.test(value)) {
+        throw new n8n_workflow_1.NodeApiError(context.getNode(), {
+            message: `Invalid ${fieldName}: must be a valid UUID`,
+            description: `Received: "${value}"`,
+        });
+    }
+}
+/** Safe URL path encoding for user-supplied IDs. */
+function safePath(id) {
+    return encodeURIComponent(id);
+}
+/** Error map for friendly user-facing messages. */
+const ERROR_MAP = {
+    401: 'Authentication failed. Check your Formfex API key.',
+    402: 'Insufficient credits. Upgrade your Formfex plan.',
+    403: 'Your API key does not have the required scope for this operation.',
+    404: 'The requested resource was not found.',
+    429: 'Rate limit exceeded. Please slow down your requests.',
+};
+/** Make an authenticated API request to Formfex. */
+async function formfexApiRequest(method, endpoint, body, query) {
+    const options = {
+        method,
+        url: `${exports.BASE_URL}${exports.API_PREFIX}${endpoint}`,
+        json: true,
+        qs: query ?? {},
+    };
+    if (body && Object.keys(body).length > 0) {
+        options.body = body;
+    }
+    try {
+        return await this.helpers.requestWithAuthentication.call(this, 'formfexApi', options);
+    }
+    catch (error) {
+        const statusCode = error?.statusCode ?? error?.response?.statusCode;
+        const friendlyMessage = statusCode ? ERROR_MAP[statusCode] : undefined;
+        throw new n8n_workflow_1.NodeApiError(this.getNode(), error, {
+            message: friendlyMessage ?? `Formfex API error (${statusCode ?? 'unknown'})`,
+            description: sanitizeError(error?.message ?? ''),
+        });
+    }
+}
+/** Strip internal details from error messages before showing to user. */
+function sanitizeError(message) {
+    // Remove internal paths, stack traces, and sensitive details
+    return message
+        .replace(/\/[a-zA-Z0-9/_.-]+\.(ts|js):\d+/g, '[internal]')
+        .replace(/at\s+[\w.]+\s+\(.*\)/g, '')
+        .substring(0, 500);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "n8n-nodes-formfex",
+  "version": "1.0.0",
+  "description": "n8n community node for Formfex — AI-powered form builder",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": ["dist/credentials/FormfexApi.credentials.js"],
+    "nodes": [
+      "dist/nodes/Formfex/Formfex.node.js",
+      "dist/nodes/Formfex/FormfexTrigger.node.js"
+    ]
+  },
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "formfex",
+    "forms",
+    "automation",
+    "ai",
+    "form-builder"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint . --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "devDependencies": {
+    "n8n-workflow": "^1.72.0",
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/formfex/n8n-nodes-formfex"
+  }
+}