<?php

namespace App\Services\Proxmox;

use App\Models\Host;

/**
 * Proxmox VE REST client, addressed per host over its wg_ip with a token.
 * A v1.0 reads capacity and provisions the automation token; Subsystem B
 * extends it with VM lifecycle methods (clone, cloud-init, guestExec …).
 */
interface ProxmoxClient
{
    /** Configure this client for a host (base URL from wg_ip, token from api_token_ref). */
    public function forHost(Host $host): static;

    /** @return array<int, array<string, mixed>> */
    public function listNodes(): array;

    /** @return array<string, mixed> */
    public function nodeStatus(string $node): array;

    /** @return array<int, array<string, mixed>> */
    public function nodeStorage(string $node): array;

    public function createRole(string $roleId, string $privs): void;

    /** @return array{token_id: string, secret: string} */
    public function createUserAndToken(string $user, string $roleId): array;
}