npm package: @jatdalton/node-red-contrib-commerce7
Description: Node-RED nodes for Commerce7 REST API integration with authentication, rate limiting, error handling, and built-in pagination
Author: JATD
Latest version: 4.0.12
Deprecated: Package restructured. New version coming soon.

# node-red-contrib-commerce7

A Node-RED package for integrating with the Commerce7 REST API. This package provides a clean API client with authentication, request handling, rate limiting, and error management when working with Commerce7's wine and e-commerce platform.

## Features

- **Secure Authentication**: HTTP Basic Auth with App ID/Secret and tenant headers
- **Rate Limiting**: Configurable rate limiting with dynamic backoff
- **Error Handling**: Comprehensive error handling with retry logic
- **Built-in Pagination**: Automatic cursor-based pagination support
- **Flexible Configuration**: Runtime override of paths, methods, headers, and timeouts
- **Multi-Tenant Support**: Dynamic tenant switching per request
- **Node-RED 4.1+ Compatible**: Built for modern Node-RED versions

## Installation

### Method 1: npm install (Recommended)

Navigate to your Node-RED user directory (typically `~/.node-red`):

```bash
cd ~/.node-red
npm install @jatdalton/node-red-contrib-commerce7
```

### Method 2: Node-RED Palette Manager

1. Open Node-RED
2. Menu → **Manage palette**
3. Search for "commerce7"
4. Click **Install**

### Method 2: Manual Installation

1. Clone or download this repository
2. Copy the `node-red-contrib-commerce7` folder to your Node-RED user directory
3. Restart Node-RED

## Compatibility

- **Node-RED**: >= 4.1.0
- **Node.js**: >= 18.0.0
- **Commerce7 API**: v1 REST endpoints

## Nodes

### 1. Commerce7 Config Node (`commerce7-config`)

Configuration node for Commerce7 API connection settings.

#### Configuration Options

- **Name**: Display name for the configuration
- **Base URL**: Commerce7 API base URL (default: `https://api.commerce7.com`)
- **Tenant Header**: Header name for tenant (default: `tenant`)
- **Requests per Minute**: Rate limiting configuration (default: 100)
- **Connect Timeout**: Connection timeout in milliseconds (default: 30000)
- **Socket Timeout**: Socket timeout in milliseconds (default: 30000)
- **Pool Settings**: Connection pool configuration

#### Credentials

- **App ID**: Your Commerce7 App ID
- **App Secret**: Your Commerce7 App Secret Key
- **Tenant**: Your Commerce7 tenant identifier

### 2. Commerce7 Request Node (`commerce7-request`)

Executes HTTP requests to the Commerce7 API with rate limiting, error handling, and built-in pagination support.

#### Configuration Options

- **Name**: Display name for the node
- **Commerce7 Config**: Link to a configuration node
- **API Path**: API endpoint path (e.g., `/customer`)
- **HTTP Method**: GET, POST, PUT, PATCH, DELETE
- **Send msg.payload as body**: Automatically send message payload as request body
- **Timeout**: Request timeout in milliseconds
- **Enable Pagination**: Enable automatic cursor-based pagination (GET requests only)
- **Pagination Mode**: Collect all pages or stream per page
- **Record Tag**: Field name containing records array (e.g., `clubMemberships`)
- **Dynamic Rate Limiting**: Enable smart retry and backoff logic

## Usage Examples

### Basic Customer Retrieval

```javascript
// Function node to prepare message
msg.query = {
    limit: 10,
    orderCount: "gt:1"
};
return msg;
```

Connect to a Commerce7 Request node configured with:
- Method: GET
- Path: `/customer`
- Send payload as body: false

### Creating a Customer

```javascript
// Function node to prepare customer data
msg.payload = {
    firstName: "John",
    lastName: "Doe",
    email: "john.doe@example.com",
    isSendTransactionEmail: false
};
return msg;
```

Connect to a Commerce7 Request node configured with:
- Method: POST
- Path: `/customer`
- Send payload as body: true

### Dynamic Request Override

```javascript
// Function node to override request parameters
msg.c7 = {
    tenant: "dynamic-tenant-id",  // Override config tenant (supports multi-tenant flows)
    method: "PUT",
    path: "/customer/123e4567-e89b-12d3-a456-426614174000",
    query: {  // Query parameters (alternative to msg.query)
        limit: 10,
        updatedAt: "gte:2024-01-01"
    },
    body: {
        firstName: "Jane",
        lastName: "Smith"
    },
    headers: {
        "X-Custom-Header": "value"
    },
    timeout: 45000
};
return msg;
```

