<?php
/**
 * Fehler beim Aufruf der Aivor-API.
 *
 * @package Aivor\Content
 */

namespace Aivor\Content\Api;

defined( 'ABSPATH' ) || exit;

/**
 * Traegt HTTP-Status und Serverantwort, damit der Aufrufer zwischen
 * Transportfehler, fachlicher Ablehnung und unbekannter Action unterscheiden
 * kann. Die Meldung enthaelt nie den API-Key.
 */
final class ApiException extends \RuntimeException {

	/**
	 * Baut die Ausnahme.
	 *
	 * @param string $message      Meldung fuer Protokoll und Job-Fehlerfeld.
	 * @param int    $status       HTTP-Status, 0 bei einem Transportfehler.
	 * @param string $server_error Fehlertext des Servers, leer wenn keiner kam.
	 */
	public function __construct(
		string $message,
		public readonly int $status = 0,
		public readonly string $server_error = ''
	) {
		parent::__construct( $message, $status );
	}

	/**
	 * Ob der Server gar nicht erreicht wurde.
	 *
	 * @return bool
	 */
	public function is_transport_error(): bool {
		return 0 === $this->status;
	}

	/**
	 * Ob der Server die Action nicht kennt — ein aelterer Server-Stand.
	 *
	 * Das Gateway antwortet dann mit 404 und „Action '…' not found.". Weil die
	 * Key-Pruefung davor laeuft, ist der Key in diesem Fall gueltig.
	 *
	 * @return bool
	 */
	public function is_unknown_action(): bool {
		// Der Fehlertext wird beim Werfen escaped; verglichen wird der Klartext.
		$error = html_entity_decode( $this->server_error, ENT_QUOTES, 'UTF-8' );

		return 404 === $this->status && 1 === preg_match( "/^Action '.*' not found\\.$/", $error );
	}
}