<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Mcp\Action;

/**
 * The shop's language codes, as {@see ArgumentBinder} needs them to bind a `{code}`/`{iso}` field.
 *
 * An interface for one production implementation exists for a single reason: {@see ArgumentBinder}
 * is deliberately pure — no DB, no `Shop::`, no superglobals — so that it runs in a unit test and in
 * a build-time catalog check without a booted shop. A templated field keyed by the installed
 * languages is the one thing it cannot answer from the catalog alone, so the answer is injected
 * rather than fetched, and the binder stays testable.
 *
 * `null` is not "no languages"; it is "could not tell". The binder treats it as a hard stop
 * ({@see ArgumentBinder::templated()}), because the alternative — the behaviour this interface was
 * added to remove — is accepting every key a caller invents and writing it into `$_POST`.
 */
interface LanguageCodes
{
    /**
     * @return list<string>|null the codes a localised field may be keyed by (`ger`, `eng`, …), or
     *                           null when they could not be determined
     */
    public function codes(): ?array;
}
