first commit

packages/nodes-base/nodes/Formstack/FormstackTrigger.node.json

@@ -0,0 +1,18 @@
+{
+	"node": "n8n-nodes-base.formstackTrigger",
+	"nodeVersion": "1.0",
+	"codexVersion": "1.0",
+	"categories": ["Communication"],
+	"resources": {
+		"credentialDocumentation": [
+			{
+				"url": "https://docs.n8n.io/integrations/builtin/credentials/formstacktrigger/"
+			}
+		],
+		"primaryDocumentation": [
+			{
+				"url": "https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.formstacktrigger/"
+			}
+		]
+	}
+}

packages/nodes-base/nodes/Formstack/FormstackTrigger.node.ts

@@ -0,0 +1,184 @@
+import type {
+	IHookFunctions,
+	IWebhookFunctions,
+	IDataObject,
+	INodeType,
+	INodeTypeDescription,
+	IWebhookResponseData,
+} from 'n8n-workflow';
+import { NodeConnectionTypes } from 'n8n-workflow';
+
+import type { IFormstackWebhookResponseBody } from './GenericFunctions';
+import { apiRequest, getForms } from './GenericFunctions';
+
+export class FormstackTrigger implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Formstack Trigger',
+		name: 'formstackTrigger',
+		icon: 'file:formstack.svg',
+		group: ['trigger'],
+		version: 1,
+		subtitle: '=Form ID: {{$parameter["formId"]}}',
+		description: 'Starts the workflow on a Formstack form submission.',
+		defaults: {
+			name: 'Formstack Trigger',
+		},
+		inputs: [],
+		outputs: [NodeConnectionTypes.Main],
+		credentials: [
+			{
+				name: 'formstackApi',
+				required: true,
+				displayOptions: {
+					show: {
+						authentication: ['accessToken'],
+					},
+				},
+			},
+			{
+				name: 'formstackOAuth2Api',
+				required: true,
+				displayOptions: {
+					show: {
+						authentication: ['oAuth2'],
+					},
+				},
+			},
+		],
+		webhooks: [
+			{
+				name: 'default',
+				httpMethod: 'POST',
+				responseMode: 'onReceived',
+				path: 'webhook',
+			},
+		],
+		properties: [
+			{
+				displayName: 'Authentication',
+				name: 'authentication',
+				type: 'options',
+				options: [
+					{
+						name: 'Access Token',
+						value: 'accessToken',
+					},
+					{
+						name: 'OAuth2',
+						value: 'oAuth2',
+					},
+				],
+				default: 'accessToken',
+			},
+			{
+				displayName: 'Form Name or ID',
+				name: 'formId',
+				type: 'options',
+				typeOptions: {
+					loadOptionsMethod: 'getForms',
+				},
+				default: '',
+				required: true,
+				description:
+					'The Formstack form to monitor for new submissions. Choose from the list, or specify an ID using an <a href="https://docs.n8n.io/code/expressions/">expression</a>.',
+			},
+			{
+				displayName: 'Simplify',
+				name: 'simple',
+				type: 'boolean',
+				default: true,
+				description:
+					'Whether to return a simplified version of the response instead of the raw data',
+			},
+		],
+	};
+
+	methods = {
+		loadOptions: {
+			getForms,
+		},
+	};
+
+	webhookMethods = {
+		default: {
+			async checkExists(this: IHookFunctions): Promise<boolean> {
+				const webhookUrl = this.getNodeWebhookUrl('default');
+				const webhookData = this.getWorkflowStaticData('node');
+
+				const formId = this.getNodeParameter('formId') as string;
+
+				const endpoint = `form/${formId}/webhook.json`;
+
+				const { webhooks } = await apiRequest.call(this, 'GET', endpoint);
+
+				for (const webhook of webhooks) {
+					if (webhook.url === webhookUrl) {
+						webhookData.webhookId = webhook.id;
+						return true;
+					}
+				}
+
+				return false;
+			},
+			async create(this: IHookFunctions): Promise<boolean> {
+				const webhookUrl = this.getNodeWebhookUrl('default');
+
+				const formId = this.getNodeParameter('formId') as string;
+
+				const endpoint = `form/${formId}/webhook.json`;
+
+				// TODO: Add handshake key support
+				const body = {
+					url: webhookUrl,
+					standardize_field_values: true,
+					include_field_type: true,
+					content_type: 'json',
+				};
+
+				const response = await apiRequest.call(this, 'POST', endpoint, body);
+
+				const webhookData = this.getWorkflowStaticData('node');
+				webhookData.webhookId = response.id;
+				return true;
+			},
+			async delete(this: IHookFunctions): Promise<boolean> {
+				const webhookData = this.getWorkflowStaticData('node');
+
+				if (webhookData.webhookId !== undefined) {
+					const endpoint = `webhook/${webhookData.webhookId}.json`;
+
+					try {
+						const body = {};
+						await apiRequest.call(this, 'DELETE', endpoint, body);
+					} catch (e) {
+						return false;
+					}
+					// Remove from the static workflow data so that it is clear
+					// that no webhooks are registered anymore
+					delete webhookData.webhookId;
+				}
+
+				return true;
+			},
+		},
+	};
+
+	async webhook(this: IWebhookFunctions): Promise<IWebhookResponseData> {
+		const bodyData = this.getBodyData() as unknown as IFormstackWebhookResponseBody;
+		const simple = this.getNodeParameter('simple') as string;
+
+		const response = bodyData as unknown as IDataObject;
+
+		if (simple) {
+			for (const key of Object.keys(response)) {
+				if ((response[key] as IDataObject).hasOwnProperty('value')) {
+					response[key] = (response[key] as IDataObject).value;
+				}
+			}
+		}
+
+		return {
+			workflowData: [this.helpers.returnJsonArray([response as unknown as IDataObject])],
+		};
+	}
+}

