<?php
/**
 * Captcha Provider Interface
 *
 * Contract implemented by every WP PowerSuite CAPTCHA module (Simple, Google
 * reCAPTCHA, Cloudflare Turnstile) so external code — and cross-module code
 * like the dashboard widget — can treat them uniformly without coupling to a
 * specific provider.
 *
 * The interface is intentionally declarative: implementing it does NOT force
 * any extra bootstrapping or asset loading, so modules that are disabled stay
 * completely inert (the PSR-4 autoloader only loads this file when a captcha
 * module is already active and its Module class is referenced).
 *
 * @package WP_PowerSuite\Captcha
 * @since 1.1.0
 */

namespace WP_PowerSuite\Captcha;

use WP_PowerSuite\Core\Contracts\ModuleInterface;

/**
 * Captcha Provider Interface
 *
 * Extends ModuleInterface so every captcha implementation can still be loaded
 * by {@see \WP_PowerSuite\Core\ModuleManager} with no extra plumbing.
 */
interface ProviderInterface extends ModuleInterface {

	/**
	 * Canonical, provider-agnostic failure message.
	 *
	 * Filterable through {@see apply_filters()} with hook `wpps_captcha_error_message`.
	 * Arguments: `( string $message, string $context, string $module_id )` where
	 * `$module_id` is one of `simple-captcha`, `google-recaptcha`, `cloudflare-turnstile`.
	 *
	 * @since 1.1.0
	 */
	public const DEFAULT_ERROR_MESSAGE = 'Please complete the verification.';

	/**
	 * Provider slug for cross-module code (analytics, dashboard widget, tests).
	 *
	 * Matches the module ID used in `wp_powersuite_settings` — e.g. `simple-captcha`,
	 * `google-recaptcha`, `cloudflare-turnstile`.
	 *
	 * @since 1.1.0
	 */
	public function getProviderSlug(): string;

	/**
	 * Whether the provider has the minimum configuration required to verify.
	 *
	 * Used by the admin banner (Phase 2 #12) so we can warn when protection
	 * toggles are on but the keys/answers are empty without duplicating the
	 * readiness logic across three modules.
	 *
	 * @since 1.1.0
	 */
	public function isConfigured(): bool;
}
