n8n-nodes-pachca 1.0.27 → 2.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 n8n-nodes-pachca
+Copyright (c) 2025 Pachca
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,346 +1,283 @@
-# n8n Pachca Node
+# n8n-nodes-pachca
 
-Custom n8n node for integration with the Pachca messenger API. Automate work with users, messages, chats, files, and other Pachca resources.
+Community node for [n8n](https://n8n.io/) to interact with the [Pachca API](https://dev.pachca.com/).
 
-## Table of Contents
-
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Resources and Operations](#resources-and-operations)
-- [Usage Examples](#usage-examples)
-- [Troubleshooting](#troubleshooting)
-- [Support](#support)
+Auto-generated from the [OpenAPI spec](https://github.com/pachca/openapi) — always in sync with the latest API.
 
 ## Installation
 
-### Automatic installation
+In your n8n instance:
 
-1. Download the node archive:
-```bash
-wget https://github.com/pachca/n8n-nodes-pachca/releases/latest/download/pachca-node-v2.2.2.tar.gz
-```
+1. Go to **Settings > Community Nodes**
+2. Enter `n8n-nodes-pachca`
+3. Click **Install**
 
-2. Extract to the custom nodes directory:
-```bash
-tar -xzf pachca-node-v2.2.2.tar.gz -C /path/to/n8n/custom-nodes/
-```
+Or install via CLI:
 
-3. Restart n8n:
 ```bash
-docker restart n8n-container
+npm install n8n-nodes-pachca
 ```
 
-### Manual installation
+Or install from archive (Docker, custom n8n images):
 
-1. Clone the repository:
 ```bash
-git clone https://github.com/pachca/n8n-nodes-pachca.git
-cd n8n-nodes-pachca
-```
+# Download from GitHub Releases
+# Find the latest n8n-nodes-pachca.tgz at:
+# https://github.com/pachca/openapi/releases?q=n8n
+wget https://github.com/pachca/openapi/releases/download/n8n-v2.0.1/n8n-nodes-pachca.tgz
 
-2. Install dependencies:
-```bash
-npm install
-```
+# Via npm (recommended)
+cd ~/.n8n/nodes && npm install ./n8n-nodes-pachca.tgz
 
-3. Build the project:
-```bash
-npm run build
-```
+# Or extract directly (no npm needed)
+tar -xzf n8n-nodes-pachca.tgz -C ~/.n8n/nodes/
 
-4. Restart n8n:
-```bash
-docker restart n8n-container
+# Restart n8n
 ```
 
-## Configuration
+## Nodes
+
+### Pachca
 
-### 1. Creating credentials
+Main node for interacting with the Pachca API. Supports 18 resources and 65+ operations:
 
-1. In n8n go to **Settings** → **Credentials**
-2. Click **Add Credential**
-3. Find **Pachca API** in the list
-4. Fill in the fields:
-   - **Base URL**: `https://api.pachca.com/api/shared/v1`
-   - **Access Token**: Your Pachca API access token
+| Resource | Operations |
+|----------|-----------|
+| Bot | Update, Get Many Events, Remove Events |
+| Chat | Create, Get, Get Many, Update, Archive, Unarchive |
+| Chat Export | Create, Get |
+| Chat Member | Get Many, Create, Delete, Update, Leave, Add/Remove Group Tags |
+| Custom Property | Get |
+| File | Create (S3 two-stage upload) |
+| Form | Create (visual builder, templates, or JSON) |
+| Group Tag | Create, Get, Get Many, Update, Delete, Get Many Users |
+| Link Preview | Create |
+| Message | Create, Get, Get Many, Update, Delete, Pin, Unpin |
+| Profile | Get Info, Get, Update/Delete Avatar, Get/Update/Delete Status |
+| Reaction | Create, Delete, Get Many |
+| Read Member | Get Many |
+| Search | Chats, Messages, Users |
+| Security | Get Many |
+| Task | Create, Get, Get Many, Update, Delete |
+| Thread | Create, Get |
+| User | Create, Get, Get Many, Update, Delete, Update/Delete Avatar, Get/Update/Delete Status |
 
-### 2. Obtaining an access token
+### Pachca Trigger
 
-To get an access token:
+Webhook-based trigger that listens for 16 Pachca event types:
 
-1. Log in to the Pachca web app
-2. Go to **Settings** → **Integrations**
-3. Create a new access token
-4. Copy the token and paste it into the credentials settings
+| Category | Events |
+|----------|--------|
+| Messages | new, updated, deleted |
+| Reactions | new, deleted |
+| Interactive | button pressed, form submitted, link shared |
+| Chat members | added, removed |
+| Users | invited, confirmed, activated, suspended, updated, deleted |
+| Wildcard | all events |
 
-> **Important**: The token must have the required permissions for the operations you plan to perform.
+Automatically registers webhooks via the Bot API when workflow is activated. Deactivation removes the webhook.
 
-## Resources and Operations
+## Credentials
 
-### User
+Create a **Pachca API** credential with:
 
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Get All | Get list of all users | GET |
-| Get By ID | Get user by ID | GET |
-| Create | Create new user | POST |
-| Update | Update user data | PUT |
-| Delete | Delete user | DELETE |
+| Field | Required | Description |
+|-------|----------|-------------|
+| **Base URL** | no | Default: `https://api.pachca.com/api/shared/v1`. Change only for on-premise. |
+| **Access Token** | yes | Bot or personal API token |
+| **Bot ID** | no | For automatic webhook registration in Trigger. Auto-detected from bot tokens. Set explicitly for admin tokens. |
+| **Signing Secret** | no | For HMAC-SHA256 verification of incoming webhooks (`pachca-signature` header) |
+| **Webhook Allowed IPs** | no | Comma-separated IPs allowed to send webhooks. Pachca sends from `37.200.70.177`. Empty = allow all. |
 
-**Update parameters:**
-- First Name, Last Name, Email
-- Nickname, Phone Number
-- Department, Title, Role
-- Suspended (deactivation)
-- List Tags (comma-separated tags)
-- Custom Properties (additional fields)
+**Where to get tokens:**
 
-### Message
+- **Bot token** — Bot settings > API tab
+- **Personal token** — Settings > Automations > API
 
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Send | Send message | POST |
-| Get All By Chat | Get chat messages | GET |
-| Get By ID | Get message by ID | GET |
-| Update | Edit message | PUT |
-| Delete | Delete message | DELETE |
-| Get Read Members | Get list of readers | GET |
+Credentials are tested by calling `GET /oauth/token/info`.
 
-### Chat
+## Key Features
 
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Get All | Get list of chats | GET |
-| Get By ID | Get chat by ID | GET |
-| Create | Create new chat | POST |
-| Update | Update chat | PUT |
-| Archive | Archive chat | PUT |
-| Unarchive | Unarchive chat | PUT |
+### Pagination
+
+All list operations (Get Many) support automatic cursor-based pagination:
+
+- **Return All** = true — fetches all pages automatically
+- **Return All** = false — returns up to **Limit** results (default: 50)
+
+### Simplify
+
+Toggle **Simplify** (on by default) to return only key fields from API responses. Turn off for full response.
+
+- **Message** — id, entity_id, chat_id, content, user_id, created_at
+- **Chat** — id, name, channel, public, members_count, created_at
+- **User** — id, first_name, last_name, nickname, email, role, suspended
+- **Task** — id, content, kind, status, priority, due_at, created_at
+
+### Searchable Dropdowns
+
+Chat ID and User ID fields support search by name — type to find instead of entering numeric IDs.
+
+### Message Buttons
+
+Create messages with interactive buttons via JSON:
+
+```json
+[[{"text": "Approve", "data": "approve"}, {"text": "Reject", "data": "reject"}]]
+```
 
-**Create parameters:**
-- Chat Name
-- Channel (channel/direct switch)
-- Public (public/private switch)
+Button types: **URL** (opens link) and **Data** (sends `button_pressed` webhook event).
 
-### Group Tag
+### Forms
 
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Get All | Get all tags | GET |
-| Get By ID | Get tag by ID | GET |
-| Create | Create new tag | POST |
-| Update | Update tag | PUT |
-| Delete | Delete tag | DELETE |
-| Add Tags | Add tags to chat | POST |
-| Remove Tag | Remove tag from chat | DELETE |
+Create modal forms with three builder modes:
 
-### File
+- **Visual Builder** — add blocks (text input, select, radio, checkboxes, date/time, file upload)
+- **Templates** — predefined forms (Feedback, Time Off, Survey, Bug Report)
+- **JSON** — paste blocks from the visual playground
 
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Upload | Upload file | POST |
-| Get Upload Params | Get upload parameters | POST |
+Forms require a `trigger_id` from a `button_pressed` webhook event (valid for 3 seconds).
 
-**Supported file sources:**
-- URL (file link)
-- Binary (binary data from previous nodes)
+### Avatar Upload
 
-### Custom Fields
+Upload avatar images for profiles and users via `multipart/form-data`. Uses binary data from a previous node (HTTP Request, Read Binary File). The **Input Binary Field** parameter (default: `data`) specifies which binary property contains the image.
 
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Get Custom Properties | Get list of fields | GET |
+### File Upload
 
-### Task
+Two-stage S3 upload with automatic retry. Sources: **URL** or **Binary Data** from previous workflow nodes.
 
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Create | Create task | POST |
+### AI Tool Use
 
-### Bot
-
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Update | Update bot settings | PUT |
+Both nodes have `usableAsTool: true` — they can be used as tools for AI Agent nodes in n8n.
 
-### Status
+### Error Handling
 
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Get Profile | Get profile | GET |
-| Get Status | Get status | GET |
-| Update Status | Update status | PUT |
-| Delete Status | Delete status | DELETE |
-
-### Thread
-
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Create Thread | Create thread | POST |
-| Get Thread | Get thread | GET |
-
-### Reactions
-
-| Operation | Description | Method |
-|-----------|-------------|--------|
-| Add Reaction | Add reaction | POST |
-| Delete Reaction | Delete reaction | DELETE |
-| Get Reactions | Get reactions | GET |
+- **5xx/429 retry** — exponential backoff with jitter, respects `Retry-After` header (up to 5 attempts)
+- **continueOnFail** — supported on all operations
+
+## v1 Compatibility
+
+Version 2 is fully backward compatible with v1. Existing v1 workflows continue to work without modification.
+
+The node uses the **VersionedNodeType** pattern with `defaultVersion: 2`:
+
+- Existing nodes keep `typeVersion: 1` with v1 UI and parameter names
+- New nodes get `typeVersion: 2` with cleaner naming and new resources
+- A shared router translates v1 names to v2 at runtime
+
+**Renamed resources:** `reactions` → `reaction`, `status` → `profile`, `customFields` → `customProperty`
+
+**Renamed operations:** `send` → `create`, `getById` → `get`, `addReaction` → `create`, etc.
+
+**New v2 resources:** Chat Member, Custom Property, Read Member, Link Preview, Search, Chat Export, Security
+
+To upgrade a v1 node: delete it, add a new Pachca node (defaults to v2), reconfigure with v2 names. API calls are identical.
 
 ## Usage Examples
 
-### 1. Send a message to a chat
+### Send a message
 
-```json
-{
-  "resource": "message",
-  "operation": "send",
-  "chatId": 12345,
-  "content": "Hello! This is an automated message from n8n."
-}
-```
+Set **Resource** = Message, **Operation** = Create:
 
-### 2. Create a chat with settings
+- **Entity ID** — chat ID (use searchable dropdown or enter number)
+- **Content** — message text (supports Markdown)
 
-```json
-{
-  "resource": "chat",
-  "operation": "create",
-  "chatName": "New project",
-  "channel": true,
-  "public": false
-}
-```
+### Send a message with buttons
 
-### 3. Update a user
+Set **Resource** = Message, **Operation** = Create, then in **Additional Fields** add **Buttons**:
 
 ```json
-{
-  "resource": "user",
-  "operation": "update",
-  "userId": 123,
-  "firstName": "John",
-  "lastName": "Doe",
-  "department": "Engineering",
-  "title": "Senior Developer",
-  "role": "user",
-  "listTags": "Backend, Senior",
-  "customProperties": {
-    "property": [
-      {
-        "id": 1678,
-        "value": "New York"
-      }
-    ]
-  }
-}
+[[{"text": "Approve", "data": "approve"}, {"text": "Reject", "data": "reject"}]]
 ```
 
-### 4. Upload a file
+When a user clicks a Data button, the Pachca Trigger node receives a `button_pressed` event with the button's `data` value.
 
-```json
-{
-  "resource": "file",
-  "operation": "upload",
-  "fileSource": "url",
-  "fileUrl": "https://example.com/document.pdf",
-  "fileName": "document.pdf"
-}
-```
+### Upload a file and attach to message
 
-### 5. Workflow: New user notification
+1. **Pachca** (File > Create) — upload file from URL or binary data, get `key` in response
+2. **Pachca** (Message > Create) — send message with the file key in the `files` field
 
-1. **Webhook** – receives new user data
-2. **Pachca: Create User** – creates the user in Pachca
-3. **Pachca: Send Message** – sends a welcome message
-4. **Pachca: Create Chat** – creates a personal chat
+### Search and process results
 
-## Troubleshooting
+Set **Resource** = Search, **Operation** = Get Many Messages:
 
-### "Invalid URL" error
+- **Query** — search text
+- **Return All** = false, **Limit** = 10
 
-**Problem**: API requests fail due to incorrect URL.
+### Open a modal form
 
-**Solution**:
-1. Check Base URL in credentials: `https://api.pachca.com/api/shared/v1`
-2. Ensure the access token is valid
-3. Check token permissions
+1. **Pachca Trigger** — event `Button Pressed` (provides `trigger_id`)
+2. **Pachca** (Form > Create) — set **Title**, **Trigger ID**, choose builder mode
+3. **Pachca Trigger** — event `Form Submitted` (in a separate workflow)
 
-### "Request failed with status code 404"
+### Bot echo workflow
 
-**Problem**: Resource not found.
+1. **Pachca Trigger** — event `New Message`
+2. **IF** — filter: `message.user_id` ≠ bot ID
+3. **Pachca** (Message > Create) — echo the message back
 
-**Solution**:
-1. Verify the resource ID
-2. Ensure the token has access to the resource
-3. Confirm the resource exists
+## Troubleshooting
 
-### "Request failed with status code 400"
+### 401 Unauthorized
 
-**Problem**: Invalid request parameters.
+Token is invalid or expired. Check **Access Token** in Credentials. For bot tokens: Bot settings > API tab. For personal tokens: Settings > Automations > API.
 
-**Solution**:
-1. Check required fields
-2. Verify data format
-3. Check API limits (text length, file size)
+### 403 Forbidden
 
-### Files not uploading
+Token lacks required scopes for this operation. Check available scopes in your token settings. Admin operations (managing users, tags, security log) require admin-level scopes.
 
-**Problem**: Error when uploading files.
+### 429 Too Many Requests
 
-**Solution**:
-1. Check that the file URL is accessible
-2. Ensure the file does not exceed size limits
-3. Check file format (supported types)
+Rate limit exceeded (~4 req/sec for messages, ~50 req/sec for other operations). The node retries automatically with exponential backoff. For bulk operations, add a **Wait** node between steps.
 
-### Node not showing in the list
+### Webhook not received (Trigger)
 
-**Problem**: Custom node does not appear in n8n.
+1. **Bot not in chat** — bot only receives events from chats it's a member of
+2. **Workflow not activated** — click **Activate** in the top right
+3. **Bot ID missing** — set Bot ID in Credentials for auto-registration, or configure webhook URL manually in bot settings
+4. **n8n not reachable** — Pachca can't send webhooks to `localhost`. Use a tunnel (ngrok, Cloudflare Tunnel) or deploy to a server with a public IP
 
-**Solution**:
-1. Ensure files are copied to the correct directory
-2. Restart n8n
-3. Check n8n logs for loading errors
+### Form not opening
 
-## Support
+`trigger_id` from a `button_pressed` event expires in **3 seconds**. Place the Form > Create node immediately after the Trigger, with no Wait nodes or long operations in between.
 
-### Getting help
+### Node not showing in n8n
 
-- **GitHub Issues**: [Create an issue](https://github.com/pachca/n8n-nodes-pachca/issues)
-- **Pachca API documentation**: [api.pachca.com](https://api.pachca.com)
-- **n8n Community**: [community.n8n.io](https://community.n8n.io)
+1. Restart n8n after installing the package
+2. Check n8n logs for loading errors
+3. Verify the package is in the correct directory (`~/.n8n/nodes/` or `~/.n8n/custom/node_modules/`)
 
-### Reporting bugs
+## Support
 
-When reporting a bug please include:
+- **GitHub Issues** — [github.com/pachca/openapi/issues](https://github.com/pachca/openapi/issues)
+- **Pachca API docs** — [dev.pachca.com](https://dev.pachca.com)
+- **n8n Community** — [community.n8n.io](https://community.n8n.io)
 
-1. n8n version
-2. Node version
-3. Problem description
-4. Error logs
-5. Steps to reproduce
+## Development
 
-### Contributing
+This node is auto-generated from the OpenAPI specification:
 
-We welcome contributions:
+```bash
+# Generate node files from OpenAPI
+bun run integrations/n8n/scripts/generate-n8n.ts
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Open a Pull Request
+# Run tests
+cd integrations/n8n && npx vitest run
 
-## License
+# Type check
+cd integrations/n8n && npx tsc --noEmit
 
-MIT License – see the [LICENSE](LICENSE) file for details.
+# Build for distribution
+cd integrations/n8n && npx n8n-node build
 
-## Versions
+# Full CI check (from repo root)
+npx turbo check
+```
 
-### v1.0.0
-- Base functionality
-- Support for all main Pachca API resources
-- File upload
-- User and chat management
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for architecture, local testing, and adding new endpoints.
 
----
+See [docs/CONTRIBUTORS.md](docs/CONTRIBUTORS.md) for project structure and contribution guidelines.
+
+## License
 
-**Made with ❤️ for the n8n and Pachca community**
+MIT

package/dist/credentials/PachcaApi.credentials.d.ts

@@ -1,7 +1,11 @@
-import { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
 export declare class PachcaApi implements ICredentialType {
     name: string;
     displayName: string;
+    icon: {
+        readonly light: "file:pachca.svg";
+        readonly dark: "file:pachca.dark.svg";
+    };
     documentationUrl: string;
     properties: INodeProperties[];
     authenticate: IAuthenticateGeneric;

package/dist/credentials/PachcaApi.credentials.js

@@ -5,53 +5,48 @@ class PachcaApi {
     constructor() {
         this.name = 'pachcaApi';
         this.displayName = 'Pachca API';
-        this.documentationUrl = 'https://crm.pachca.com/dev/getting-started/requests-and-responses/';
+        this.icon = { light: 'file:pachca.svg', dark: 'file:pachca.dark.svg' };
+        this.documentationUrl = 'https://dev.pachca.com/api/authorization';
         this.properties = [
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: 'https://api.pachca.com/api/shared/v1',
+                description: 'Base URL of the Pachca API. Change only for on-premise installations or API proxies.',
+            },
             {
                 displayName: 'Access Token',
                 name: 'accessToken',
                 type: 'string',
                 typeOptions: { password: true },
                 default: '',
-                description: 'Access token for Pachca API. Can be obtained in developer settings.',
             },
             {
-                displayName: 'Base URL',
-                name: 'baseUrl',
-                type: 'string',
-                default: 'https://api.pachca.com/api/shared/v1',
-                description: 'Base URL for Pachca API',
+                displayName: 'Bot ID',
+                name: 'botId',
+                type: 'number',
+                default: 0,
+                description: 'Bot ID for automatic webhook registration (found in bot settings). Leave empty to auto-detect from token. Only needed for Pachca Trigger node.',
+                hint: 'Only required when using a bot token with the Pachca Trigger node',
             },
             {
-                displayName: 'Token Type',
-                name: 'tokenType',
-                type: 'options',
-                options: [
-                    {
-                        name: 'Bot Token',
-                        value: 'bot',
-                        description: 'Bot token - access to core API methods',
-                    },
-                    {
-                        name: 'Admin Token',
-                        value: 'admin',
-                        description: 'Admin token - access to user and tag management',
-                    },
-                    {
-                        name: 'Owner Token',
-                        value: 'owner',
-                        description: 'Owner token - full access including export',
-                    },
-                ],
-                default: 'bot',
-                description: 'Token type determines available API methods',
+                displayName: 'Webhook Signing Secret',
+                name: 'signingSecret',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                description: 'Used to verify incoming webhook requests from Pachca. Found in bot settings under the Webhook section.',
+                hint: 'Only required when using the Pachca Trigger node',
             },
             {
-                displayName: 'User ID',
-                name: 'userId',
-                type: 'number',
+                displayName: 'Webhook Allowed IPs',
+                name: 'webhookAllowedIps',
+                type: 'string',
                 default: '',
-                description: 'User/bot ID that owns the token (optional)',
+                description: 'Comma-separated list of IP addresses allowed to send webhooks. Pachca sends from 37.200.70.177. Leave empty to allow all.',
+                placeholder: '37.200.70.177',
+                hint: 'Only used with the Pachca Trigger node',
             },
         ];
         this.authenticate = {
@@ -65,9 +60,11 @@ class PachcaApi {
         this.test = {
             request: {
                 baseURL: '={{$credentials.baseUrl}}',
-                url: '/profile',
+                url: '/oauth/token/info',
+                method: 'GET',
             },
         };
     }
 }
 exports.PachcaApi = PachcaApi;
+//# sourceMappingURL=PachcaApi.credentials.js.map