### Manual Installation (Linux/macOS)

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/INSTALL.md

Steps for manual extraction and permission setting on Linux/macOS if scripts are not used. Ensure correct paths and execute permissions.

```bash
unzip whmcs-reseller-module-v1.0.0.zip -d /path/to/whmcs/
```

```bash
tar -xzf whmcs-reseller-module-v1.0.0.tar.gz -C /path/to/whmcs/
```

```bash
chmod -R 755 /path/to/whmcs/modules/servers/products_reseller_server
```

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

### Install WHMCS Reseller Module (Linux/macOS)

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Use this script to install the module ZIP. It auto-detects the WHMCS path. Ensure the script is executable.

```bash
chmod +x install.sh
./install.sh -f whmcs-reseller-module-v1.0.0.zip
```

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

### Troubleshooting Script Execution (Linux/macOS)

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/INSTALL.md

Command to make the installation script executable on Linux/macOS if it fails to run. Ensure the script has execute permissions before running.

```bash
# Make script executable
chmod +x install.sh

# Then run
./install.sh -f whmcs-reseller-module-v1.0.0.zip
```

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

### Install WHMCS Reseller Module with Options (Linux/macOS)

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Install the module specifying the WHMCS path, ZIP file, and enabling SHA256 verification. Provide the checksum for verification.

```bash
./install.sh \
  -p /var/www/html/whmcs \
  -f whmcs-reseller-module-v1.0.0.zip \
  -v \
  -s "abcd1234ef567890abcd1234ef567890abcd1234ef567890abcd1234ef567890"
```

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

### Example of Released Package Structure

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/SETUP_COMPLETE.md

This shows the expected structure of the downloaded release package. Only the 'modules/' directory is included, along with SHA256 checksum files for verification.

```tree
whmcs-reseller-module-v1.0.1.zip
├── modules/
│   └── servers/
│       └── products_reseller_server/
│           ├── ajax_functions.php
│           ├── hooks.php
│           ├── pr_server_classes.php
│           ├── products_reseller_server.php
│           ├── whmcs.json
│           ├── hooks/
│           ├── images/
│           └── templates/

+ SHA256 checksum files for verification
```

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

### Install WHMCS Reseller Module (Windows)

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/INSTALL.md

This batch script automates installation on Windows. It detects WHMCS paths, creates backups, and uses PowerShell for extraction. Requires Windows 7+ and PowerShell 3.0+.

```batch
install.bat -f whmcs-reseller-module-v1.0.0.zip
```

```batch
install.bat -p "C:\whmcs" -f whmcs-reseller-module-v1.0.0.zip
```

```batch
install.bat -h
```

```batch
install.bat -f whmcs-reseller-module-v1.0.0.zip
```

```batch
install.bat -p "D:\hosting\whmcs" -f whmcs-reseller-module-v1.0.0.zip
```

```batch
REM Right-click Command Prompt -> Run as Administrator, then:
install.bat -p "C:\whmcs" -f whmcs-reseller-module-v1.0.0.zip
```

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

### Semantic Versioning Examples

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_QUICK_REFERENCE.md

Illustrates semantic versioning (SemVer) for release numbering, including standard releases, pre-releases, and their corresponding patch, minor, and major version increments.

```text
v1.0.0 - Initial release
v1.0.1 - Bug fix (patch)
v1.1.0 - New feature (minor)
v2.0.0 - Breaking change (major)

Pre-releases:
v1.1.0-alpha.1
v1.1.0-beta.1
v1.1.0-rc.1
```

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

### cURL POST Request Example

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/API.md

Example of how to make a POST request to the Avalon reseller API endpoint using cURL, including the JSON payload.

```bash
curl -X POST "https://your-api-endpoint/modules/addons/products_reseller/api.php" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "action": "CreateAccount",
    "params": {
      "serviceid": 123,
      "server_id": 1,
      "domain": "example.com",
      "username": "exampleuser"
    }
  }'
```

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

### Install WHMCS Reseller Module (Linux/macOS)

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/INSTALL.md

Use this bash script for automated installation on Linux/macOS. It detects WHMCS, verifies integrity, backs up, and sets permissions. Requires bash, unzip/tar, and standard Unix utilities.

```bash
./install.sh -f whmcs-reseller-module-v1.0.0.zip
```

```bash
./install.sh -p /var/www/whmcs -f whmcs-reseller-module-v1.0.0.zip
```

```bash
./install.sh -f whmcs-reseller-module-v1.0.0.zip -v -s abc123def456...
```

```bash
./install.sh -h
```

```bash
chmod +x install.sh
./install.sh -f whmcs-reseller-module-v1.0.0.zip
```

```bash
./install.sh -f whmcs-reseller-module-v1.0.0.zip -v
```

```bash
./install.sh \
  -p /home/hostingco/public_html \
  -f whmcs-reseller-module-v1.0.0.zip \
  -v \
  -s "abcd1234efgh5678..."
```

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

