MagnusBilling VoIP Website Integration

A comprehensive VoIP website with full MagnusBilling API integration, built with Node.js and Express. This project provides a complete customer portal and administrative interface for VoIP service providers using MagnusBilling as the backend billing system.

Features

Customer Portal

• User Authentication: Secure login/registration with MagnusBilling integration
• Account Dashboard: Real-time balance, usage statistics, and account overview
• SIP Account Management: Create, configure, and manage SIP accounts
• DID Number Management: Purchase and configure Direct Inward Dialing numbers
• Call History: Detailed call records with filtering and export options
• Payment Processing: Stripe and PayPal integration for credit purchases
• Billing & Invoicing: Automated invoice generation and payment history

Administrative Features

• Customer Management: Full customer account administration
• Rate Plan Management: Dynamic pricing and rate configuration
• System Statistics: Comprehensive reporting and analytics
• Bulk Operations: Mass updates and administrative tools

Technical Features

• MagnusBilling API Integration: Full compatibility with MagnusBilling PHP API
• Redis Caching: Intelligent caching for optimal performance
• Error Handling: Comprehensive error management with fallback responses
• Security: Rate limiting, CORS, helmet security headers
• Session Management: Redis-backed sessions with role-based access control
• Validation: Comprehensive input validation and sanitization
• Logging: Structured logging with Winston
• Testing: Jest test framework with comprehensive test coverage

Prerequisites

• Node.js 16+
• Redis server
• MagnusBilling installation with API access
• Stripe account (for payment processing)
• PayPal account (for payment processing)

Installation

1. Clone the repository

   git clone <repository-url>
   cd voicelinkproject

2. Install dependencies

   npm install

3. Configure environment variables

   cp .env.example .env

   Edit .env with your configuration:

   # MagnusBilling Configuration
   MB_API_BASE_URL=https://your-magnusbilling-domain.com
   MB_API_KEY=your-api-key
   MB_API_SECRET=your-api-secret
   
   # Redis Configuration
   REDIS_URL=redis://localhost:6379
   
   # Email Configuration
   SMTP_HOST=smtp.gmail.com
   SMTP_USER=[email protected]
   SMTP_PASS=your-app-password
   
   # Payment Configuration
   STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
   PAYPAL_CLIENT_ID=your_paypal_client_id
   PAYPAL_CLIENT_SECRET=your_paypal_client_secret

4. Start Redis server

   redis-server

5. Run the application

   # Development
   npm run dev
   
   # Production
   npm start

MagnusBilling API Integration

This project is specifically designed to work with MagnusBilling's PHP-based API structure:

API Endpoints

• Authentication: /mbilling/index.php/api/login
• User Management: /mbilling/index.php/api/user/*
• SIP Accounts: /mbilling/index.php/api/sip/*
• DID Numbers: /mbilling/index.php/api/did/*
• Call Records: /mbilling/index.php/api/call
• Billing: /mbilling/index.php/api/refill/*
• Rates: /mbilling/index.php/api/rate/*

Authentication Methods

The client supports multiple MagnusBilling authentication methods:

• API Key/Secret pairs
• Bearer token authentication
• Session-based authentication

Project Structure

voicelinkproject/
├── config/
│   └── environment.js          # Environment configuration
├── middleware/
│   ├── errorHandler.js         # Global error handling
│   ├── security.js             # Security middleware
│   └── session.js              # Session management
├── services/
│   ├── authService.js          # Authentication service
│   ├── billingService.js       # Payment & billing service
│   └── customerService.js      # Customer management service
├── utils/
│   ├── logger.js               # Winston logging
│   ├── mbClient.js             # MagnusBilling API client
│   ├── redis.js                # Redis client
│   └── validation.js           # Input validation
├── routes/                     # Express routes (to be implemented)
├── views/                      # EJS templates (to be implemented)
├── public/                     # Static assets (to be implemented)
├── tests/                      # Test files
└── logs/                       # Log files

API Client Features

Circuit Breaker Pattern

Prevents cascading failures when MagnusBilling API is unavailable:

• Configurable failure threshold
• Automatic recovery attempts
• Fallback responses

Retry Logic

Exponential backoff with jitter for failed requests:

• Configurable retry attempts
• Smart retry conditions
• Request timeout handling

Caching Strategy

Redis-based caching for optimal performance:

• Customer profiles (30 minutes)
• Account balances (5 minutes)
• Rate plans (30 minutes)
• Usage statistics (30 minutes)

Services Overview

AuthService

• User authentication with MagnusBilling
• Session management and validation
• Role-based access control
• Password reset functionality
• JWT token management

CustomerService

• Customer profile management
• Account balance retrieval
• Usage statistics calculation
• Notification preferences
• Activity summaries

BillingService

• Stripe and PayPal payment processing
• Credit management
• Payment history
• Invoice generation
• Usage cost calculation
• Rate plan management

Security Features

• Rate Limiting: Configurable rate limits for different endpoints
• CORS: Cross-origin request handling
• Helmet: Security headers middleware
• Input Validation: Comprehensive Joi-based validation
• Session Security: Secure Redis-backed sessions
• Error Handling: Classified error responses with fallbacks

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Environment Variables

Variable	Description	Required
MB_API_BASE_URL	MagnusBilling API base URL	Yes
MB_API_KEY	MagnusBilling API key	Yes
MB_API_SECRET	MagnusBilling API secret	Yes
REDIS_URL	Redis connection URL	Yes
SMTP_HOST	Email SMTP host	Yes
SMTP_USER	Email SMTP username	Yes
SMTP_PASS	Email SMTP password	Yes
STRIPE_SECRET_KEY	Stripe secret key	No
PAYPAL_CLIENT_ID	PayPal client ID	No
PAYPAL_CLIENT_SECRET	PayPal client secret	No

Development Roadmap

Phase 1: Core Infrastructure ✅

• Project setup and dependencies
• MagnusBilling API client
• Error handling middleware
• Authentication service
• Customer service
• Billing service

Phase 2: VoIP Services (In Progress)

• SIP management service
• DID management service
• Call history service

Phase 3: User Interface

• Customer portal pages
• Admin panel interface
• Payment integration UI

Phase 4: Advanced Features

• Notification system
• Reporting and analytics
• API endpoints
• Comprehensive testing

Contributing

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

License

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

Support

For support and questions:

• Create an issue in the GitHub repository
• Check the MagnusBilling documentation
• Review the API client implementation in utils/mbClient.js

Acknowledgments

• MagnusBilling for the comprehensive VoIP billing platform
• Express.js community for the robust web framework
• Redis for high-performance caching
• All contributors and testers