### Run Initial Setup Script

Source: https://github.com/alijayanet/gembok-bill/blob/main/DATA_README.md

Execute this command to install dependencies, run database migrations, and set up initial data for a new server.

```bash
npm run setup
```

--------------------------------

### Start the Application

Source: https://github.com/alijayanet/gembok-bill/blob/main/WHATSAPP_FIX_SUMMARY.md

This command starts the main application after dependencies are installed.

```bash
npm start
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/alijayanet/gembok-bill/blob/main/DEPLOY_README.md

Install all necessary project dependencies using npm.

```bash
npm install
```

--------------------------------

### Copy Environment Example File

Source: https://github.com/alijayanet/gembok-bill/blob/main/DATA_README.md

Copy the example environment file to create your own configuration. Adjust the values in the new `.env` file for your specific environment.

```bash
cp .env.example .env
```

--------------------------------

### Setup Database

Source: https://github.com/alijayanet/gembok-bill/blob/main/DEPLOY_README.md

The database is created automatically on first run. Alternatively, restore from a backup.

```bash
# Database akan dibuat otomatis saat pertama kali run
# Atau restore dari backup:
# cp backup/billing.db data/billing.db
```

--------------------------------

### Example: Technician Handling a Report Scenario

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/TROUBLE_REPORT_WHATSAPP.md

This example demonstrates the complete workflow for a technician handling a trouble report, from receiving a new notification to resolving the issue and customer confirmation.

```text
1. Teknisi terima notifikasi laporan baru
   📱 Laporan gangguan baru: TR001

2. Teknisi lihat daftar laporan
   👤 Kirim: trouble
   📋 Sistem tampilkan daftar laporan aktif

3. Teknisi lihat detail laporan
   👤 Kirim: status TR001
   📋 Sistem tampilkan detail lengkap

4. Teknisi mulai kerja
   👤 Kirim: update TR001 in_progress Sedang dicek di lokasi
   ✅ Status berubah, notifikasi ke pelanggan & admin

5. Teknisi tambah progress
   👤 Kirim: catatan TR001 Sudah dicek, masalah di kabel
   ✅ Catatan ditambahkan, notifikasi ke semua

6. Teknisi selesaikan
   👤 Kirim: selesai TR001 Masalah sudah diperbaiki, internet normal
   ✅ Status jadi resolved, notifikasi ke semua

7. Pelanggan konfirmasi
   📱 Pelanggan dapat notifikasi penyelesaian
   🌐 Pelanggan cek internet, konfirmasi selesai
   ✅ Laporan bisa ditutup
```

--------------------------------

### Customer WhatsApp Commands Examples

Source: https://github.com/alijayanet/gembok-bill/blob/main/README.md

Examples of commands customers can use via WhatsApp for registration, status checks, and menu access. Ensure correct formatting for each command.

```text
REG Budi Santoso
REG 081234567890
DAFTAR Agus Setiawan#08123456789#Jl. Melati No 5#1
```

--------------------------------

### Admin WhatsApp Command Example

Source: https://github.com/alijayanet/gembok-bill/blob/main/README.md

Example of an admin command to save their WhatsApp LID to settings. The admin password must be configured in settings.json.

```text
SETLID admin123
```

--------------------------------

### Manual Mikrotik Address List Setup

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/STATIC_IP_ISOLATION_SYSTEM.md

Optional manual setup for Mikrotik's 'address_list' method. This involves creating an empty address list and associated firewall rules for blocking suspended customers.

```mikrotik
# Buat address list kosong
/ip firewall address-list add list=blocked_customers address=0.0.0.0 comment="Placeholder - will be auto-managed"

# Buat firewall rules
/ip firewall filter add chain=forward src-address-list=blocked_customers action=drop place-before=0
/ip firewall filter add chain=input src-address-list=blocked_customers action=drop
```

--------------------------------

### Run Gembok Bill Application (Development)

Source: https://github.com/alijayanet/gembok-bill/blob/main/README.md

Use this command to start the application in development mode.

```bash
npm run dev
```

--------------------------------

### Check Server Status and Start Node App

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/IMPORT_TROUBLESHOOTING_GUIDE.md

Use these bash commands to check if the server is running on port 3002 and to start the Node.js application if it's not.

```bash
# Cek apakah server berjalan
netstat -ano | findstr :3002

# Jika tidak ada output, start server:
node app.js
```

--------------------------------

### Run Mikrotik Isolation Setup Script

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mikrotik-isolir-setup.md

Execute the uploaded isolation script on the Mikrotik router via SSH.

```bash
# Login ke Mikrotik
ssh admin@192.168.8.1

# Jalankan script
/import file-name=mikrotik-isolir-setup.rsc
```

--------------------------------

### Get PPPoE Help

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/PPPOE_WHATSAPP.md

This command displays comprehensive help information for all available PPPoE commands. It is useful for users who need to understand the full range of functionalities.

```bash
help pppoe
```

--------------------------------

### Verify Mikrotik Isolation Configuration

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mikrotik-isolir-setup.md

Check the static DNS, NAT, and firewall rules to confirm the isolation setup is applied correctly.

```bash
# Cek DNS static
/ip dns static print where name~"alijaya.gantiwifi.online"

# Cek NAT rules
/ip firewall nat print where comment~"isolir"

