<?php

declare(strict_types=1);

namespace BotGuard\Services\Captcha;

/**
 * Contract for a human-verification challenge provider.
 *
 * The default implementation is a self-hosted PuzzleProvider (no external keys).
 * reCAPTCHA / hCaptcha / Turnstile implement the same interface, so the rest of
 * the app is provider-agnostic.
 */
interface CaptchaProviderInterface
{
    /**
     * Provider identifier, e.g. "puzzle", "turnstile".
     */
    public function name(): string;

    /**
     * Data the client needs to render the challenge, plus (for self-hosted
     * challenges) the server-side answer to persist with the session.
     *
     * @return array{client: array<string,mixed>, answer: ?string}
     */
    public function issue(): array;

    /**
     * Verify the client's challenge response.
     *
     * @param array<string, mixed> $input       Client-submitted challenge fields.
     * @param string|null          $serverAnswer The answer stored at issue time.
     * @param string               $clientIp     For remote providers' remoteip.
     */
    public function verify(array $input, ?string $serverAnswer, string $clientIp = ''): CaptchaResult;
}
