Add complete billing module with prepaid, rate plans, and mod_nibblebill integration

[Copilot]

Implements dynamic prepaid and digit-based billing system with multi-prefix rate plans, call center agent billing, CDR integration, and real-time balance monitoring via mod_nibblebill.

Core Implementation

Database Schema (6 tables)

• v_billing_rates - Rate plans with destination prefixes
• v_billing_balances - User prepaid balances
• v_billing_user_rates / v_billing_agent_rates - Many-to-many rate assignments
• v_billing_usage - Call usage records with costs
• v_billing_balance_history - Transaction audit trail

Rate Plan Management (billing_rates.php, billing_rate_edit.php)

• Per-minute or per-second billing
• Longest prefix match algorithm for destination-based pricing
• Multiple rate plans assignable per user/agent via junction tables

Balance Management (billing_balances.php, billing_balance_edit.php, billing_balance_adjust.php)

• Prepaid balance tracking with multi-rate assignment
• Manual credit adjustments (add/deduct/refund/payment)
• Complete transaction history with audit trail

Billing Engine (resources/classes/billing.php)

// Calculates cost using longest prefix match across assigned rate plans
$billing = new billing();
$cost = $billing->calculate_call_cost($extension, $destination, $duration_seconds);
$billing->deduct_balance($extension, $cost, $call_uuid);

FreeSWITCH Integration

mod_nibblebill Configuration (resources/install/nibblebill.conf.xml)

• Custom SQL queries for FusionPBX database
• 60-second heartbeat for real-time balance monitoring
• Automatic call termination at $0 balance
• Low balance threshold warnings at $5

Dialplan Integration (resources/install/dialplan/888_billing_integration.xml)

• Pre-call balance validation
• Dynamic rate lookup via Lua scripts
• Balance info extension (dial 9999)

Lua Scripts (resources/install/scripts/)

-- check_rate.lua: Queries v_billing_rates for longest prefix match
-- check_balance.lua: Validates sufficient balance before call
-- Sets nibblebill channel variables dynamically

API Endpoint (api_nibblebill.php)

• RESTful interface for mod_nibblebill callbacks
• Actions: check_balance, deduct_balance, check_rate, calculate_cost
• Integrates with billing class for balance operations

CDR Integration

Post-Call Processing (resources/service/cdr_billing_hook.php)

• Automatic billing when CDR records are created
• Batch processing for unbilled CDRs
• Balance deduction with usage record creation
• Call center agent billing support via cc_agent field

UI Components

Dashboard (billing.php)

• Overview cards: rate plans, balances, usage, low balance alerts
• Financial summary: total balance, today's usage
• Recent activity table

Usage Reports (billing_usage.php)

• Date range and extension filtering
• Cost totals and statistics
• Detailed call history with per-call costs

Bug Fix

groups.php line 462 - Fixed TypeError when database->select() returns false

- if (count($result) == 0) {
+ if (!is_array($result) || count($result) == 0) {

Documentation

• QUICKSTART.md - 5-minute setup guide
• INSTALL.md - Complete installation manual (13,000 words)
• CONFIGURATION.md - Config files reference
• CONFIGURATION_REFERENCE.md - config.conf compatibility analysis
• Sample data SQL for quick testing

File Structure

Follows FusionPBX app conventions:

• Standard app_*.php files (config, defaults, languages, menu)
• resources/classes/ for core logic
• resources/dashboard/ for dashboard widget integration
• resources/install/ for configuration templates
• resources/service/ for background processing hooks

All paths compatible with existing /etc/fusionpbx/config.conf - no configuration changes required.

Original prompt

create dynamic prepaid and digit based billing for user and agent, rate pland option to add multiple prefix per user

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.