# Cek Firewall rules
/ip firewall filter print where comment~"isolir"
```

--------------------------------

### Upload Isolation Script to Mikrotik

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mikrotik-isolir-setup.md

Upload the isolation setup script to the Mikrotik device using SCP or by pasting into the terminal.

```bash
# Upload script ke Mikrotik
scp scripts/mikrotik-isolir-setup.rsc admin@192.168.8.1:/tmp/

# Atau copy-paste script ke terminal Mikrotik
```

--------------------------------

### Payment Gateway Configuration

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Example JSON configuration for the Payment Gateway Manager, specifying the active gateway and individual gateway credentials.

```json
{
  "payment_gateway": {
    "active": "midtrans",
    "midtrans": {
      "enabled": true,
      "production": false,
      "server_key": "SB-Mid-server-XXXX",
      "client_key": "SB-Mid-client-XXXX"
    },
    "tripay": {
      "enabled": true,
      "production": false,
      "api_key": "your_tripay_key",
      "private_key": "your_tripay_private_key",
      "merchant_code": "T12345"
    },
    "duitku": { "enabled": false }
  }
}
```

--------------------------------

### Test WhatsApp Connection Script

Source: https://github.com/alijayanet/gembok-bill/blob/main/WHATSAPP_SETUP.md

Command to execute a script for testing the WhatsApp connection. Use this after setup or troubleshooting to verify connectivity.

```bash
node scripts/test-whatsapp-connection.js
```

--------------------------------

### Test Customer Data Successfully Imported

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/IMPORT_TROUBLESHOOTING_GUIDE.md

Example of a single customer record that was successfully imported into the system.

```text
ID: 1027, Name: Test Customer Valid, Phone: 081234567888
```

--------------------------------

### Clone Gembok Bill Repository

Source: https://github.com/alijayanet/gembok-bill/blob/main/README.md

Clone the Gembok Bill repository to your local machine to begin the installation process.

```bash
git clone https://github.com/alijayanet/gembok-bill.git
```

--------------------------------

### Check WhatsApp Version Script

Source: https://github.com/alijayanet/gembok-bill/blob/main/WHATSAPP_FIX_SUMMARY.md

Execute this npm script to check the current WhatsApp Web version. This is an optional but recommended step during installation.

```bash
npm run check-whatsapp-version
```

--------------------------------

### WhatsApp Version Check Output Example

Source: https://github.com/alijayanet/gembok-bill/blob/main/WHATSAPP_FIX_SUMMARY.md

This output shows the result of running a WhatsApp version check script, indicating the latest WhatsApp Web version and the default Baileys version.

```text
🔍 Checking latest WhatsApp Web version..
📱 Latest WhatsApp Web version: 2.3000.1027934701
📦 Default Baileys version: 2.3000.1019707846
✅ Version check completed successfully
```

--------------------------------

### Successful Import Test Results

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/IMPORT_TROUBLESHOOTING_GUIDE.md

Example JSON response indicating a successful import operation, including counts of created, updated, and failed records, along with specific error details.

```json
{
  "success": true,
  "summary": {
    "created": 1,
    "updated": 0,
    "failed": 2
  },
  "errors": [
    {
      "row": 4,
      "error": "Nama/Phone wajib"
    },
    {
      "row": 3,
      "error": "Format nomor telepon tidak valid"
    }
  ]
}
```

--------------------------------

### Isolate and Restore Static IP Customers via WhatsApp

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/STATIC_IP_ISOLATION_SYSTEM.md

Example WhatsApp commands for isolating and restoring static IP customers. These commands trigger the suspension or restoration process based on the customer's phone number.

```text
# Isolir pelanggan IP statik
isolir 081234567890 Telat bayar

# Restore pelanggan IP statik  
restore 081234567890 Sudah bayar
```

--------------------------------

### Correct Excel Headers and Sample Data

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/IMPORT_TROUBLESHOOTING_GUIDE.md

Defines the required header row for the customer import Excel file and provides an example of correctly formatted data.

```excel
Header yang benar:
name | phone | pppoe_username | email | address | package_id | pppoe_profile | status | auto_suspension | billing_day

Contoh data:
John Doe | 081234567890 | john_doe | john@example.com | Jln. Contoh 123 | 1 | default | active | 1 | 15
```

--------------------------------

### Suspend and Restore Static IP Customer via API

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/STATIC_IP_ISOLATION_SYSTEM.md

JavaScript examples for interacting with the Gembok Bill API to suspend and restore static IP customers. These POST requests are made to specific endpoints with a reason for the action.

```javascript
// Suspend static IP customer
POST /admin/billing/service-suspension/suspend/:username
{
  "reason": "Telat bayar"
}

// Restore static IP customer
POST /admin/billing/service-suspension/restore/:username
{
  "reason": "Sudah bayar"
}
```

--------------------------------

### Configure Server Settings

Source: https://github.com/alijayanet/gembok-bill/blob/main/DEPLOY_README.md

Copy the template settings file and edit it with your server-specific configurations.

```bash
# Copy template settings
cp settings.server.template.json settings.json

# Edit settings sesuai server
nano settings.json
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/alijayanet/gembok-bill/blob/main/README.md

Change the current directory to the cloned Gembok Bill project folder.

```bash
cd gembok-bill
```

--------------------------------

### Implement Responsive Images

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mobile-responsive-implementation.md

Use the `srcset` and `sizes` attributes on the `<img>` tag to provide different image sources for various screen sizes and resolutions. This helps optimize loading times by serving appropriately sized images to users.