packages/nodes-base/nodes/Formstack/GenericFunctions.ts

@@ -0,0 +1,195 @@
+import type {
+	IDataObject,
+	IExecuteFunctions,
+	IHookFunctions,
+	ILoadOptionsFunctions,
+	IWebhookFunctions,
+	INodePropertyOptions,
+	JsonObject,
+	IHttpRequestMethods,
+	IRequestOptions,
+} from 'n8n-workflow';
+import { ApplicationError, NodeApiError } from 'n8n-workflow';
+
+export interface IFormstackFieldDefinitionType {
+	id: string;
+	label: string;
+	description: string;
+	name: string;
+	type: string;
+	options: unknown;
+	required: string;
+	uniq: string;
+	hidden: string;
+	readonly: string;
+	colspan: string;
+	label_position: string;
+	num_columns: string;
+	date_format: string;
+	time_format: string;
+}
+
+export interface IFormstackWebhookResponseBody {
+	FormID: string;
+	UniqueID: string;
+}
+
+export interface IFormstackSubmissionFieldContainer {
+	field: string;
+	value: string;
+}
+
+export const FormstackFieldFormats = {
+	ID: 'id',
+	Label: 'label',
+	Name: 'name',
+} as const;
+
+export type FormstackFieldFormat =
+	(typeof FormstackFieldFormats)[keyof typeof FormstackFieldFormats];
+
+/**
+ * Make an API request to Formstack
+ *
+ */
+export async function apiRequest(
+	this: IHookFunctions | IExecuteFunctions | ILoadOptionsFunctions | IWebhookFunctions,
+	method: IHttpRequestMethods,
+	endpoint: string,
+	body: IDataObject = {},
+	query: IDataObject = {},
+): Promise<any> {
+	const authenticationMethod = this.getNodeParameter('authentication', 0);
+
+	const options: IRequestOptions = {
+		headers: {},
+		method,
+		body,
+		qs: query || {},
+		uri: `https://www.formstack.com/api/v2/${endpoint}`,
+		json: true,
+	};
+
+	if (!Object.keys(body).length) {
+		delete options.body;
+	}
+
+	try {
+		if (authenticationMethod === 'accessToken') {
+			const credentials = await this.getCredentials<{ accessToken: string }>('formstackApi');
+
+			options.headers!.Authorization = `Bearer ${credentials.accessToken}`;
+			return await this.helpers.request(options);
+		} else {
+			return await this.helpers.requestOAuth2.call(this, 'formstackOAuth2Api', options);
+		}
+	} catch (error) {
+		throw new NodeApiError(this.getNode(), error as JsonObject);
+	}
+}
+
+/**
+ * Make an API request to paginated Formstack endpoint
+ * and return all results
+ *
+ * @param {(IHookFunctions | IExecuteFunctions)} this
+ */
+export async function apiRequestAllItems(
+	this: IHookFunctions | IExecuteFunctions | ILoadOptionsFunctions | IWebhookFunctions,
+	method: IHttpRequestMethods,
+	endpoint: string,
+	body: IDataObject,
+	dataKey: string,
+	query?: IDataObject,
+): Promise<any> {
+	if (query === undefined) {
+		query = {};
+	}
+
+	query.per_page = 200;
+	query.page = 0;
+
+	const returnData = {
+		items: [] as IDataObject[],
+	};
+
+	let responseData;
+
+	do {
+		query.page += 1;
+
+		responseData = await apiRequest.call(this, method, endpoint, body, query);
+		returnData.items.push.apply(returnData.items, responseData[dataKey] as IDataObject[]);
+	} while (
+		responseData.total !== undefined &&
+		Math.ceil(responseData.total / query.per_page) > query.page
+	);
+
+	return returnData;
+}
+
+/**
+ * Returns all the available forms
+ *
+ */
+export async function getForms(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]> {
+	const endpoint = 'form.json';
+	const responseData = await apiRequestAllItems.call(this, 'GET', endpoint, {}, 'forms', {
+		folders: false,
+	});
+
+	if (responseData.items === undefined) {
+		throw new ApplicationError('No data got returned', { level: 'warning' });
+	}
+	const returnData: INodePropertyOptions[] = [];
+	for (const baseData of responseData.items) {
+		returnData.push({
+			name: baseData.name,
+			value: baseData.id,
+		});
+	}
+	return returnData;
+}
+
+/**
+ * Returns all the fields of a form
+ *
+ */
+export async function getFields(
+	this: IWebhookFunctions,
+	formID: string,
+): Promise<Record<string, IFormstackFieldDefinitionType>> {
+	const endpoint = `form/${formID}.json`;
+	const responseData = await apiRequestAllItems.call(this, 'GET', endpoint, {}, 'fields');
+
+	if (responseData.items === undefined) {
+		throw new ApplicationError('No form fields meta data got returned', { level: 'warning' });
+	}
+
+	const fields = responseData.items as IFormstackFieldDefinitionType[];
+	const fieldMap: Record<string, IFormstackFieldDefinitionType> = {};
+
+	fields.forEach((field) => {
+		fieldMap[field.id] = field;
+	});
+
+	return fieldMap;
+}
+
+/**
+ * Returns all the fields of a form
+ *
+ */
+export async function getSubmission(
+	this: ILoadOptionsFunctions | IWebhookFunctions,
+	uniqueId: string,
+): Promise<IFormstackSubmissionFieldContainer[]> {
+	const endpoint = `submission/${uniqueId}.json`;
+	const responseData = await apiRequestAllItems.call(this, 'GET', endpoint, {}, 'data');
+
+	if (responseData.items === undefined) {
+		throw new ApplicationError('No form fields meta data got returned', { level: 'warning' });
+	}
+
+	return responseData.items as IFormstackSubmissionFieldContainer[];
+}

