n8n-nodes-clientify 0.2.4 → 0.2.6

package/README.md

@@ -3,24 +3,14 @@
 [![npm version](https://badge.fury.io/js/n8n-nodes-clientify.svg)](https://www.npmjs.com/package/n8n-nodes-clientify)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Connect n8n to Clientify CRM using the Model Context Protocol. Access contacts, companies, deals, tasks, and more through simple workflow nodes.
+Connect n8n to Clientify CRM via the Clientify REST API using API keys (`Authorization: Token <apiKey>`).
 
-## Table of Contents
+This package stays aligned with the official action catalog by generating actions/fields from the same connector spec used elsewhere (bundled inside this package under `appmixer/clientify/crm/`).
 
-- [Installation](#installation)
-- [Prerequisites](#prerequisites)
-- [Configuration](#configuration)
-- [Available Operations](#available-operations)
-- [Trigger Events](#trigger-events)
-- [Usage Examples](#usage-examples)
-- [Troubleshooting](#troubleshooting)
-- [Support](#support)
-- [License](#license)
+Under the hood, requests are executed via `@clientify/api-client`.
 
 ## Installation
 
-Start with the GUI method - it's the easiest.
-
 ### In n8n (GUI)
 
 1. Go to **Settings** → **Community Nodes**
@@ -39,7 +29,7 @@ npm install n8n-nodes-clientify
 
 ### Docker
 
-⚠️ Don't forget to persist the nodes directory, or you'll lose the node on restart:
+Persist the nodes directory, or you’ll lose the node on restart:
 
 ```yaml
 volumes:
@@ -56,356 +46,59 @@ environment:
 ## Prerequisites
 
 You'll need:
-- n8n 0.180.0+
-- Node.js 20.15+
-- Active Clientify CRM account
-- JWT token from Clientify MCP server
+- n8n 2.x
+- Node.js 20+
+- A Clientify API key
 
 ## Configuration
 
-### Step 1: Obtain Your Clientify MCP Token
-
-1. Log into your Clientify account
-2. Navigate to API settings or contact your Clientify administrator
-3. Generate or copy your MCP authentication token (JWT format)
-
-### Step 2: Add Credentials in n8n
-
 1. In n8n, go to **Credentials** → **New**
-2. Search for **"Clientify MCP API"**
-3. Enter your **Authentication Token** (JWT)
+2. Search for **"Clientify API"**
+3. Enter your **API Key**
 4. Click **Save**
 
-### Step 3: Use the Node
-
-1. In your workflow, click **+** to add a node
-2. Search for **"Clientify"**
-3. Select the **Clientify** node
-4. Choose your saved credentials
-5. Select an operation from the dropdown
-6. Configure the parameters for your operation
-
-## Available Operations
-
-26 operations available from the Clientify MCP API:
-
-### 📊 Companies
-- **List Companies** - Browse all companies with pagination
-- **Get Company** - Fetch full company details by ID
-- **Create Company** - Add a new company to your CRM
-- **Update Company** - Modify existing company info
-- **Delete Company** - Remove a company
-- **Search Companies** - Find companies by name or criteria
-
-### 👥 Contacts
-- **List Contacts** - View all contacts or search for specific ones
-- **Get Contact** - Look up a contact's information by ID
-- **Create Contact** - Add someone new to your CRM
-- **Update Contact** - Change contact details
-- **Delete Contact** - Remove a contact
-
-### 💼 Deals
-- **List Deals** - See all deals with filters and pagination
-- **List Deals By Stage** - Show deals in a specific pipeline stage
-- **Get Deal** - Pull complete deal data by ID
-- **Create Deal** - Start tracking a new opportunity
-- **Update Deal** - Modify deal information
-- **Delete Deal** - Remove a deal
-- **Mark Deal Won** - Close a deal as won
-- **Mark Deal Lost** - Mark a deal as lost
-
-### ✅ Tasks
-- **List Tasks** - View all tasks with pagination
-- **Get Task** - Retrieve task details by ID
-- **Create Task** - Add a new activity or to-do
-- **List Activity Types** - See available task categories
-
-### ⚙️ Configuration & Utilities
-- **List Pipelines** - Get your sales pipeline configurations
-- **Get Current User** - Check authenticated user details
-- **Get Current Time** - Grab current timestamp with timezone
-
-## Trigger Events
-
-**NEW in v0.2.0!** Triggers are way better than polling. The Clientify Trigger node enables automatic workflow execution when events occur in Clientify CRM. With 16 event types covering contacts, companies, deals, and tasks, you can automate workflows instantly when things happen in your CRM.
-
-### How triggers work
-
-Add a Clientify Trigger node, pick an event (like "Contact Created"), and activate your workflow. You'll get a unique webhook URL. Configure that URL in Clientify's webhook settings, and boom - your workflow runs automatically whenever that event fires.
-
-### 16 Available Triggers
-
-| Event | Trigger Name | When It Fires | Common Use Cases |
-|-------|--------------|---------------|------------------|
-| 👥 **Contacts** | | | |
-| | Contact Created | New contact added | Welcome email, create follow-up task, add to CRM |
-| | Contact Updated | Contact details changed | Sync to other systems, log changes, update records |
-| | Contact Deleted | Contact removed | Archive data, remove from email lists, cleanup |
-| 📊 **Companies** | | | |
-| | Company Created | New company added | Research company, assign account manager, notify team |
-| | Company Updated | Company details changed | Update external systems, track changes |
-| | Company Deleted | Company removed | Clean up related data, archive records |
-| 💼 **Deals** | | | |
-| | Deal Created | New deal/opportunity created | Notify sales team, create tasks, log in analytics |
-| | Deal Updated | Deal details changed | Track value changes, update forecasts, log activity |
-| | Deal Won | Deal closed successfully | Send celebration, create invoice, start onboarding |
-| | Deal Lost | Deal closed unsuccessfully | Add to nurture campaign, analyze loss reason |
-| | Deal Stage Changed | Deal moved to different stage | Stage-specific actions (send pricing, generate contract) |
-| | Deal Deleted | Deal removed | Log deletion, archive data |
-| ✅ **Tasks** | | | |
-| | Task Created | New task added | Add to calendar, notify assignee, sync to project tools |
-| | Task Completed | Task marked complete | Log activity, update metrics, trigger next steps |
-| | Task Due Soon | Task approaching due date | Send reminder to assignee |
-| | Task Overdue | Task past due date | Escalate to manager, send urgent notification |
-
-### Setup Instructions
-
-**In n8n:**
-1. Add "Clientify Trigger" node to your workflow
-2. Select the event from the dropdown
-3. Choose your Clientify MCP credentials
-4. Save and **activate** the workflow (toggle ON)
-5. Click the trigger node → Expand "Webhook URLs"
-6. Switch to "Production URL" tab
-7. Copy the webhook URL
-
-**In Clientify:**
-1. Go to Settings → Webhooks
-2. Click "Add Webhook"
-3. Select the matching event (e.g., "contact.created")
-4. Paste your n8n webhook URL
-5. Set status to "Active"
-6. Save
-
-**Test It:**
-Create a contact, deal, or task in Clientify → Check n8n executions → Your workflow should have run!
-
-### Data You'll Receive
-
-Webhook data is automatically flattened for easy access in your workflows. Event payloads look like this:
-
-**Contact Events** (`contact.created`, `contact.updated`, `contact.deleted`)
-```json
-{
-  "event": "contact.created",
-  "timestamp": "2025-10-02T15:30:00Z",
-  "contact_id": 12345,
-  "first_name": "John",
-  "last_name": "Doe",
-  "email": "john.doe@example.com",
-  "phone": "+1234567890",
-  "company_id": 456,
-  "company_name": "Acme Corp",
-  "changes": { /* only for .updated events */ }
-}
-```
-Access with: `{{$json.first_name}}`, `{{$json.email}}`, `{{$json.company_name}}`
-
-**Company Events** (`company.created`, `company.updated`, `company.deleted`)
-```json
-{
-  "event": "company.created",
-  "timestamp": "2025-10-02T18:00:00Z",
-  "company_id": 999,
-  "name": "Tech Startup Inc",
-  "domain": "techstartup.com",
-  "industry": "Technology",
-  "size": "50-100",
-  "country": "USA"
-}
-```
-Access with: `{{$json.name}}`, `{{$json.domain}}`, `{{$json.industry}}`
-
-**Deal Events** (`deal.created`, `deal.updated`, `deal.won`, `deal.lost`, `deal.stage_changed`, `deal.deleted`)
-```json
-{
-  "event": "deal.won",
-  "timestamp": "2025-10-02T23:00:00Z",
-  "deal_id": 98765,
-  "title": "Enterprise License Sale",
-  "value": 60000,
-  "currency": "USD",
-  "contact_id": 12345,
-  "contact_name": "John Doe",
-  "company_id": 999,
-  "company_name": "Tech Startup Inc",
-  "stage_name": "Won",
-  "won_at": "2025-10-02T23:00:00Z"
-}
-```
-Access with: `{{$json.title}}`, `{{$json.value}}`, `{{$json.contact_name}}`
-
-**Task Events** (`task.created`, `task.completed`, `task.due_soon`, `task.overdue`)
-```json
-{
-  "event": "task.created",
-  "timestamp": "2025-10-03T03:00:00Z",
-  "task_id": 5555,
-  "title": "Follow up with John Doe",
-  "description": "Discuss pricing options",
-  "type": "call",
-  "contact_id": 12345,
-  "contact_name": "John Doe",
-  "deal_id": 98765,
-  "assigned_to_name": "Sales Rep",
-  "due_date": "2025-10-05"
-}
-```
-Access with: `{{$json.title}}`, `{{$json.contact_name}}`, `{{$json.due_date}}`
-
-### Important Notes
-
-- Event names are case-sensitive - use `contact.created`, not `Contact.Created`
-- Each workflow gets a unique webhook URL - you'll need to update Clientify if you recreate the workflow
-- ⚠️ **Common mistake:** Workflows must be active to receive webhooks - toggle that switch on!
-- All payloads include a `_raw` field with the original data if you need it
-- Update events show what changed in the `changes` object (old vs new values)
-- 💡 **Tip:** Session IDs expire after each request. Don't try to reuse them across workflow runs.
-
-## Usage Examples
-
-We recommend starting with List Contacts to verify your setup works.
-
-### Example 1: List All Contacts
-
-Retrieve a paginated list of all contacts in your CRM.
-
-**Configuration:**
-- **Operation:** `List Contacts`
-- **Parameters:** Leave empty for all contacts, or add filters
-
-**Output:** Array of contact objects with names, emails, phone numbers, and IDs.
-
-```json
-[
-  {
-    "id": 123,
-    "first_name": "John",
-    "last_name": "Doe",
-    "email": "john.doe@example.com",
-    "phone": "+1234567890",
-    "company_id": 456
-  }
-]
-```
-
----
-
-### Example 2: Auto-Send Welcome Email (Using Trigger)
-
-**NEW in v0.2.0!**
-
-Automatically send a welcome email when a new contact is created.
-
-**Workflow:**
-1. **Clientify Trigger**
-   - Event: `Contact Created`
+## Nodes
 
-2. **Send Email**
-   - To: `{{$json.email}}`
-   - Subject: `Welcome {{$json.first_name}}!`
-   - Body: Welcome message
+### Clientify (action node)
 
-3. **Create Task**
-   - Title: `Follow up with {{$json.first_name}} {{$json.last_name}}`
-   - Contact ID: `{{$json.contact_id}}`
-   - Due: 3 days from now
+1. Add a node and search for **Clientify**.
+2. Pick an **Action**.
+3. Fill fields directly or map them from previous nodes using expressions.
 
-**Result:** When someone creates a contact "Jane Smith" in Clientify:
-- Jane automatically receives welcome email
-- Follow-up task is created for sales team
-- All happens instantly without manual intervention
+### Clientify Trigger (webhook helper)
 
----
+Use this when you want a Clientify-branded trigger in the workflow. Under the hood it behaves like an n8n webhook:
 
-### Example 3: Deal Won Notification (Using Trigger)
+- Use **Test URL** when executing on the canvas.
+- Use **Production URL** for always-on external calls (runs show up in **Executions**).
+- The trigger verifies the incoming payload `event` matches the selected event type.
 
-**NEW in v0.2.0!**
+For payload formats and examples, see `TRIGGERS_REFERENCE.md`.
 
-Notify your team instantly when a deal closes.
-
-**Workflow:**
-1. **Clientify Trigger**
-   - Event: `Deal Won`
+## Available Operations
 
-2. **Slack** (or Email)
-   - Message: `🎉 Deal Won! {{$json.title}} - ${{$json.value}} - {{$json.contact_name}}`
-   - Channel: `#sales-wins`
+Operations are generated from the bundled catalog (currently 81 actions).
 
-3. **Clientify** (Action Node)
-   - Operation: `Create Task`
-   - Title: `Onboard {{$json.contact_name}}`
-   - Deal ID: `{{$json.deal_id}}`
+## Mapping (inputs from earlier steps)
 
-**Result:** When a deal is marked as won:
-- Team gets instant Slack notification
-- Onboarding task is automatically created
-- No manual steps required
+Mapping is field-based:
 
----
+- Use the field’s **+** button (variable picker), or
+- Toggle **=** and use expressions like `{{$node["Create Contact"].json.id}}`.
 
 ## Troubleshooting
 
-### Node not showing up?
-
-Restart n8n first. Seriously - it won't appear until you do a full restart.
-
-Still nothing? Clear your browser cache (Ctrl+Shift+Del) and search for "Clientify" in the node panel. Not the package name, just "Clientify".
-
-Check Settings → Community Nodes to confirm it installed. If it's there but still not showing up, something's cached - try a hard refresh (Ctrl+F5).
-
-### Getting auth errors?
-
-Your token's probably expired or invalid. Double-check it in your Clientify settings, or generate a fresh one. Happens to everyone.
-
-Make sure you're using the MCP token, not a regular API key - they're different things. The MCP token starts with your account identifier.
-
-### Missing parameter errors?
-
-Look for the red asterisk (*) next to field names - those are required.
-
-Some operations need IDs from previous steps. Run a Get operation first to grab the ID, then pass it to Update or Delete. You'll save yourself a headache. Example: Get Contact → use `{{$json.id}}` in Update Contact.
-
-### Empty results?
-
-Your token might not have permission to access that data. Check your Clientify user permissions first.
-
-Pro tip: Try listing without filters to confirm basic access works. If you see results, then it's your filters that need adjusting.
-
-## Development & Contribution
-
-This is an official Clientify node. Contributions are welcome!
-
-**Repository:** https://github.com/contacteitor/clientify_n8n
-
-**Report Issues:** https://github.com/contacteitor/clientify_n8n/issues
-
-**Documentation:** See the repository for full documentation
+- If the node does not appear after install, restart n8n.
+- If the API returns `401`, verify your API key.
+- If an operation requires an ID, ensure you mapped the correct numeric ID from a previous node.
 
 ## Support
 
-- **Issues & Bugs:** https://github.com/contacteitor/clientify_n8n/issues
-- **Email:** develop@clientify.com
-- **Clientify Documentation:** https://mcp.clientify.com/docs
-
-## Version History
-
-**v0.2.0** (2025-10-02) - Triggers!
-
-Added webhook-based triggers for real-time automation. ~~28 operations~~ 16 trigger events covering contacts, companies, deals, and tasks. Way faster than polling.
-
-**v0.1.0** (2025-10-01) - Initial release
-
-26 operations for managing contacts, companies, deals, and tasks through the MCP API.
+- **Clientify API docs:** https://newapi.clientify.com/
+- **Triggers reference:** [`TRIGGERS_REFERENCE.md`](TRIGGERS_REFERENCE.md)
 
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
 Copyright (c) 2025 Clientify
-
----
-
-**Made with ❤️ by Clientify**
-
-*This is an official Clientify node. n8n is a trademark of its respective owner.*