<?php
/**
 * Outcome of sending one login code.
 *
 * @package Rahkar\WP
 */

declare( strict_types = 1 );

namespace Rahkar\WP\Modules\OtpAuth;

defined( 'ABSPATH' ) || exit;

/**
 * What happened when a code was put in front of a customer.
 *
 * The distinction the caller needs is not success against failure but whose
 * fault a failure was. When the store's own gateways refused — no credit, a
 * provider outage, nothing configured — the customer's send quota is handed
 * back: charging them an attempt for the store's outage would let one provider
 * blip lock them out for the rest of the window.
 */
final class DispatchOutcome {

	private const SENT       = 'sent';
	private const TEST       = 'test';
	private const NO_GATEWAY = 'no_gateway';
	private const FAILED     = 'failed';

	/**
	 * Use the named constructors.
	 *
	 * @param string $kind     One of the private kind constants.
	 * @param string $driverId Gateway that delivered, when one did.
	 * @param string $message  Provider's own words on failure.
	 * @param string $testCode The code, in test mode only.
	 */
	private function __construct(
		private string $kind,
		private string $driverId = '',
		private string $message = '',
		private string $testCode = ''
	) {}

	/**
	 * A gateway accepted the code.
	 *
	 * @param string $driverId Gateway id.
	 */
	public static function sent( string $driverId ): self {
		return new self( self::SENT, $driverId );
	}

	/**
	 * Nothing left the server; the code is carried back so the allow-listed
	 * tester can be shown it.
	 *
	 * @param string $code The code.
	 */
	public static function testMode( string $code ): self {
		return new self( self::TEST, 'test_mode', '', $code );
	}

	/**
	 * No gateway is enabled and configured.
	 */
	public static function noGateway(): self {
		return new self( self::NO_GATEWAY );
	}

	/**
	 * Every gateway tried refused.
	 *
	 * @param string $message The last gateway's reason.
	 */
	public static function failed( string $message ): self {
		return new self( self::FAILED, '', $message );
	}

	/**
	 * Should the customer expect a code (or be shown one)?
	 */
	public function isDelivered(): bool {
		return self::SENT === $this->kind || self::TEST === $this->kind;
	}

	/**
	 * Was this a test-mode send?
	 */
	public function isTestMode(): bool {
		return self::TEST === $this->kind;
	}

	/**
	 * Did nothing go out because of the store rather than the customer?
	 */
	public function isShopFault(): bool {
		return self::NO_GATEWAY === $this->kind || self::FAILED === $this->kind;
	}

	/**
	 * Was nothing configured to send with?
	 */
	public function hasNoGateway(): bool {
		return self::NO_GATEWAY === $this->kind;
	}

	/**
	 * The gateway that delivered, or `test_mode`, or empty.
	 */
	public function driverId(): string {
		return $this->driverId;
	}

	/**
	 * The provider's reason. For the log and the admin — never shown to a
	 * customer, who cannot act on "pattern 4412 is not approved".
	 */
	public function message(): string {
		return $this->message;
	}

	/**
	 * The code, only ever non-empty in test mode.
	 */
	public function testCode(): string {
		return $this->testCode;
	}
}