<?php
declare(strict_types=1);

namespace Phred\Http\Contracts;

use Psr\Http\Message\ResponseInterface;

interface ApiResponseFactoryInterface
{
    /**
     * Generic 200 OK with array payload.
     * Implementations must set appropriate Content-Type.
     * @param array<string,mixed> $data
     */
    public function ok(array $data = []): ResponseInterface;

    /**
     * 201 Created with array payload.
     * @param array<string,mixed> $data
     * @param string|null $location Optional Location header
     */
    public function created(array $data = [], ?string $location = null): ResponseInterface;

    /**
     * 204 No Content
     */
    public function noContent(): ResponseInterface;

    /**
     * Error response with status and details.
     * @param int $status HTTP status code (4xx/5xx)
     * @param string $title Short, human-readable summary
     * @param string|null $detail Detailed description
     * @param array<string,mixed> $extra Extra members dependent on format
     */
    public function error(int $status, string $title, ?string $detail = null, array $extra = []): ResponseInterface;

    /**
     * Create a response from a raw associative array payload.
     * @param array<string,mixed> $payload
     * @param int $status
     */
    public function fromArray(array $payload, int $status = 200): ResponseInterface;
}