```html
<!-- Use responsive images -->
<img src="image.jpg" 
     srcset="image-small.jpg 300w, image-medium.jpg 600w, image-large.jpg 900w"
     sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"
     alt="Description">
```

--------------------------------

### Create New PPPoE User

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/PPPOE_WHATSAPP.md

Use this command to create a new PPPoE user. It requires the username, password, and the desired internet package profile. The system then creates the user in MikroTik.

```bash
addpppoe john123 password123 Premium
```

--------------------------------

### Agent Manager - Get Agent Balance

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Retrieves the current balance and last updated timestamp for a specific sales agent.

```APIDOC
## Get Agent Balance

### Description
Fetches the current financial balance and the time of the last update for a given sales agent.

### Method
`getAgentBalance(agentId: string): Promise<AgentBalance>`

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **balance** (number) - The current balance of the agent.
- **last_updated** (string) - The ISO 8601 timestamp of the last balance update.

### Response Example
```json
{
  "balance": 250000,
  "last_updated": "..."
}
```
```

--------------------------------

### BillingManager: Get All Customers

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Retrieves all customer records, including a derived `payment_status` field which can be 'overdue', 'unpaid', 'paid', or 'no_invoice'.

```javascript
// Get all customers with payment_status derived field
const all = await billingManager.getCustomers();
// Each record: { ..., payment_status: 'overdue' | 'unpaid' | 'paid' | 'no_invoice' }
```

--------------------------------

### Verify Production Database Structure

Source: https://github.com/alijayanet/gembok-bill/blob/main/README.md

Run a script to verify the structure of your production database after migrations have been applied.

```bash
node scripts/verify-production-database.js
```

--------------------------------

### Get Device Information

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mobile-responsive-implementation.md

Retrieve device-specific information such as mobile status, touch capability, screen dimensions, pixel ratio, and orientation.

```javascript
const deviceInfo = window.getDeviceInfo();
console.log({
    isMobile: deviceInfo.isMobile,
    isTouch: deviceInfo.isTouch,
    screenWidth: deviceInfo.screenWidth,
    screenHeight: deviceInfo.screenHeight,
    pixelRatio: deviceInfo.pixelRatio,
    orientation: deviceInfo.orientation
});
```

--------------------------------

### Troubleshoot Database Permissions

Source: https://github.com/alijayanet/gembok-bill/blob/main/DEPLOY_README.md

Fix database errors by checking and setting correct file permissions or restoring from a backup.

```bash
# Cek permissions
chmod 755 data/
chmod 644 data/billing.db

# Restore dari backup
cp data/backup/latest.db data/billing.db
```

--------------------------------

### Configure Settings

Source: https://github.com/alijayanet/gembok-bill/blob/main/DEPLOY_CHECKLIST.md

Edit the settings.json file to match the server configuration. This file contains essential server-specific settings.

```bash
# Edit settings.json sesuai server
nano settings.json
```

--------------------------------

### Get Agent Balance

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Retrieves the current balance and last updated timestamp for a given agent ID. Requires the agent's ID to be known.

```javascript
// Get agent balance
const balance = await agentManager.getAgentBalance(agent.id);
// → { balance: 250000, last_updated: '...' }
```

--------------------------------

### Create Agent with AgentManager

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Initializes the AgentManager and creates a new sales agent with specified details including commission rate. The agent's ID is returned upon successful creation.

```javascript
const AgentManager = require('./config/agentManager');
const agentManager = new AgentManager();

// Create agent
const agent = await agentManager.createAgent({
  username: 'agent_andi',
  name: 'Andi Wijaya',
  phone: '6281999888777',
  password: 'secure_password',
  commission_rate: 5.00
});
```

--------------------------------

### Troubleshooting: Test WhatsApp Connection

Source: https://github.com/alijayanet/gembok-bill/blob/main/WHATSAPP_FIX_SUMMARY.md

Run this command to test the WhatsApp connection independently, which can help diagnose persistent issues.

```bash
npm run test-whatsapp-connection
```

--------------------------------

### Test Frontend Device and Customer Lookup

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/genieacs-mapping-integration.md

This JavaScript code snippet demonstrates how to test the frontend logic for finding a customer associated with a device. It simulates a device object and calls a function to find the customer.

```javascript
// Test coordinate mapping
const testDevice = {
  pppoeUsername: 'testuser',
  Tags: ['6281947215703'],
  DeviceID: { SerialNumber: 'TEST123' }
};

// Test customer search priority
const customer = await findCustomerForDevice(testDevice);
console.log('Found customer:', customer);
```

--------------------------------

### Run Unit Tests for Utility Functions

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/network-mapping-features.md

Executes unit tests for the mapping utility functions using npm. Ensure the test file path is correct.

```bash
# Test utility functions
npm test utils/mappingUtils.test.js
```

--------------------------------

### Run Database Migrations

Source: https://github.com/alijayanet/gembok-bill/blob/main/README.md

Execute all database migration scripts to ensure the database schema is up-to-date. This is important for new servers and updates.

```bash
node scripts/run-all-migrations.js
```

--------------------------------

### Run Database Migration Script

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/STATIC_IP_ISOLATION_SYSTEM.md

Command to execute the Node.js script for adding static IP-related fields to the database. This is a prerequisite for using the static IP isolation features.

```bash
node scripts/add-static-ip-fields.js
```

--------------------------------

### Mobile-First CSS Approach

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mobile-responsive-implementation.md

Implement a mobile-first CSS strategy by defining base styles for mobile and then using media queries to add styles for larger screens.

