<?php

/**
 * This file is part of the AI Access library.
 * Copyright (c) 2024 David Grudl (https://davidgrudl.com)
 */

declare(strict_types=1);

namespace AIAccess\Batch;

use AIAccess\Chat\Message;


/**
 * Represents the state and eventual result of a batch processing job.
 */
interface Response
{
	/**
	 * Gets the current status of the batch job.
	 */
	function getStatus(): Status;

	/**
	 * Gets the output messages generated by the completed batch job.
	 * Keys in the returned array correspond to custom_id values from requests.
	 * @return Message[]|null
	 */
	function getMessages(): ?array;

	/**
	 * Gets the error information if the batch job had any issues, otherwise null.
	 */
	function getError(): ?string;

	/**
	 * Gets the timestamp when the batch job was created.
	 */
	function getCreatedAt(): ?\DateTimeImmutable;

	/**
	 * Gets the timestamp when the batch job finished processing (completed, failed, or cancelled).
	 */
	function getCompletedAt(): ?\DateTimeImmutable;

	/**
	 * Gets the raw, unprocessed result data associated with the batch job from the API.
	 */
	function getRawResult(): mixed;
}
