Merge pull request #15 from openSVM/copilot/fix-14

Add comprehensive n8n workflow automation integration and tutorial

Author: 0xrinegade

docs/n8n-integration.md

@@ -0,0 +1,343 @@
+# n8n Integration Guide
+
+## Overview
+
+This guide provides comprehensive instructions for integrating SVM-Pay with n8n, a powerful workflow automation platform. With this integration, you can automate payment workflows, handle complex business logic, and integrate cryptocurrency payments seamlessly into your existing automation processes.
+
+## What is n8n?
+
+n8n is an open-source workflow automation tool that allows you to connect different services and automate tasks. It provides a visual workflow editor and supports custom nodes for extending functionality. With the SVM-Pay integration, you can:
+
+- Automate payment processing based on external events
+- Create conditional payment workflows
+- Process bulk payments and transfers
+- Handle payment notifications and updates
+- Integrate with databases, APIs, and other services
+
+## Key Features
+
+### SVM-Pay Custom Nodes
+
+The integration includes several custom nodes:
+
+1. **SVM-Pay Node** - Main payment processing and wallet operations
+2. **SVM-Pay Webhook Node** - Handle payment events and notifications
+3. **SVM-Pay Batch Node** - Process multiple payments efficiently
+4. **SVM-Pay Credentials** - Secure credential management
+
+### Supported Operations
+
+- **Payment Processing**: Create payment requests, process direct payments, verify transactions
+- **Webhook Handling**: Receive and process real-time payment events
+- **Batch Operations**: Handle bulk payments, payroll distribution, airdrops
+- **Wallet Management**: Check balances, manage multiple wallets
+- **Token Operations**: Support for USDC, SOL, and custom tokens
+
+## Installation
+
+### Prerequisites
+
+- n8n installed (locally or cloud)
+- Node.js 16+ (for local development)
+- SVM-Pay account and API credentials
+- Basic understanding of workflow automation
+
+### Installing Custom Nodes
+
+1. **Create Node Package**:
+```bash
+mkdir n8n-nodes-svm-pay
+cd n8n-nodes-svm-pay
+npm init -y
+```
+
+2. **Install Dependencies**:
+```bash
+npm install --save n8n-workflow n8n-core @svm-pay/sdk
+npm install --save-dev typescript @types/node
+```
+
+3. **Build and Install**:
+```bash
+npm run build
+npm install -g .
+```
+
+4. **Restart n8n**:
+```bash
+n8n start
+```
+
+## Configuration
+
+### Setting Up Credentials
+
+1. In n8n, go to **Settings** > **Credentials**
+2. Click **Add Credential** and select **SVM-Pay API**
+3. Configure the following:
+   - **Environment**: Choose between Mainnet and Devnet
+   - **Private Key**: Your wallet private key (base58 format)
+   - **API Key**: Optional API key for enhanced features
+   - **Default Token**: Default token for payments (e.g., USDC)
+   - **Webhook Secret**: Secret for webhook verification
+
+### Environment Variables
+
+For production deployments, set these environment variables:
+
+```bash
+# SVM-Pay Configuration
+SVMPAY_ENVIRONMENT=mainnet
+SVMPAY_PRIVATE_KEY=your_private_key_here
+SVMPAY_API_KEY=your_api_key_here
+SVMPAY_WEBHOOK_SECRET=your_webhook_secret_here
+
+# n8n Configuration
+N8N_HOST=your-domain.com
+N8N_PROTOCOL=https
+WEBHOOK_URL=https://your-domain.com/webhook
+```
+
+## Common Use Cases
+
+### 1. E-commerce Order Processing
+
+Automate payment processing for online stores:
+
+```yaml
+Workflow: Order Payment Automation
+Trigger: Webhook (Order Created)
+Steps:
+  1. Validate order data
+  2. Create payment request
+  3. Send payment link to customer
+  4. Wait for payment confirmation
+  5. Update order status
+  6. Send confirmation email
+```
+
+### 2. Subscription Billing
+
+Automate recurring subscription payments:
+
+```yaml
+Workflow: Monthly Subscription Billing
+Trigger: Cron (Monthly)
+Steps:
+  1. Get active subscriptions from database
+  2. Process batch payments
+  3. Update billing dates
+  4. Handle failed payments
+  5. Send invoices and receipts
+```
+
+### 3. Payroll Distribution
+
+Automate employee payroll payments:
+
+```yaml
+Workflow: Payroll Processing
+Trigger: Manual/Scheduled
+Steps:
+  1. Load payroll data from HR system
+  2. Validate employee wallet addresses
+  3. Process batch transfers
+  4. Generate payroll reports
+  5. Notify employees of payment
+```
+
+### 4. Event-Driven Payments
+
+Create conditional payment workflows:
+
+```yaml
+Workflow: Conditional Payment Router
+Trigger: Payment Event Webhook
+Steps:
+  1. Receive payment event
+  2. Check payment amount and conditions
+  3. Route to appropriate handler
+  4. Execute business logic
+  5. Send notifications
+```
+
+## Advanced Features
+
+### Batch Processing
+
+The SVM-Pay Batch node supports several batch operations:
+
+- **Batch Payments**: Process multiple payments in optimized batches
+- **Bulk Transfers**: Send transfers to multiple recipients
+- **Payroll Distribution**: Handle employee payments with metadata
+- **Airdrop Campaigns**: Distribute tokens to community members
+
+### Error Handling
+
+Implement robust error handling:
+
+- **Continue on Error**: Process remaining items if some fail
+- **Retry Logic**: Automatic retry with exponential backoff
+- **Error Notifications**: Alert administrators of failures
+- **Grace Periods**: Handle temporary payment failures
+
+### Monitoring and Analytics
+
+Track workflow performance:
+
+- **Execution Metrics**: Monitor success rates and timing
+- **Payment Analytics**: Track volumes and patterns
+- **Error Tracking**: Identify and resolve issues quickly
+- **Performance Optimization**: Optimize batch sizes and timing
+
+## Security Best Practices
+
+### Credential Management
+
+- Store private keys securely using n8n's credential system
+- Use environment variables for production deployments
+- Rotate API keys and webhook secrets regularly
+- Implement proper access controls
+
+### Webhook Security
+
+- Always verify webhook signatures
+- Use HTTPS for all webhook endpoints
+- Implement rate limiting and throttling
+- Log and monitor webhook activity
+
+### Network Security
+
+- Use secure networks (Mainnet for production)
+- Implement proper firewall rules
+- Monitor for unusual activity
+- Keep n8n and dependencies updated
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection Errors**:
+   - Verify network configuration
+   - Check API endpoints and credentials
+   - Ensure proper firewall settings
+
+2. **Payment Failures**:
+   - Verify wallet balances
+   - Check token configurations
+   - Review transaction limits
+
+3. **Webhook Issues**:
+   - Verify webhook URLs and secrets
+   - Check n8n webhook configuration
+   - Monitor webhook logs
+
+4. **Performance Issues**:
+   - Optimize batch sizes
+   - Implement proper delays
+   - Monitor resource usage
+
+### Debug Mode
+
+Enable debug logging for troubleshooting:
+
+```bash
+N8N_LOG_LEVEL=debug n8n start
+```
+
+### Support Resources
+
+- **Documentation**: [SVM-Pay Docs](https://docs.svm-pay.dev)
+- **n8n Community**: [n8n Community Forum](https://community.n8n.io)
+- **GitHub Issues**: [SVM-Pay GitHub](https://github.com/openSVM/svm-pay/issues)
+- **Discord**: [SVM-Pay Discord](https://discord.gg/svm-pay)
+
+## Examples and Templates
+
+### Basic Payment Workflow
+
+```json
+{
+  "name": "Basic Payment Processing",
+  "nodes": [
+    {
+      "name": "Payment Trigger",
+      "type": "svmPayWebhook",
+      "parameters": {
+        "eventTypes": ["payment.pending"]
+      }
+    },
+    {
+      "name": "Process Payment",
+      "type": "svmPay",
+      "parameters": {
+        "resource": "payment",
+        "operation": "processPayment"
+      }
+    },
+    {
+      "name": "Send Confirmation",
+      "type": "n8n-nodes-base.emailSend",
+      "parameters": {
+        "subject": "Payment Confirmed"
+      }
+    }
+  ]
+}
+```
+
+### Batch Payment Template
+
+```json
+{
+  "name": "Bulk Payment Distribution",
+  "nodes": [
+    {
+      "name": "Load Payment Data",
+      "type": "n8n-nodes-base.postgres",
+      "parameters": {
+        "query": "SELECT * FROM pending_payments"
+      }
+    },
+    {
+      "name": "Process Batch",
+      "type": "svmPayBatch",
+      "parameters": {
+        "operation": "batchPayments",
+        "batchSize": 20
+      }
+    },
+    {
+      "name": "Update Database",
+      "type": "n8n-nodes-base.postgres",
+      "parameters": {
+        "query": "UPDATE payments SET status = 'completed'"
+      }
+    }
+  ]
+}
+```
+
+## Migration Guide
+
+### From Manual Processes
+
+1. **Identify Automation Opportunities**: Review current manual payment processes
+2. **Design Workflows**: Create n8n workflows for each process
+3. **Test in Devnet**: Thoroughly test all workflows
+4. **Gradual Migration**: Migrate processes incrementally
+5. **Monitor and Optimize**: Continuously improve workflows
+
+### From Other Platforms
+
+1. **Export Existing Workflows**: Export configurations from current platform
+2. **Map to n8n Nodes**: Identify equivalent n8n nodes and operations
+3. **Recreate Workflows**: Build new workflows in n8n
+4. **Data Migration**: Migrate any stored data or configurations
+5. **Testing and Validation**: Ensure all functionality works correctly
+
+## Conclusion
+
+The SVM-Pay n8n integration provides a powerful platform for automating cryptocurrency payment workflows. With custom nodes, comprehensive error handling, and extensive monitoring capabilities, you can build robust payment automation systems that scale with your business needs.
+
+For additional support and advanced use cases, refer to the main SVM-Pay documentation and join our community channels.