```css
/* Start with mobile styles */
.element { /* Mobile styles */ }

/* Then add larger screen styles */
@media (min-width: 769px) {
    .element { /* Desktop styles */ }
}
```

--------------------------------

### Create Balance Top-up Request

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Initiates a request for a balance top-up for a specific agent. The amount requested is specified in the call.

```javascript
// Request balance top-up
await agentManager.createBalanceRequest(agent.id, 100000);
```

--------------------------------

### Test Full WhatsApp Integration Flow

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/WHATSAPP_MODULAR_README.md

Tests the complete integration flow by connecting to WhatsApp. This requires the 'whatsapp-new' module to be correctly set up.

```javascript
const whatsapp = require('./whatsapp-new');
await whatsapp.connectToWhatsApp();
```

--------------------------------

### Run GEMBOK-BILL Application

Source: https://github.com/alijayanet/gembok-bill/blob/main/DEPLOY_README.md

Commands to run the application in development, production, or using PM2 for process management.

```bash
# Development
npm run dev

# Production
npm start

# Atau dengan PM2
pm2 start app.js --name gembok-bill
pm2 save
pm2 startup
```

--------------------------------

### Troubleshoot Isolation Page Not Appearing

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mikrotik-isolir-setup.md

If the isolation page does not load, check the static DNS configuration and ensure the application is running on the correct port.

```bash
# Cek DNS static
/ip dns static print where name~"alijaya.gantiwifi.online"

# Cek aplikasi berjalan di port 3003
netstat -tlnp | grep 3003
```

--------------------------------

### Connect to WhatsApp and Send Message

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Connects to WhatsApp using provided configuration and sends a message to a specified phone number. Ensure the whatsapp module is correctly configured.

```javascript
// config/whatsapp.js — Connect to WhatsApp (called by app.js)
const whatsapp = require('./config/whatsapp');
const sock = await whatsapp.connectToWhatsApp();
whatsapp.setSock(sock);

// Send a message programmatically
await whatsapp.sendMessage('6281234567890', 'Tagihan Anda jatuh tempo besok: Rp 150.000');

// Check connection status
const status = whatsapp.getWhatsAppStatus();
// → { connected: true, phoneNumber: '628...', connectedSince: '2025-01-15T08:00:00Z', status: 'open' }
```

--------------------------------

### Settings Manager

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Provides methods to read and write system settings from a `settings.json` file with caching.

```APIDOC
## Settings Manager — `getSetting` / `setSetting`

Reads and writes a flat/nested `settings.json` file with a 5-second in-memory cache, supporting both dot-notation nested keys and direct flat keys with the same call signature.

```js
const { getSetting, setSetting, getSettingsWithCache } = require('./config/settingsManager');

// Read a flat key with a default
const port = getSetting('server_port', 4555);              // → 4555

// Read a nested key (telegram_bot.enabled)
const telegramEnabled = getSetting('telegram_bot.enabled', false);

// Read an array-index style key (admins.0)
const primaryAdmin = getSetting('admins.0', '6281234567890');

// Write a key back to settings.json (invalidates cache)
setSetting('server_port', 3000);

// Read full settings object (cached)
const all = getSettingsWithCache();
console.log(all.company_header);  // → "GEMBOK-BILL"
```
```

--------------------------------

### Clone GEMBOK-BILL Repository

Source: https://github.com/alijayanet/gembok-bill/blob/main/DEPLOY_README.md

Clone the official GEMBOK-BILL repository and navigate into the project directory.

```bash
git clone https://github.com/alijayanet/gembok-bill
cd gembok-bill
```

--------------------------------

### Run Application

Source: https://github.com/alijayanet/gembok-bill/blob/main/DEPLOY_CHECKLIST.md

Commands to run the application in development or production mode. PM2 can be used for production process management.

```bash
# Development
npm run dev

# Production
npm start

# Atau dengan PM2
pm2 start app.js --name gembok-bill
```

--------------------------------

### Troubleshooting PPPoE User Login Issues

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/PPPOE_WHATSAPP.md

This command is used to check the status of a PPPoE user, which is helpful when troubleshooting login problems. It requires the username as an argument.

```bash
checkpppoe [username]
```

--------------------------------

### Check Database Schema Script

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/collector-payment-fix-complete.md

Use this script to verify the database schema after applying fixes.

```bash
node scripts/check-database-schema.js
```

--------------------------------

### BillingManager: Create Customer

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Creates a new customer record in the database, automatically generating a username and PPPoE username. Requires customer details including name, phone, address, package, and network mapping.

```javascript
const billingManager = require('./config/billing');

// Create a new customer (auto-generates username + PPPoE username)
const customer = await billingManager.createCustomer({
  name: 'Budi Santoso',
  phone: '081234567890',
  pppoe_username: 'budi_pppoe',
  email: 'budi@example.com',
  address: 'Jl. Melati No 5',
  package_id: 1,
  odp_id: 3,
  pppoe_profile: '10Mbps',
  status: 'active',
  billing_day: 1,
  latitude: -6.2088,
  longitude: 106.8456,
  cable_type: 'Fiber Optic',
  port_number: 4
});
// → { id: 42, username: 'cust_7890_...', name: 'Budi Santoso', ... }
```

--------------------------------

### Troubleshoot User Internet Access

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mikrotik-isolir-setup.md

If users can still access the internet, verify the firewall and NAT rules related to isolation.

