Digital Wallet Cards n8n Custom Node

A comprehensive n8n custom node for integrating with the Digital Wallet Cards loyalty program API. This node provides complete CRUD operations for managing loyalty cards, customers, companies, templates, communications, analytics, and system operations.

Features

• Complete API Coverage: Full support for all Digital Wallet Cards API v2 endpoints
• Card Management: Create, update, and manage loyalty cards with balance tracking
• Customer Operations: Comprehensive customer profile management
• Company & Template Management: Multi-tenant company setup and card template configuration
• Communication Tools: Send push notifications and SMS messages to customers
• Analytics & Reporting: Access revenue statistics and transaction analytics
• System Operations: Profile management, usage statistics, and marketplace integration
• Robust Error Handling: Comprehensive error handling with detailed feedback
• Batch Processing: Process multiple items with individual error handling
• TypeScript Support: Fully typed with comprehensive interfaces

Installation

From n8n Community Nodes

1. In your n8n instance, go to Settings → Community Nodes
2. Click Install and enter: n8n-nodes-digital-wallet-cards
3. Click Install and restart your n8n instance

Manual Installation

1. Navigate to your n8n installation directory
2. Install the package:

   npm install n8n-nodes-digital-wallet-cards
   

3. Restart n8n

Development Installation

1. Clone this repository:

   git clone https://github.com/your-username/n8n-nodes-digital-wallet-cards.git
   cd n8n-nodes-digital-wallet-cards
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Link to your n8n instance:

   npm link
   cd ~/.n8n/nodes
   npm link n8n-nodes-digital-wallet-cards
   

Setup

API Credentials

1. Obtain your Digital Wallet Cards marketplace app token from your dashboard
2. In n8n, create a new credential of type Digital Wallet Cards API
3. Enter your app token and optionally customize the base URL

Authentication

The node uses X-App-Token authentication with the Digital Wallet Cards API. All requests are automatically authenticated using your provided app token.

Usage

Available Resources

1. Cards - Loyalty card operations
2. Customers - Customer profile management
3. Companies - Company configuration
4. Templates - Card template management
5. Communication - Push notifications and SMS
6. Analytics - Revenue and operation statistics
7. System - Profile and system operations

Card Operations

Create, manage, and operate on loyalty cards:

• Create: Create new loyalty cards
• Get/Get All: Retrieve card information
• Update/Delete: Modify or remove cards
• Balance Operations: Add/deduct amounts, points, stamps, visits
• Rewards: Manage rewards and redemptions
• Configuration: Set expiration dates and membership tiers

Customer Operations

Manage customer profiles and data:

• CRUD Operations: Create, read, update, delete customers
• Profile Management: Handle contact information and preferences
• Search & Filter: Find customers by various criteria
• Batch Processing: Process multiple customers efficiently

Communication Operations

Engage with customers through multiple channels:

• Push Notifications: Send targeted push notifications
• SMS Messaging: Send SMS messages with scheduling
• Message History: Track communication history
• Scheduling: Schedule messages for future delivery

Analytics Operations

Access comprehensive business insights:

• Revenue Statistics: Get detailed revenue analytics
• Transaction Analysis: Analyze customer operations
• Time-based Reports: Generate reports for specific periods
• Customer Segmentation: Analyze customer behavior patterns

Quick Start Guide

1. Install the Node

Install via n8n Community Nodes:

1. Navigate to Settings → Community Nodes
2. Install n8n-nodes-digital-wallet-cards
3. Restart n8n

2. Set up Credentials

1. Create Digital Wallet Cards API credentials
2. Enter your marketplace app token
3. (Optional) Customize base URL if using a different environment

3. Add the Node to Your Workflow

1. Search for "Digital Wallet Cards" in the node palette
2. Drag it into your workflow
3. Configure your desired operation

Configuration Examples

Basic Card Creation

{
  "resource": "card",
  "operation": "create",
  "customerId": "customer_123",
  "companyId": 1,
  "templateId": 1,
  "initialBalance": 100.00,
  "metadata": {
    "source": "mobile_app",
    "campaign": "spring_2024"
  }
}

