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

namespace Aiwend\WordPress;

use Aiwend\Policy\Capabilities;
use Aiwend\Pricing\Amount;
use Aiwend\Pricing\CostCalculator;
use Aiwend\Pricing\CostReport;
use Aiwend\Pricing\PriceBook;
use Aiwend\Pricing\PriceOverrides;
use Aiwend\Usage\ClientBudget;
use Aiwend\Usage\LimitWarnings;
use Aiwend\Usage\Reservation;
use Aiwend\Usage\UsageSeries;

/**
 * Usage screen sections added in Phase 118 (B1-a): preventive limit warnings, the limits in force and what each applies to, daily and
 * monthly usage from the site's own calendar, and a short glossary. Everything is read from the local accounting rows; nothing here
 * contacts a provider, and nothing is shown that the stored records do not support (an unmeasured quantity is "Not available", never 0).
 * Rendered only on Aiwend's own screens, for people who may view usage.
 */
final class UsageReports
{
    public function __construct(private Plugin $plugin)
    {
    }

    private static function n(int $v): string
    {
        return number_format_i18n($v);
    }

    /** Output of markup built from escaped parts, integers and fixed labels, filtered once more through the admin allowlist (wp_kses). */
    private function out(string $html): void
    {
        echo wp_kses($html, AdminView::allowedHtml()); // the markup is built from escaped parts; the allowlist is the second barrier
    }

    // ---------------------------------------------------------------- warnings

    /** On-screen warnings before the site limit is reached. No stored state, no dismissal: they disappear when the condition does. */
    public function warnings(): void
    {
        if (!current_user_can(Capabilities::VIEW_USAGE)) {
            return;
        }
        $site = get_current_blog_id();
        $warnings = LimitWarnings::forSite($this->plugin->ledger, $site, $this->plugin->clock->now(), wp_timezone());
        $usage = AdminView::url('aiwend-usage');
        // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only navigation parameter; only decides whether to show a link
        $onUsage = isset($_GET['page']) && sanitize_key((string) wp_unslash($_GET['page'])) === 'aiwend-usage';
        foreach ($warnings as $w) {
            $available = self::n((int) $w['available']);
            [$tone, $title, $text] = match ($w['code']) {
                'exhausted' => ['error', __('The site usage limit is used up.', 'aiwend'),
                    __('This limit is shared by all visitors together, so every assistant refuses new questions until it is raised. The per-conversation and per-visitor limits are separate. Raise the site limit on the Usage page when you are ready to allow more use.', 'aiwend')],
                'warning_95' => ['warning', sprintf(/* translators: %d: percentage of the site usage limit that is used or held */ __('The site usage limit is %d%% used.', 'aiwend'), (int) $w['percent']),
                    sprintf(/* translators: %s: usage units still available under the site limit */ __('About %s usage units remain. This limit is shared by all visitors together; when it is used up, every assistant stops answering until you raise it. The per-conversation and per-visitor limits are separate. Review where usage comes from below, or raise the site limit.', 'aiwend'), $available)],
                'notice_80' => ['info', sprintf(/* translators: %d: percentage of the site usage limit that is used or held */ __('The site usage limit is %d%% used.', 'aiwend'), (int) $w['percent']),
                    sprintf(/* translators: %s: usage units still available under the site limit */ __('About %s usage units remain, and nothing is being refused yet. This limit is shared by all visitors together; each visitor and each conversation also has a separate limit. Review where usage comes from below, or raise the site limit before it runs out.', 'aiwend'), $available)],
                'headroom' => ['warning', __('Little room is left for another answer.', 'aiwend'),
                    sprintf(/* translators: %s: usage units still available under the site limit */ __('Only about %s usage units remain under the site limit, which is less than recent answers each set aside. The next answers may be refused even though the limit is not used up yet. Review usage, or raise the site limit.', 'aiwend'), $available)],
                default => ['info', __('Projection from recent use.', 'aiwend'),
                    sprintf(/* translators: 1: number of days, 2: usage units still available under the site limit */ __('At the pace of the last 7 days the remaining %2$s usage units of the site limit would last about %1$d days. This is a projection from past use, not a guarantee; a busy day changes it. Review usage if that is sooner than you want.', 'aiwend'), (int) ($w['days'] ?? 0), $available)],
            };
            $this->out(sprintf(
                '<div class="notice notice-%1$s aw-notice aw-limit-warning" role="%2$s" data-aiwend-warning="%3$s"><p><strong>%4$s</strong> %5$s%6$s</p></div>',
                esc_attr($tone),
                $tone === 'error' ? 'alert' : 'status',
                esc_attr((string) $w['code']),
                esc_html($title),
                esc_html($text),
                $onUsage ? '' : ' <a href="' . esc_url($usage) . '">' . esc_html__('Review usage', 'aiwend') . '</a>'
            ));
        }
    }

