<?php
/**
 * Send result.
 *
 * @package Rahkar\WP
 */

declare( strict_types = 1 );

namespace Rahkar\WP\Notifications;

defined( 'ABSPATH' ) || exit;

/**
 * The outcome of one delivery attempt.
 *
 * Deliberately not a `bool` or a `WP_Error`. A store needs to answer three
 * questions after the fact — did it go, what did it cost, and what did the
 * provider actually say — and a boolean answers none of them. The provider's
 * message id is what makes a delivery traceable in their panel when a customer
 * claims they never got the code.
 *
 * `retryable` is the field the queue acts on: a wrong API key should not be
 * retried five times over the next half hour, but a timeout should.
 */
final class Result {

	/**
	 * Constructor promotion without `readonly`: the plugin targets PHP 8.0, where
	 * that modifier does not yet exist. The constructor is private and no setters
	 * are offered, which gets the same immutability in practice.
	 *
	 * @param bool                $ok        Whether the provider accepted the message.
	 * @param string              $messageId Provider's own identifier, for tracing.
	 * @param float               $cost      Reported cost, when the provider returns one.
	 * @param string              $errorCode Machine-readable failure code.
	 * @param string              $error     Human-readable failure message.
	 * @param bool                $retryable Whether trying again could succeed.
	 * @param array<string,mixed> $raw       Decoded provider response, for the log.
	 */
	private function __construct(
		public bool $ok,
		public string $messageId = '',
		public float $cost = 0.0,
		public string $errorCode = '',
		public string $error = '',
		public bool $retryable = false,
		public array $raw = []
	) {}

	/**
	 * The provider accepted the message.
	 *
	 * @param string              $messageId Provider identifier.
	 * @param float               $cost      Reported cost.
	 * @param array<string,mixed> $raw       Decoded response.
	 */
	public static function success( string $messageId = '', float $cost = 0.0, array $raw = [] ): self {
		return new self( true, $messageId, $cost, '', '', false, $raw );
	}

	/**
	 * The attempt failed, but trying again might work.
	 *
	 * Network timeouts, HTTP 5xx, provider rate limits.
	 *
	 * @param string              $code    Machine-readable code.
	 * @param string              $message Human-readable message.
	 * @param array<string,mixed> $raw     Decoded response.
	 */
	public static function retryable( string $code, string $message, array $raw = [] ): self {
		return new self( false, '', 0.0, $code, $message, true, $raw );
	}

	/**
	 * The attempt failed and will keep failing.
	 *
	 * Bad credentials, unknown pattern code, malformed recipient, empty credit.
	 * Retrying these burns the queue and delays real work.
	 *
	 * @param string              $code    Machine-readable code.
	 * @param string              $message Human-readable message.
	 * @param array<string,mixed> $raw     Decoded response.
	 */
	public static function permanent( string $code, string $message, array $raw = [] ): self {
		return new self( false, '', 0.0, $code, $message, false, $raw );
	}

	/**
	 * Loggable summary. Never includes credentials.
	 *
	 * @return array<string, mixed>
	 */
	public function toLog(): array {
		return array_filter(
			[
				'ok'         => $this->ok,
				'message_id' => $this->messageId,
				'cost'       => $this->cost,
				'error_code' => $this->errorCode,
				'error'      => $this->error,
				'retryable'  => $this->retryable,
			],
			static fn( $value ): bool => '' !== $value && 0.0 !== $value
		);
	}
}