### Install WHMCS Reseller Module (Windows)

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Use PowerShell to extract the module ZIP file to the specified WHMCS directory. Ensure the System.IO.Compression.FileSystem assembly is loaded.

```powershell
Add-Type -AssemblyName 'System.IO.Compression.FileSystem'
[System.IO.Compression.ZipFile]::ExtractToDirectory(
    'C:\path\to\whmcs-reseller-module-v1.0.0.zip',
    'C:\inetpub\wwwroot\whmcs'
)
```

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

### Manual Installation (Windows PowerShell)

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/INSTALL.md

Use PowerShell for manual extraction of the ZIP package on Windows. Ensure the correct paths for the package and WHMCS root directory.

```powershell
Add-Type -AssemblyName 'System.IO.Compression.FileSystem'
[System.IO.Compression.ZipFile]::ExtractToDirectory('C:\path\to\whmcs-reseller-module-v1.0.0.zip', 'C:\path\to\whmcs')
```

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

### Verify Signed Commits

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/SETUP_COMPLETE.md

These are examples of verified signed commits. Ensure all your contributions have similar verification.

```git
✓ 794c897 - Add release quick reference guide
✓ 2d55175 - Add automated release workflow and installation helpers
✓ 6478b78 - Initial commit: WHMCS Reseller Module v1.0.0
```

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

### View Commits Since Last Tag

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_QUICK_REFERENCE.md

Use this command to view a concise list of commits made since the last tagged release. Ensure you have Git installed and are in the repository's root directory.

```bash
git log v1.0.0..HEAD --oneline
```

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

### Provision New Service with cURL

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Shows how to provision a new hosting account by sending a POST request to the upstream API with the 'CreateAccount' action. This is triggered by WHMCS on order activation.

```bash
curl -X POST "https://node1.avalon.hosting/reseller/modules/addons/products_reseller/api.php" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_abc123",
    "action": "CreateAccount",
    "params": {
      "serviceid":        1001,
      "billingcycle":     "monthly",
      "qty":              1,
      "domain":           "clientsite.com",
      "username":         "clientsite",
      "password":         "Str0ngP@ss!",
      "ip_address":       "",
      "selected_product": 42,
      "server_id":        1
    }
  }'
```

```json
# Successful upstream response:
# { "status": "success", "data": { "serviceid": 1001 }, "message": "Account created" }
```

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

### Create and Push Pre-release Tag

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_PROCESS.md

Create a signed, annotated tag for a pre-release version (e.g., beta) and push it to the remote repository.

```bash
git tag -s v1.1.0-beta.1 -m "Beta release"
git push origin v1.1.0-beta.1
```

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

### Create and Push Lightweight Release Tag

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_PROCESS.md

Create a lightweight tag for a release and push it to the remote repository to trigger the release workflow.

```bash
# Create a lightweight tag
git tag v1.0.0

# Push the tag
git push origin v1.0.0
```

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

### Create and Commit Changes

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_QUICK_REFERENCE.md

Use these commands to create a new feature branch, make changes, sign your commits, and push them to your fork. All commits must be signed for pull requests.

```bash
git checkout -b feature/your-feature

# Make your changes
# ... edit files ...

# Commit with signature (REQUIRED)
git commit -S -m "Your commit message"

# Push to your fork
git push origin feature/your-feature
```

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

### products_reseller_server_ConfigOptions

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Builds the WHMCS module configuration form for product settings. It fetches the live product list from the upstream API and returns a products dropdown and toggles for displaying service details.

```APIDOC
## `products_reseller_server_ConfigOptions($params)` — Product dropdown config

Builds the WHMCS module configuration form shown on the Product edit screen. It fetches the live product list from the upstream API and returns a `products` dropdown (mapped to `configoption1`) plus five yes/no toggles controlling which service details (server name, hostname, domain, IP, username, password) are displayed in the client area for non-cPanel products.

```php
// Config option keys used elsewhere in the module:
// configoption1 => selected upstream product ID
// configoption2 => show_server_name  (on/off)
// configoption3 => show_host_name    (on/off)
// configoption4 => show_domain       (on/off)
// configoption5 => show_ip           (on/off)
// configoption6 => show_username     (on/off)
// configoption7 => show_password     (on/off)

// Example: read the mapped product ID inside another module function
$upstreamProductId = (int) $params['configoption1'];  // e.g. 42
$showDomain        = $params['configoption4'] === 'on'; // true/false
```
```

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

### Create a Signed Release Tag

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/SETUP_COMPLETE.md

Follow these steps to create a new release. This includes committing changes, updating version files, creating a signed tag, and pushing it to trigger the automated release workflow.