    // ---------------------------------------------------------------- limits in force

    /** The three kinds of limit, each with what it applies to: a site allowance is never presented as a visitor's allowance. */
    public function limitsInForce(): void
    {
        $site = get_current_blog_id();
        $b = $this->plugin->ledger->balance($site, 'site') ?? ['limit' => 0, 'reserved' => 0, 'spent' => 0, 'available' => 0];
        $session = (int) $this->plugin->options->get('aiwend_session_budget_units', 20000);
        $daily = ClientBudget::dailyUnits($this->plugin->options->get(ClientBudget::OPTION_DAILY));
        $share = ClientBudget::sharePercent($this->plugin->options->get(ClientBudget::OPTION_SHARE));
        $this->out('<section class="aw-card"><h2 class="aw-h3">' . esc_html__('Which limit applies to what', 'aiwend') . '</h2>');
        $this->out('<div class="aw-table-wrap"><table class="aw-table aw-table--stack" data-aiwend-limits><thead><tr><th scope="col">' . esc_html__('Limit', 'aiwend') . '</th><th scope="col">' . esc_html__('Amount', 'aiwend') . '</th><th scope="col">' . esc_html__('Applies to', 'aiwend') . '</th></tr></thead><tbody>');
        $this->out('<tr data-aiwend-limit="site"><th scope="row">' . esc_html__('Site', 'aiwend') . '</th><td>'
            . esc_html($b['limit'] > 0 ? sprintf(/* translators: 1: used or held units, 2: the limit, both in usage units */ __('%1$s of %2$s usage units used or held', 'aiwend'), self::n((int) $b['spent'] + (int) $b['reserved']), self::n((int) $b['limit'])) : __('Not set: assistants cannot answer', 'aiwend'))
            . '</td><td>' . esc_html__('Shared by all visitors together, across all assistants. When it is used up every assistant stops answering until it is raised.', 'aiwend') . '</td></tr>');
        $this->out('<tr data-aiwend-limit="conversation"><th scope="row">' . esc_html__('Each conversation', 'aiwend') . '</th><td>'
            . esc_html(sprintf(/* translators: %s: usage units */ __('%s usage units', 'aiwend'), self::n($session))) . '</td><td>'
            . esc_html__('One conversation on its own. Reaching it ends that conversation only; other conversations and the site limit are not affected.', 'aiwend') . '</td></tr>');
        $this->out('<tr data-aiwend-limit="visitor"><th scope="row">' . esc_html__('Each visitor, per day', 'aiwend') . '</th><td>'
            . esc_html(sprintf(/* translators: 1: usage units a day, 2: percentage of the site limit */ __('%1$s usage units a day, and at most %2$d%% of the site limit', 'aiwend'), self::n($daily), $share)) . '</td><td>'
            . esc_html__('Applies to each visitor separately (a signed-in account, or a network address: people sharing an address share it). Reaching it stops that visitor for the rest of the day (UTC) and no one else.', 'aiwend') . '</td></tr>');
        $this->out('</tbody></table></div></section>');
    }

    // ---------------------------------------------------------------- daily and monthly usage

