n8n-nodes-future-systems-connector/README.md

Exclusive Future Systems GoHighLevel connector for n8n

# Future Systems Connector for n8n

Exclusive Future Systems GoHighLevel connector for n8n workflow automation.

## Features

- **Complete GoHighLevel Integration**: Full support for contacts, tags, notes, courses, workflows, and DND settings
- **Robust Error Handling**: Automatic retries with exponential backoff and fallback endpoints
- **Proxy Support**: Route requests through proxy servers for enhanced security
- **Idempotency**: Prevent duplicate operations with idempotency keys
- **Future-Proof**: Built with TypeScript and comprehensive endpoint fallbacks

## Installation

### Community Nodes (Recommended)

1. In your n8n instance, go to **Settings** → **Community Nodes**
2. Click **Install a community node**
3. Enter: `n8n-nodes-future-systems-connector`
4. Click **Install**

### Docker Installation

If you're running n8n in Docker, you can install the node by copying it to your n8n container:

```bash
# Copy the built node to your n8n container
docker cp dist/ your-n8n-container:/home/node/.n8n/nodes/

# Restart your n8n container
docker restart your-n8n-container
```

## Credentials Setup

1. Create a new credential of type **Future Systems API**
2. Configure the following fields:
   - **Base URL**: `https://rest.gohighlevel.com` (default)
   - **API Key**: Your GoHighLevel Location API key
   - **Use Proxy**: Enable if routing through a proxy server
   - **Proxy Base URL**: Your proxy server URL (only shown when Use Proxy is enabled)

### Getting Your API Key

1. Log into your GoHighLevel account
2. Go to **Settings** → **API Keys**
3. Create a new API key with appropriate permissions
4. Copy the key and paste it into the credentials

## Operations

### Contact Operations

#### Create Contact
Creates a new contact in GoHighLevel.

**Required Fields:**
- Email

**Optional Fields:**
- First Name
- Last Name
- Phone
- Tags (comma-separated)
- Custom Fields (key-value pairs)
- Idempotency Key

**Example:**
```json
{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "tags": "lead,premium",
  "customFields": {
    "source": "website",
    "priority": "high"
  }
}
```

#### Update Contact
Updates an existing contact.

**Required Fields:**
- Contact ID

**Optional Fields:**
- First Name
- Last Name
- Phone
- Tags (comma-separated)
- Custom Fields (key-value pairs)

#### Find by Email
Finds a contact by their email address.

**Required Fields:**
- Email

### Tag Operations

#### Add Tags
Adds tags to a contact.

**Required Fields:**
- Contact ID
- Tag List (comma-separated)

**Example:**
```
Contact ID: contact_123
Tag List: premium,engaged,hot-lead
```

#### Remove Tags
Removes tags from a contact. Automatically tries JSON body first, then falls back to query parameters.

**Required Fields:**
- Contact ID
- Tag List (comma-separated)

### Note Operations

#### Add Note
Adds a note to a contact.

**Required Fields:**
- Contact ID
- Note

**Example:**
```
Contact ID: contact_123
Note: Customer called asking about pricing. Very interested in premium package.
```

### Course Operations

#### Enroll
Enrolls a contact in a course.

**Required Fields:**
- Contact ID
- Course ID

**Optional Fields:**
- Offer ID
- Idempotency Key

#### Unenroll
Unenrolls a contact from a course.

**Required Fields:**
- Contact ID
- Course ID

### Workflow Operations

#### Add to Workflow
Adds a contact to a workflow.

**Required Fields:**
- Contact ID
- Workflow ID
- Idempotency Key

#### Remove from Workflow
Removes a contact from a workflow.

**Required Fields:**
- Contact ID
- Workflow ID

### Do Not Disturb Operations

#### Enable DND
Enables do not disturb for specified channels.

**Required Fields:**
- Contact ID
- Channels (multi-select: SMS, Email, Call, WhatsApp)

#### Disable DND
Disables do not disturb for specified channels.

**Required Fields:**
- Contact ID
- Channels (multi-select: SMS, Email, Call, WhatsApp)

### Raw API Operations

#### Passthrough
Makes a raw API request to GoHighLevel.

**Required Fields:**
- Method (GET, POST, PUT, DELETE, PATCH)
- Path

**Optional Fields:**
- Body (JSON for POST/PUT/PATCH requests)

**Example:**
```
Method: GET
Path: /v1/contacts?limit=10&startAfterId=contact_123
```

## Error Handling

The connector includes robust error handling:

- **Automatic Retries**: 3 attempts with exponential backoff for 5xx errors and rate limits (429)
- **Fallback Endpoints**: Tries alternative API endpoints when primary endpoints fail
- **Continue on Fail**: Returns errors as items instead of stopping the workflow
- **Informative Errors**: Includes status codes, paths, and response bodies in error messages

## Output Format

All operations return data in the following format:

```json
{
  "success": true,
  "data": {
    // Response data from GoHighLevel API
  },
  "meta": {
    "statusCode": 200,
    "responseTime": 150,
    "attemptedPaths": ["POST /v1/contacts/", "POST /v1/contacts"]
  }
}
```

When errors occur and "Continue on Fail" is enabled:

```json
{
  "error": "Error message describing what went wrong"
}
```

## Development

### Prerequisites

- Node.js 18+
- npm or yarn

### Setup

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix
```

### Project Structure

```
├── credentials/
│   └── FutureSystemsApi.credentials.ts    # Credential configuration
├── nodes/
│   └── FutureSystems/
│       ├── FutureSystems.node.ts          # Main node implementation
│       └── descriptions.ts                # Resource and operation descriptions
├── utils/
│   ├── apiRequest.ts                      # HTTP request helper with retries
│   ├── endpoints.ts                       # API endpoint configuration
│   └── __tests__/                        # Unit tests
├── dist/                                 # Built files (generated)
├── package.json                          # Package configuration
├── tsconfig.json                         # TypeScript configuration
└── README.md                             # This file
```

## Changelog

### v1.0.0 (2024-01-XX)

**Initial Release**

- ✅ Complete GoHighLevel API integration
- ✅ Contact management (create, update, find by email)
- ✅ Tag management (add, remove with fallback support)
- ✅ Note management (add with fallback support)
- ✅ Course enrollment (enroll, unenroll with fallback support)
- ✅ Workflow management (add, remove)
- ✅ Do Not Disturb settings (enable, disable)
- ✅ Raw API passthrough
- ✅ Proxy support for enhanced security
- ✅ Idempotency key support
- ✅ Comprehensive error handling with retries
- ✅ Fallback endpoint support
- ✅ TypeScript strict mode
- ✅ Unit tests for critical functionality
- ✅ Continue on Fail support

## Support

For support and questions:

- **Documentation**: [Future Systems Docs](https://futuresystems.com/docs)
- **Issues**: [GitHub Issues](https://github.com/futuresystems/n8n-nodes-future-systems-connector/issues)
- **Email**: support@futuresystems.com

## License

MIT License - see LICENSE file for details.

## Contributing

We welcome contributions! Please see our contributing guidelines for more information.

---

**Future Systems Connector** - Making GoHighLevel automation simple and reliable.