<?php

namespace App\Services\Monitoring;

interface MonitoringClient
{
    /** Register an uptime/monitoring target; returns the external target id. */
    public function registerTarget(string $name, string $url): string;

    public function deregisterTarget(string $externalId): void;

    /**
     * Current health of a target as reported by the monitoring provider.
     *
     * A yes/no answer for the provisioning acceptance check, which wants a
     * verdict and treats "cannot tell" as a pass. Anything RECORDING health
     * must use health() instead.
     */
    public function isHealthy(string $externalId): bool;

    /**
     * Current health, or null when the provider could not answer.
     *
     * The three states are genuinely different and collapsing them is how a
     * status page lies: with no monitoring configured isHealthy() answers true,
     * and with the monitoring service unreachable it answers false — so
     * recording that boolean would publish either a fleet-wide all-clear nobody
     * measured, or a fleet-wide outage that is really one broken monitor.
     */
    public function health(string $externalId): ?bool;
}