    /** Usage per day (31 days) or per month (12 months) of the site's own calendar. Reads this site's stored records in one bounded query. */
    public function series(): void
    {
        // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only navigation parameter; no state is changed
        $kind = isset($_GET['series']) && sanitize_key((string) wp_unslash($_GET['series'])) === 'monthly' ? 'monthly' : 'daily';
        $tz = wp_timezone();
        $now = $this->plugin->clock->now();
        $periods = $kind === 'monthly' ? UsageSeries::months($now, $tz) : UsageSeries::days($now, $tz);
        $totals = $this->plugin->ledger->periodTotals(get_current_blog_id(), $periods);
        $costs = $this->costReport()->summarize(get_current_blog_id(), $periods);
        $format = $kind === 'monthly' ? 'Y-m' : 'Y-m-d';
        $this->out('<section class="aw-card"><div class="aw-sectionhead"><h2 class="aw-h3">' . esc_html__('Usage over time', 'aiwend') . '</h2><p class="aw-actionrow">'
            . '<a class="button' . ($kind === 'daily' ? ' button-primary' : '') . '" href="' . esc_url(AdminView::url('aiwend-usage', ['series' => 'daily'])) . '"' . ($kind === 'daily' ? ' aria-current="true"' : '') . '>' . esc_html__('Daily, last 31 days', 'aiwend') . '</a> '
            . '<a class="button' . ($kind === 'monthly' ? ' button-primary' : '') . '" href="' . esc_url(AdminView::url('aiwend-usage', ['series' => 'monthly'])) . '"' . ($kind === 'monthly' ? ' aria-current="true"' : '') . '>' . esc_html__('Monthly, last 12 months', 'aiwend') . '</a></p></div>');
        $this->out('<p class="aw-muted">' . esc_html(sprintf(/* translators: %s: time zone name */ __('Days and months follow this site’s time zone (%s). A request counts on the day it started. Columns are different measures and are not added together; “Usage units” is everything that counted against your limits.', 'aiwend'), $tz->getName())) . '</p>');
        $empty = array_sum(array_map(static fn(array $t): int => (int) $t['requests'] + (int) $t['units'] + (int) $t['held_units'], $totals)) === 0;
        if ($empty) {
            // Nothing recorded in this window: say so briefly; the full grid (all zeros) stays available on demand.
            $this->out('<p data-aiwend-series-empty><strong>' . esc_html($kind === 'monthly' ? __('No usage recorded in the last months.', 'aiwend') : __('No usage recorded in the last 31 days.', 'aiwend')) . '</strong> '
                . esc_html__('Usage appears here after an assistant answers, a draft is written or a message is analysed with a real or simulated provider.', 'aiwend') . '</p><details class="aw-details"><summary>' . esc_html__('Show the empty table anyway', 'aiwend') . '</summary>');
        }
        $this->out('<div class="aw-table-wrap"><table class="aw-table aw-table--stack aw-usage-series" data-aiwend-series="' . esc_attr($kind) . '"><thead><tr><th scope="col">' . ($kind === 'monthly' ? esc_html__('Month', 'aiwend') : esc_html__('Day', 'aiwend')) . '</th>'
            . '<th scope="col">' . esc_html__('Attempts', 'aiwend') . '</th><th scope="col">' . esc_html__('Usage units', 'aiwend') . '</th>'
            . '<th scope="col">' . esc_html__('Reported by provider', 'aiwend') . '</th><th scope="col">' . esc_html__('Entered by admin', 'aiwend') . '</th><th scope="col">' . esc_html__('Estimated', 'aiwend') . '</th><th scope="col">' . esc_html__('Simulated', 'aiwend') . '</th><th scope="col">' . esc_html__('Older records', 'aiwend') . '</th>'
            . '<th scope="col">' . esc_html__('Provider tokens (input / output)', 'aiwend') . '</th><th scope="col">' . esc_html__('Estimated cost (not an invoice)', 'aiwend') . '</th><th scope="col">' . esc_html__('Held or unresolved', 'aiwend') . '</th></tr></thead><tbody>');
        $dash = '<span class="aw-muted">—</span>';
        foreach ($periods as $i => $p) {
            $t = $totals[$i];
            $label = (new \DateTimeImmutable('@' . $p['start']))->setTimezone($tz)->format($format);
            $basis = static fn(string $b): string => isset($t['units_by_basis'][$b]) && $t['units_by_basis'][$b] > 0 ? esc_html(self::n($t['units_by_basis'][$b])) : '<span class="aw-muted">—</span>';
            $held = $t['held_units'] > 0
                ? esc_html(sprintf(/* translators: 1: usage units held, 2: number of requests */ _n('%1$s units (%2$d request)', '%1$s units (%2$d requests)', $t['unresolved_requests'] + $t['in_progress_requests'], 'aiwend'), self::n($t['held_units']), $t['unresolved_requests'] + $t['in_progress_requests']))
                : $dash;
            $this->out('<tr data-period="' . esc_attr($label) . '"><th scope="row">' . esc_html(wp_date($kind === 'monthly' ? 'F Y' : get_option('date_format'), $p['start'], $tz)) . '</th>'
                . '<td data-col="requests">' . esc_html(self::n($t['requests'])) . '</td>'
                . '<td data-col="units">' . esc_html(self::n($t['units'])) . '</td>'
                . '<td data-col="reported">' . $basis(Reservation::BASIS_REPORTED) . '</td>'
                . '<td data-col="entered">' . $basis(Reservation::BASIS_ADMIN_ENTERED) . '</td>'
                . '<td data-col="estimated">' . $basis(Reservation::BASIS_ESTIMATED) . '</td>'
                . '<td data-col="simulated">' . $basis(Reservation::BASIS_SIMULATED) . '</td>'
                . '<td data-col="legacy">' . $basis(Reservation::BASIS_LEGACY) . '</td>'
                . '<td data-col="provider_tokens">' . self::tokensCell($t['requests'], $t['provider_input_tokens'], $t['provider_output_tokens'], $t['reported_with_breakdown'], $t['reported_requests']) . '</td>'
                . '<td data-col="cost">' . self::costCell($costs[$i]) . '</td>'
                . '<td data-col="held">' . $held . '</td></tr>');
        }
        $this->out('</tbody></table></div>' . ($empty ? '</details>' : '') . '</section>');
    }

