<?php
/**
 * Standardized REST API error response formatter.
 *
 * Ensures every error returned by the AICommerce REST API follows
 * a consistent envelope structure.
 *
 * @package AICommerce\API
 */

declare(strict_types=1);

namespace AICommerce\API;

/**
 * Formats REST API error responses.
 */
class ErrorFormatter {

	/**
	 * Create a standardized error response.
	 *
	 * @param string $code    Machine-readable error slug.
	 * @param string $message Human-readable error message.
	 * @param int    $status  HTTP status code.
	 * @param array  $details Additional error details.
	 *
	 * @return \WP_REST_Response
	 */
	public static function error( string $code, string $message, int $status = 400, array $details = array() ): \WP_REST_Response {
		$data = array(
			'code'    => $code,
			'message' => $message,
			'data'    => array_merge( array( 'status' => $status ), $details ),
		);

		return new \WP_REST_Response( $data, $status );
	}

	/**
	 * Create a Pro-required error response.
	 *
	 * @param string $feature_name The feature requiring Pro.
	 *
	 * @return \WP_REST_Response
	 */
	public static function pro_required( string $feature_name ): \WP_REST_Response {
		return self::error(
			'pro_required',
			sprintf(
				/* translators: %s: Feature name */
				__( '%s requires a Pro license.', 'ai-discoverability-kit' ),
				$feature_name
			),
			403,
			array( 'upgrade' => true )
		);
	}

	/**
	 * Create a rate-limit exceeded response.
	 *
	 * @param int $retry_after Seconds until the rate limit resets.
	 *
	 * @return \WP_REST_Response
	 */
	public static function rate_limited( int $retry_after = 60 ): \WP_REST_Response {
		$response = self::error(
			'rate_limit_exceeded',
			__( 'Too many requests. Please try again later.', 'ai-discoverability-kit' ),
			429
		);

		$response->header( 'Retry-After', (string) $retry_after );

		return $response;
	}

	/**
	 * Create a not-found error response.
	 *
	 * @param string $resource_name The resource type that was not found.
	 *
	 * @return \WP_REST_Response
	 */
	public static function not_found( string $resource_name = 'Resource' ): \WP_REST_Response {
		return self::error(
			'not_found',
			sprintf(
				/* translators: %s: Resource type */
				__( '%s not found.', 'ai-discoverability-kit' ),
				$resource_name
			),
			404
		);
	}
}