```bash
# 1. Make changes and commit with signature
git commit -S -m "Your changes"

# 2. Update version files (CHANGELOG, README, etc.)
# Update CHANGELOG.md with release notes

# 3. Create signed tag and push
git tag -s v1.0.1 -m "Release version 1.0.1"
git push origin v1.0.1

# 4. GitHub Actions automatically:
#    - Packages modules/ folder
#    - Creates ZIP and TAR.GZ files
#    - Generates SHA256 checksums
#    - Creates GitHub Release with downloads
```

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

### Get_Products

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/API.md

Used by module config and connection test to fetch product list. Requires server_id.

```APIDOC
## Get_Products

### Description
Used by module config and connection test to fetch product list.

### Parameters
#### Request Body
- **server_id** (int) - Required
```

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

### Pushing to GitHub

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/SETUP_COMPLETE.md

Use these commands to push your local changes and tags to the GitHub repository.

```bash
# If not already pushed
git push origin master
git push origin --tags
```

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

### Read Config Options in PHP

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Demonstrates how to read configuration options set within the WHMCS module, such as the selected upstream product ID and display settings for service details.

```php
// Config option keys used elsewhere in the module:
// configoption1 => selected upstream product ID
// configoption2 => show_server_name  (on/off)
// configoption3 => show_host_name    (on/off)
// configoption4 => show_domain       (on/off)
// configoption5 => show_ip           (on/off)
// configoption6 => show_username     (on/off)
// configoption7 => show_password     (on/off)

// Example: read the mapped product ID inside another module function
$upstreamProductId = (int) $params['configoption1'];  // e.g. 42
$showDomain        = $params['configoption4'] === 'on'; // true/false
```

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

### Create and Push Release Tag

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_QUICK_REFERENCE.md

Create a signed, annotated tag for the release and push it to the origin. Pushing the tag triggers the automated release workflow.

```bash
# Create signed, annotated tag (recommended)
git tag -s v1.0.1 -m "Release version 1.0.1

Improvements:
- Bug fixes
- Performance enhancements"

# Push the tag (this triggers the release workflow!)
git push origin v1.0.1
```

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

### Send API Request with ProductsReseller_Main

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Use this method to interact with the Avalon Hosting Services reseller API. It handles request formatting, dispatching, and response decoding. Ensure the WHMCS context is available and the `pr_server_classes.php` file is included.

```php
require_once __DIR__ . '/modules/servers/products_reseller_server/pr_server_classes.php';

$main = new ProductsReseller_Main();

// Fetch all products available on the reseller account
$response = $main->send_request_to_api([
    'action'    => 'Get_Products',
    'server_id' => 1,            // tblservers.id of the Products Reseller server
]);

if ($response['status'] === 'success' && is_array($response['data'])) {
    foreach ($response['data'] as $product) {
        // $product['product_id']   => upstream product ID (used as configoption1)
        // $product['product_name'] => display name
        echo $product['product_id'] . ': ' . $product['product_name'] . PHP_EOL;
    }
} else {
    echo 'Error: ' . $response['message'];
}

/* Expected response shape:
{
  "status": "success",
  "data": [
    { "product_id": 42, "product_name": "cPanel Starter" },
    { "product_id": 43, "product_name": "cPanel Business" }
  ],
  "message": "Request completed successfully"
}
*/
```

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

### Enable Automatic Commit Signing

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_PROCESS.md

Configure Git to automatically sign all your commits with GPG.

```bash
git config --global commit.gpgsign true
```

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

### Update Version Files

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_QUICK_REFERENCE.md

Before creating a release tag, update version information in CHANGELOG.md, README.md, and any other relevant project files. Commit these updates with a signed commit.

```markdown
## [1.0.1] - 2026-03-25

### Fixed
- Bug fix description

### Added
- New feature description
```

```bash
git commit -S -m "Bump version to 1.0.1

- Update CHANGELOG with fixes and features
- Update version in documentation"
```

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

### ChangePackage

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/API.md

Used when package/product is changed. Requires serviceid, server_id, domain, username, password, and ip_address.

```APIDOC
## ChangePackage

### Description
Used when package/product is changed.

### Parameters
#### Request Body
- **serviceid** (int) - Required
- **server_id** (int) - Required
- **domain** (string) - Required
- **username** (string) - Required
- **password** (string) - Required
- **ip_address** (string) - Required
```

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

### Manual Module Extraction (Linux)

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Manually extract the module ZIP file and set appropriate permissions for the extracted files.

```bash
unzip whmcs-reseller-module-v1.0.0.zip -d /var/www/html/whmcs/
chmod -R 755 /var/www/html/whmcs/modules/servers/products_reseller_server/
```

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

### Verify Release Workflow

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_QUICK_REFERENCE.md

Monitor the GitHub Actions tab to ensure the release workflow completes successfully. Verify the release files and checksums in the Releases tab.

```bash
# Check if tag was created
git tag -l v1.0.1

# View tag details
git show v1.0.1

# Check if tag is on GitHub
git ls-remote --tags origin v1.0.1
```

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

