<?php
/**
 * Ответ на просьбу окна загрузить одно фото товара.
 *
 * @package Aimodelka
 */

namespace Aimodelka\Rest;

use Aimodelka\Api\Error_Kind;
use Aimodelka\Media\Source_Photo_Links;

defined( 'ABSPATH' ) || exit;

/**
 * Что адрес `POST products/{id}/photos/upload` отвечает скрипту страницы товара, а тот — окну
 * генерации (Documents/WPPlugin-HLD.md §4.4, сообщения «product-photo-uploaded»
 * и «product-photo-failed»).
 *
 * Исходов три, и окно делает с ними разное:
 *
 * - «загружено» — фото вещи, куда фото легло на самом деле: сервер мог переложить его
 *   в рекомендуемый свободный слот, и окно ведёт занятость слотов по этому ответу;
 * - «не прошло проверку» — повтор не поможет: окно вернёт фото человеку в левую колонку
 *   с пометкой. Код ошибки aiModelka уходит окну как есть: по `CONTENT_REJECTED` оно
 *   показывает объяснение, как снимать;
 * - сбой — повтор может помочь: окно оставит фото в слоте и повторит по «Продолжить».
 *   Сбой отдаётся ошибкой REST с текстом для человека, а не этим ответом.
 *
 * Чистая логика без WordPress — проверяется тестами.
 */
final class Upload_Reply {

	/** Исход «загружено». */
	public const UPLOADED = 'uploaded';

	/** Исход «не прошло проверку». */
	public const REJECTED = 'rejected';

	/**
	 * Ответ «загружено».
	 *
	 * @param mixed $server_photo Фото вещи (`SourcePhoto`) из ответа aiModelka.
	 * @return array{result: string, photo: array{id: string, slot: string, sizeBytes: int|null}}|null
	 *         Null — ответ сервера не того вида: это сбой, а не успех.
	 */
	public static function uploaded( mixed $server_photo ): ?array {
		$photo = Source_Photo_Links::photo_ref( $server_photo );

		if ( null === $photo ) {
			return null;
		}

		return array(
			'result' => self::UPLOADED,
			'photo'  => $photo,
		);
	}

	/**
	 * Ответ «не прошло проверку».
	 *
	 * @param string $code    Код ошибки aiModelka (`CONTENT_REJECTED`, `FILE_TOO_LARGE` и т. п.);
	 *                        пустая строка — файл отсеял сам плагин, до отправки.
	 * @param string $message Что не так, словами, на языке админки.
	 * @return array{result: string, code: string, message: string}
	 */
	public static function rejected( string $code, string $message ): array {
		return array(
			'result'  => self::REJECTED,
			'code'    => $code,
			'message' => $message,
		);
	}

	/**
	 * Значит ли отказ aiModelka «не прошло проверку», а не сбой.
	 *
	 * Только отказ по самому фото — проверка содержимого, размер, число точек, формат
	 * (Error_Kind::PhotoRejected). Всё остальное — недоступность, ключ, лимиты, удалённая
	 * фотосессия — сбой: фото тут ни при чём, и возвращать его человеку как негодное нельзя.
	 *
	 * @param Error_Kind $kind Вид отказа.
	 * @return bool
	 */
	public static function is_rejection( Error_Kind $kind ): bool {
		return Error_Kind::PhotoRejected === $kind;
	}
}