<?php
// SPDX-License-Identifier: GPL-3.0-or-later
declare(strict_types=1);

namespace Aiwend\Provider;

/**
 * What a provider reported about a completed request beyond the input and output totals, as a price needs it. Every field is null when
 * the provider did not report it (unknown, never zero), except where a provider's protocol defines an omitted count as none.
 *
 *  - cachedInputTokens: the part of the input tokens that was served from a cache (OpenAI, Gemini). Not reported by Anthropic here.
 *  - reasoningTokens: the part of the output tokens spent on reasoning (OpenAI, Gemini). Already inside the output total; information only.
 *  - otherTokens: token categories this price list cannot price: Anthropic cache reads and writes (NOT inside the input total), OpenAI cache writes, Gemini tool-use prompt tokens. A request that has any is not priced.
 *  - servedModel: the model identifier the provider says answered, which can be a dated snapshot of the alias that was requested.
 */
final class UsageDetail
{
    public function __construct(
        public readonly string $provider,
        public readonly ?string $servedModel = null,
        public readonly ?int $cachedInputTokens = null,
        public readonly ?int $reasoningTokens = null,
        public readonly ?int $otherTokens = null,
        public readonly ?string $processingTier = null,
    ) {
    }

    /** A plain model identifier, or null. */
    public static function cleanModel(mixed $model): ?string
    {
        return is_string($model) && preg_match('/^[A-Za-z0-9][A-Za-z0-9._:\/@+-]{0,190}$/D', $model) === 1 ? $model : null;
    }

    /** The provider's name for the processing tier of the request ("default", "standard", "priority", "flex"...), lower case, or null. */
    public static function cleanTier(mixed $tier): ?string
    {
        return is_string($tier) && preg_match('/^[A-Za-z_]{1,16}$/D', $tier) === 1 ? strtolower($tier) : null;
    }

    /**
     * Builds the detail of one response, dropping any count that cannot be right (a cached part larger than the input, reasoning
     * larger than the output, a negative or absurd number) instead of storing it.
     */
    public static function from(string $provider, mixed $servedModel, int $input, int $output, mixed $cached, mixed $reasoning, mixed $other, mixed $tier = null): self
    {
        $ok = static fn(mixed $v, int $max): ?int => is_int($v) && $v >= 0 && $v <= $max ? $v : null;
        return new self($provider, self::cleanModel($servedModel), $ok($cached, $input), $ok($reasoning, $output), $ok($other, 1_000_000_000), self::cleanTier($tier));
    }
}