first commit

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

@@ -0,0 +1,106 @@
+import type {
+	IDataObject,
+	IExecuteFunctions,
+	IHttpRequestMethods,
+	ILoadOptionsFunctions,
+	IRequestOptions,
+	JsonObject,
+} from 'n8n-workflow';
+import { NodeApiError, NodeOperationError } from 'n8n-workflow';
+
+import type {
+	GristCredentials,
+	GristDefinedFields,
+	GristFilterProperties,
+	GristSortProperties,
+} from './types';
+
+export async function gristApiRequest(
+	this: IExecuteFunctions | ILoadOptionsFunctions,
+	method: IHttpRequestMethods,
+	endpoint: string,
+	body: IDataObject | number[] = {},
+	qs: IDataObject = {},
+) {
+	const { apiKey, planType, customSubdomain, selfHostedUrl } =
+		await this.getCredentials<GristCredentials>('gristApi');
+
+	const gristapiurl =
+		planType === 'free'
+			? `https://docs.getgrist.com/api${endpoint}`
+			: planType === 'paid'
+				? `https://${customSubdomain}.getgrist.com/api${endpoint}`
+				: `${selfHostedUrl}/api${endpoint}`;
+
+	const options: IRequestOptions = {
+		headers: {
+			Authorization: `Bearer ${apiKey}`,
+		},
+		method,
+		uri: gristapiurl,
+		qs,
+		body,
+		json: true,
+	};
+
+	if (!Object.keys(body).length) {
+		delete options.body;
+	}
+
+	if (!Object.keys(qs).length) {
+		delete options.qs;
+	}
+
+	try {
+		return await this.helpers.request(options);
+	} catch (error) {
+		throw new NodeApiError(this.getNode(), error as JsonObject);
+	}
+}
+
+export function parseSortProperties(sortProperties: GristSortProperties) {
+	return sortProperties.reduce((acc, cur, curIdx) => {
+		if (cur.direction === 'desc') acc += '-';
+		acc += cur.field;
+		if (curIdx !== sortProperties.length - 1) acc += ',';
+		return acc;
+	}, '');
+}
+
+export function isSafeInteger(val: number) {
+	//used MIN_SAFE_INTEGER and MAX_SAFE_INTEGER instead of MIN_VALUE and MAX_VALUE to avoid edge cases
+	return !isNaN(val) && val > Number.MIN_SAFE_INTEGER && val < Number.MAX_SAFE_INTEGER;
+}
+
+export function parseFilterProperties(filterProperties: GristFilterProperties) {
+	return filterProperties.reduce<{ [key: string]: Array<string | number> }>((acc, cur) => {
+		acc[cur.field] = acc[cur.field] ?? [];
+		const values = isSafeInteger(Number(cur.values)) ? Number(cur.values) : cur.values;
+		acc[cur.field].push(values);
+		return acc;
+	}, {});
+}
+
+export function parseDefinedFields(fieldsToSendProperties: GristDefinedFields) {
+	return fieldsToSendProperties.reduce<{ [key: string]: string }>((acc, cur) => {
+		acc[cur.fieldId] = cur.fieldValue;
+		return acc;
+	}, {});
+}
+
+export function parseAutoMappedInputs(incomingKeys: string[], inputsToIgnore: string[], item: any) {
+	return incomingKeys.reduce<{ [key: string]: any }>((acc, curKey) => {
+		if (inputsToIgnore.includes(curKey)) return acc;
+		acc = { ...acc, [curKey]: item[curKey] };
+		return acc;
+	}, {});
+}
+
+export function throwOnZeroDefinedFields(this: IExecuteFunctions, fields: GristDefinedFields) {
+	if (!fields?.length) {
+		throw new NodeOperationError(
+			this.getNode(),
+			"No defined data found. Please specify the data to send in 'Fields to Send'.",
+		);
+	}
+}