```bash
# Cek firewall rules
/ip firewall filter print where comment~"isolir"

# Cek NAT rules
/ip firewall nat print where comment~"isolir"
```

--------------------------------

### Create Online Payment Endpoint

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Initiates the creation of an online payment for a given invoice ID using a specified payment gateway. Requires a POST request with JSON payload.

```bash
# Create an online payment
curl -X POST http://localhost:4555/payment/create \
  -H "Content-Type: application/json" \
  -d '{"invoice_id": 101, "gateway": "midtrans"}'
# → {"success":true,"data":{"payment_url":"https://...","token":"..."}}
```

--------------------------------

### Run Integration Tests for API Endpoints

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/network-mapping-features.md

Executes integration tests for API endpoints using npm. Verify the test file path for accuracy.

```bash
# Test API endpoints
npm test routes/adminBilling.test.js
```

--------------------------------

### Test Import with Node.js Script

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/IMPORT_TROUBLESHOOTING_GUIDE.md

A Node.js script using Axios and Form-Data to automate the customer import process by logging in and sending an Excel file.

```javascript
// Buat file test_import.js
const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');

async function testImport() {
    // Login
    const loginResponse = await axios.post('http://localhost:3002/admin/login', {
        username: 'admin',
        password: 'admin'
    });
    
    const cookies = loginResponse.headers['set-cookie'];
    
    // Import
    const formData = new FormData();
    formData.append('file', fs.readFileSync('your_file.xlsx'));
    
    const response = await axios.post('http://localhost:3002/admin/billing/import/customers/xlsx', formData, {
        headers: {
            ...formData.getHeaders(),
            'Cookie': cookies.join('; ')
        }
    });
    
    console.log(response.data);
}

testImport();
```

--------------------------------

### Expected Log Output for Voucher Payment

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/UNIVERSAL_WEBHOOK_CONFIGURATION.md

This shows the expected log output when the universal webhook successfully detects and redirects a voucher payment. It confirms receipt, detection of a voucher payment, and the subsequent voucher webhook handling.

```text
🔍 Universal webhook received: {...}
🎫 Detected voucher payment, redirecting to voucher webhook handler
🎫 Voucher webhook response: {...}
```

--------------------------------

### SQL Schema for Voucher Packages

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/VOUCHER_PACKAGE_NAME_FIX.md

Defines a new table to store dedicated voucher package information, including price, duration, and profile. This table is intended for future use to manage voucher offerings systematically.

```sql
CREATE TABLE voucher_packages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    package_id TEXT UNIQUE NOT NULL, -- '3k', '5k', '10k', etc.
    name TEXT NOT NULL, -- '3rb - 1 Hari', '5rb - 2 Hari', etc.
    price DECIMAL(10,2) NOT NULL,
    duration TEXT NOT NULL, -- '1 hari', '2 hari', etc.
    profile TEXT NOT NULL, -- Mikrotik profile
    enabled BOOLEAN DEFAULT 1
);
```

--------------------------------

### Agent Manager - Create Agent

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Creates a new sales agent within the system. This involves setting up their credentials, commission rate, and contact information.

```APIDOC
## Create Agent

### Description
Registers a new sales agent in the system, enabling them to sell vouchers and manage payments.

### Method
`createAgent(agentData: object): Promise<Agent>`

### Parameters
#### Request Body
- **username** (string) - Required - Unique username for the agent.
- **name** (string) - Required - Full name of the agent.
- **phone** (string) - Required - Agent's contact phone number.
- **password** (string) - Required - Agent's login password.
- **commission_rate** (number) - Required - The commission percentage the agent earns on sales.

### Request Example
```js
const agent = await agentManager.createAgent({
  username: 'agent_andi',
  name: 'Andi Wijaya',
  phone: '6281999888777',
  password: 'secure_password',
  commission_rate: 5.00
});
```
```

--------------------------------

### Troubleshoot Bandwidth Not Limited

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mikrotik-isolir-setup.md

If bandwidth is not limited for isolated users, check the queue tree and mangle rules.

```bash
# Cek queue tree
/queue tree print where name~"isolir"

# Cek mangle rules
/ip firewall mangle print where comment~"isolir"
```

--------------------------------

### Create and Manage Invoices with BillingManager

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Use BillingManager to create monthly or voucher invoices, record manual payments, initiate online payments, and handle payment webhooks. Requires customer and package details for invoice creation.

```javascript
const invoice = await billingManager.createInvoice({
  customer_id: 42,
  package_id: 1,
  amount: 150000,
  base_amount: 135135,
  tax_rate: 11.00,
  due_date: '2025-02-01',
  invoice_type: 'monthly',   // or 'voucher'
  notes: 'January 2025'
});
```

```javascript
const result = await billingManager.processManualPayment(
  101,          // invoiceId
  150000,       // amount
  'cash',       // method: cash | bank_transfer | online
  'TRF-001',    // reference
  'Paid at counter'
);
```

```javascript
const paymentLink = await billingManager.createOnlinePayment(101, 'midtrans');
```

```javascript
await billingManager.handlePaymentWebhook({ body: req.body, headers: req.headers }, 'midtrans');
```

--------------------------------

### Restart PPPoE Connection

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/PPPOE_WHATSAPP.md

Use this command to restart a user's PPPoE connection. It requires the username as an argument and provides feedback on the restart status, including the username and timestamp.

```bash
restartpppoe [username]
```