    /**
     * Provider token totals for a row, or why there are none. Null means no request carried a breakdown: that is "Not available", never 0.
     * When only some reported requests carry one, the numbers cover those only and the cell says how many.
     */
    public static function tokensCell(int $requests, ?int $in, ?int $out, int $withBreakdown, int $comparedTo): string
    {
        if ($in === null || $out === null) {
            return $requests > 0 ? esc_html__('Not available', 'aiwend') : '<span class="aw-muted">—</span>';
        }
        $text = sprintf(/* translators: 1: provider-reported input tokens, 2: provider-reported output tokens */ __('%1$s in / %2$s out', 'aiwend'), self::n($in), self::n($out));
        if ($comparedTo > $withBreakdown) {
            $text .= ' · ' . sprintf(/* translators: 1: requests with a provider breakdown, 2: requests it could cover */ __('%1$d of %2$d requests', 'aiwend'), $withBreakdown, $comparedTo);
        }
        return esc_html($text);
    }

    // ---------------------------------------------------------------- estimated cost (B1-b)

    private function book(): PriceBook
    {
        return PriceBook::bundled((new PriceOverrides($this->plugin->options, $this->plugin->clock))->all());
    }

    private function costReport(): CostReport
    {
        return new CostReport($this->plugin->db, $this->book());
    }

    /** An amount for people: the currency code first, 4 decimals below one unit and 2 from one unit up, half up; tiny amounts are said to be tiny. */
    public static function money(Amount $a, string $currency): string
    {
        if ($a->isZero()) {
            return $currency . ' 0';
        }
        if ($a->micro < 100) {
            return sprintf(/* translators: %s: currency code */ __('less than %s 0.0001', 'aiwend'), $currency);
        }
        return $currency . ' ' . $a->toDecimalString($a->micro < 1_000_000 ? 4 : 2);
    }

    /** @return array<string, string> */
    private static function reasons(): array
    {
        return [
            PriceBook::NO_RATE => __('no price is listed for the model', 'aiwend'),
            PriceBook::BEFORE_RATES => __('older than the first verified price list', 'aiwend'),
            CostCalculator::MODEL_UNKNOWN => __('the model was not recorded', 'aiwend'),
            CostCalculator::DETAILS_MISSING => __('cached-token details were not recorded', 'aiwend'),
            CostCalculator::DETAILS_INVALID => __('the recorded token details are inconsistent', 'aiwend'),
            CostCalculator::NO_CACHED_RATE => __('cached input was used but no cached-input price is listed', 'aiwend'),
            CostCalculator::OTHER_CATEGORIES => __('it used a token category Aiwend does not price (for example prompt caching)', 'aiwend'),
            CostCalculator::TIER_UNKNOWN => __('the provider did not say how the request was processed (standard, priority, flex or batch)', 'aiwend'),
            CostCalculator::TIER_NOT_PRICED => __('it was processed at a tier other than standard (priority, flex or batch), which the list does not price', 'aiwend'),
            'no_split' => __('the provider gave no input and output counts', 'aiwend'),
        ];
    }

    /** @return array<string, string> */
    private static function kinds(): array
    {
        return [
            'simulated' => __('simulated (nothing billed)', 'aiwend'),
            'estimated' => __('usage estimated by Aiwend, not reported', 'aiwend'),
            'administrator_entered' => __('usage entered by an administrator', 'aiwend'),
            'legacy' => __('recorded before usage sources were tracked', 'aiwend'),
            'no_split' => __('the provider gave no input and output counts', 'aiwend'),
            'uncertain' => __('outcome unknown', 'aiwend'),
            'in_progress' => __('still in progress', 'aiwend'),
            'nothing_billed' => __('failed or refused before processing (nothing billed)', 'aiwend'),
            'released' => __('released before sending', 'aiwend'),
        ];
    }

    /** The estimated cost of one period: a total per currency (never added together), or why there is none. Escaped HTML. */
    private static function costCell(array $p): string
    {
        // Provider-reported requests whose cost could not be worked out: unpriced ones and ones without input and output counts.
        $unpriced = array_sum($p['unpriced']) + (int) ($p['not_priced']['no_split'] ?? 0);
        if ($p['cost'] === []) {
            return $unpriced > 0 ? esc_html__('Not available', 'aiwend') : '<span class="aw-muted">—</span>';
        }
        $parts = [];
        ksort($p['cost']);
        foreach ($p['cost'] as $currency => $amount) {
            $parts[] = esc_html(self::money($amount, (string) $currency));
        }
        $html = implode('<br>', $parts);
        if ($unpriced > 0) {
            $html .= '<br><span class="aw-muted">' . esc_html(sprintf(/* translators: 1: requests priced, 2: provider-reported requests that could have been priced */ __('Partial: %1$d of %2$d provider-reported requests priced', 'aiwend'), $p['priced'], $p['priced'] + $unpriced)) . '</span>';
        }
        return $html;
    }