### Create a Git Tag for Release

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/CONTRIBUTING.md

Create a signed Git tag for a new release using semantic versioning. This action triggers the build and release process for the `modules` folder. Ensure all commits included in the release are signed.

```bash
git tag -s v1.0.1 -m "Release version 1.0.1"
git push origin v1.0.1
```

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

### Testing Release Workflow

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/SETUP_COMPLETE.md

This sequence of commands allows you to test the automated release workflow by creating, pushing, and then deleting a test tag.

```bash
# Create a test pre-release tag
git tag -s v1.0.0-test.1 -m "Test release"
git push origin v1.0.0-test.1

# Monitor the Actions tab
# Once verified, delete test tag
git tag -d v1.0.0-test.1
git push origin --delete v1.0.0-test.1
```

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

### CreateAccount

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/API.md

Used by WHMCS when provisioning a new service. Requires serviceid, billingcycle, qty, domain, username, password, ip_address, selected_product, and server_id.

```APIDOC
## CreateAccount

### Description
Used by WHMCS when provisioning a new service.

### Parameters
#### Request Body
- **serviceid** (int) - Required
- **billingcycle** (string) - Required
- **qty** (int) - Required
- **domain** (string) - Required
- **username** (string) - Required
- **password** (string) - Required
- **ip_address** (string) - Required
- **selected_product** (int) - Required
- **server_id** (int) - Required
```

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

### Render Client Area Service Tab with products_reseller_server_ClientArea

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Renders the service overview tab in the WHMCS client area. For cPanel services, it uses a template with usage data and shortcuts; for others, it generates an HTML block.

```php
// cPanel branch — returned to WHMCS as a template array:
return [
    'tabOverviewReplacementTemplate' => 'cpanel.tpl',
    'vars' => [
        'service'   => $service,      // tblhosting row
        'product'   => $product,      // tblproducts row
        'shortcuts' => [
            ['label' => 'Email Accounts', 'app' => 'Email_Accounts',     'icon' => '...png'],
            ['label' => 'File Manager',   'app' => 'FileManager_Home',   'icon' => '...png'],
            ['label' => 'MySQL Databases','app' => 'Database_MySQL',     'icon' => '...png'],
            // ... more shortcuts
        ],
        'usage' => [
            'disk_used'    => 512,           // MB used
            'disk_limit'   => '10240 M',     // MB or 'Unlimited M'
            'disk_percent' => 5,             // 0–100
            'bw_used'      => 1024,
            'bw_limit'     => 'Unlimited M',
            'bw_percent'   => 0,
            'last_updated' => '2025-06-01 12:00:00',
        ],
    ],
];
```

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

### Verify Package Integrity (Windows PowerShell)

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_PROCESS.md

Verify the SHA256 checksum of the downloaded release package on Windows using PowerShell.

```powershell
# On Windows (PowerShell)
(Get-FileHash -Path "whmcs-reseller-module-v1.0.0.zip" -Algorithm SHA256).Hash
```

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

### products_reseller_server_CreateAccount

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Provisions a new service when triggered by WHMCS on order activation or manual provisioning. It sends a `CreateAccount` action to the upstream API.

```APIDOC
## `products_reseller_server_CreateAccount($params)` — Provision a new service

Triggered by WHMCS on order activation (or manual provisioning). Reads `billingcycle`, `qty`, `domain`, `username`, and `dedicatedip` from `tblhosting`, then sends a `CreateAccount` action to the upstream API. Returns the string `'success'` on success or an error message string on failure (WHMCS displays the error in the admin interface).

```php
// API request dispatched internally:
curl -X POST "https://node1.avalon.hosting/reseller/modules/addons/products_reseller/api.php" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_abc123",
    "action": "CreateAccount",
    "params": {
      "serviceid":        1001,
      "billingcycle":     "monthly",
      "qty":              1,
      "domain":           "clientsite.com",
      "username":         "clientsite",
      "password":         "Str0ngP@ss!",
      "ip_address":       "",
      "selected_product": 42,
      "server_id":        1
    }
  }'

# Successful upstream response:
# { "status": "success", "data": { "serviceid": 1001 }, "message": "Account created" }
```
```

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

### Change Hosting Package with products_reseller_server_ChangePackage

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Use this function to upgrade or downgrade a hosting plan for a WHMCS service. It sends a ChangePackage action to the upstream provider.

```bash
curl -X POST "https://node1.avalon.hosting/reseller/modules/addons/products_reseller/api.php" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_abc123",
    "action": "ChangePackage",
    "params": {
      "serviceid":  1001,
      "server_id":  1,
      "domain":     "clientsite.com",
      "username":   "clientsite",
      "password":   "Str0ngP@ss!",
      "ip_address": ""
    }
  }'

# { "status": "success", "message": "Package updated" }
```

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