packages/nodes-base/nodes/Grist/Grist.node.json

@@ -0,0 +1,18 @@
+{
+	"node": "n8n-nodes-base.grist",
+	"nodeVersion": "1.0",
+	"codexVersion": "1.0",
+	"categories": ["Data & Storage"],
+	"resources": {
+		"credentialDocumentation": [
+			{
+				"url": "https://docs.n8n.io/integrations/builtin/credentials/grist/"
+			}
+		],
+		"primaryDocumentation": [
+			{
+				"url": "https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.grist/"
+			}
+		]
+	}
+}

packages/nodes-base/nodes/Grist/Grist.node.ts

@@ -0,0 +1,267 @@
+import {
+	type IExecuteFunctions,
+	type ICredentialsDecrypted,
+	type ICredentialTestFunctions,
+	type IDataObject,
+	type ILoadOptionsFunctions,
+	type INodeCredentialTestResult,
+	type INodeExecutionData,
+	type INodeType,
+	type INodeTypeDescription,
+	type IRequestOptions,
+	NodeConnectionTypes,
+} from 'n8n-workflow';
+
+import {
+	gristApiRequest,
+	parseAutoMappedInputs,
+	parseDefinedFields,
+	parseFilterProperties,
+	parseSortProperties,
+	throwOnZeroDefinedFields,
+} from './GenericFunctions';
+import { operationFields } from './OperationDescription';
+import type {
+	FieldsToSend,
+	GristColumns,
+	GristCreateRowPayload,
+	GristCredentials,
+	GristGetAllOptions,
+	GristUpdateRowPayload,
+	SendingOptions,
+} from './types';
+
+export class Grist implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Grist',
+		name: 'grist',
+		icon: 'file:grist.svg',
+		subtitle: '={{$parameter["operation"]}}',
+		group: ['input'],
+		version: 1,
+		description: 'Consume the Grist API',
+		defaults: {
+			name: 'Grist',
+		},
+		usableAsTool: true,
+		inputs: [NodeConnectionTypes.Main],
+		outputs: [NodeConnectionTypes.Main],
+		credentials: [
+			{
+				name: 'gristApi',
+				required: true,
+				testedBy: 'gristApiTest',
+			},
+		],
+		properties: operationFields,
+	};
+
+	methods = {
+		loadOptions: {
+			async getTableColumns(this: ILoadOptionsFunctions) {
+				const docId = this.getNodeParameter('docId', 0) as string;
+				const tableId = this.getNodeParameter('tableId', 0) as string;
+				const endpoint = `/docs/${docId}/tables/${tableId}/columns`;
+
+				const { columns } = (await gristApiRequest.call(this, 'GET', endpoint)) as GristColumns;
+				return columns.map(({ id }) => ({ name: id, value: id }));
+			},
+		},
+
+		credentialTest: {
+			async gristApiTest(
+				this: ICredentialTestFunctions,
+				credential: ICredentialsDecrypted,
+			): Promise<INodeCredentialTestResult> {
+				const { apiKey, planType, customSubdomain, selfHostedUrl } =
+					credential.data as GristCredentials;
+
+				const endpoint = '/orgs';
+
+				const gristapiurl =
+					planType === 'free'
+						? `https://docs.getgrist.com/api${endpoint}`
+						: planType === 'paid'
+							? `https://${customSubdomain}.getgrist.com/api${endpoint}`
+							: `${selfHostedUrl}/api${endpoint}`;
+
+				const options: IRequestOptions = {
+					headers: {
+						Authorization: `Bearer ${apiKey}`,
+					},
+					method: 'GET',
+					uri: gristapiurl,
+					qs: { limit: 1 },
+					json: true,
+				};
+
+				try {
+					await this.helpers.request(options);
+					return {
+						status: 'OK',
+						message: 'Authentication successful',
+					};
+				} catch (error) {
+					return {
+						status: 'Error',
+						message: error.message,
+					};
+				}
+			},
+		},
+	};
+
+	async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+		const items = this.getInputData();
+		let responseData;
+		const returnData: INodeExecutionData[] = [];
+
+		const operation = this.getNodeParameter('operation', 0);
+
+		for (let i = 0; i < items.length; i++) {
+			try {
+				if (operation === 'create') {
+					// ----------------------------------
+					//             create
+					// ----------------------------------
+
+					// https://support.getgrist.com/api/#tag/records/paths/~1docs~1{docId}~1tables~1{tableId}~1records/post
+
+					const body = { records: [] } as GristCreateRowPayload;
+
+					const dataToSend = this.getNodeParameter('dataToSend', 0) as SendingOptions;
+
+					if (dataToSend === 'autoMapInputs') {
+						const incomingKeys = Object.keys(items[i].json);
+						const rawInputsToIgnore = this.getNodeParameter('inputsToIgnore', i) as string;
+						const inputsToIgnore = rawInputsToIgnore.split(',').map((c) => c.trim());
+						const fields = parseAutoMappedInputs(incomingKeys, inputsToIgnore, items[i].json);
+						body.records.push({ fields });
+					} else if (dataToSend === 'defineInNode') {
+						const { properties } = this.getNodeParameter('fieldsToSend', i, []) as FieldsToSend;
+						throwOnZeroDefinedFields.call(this, properties);
+						body.records.push({ fields: parseDefinedFields(properties) });
+					}
+
+					const docId = this.getNodeParameter('docId', 0) as string;
+					const tableId = this.getNodeParameter('tableId', 0) as string;
+					const endpoint = `/docs/${docId}/tables/${tableId}/records`;
+
+					responseData = await gristApiRequest.call(this, 'POST', endpoint, body);
+					responseData = {
+						id: responseData.records[0].id,
+						...body.records[0].fields,
+					};
+				} else if (operation === 'delete') {
+					// ----------------------------------
+					//            delete
+					// ----------------------------------
+
+					// https://support.getgrist.com/api/#tag/data/paths/~1docs~1{docId}~1tables~1{tableId}~1data~1delete/post
+
+					const docId = this.getNodeParameter('docId', 0) as string;
+					const tableId = this.getNodeParameter('tableId', 0) as string;
+					const endpoint = `/docs/${docId}/tables/${tableId}/data/delete`;
+
+					const rawRowIds = (this.getNodeParameter('rowId', i) as string).toString();
+					const body = rawRowIds
+						.split(',')
+						.map((c) => c.trim())
+						.map(Number);
+
+					await gristApiRequest.call(this, 'POST', endpoint, body);
+					responseData = { success: true };
+				} else if (operation === 'update') {
+					// ----------------------------------
+					//            update
+					// ----------------------------------
+
+					// https://support.getgrist.com/api/#tag/records/paths/~1docs~1{docId}~1tables~1{tableId}~1records/patch
+
+					const body = { records: [] } as GristUpdateRowPayload;
+
+					const rowId = this.getNodeParameter('rowId', i) as string;
+					const dataToSend = this.getNodeParameter('dataToSend', 0) as SendingOptions;
+
+					if (dataToSend === 'autoMapInputs') {
+						const incomingKeys = Object.keys(items[i].json);
+						const rawInputsToIgnore = this.getNodeParameter('inputsToIgnore', i) as string;
+						const inputsToIgnore = rawInputsToIgnore.split(',').map((c) => c.trim());
+						const fields = parseAutoMappedInputs(incomingKeys, inputsToIgnore, items[i].json);
+						body.records.push({ id: Number(rowId), fields });
+					} else if (dataToSend === 'defineInNode') {
+						const { properties } = this.getNodeParameter('fieldsToSend', i, []) as FieldsToSend;
+						throwOnZeroDefinedFields.call(this, properties);
+						const fields = parseDefinedFields(properties);
+						body.records.push({ id: Number(rowId), fields });
+					}
+
+					const docId = this.getNodeParameter('docId', 0) as string;
+					const tableId = this.getNodeParameter('tableId', 0) as string;
+					const endpoint = `/docs/${docId}/tables/${tableId}/records`;
+
+					await gristApiRequest.call(this, 'PATCH', endpoint, body);
+					responseData = {
+						id: rowId,
+						...body.records[0].fields,
+					};
+				} else if (operation === 'getAll') {
+					// ----------------------------------
+					//             getAll
+					// ----------------------------------
+
+					// https://support.getgrist.com/api/#tag/records
+
+					const docId = this.getNodeParameter('docId', 0) as string;
+					const tableId = this.getNodeParameter('tableId', 0) as string;
+					const endpoint = `/docs/${docId}/tables/${tableId}/records`;
+
+					const qs: IDataObject = {};
+
+					const returnAll = this.getNodeParameter('returnAll', i);
+
+					if (!returnAll) {
+						qs.limit = this.getNodeParameter('limit', i);
+					}
+
+					const { sort, filter } = this.getNodeParameter(
+						'additionalOptions',
+						i,
+					) as GristGetAllOptions;
+
+					if (sort?.sortProperties.length) {
+						qs.sort = parseSortProperties(sort.sortProperties);
+					}
+
+					if (filter?.filterProperties.length) {
+						const parsed = parseFilterProperties(filter.filterProperties);
+						qs.filter = JSON.stringify(parsed);
+					}
+
+					responseData = await gristApiRequest.call(this, 'GET', endpoint, {}, qs);
+					responseData = responseData.records.map((data: IDataObject) => {
+						return { id: data.id, ...(data.fields as object) };
+					});
+				}
+			} catch (error) {
+				if (this.continueOnFail()) {
+					const executionData = this.helpers.constructExecutionMetaData(
+						this.helpers.returnJsonArray({ error: error.message }),
+						{ itemData: { item: i } },
+					);
+					returnData.push(...executionData);
+
+					continue;
+				}
+				throw error;
+			}
+			const executionData = this.helpers.constructExecutionMetaData(
+				this.helpers.returnJsonArray(responseData as IDataObject[]),
+				{ itemData: { item: i } },
+			);
+			returnData.push(...executionData);
+		}
+
+		return [returnData];
+	}
+}

