n8n-nodes-zoho-desk 1.0.0

package/README.md

@@ -0,0 +1,339 @@
+# n8n-nodes-zoho-desk-extended
+
+Production-ready n8n community node for integrating with [Zoho Desk](https://www.zoho.com/desk/) API. Manage support tickets, contacts, and accounts with comprehensive field support, dynamic resource loading, and automatic contact creation.
+
+[![npm version](https://badge.fury.io/js/n8n-nodes-zoho-desk-extended.svg)](https://www.npmjs.com/package/n8n-nodes-zoho-desk-extended)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Full CRUD Operations**: Create, Read, Update, Delete for Tickets, Contacts, and Accounts
+- **Dynamic Dropdowns**: Department & Team selection auto-populated from your Zoho Desk account
+- **Automatic Contact Creation**: Provide email/name and contacts are auto-created or matched
+- **Pagination Support**: "Return All" toggle to fetch all records automatically
+- **Comprehensive Field Support**: All fields including custom fields, priority, due dates, and more
+- **OAuth2 Authentication**: Secure authentication with support for all Zoho data centers
+- **Type-Safe & Validated**: Full TypeScript implementation with input validation
+- **Fully Tested**: 17 integration tests covering all operations
+
+## Supported Operations
+
+| Resource | Operations |
+|----------|------------|
+| **Ticket** | Create, Get, List, Update, Delete, Add Comment, List Threads |
+| **Contact** | Create, Get, List, Update, Delete |
+| **Account** | Create, Get, List, Update, Delete |
+
+## Installation
+
+### Community Node (Recommended)
+
+1. Go to **Settings** > **Community Nodes** in n8n
+2. Search for `n8n-nodes-zoho-desk-extended`
+3. Click **Install**
+
+### Manual Installation
+
+```bash
+npm install n8n-nodes-zoho-desk-extended
+```
+
+## Setup
+
+### 1. Create Zoho Desk OAuth2 Client
+
+1. Go to [Zoho API Console](https://api-console.zoho.com/)
+2. Click on "Add Client"
+3. Choose "Server-based Applications"
+4. Enter the following details:
+   - **Client Name**: n8n Integration
+   - **Homepage URL**: Your n8n instance URL
+   - **Authorized Redirect URIs**: `https://your-n8n-instance.com/rest/oauth2-credential/callback`
+5. Click "Create"
+6. Note down your **Client ID** and **Client Secret**
+
+### 2. Get Organization ID
+
+1. Login to your Zoho Desk account
+2. Go to **Setup** > **Developer Space** > **API**
+3. Copy your **Organization ID**
+
+### 3. Configure Credentials in n8n
+
+1. In n8n, go to **Credentials** > **New**
+2. Select **Zoho Desk OAuth2 API**
+3. Enter:
+   - **Client ID**: From step 1
+   - **Client Secret**: From step 1
+   - **Organization ID**: From step 2
+   - **Data Center**: Select your Zoho data center
+4. Click **Connect** and authorize the application
+
+## Operations
+
+### Ticket Operations
+
+#### Create Ticket
+
+Creates a new support ticket with automatic contact creation/matching.
+
+**Required Fields:**
+- **Department**: Select from dropdown (auto-populated)
+- **Subject**: Ticket subject line
+
+**Primary Fields:**
+- **Priority**: Low, Medium, or High (default: Medium)
+- **Classification**: Question, Problem, Request, Others (default: Question)
+- **Due Date**: Resolution deadline
+- **Description**: Detailed ticket description
+- **Team**: Select from department's teams (dropdown)
+
+**Contact** (optional):
+- **Email** OR **Last Name** (at least one required if providing contact)
+- First Name, Phone (optional)
+- If email exists, existing contact is used; otherwise new contact is created
+
+**Additional Fields:**
+- Account ID, Assignee ID, Category, Channel, Custom Fields, Email, Language, Phone, Product ID, Resolution, Secondary Contacts, Status, Sub Category
+
+#### Get Ticket
+
+Retrieves a single ticket by ID.
+
+#### List Tickets
+
+Lists all tickets with optional filters.
+- **Return All**: Toggle to fetch all tickets (with automatic pagination)
+- **Limit**: Maximum number of results (when Return All is off)
+- **Filters**: Department ID, Assignee ID, Status
+
+#### Update Ticket
+
+Updates an existing ticket. All fields are optional.
+
+#### Delete Ticket
+
+Moves a ticket to trash.
+
+#### Add Comment
+
+Adds a comment to a ticket.
+- **Content**: Comment text
+- **Is Public**: Whether visible to customers or internal only
+
+#### List Threads
+
+Lists all conversations/threads on a ticket.
+
+### Contact Operations
+
+#### Create Contact
+
+**Required Fields:**
+- **Last Name**
+- **Email**
+
+**Additional Fields:**
+- First Name, Phone, Mobile, Account ID, Twitter, Facebook, Type, Description, Custom Fields
+
+#### Get / List / Update / Delete Contact
+
+Standard CRUD operations with pagination support for List.
+
+### Account Operations
+
+#### Create Account
+
+**Required Fields:**
+- **Account Name**
+
+**Additional Fields:**
+- Website, Phone, Fax, Industry, Description, Code, City, Country, State, Street, Zip, Custom Fields
+
+#### Get / List / Update / Delete Account
+
+Standard CRUD operations with pagination support for List.
+
+## Usage Examples
+
+### Create Ticket with Contact Auto-Creation
+
+```json
+{
+  "departmentId": "1892000000006907",
+  "subject": "Order processing delay",
+  "contact": {
+    "email": "carol@zylker.com",
+    "lastName": "Carol",
+    "firstName": "Lucas",
+    "phone": "1 888 900 9646"
+  },
+  "description": "Customer experiencing delays in order processing",
+  "dueDate": "2025-12-01T10:00:00.000Z",
+  "priority": "High",
+  "classification": "Problem",
+  "teamId": "8920000000069071"
+}
+```
+
+### Create Contact
+
+```json
+{
+  "lastName": "Smith",
+  "email": "john.smith@example.com",
+  "firstName": "John",
+  "phone": "+1-555-123-4567",
+  "description": "VIP Customer"
+}
+```
+
+### Create Account
+
+```json
+{
+  "accountName": "Acme Corporation",
+  "website": "https://acme.example.com",
+  "industry": "Technology",
+  "phone": "+1-555-000-0000",
+  "city": "San Francisco",
+  "country": "USA"
+}
+```
+
+### List All Tickets with Filters
+
+```json
+{
+  "returnAll": true,
+  "filters": {
+    "status": "Open",
+    "departmentId": "1892000000006907"
+  }
+}
+```
+
+## Field Details
+
+### Custom Fields (cf)
+
+Pass custom fields as a JSON object:
+
+```json
+{
+  "cf": {
+    "cf_fieldname": "value",
+    "cf_priority_level": "urgent",
+    "cf_product_version": "2.0.1"
+  }
+}
+```
+
+### Secondary Contacts
+
+Provide multiple contact IDs as comma-separated values:
+
+```
+"secondaryContacts": "1892000000042038, 1892000000042042, 1892000000042056"
+```
+
+## Validation & Error Handling
+
+The node includes comprehensive validation:
+
+- **Contact Validation**: Ensures either email or lastName is provided
+- **ID Validation**: Validates IDs are numeric with proper length
+- **JSON Validation**: Safe parsing of custom fields with detailed error messages
+- **Email Validation**: RFC 5322 compliant email validation
+- **Clear Error Messages**: User-friendly error messages with actionable guidance
+
+## API Rate Limits
+
+Zoho Desk API has the following rate limits:
+- 10 requests per second per organization
+- 5000 API calls per day
+
+The node detects rate limiting (HTTP 429) and provides clear error messages.
+
+## Supported Zoho Data Centers
+
+- zoho.com (US)
+- zoho.com.au (Australia)
+- zoho.com.cn (China)
+- zoho.eu (EU)
+- zoho.in (India)
+- zoho.jp (Japan)
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/ron137/zoho-desk-n8n-integration.git
+
+# Install dependencies
+npm install
+
+# Build the node
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Run linting
+npm run lint
+
+# Run tests
+npm run test:integration
+```
+
+### Testing
+
+The project includes comprehensive integration tests that run against the real Zoho Desk API:
+
+```bash
+# Create .env.test with your credentials
+ZOHO_DESK_ACCESS_TOKEN=your_token
+ZOHO_DESK_REFRESH_TOKEN=your_refresh_token
+ZOHO_DESK_CLIENT_ID=your_client_id
+ZOHO_DESK_CLIENT_SECRET=your_client_secret
+ZOHO_DESK_ORG_ID=your_org_id
+ZOHO_DESK_DATACENTER=com
+
+# Run tests
+npm run test:integration
+```
+
+## License
+
+MIT
+
+## Support
+
+If you encounter any issues or have questions:
+1. Check the [Issues](https://github.com/ron137/zoho-desk-n8n-integration/issues) page
+2. Create a new issue if your problem isn't already listed
+
+## Changelog
+
+### 1.0.0 - Major Release
+- **New Resources**: Contact and Account with full CRUD operations
+- **New Ticket Operations**: Get, List, Delete, Add Comment, List Threads
+- **Pagination**: "Return All" toggle with automatic page fetching
+- **Integration Tests**: 17 comprehensive tests for all operations
+- **Lint Compliance**: Full n8n linting rules compliance
+- **Bug Fixes**: Proper error handling with NodeOperationError/ApplicationError
+
+### Previous Versions (as @enthu/n8n-nodes-zoho-desk)
+- 0.3.x - Ticket create/update operations
+- 0.2.x - Dynamic dropdowns, contact auto-creation
+- 0.1.x - Initial release
+
+## Resources
+
+- [Zoho Desk API Documentation](https://desk.zoho.com/DeskAPIDocument)
+- [n8n Documentation](https://docs.n8n.io/)
+- [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/)
+- [GitHub Repository](https://github.com/ron137/zoho-desk-n8n-integration)
+- [npm Package](https://www.npmjs.com/package/n8n-nodes-zoho-desk-extended)

package/dist/credentials/ZohoDeskOAuth2Api.credentials.d.ts

@@ -0,0 +1,11 @@
+import { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class ZohoDeskOAuth2Api implements ICredentialType {
+    name: string;
+    extends: string[];
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    test: ICredentialTestRequest;
+    authenticate: IAuthenticateGeneric;
+}
+//# sourceMappingURL=ZohoDeskOAuth2Api.credentials.d.ts.map

package/dist/credentials/ZohoDeskOAuth2Api.credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZohoDeskOAuth2Api.credentials.d.ts","sourceRoot":"","sources":["../../credentials/ZohoDeskOAuth2Api.credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,eAAe,EAChB,MAAM,cAAc,CAAC;AAEtB,qBAAa,iBAAkB,YAAW,eAAe;IACvD,IAAI,SAAuB;IAC3B,OAAO,WAAiB;IACxB,WAAW,SAA0B;IACrC,gBAAgB,SAA0D;IAC1E,UAAU,EAAE,eAAe,EAAE,CAwF3B;IAEF,IAAI,EAAE,sBAAsB,CAQ1B;IAEF,YAAY,EAAE,oBAAoB,CAOhC;CACH"}

package/dist/credentials/ZohoDeskOAuth2Api.credentials.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZohoDeskOAuth2Api = void 0;
+class ZohoDeskOAuth2Api {
+    constructor() {
+        this.name = 'zohoDeskOAuth2Api';
+        this.extends = ['oAuth2Api'];
+        this.displayName = 'Zoho Desk OAuth2 API';
+        this.documentationUrl = 'https://desk.zoho.com/support/APIDocument#OAuthtoken';
+        this.properties = [
+            {
+                displayName: 'Grant Type',
+                name: 'grantType',
+                type: 'hidden',
+                default: 'authorizationCode',
+            },
+            {
+                displayName: 'Zoho Data Center',
+                name: 'datacenter',
+                type: 'options',
+                options: [
+                    {
+                        name: 'zoho.com (US)',
+                        value: 'com',
+                    },
+                    {
+                        name: 'zoho.com.au (Australia)',
+                        value: 'com.au',
+                    },
+                    {
+                        name: 'zoho.com.cn (China)',
+                        value: 'com.cn',
+                    },
+                    {
+                        name: 'zoho.eu (EU)',
+                        value: 'eu',
+                    },
+                    {
+                        name: 'zoho.in (India)',
+                        value: 'in',
+                    },
+                    {
+                        name: 'zoho.jp (Japan)',
+                        value: 'jp',
+                    },
+                ],
+                default: 'com',
+                description: 'The data center where your Zoho Desk account is hosted',
+            },
+            {
+                displayName: 'Organization ID',
+                name: 'orgId',
+                type: 'string',
+                default: '',
+                required: true,
+                description: 'Your Zoho Desk Organization ID. You can find this in Setup > Developer Space > API.',
+            },
+            {
+                displayName: 'Authorization URL',
+                name: 'authUrl',
+                type: 'hidden',
+                default: '=https://accounts.zoho.{{$self["datacenter"]}}/oauth/v2/auth',
+                required: true,
+            },
+            {
+                displayName: 'Access Token URL',
+                name: 'accessTokenUrl',
+                type: 'hidden',
+                default: '=https://accounts.zoho.{{$self["datacenter"]}}/oauth/v2/token',
+                required: true,
+            },
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'hidden',
+                default: '=https://desk.zoho.{{$self["datacenter"]}}/api/v1',
+            },
+            {
+                displayName: 'Scope',
+                name: 'scope',
+                type: 'hidden',
+                default: 'Desk.tickets.ALL Desk.contacts.ALL Desk.accounts.ALL Desk.basic.READ Desk.settings.READ',
+            },
+            {
+                displayName: 'Auth URI Query Parameters',
+                name: 'authQueryParameters',
+                type: 'hidden',
+                default: 'access_type=offline&prompt=consent',
+            },
+            {
+                displayName: 'Authentication',
+                name: 'authentication',
+                type: 'hidden',
+                default: 'header',
+            },
+        ];
+        this.test = {
+            request: {
+                baseURL: '=https://desk.zoho.{{$credentials["datacenter"]}}/api/v1',
+                url: '/tickets?limit=1',
+                headers: {
+                    orgId: '={{$credentials["orgId"]}}',
+                },
+            },
+        };
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.oauthTokenData.access_token}}',
+                },
+            },
+        };
+    }
+}
+exports.ZohoDeskOAuth2Api = ZohoDeskOAuth2Api;
+// Test comment for pre-commit hook verification
+//# sourceMappingURL=ZohoDeskOAuth2Api.credentials.js.map

package/dist/credentials/ZohoDeskOAuth2Api.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZohoDeskOAuth2Api.credentials.js","sourceRoot":"","sources":["../../credentials/ZohoDeskOAuth2Api.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,iBAAiB;IAA9B;QACE,SAAI,GAAG,mBAAmB,CAAC;QAC3B,YAAO,GAAG,CAAC,WAAW,CAAC,CAAC;QACxB,gBAAW,GAAG,sBAAsB,CAAC;QACrC,qBAAgB,GAAG,sDAAsD,CAAC;QAC1E,eAAU,GAAsB;YAC9B;gBACE,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,mBAAmB;aAC7B;YACD;gBACE,WAAW,EAAE,kBAAkB;gBAC/B,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,eAAe;wBACrB,KAAK,EAAE,KAAK;qBACb;oBACD;wBACE,IAAI,EAAE,yBAAyB;wBAC/B,KAAK,EAAE,QAAQ;qBAChB;oBACD;wBACE,IAAI,EAAE,qBAAqB;wBAC3B,KAAK,EAAE,QAAQ;qBAChB;oBACD;wBACE,IAAI,EAAE,cAAc;wBACpB,KAAK,EAAE,IAAI;qBACZ;oBACD;wBACE,IAAI,EAAE,iBAAiB;wBACvB,KAAK,EAAE,IAAI;qBACZ;oBACD;wBACE,IAAI,EAAE,iBAAiB;wBACvB,KAAK,EAAE,IAAI;qBACZ;iBACF;gBACD,OAAO,EAAE,KAAK;gBACd,WAAW,EAAE,wDAAwD;aACtE;YACD;gBACE,WAAW,EAAE,iBAAiB;gBAC9B,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EACT,qFAAqF;aACxF;YACD;gBACE,WAAW,EAAE,mBAAmB;gBAChC,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,8DAA8D;gBACvE,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,WAAW,EAAE,kBAAkB;gBAC/B,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,+DAA+D;gBACxE,QAAQ,EAAE,IAAI;aACf;YACD;gBACE,WAAW,EAAE,UAAU;gBACvB,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,mDAAmD;aAC7D;YACD;gBACE,WAAW,EAAE,OAAO;gBACpB,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,QAAQ;gBACd,OAAO,EACL,yFAAyF;aAC5F;YACD;gBACE,WAAW,EAAE,2BAA2B;gBACxC,IAAI,EAAE,qBAAqB;gBAC3B,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,oCAAoC;aAC9C;YACD;gBACE,WAAW,EAAE,gBAAgB;gBAC7B,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,QAAQ;aAClB;SACF,CAAC;QAEF,SAAI,GAA2B;YAC7B,OAAO,EAAE;gBACP,OAAO,EAAE,0DAA0D;gBACnE,GAAG,EAAE,kBAAkB;gBACvB,OAAO,EAAE;oBACP,KAAK,EAAE,4BAA4B;iBACpC;aACF;SACF,CAAC;QAEF,iBAAY,GAAyB;YACnC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,aAAa,EAAE,sDAAsD;iBACtE;aACF;SACF,CAAC;IACJ,CAAC;CAAA;AAjHD,8CAiHC;AAED,gDAAgD"}

package/dist/nodes/ZohoDesk/ZohoDesk.node.d.ts

@@ -0,0 +1,20 @@
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription, ILoadOptionsFunctions, INodePropertyOptions } from 'n8n-workflow';
+export declare class ZohoDesk implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            /**
+             * Load all departments from Zoho Desk
+             * @returns Array of department options for dropdown
+             */
+            getDepartments(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            /**
+             * Load teams for a specific department from Zoho Desk
+             * @returns Array of team options for dropdown, or empty array if department not selected
+             */
+            getTeams(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}
+//# sourceMappingURL=ZohoDesk.node.d.ts.map

package/dist/nodes/ZohoDesk/ZohoDesk.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZohoDesk.node.d.ts","sourceRoot":"","sources":["../../../nodes/ZohoDesk/ZohoDesk.node.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,oBAAoB,EAEpB,qBAAqB,EACrB,oBAAoB,EAErB,MAAM,cAAc,CAAC;AAsmBtB,qBAAa,QAAS,YAAW,SAAS;IACxC,WAAW,EAAE,oBAAoB,CAk5C/B;IAEF,OAAO;;YAEH;;;eAGG;iCACwB,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;YAiDlF;;;eAGG;2BACkB,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;;MAqE9E;IAEI,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;CAqvBxE"}