<?php
/**
 * Неудача действия плагина с текстом для человека.
 *
 * @package Aimodelka
 */

namespace Aimodelka;

use Aimodelka\Admin\Notices;
use Aimodelka\Admin\Texts;
use Aimodelka\Api\Api_Exception;
use Aimodelka\Api\Error_Kind;

defined( 'ABSPATH' ) || exit;

/**
 * Действие плагина не удалось — подготовка окна или сохранение фото в товар.
 *
 * Сообщение исключения — готовый текст для человека на языке админки: его показывают
 * в окне, на странице товара и отдают окну генерации в ответе «save-failed». Любой сбой
 * ловится и превращается в такое исключение, а не обрывает страницу
 * (Documents/WPPlugin-HLD.md §4.3).
 *
 * Признак «временная» говорит, поможет ли повтор позже без участия человека: по нему
 * сохранение остаётся ожидающим и доделывается фоновой задачей.
 */
final class Action_Failed extends \RuntimeException {

	/**
	 * Создаёт исключение.
	 *
	 * @param string $message   Текст для человека, уже переведённый.
	 * @param bool   $temporary Поможет ли повтор позже.
	 */
	public function __construct( string $message, public readonly bool $temporary = false ) {
		parent::__construct( $message );
	}

	/**
	 * Неудача из-за отказа API aiModelka: текст по виду отказа.
	 *
	 * Отказ «ключ неверен» заодно ставит отметку для уведомления в админке — тот, кто может
	 * поменять ключ, увидит её на любой странице.
	 *
	 * @param Api_Exception $exception Отказ API.
	 * @param string        $addition  Что добавить к тексту, например «уже отправленные фото повторно не уйдут».
	 * @return self
	 */
	public static function from_api( Api_Exception $exception, string $addition = '' ): self {
		if ( Error_Kind::KeyInvalid === $exception->kind ) {
			Notices::flag_key_rejected();
		}

		$message = Texts::for_error( $exception->kind );

		if ( '' !== $addition ) {
			$message .= ' ' . $addition;
		}

		return new self( $message, $exception->kind->is_temporary() );
	}
}