<?php
/**
 * Connector Result Value Object
 *
 * Standardises the return value from connector operations.
 *
 * @package AmbassadorHub\Connectors
 */

namespace AmbassadorHub\Connectors;

/**
 * Immutable value object returned by connector operations.
 *
 * Covers both synchronous PSP payment initiations (which return a redirect_url)
 * and any other connector operation that needs to communicate success/failure
 * back to the caller.
 */
final class ConnectorResult {

	/**
	 * @param bool        $success        Whether the operation succeeded.
	 * @param string|null $transaction_id PSP transaction / order ID, if applicable.
	 * @param string|null $redirect_url   Hosted checkout URL to redirect the donor to (PSP phase 1).
	 * @param string|null $error_message  Human-readable failure reason, if success is false.
	 */
	public function __construct(
		public readonly bool $success,
		public readonly ?string $transaction_id = null,
		public readonly ?string $redirect_url = null,
		public readonly ?string $error_message = null,
	) {}

	/**
	 * Create a successful result.
	 *
	 * @param string|null $transaction_id PSP transaction ID.
	 * @param string|null $redirect_url   Hosted checkout redirect URL.
	 * @return self
	 */
	public static function ok( ?string $transaction_id = null, ?string $redirect_url = null ): self {
		return new self(
			success: true,
			transaction_id: $transaction_id,
			redirect_url: $redirect_url,
		);
	}

	/**
	 * Create a failed result.
	 *
	 * @param string $error_message Human-readable reason for the failure.
	 * @return self
	 */
	public static function fail( string $error_message ): self {
		return new self(
			success: false,
			error_message: $error_message,
		);
	}
}
