<?php
/**
 * Anti-spam provider interface for implementing anti-spam protection.
 *
 * @package Awesomemotive\Rewardswp\Interfaces
 * @since 1.2.0
 */

namespace Awesomemotive\Rewardswp\Interfaces;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * AntiSpamProvider interface.
 *
 * Defines the contract that all anti-spam providers must implement.
 * Providers can include honeypot, reCAPTCHA, hCaptcha, Cloudflare Turnstile, etc.
 *
 * @since 1.2.0
 */
interface AntiSpamProviderInterface {
	/**
	 * Get the unique provider identifier.
	 *
	 * Must return a unique snake_case identifier for this provider.
	 * Example: 'honeypot', 'google_recaptcha', 'hcaptcha', 'cloudflare_turnstile'.
	 *
	 * @since 1.2.0
	 *
	 * @return string The provider identifier.
	 */
	public function get_name(): string;

	/**
	 * Get the human-readable label for admin display.
	 *
	 * @since 1.2.0
	 *
	 * @return string The provider label.
	 */
	public function get_label(): string;

	/**
	 * Get the feature slug for license checking.
	 *
	 * This is used to check if the current plan has access to this provider.
	 * Example: 'antispam_honeypot', 'antispam_recaptcha'.
	 *
	 * @since 1.2.0
	 *
	 * @return string The feature slug.
	 */
	public function get_feature_slug(): string;

	/**
	 * Check if the provider is available for use.
	 *
	 * This checks license access and any required configuration (API keys, etc.).
	 *
	 * @since 1.2.0
	 *
	 * @return bool True if available, false otherwise.
	 */
	public function is_available(): bool;

	/**
	 * Check if the provider is properly configured.
	 *
	 * For honeypot, this always returns true.
	 * For CAPTCHA providers, this checks if API keys are set.
	 *
	 * @since 1.2.0
	 *
	 * @return bool True if configured, false otherwise.
	 */
	public function is_configured(): bool;

	/**
	 * Render the anti-spam field(s) in the form.
	 *
	 * For honeypot, this renders a hidden field.
	 * For CAPTCHA providers, this renders the CAPTCHA widget.
	 *
	 * @since 1.2.0
	 *
	 * @return void
	 */
	public function render_field(): void;

	/**
	 * Validate the anti-spam submission.
	 *
	 * For honeypot, this checks if the hidden field was filled (indicating a bot).
	 * For CAPTCHA providers, this verifies the CAPTCHA response.
	 *
	 * @since 1.2.0
	 *
	 * @param array $request_data The request data (typically $_POST).
	 *
	 * @return bool True if validation passed (not spam), false if spam detected.
	 */
	public function validate( array $request_data ): bool;

	/**
	 * Get the error message when validation fails.
	 *
	 * Should return a generic message to avoid revealing anti-spam mechanism details.
	 *
	 * @since 1.2.0
	 *
	 * @return string The error message.
	 */
	public function get_error_message(): string;

	/**
	 * Get the field name used by this provider.
	 *
	 * This is the form field name that needs to be sent with the request.
	 *
	 * @since 1.2.0
	 *
	 * @return string The field name.
	 */
	public function get_field_name(): string;
}

