<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Ai;

/**
 * The outcome of asking a provider "is this key good?" ({@see AiConnectionTester}).
 *
 * `message` is written for a merchant and for an LLM reading an MCP result, not for a log: it says
 * what to do about the failure. A raw "HTTP 401" tells neither of them whether the key is wrong,
 * expired, or simply pasted with a trailing space.
 *
 * ⚠️ Neither the key nor any request header ever reaches this object — see {@see AiConnectionTester}
 * for why a failure message is composed from the STATUS rather than from the provider's body.
 */
final class AiConnectionResult implements \JsonSerializable
{
    /**
     * @param list<string> $models model ids the key may use; empty when the call failed, and also
     *                             legitimately empty for an endpoint that has no model listing
     */
    public function __construct(
        public readonly bool $ok,
        public readonly string $message,
        public readonly ?int $status = null,
        public readonly array $models = [],
    ) {
    }

    /**
     * @return array{ok: bool, message: string, status: int|null, models: list<string>, modelCount: int}
     */
    public function jsonSerialize(): array
    {
        return [
            'ok'         => $this->ok,
            'message'    => $this->message,
            'status'     => $this->status,
            'models'     => $this->models,
            'modelCount' => \count($this->models),
        ];
    }
}