Customer Profile Creation

{
  "resource": "customer",
  "operation": "create",
  "email": "customer@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "companyId": 1,
  "dateOfBirth": "1990-05-15",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "US"
  },
  "preferences": {
    "notifications": {
      "email": true,
      "push": true,
      "sms": false
    }
  }
}

Balance Operations

{
  "resource": "card",
  "operation": "addAmount",
  "cardId": "card_123",
  "amount": 25.50,
  "description": "Purchase reward - Coffee shop visit",
  "reference": "txn_789"
}

Send Push Notification

{
  "resource": "communication",
  "operation": "sendPush",
  "cardId": "card_123",
  "title": "Reward Earned!",
  "message": "You earned 100 points with your recent purchase!",
  "type": "reward_earned",
  "data": {
    "points": 100,
    "tier": "Gold",
    "merchant": "Coffee Corner"
  }
}

Analytics Query

{
  "resource": "analytics",
  "operation": "getRevenue",
  "companyId": 1,
  "startDate": "2024-01-01",
  "endDate": "2024-03-31",
  "groupBy": "month"
}

Common Workflows

Customer Onboarding

1. Create Customer → Create Card → Send Welcome Push
2. Automatically set up new customers with initial loyalty cards
3. Send personalized welcome messages with account details

Transaction Processing

1. Add Amount/Points → Check Tier Upgrades → Send Notifications
2. Process purchases and automatically award loyalty points
3. Notify customers of balance updates and tier changes

Marketing Campaigns

1. Get Customers → Filter by Criteria → Send Push/SMS
2. Target specific customer segments with personalized offers
3. Track campaign performance through analytics

Revenue Analytics

1. Get Revenue Stats → Format Data → Send to Dashboard
2. Generate comprehensive business intelligence reports
3. Monitor loyalty program performance and ROI

Development

Project Structure

├── credentials/              # API credential definitions
├── nodes/                   # Main node implementation
│   └── DigitalWalletCards/
│       ├── DigitalWalletCards.node.ts
│       ├── types.ts         # TypeScript interfaces
│       └── utils.ts         # Utility functions
├── tests/                   # Comprehensive test suite
│   ├── units/              # Unit tests
│   ├── nodes/              # Integration tests
│   ├── credentials/        # Credential tests
│   └── error-handling/     # Error handling tests
└── package.json

Building

# Install dependencies
npm install

# Build the project
npm run build

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test tests/units/utils.test.ts

API Documentation

The node is built against the Digital Wallet Cards API v2. For detailed API documentation, visit:
https://api.digitalwallet.cards/api/v2/docs

Error Handling

The node provides comprehensive error handling:

• Validation Errors: Input validation with detailed feedback
• API Errors: Structured error responses from the API
• Network Errors: Connection and timeout handling
• Rate Limiting: Automatic handling of rate limit responses
• Batch Processing: Individual error handling for batch operations

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your app token is correct and not expired
   • Ensure you have sufficient permissions for the operation

2. Validation Errors

   • Check that all required fields are provided
   • Verify data formats (email, phone, dates)
   • Ensure numeric values are positive where required

3. Rate Limiting

   • The API has rate limits; implement appropriate delays
   • Monitor the Retry-After header in rate limit responses

4. Network Issues

   • Check your internet connection
   • Verify the base URL is correct
   • Ensure firewall allows outbound connections

Debug Mode

Enable debug logging in n8n to see detailed request/response information:

export N8N_LOG_LEVEL=debug

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Write comprehensive tests for new features
• Follow TypeScript best practices
• Maintain backward compatibility
• Update documentation for API changes
• Use semantic versioning for releases

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: Digital Wallet Cards API Docs
• Issues: GitHub Issues
• n8n Community: n8n Community Forum

Changelog

See CHANGELOG.md for detailed version history.

Acknowledgments

• Built for the n8n workflow automation platform
• Integrates with Digital Wallet Cards loyalty program platform
• Thanks to the n8n community for best practices and guidance