n8n-nodes-zid-beta/README.md

BETA; n8n custom nodes for integrating with the Zid API (orders, products, customers, etc.)

# n8n-nodes-zid

Custom n8n nodes for integrating with the Zid API. This package provides trigger and action nodes to automate workflows with Zid's e-commerce platform.

## Features

- **OAuth2 Authentication**: Secure authentication using Zid's OAuth2 flow with dual-token support
- **Trigger Nodes**: Automatically trigger workflows on new orders, order updates, and new customers
- **Action Nodes**: Perform operations on orders, products, and customers
- **Error Handling**: Comprehensive error handling with specific Zid API error responses
- **Pagination Support**: Automatic handling of paginated API responses
- **Rate Limiting**: Built-in respect for Zid API rate limits

## Installation

### Method 1: Global npm Installation (Recommended)

```bash
npm install -g n8n-nodes-zid-beta@0.1.1
```

### Method 2: Docker Installation

```bash
# Pull the n8n image
docker pull n8nio/n8n

# Install the package in a running container
docker exec -it <container_name> npm install -g n8n-nodes-zid-beta@0.1.1

# Or build a custom image
FROM n8nio/n8n
RUN npm install -g n8n-nodes-zid-beta@0.1.1
```

### Method 3: Development Installation

```bash
# Clone and build
git clone <repository>
cd n8n-nodes-zid
npm install
npm run build
npm pack

# Install the package
npm install -g n8n-nodes-zid-beta-0.1.1.tgz
```

## OAuth2 Setup

This package implements Zid's OAuth2 authorization flow with dual-token authentication. See [OAUTH2_IMPLEMENTATION.md](./OAUTH2_IMPLEMENTATION.md) for detailed implementation information.

### Quick Setup

1. **Create Zid App**: Register your application in the [Zid Partner Dashboard](https://partners.zid.sa)
2. **Get Credentials**: Note your Client ID and Client Secret
3. **Configure URLs**: Set up the required URLs in your Zid app
4. **Configure n8n**: 
   - Go to Settings → Credentials
   - Add new "Zid OAuth2 API" credential
   - Enter your Client ID and Client Secret
   - Complete the OAuth2 flow

### Partner Dashboard URL Configuration

When creating your Zid app, configure these URLs:

1. **Application URL**: Your n8n instance base URL
   - Example: `https://your-n8n.com`

2. **Redirect URL**: n8n OAuth2 redirect endpoint  
   - Example: `https://your-n8n.com/rest/oauth2-credential/callback`

3. **Callback URL**: Same as redirect URL
   - Example: `https://your-n8n.com/rest/oauth2-credential/callback`

> **Note**: The exact callback URL format may vary depending on your n8n installation. Check your n8n instance's OAuth2 callback URL pattern.

### Required Tokens

Zid requires two tokens for API access:
- **Authorization Token**: Bearer token for API access
- **X-Manager-Token**: Store-specific access token

Both tokens are automatically handled by the OAuth2 credential.

### Scope Configuration

Configure required scopes in your Zid Partner Dashboard:
- `read:orders` - Read order data
- `write:orders` - Update order information  
- `read:products` - Read product data
- `write:products` - Create/update products
- `read:customers` - Read customer data
- `write:customers` - Create/update customers

## Available Nodes

### Trigger Nodes

#### Zid Order Trigger
- Triggers on new orders or order status updates
- Configurable polling interval (1-60 minutes)
- Status filtering support
- Flood prevention on first run

#### Zid Customer Trigger  
- Triggers on new customer registrations
- Configurable polling interval (1-60 minutes)
- Automatic duplicate prevention

### Action Nodes

#### Zid (Main Action Node)
Supports three resources with multiple operations:

**Orders**
- Get All Orders
- Get Order by ID  
- Update Order

**Products**
- Get All Products
- Get Product by ID
- Create Product
- Update Product

**Customers**
- Get All Customers
- Get Customer by ID
- Create Customer
- Update Customer

## API Reference

### Authentication Headers

All API requests include:
```
Authorization: Bearer <authorization_token>
X-Manager-Token: <access_token>
Content-Type: application/json
Accept: application/json
```

### Base URL
```
https://api.zid.sa/v1
```

### Error Handling

The package handles specific Zid API errors:
- **401**: Authentication errors
- **403**: Authorization/permission errors  
- **429**: Rate limit exceeded
- **Network errors**: Connection issues

## Usage Examples

### Example 1: New Order Email Notification

```json
{
  "nodes": [
    {
      "name": "Zid Order Trigger",
      "type": "n8n-nodes-zid.zidOrderTrigger",
      "parameters": {
        "triggerOn": "newOrder",
        "pollInterval": 5
      }
    },
    {
      "name": "Send Email",
      "type": "n8n-nodes-base.emailSend",
      "parameters": {
        "subject": "New Order: {{$json.id}}",
        "text": "Order total: {{$json.total}}"
      }
    }
  ]
}
```

### Example 2: Product Sync

```json
{
  "nodes": [
    {
      "name": "Get Products",
      "type": "n8n-nodes-zid.zid",
      "parameters": {
        "resource": "product",
        "operation": "getAll",
        "limit": 50
      }
    }
  ]
}
```

## Development

### Building

```bash
npm install
npm run build
```

### Testing

```bash
npm test
```

### Linting

```bash
npm run lint
npm run lint:fix
```

## Troubleshooting

### Installation Issues

1. **"Package does not contain any nodes"**
   - Ensure you're using version 0.1.1 or later
   - Restart n8n after installation

2. **OAuth2 Authentication Fails**
   - Verify Client ID and Client Secret
   - Check redirect URLs in Partner Dashboard
   - Ensure both tokens are present

3. **API Errors**
   - Check token expiration (tokens last 1 year)
   - Verify required scopes are granted
   - Check API rate limits

### Debug Steps

1. Check n8n logs for detailed error messages
2. Verify credentials in n8n Settings → Credentials
3. Test API access with curl using the same tokens
4. Check Zid Partner Dashboard for app status

## Version History

- **0.1.1**: Updated OAuth2 implementation with dual-token support
- **0.1.0**: Initial release with basic OAuth2 support

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

- [Zid API Documentation](https://docs.zid.sa)
- [Zid Partner Dashboard](https://partners.zid.sa)
- [n8n Community](https://community.n8n.io)

## Related Documentation

- [OAuth2 Implementation Details](./OAUTH2_IMPLEMENTATION.md)
- [Installation Guide](./INSTALLATION.md)
- [Example Workflows](./examples/)