    /** What the BYOK billing arrangement means, and what an Aiwend limit is not. */
    private function billingExplanation(): string
    {
        return '<div class="aw-callout" role="note" data-aiwend-billing><p><strong>' . esc_html__('Who is paid.', 'aiwend') . '</strong> '
            . esc_html__('The administrator pays the AI provider directly through their own API account. Aiwend does not collect those provider usage charges. A consumer ChatGPT subscription does not automatically include OpenAI API usage.', 'aiwend') . '</p><p>'
            . '<strong>' . esc_html__('A usage limit is not a spending cap.', 'aiwend') . '</strong> '
            . esc_html__('Aiwend limits count usage units before a request is sent. They do not stop spending in money. Set spending limits and alerts in your provider’s own account.', 'aiwend') . '</p></div>';
    }

    /** Estimated cost for the last 30 days, with how much of the usage it covers, and by provider and model. */
    public function costSection(): void
    {
        if (!current_user_can(Capabilities::VIEW_USAGE)) {
            return;
        }
        $site = get_current_blog_id();
        $now = $this->plugin->clock->now();
        $since = $now - 30 * 86400;
        $book = $this->book();
        $report = new CostReport($this->plugin->db, $book);
        [$total] = $report->summarize($site, [['start' => $since, 'end' => $now + 1]]);
        $noSplit = (int) ($total['not_priced']['no_split'] ?? 0);
        unset($total['not_priced']['no_split']);
        $unpricedCount = array_sum($total['unpriced']) + $noSplit;
        if ($noSplit > 0) {
            $total['unpriced']['no_split'] = $noSplit;
        }
        $this->out('<section class="aw-card" data-aiwend-cost><h2 class="aw-h3">' . esc_html__('Estimated cost, last 30 days', 'aiwend') . '</h2>');
        $this->out($this->billingExplanation());
        $this->out('<p class="aw-muted">' . esc_html__('An estimate from the token counts your provider reported and the list prices below. It is not your provider’s invoice: your provider’s own billing, discounts, taxes and price changes decide what you pay. Only requests the provider reported in full are priced; amounts in different currencies are never added together or converted. If your provider account is on a free tier or has credits, less or nothing is billed, and Aiwend cannot see that.', 'aiwend') . '</p>');
        if ($book->isStale($now)) {
            $this->out('<div class="notice notice-warning inline aw-notice" role="status" data-aiwend-price-stale-cost><p>' . esc_html__('The price list behind these estimates is more than four months old, so they may be out of date.', 'aiwend') . '</p></div>');
        }
        if ($total['cost'] === []) {
            $this->out('<p data-aiwend-cost-total>' . esc_html__('No estimated cost yet: no request in the last 30 days could be priced.', 'aiwend') . '</p>');
        } else {
            ksort($total['cost']);
            $lines = [];
            foreach ($total['cost'] as $currency => $amount) {
                $lines[] = '<strong>' . esc_html(self::money($amount, (string) $currency)) . '</strong>';
            }
            $this->out('<p data-aiwend-cost-total>' . implode(' · ', $lines) . ' ' . esc_html(sprintf(/* translators: %d: number of requests */ _n('estimated from %d priced request', 'estimated from %d priced requests', (int) $total['priced'], 'aiwend'), (int) $total['priced'])) . '</p>');
        }
        if ($unpricedCount > 0) {
            $this->out('<div class="notice notice-warning inline aw-notice" role="status" data-aiwend-cost-partial><p><strong>' . esc_html__('Partial estimate.', 'aiwend') . '</strong> ' . esc_html(sprintf(/* translators: 1: requests priced, 2: provider-reported requests */ __('Only %1$d of %2$d provider-reported requests could be priced. The amount above leaves out the others, whose cost is unknown.', 'aiwend'), (int) $total['priced'], (int) $total['priced'] + $unpricedCount)) . '</p></div>');
        }
        if ($total['unpriced'] !== []) {
            $reasons = self::reasons();
            $items = '';
            foreach ($total['unpriced'] as $reason => $n) {
                $items .= '<li>' . esc_html(sprintf(/* translators: 1: number of requests, 2: reason */ _n('%1$d request: %2$s', '%1$d requests: %2$s', $n, 'aiwend'), $n, $reasons[$reason] ?? $reason)) . '</li>';
            }
            $this->out('<p><strong>' . esc_html__('Not priced (cost unknown, not zero):', 'aiwend') . '</strong></p><ul class="aw-bullets" data-aiwend-cost-unpriced>' . $items . '</ul>');
        }
        if ($total['not_priced'] !== []) {
            $kinds = self::kinds();
            $items = '';
            foreach ($total['not_priced'] as $kind => $n) {
                $items .= '<li>' . esc_html(sprintf(/* translators: 1: number of requests, 2: kind of request */ _n('%1$d request: %2$s', '%1$d requests: %2$s', $n, 'aiwend'), $n, $kinds[$kind] ?? $kind)) . '</li>';
            }
            $this->out('<p class="aw-muted">' . esc_html__('Other requests in the same period are never priced as provider usage:', 'aiwend') . '</p><ul class="aw-bullets" data-aiwend-cost-other>' . $items . '</ul>');
        }
        $models = $report->byModel($site, $since, $now + 1);
        if ($models !== []) {
            $this->out('<h3 class="aw-h3">' . esc_html__('By provider and model', 'aiwend') . '</h3><div class="aw-table-wrap"><table class="aw-table aw-table--stack" data-aiwend-cost-models><thead><tr>'
                . '<th scope="col">' . esc_html__('Provider', 'aiwend') . '</th><th scope="col">' . esc_html__('Model', 'aiwend') . '</th><th scope="col">' . esc_html__('Priced', 'aiwend') . '</th><th scope="col">' . esc_html__('Not priced', 'aiwend') . '</th>'
                . '<th scope="col">' . esc_html__('Estimated cost', 'aiwend') . '</th><th scope="col">' . esc_html__('Rate used', 'aiwend') . '</th></tr></thead><tbody>');
            $providers = ['openai' => 'OpenAI', 'anthropic' => 'Anthropic', 'gemini' => 'Google Gemini', 'deepseek' => 'DeepSeek', 'xai' => 'xAI (Grok)', 'openrouter' => 'OpenRouter', 'groq' => 'GroqCloud'];
            foreach ($models as $m) {
                $rate = $m['origin'] === null ? '<span class="aw-muted">—</span>' : esc_html($m['origin'] === 'override'
                    ? sprintf(/* translators: %s: date */ __('Custom rate, entered %s', 'aiwend'), (string) $m['verified'])
                    : sprintf(/* translators: %s: date */ __('Bundled list, verified %s', 'aiwend'), (string) $m['verified']));
                $this->out('<tr data-model="' . esc_attr($m['provider'] . '/' . $m['model']) . '"><th scope="row">' . esc_html($providers[$m['provider']] ?? ($m['provider'] === '' ? __('Not recorded', 'aiwend') : $m['provider'])) . '</th>'
                    . '<td>' . ($m['model'] === '' ? esc_html__('Not recorded', 'aiwend') : '<code>' . esc_html($m['model']) . '</code>') . '</td>'
                    . '<td>' . esc_html(self::n($m['priced'])) . '</td><td>' . esc_html(self::n($m['unpriced'])) . '</td>'
                    . '<td>' . ($m['amount'] === null ? esc_html__('Unknown', 'aiwend') : esc_html(self::money($m['amount'], (string) $m['currency'])) . ($m['unpriced'] > 0 ? ' <span class="aw-muted">' . esc_html__('(partial)', 'aiwend') . '</span>' : '')) . '</td><td>' . $rate . '</td></tr>');
            }
            $this->out('</tbody></table></div>');
        }
        $this->out('</section>');
    }

