<?php

namespace App\Services\Captcha\Providers;

interface CaptchaProviderInterface
{
    /**
     * Verify the CAPTCHA response
     *
     * @param string $response
     * @param string|null $ipAddress
     * @return array ['success' => bool, 'score' => float|null, 'error' => string|null]
     */
    public function verify(string $response, ?string $ipAddress = null): array;

    /**
     * Get the provider name
     *
     * @return string
     */
    public function getName(): string;

    /**
     * Get the site key
     *
     * @return string
     */
    public function getSiteKey(): string;

    /**
     * Get the script URL to include in HTML
     *
     * @return string
     */
    public function getScriptUrl(): string;

    /**
     * Render the CAPTCHA HTML
     *
     * @param array $attributes
     * @return string
     */
    public function render(array $attributes = []): string;

    /**
     * Check if provider is properly configured
     *
     * @return bool
     */
    public function isConfigured(): bool;
}
