Product Module Client Management

Management tab clicked
  └─ GET use_module_method-less request  ->  ClientServices::get_management_details
       ├─ owner + type + active-state check
       ├─ client_module_instance()        ->  $client_area = true, $area_link set
       ├─ ProductModule::service_management_page()  ->  get_page('dashboard')
       └─ inline script tags split out, evaluated separately by the theme bridge

Overview tab
  └─ the services controller, for special and software services
       ├─ client_overview_data()   ->  usage rings + account rows
       └─ client_quick_actions()   ->  shortcut buttons

A shortcut or a dashboard button
  └─ POST use_module_method  ->  allowlist  ->  handle_{name}()

// Declared on ProductModule; override what you need.
public bool  $client_area            = false;   // set to true only by the client renderer
public array $client_callable_methods = [];     // names WITHOUT the handle_ prefix
public array $client_readonly_methods = [];     // a subset of the above, GET-safe

public function has_client_management(): bool;
public function client_overview_data(): array;
public function client_quick_actions(int $limit = 8): array;

// Your handler for a declared callable. No parameters; returns the JSON payload.
public function handle_reset_usage(): array;

return [
    'gauges' => [
        [
            'key'   => 'storage',
            'label' => $this->lang['storage-usage'],
            'icon'  => 'bi bi-hdd',
            'used'  => 4.5,
            'total' => 20,          // 0 or below means unlimited; pass -1 for clarity
            'unit'  => 'GB',
        ],
    ],
    'resources' => [
        // Ratio form: same keys as a gauge.
        ['key' => 'seats', 'label' => 'Seats', 'icon' => 'bi bi-people', 'used' => 3, 'total' => 10, 'unit' => ''],
        // Value form: a single reading with no limit.
        ['key' => 'region', 'label' => 'Region', 'icon' => 'bi bi-globe', 'value' => 'eu-west'],
    ],
    'account' => [
        ['key' => 'account_id', 'label' => 'Account ID', 'type' => 'text', 'copyable' => true, 'value' => 'ac_1042'],
        ['key' => 'username',   'label' => 'Username',   'type' => 'text', 'copyable' => true, 'value' => 'acme'],
        ['key' => 'status',     'label' => 'Status',     'type' => 'badge', 'badge_color' => 'success', 'value' => 'Active'],
        ['key' => 'console',    'label' => 'Console',    'type' => 'link',  'value' => 'https://panel.example.com'],
    ],
];

public function client_quick_actions(int $limit = 8): array
{
    $actions = [
        // action => true: runs the handler in place, through the callable allowlist.
        ['key' => 'reset_usage', 'label' => $this->lang['action-reset-usage'],
         'icon' => 'bi bi-arrow-counterclockwise', 'action' => true, 'method' => 'reset_usage'],

        // action => false: navigates to a page inside the management tab instead.
        ['key' => 'backups', 'label' => $this->lang['action-backups'],
         'icon' => 'bi bi-archive', 'action' => false, 'method' => 'backups'],
    ];

    // Honour the limit: the caller decides how many fit.
    return array_slice($actions, 0, $limit);
}

// ClientServices::use_module_method, reduced to the decisions.
$service = $this->owned_managed_service($uid);      // owner, type, module and active-state check
$method  = (string) Filter::init("REQUEST/method", "route");

$module = $this->client_module_instance($service);  // sets $client_area and $area_link

$handleMethod = 'handle_' . str_replace('-', '_', $method);
$isTool       = in_array($method, ['tool_action', 'tool_table', 'sso_panel_login'], true);

// BOTH conditions: declared in the allowlist AND the handler actually exists.
$isClientCallable = !$isTool
    && in_array($method, $module->client_callable_methods ?? [], true)
    && method_exists($module, $handleMethod);

if (!$isTool && !$isClientCallable)
    throw new \Exception(Language::gc("website/services/err-invalid"));

// Read-only callables skip the token and the active-service requirement.
$isReadonly = $isClientCallable && in_array($method, $module->client_readonly_methods ?? [], true);
$mutates    = ($method === 'tool_action' || $isClientCallable) && !$isReadonly;

if ($mutates && !\Validation::verify_csrf_token((string) Filter::init("POST/token", "hclear"), "services"))
    throw new \Exception(Language::g("needs/csrf-failed"));

if ($mutates && ($service['status'] ?? '') !== 'active')
    throw new \Exception(Language::gc("website/services/err-invalid"));

// Declared without the handle_ prefix. Anything absent here is refused.
public array $client_callable_methods = ['reset_usage', 'download_report'];

// Served over a GET link, so exempt from the token and the POST requirement.
public array $client_readonly_methods = ['download_report'];

public function client_overview_data(): array
{
    $remote = $this->fetchRemoteStatus();
    if (!$remote) return [];                       // nothing provisioned yet: no gauges

    $gauges = [];
    if (isset($remote['storage_limit']))
        $gauges[] = [
            'key'   => 'storage',
            'label' => $this->lang['storage-usage'],
            'icon'  => 'bi bi-hdd',
            'used'  => (float) ($remote['used_storage'] ?? 0),
            'total' => (float) $remote['storage_limit'] > 0 ? (float) $remote['storage_limit'] : -1,
            'unit'  => 'GB',
        ];

    $account = [];
    $username = (string) ($this->options['login']['username'] ?? '');

    // The controller injects the password row right after this one.
    if ($username !== '')
        $account[] = ['key' => 'username', 'label' => $this->lang['username'], 'type' => 'text', 'copyable' => true, 'value' => $username];

    $status = (string) ($remote['status'] ?? '');
    if ($status !== '')
        $account[] = [
            'key'         => 'status',
            'label'       => $this->lang['account-status'],
            'type'        => 'badge',
            'badge_color' => $status === 'active' ? 'success' : 'secondary',
            'value'       => $this->lang['status-' . $status] ?? ucfirst($status),
        ];

    if (!$gauges && !$account) return [];

    return ['gauges' => $gauges, 'resources' => [], 'account' => $account];
}

public function handle_reset_usage(): array
{
    // Client-triggered: nothing has prepared the API client for you.
    $this->initApi();

    $accountId = $this->options['config']['id'] ?? '';
    if (!$accountId) throw new Exception($this->lang['err-not-provisioned']);

    $this->api->call('accounts/' . $accountId . '/usage/reset', [], 'POST');

    return ['status' => 'successful', 'message' => $this->lang['usage-reset-ok']];
}

<?php
/** @var ProductModule $module */

// Admin has no Overview tab, so it must keep these blocks. The customer already
// sees the same numbers there, so hide them here rather than deleting them.
if (!($module->client_area ?? false)):
?>
    <div class="row">
        <!-- gauge widgets and the account card -->
    </div>
<?php endif; ?>

<!-- Actions stay in both views: this is the management surface. -->
<button type="button" class="btn btn-primary" id="acmeResetUsage">Reset Usage</button>

<script>
(function () {
    // Null-guard every lookup: a block hidden by $client_area leaves its ids missing,
    // and an uncaught error here takes the whole panel down, not just this button.
    var btn = document.getElementById('acmeResetUsage');
    if (!btn) return;

    btn.addEventListener('click', function () {
        run_module_method('reset_usage');
    });
})();
</script>