* @copyright 2026 webhead GmbH */ declare( strict_types=1 ); namespace Webhead\WP\SearchCloud\Connection; use WP_Error; use Webhead\WP\SearchCloud\Enums\Account_Refusal; defined( 'ABSPATH' ) || exit; /** * @since 1.0.0 */ final class Api_Response { /** * @param array $body */ private function __construct( public readonly int $status, public readonly array $body, public readonly ?int $retry_after = null, public readonly bool $transport_error = false, public readonly string $error_message = '', ) {} /** * @param array|\WP_HTTP_Response|array $response wp_remote_request result. */ public static function from_http( int $status, mixed $response ): self { $raw = wp_remote_retrieve_body( $response ); $body = json_decode( is_string( $raw ) ? $raw : '', true ); $body = is_array( $body ) ? $body : []; $retry_after_header = wp_remote_retrieve_header( $response, 'retry-after' ); $retry_after = is_numeric( $retry_after_header ) ? (int) $retry_after_header : null; return new self( $status, $body, $retry_after ); } /** * A successful answer read again from where it was kept * ({@see Search_Cloud_Client}): its status and its body. * * @param array $body */ public static function kept( int $status, array $body ): self { return new self( $status, $body ); } public static function from_transport_error( WP_Error $error ): self { return new self( 0, [], null, true, $error->get_error_message() ); } public function ok(): bool { return $this->status >= 200 && $this->status < 300; } /** * A plan-limit 429 carries `{ metric, limit }` and is not transient. */ public function is_plan_limit(): bool { return 429 === $this->status && isset( $this->body['metric'] ); } /** * An account without an active plan, or a suspended one, is refused with * `402`/`403` and a `reason`. Only choosing a plan or the end of the * suspension changes that, so the call is never tried again: a `402` or * `403` is not one {@see self::should_retry()} retries. */ public function account_refusal(): ?Account_Refusal { return Account_Refusal::from_response( $this->status, $this->body ); } public function should_retry(): bool { if ( $this->transport_error ) { return true; } if ( 429 === $this->status ) { return ! $this->is_plan_limit(); } return $this->status >= 500; } public function retry_after(): ?int { return $this->retry_after; } /** * @return array */ public function body(): array { return $this->body; } }