packages/nodes-base/nodes/Grist/OperationDescription.ts

@@ -0,0 +1,313 @@
+import type { INodeProperties } from 'n8n-workflow';
+
+export const operationFields: INodeProperties[] = [
+	{
+		displayName: 'Operation',
+		name: 'operation',
+		type: 'options',
+		noDataExpression: true,
+		options: [
+			{
+				name: 'Create Row',
+				value: 'create',
+				description: 'Create rows in a table',
+				action: 'Create rows in a table',
+			},
+			{
+				name: 'Delete Row',
+				value: 'delete',
+				description: 'Delete rows from a table',
+				action: 'Delete rows from a table',
+			},
+			{
+				// eslint-disable-next-line n8n-nodes-base/node-param-option-name-wrong-for-get-many
+				name: 'Get Many Rows',
+				value: 'getAll',
+				description: 'Read rows from a table',
+				action: 'Read rows from a table',
+			},
+			{
+				name: 'Update Row',
+				value: 'update',
+				description: 'Update rows in a table',
+				action: 'Update rows in a table',
+			},
+		],
+		default: 'getAll',
+	},
+
+	// ----------------------------------
+	//             shared
+	// ----------------------------------
+	{
+		displayName: 'Document ID',
+		name: 'docId',
+		type: 'string',
+		default: '',
+		required: true,
+		description:
+			'In your document, click your profile icon, then Document Settings, then copy the value under "This document\'s ID"',
+	},
+	{
+		displayName: 'Table ID',
+		name: 'tableId',
+		type: 'string',
+		default: '',
+		required: true,
+		description: 'ID of table to operate on. If unsure, look at the Code View.',
+	},
+
+	// ----------------------------------
+	//              delete
+	// ----------------------------------
+	{
+		displayName: 'Row ID',
+		name: 'rowId',
+		type: 'string',
+		displayOptions: {
+			show: {
+				operation: ['delete'],
+			},
+		},
+		default: '',
+		description: 'ID of the row to delete, or comma-separated list of row IDs to delete',
+		required: true,
+	},
+
+	// ----------------------------------
+	//              getAll
+	// ----------------------------------
+	{
+		displayName: 'Return All',
+		name: 'returnAll',
+		type: 'boolean',
+		default: false,
+		description: 'Whether to return all results or only up to a given limit',
+		displayOptions: {
+			show: {
+				operation: ['getAll'],
+			},
+		},
+	},
+	{
+		displayName: 'Limit',
+		name: 'limit',
+		type: 'number',
+		typeOptions: {
+			minValue: 1,
+		},
+		default: 50,
+		description: 'Max number of results to return',
+		displayOptions: {
+			show: {
+				operation: ['getAll'],
+				returnAll: [false],
+			},
+		},
+	},
+	{
+		displayName: 'Additional Options',
+		name: 'additionalOptions',
+		type: 'collection',
+		displayOptions: {
+			show: {
+				operation: ['getAll'],
+			},
+		},
+		default: {},
+		placeholder: 'Add option',
+		options: [
+			{
+				displayName: 'Filter',
+				name: 'filter',
+				placeholder: 'Add Filter',
+				description:
+					'Only return rows matching all of the given filters. For complex filters, create a formula column and filter for the value "true".',
+				type: 'fixedCollection',
+				typeOptions: {
+					multipleValues: true,
+				},
+				default: {},
+				options: [
+					{
+						displayName: 'Filter Properties',
+						name: 'filterProperties',
+						values: [
+							{
+								displayName: 'Column Name or ID',
+								name: 'field',
+								type: 'options',
+								typeOptions: {
+									loadOptionsDependsOn: ['docId', 'tableId'],
+									loadOptionsMethod: 'getTableColumns',
+								},
+								default: '',
+								description:
+									'Column to apply the filter in. Choose from the list, or specify an ID using an <a href="https://docs.n8n.io/code/expressions/">expression</a>.',
+								required: true,
+							},
+							{
+								displayName: 'Values',
+								name: 'values',
+								type: 'string',
+								default: '',
+								description: 'Comma-separated list of values to search for in the filtered column',
+							},
+						],
+					},
+				],
+			},
+			{
+				displayName: 'Sort Order',
+				name: 'sort',
+				placeholder: 'Add Field',
+				type: 'fixedCollection',
+				typeOptions: {
+					multipleValues: true,
+				},
+				default: {},
+				options: [
+					{
+						displayName: 'Sort Properties',
+						name: 'sortProperties',
+						values: [
+							{
+								displayName: 'Column Name or ID',
+								name: 'field',
+								type: 'options',
+								typeOptions: {
+									loadOptionsDependsOn: ['docId', 'tableId'],
+									loadOptionsMethod: 'getTableColumns',
+								},
+								default: '',
+								required: true,
+								description:
+									'Column to sort on. Choose from the list, or specify an ID using an <a href="https://docs.n8n.io/code/expressions/">expression</a>.',
+							},
+							{
+								displayName: 'Direction',
+								name: 'direction',
+								type: 'options',
+								options: [
+									{
+										name: 'Ascending',
+										value: 'asc',
+									},
+									{
+										name: 'Descending',
+										value: 'desc',
+									},
+								],
+								default: 'asc',
+								description: 'Direction to sort in',
+							},
+						],
+					},
+				],
+			},
+		],
+	},
+
+	// ----------------------------------
+	//            update
+	// ----------------------------------
+	{
+		displayName: 'Row ID',
+		name: 'rowId',
+		type: 'string',
+		displayOptions: {
+			show: {
+				operation: ['update'],
+			},
+		},
+		default: '',
+		description: 'ID of the row to update',
+		required: true,
+	},
+
+	// ----------------------------------
+	//         create + update
+	// ----------------------------------
+	{
+		displayName: 'Data to Send',
+		name: 'dataToSend',
+		type: 'options',
+		options: [
+			{
+				name: 'Auto-Map Input Data to Columns',
+				value: 'autoMapInputs',
+				description: 'Use when node input properties match destination column names',
+			},
+			{
+				name: 'Define Below for Each Column',
+				value: 'defineInNode',
+				description: 'Set the value for each destination column',
+			},
+		],
+		displayOptions: {
+			show: {
+				operation: ['create', 'update'],
+			},
+		},
+		default: 'defineInNode',
+		description: 'Whether to insert the input data this node receives in the new row',
+	},
+	{
+		displayName: 'Inputs to Ignore',
+		name: 'inputsToIgnore',
+		type: 'string',
+		displayOptions: {
+			show: {
+				operation: ['create', 'update'],
+				dataToSend: ['autoMapInputs'],
+			},
+		},
+		default: '',
+		description:
+			'List of input properties to avoid sending, separated by commas. Leave empty to send all properties.',
+		placeholder: 'Enter properties...',
+	},
+	{
+		displayName: 'Fields to Send',
+		name: 'fieldsToSend',
+		placeholder: 'Add Field',
+		type: 'fixedCollection',
+		typeOptions: {
+			multipleValueButtonText: 'Add Field to Send',
+			multipleValues: true,
+		},
+		displayOptions: {
+			show: {
+				operation: ['create', 'update'],
+				dataToSend: ['defineInNode'],
+			},
+		},
+		default: {},
+		options: [
+			{
+				displayName: 'Properties',
+				name: 'properties',
+				values: [
+					{
+						displayName: 'Column Name or ID',
+						name: 'fieldId',
+						description:
+							'Choose from the list, or specify an ID using an <a href="https://docs.n8n.io/code/expressions/">expression</a>',
+						type: 'options',
+						typeOptions: {
+							loadOptionsDependsOn: ['tableId'],
+							loadOptionsMethod: 'getTableColumns',
+						},
+						default: '',
+					},
+					{
+						displayName: 'Field Value',
+						name: 'fieldValue',
+						type: 'string',
+						default: '',
+					},
+				],
+			},
+		],
+	},
+];