    /** The price list in force (version, verification date, sources), the administrator’s own rates and the form to add one. */
    public function pricingSection(): void
    {
        if (!current_user_can(Capabilities::VIEW_USAGE)) {
            return;
        }
        $book = $this->book();
        $now = $this->plugin->clock->now();
        $providers = ['openai' => 'OpenAI', 'anthropic' => 'Anthropic', 'gemini' => 'Google Gemini', 'deepseek' => 'DeepSeek', 'xai' => 'xAI (Grok)', 'openrouter' => 'OpenRouter', 'groq' => 'GroqCloud'];
        $this->out('<section class="aw-card" data-aiwend-pricing><h2 class="aw-h3">' . esc_html__('Prices used for the estimate', 'aiwend') . '</h2>');
        $this->out('<p>' . esc_html(sprintf(/* translators: 1: list version, 2: date */ __('Bundled price list %1$s, verified on %2$s from each provider’s own pricing page. It is version-controlled data inside the plugin: Aiwend never fetches prices, and a newer plugin release carries a newer list.', 'aiwend'), $book->version(), $book->verifiedOn())) . '</p>');
        if ($book->isStale($now)) {
            $this->out('<div class="notice notice-warning inline aw-notice" role="status" data-aiwend-price-stale><p>' . esc_html__('This price list is more than four months old. Providers change prices, so estimates from it may be out of date. Check your provider’s pricing page, and enter your own rate below where it differs.', 'aiwend') . '</p></div>');
        }
        $overrides = (new PriceOverrides($this->plugin->options, $this->plugin->clock))->all();
        $manage = current_user_can(Capabilities::MANAGE);
        $this->out('<h3 class="aw-h3">' . esc_html__('Your custom rates', 'aiwend') . '</h3>');
        if ($overrides === []) {
            $this->out('<p class="aw-muted">' . esc_html__('None. A custom rate replaces the bundled price for that model, and lets you price a model the list does not have.', 'aiwend') . '</p>');
        } else {
            $this->out('<div class="aw-table-wrap"><table class="aw-table aw-table--stack" data-aiwend-overrides><thead><tr><th scope="col">' . esc_html__('Provider', 'aiwend') . '</th><th scope="col">' . esc_html__('Model', 'aiwend') . '</th>'
                . '<th scope="col">' . esc_html__('Input', 'aiwend') . '</th><th scope="col">' . esc_html__('Cached input', 'aiwend') . '</th><th scope="col">' . esc_html__('Output', 'aiwend') . '</th><th scope="col">' . esc_html__('Entered', 'aiwend') . '</th>' . ($manage ? '<th scope="col"><span class="screen-reader-text">' . esc_html__('Remove', 'aiwend') . '</span></th>' : '') . '</tr></thead><tbody>');
            foreach ($overrides as $o) {
                $this->out('<tr data-override="' . esc_attr($o['provider'] . '/' . $o['model']) . '"><th scope="row">' . esc_html($providers[$o['provider']] ?? $o['provider']) . '</th><td><code>' . esc_html($o['model']) . '</code></td>'
                    . '<td>' . esc_html($o['currency'] . ' ' . $o['input']) . '</td><td>' . ($o['cached_input'] === null ? '<span class="aw-muted">—</span>' : esc_html($o['currency'] . ' ' . $o['cached_input'])) . '</td><td>' . esc_html($o['currency'] . ' ' . $o['output']) . '</td>'
                    . '<td>' . esc_html(gmdate('Y-m-d', $o['entered_at'])) . '</td>');
                if ($manage) {
                    ob_start();
                    AdminView::form('remove_price', 'aiwend-usage', ['provider' => $o['provider'], 'model' => $o['model']]);
                    echo '<button type="submit" class="button button-link-delete">' . esc_html__('Remove', 'aiwend') . '</button></form>';
                    $this->out('<td>' . (string) ob_get_clean() . '</td>');
                }
                $this->out('</tr>');
            }
            $this->out('</tbody></table></div><p class="aw-muted">' . esc_html__('Rates are per one million tokens, in the currency you entered.', 'aiwend') . '</p>');
        }
        if ($manage) {
            ob_start();
            AdminView::form('save_price', 'aiwend-usage');
            $this->out((string) ob_get_clean());
            $this->out('<fieldset class="aw-fieldset"><legend>' . esc_html__('Add or replace a custom rate', 'aiwend') . '</legend>'
                . '<p class="aw-field"><label for="aiw-rate-provider">' . esc_html__('Provider', 'aiwend') . '</label><select id="aiw-rate-provider" name="provider" class="aw-input">'
                . '<option value="openai">OpenAI</option><option value="anthropic">Anthropic</option><option value="gemini">Google Gemini</option></select></p>'
                . '<p class="aw-field"><label for="aiw-rate-model">' . esc_html__('Model name', 'aiwend') . '</label><input type="text" id="aiw-rate-model" name="model" class="aw-input" maxlength="191" autocomplete="off" required></p>'
                . '<p class="aw-field"><label for="aiw-rate-currency">' . esc_html__('Currency (three letters)', 'aiwend') . '</label><input type="text" id="aiw-rate-currency" name="currency" class="aw-input" maxlength="3" value="USD" autocomplete="off" required></p>'
                . '<p class="aw-field"><label for="aiw-rate-in">' . esc_html__('Input, per million tokens', 'aiwend') . '</label><input type="text" inputmode="decimal" id="aiw-rate-in" name="input" class="aw-input" autocomplete="off" required></p>'
                . '<p class="aw-field"><label for="aiw-rate-cached">' . esc_html__('Cached input, per million tokens (optional)', 'aiwend') . '</label><input type="text" inputmode="decimal" id="aiw-rate-cached" name="cached_input" class="aw-input" autocomplete="off"></p>'
                . '<p class="aw-field"><label for="aiw-rate-out">' . esc_html__('Output, per million tokens', 'aiwend') . '</label><input type="text" inputmode="decimal" id="aiw-rate-out" name="output" class="aw-input" autocomplete="off" required></p>'
                . '<label class="aw-choice"><input type="checkbox" name="confirm" value="1"><span>' . esc_html__('This is the rate my own provider account charges. Estimates that use it are labelled as custom.', 'aiwend') . '</span></label>'
                . '<p><button type="submit" class="button button-primary">' . esc_html__('Save custom rate', 'aiwend') . '</button></p></fieldset></form>');
        }
        $this->out('<details class="aw-details"><summary>' . esc_html__('Bundled list prices', 'aiwend') . '</summary><div class="aw-table-wrap"><table class="aw-table aw-table--stack" data-aiwend-bundled><thead><tr>'
            . '<th scope="col">' . esc_html__('Provider', 'aiwend') . '</th><th scope="col">' . esc_html__('Model', 'aiwend') . '</th><th scope="col">' . esc_html__('Prompt size', 'aiwend') . '</th><th scope="col">' . esc_html__('Input', 'aiwend') . '</th><th scope="col">' . esc_html__('Cached input', 'aiwend') . '</th><th scope="col">' . esc_html__('Output', 'aiwend') . '</th><th scope="col">' . esc_html__('Verified', 'aiwend') . '</th></tr></thead><tbody>');
        foreach ($book->entries() as $e) {
            foreach ((array) $e['tiers'] as $t) {
                $size = isset($t['up_to']) ? sprintf(/* translators: %s: number of tokens */ __('up to %s tokens', 'aiwend'), self::n((int) $t['up_to'])) : (count((array) $e['tiers']) > 1 ? __('above that', 'aiwend') : __('any', 'aiwend'));
                $this->out('<tr><th scope="row">' . esc_html($providers[$e['provider']] ?? (string) $e['provider']) . '</th><td><code>' . esc_html((string) $e['model']) . '</code></td><td>' . esc_html($size) . '</td>'
                    . '<td>' . esc_html($e['currency'] . ' ' . $t['input']) . '</td><td>' . ($t['cached_input'] === null ? '<span class="aw-muted">—</span>' : esc_html($e['currency'] . ' ' . $t['cached_input'])) . '</td><td>' . esc_html($e['currency'] . ' ' . $t['output']) . '</td><td>' . esc_html((string) $e['verified']) . '</td></tr>');
            }
        }
        $this->out('</tbody></table></div><p class="aw-muted">' . esc_html(sprintf(/* translators: %s: notice */ __('Per million tokens. %s', 'aiwend'), $book->notice())) . '</p></details></section>');
    }

