Phacet n8n Community Node

Custom n8n community node for integrating with the Phacet API. This node allows you to upload files and create rows in Phacet spreadsheets directly from your n8n workflows.

Features

• File Upload: Upload PDF files to Phacet
• Row Creation: Create rows in Phacet spreadsheets with dynamic dropdowns
• Dynamic UI: User-friendly dropdowns for selecting phacets, sessions, and columns
• Type Safety: Full TypeScript implementation with strict linting

Prerequisites

You need the following installed on your development machine:

• git
• Node.js and npm (minimum version Node 20)
• n8n installed globally: npm install n8n -g

Setup

1. Clone the repository:

   git clone <repository-url>
   cd n8n-node

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Link the node for local development:

   npm link
   n8n start

5. The Phacet node should now be available in your n8n instance at http://localhost:5678

Repository Structure

This repository follows n8n's community node structure:

Key Directories

• /nodes/ - Contains node implementations
  • /Phacet/ - Main Phacet node with operations for files and rows
  • /NasaPics/ - Example NASA Pictures node
• /credentials/ - Authentication credential definitions
  • PhacetApi.credentials.ts - Phacet API key authentication
  • NasaPicsApi.credentials.ts - NASA API authentication
• /dist/ - Compiled output (auto-generated)
• /zapier-examples/ - Reference implementations from Zapier integration

Core Concepts

Nodes: The main integration components that appear in n8n workflows. Each node:

• Defines available operations (upload, create, etc.)
• Specifies UI parameters with validation
• Implements execution logic
• Handles authentication via credentials

Credentials: Authentication definitions that nodes reference:

• Define required fields (API keys, tokens, etc.)
• Handle authentication headers
• Support multiple auth methods

Load Options Methods: Enable dynamic dropdowns that fetch data from APIs:

• getPhacets() - Loads available phacets
• getSessions() - Loads sessions for selected phacet
• getColumns() - Loads columns for selected phacet

Development Commands

• npm run build - Build TypeScript and copy assets
• npm run dev - Start development mode with watch compilation
• npm run lint - Run ESLint checks
• npm run lintfix - Auto-fix ESLint errors
• npm run format - Format code with Prettier

Developing New Features

1. Adding New Operations

To add a new operation to the Phacet node:

1. Update the node definition in /nodes/Phacet/Phacet.node.ts:

   // Add to the operations array
   {
     name: 'Your Operation',
     value: 'yourOperation',
     description: 'Description of what it does',
     action: 'Action verb for the operation',
   }

2. Add UI parameters for the operation:

   // Add parameter fields with displayOptions
   {
     displayName: 'Parameter Name',
     name: 'parameterName',
     type: 'string',
     displayOptions: {
       show: {
         resource: ['row'],
         operation: ['yourOperation'],
       },
     },
     // ... other parameter config
   }

3. Implement the logic in the execute() method:

   if (resource === 'row' && operation === 'yourOperation') {
     // Your implementation here
   }

2. Adding Dynamic Dropdowns

For dropdowns that load data from APIs:

1. Add loadOptionsMethod to parameter definition:

   {
     type: 'options',
     typeOptions: {
       loadOptionsMethod: 'getYourOptions',
       loadOptionsDependsOn: ['otherParameter'], // optional
     },
   }

2. Implement the method in the methods.loadOptions object:

   async getYourOptions(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]> {
     const response = await this.helpers.httpRequestWithAuthentication.call(
       this, 'phacetApi', { /* request options */ }
     );
     return response.map(item => ({
       name: item.displayName,
       value: item.id,
     }));
   }

3. Adding New Nodes

To create a completely new node:

1. Create node directory: /nodes/YourNode/
2. Create files:
   • YourNode.node.ts - Main implementation
   • YourNode.node.json - Metadata (optional, can be inline)
   • yournode.svg - Icon file
3. Follow the existing patterns from Phacet node
4. Update package.json to include the new node

4. Adding Credentials

For new authentication methods:

1. Create credential file: /credentials/YourApi.credentials.ts
2. Define the credential class:

   export class YourApiCredentials implements ICredentialType {
     name = 'yourApi';
     displayName = 'Your API';
     properties: INodeProperties[] = [
       {
         displayName: 'API Key',
         name: 'apiKey',
         type: 'string',
         typeOptions: { password: true },
         default: '',
       },
     ];
   }

Testing

1. Build the project: npm run build
2. Run linting: npm run lint
3. Test in n8n: Start n8n and test your workflows
4. Check the console: Monitor for errors in both terminal and browser console

API References

• n8n Node Development
• Phacet API Documentation
• n8n Community Nodes

License

MIT