packages/nodes-base/nodes/Grist/types.ts

@@ -0,0 +1,47 @@
+export type GristCredentials = {
+	apiKey: string;
+	planType: 'free' | 'paid' | 'selfHosted';
+	customSubdomain?: string;
+	selfHostedUrl?: string;
+};
+
+export type GristColumns = {
+	columns: Array<{ id: string }>;
+};
+
+export type GristSortProperties = Array<{
+	field: string;
+	direction: 'asc' | 'desc';
+}>;
+
+export type GristFilterProperties = Array<{
+	field: string;
+	values: string;
+}>;
+
+export type GristGetAllOptions = {
+	sort?: { sortProperties: GristSortProperties };
+	filter?: { filterProperties: GristFilterProperties };
+};
+
+export type GristDefinedFields = Array<{
+	fieldId: string;
+	fieldValue: string;
+}>;
+
+export type GristCreateRowPayload = {
+	records: Array<{
+		fields: { [key: string]: any };
+	}>;
+};
+
+export type GristUpdateRowPayload = {
+	records: Array<{
+		id: number;
+		fields: { [key: string]: any };
+	}>;
+};
+
+export type SendingOptions = 'defineInNode' | 'autoMapInputs';
+
+export type FieldsToSend = { properties: GristDefinedFields };