    // ---------------------------------------------------------------- glossary

    /** What the numbers on this screen mean and do not mean (kept short; pricing and who is paid come with the cost estimates). */
    public function glossary(): void
    {
        $this->out('<details class="aw-card aw-details" id="aw-glossary"><summary><span class="aw-h3">' . esc_html__('How to read these numbers', 'aiwend') . '</span></summary><dl class="aw-glossary">'
            . '<dt>' . esc_html__('Usage units', 'aiwend') . '</dt><dd>' . esc_html__('Aiwend’s own count, roughly one token of text. Limits are counted in usage units. They are not money, and they are not an exact count of what any provider measured.', 'aiwend') . '</dd>'
            . '<dt>' . esc_html__('Attempts', 'aiwend') . '</dt><dd>' . esc_html__('Every request for which Aiwend set aside usage, whether or not it reached the provider or finished: answered, failed before sending, refused by the provider, released, still in progress, unknown, simulated and connection tests. Requests turned away by a limit before anything was set aside are not counted, and neither is indexing of your content. Attempts are not provider calls and not successful answers.', 'aiwend') . '</dd>'
            . '<dt>' . esc_html__('Estimated cost', 'aiwend') . '</dt><dd>' . esc_html__('Provider tokens multiplied by a list price (or a rate you entered). It covers only requests the provider reported in full, is shown per currency without conversion, and is an estimate: not your provider’s invoice, and not a spending limit.', 'aiwend') . '</dd>'
            . '<dt>' . esc_html__('Provider tokens', 'aiwend') . '</dt><dd>' . esc_html__('The input and output token counts reported by the provider, shown only for requests where the provider gave both. Older records, some failed requests, estimates and simulated requests have none, and show “Not available” instead of 0.', 'aiwend') . '</dd>'
            . '<dt>' . esc_html__('Estimates', 'aiwend') . '</dt><dd>' . esc_html__('When a provider never reported its usage, the amount held can be charged as an estimate. Estimates can differ from what your provider bills, and a usage-unit limit is not a guaranteed spending limit: your provider’s own billing and limits are separate and are the final word.', 'aiwend') . '</dd>'
            . '<dt>' . esc_html__('Uncertain requests', 'aiwend') . '</dt><dd>' . esc_html__('A request whose outcome Aiwend could not confirm. Its amount stays held against the limit until you resolve it under Detailed accounting, and it is never added to “Usage units” until then.', 'aiwend') . '</dd>'
            . '<dt>' . esc_html__('Simulated usage', 'aiwend') . '</dt><dd>' . esc_html__('From the built-in demo. Nothing was sent to a provider and nothing is billed; its units are synthetic.', 'aiwend') . '</dd>'
            . '</dl></details>');
    }
}