@byte-42/fantastico-sdk 0.0.0-stage → 0.21.0

package/dist/client.d.ts

@@ -0,0 +1,410 @@
+import type { FantasticoOptions, ChatCompletionCreateParams, ChatCompletionResult, ToolDefinition, RawCompletionCreateParams, RawChatCompletion, AccountCreateParams, AccountUpdateParams, AccountInfo, AccountKeyInfo, IssuedAccountKey, RuntimeKeyInfo, RuntimeKeyHandle, ContoBalance, UsageRecordParams, UsageRecordResult, ResumeDecision, OpenRouterModel } from "./types.js";
+import { type Surface } from "./surface.js";
+import type { ChatActivityOptions } from "./activity.js";
+import { type RegisteredTool, type LocalToolDefinition } from "./local-tools.js";
+import { type EvaluateDecisionParams, type DecisionResult, type DecisionToolConfig } from "./decisions.js";
+import { type SpeechCreateParams, type SpeechResult, type SpeechModel } from "./speech.js";
+export declare class Fantastico {
+    private readonly opts;
+    private readonly auth;
+    private readonly fetchImpl;
+    private readonly mcpExecutor;
+    private readonly localTools;
+    /** Costo non ancora regolato per tenant: si salda alla chiamata successiva (delta). */
+    private readonly unsettled;
+    /** Nome visibile dell'assistente, se impostato — un solo posto da cui prompt e UI
+     *  lo leggono, invece di ripetere la stringa (vedi FantasticoOptions.name). */
+    readonly name?: string;
+    /**
+     * Su quale delle due superfici parla questo client, dedotto dal prefisso della credenziale
+     * (`surface.ts`). Leggibile perché chi integra con l'una o con l'altra ha a disposizione cose
+     * diverse — `accounts` di qua, `balance` di là — e un `if` sulla stringa della chiave, scritto
+     * a valle, sarebbe la seconda copia della stessa deduzione.
+     */
+    readonly surface: Surface;
+    readonly chat: {
+        completions: {
+            /** `options.onEvent` riceve gli eventi del turno mentre accadono (`activity.ts`). */
+            create: (params: ChatCompletionCreateParams, options?: ChatActivityOptions) => Promise<ChatCompletionResult>;
+            /**
+             * Riprende un'orchestrazione fermata con `status: "pending"` (conferma umana o esito
+             * di un'azione client). `state` è quello ricevuto in `PendingCompletion.state`, passato
+             * identico — non va ispezionato né modificato.
+             */
+            resume: (state: unknown, decisions: ResumeDecision[], context?: unknown, options?: ChatActivityOptions) => Promise<ChatCompletionResult>;
+            /** Nessuna orchestrazione: una chiamata, tool del chiamante, il loop resta a lui. */
+            createRaw: (params: RawCompletionCreateParams) => Promise<RawChatCompletion>;
+        };
+    };
+    /**
+     * Tool del marketplace FANTASTICO, per chi gestisce il proprio loop via createRaw().
+     *
+     * **`user` nomina il conto**, come in `create()`: i tool token arrivano col conio e sono la
+     * credenziale con cui quel tool verrà pagato, quindi chiedere l'elenco per un tenant significa
+     * coniare — e far pagare — sul conto giusto. Omesso, è il conto del proprietario.
+     */
+    readonly tools: {
+        list: (user?: string) => Promise<ToolDefinition[]>;
+        execute: (name: string, args: Record<string, unknown>, user?: string) => Promise<string>;
+        /**
+         * **Cosa il progetto ha abilitato**: id e nome, senza coniare. Dalla 0.14.0.
+         *
+         * È la domanda di chi **configura**, non di chi esegue: un pannello che deve offrire le
+         * skill disponibili, un controllo di installazione. Per questo non porta endpoint, token né
+         * digest — quelli arrivano col conio, uno per tool, ed è lì che restano.
+         *
+         * La differenza con `list()` è **quanto costa chiederlo**: `list()` conia (e quindi impegna
+         * un blocco sul conto) perché deve restituire i tool *pronti all'uso*, verificati contro il
+         * documento che serviranno. Questa no: non impegna niente e non apre nessuna chiave, quindi
+         * è quella giusta ogni volta che la risposta serve a mostrare un elenco e non a chiamarlo.
+         */
+        enabled: () => Promise<Array<{
+            id: string;
+            name: string;
+        }>>;
+    };
+    /** Catalogo modelli disponibili sul provider (OpenRouter), per chi vuole scegliere
+     *  `model` senza conoscerlo a priori — es. un selettore in UI. Risposta cachata dal
+     *  Cloud per qualche minuto: chiamarlo spesso non genera traffico verso il provider. */
+    readonly models: {
+        list: () => Promise<OpenRouterModel[]>;
+    };
+    /**
+     * Anagrafica dei conti del progetto — i tenant finali a cui è attribuito il consumo.
+     *
+     * Progetto e ambiente **non si passano**: sono quelli della project key con cui è stato
+     * costruito il client. Non esiste un parametro con cui operare sul progetto di qualcun
+     * altro, e quindi non c'è la classe di errore corrispondente.
+     */
+    readonly accounts: {
+        create: (params: AccountCreateParams) => Promise<AccountInfo>;
+        list: () => Promise<AccountInfo[]>;
+        get: (userKey: string) => Promise<AccountInfo>;
+        update: (userKey: string, params: AccountUpdateParams) => Promise<AccountInfo>;
+        /**
+         * Chiude la prova di un conto aperto con `type: "trial"`: da qui è un conto a pagamento.
+         * Dalla 0.13.0.
+         *
+         * **La chiama il verticale che ha incassato l'abbonamento**, perché è l'unico a sapere che è
+         * stato pagato. Senza, il conto resta una prova e il Cloud lo sospende alla scadenza anche se
+         * il cliente nel frattempo si è abbonato.
+         *
+         * Cosa cambia per quel conto: la parte non spesa della concessione di prova torna alla riserva
+         * del progetto (era un prestito per provare), cominciano la quota periodica del piano e la fee
+         * per conto, e se era sospeso **dalla propria scadenza** torna attivo — uno sospeso da un
+         * operatore resta sospeso, di proposito.
+         *
+         * Una volta sola e senza ritorno: su un conto che non è una prova risponde 422.
+         */
+        upgrade: (userKey: string) => Promise<AccountInfo>;
+        /**
+         * La **chiave di conto**: si emette quando l'operatività di quel conto va delegata a un
+         * perimetro che non controlli — il plugin di un cliente, un dispositivo, un'installazione.
+         * Chi la riceve può coniare runtime key **solo** entro il credito di
+         * quel conto, e non può nominarne un altro.
+         *
+         * È opzionale: un conto senza chiave resta operato da questo stesso client, con la
+         * project key, esattamente come oggi. Emetterla è un atto in più e volontario.
+         *
+         * **Una sola chiave viva per conto**: se ne esiste già una, `issue` risponde 409 —
+         * per sostituirla si usa `rotate`, che invalida la precedente nello stesso istante.
+         */
+        keys: {
+            /** Le chiavi attive del progetto+ambiente: quali conti hanno una credenziale in giro. */
+            list: () => Promise<AccountKeyInfo[]>;
+            /** Emette la chiave. **L'unico momento in cui il valore in chiaro esiste.** */
+            issue: (userKey: string, label?: string) => Promise<IssuedAccountKey>;
+            /** Ne emette una nuova e invalida la precedente. Da usare dopo un sospetto, o su un clone. */
+            rotate: (userKey: string) => Promise<IssuedAccountKey>;
+            /** Revoca senza sostituire: il conto resta, e torna operabile da qui. */
+            revoke: (userKey: string) => Promise<{
+                revoked: number;
+            }>;
+        };
+    };
+    /**
+     * Le runtime key OpenRouter che questo progetto ha ancora aperte.
+     *
+     * **Esiste perché il segreto non si conserva.** La credenziale vive solo nella memoria di chi
+     * l'ha coniata: un processo riavviato, o una seconda istanza dello stesso client, non sa
+     * più nominare le chiavi che ha in giro — mentre ognuna di esse occupa uno slot del piano
+     * (`maxOpenKeys`) finché non liquida. Questa lettura le rende nominabili, e quindi
+     * restituibili, invece di lasciarle scadere.
+     *
+     * Senza `userKey` è il conto del proprietario, lo stesso che il conio userebbe.
+     */
+    readonly runtimeKeys: {
+        /**
+         * La chiave con cui questo client sta lavorando, **coniandone una se non ne ha**.
+         *
+         * È la sostituzione onesta del vecchio "conia tu e passami la key": chi vuole vedere handle,
+         * tetto, impegno e scadenza all'avvio — o vuole poter **restituire** la chiave all'uscita,
+         * invece di lasciare uno slot di `maxOpenKeys` occupato per il TTL residuo — la chiama qui e
+         * continua a usare il client normalmente. Il segreto resta dentro, dove può scadere e
+         * rinnovarsi senza che nessuno se ne accorga.
+         *
+         * Chiamarla non è obbligatorio: la prima `create()` conia da sé.
+         *
+         * **`user` nomina il conto che paga**, ed è lo stesso campo di `create()`: una chiave è di un
+         * conto, quindi chiedere "la chiave di questo client" senza dire quale conto significa quella
+         * del proprietario del progetto. Chi chiama per conto di un tenant — per leggere i tool che il
+         * conio gli concede, per esempio — deve nominarlo, o aprirà un hold sul conto sbagliato.
+         */
+        ensure: (user?: string) => Promise<RuntimeKeyHandle>;
+        /**
+         * La chiave in mano **adesso**, senza coniarne una: `null` se non se n'è ancora coniata
+         * nessuna, o se l'ultima è stata scartata dopo un errore del provider.
+         *
+         * È la metà in sola lettura di `ensure`, e serve quando restituire una chiave è l'ultima cosa
+         * che si fa: fra l'avvio e l'uscita l'SDK può averne coniata un'altra — una chiave si esaurisce
+         * o scade a metà lavoro — e restituire l'handle di partenza lascerebbe viva quella vera,
+         * occupando uno slot di `maxOpenKeys` per il TTL residuo. Con `ensure` non si potrebbe: a
+         * processo in chiusura conierebbe la chiave che si sta cercando di rendere.
+         *
+         * `user` come in `ensure`: la chiave in mano **di quel conto**.
+         */
+        current: (user?: string) => RuntimeKeyHandle | null;
+        list: (userKey?: string) => Promise<RuntimeKeyInfo[]>;
+        /**
+         * Restituisce una chiave prima della scadenza: smette di funzionare sul provider subito, e
+         * il suo slot torna libero appena lo scheduler la liquida — un paio di minuti invece del
+         * TTL residuo. `revoked: false` se era già stata revocata.
+         *
+         * **L'handle la nomina, il conto la autorizza**: come per il conio, senza `userKey` è il
+         * conto del proprietario. Una chiave di un altro conto viene rifiutata con le stesse parole
+         * di una che non esiste.
+         */
+        revoke: (recordId: string, userKey?: string) => Promise<{
+            revoked: boolean;
+        }>;
+    };
+    /**
+     * Modelli decisionali "System One" (Jev di TypeSafe e affini) — non chat, non `/chat/completions`:
+     * uno stato in ingresso, un verdetto tipizzato con probabilità in uscita, sullo stesso conto e
+     * la stessa runtime key di ogni altra chiamata (`decisions.ts`).
+     *
+     * **`evaluate` è la chiamata diretta**, con la stessa contabilità di `createRaw()` — prenota il
+     * budget del tenant, conia/ri-conia se il provider rifiuta, regola il costo reale al giro
+     * successivo. **`tool` è l'integrazione nel loop di tool-use**: costruisce un
+     * `LocalToolDefinition` che un LLM conversazionale (avviato con `chat.completions.create()`)
+     * può chiamare a metà conversazione per ottenere una decisione veloce senza uscire dal loop —
+     * es. instradare un ticket, o segnalare un contenuto, mentre il modello principale continua a
+     * scrivere la risposta. Registralo con `ai.addTool(ai.decisions.tool({...}))`.
+     */
+    readonly decisions: {
+        evaluate: (params: EvaluateDecisionParams) => Promise<DecisionResult>;
+        tool: <TContext = unknown>(config: DecisionToolConfig<TContext>) => LocalToolDefinition<TContext>;
+    };
+    /**
+     * Voce sintetica (text-to-speech), drop-in di `audio.speech.create()` dell'SDK OpenAI — sullo
+     * stesso conto e la stessa runtime key di ogni altra chiamata (`speech.ts`). Dalla 0.20.0.
+     *
+     * **`create`** ha la stessa contabilità di `createRaw()`: prenota il budget del tenant, conia o
+     * ri-conia se il provider rifiuta la chiave, e **non dichiara nessun costo** — la spesa entra
+     * nell'`usage` della runtime key presso il provider come quella di una chat, e il ledger la
+     * liquida sull'hold del conio. Verificato sul campo il 2026-10-17.
+     *
+     * **`models`** è il catalogo dei modelli TTS con le voci che ciascuno ammette
+     * (`supported_voices`) e il listino, per un selettore che faccia scegliere la voce anche in
+     * base al costo come già fa per i modelli di chat. È un catalogo a sé: `ai.models.list()`
+     * **non li contiene** — OpenRouter li espone solo filtrando per modalità in uscita.
+     */
+    readonly audio: {
+        speech: {
+            create: (params: SpeechCreateParams) => Promise<SpeechResult>;
+            models: () => Promise<SpeechModel[]>;
+        };
+    };
+    /**
+     * Il saldo del **proprio** conto — solo con una chiave di conto (`/api/edge/balance`).
+     *
+     * Con una project key non esiste, e non è una lacuna da colmare: lì i conti sono molti e si
+     * nominano, quindi la stessa domanda è `ai.accounts.get(userKey)`. Le due superfici non offrono
+     * le stesse cose perché non hanno la stessa identità, e fingere il contrario significherebbe
+     * rispondere con il saldo di qualcun altro.
+     */
+    readonly balance: () => Promise<ContoBalance>;
+    /**
+     * @deprecated Non addebita niente e non manda nessuna richiesta: risolve con `amount: 0`.
+     * Tenuto perché un client scritto contro una versione precedente continui a compilare **e a
+     * girare**.
+     *
+     * Dichiarava il consumo di un servizio marketplace a esecuzione locale (`POST /api/usage`), ed
+     * era l'unico addebito del marketplace deciso da **chi chiama** invece che dal tool. Non c'è
+     * più perché quel modello non c'è più: ogni tool si registra a un endpoint, ci viene chiamato
+     * con un tool token e dichiara da sé quanto è costata la chiamata, contro un tetto che il conio
+     * gli ha dato. Prezzare a unità non è morto — è aritmetica che il
+     * tool fa; è morto il *client* che dichiara le unità.
+     *
+     * **Un servizio che si faceva pagare così, oggi, non si fa pagare.** Questo ramo tiene in piedi
+     * il codice, non il ricavo: se questa chiamata era l'unica contabilità di un servizio, quel
+     * servizio va registrato nel marketplace e deve fatturarsi contro il proprio tool token.
+     */
+    readonly usage: {
+        record: (params: UsageRecordParams) => Promise<UsageRecordResult>;
+    };
+    /**
+     * La sessione di attività in corso, o `null` prima del primo conio.
+     *
+     * **Non è una credenziale**: non autorizza niente, si può stampare, loggare e mettere in un
+     * ticket — ed è esattamente ciò per cui esiste, visto che la query di supporto a valle è
+     * `WHERE activity_session_id = '…'`. Prima non usciva da `AuthClient`, quindi chi integrava non
+     * aveva modo di scrivere nei propri log l'unico id con cui quella spesa si ritrova.
+     *
+     * Può **cambiare da sola**: il ledger ne sostituisce in silenzio una che non riconosce più
+     * (potata, o mai stata di questo conto), quindi va riletta dopo un conio e non memorizzata una
+     * volta per tutte.
+     */
+    get activitySessionId(): string | null;
+    constructor(options: FantasticoOptions);
+    /**
+     * Il tenant a cui attribuire questa chiamata — **e il rifiuto di nominarne uno sull'edge**.
+     *
+     * `user` è il campo OpenAI-compat con cui una project key dice a quale conto del progetto va il
+     * consumo. Con una chiave di conto quel conto è già deciso: è quello della credenziale, e
+     * nessuna rotta edge ne legge uno dal corpo. Ignorarlo in silenzio sarebbe peggio che
+     * rifiutarlo — chi lo passa crede di star separando due tenant, e vedrebbe invece la spesa di
+     * tutti e due finire sullo stesso conto, senza niente che lo dica.
+     */
+    private tenantOf;
+    /**
+     * L'anagrafica dei conti, e il posto unico in cui la sua superficie si verifica.
+     *
+     * `/api/conti/*` autentica con la project key e descrive **tutti** i conti di un progetto: non
+     * esiste su edge, e non è una rotta che manca — una chiave di conto ne vale uno solo, quindi
+     * "elenca i conti" lì è una domanda che non ha un soggetto.
+     */
+    private conti;
+    /** Registra un tool locale o un'azione-client dopo la costruzione (in alternativa/oltre a
+     *  passarli nel costruttore via `tools`). */
+    addTool(tool: RegisteredTool): void;
+    /**
+     * Conia la runtime key e ci esegue `run`. Se il provider risponde `401`/`402` — o, meglio, se
+     * classifica lui stesso l'errore come `authentication`/`payment_required` — NON è un verdetto
+     * affidabile che "sono finiti i fondi del cliente": può essere il tetto di QUESTA key esaurito
+     * prima della sua scadenza per tempo, oppure un problema del tutto estraneo al cliente
+     * (una key già ritirata, o un problema del provider). L'ambiguità è **documentata dal
+     * provider**: il suo 402 vale "your account **or API key** has insufficient credits", e la doc
+     * dice apertamente di non distinguere i due casi. Quindi il verdetto non si dà, si prova: un solo
+     * retry a chiave nuova; se sparisce da solo, il chiamante non vede nulla. Se persiste, l'unico
+     * messaggio onesto è un errore di comunicazione col provider — MAI "sono finiti i tuoi fondi",
+     * perché a questo punto non lo sappiamo.
+     *
+     * **Su cosa si decide.** Su `ProviderError` (`provider-error.ts`), cioè sullo stato HTTP e su
+     * `metadata.error_type`, mai sul testo del messaggio. La regex che c'era prima leggeva la prosa
+     * del provider perché lo stato non sopravviveva alla pila: quel file racconta i due modi in cui
+     * sbagliava. Conseguenza per chi inietta un `LlmClient` proprio: per partecipare al ri-conio deve
+     * lanciare un `ProviderError` (esportato dall'indice); un `Error` qualunque è un errore e basta.
+     *
+     * L'UNICO caso in cui "fondi insufficienti" è un'affermazione vera è quando è
+     * FANTASTICO STESSO a rifiutarsi di coniare (`FantasticoError` da `getRuntimeKey()`,
+     * es. `INSUFFICIENT_RESERVE`/`ALLOWANCE_EXHAUSTED`): lì il verdetto è nostro, autorevole,
+     * e si propaga così com'è — non va mai reinterpretato.
+     */
+    /**
+     * Il `max_tokens` da mandare quando il chiamante non ne ha scritto uno.
+     *
+     * **Va calcolato dopo il conio e dentro il retry**, non una volta per chiamata: la chiave del
+     * secondo tentativo e un'altra chiave, con un tetto suo, e riusare il numero della prima e
+     * esattamente il caso che il retry esiste per riparare.
+     *
+     * `undefined` quando non c'e niente da calcolare — catalogo muto, o chiave capiente. In
+     * entrambi i casi non si scrive nulla sul filo. Vedi `max-tokens.ts` per il perche del conto.
+     */
+    private defaultMaxTokens;
+    /**
+     * Come un errore del provider arriva al chiamante.
+     *
+     * Se il provider l'ha classificato, si passa il suo stato e un codice `PROVIDER_*` che dice **chi
+     * ha parlato**: `status` in questo SDK porta già, verbatim, lo stato HTTP del Cloud (`auth.ts`,
+     * `api()`), quindi il numero da solo non basta più a distinguere i due mittenti — e il `403` lo
+     * usano entrambi, per cose con rimedi opposti. Vedi `providerFailure()`.
+     *
+     * Quel che resta `INTERNAL_ERROR` 500 è solo ciò che davvero non sappiamo attribuire.
+     */
+    private asFantasticoError;
+    /** La configurazione dei ritentativi transitori, con la scadenza entro cui è lecito dormire. */
+    private retryConfig;
+    /**
+     * Un `LlmClient` che si ri-conia da solo, **per singola chiamata**.
+     *
+     * È qui che sta la differenza con la versione precedente, e non è una rifinitura. Prima il
+     * ri-conio avvolgeva l'intera `orchestrate()`, e l'orchestratore riparte da `[...messages]`: un
+     * 402 al quarto turno non riprendeva il lavoro, lo **rigiocava da capo** — i turni 1-3 rimandati
+     * al modello e ripagati sulla chiave nuova, e i loro tool **rieseguiti**, quelli remoti con un
+     * altro addebito e quelli locali con i loro effetti. Il primo tentativo non veniva rimborsato:
+     * era semplicemente perso. E il momento in cui un tetto di chiave si esaurisce è, per
+     * costruzione, **a metà conversazione**: il ri-conio scattava quindi proprio dove rigiocare
+     * costava di più.
+     *
+     * Spostato qui, l'unica cosa rifatta è la richiesta HTTP che è fallita. Lo stato accumulato resta
+     * dov'è sempre stato, dentro l'orchestratore, che non si accorge di niente.
+     *
+     * **E il `max_tokens` si ricalcola da sé**, che è l'invariante che il vecchio commento
+     * raccomandava a voce: si calcola dentro `run`, cioè dopo il conio, quindi la chiave nuova porta
+     * il proprio tetto invece di ereditare il numero di quella scartata — che è esattamente il caso
+     * che il ri-conio esiste per riparare.
+     */
+    private remintingLlm;
+    private withProviderRetry;
+    private createCompletion;
+    /**
+     * I tool remoti di questo giro: conia se serve, poi chiede a ciascun tool le proprie funzioni.
+     *
+     * **Il conio viene prima, ed e' l'unico ordine possibile** da quando la discovery non ha un
+     * ripiego: le concessioni — endpoint, token, digest — arrivano *con* la
+     * runtime key, quindi senza chiave non c'e' niente da scoprire. Prima l'ordine era comodo e non
+     * necessario, perche' senza token si ricadeva sul catalogo aggregato del Cloud; ora chiedere
+     * prima di coniare significa un elenco vuoto.
+     *
+     * **Qui e non in tre posti.** Lo facevano `create`, `resume` e `ai.tools`, e il terzo non coniava:
+     * `ai.tools.list()` su un client appena costruito rispondeva quindi sempre `[]` — la superficie
+     * che esiste apposta per chi orchestra da se, muta senza dire perche'.
+     */
+    private remoteTools;
+    /**
+     * Riprende un'orchestrazione sospesa da create() (`status: "pending"`). Rifà lo stesso
+     * bootstrap di create() (MCP abilitati, runtime key) perché in un backend a richieste può
+     * arrivare come chiamata HTTP separata, anche minuti dopo — mai supporre che sia lo stesso
+     * processo che l'ha messa in pausa.
+     */
+    private resumeCompletion;
+    /**
+     * Una sola chiamata a OpenRouter — nessuna orchestrazione interna, nessun tool eseguito
+     * da FANTASTICO. Riusa la stessa runtime key + prenotazione budget di create(): il
+     * chiamante ottiene lo stesso pattern "prenota-e-salda ad ogni giro"
+     * semplicemente richiamando createRaw() a ogni passo del proprio loop di tool-use.
+     */
+    private createRawCompletion;
+    /**
+     * Una chiamata all'endpoint Decisions (`decisions.ts`) — stessa contabilità di `createRawCompletion`:
+     * prenota il budget del tenant prima, regola il costo reale dopo. È il punto unico da cui passano
+     * sia `ai.decisions.evaluate()` sia i tool costruiti con `ai.decisions.tool()`, cosicché una
+     * decisione chiamata da dentro un loop di tool-use paghi sullo stesso conto delle chiamate dirette.
+     */
+    private evaluateDecision;
+    /**
+     * Una chiamata all'endpoint TTS (`speech.ts`) — la stessa contabilità di `createRawCompletion`
+     * **meno la regolazione del costo**, e la differenza va detta: la risposta è audio e non porta
+     * un `usage`; il costo si legge da `GET /generation` solo dopo circa cinque secondi. Aspettarli
+     * dentro la chiamata la rallenterebbe per un numero che serve soltanto al preavviso di
+     * `lowBalance` — l'addebito vero lo misura il ledger dall'usage della chiave, qui come per una
+     * chat. Quindi `unsettled` non si tocca, e il risultato porta l'id della generazione e non una
+     * stima.
+     */
+    private createSpeech;
+    /**
+     * Chiamata autenticata al control plane con la project key.
+     *
+     * Il codice d'errore arriva dal Cloud e si propaga così com'è (`ALLOWANCE_EXHAUSTED`,
+     * `CONTO_KEY_EXISTS`, `SCOPE_FORBIDDEN`…): tradurlo in un codice generico farebbe perdere
+     * al chiamante l'unica informazione che gli dice cosa fare.
+     */
+    private api;
+    /**
+     * Salda subito il consumo residuo di un tenant senza avviare una nuova chiamata.
+     * Da invocare a fine sessione, così l'ultimo costo non resta in sospeso fino al giro
+     * successivo (la misura del provider resta comunque la fonte di verità).
+     */
+    flushBudget(userKey: string): Promise<void>;
+}