### Multi-Tenant Support

The request node supports dynamic tenant switching via `msg.c7.tenant`. This allows you to use a single config node for multiple tenants while maintaining per-tenant rate limiting:

```javascript
// Function node for multi-tenant flow
const tenants = ["tenant1", "tenant2", "tenant3"];

tenants.forEach(tenant => {
    msg.c7 = {
        tenant: tenant,  // Dynamic tenant override
        path: "/customer",
        method: "GET",
        query: { limit: 10 }
    };
    node.send(msg);
});
```

## Message Properties

### Input Message Properties

- `msg.payload`: Request body data (for POST/PUT/PATCH)
- `msg.query`: Query parameters for GET requests (alternative to `msg.c7.query`)
- `msg.c7`: Runtime override object (see Dynamic Request Override)
  - `msg.c7.tenant`: Override the tenant from config node (enables multi-tenant flows)
  - `msg.c7.method`: Override HTTP method
  - `msg.c7.path`: Override API path
  - `msg.c7.query`: Query parameters (alternative to `msg.query`)
  - `msg.c7.body`: Request body (alternative to `msg.payload`)
  - `msg.c7.headers`: Additional/custom headers
  - `msg.c7.timeout`: Override request timeout

### Output Message Properties

- `msg.payload`: Response data from Commerce7 API
- `msg.statusCode`: HTTP status code
- `msg.headers`: Response headers
- `msg.c7Response`: Commerce7-specific metadata
- `msg.error`: Error message (if request failed)

## Rate Limiting

The package implements intelligent rate limiting:

- **Per-tenant limiting**: Each tenant has its own rate limiter
- **Dynamic backoff**: Automatic retry with exponential backoff
- **429 handling**: Respects `Retry-After` headers
- **Configurable limits**: Set requests per minute per configuration

## Error Handling

Comprehensive error handling for common scenarios:

- **401 Unauthorized**: Invalid credentials or missing tenant
- **403 Forbidden**: Insufficient API permissions
- **429 Rate Limited**: Too many requests
- **5xx Server Errors**: Automatic retry with backoff
- **Network Errors**: Timeout and connection handling

## Security Features

- **Credential Storage**: Secrets stored securely in Node-RED credentials
- **HTTPS Only**: All requests use secure connections
- **No Client Exposure**: App secrets never exposed to browser

## Example Flows

### Customer Management Flow

1. **Commerce7 Config** → Configure API connection
2. **Commerce7 Request** (GET `/customer`) → Retrieve customer list
3. **Function** → Process customer data
4. **Commerce7 Request** (POST `/customer`) → Create new customer

### Club Membership Flow

1. **Commerce7 Config** → Configure API connection
2. **Commerce7 Request** (GET `/customer/{id}`) → Get customer details
3. **Commerce7 Request** (POST `/customer-address`) → Create address
4. **Commerce7 Request** (POST `/club-membership`) → Create membership

## Troubleshooting

### Common Issues

1. **401 Unauthorized**: Check App ID, Secret, and Tenant in config
2. **403 Forbidden**: Verify your app has required API scopes
3. **Rate Limiting**: Reduce requests per minute or implement delays
4. **Timeout Errors**: Increase timeout values for slow operations

### Debug Mode

Enable Node-RED debug mode to see detailed request/response information:

```bash
node-red --debug
```

## Development

### Building from Source

```bash
git clone https://github.com/yourusername/node-red-contrib-commerce7.git
cd node-red-contrib-commerce7
npm install
```

### Testing

```bash
npm test
```

## Contributing

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

## License

MIT License - see LICENSE file for details

## Publishing

This package is published as a **public npm package**. See [PUBLISHING.md](PUBLISHING.md) for:
- How to publish updates
- Managing access
- Version management
- CI/CD setup

## Support

- **Issues**: GitHub Issues
- **Documentation**: [Commerce7 API Docs](https://developer.commerce7.com/)
- **Node-RED**: [Node-RED Documentation](https://nodered.org/docs/)
- **Publishing Guide**: [PUBLISHING.md](PUBLISHING.md)

## Changelog

### v4.0.0
- Simplified to core API client nodes (config + request)
- Built-in pagination support
- Multi-tenant support with dynamic tenant switching
- Node-RED 4.1+ compatibility

### v3.2.1
- Previous version with sync nodes (removed in v4.0.0)