```text
🔄 KONEKSI PPPoE BERHASIL DIRESTART

👤 Username: john123
🕒 Restart Pada: 15/12/2024 17:15:30

💡 Langkah Selanjutnya:
1. Tunggu 30-60 detik untuk koneksi stabil
2. Test koneksi internet
3. Verifikasi speed sesuai profile
4. Update status di trouble report jika ada
```

--------------------------------

### Agent Manager - Create Balance Request

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Allows an agent to request a top-up for their balance. This initiates a process for administrative approval and fund allocation.

```APIDOC
## Create Balance Request

### Description
Submits a request for an agent to have their account balance topped up.

### Method
`createBalanceRequest(agentId: string, amount: number): Promise<void>`

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent making the request.
#### Request Body
- **amount** (number) - Required - The amount the agent wishes to add to their balance.

### Request Example
```js
await agentManager.createBalanceRequest(agent.id, 100000);
```
```

--------------------------------

### Troubleshoot Dependencies Error

Source: https://github.com/alijayanet/gembok-bill/blob/main/DEPLOY_README.md

Resolve dependency issues by clearing the npm cache and reinstalling packages.

```bash
# Clear cache dan install ulang
rm -rf node_modules package-lock.json
npm install
```

--------------------------------

### Test Collector Payment Script

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/collector-payment-fix-complete.md

Run this script to test the payment recording functionality after applying the fixes.

```bash
node scripts/test-collector-payment.js
```

--------------------------------

### Configure Static IP Suspension Method

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/STATIC_IP_ISOLATION_SYSTEM.md

JSON configuration for the Gembok Bill system, specifying the method for suspending static IP customers. The 'address_list' method is recommended for its efficiency.

```json
{
  "static_ip_suspension_method": "address_list",
  "suspension_bandwidth_limit": "1k/1k",
  "isolir_profile": "isolir"
}
```

--------------------------------

### Edit PPPoE User Profile

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/PPPOE_WHATSAPP.md

Use this command to upgrade a user's internet package profile. It requires the username and the new profile name (e.g., VIP, Premium). The system updates the profile in MikroTik.

```bash
editpppoe john123 profile VIP
```

--------------------------------

### Resource Preloading for Mobile

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mobile-responsive-implementation.md

Preload critical CSS and JavaScript resources for mobile devices to improve initial load performance.

```html
<link rel="preload" href="/css/responsive.css" as="style">
<link rel="preload" href="/js/mobile-utils.js" as="script">
```

--------------------------------

### Test Voucher Payment

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/DUAL_PAYMENT_SYSTEM_FIX.md

Steps to test the voucher payment flow after the fix. This involves simulating a voucher purchase and verifying the correct redirection to the voucher finish page.

```bash
# 1. Buka halaman /voucher
# 2. Pilih paket voucher dan payment method
# 3. Bayar via payment gateway
# 4. Cek apakah redirect ke /voucher/finish
```

--------------------------------

### Monitor Universal Webhook Logs

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/UNIVERSAL_WEBHOOK_CONFIGURATION.md

This bash command monitors the application log file (`logs/app.log`) in real-time, filtering for messages related to the universal webhook, voucher detection, or invoice processing. Useful for debugging.

```bash
# Monitor log saat payment dilakukan
tail -f logs/app.log | grep -E "(Universal webhook|Detected voucher|Processing invoice)"
```

--------------------------------

### Contribute to Gembok Bill: Feature Branch Workflow

Source: https://github.com/alijayanet/gembok-bill/blob/main/README.md

Steps to contribute code by forking the repository, creating a feature branch, committing changes, and opening a Pull Request.

```git
git checkout -b feature/AmazingFeature
```

```git
git commit -m 'Add some AmazingFeature'
```

```git
git push origin feature/AmazingFeature
```

--------------------------------

### Callback URL Configuration for Tripay

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/UNIVERSAL_WEBHOOK_CONFIGURATION.md

This configuration snippet shows how to set the `callback_url` for Tripay payments. It ensures that both invoice and voucher payments are directed to the same universal webhook endpoint. The `return_url` is conditionally set based on the payment type.

```javascript
// Semua payment (invoice + voucher) menggunakan callback URL yang sama
callback_url: `${appBaseUrl}/payment/webhook/tripay`,
return_url: paymentType === 'voucher' ? `${appBaseUrl}/voucher/finish` : `${appBaseUrl}/payment/finish`
```

--------------------------------

### Logging Payment Type and Gateway

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/DUAL_PAYMENT_SYSTEM_FIX.md

This code snippet shows how to log the payment type and gateway being used during payment creation. This is helpful for debugging and monitoring payment processes.

```javascript
console.log(`[PAYMENT] Creating ${paymentType} payment with ${gateway}`);
```

--------------------------------

### Settings Manager: Read and Write Settings

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Reads and writes settings from a flat/nested settings.json file with an in-memory cache. Supports dot-notation for nested keys and array indices. Cache is invalidated on write.

```javascript
const { getSetting, setSetting, getSettingsWithCache } = require('./config/settingsManager');

// Read a flat key with a default
const port = getSetting('server_port', 4555);              // → 4555

// Read a nested key (telegram_bot.enabled)
const telegramEnabled = getSetting('telegram_bot.enabled', false);

// Read an array-index style key (admins.0)
const primaryAdmin = getSetting('admins.0', '6281234567890');

// Write a key back to settings.json (invalidates cache)
setSetting('server_port', 3000);

// Read full settings object (cached)
const all = getSettingsWithCache();
console.log(all.company_header);  // → "GEMBOK-BILL"
```