### Generate cPanel SSO Redirect with products_reseller_server_ServiceSingleSignOn

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Provides a one-time cPanel login URL for single sign-on. It calls the upstream CreateSSOSession action and returns a redirect URL.

```bash
// Requesting SSO for a specific cPanel app (e.g. File Manager):
// In the client area URL: ?app=FileManager_Home

curl -X POST "https://node1.avalon.hosting/reseller/modules/addons/products_reseller/api.php" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_abc123",
    "action": "CreateSSOSession",
    "params": {
      "serviceid":  1001,
      "server_id":  1,
      "app":        "FileManager_Home"
    }
  }'

# Upstream response:
# { "status": "success", "url": "https://cpanel.clientsite.com:2083/?session=TOKENABC123" }

# Module returns to WHMCS:
# ['success' => true, 'redirectTo' => 'https://cpanel.clientsite.com:2083/?session=TOKENABC123']
```

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

### Create and Push Signed Release Tag

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_PROCESS.md

Create a signed, annotated tag for a release and push it to the remote repository to trigger the release workflow.

```bash
git tag -s v1.0.0 -m "Release version 1.0.0"

# Push the tag to trigger the release workflow
git push origin v1.0.0
```

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

### View All Git Tags

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_QUICK_REFERENCE.md

Provides commands to manage and view Git tags, including listing all tags, viewing tag details, listing signed tags, and deleting tags locally or remotely.

```bash
# View all tags
git tag -l

# View tag details
git show v1.0.0

# List signed tags
git tag -l -n 3

# Delete tag locally
git tag -d v1.0.0

# Delete tag on GitHub
git push origin --delete v1.0.0

# Create and sign tag in one go
git tag -s v1.0.1 -m "Release v1.0.1" && git push origin v1.0.1
```

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

### Documentation URL for WHMCS Marketplace

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/MARKETPLACE_LISTING.md

The URL where users can find documentation for the module.

```plaintext
https://github.com/AvalonHostingServices/whmcs-reseller-module
```

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

### Verify Package Integrity (Linux/Mac)

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_PROCESS.md

Verify the SHA256 checksum of the downloaded release package on Linux or macOS.

```bash
# On Linux/Mac
sha256sum -c whmcs-reseller-module-v1.0.0.zip.sha256
```

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

### Verify Package Integrity (macOS)

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_PROCESS.md

Verify the SHA256 checksum of the downloaded release package on macOS using shasum.

```bash
# On macOS
shasum -a 256 -c whmcs-reseller-module-v1.0.0.zip.sha256
```

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

### Configure Automatic Commit Signing

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_QUICK_REFERENCE.md

Enable automatic commit signing by configuring Git with your GPG signing key. Unsigned commits will not be accepted in pull requests.

```bash
# Sign a single commit
git commit -S -m "Your message"

# Or enable automatic signing
git config --global commit.gpgsign true
git config --global user.signingkey YOUR_KEY_ID

# Then just use normal commit
git commit -m "Your message"
```

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

### CreateSSOSession

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/API.md

Used for cPanel SSO redirection. Requires serviceid and server_id. 'app' is optional.

```APIDOC
## CreateSSOSession

### Description
Used for cPanel SSO redirection.

### Parameters
#### Request Body
- **serviceid** (int) - Required
- **server_id** (int) - Required
- **app** (string) - Optional
```

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

### Troubleshooting Module Not Appearing

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/INSTALL.md

Commands to check file location and permissions for the WHMCS module on Linux/macOS. Verify the module is in the correct directory and has appropriate permissions.

```bash
WHMCS_ROOT/modules/servers/products_reseller_server/
```

```bash
ls -la /path/to/whmcs/modules/servers/products_reseller_server/
```

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

### Extract Release Package to WHMCS

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_PROCESS.md

Instructions for resellers to extract the downloaded release package into their WHMCS root directory.

```bash
unzip whmcs-reseller-module-v1.0.0.zip -d /path/to/whmcs/
```

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

### Configure Git Commit Signing

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/CONTRIBUTING.md

Configure Git to automatically sign all commits with your GPG key. Ensure you have a GPG key generated and its ID is correctly set.

```bash
gpg --gen-key
```

```bash
gpg --list-secret-keys --keyid-format LONG
```

```bash
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true
```

```bash
git config commit.gpgsign true
git config user.signingkey YOUR_KEY_ID
```

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

### Bulk Import or Sync Products via AJAX

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

This jQuery AJAX call handles the bulk import or synchronization of selected products. It sends a JSON-encoded array of products with margin settings to the server, which then creates/updates WHMCS products and pricing, and records the mapping upstream.

