# 🚀 n8n Integration - Complete Implementation

## 📋 What's Been Created

A complete low-code n8n integration that allows you to fetch data from multiple providers (Zoho, Salesforce, QuickBooks) through a single unified webhook.

### ✅ Created Files

```
src/
├── integrations/
│   └── n8n/
│       ├── client.js          # n8n webhook HTTP client
│       ├── handler.js          # Request orchestration & token management
│       ├── mapper.js           # Module validation & mapping
│       └── README.md           # Module documentation
│
├── services/
│   └── n8nService.js          # Business logic layer
│
├── api/
│   ├── controllers/
│   │   └── n8nController.js   # HTTP request handlers
│   └── routes/
│       └── n8nRoutes.js        # API route definitions
│
└── app.js                      # Updated with n8n routes

docs/
├── N8N_INTEGRATION.md          # Complete integration guide
└── N8N_SETUP_EXAMPLE.md        # Quick start examples

README_N8N.md                   # This file
```

## 🏗️ Architecture

```
┌─────────────┐
│   Client    │
│  (Frontend) │
└──────┬──────┘
       │ HTTP Request
       ↓
┌─────────────────────────────────────────────┐
│           Backend API                        │
│  ┌────────────────────────────────────┐    │
│  │  GET /api/v1/n8n/zoho/crm/leads    │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │      n8nController                  │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │      n8nService                     │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │      N8nHandler                     │    │
│  │   • Gets user's access token       │    │
│  │   • Decrypts token                 │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │      N8nClient                      │    │
│  │   • Calls n8n webhook              │    │
│  └──────────────┬─────────────────────┘    │
└─────────────────┼──────────────────────────┘
                  │
                  │ HTTP POST
                  ↓
┌─────────────────────────────────────────────┐
│              n8n Workflow                    │
│  ┌────────────────────────────────────┐    │
│  │  Webhook (receives request)         │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │  Provider Switch (zoho/salesforce)  │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │  Service Switch (crm/books/etc)     │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │  Module Switch (leads/contacts)     │    │
│  └──────────────┬─────────────────────┘    │
│                 ↓                            │
│  ┌────────────────────────────────────┐    │
│  │  HTTP Request to Provider API       │    │
│  └──────────────┬─────────────────────┘    │
└─────────────────┼──────────────────────────┘
                  │
                  ↓
          ┌───────────────┐
          │   Zoho API    │
          │ Salesforce API│
          │ QuickBooks API│
          └───────────────┘
```

## 🚀 Quick Start

### Step 1: Environment Setup

Add to `.env`:

```env
# n8n Configuration
N8N_WEBHOOK_URL=http://localhost:5678
N8N_WEBHOOK_ID=04e677f5-ec57-4772-bf12-96f2610d4b9c
```

### Step 2: Import n8n Workflow

1. Open n8n at `http://localhost:5678`
2. Import `My_workflow_3 (1).json`
3. Activate the workflow

### Step 3: User Authentication

Users must authenticate with providers first:

```http
GET /api/v1/users/oauth/callback?
    authorization_code=ABC123&
    user_uuid=550e8400-e29b-41d4-a716-446655440000&
    service_name=zoho
```

### Step 4: Fetch Data

```http
GET /api/v1/n8n/zoho/crm/leads?limit=100
Authorization: Bearer <jwt_token>
```

## 📡 API Endpoints

### Get Supported Providers

```http
GET /api/v1/n8n/providers
```

### Generic Endpoint (Any Provider)

```http
GET /api/v1/n8n/data/:provider/:service/:module
```

**Examples:**
```http
GET /api/v1/n8n/data/zoho/crm/leads
GET /api/v1/n8n/data/salesforce/crm/accounts
GET /api/v1/n8n/data/zoho/people/employees
```

### Zoho Shorthand

```http
GET /api/v1/n8n/zoho/:service/:module
```

**Examples:**
```http
GET /api/v1/n8n/zoho/crm/leads
GET /api/v1/n8n/zoho/books/invoices
GET /api/v1/n8n/zoho/people/employees
GET /api/v1/n8n/zoho/projects/portals
```

### Salesforce Shorthand

```http
GET /api/v1/n8n/salesforce/:service/:module
```

**Examples:**
```http
GET /api/v1/n8n/salesforce/crm/leads
GET /api/v1/n8n/salesforce/crm/accounts
GET /api/v1/n8n/salesforce/crm/opportunities
```

## 🎯 Supported Providers & Modules

### Zoho

**CRM:** leads, contacts, accounts, deals, tasks, invoices, purchase_orders, sales_orders

**Books:** organizations, contacts, customers, vendors, accounts, invoices, bills, expenses, purchase_orders, sales_orders

**People:** employees, departments, timesheets, leaves, attendence, attendence_entries, attendence_report, leave_tracker, leaves_data, goals_data, performance_data

**Projects:** portals, projects, tasks, all_tasks, tasklists, all_tasklists, issues, phases

### Salesforce

**CRM:** leads, accounts, tasks, opportunities, events, reports

## 📝 Usage Examples

### JavaScript/Node.js

```javascript
const axios = require('axios');

const API_URL = 'http://localhost:3000/api/v1';
const token = 'your_jwt_token';

// Fetch Zoho Leads
async function getZohoLeads() {
  const response = await axios.get(
    `${API_URL}/n8n/zoho/crm/leads?limit=100`,
    { headers: { Authorization: `Bearer ${token}` }}
  );
  return response.data;
}

// Fetch Salesforce Accounts
async function getSalesforceAccounts() {
  const response = await axios.get(
    `${API_URL}/n8n/salesforce/crm/accounts?limit=50`,
    { headers: { Authorization: `Bearer ${token}` }}
  );
  return response.data;
}

// Fetch multiple sources
async function getDashboardData() {
  const [leads, employees, opportunities] = await Promise.all([
    axios.get(`${API_URL}/n8n/zoho/crm/leads`, 
      { headers: { Authorization: `Bearer ${token}` }}),
    axios.get(`${API_URL}/n8n/zoho/people/employees`, 
      { headers: { Authorization: `Bearer ${token}` }}),
    axios.get(`${API_URL}/n8n/salesforce/crm/opportunities`, 
      { headers: { Authorization: `Bearer ${token}` }})
  ]);

  return {
    leads: leads.data,
    employees: employees.data,
    opportunities: opportunities.data
  };
}
```