packages/nodes-base/nodes/Formstack/formstack.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" fill="#fff" fill-rule="evenodd" stroke="#000" stroke-linecap="round" stroke-linejoin="round" viewBox="0 0 65.006 55.006"><use xlink:href="#a" x=".503" y=".503"/><symbol id="a" overflow="visible"><g fill-rule="nonzero" stroke="none"><path fill="#21b573" d="M50.667 5.333h3.723a1.6 1.6 0 0 1 1.6 1.6V46.38a1.6 1.6 0 0 1-1.6 1.6h-3.723zm8 5.333h3.723a1.6 1.6 0 0 1 1.6 1.6v28.78a1.6 1.6 0 0 1-1.6 1.61h-3.723zM0 1.6C0 .714.714 0 1.6 0h44.8c.886 0 1.6.714 1.6 1.6v50.133c0 .886-.714 1.6-1.6 1.6H1.6c-.886 0-1.6-.714-1.6-1.6z"/><path d="M11.2 8.533h24.624a.532.532 0 0 1 .333.95L11.533 29.182a.533.533 0 0 1-.866-.417V9.056c0-.295.239-.533.533-.533zm-.533 32.024v-8.252c0-.164.075-.319.204-.42l7.173-5.63a.53.53 0 0 1 .329-.114h13.036a.532.532 0 0 1 .301.973L11.502 40.996a.533.533 0 0 1-.835-.44zm.228 3.095 7.467-5.203a.533.533 0 0 1 .839.438v5.42a.533.533 0 0 1-.533.533H11.17a.51.51 0 0 1-.514-.514v-.236c0-.175.085-.338.228-.438z"/></g></symbol></svg>