```javascript
// Products array sent as JSON string in the POST body:
var selectedProducts = [
    {
        product_id:         42,
        product_name:       "cPanel Starter",
        product_type:       "hostingaccount",
        product_group_name: "Web Hosting",
        product_description:"Entry-level cPanel hosting",
        paytype:            "recurring",
        is_mapped:          false,
        reseller_product_id: 0,
        margin_type:        "percentage",  // "percentage" | "fixed"
        margin_value:       20,            // 20% markup applied to all cycle prices
        pricing:[{
            currency_code: "USD",
            pricing: { monthly: 4.99, annually: 49.99, msetupfee: 0, asetupfee: 0 }
        }]
    }
];

$.ajax({
    url:     '../modules/servers/products_reseller_server/ajax_functions.php',
    type:    'POST',
    data:    { prs_doing_ajax: true, action: 'importSyncProducts', products: JSON.stringify(selectedProducts) },
    dataType:'json',
    timeout: 120000,
    success: function(response) {
        // response.status  => 'success' | 'partial' | 'error'
        // response.message => "1 product(s) processed successfully"
        // response.results => [
        //   { product_id: 42, reseller_product_id: 77, status: 'imported',
        //     message: "'cPanel Starter' imported successfully." }
        // ]
        // response.success_count => 1
        // response.error_count   => 0
    }
});

// Margin calculation applied server-side (pr_server_classes equivalent):
// percentage: final_price = base_price * (1 + margin_value / 100)  => 4.99 * 1.20 = 5.99
// fixed:      final_price = base_price + margin_value               => 4.99 + 1.00 = 5.99
```

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

### Get_Products_For_Import

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/API.md

Used in admin-side mapping/import flow.

```APIDOC
## Get_Products_For_Import

### Description
Used in admin-side mapping/import flow.
```

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

### Verify Signed Commits

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/RELEASE_PROCESS.md

Check if your commits are signed with GPG. Look for the 'Verified' badge next to commits in the log.

```bash
git log --oneline --graph
# Look for the "Verified" badge next to commits
```

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

### Terminate Account with cURL

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Demonstrates permanently removing a hosting account by sending a POST request to the upstream API with the 'TerminateAccount' action. This is triggered on service termination in WHMCS.

```bash
curl -X POST "https://node1.avalon.hosting/reseller/modules/addons/products_reseller/api.php" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_abc123",
    "action": "TerminateAccount",
    "params": {
      "serviceid":  1001,
      "server_id":  1,
      "domain":     "clientsite.com",
      "username":   "clientsite",
      "password":   "Str0ngP@ss!",
      "ip_address": ""
    }
  }'
```

```json
# { "status": "success", "message": "Account terminated" }
```

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

### Support URL for WHMCS Marketplace

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/MARKETPLACE_LISTING.md

The URL where users can find support or report issues for the module.

```plaintext
https://github.com/AvalonHostingServices/whmcs-reseller-module/issues
```

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

### Enable Automatic Commit Signing

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/SETUP_COMPLETE.md

To ensure all your commits are signed, you can configure Git to automatically sign them. Alternatively, you can sign individual commits using the '-S' flag.

```bash
# Enable automatic signing
git config --global commit.gpgsign true

# Or sign individual commits
git commit -S -m "message"
```

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

### ProductsReseller_Main::send_request_to_api

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

The central method used by every module action to dispatch requests to the Avalon Hosting Services API. It handles authentication, request formatting, and response decoding. This method is crucial for all API interactions, including fetching products, provisioning services, and managing client accounts.

```APIDOC
## ProductsReseller_Main::send_request_to_api($data)

### Description
This is the core HTTP dispatcher method used by all module actions to communicate with the Avalon Hosting Services reseller API. It constructs the JSON request envelope, sends it via cURL, and returns the decoded JSON response.

### Method
```php
public function send_request_to_api(array $data)
```

### Parameters
#### Request Body
- **data** (array) - Required - An associative array containing the API request details, including:
  - **api_key** (string) - The unique API key for authentication.
  - **action** (string) - The specific API action to perform (e.g., 'Get_Products', 'Create_User').
  - **params** (array) - An optional array of parameters specific to the action.

### Request Example
```php
// Direct usage inside a custom PHP script loaded within WHMCS context
require_once __DIR__ . '/modules/servers/products_reseller_server/pr_server_classes.php';

$main = new ProductsReseller_Main();

// Fetch all products available on the reseller account
$response = $main->send_request_to_api([
    'action'    => 'Get_Products',
    'server_id' => 1,            // tblservers.id of the Products Reseller server
]);

if ($response['status'] === 'success' && is_array($response['data'])) {
    foreach ($response['data'] as $product) {
        // $product['product_id']   => upstream product ID (used as configoption1)
        // $product['product_name'] => display name
        echo $product['product_id'] . ': ' . $product['product_name'] . PHP_EOL;
    }
} else {
    echo 'Error: ' . $response['message'];
}
```

### Response
#### Success Response
- **status** (string) - Indicates the success or failure of the API request ('success' or 'error').
- **data** (array|null) - Contains the data returned by the API if the request was successful. The structure varies based on the action performed.
- **message** (string) - A message describing the outcome of the API request.

#### Response Example
```json
{
  "status": "success",
  "data": [
    { "product_id": 42, "product_name": "cPanel Starter" },
    { "product_id": 43, "product_name": "cPanel Business" }
  ],
  "message": "Request completed successfully"
}
```
```

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