--------------------------------

### Check Existing PPPoE User

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/PPPOE_WHATSAPP.md

This command is used to check the status and details of an existing PPPoE user. It is a prerequisite for operations like upgrading or deleting a user.

```bash
checkpppoe john123
```

--------------------------------

### Troubleshooting: Update Baileys Dependencies

Source: https://github.com/alijayanet/gembok-bill/blob/main/WHATSAPP_FIX_SUMMARY.md

If connection problems continue, try updating the Baileys library to its latest version using this command.

```bash
npm update @whiskeysockets/baileys
```

--------------------------------

### Test Voucher Payment Webhook

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/UNIVERSAL_WEBHOOK_CONFIGURATION.md

This `curl` command simulates an incoming webhook request for a voucher payment. It sends a POST request to the universal webhook URL with a sample JSON payload, including a voucher-like `order_id` containing 'VCR-'.

```bash
# Test voucher payment
curl -X POST https://alijaya.gantiwifi.online/payment/webhook/tripay \
  -H "Content-Type: application/json" \
  -d '{ 
    "order_id": "INV-INV-VCR-1757172817359-44",
    "status": "success",
    "amount": 10000,
    "payment_type": "tripay"
  }'
```

--------------------------------

### Modify TripayGateway createPaymentWithMethod for Return URL

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/DUAL_PAYMENT_SYSTEM_FIX.md

Update the `createPaymentWithMethod` method in `TripayGateway` to dynamically set the `return_url` based on the `paymentType`. This ensures correct redirection after payment completion.

```javascript
async createPaymentWithMethod(invoice, method, paymentType = 'invoice') {
    // ...
    return_url: paymentType === 'voucher' ? `${appBaseUrl}/voucher/finish` : `${appBaseUrl}/payment/finish`
}
```

--------------------------------

### Test Individual WhatsApp Modules

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/WHATSAPP_MODULAR_README.md

Tests core functionality, command handling, and message processing for individual WhatsApp modules. Ensure modules are correctly initialized before testing.

```javascript
const core = new WhatsAppCore();
console.log(core.isAdminNumber('628123456789'));
```

```javascript
const commands = new WhatsAppCommands(core);
await commands.handleStatus('test@jid');
```

```javascript
const handlers = new WhatsAppMessageHandlers(core, commands);
await handlers.processMessage('test@jid', '628123456789', 'status', true);
```

--------------------------------

### GenieACS Device Management

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Wraps the GenieACS NBI REST API for querying devices, managing tags, setting TR-069 parameters, and performing device actions like rebooting or factory resets. Requires configuration from './config/genieacs'.

```javascript
const genieacs = require('./config/genieacs');

// Find a device by the customer's phone tag
const device = await genieacs.findDeviceByPhoneNumber('6281234567890');
// → { _id: 'InternetGatewayDevice-...', _tags: ['6281234567890'], ... }

// Find device by PPPoE username
const device2 = await genieacs.findDeviceByPPPoE('budi_pppoe');

// Add a phone tag to a device (called automatically on customer create/update)
await genieacs.addTagToDevice(device._id, '6281234567890');

// Remove tag (called on customer delete/phone change)
await genieacs.removeTagFromDevice(device._id, '6281234567890');

// Push a TR-069 parameter value (e.g., block internet via firewall rule)
await genieacs.setParameterValues(device._id, [
  ['InternetGatewayDevice.X_CUSTOM.Blocked', true, 'xsd:boolean']
]);

// Get all managed devices (2-minute cache)
const allDevices = await genieacs.getDevices();
```

--------------------------------

### Generate Icons with JavaScript

Source: https://github.com/alijayanet/gembok-bill/blob/main/public/icons/generate-icons.html

Use this JavaScript code to create a base icon on a canvas, then generate and download multiple sizes. Ensure the HTML has a canvas element with the ID 'canvas'.

```javascript
const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');

// Create gradient background
const gradient = ctx.createLinearGradient(0, 0, 512, 512);
gradient.addColorStop(0, '#28a745');
gradient.addColorStop(1, '#20c997');

// Draw background
ctx.fillStyle = gradient;
ctx.fillRect(0, 0, 512, 512);

// Draw circle
ctx.fillStyle = 'rgba(255, 255, 255, 0.9)';
ctx.beginPath();
ctx.arc(256, 180, 60, 0, 2 * Math.PI);
ctx.fill();

// Draw money emoji
ctx.font = '80px Arial';
ctx.fillStyle = '#28a745';
ctx.textAlign = 'center';
ctx.fillText('💰', 256, 200);

// Draw letter C
ctx.font = 'bold 200px Arial';
ctx.fillStyle = 'white';
ctx.fillText('C', 256, 320);

// Convert to different sizes and download
const sizes = [16, 32, 72, 96, 128, 144, 152, 192, 384, 512];
sizes.forEach(size => {
  const tempCanvas = document.createElement('canvas');
  tempCanvas.width = size;
  tempCanvas.height = size;
  const tempCtx = tempCanvas.getContext('2d');
  tempCtx.drawImage(canvas, 0, 0, size, size);
  const link = document.createElement('a');
  link.download = 'icon-' + size + 'x' + size + '.png';
  link.href = tempCanvas.toDataURL();
  link.click();
});

console.log('Icons generated successfully!');
```

--------------------------------

### Check Database for Latest Customers

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/IMPORT_TROUBLESHOOTING_GUIDE.md

