<?php

/**
 * Ask Query Exception
 *
 * Typed error for AskQueryService failures. Carries the machine code, the
 * intended HTTP status, and any extra fields that should be merged into the
 * raw error envelope. Controllers (AskController, McpController) catch this
 * and project it onto their own wire format — REST envelope vs JSON-RPC
 * error object.
 *
 * @package ProRank\SEO\Core\Schema
 * @since   2.4.0
 */

declare(strict_types=1);

namespace ProRank\SEO\Core\Schema;

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}


class AskQueryException extends \RuntimeException {

    /**
     * @var string Machine-readable code, e.g. `unsupported_mode`.
     */
    private string $error_code;

    /**
     * @var int HTTP status the controller should use when surfacing this
     *          error on the REST wire.
     */
    private int $http_status;

    /**
     * @var array<string, mixed> Extra top-level fields to merge into the
     *                            error response (e.g. `supported_modes`).
     */
    private array $extra;

    /**
     * @param string                $error_code  Machine code.
     * @param string                $message     Human-readable message.
     * @param int                   $http_status HTTP status, default 400.
     * @param array<string, mixed>  $extra       Extra fields.
     */
    public function __construct( string $error_code, string $message, int $http_status = 400, array $extra = [] ) {
        parent::__construct( $message );
        $this->error_code  = $error_code;
        $this->http_status = $http_status;
        $this->extra       = $extra;
    }

    public function get_error_code(): string {
        return $this->error_code;
    }

    public function get_http_status(): int {
        return $this->http_status;
    }

    /**
     * @return array<string, mixed>
     */
    public function get_extra(): array {
        return $this->extra;
    }
}
