<?php
/**
 * OptIn Error Value Object
 *
 * @package Forge12\DoubleOptIn\Integration
 * @since   4.2.0
 */

namespace Forge12\DoubleOptIn\Integration;

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

/**
 * Class OptInError
 *
 * Immutable value object representing an error that occurred during OptIn creation.
 * Provides typed error codes and translatable default messages for each error scenario.
 */
class OptInError {

	/**
	 * Error code: Form submission was cancelled by a listener (FormSubmissionEvent).
	 */
	public const SUBMISSION_CANCELLED = 'submission_cancelled';

	/**
	 * Error code: No valid recipient email address found in the form data.
	 */
	public const NO_RECIPIENT = 'no_recipient';

	/**
	 * Error code: Rate limit exceeded for the submitting IP address.
	 */
	public const RATE_LIMIT_IP = 'rate_limit_ip';

	/**
	 * Error code: Rate limit exceeded for the recipient email address.
	 */
	public const RATE_LIMIT_EMAIL = 'rate_limit_email';

	/**
	 * Error code: Recipient email validation failed (e.g. MX check).
	 */
	public const RECIPIENT_INVALID = 'recipient_invalid';

	/**
	 * Error code: Duplicate email rejected by Unique Email validator.
	 */
	public const UNIQUE_EMAIL_DUPLICATE = 'unique_email_duplicate';

	/**
	 * Error code: Failed to save the OptIn record to the database.
	 */
	public const SAVE_FAILED = 'save_failed';

	/**
	 * Error code: Consent acceptance gate failed — the form has a
	 * configured consent_field, but the user did not check it. We
	 * reject the opt-in instead of fabricating GDPR Art. 7 evidence.
	 */
	public const CONSENT_NOT_GIVEN = 'consent_not_given';

	/**
	 * The error code.
	 *
	 * @var string
	 */
	private string $code;

	/**
	 * The human-readable error message.
	 *
	 * @var string
	 */
	private string $message;

	/**
	 * Additional context data.
	 *
	 * @var array
	 */
	private array $context;

	/**
	 * Constructor.
	 *
	 * @param string $code    The error code.
	 * @param string $message The error message.
	 * @param array  $context Additional context data.
	 */
	public function __construct( string $code, string $message, array $context = array() ) {
		$this->code    = $code;
		$this->message = $message;
		$this->context = $context;
	}

	/**
	 * Create an OptInError from an error code with a default message.
	 *
	 * @param string $code    The error code.
	 * @param array  $context Additional context data.
	 *
	 * @return self
	 */
	public static function fromCode( string $code, array $context = array() ): self {
		$messages = self::getDefaultMessages();
		$message  = $messages[ $code ] ?? __( 'An unknown error occurred.', 'double-opt-in' );

		return new self( $code, $message, $context );
	}

	/**
	 * Get the error code.
	 *
	 * @return string
	 */
	public function getCode(): string {
		return $this->code;
	}

	/**
	 * Get the human-readable error message.
	 *
	 * @return string
	 */
	public function getMessage(): string {
		return $this->message;
	}

	/**
	 * Get additional context data.
	 *
	 * @return array
	 */
	public function getContext(): array {
		return $this->context;
	}

	/**
	 * Must the visitor see this error, whatever the site configured?
	 *
	 * Only for errors the visitor caused and can fix on the spot. A refused
	 * consent is one: the form looked sent, no mail ever came, and the only
	 * hint was a toast over a green "Thank you" that vanished after ten
	 * seconds (CF7, Core 5.6.1). Rate limits, blocklists and the like stay
	 * behind `f12_cf7_doubleoptin_show_validation_error` — telling a bot why
	 * it was refused is not always wanted.
	 *
	 * @return bool
	 */
	public function isAlwaysShown(): bool {
		return self::CONSENT_NOT_GIVEN === $this->code;
	}

	/**
	 * Should the form show this error in place of its own success message?
	 *
	 * @param int $formId The form the submission came from.
	 *
	 * @return bool
	 */
	public function shouldShowToVisitor( int $formId ): bool {
		if ( $this->isAlwaysShown() ) {
			return true;
		}

		/**
		 * Whether a refused submission's reason is shown in the form.
		 *
		 * Default false. A refused consent is always shown and never
		 * reaches this filter.
		 *
		 * @param bool       $show   Show the error.
		 * @param OptInError $error  The error (since 5.6.2).
		 * @param int        $formId The form (since 5.6.2).
		 */
		return (bool) apply_filters( 'f12_cf7_doubleoptin_show_validation_error', false, $this, $formId );
	}

	/**
	 * Get the default translatable messages for all error codes.
	 *
	 * @return array<string, string>
	 */
	private static function getDefaultMessages(): array {
		return array(
			self::SUBMISSION_CANCELLED   => __( 'The form submission has been cancelled.', 'double-opt-in' ),
			self::NO_RECIPIENT           => __( 'No valid email address was found.', 'double-opt-in' ),
			self::RATE_LIMIT_IP          => __( 'Too many requests. Please try again later.', 'double-opt-in' ),
			self::RATE_LIMIT_EMAIL       => __( 'Too many requests for this email address. Please try again later.', 'double-opt-in' ),
			self::RECIPIENT_INVALID      => __( 'The email address could not be verified.', 'double-opt-in' ),
			self::UNIQUE_EMAIL_DUPLICATE => __( 'This email address has already been used.', 'double-opt-in' ),
			self::SAVE_FAILED            => __( 'An error occurred. Please try again.', 'double-opt-in' ),
			self::CONSENT_NOT_GIVEN      => __( 'You must agree to the consent statement to continue.', 'double-opt-in' ),
		);
	}
}