### ChangePackage

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Upgrades or downgrades a hosting plan for a given service. This action is triggered when the product assigned to a WHMCS service is changed.

```APIDOC
## POST /reseller/modules/addons/products_reseller/api.php

### Description
Upgrades or downgrades a hosting plan for a given service. This action is triggered when the product assigned to a WHMCS service is changed.

### Method
POST

### Endpoint
https://node1.avalon.hosting/reseller/modules/addons/products_reseller/api.php

### Parameters
#### Request Body
- **api_key** (string) - Required - Your API key.
- **action** (string) - Required - Must be set to "ChangePackage".
- **params** (object) - Required - Contains parameters for the action.
  - **serviceid** (integer) - Required - The ID of the WHMCS service.
  - **server_id** (integer) - Required - The ID of the server.
  - **domain** (string) - Required - The domain of the client's service.
  - **username** (string) - Required - The username for the service.
  - **password** (string) - Required - The password for the service.
  - **ip_address** (string) - Optional - The IP address of the service.

### Request Example
```json
{
  "api_key": "sk_live_abc123",
  "action": "ChangePackage",
  "params": {
    "serviceid":  1001,
    "server_id":  1,
    "domain":     "clientsite.com",
    "username":   "clientsite",
    "password":   "Str0ngP@ss!",
    "ip_address": ""
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation ('success').
- **message** (string) - A message confirming the package update.
```

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

### Fetch Upstream Product Catalogue via AJAX

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Use this jQuery AJAX call to fetch the upstream product catalogue for import or synchronization. It queries the `Get_Products_For_Import` API action and returns product details, pricing, and mapping status.

```javascript
// jQuery AJAX call issued by the admin modal (hooks/prs_hooks.php):
$.ajax({
    url:      '../modules/servers/products_reseller_server/ajax_functions.php',
    type:     'POST',
    data:     { prs_doing_ajax: true, action: 'getProductsForImport' },
    dataType: 'json',
    success: function(response) {
        // response.status === 'success'
        // response.data[] => array of product objects:
        // {
        //   product_id:         42,
        //   product_name:       "cPanel Starter",
        //   product_type:       "hostingaccount",
        //   product_group_name: "Web Hosting",
        //   is_mapped:          false,        // true if already imported to WHMCS
        //   reseller_product_id: 0,           // local WHMCS pid if mapped
        //   pricing:[{
        //     currency_code: "USD",
        //     pricing: { monthly: 4.99, annually: 49.99, msetupfee: 0, asetupfee: 0, ... }
        //   }]
        // }
    }
});
```

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

### ClientArea

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Renders the service overview tab in the WHMCS client area. For cPanel services, it displays real-time usage and shortcuts; for non-cPanel services, it shows basic service details.

```APIDOC
## ClientArea Service Tab

### Description
Renders the service overview tab in the WHMCS client area. For cPanel services, it displays real-time disk and bandwidth usage along with quick-launch shortcut icons. For non-cPanel services, it constructs an HTML block with essential service details.

### Usage
This function is called by WHMCS to populate the client area service tab.

### cPanel Service Response Example
```php
return [
    'tabOverviewReplacementTemplate' => 'cpanel.tpl',
    'vars' => [
        'service'   => $service,      // tblhosting row
        'product'   => $product,      // tblproducts row
        'shortcuts' => [
            ['label' => 'Email Accounts', 'app' => 'Email_Accounts',     'icon' => '...png'],
            ['label' => 'File Manager',   'app' => 'FileManager_Home',   'icon' => '...png'],
            ['label' => 'MySQL Databases','app' => 'Database_MySQL',     'icon' => '...png'],
        ],
        'usage' => [
            'disk_used'    => 512,           // MB used
            'disk_limit'   => '10240 M',     // MB or 'Unlimited M'
            'disk_percent' => 5,             // 0–100
            'bw_used'      => 1024,
            'bw_limit'     => 'Unlimited M',
            'bw_percent'   => 0,
            'last_updated' => '2025-06-01 12:00:00',
        ],
    ],
];
```

### Non-cPanel Service Response Example
(Returns an HTML block with service fields like server name, hostname, domain, IP, username, and password.)
```

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

### products_reseller_server_MetaData

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Declares the module's metadata, including its display name, API version, and Single Sign-On (SSO) labels. This function is automatically called by WHMCS to gather information about the server module.

```APIDOC
## products_reseller_server_MetaData()

### Description
Declares the module's display name, API version, and SSO labels consumed by WHMCS. `ServiceSingleSignOnLabel` and `AdminSingleSignOnLabel` set the button text shown in the client and admin areas when the upstream server type is cPanel.

### Method
```php
function products_reseller_server_MetaData()
```

### Returns
- **array** - An associative array containing module metadata:
  - **DisplayName** (string) - The name displayed for the module in WHMCS.
  - **APIVersion** (string) - The version of the module's API.
  - **RequiresServer** (boolean) - Indicates if a server record is required.
  - **ServiceSingleSignOnLabel** (string) - The text for the client area SSO button.
  - **AdminSingleSignOnLabel** (string) - The text for the admin area SSO button.

### Example
```php
// Returned automatically by WHMCS — shown here for reference
function products_reseller_server_MetaData() {
    return [
        'DisplayName'              => 'Products Reseller for WHMCS',
        'APIVersion'               => '1.0',
        'RequiresServer'           => true,
        'ServiceSingleSignOnLabel' => 'Login to cPanel',
        'AdminSingleSignOnLabel'   => 'Login to cPanel',
    ];
}
```
```

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

### Inject Import/Sync UI with AdminAreaHeadOutput Hook

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

This hook injects the necessary CSS and JavaScript for the Import/Sync Products modal into the WHMCS admin area. It is automatically registered on module activation and self-destructs if the module server record is removed.

```php
// The hook is auto-registered by whmp_prs_copyFileToHooks() on first module activation.
// It self-destructs (unlink(__FILE__)) if the module server record is removed,
// keeping WHMCS clean with no orphaned hook files.

// Manually register if needed (in any WHMCS hooks file):
add_hook('AdminAreaHeadOutput', 1, function($vars) {
    if ($vars['filename'] === 'configproducts' && !isset($_GET['id'])) {
        // Returns <style> + <script> block for the import modal
    }
});
```

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

### Sign a Git Commit

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/CONTRIBUTING.md

Manually sign a single Git commit with your GPG key. This is required for all contributions. Alternatively, configure Git to sign all future commits automatically.

```bash
git commit -S -m "Your commit message"
```

```bash
git commit -m "Your commit message"
```

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

### Unsuspend Account with cURL

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Shows how to reactivate a suspended hosting account by sending a POST request to the upstream API with the 'UnsuspendAccount' action. This is called when a service is reactivated in WHMCS.

```bash
curl -X POST "https://node1.avalon.hosting/reseller/modules/addons/products_reseller/api.php" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_abc123",
    "action": "UnsuspendAccount",
    "params": {
      "serviceid":  1001,
      "server_id":  1,
      "domain":     "clientsite.com",
      "username":   "clientsite",
      "password":   "Str0ngP@ss!",
      "ip_address": ""
    }
  }'
```

```json
# { "status": "success", "message": "Account reactivated" }
```

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

### WHMCS Reseller Module Directory Structure

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/modules/PROJECT.md

This is the standard directory structure for the WHMCS Reseller Module v1.0.0.

```bash
modules/
└── servers/
    └── products_reseller_server/
        ├── ajax_functions.php       # AJAX handlers for admin interface
        ├── hooks.php                # WHMCS hooks and events
        ├── pr_server_classes.php    # Core module classes
        ├── products_reseller_server.php  # Main module file
        ├── whmcs.json              # Module metadata
        ├── hooks/
        │   └── prs_hooks.php        # Additional hooks
        ├── images/
        │   └── cpanel/
        │       └── cpanel.tpl           # cPanel template
```

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

### Suspend Account with cURL

Source: https://context7.com/avalonhostingservices/whmcs-reseller-module/llms.txt

Demonstrates suspending a hosting account by sending a POST request to the upstream API with the 'SuspendAccount' action. This is used when a service is suspended in WHMCS.

```bash
curl -X POST "https://node1.avalon.hosting/reseller/modules/addons/products_reseller/api.php" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk_live_abc123",
    "action": "SuspendAccount",
    "params": {
      "serviceid":     1001,
      "server_id":     1,
      "suspendreason": "Non-payment",
      "domain":        "clientsite.com",
      "username":      "clientsite",
      "password":      "Str0ngP@ss!",
      "ip_address":    ""
    }
  }'
```

```json
# { "status": "success", "message": "Account suspended" }
```

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

### GetServerName

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/API.md

Used to decide whether cPanel SSO action should be shown. Requires serviceid and server_id.

```APIDOC
## GetServerName

### Description
Used to decide whether cPanel SSO action should be shown.

### Parameters
#### Request Body
- **serviceid** (int) - Required
- **server_id** (int) - Required
```

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

### Save_Product_Mapping

Source: https://github.com/avalonhostingservices/whmcs-reseller-module/blob/master/API.md

Used in admin-side mapping flow to save mappings.

```APIDOC
## Save_Product_Mapping

### Description
Used in admin-side mapping flow to save mappings.
```