A Node.js script using sqlite3 to query and display the 10 most recent customers from the billing database.

```javascript
// Buat file check_db.js
const sqlite3 = require('sqlite3').verbose();
const db = new sqlite3.Database('./data/billing.db');

db.all('SELECT id, username, name, phone FROM customers ORDER BY id DESC LIMIT 10', (err, rows) => {
    if (err) console.error(err);
    else {
        console.log('Latest customers:');
        rows.forEach(row => console.log(row));
    }
    db.close();
});
```

--------------------------------

### Gembok Bill Project Structure

Source: https://github.com/alijayanet/gembok-bill/blob/main/README.md

Overview of the directory and file structure for the Gembok Bill project.

```tree
gembok-bill/
├── app.js                  # Application entry point
├── package.json            # Dependencies and scripts
├── config/                 # Configuration files
├── data/                   # Database files and backups
├── migrations/             # Database migration files
├── public/                 # Static files (CSS, JS, images)
├── routes/                 # API endpoints
├── scripts/                # Utility scripts
├── utils/                  # Utility functions
└── views/                  # EJS templates
```

--------------------------------

### Manage MikroTik Routers and PPPoE Secrets

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Integrate with MikroTik routers using `node-routeros` for multi-router support. Functions include establishing connections, adding PPPoE secrets, and modifying PPPoE profiles.

```javascript
const { getMikrotikConnection, addPPPoESecret, setPPPoEProfile,
        addHotspotUser, getActivePPPoEConnections } = require('./config/mikrotik');

// Get connection (auto-selects router by routerId, falls back to legacy config)
const conn = await getMikrotikConnection('router_main');
```

```javascript
// Add a new PPPoE secret
await addPPPoESecret({
  name: 'budi_pppoe',
  password: 'pass123',
  profile: '10Mbps',
  comment: 'Customer Budi Santoso'
}, 'router_main');
```

```javascript
// Change PPPoE profile (used for suspension/restore)
await setPPPoEProfile('budi_pppoe', 'isolir', 'router_main');
await setPPPoEProfile('budi_pppoe', '10Mbps', 'router_main'); // restore
```

```javascript
// List active PPPoE connections
const active = await getActivePPPoEConnections('router_main');
```

```javascript
// Add hotspot user (for voucher system)
await addHotspotUser({ name: 'voucher_abc123', password: 'abc123', profile: '1hr' }, 'router_main');
```

--------------------------------

### Create Online Payment

Source: https://context7.com/alijayanet/gembok-bill/llms.txt

Initiates the creation of an online payment for a given invoice using a specified payment gateway.

```APIDOC
## Create Online Payment

### Description
Generates a payment URL and token for an invoice using a selected payment gateway.

### Method
`POST /payment/create`

### Endpoint
`/payment/create`

### Parameters
#### Request Body
- **invoice_id** (integer) - Required - The ID of the invoice to be paid.
- **gateway** (string) - Required - The payment gateway to use (e.g., 'midtrans').

### Request Example
```json
{
  "invoice_id": 101,
  "gateway": "midtrans"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the payment creation was successful.
- **data** (object) - Contains payment details.
  - **payment_url** (string) - The URL for the customer to complete the payment.
  - **token** (string) - A token associated with the payment transaction.

### Response Example
```json
{
  "success": true,
  "data": {
    "payment_url": "https://...",
    "token": "..."
  }
}
```
```

--------------------------------

### Run Performance Tests

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/network-mapping-features.md

Executes performance tests, typically for large datasets, using a custom npm script. Ensure the script is defined in package.json.

```bash
# Test with large datasets
npm run test:performance
```

--------------------------------

### Monitor Performance Metrics

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mobile-responsive-implementation.md

Log mobile performance metrics, specifically the page load time, using the PerformanceNavigationTiming API.

```javascript
// Mobile performance metrics
const performance = window.performance;
const navigation = performance.getEntriesByType('navigation')[0];
console.log('Page Load Time:', navigation.loadEventEnd - navigation.loadEventStart);
```

--------------------------------

### Upload Mikrotik Isolation Removal Script

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/mikrotik-isolir-setup.md

Upload the script to remove the isolation configuration from Mikrotik.

```bash
# Upload script remove
scp scripts/mikrotik-isolir-remove.rsc admin@192.168.8.1:/tmp/

# Jalankan script
/import file-name=mikrotik-isolir-remove.rsc
```

--------------------------------

### Enable Debug Logging for WhatsApp Modules

Source: https://github.com/alijayanet/gembok-bill/blob/main/docs/WHATSAPP_MODULAR_README.md

Enables debug logging for all WhatsApp-related modules by setting the DEBUG environment variable. This is useful for troubleshooting connection and module status issues.

```javascript
process.env.DEBUG = 'whatsapp:*';
```

```javascript
console.log(whatsapp.whatsappCore.getWhatsAppStatus());
```

```javascript
console.log(whatsapp.whatsappCommands.getSock());
```

--------------------------------

### Fetch Latest Baileys Version in Socket Configuration

Source: https://github.com/alijayanet/gembok-bill/blob/main/WHATSAPP_FIX_SUMMARY.md

This code snippet demonstrates how to dynamically fetch the latest compatible WhatsApp Web version for Baileys. It includes a fallback version in case the fetch operation fails.

```javascript
const { fetchLatestBaileysVersion } = require('@whiskeysockets/baileys');

// In socket configuration:
version: await fetchLatestBaileysVersion().catch(() => [2, 3000, 1023223821])
```