### cURL

```bash
# Get JWT token
TOKEN="your_jwt_token"

# Fetch Zoho CRM Leads
curl -X GET "http://localhost:3000/api/v1/n8n/zoho/crm/leads?limit=100" \
  -H "Authorization: Bearer $TOKEN"

# Fetch Salesforce Accounts
curl -X GET "http://localhost:3000/api/v1/n8n/salesforce/crm/accounts" \
  -H "Authorization: Bearer $TOKEN"

# Get supported providers
curl -X GET "http://localhost:3000/api/v1/n8n/providers" \
  -H "Authorization: Bearer $TOKEN"
```

## 🔄 Response Format

```json
{
  "status": "success",
  "message": "zoho crm leads data fetched successfully",
  "data": {
    "success": true,
    "data": [
      {
        "id": "123",
        "First_Name": "John",
        "Last_Name": "Doe",
        "Email": "john@example.com",
        "Company": "Acme Corp"
      }
    ],
    "count": 1,
    "metadata": {}
  },
  "timestamp": "2025-10-09T12:00:00.000Z"
}
```

## ✨ Key Features

### ✅ Benefits

- **Low-code Approach**: Most logic in visual n8n workflows
- **Single Webhook**: One webhook handles all providers
- **Easy Maintenance**: Add new providers in n8n without backend changes
- **Token Management**: Automatic token retrieval and decryption
- **Error Handling**: Comprehensive error handling and logging
- **Type Safety**: Module validation before API calls
- **Unified API**: Consistent endpoint structure across providers
- **Scalable**: n8n workflows can be scaled horizontally

### 🎨 Design Patterns Used

- **Facade Pattern**: N8nService provides simple interface
- **Strategy Pattern**: Different handlers for each provider
- **Factory Pattern**: N8nHandler creates appropriate clients
- **Repository Pattern**: Token management through repositories

## 🛠️ Development

### Adding a New Provider

1. **Update n8n workflow:**
   ```
   - Add switch case in "Provider Switch"
   - Add service switches
   - Add module switches
   - Add HTTP request nodes
   ```

2. **Update mapper:**
   ```javascript
   // src/integrations/n8n/mapper.js
   static getSupportedModules(provider, service) {
     const modules = {
       newprovider: {
         api: ['resource1', 'resource2']
       }
     };
   }
   ```

3. **Done!** No other backend changes needed.

### Adding a New Module

1. **Update n8n workflow:**
   - Add switch case in appropriate module switch
   - Add HTTP request node

2. **Update mapper:**
   ```javascript
   crm: ['leads', 'contacts', 'new_module']
   ```

## 🧪 Testing

### Manual Testing

1. Authenticate user with provider
2. Get JWT token
3. Call endpoint:
   ```bash
   curl -X GET "http://localhost:3000/api/v1/n8n/zoho/crm/leads" \
     -H "Authorization: Bearer $TOKEN"
   ```

### Integration Testing

```javascript
const request = require('supertest');
const app = require('./src/app');

describe('n8n Integration', () => {
  it('should fetch Zoho leads', async () => {
    const response = await request(app)
      .get('/api/v1/n8n/zoho/crm/leads')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.body.status).toBe('success');
    expect(response.body.data.data).toBeInstanceOf(Array);
  });
});
```

## 📊 Monitoring

All requests are logged with:
- User ID
- Provider
- Service
- Module
- Query parameters
- Execution time
- Errors

Check logs in your logging system.

## 🔒 Security

- ✅ JWT authentication required
- ✅ Tokens encrypted in database
- ✅ Rate limiting applied
- ✅ Module validation prevents unauthorized access
- ✅ No tokens in logs

## 📚 Documentation

- [`docs/N8N_INTEGRATION.md`](docs/N8N_INTEGRATION.md) - Complete integration guide
- [`docs/N8N_SETUP_EXAMPLE.md`](docs/N8N_SETUP_EXAMPLE.md) - Quick start examples
- [`docs/SALESFORCE_PAGINATION.md`](docs/SALESFORCE_PAGINATION.md) - Salesforce pagination guide
- [`src/integrations/n8n/README.md`](src/integrations/n8n/README.md) - Module documentation

## 🐛 Troubleshooting

### "n8n workflow execution failed"
- Check if n8n is running
- Verify webhook URL in .env
- Check n8n logs

### "Authentication not found"
- User must authenticate via OAuth first
- Check if tokens are in database

### "Unsupported combination"
- Check `/api/v1/n8n/providers` for supported modules
- Verify spelling of provider/service/module

## 🎉 Success!

You now have a complete n8n integration that:
- ✅ Supports multiple providers (Zoho, Salesforce)
- ✅ Uses a single webhook endpoint
- ✅ Requires minimal backend code
- ✅ Is easy to extend with new providers
- ✅ Includes comprehensive documentation
- ✅ Has proper error handling
- ✅ Manages tokens automatically

## 📞 Next Steps

1. Import the n8n workflow
2. Test with Zoho CRM
3. Test with Salesforce
4. Add to your dashboard/UI
5. Monitor logs for issues
6. Add more providers as needed

Happy coding! 🚀