React UI · @pura-ai/react

Prerequisiti e installazione#

Il pacchetto @pura-ai/react 0.1.1 richiede React 18.2 o 19 e @pura-ai/sdk ^0.1.1 come peer dependency. È ESM con dichiarazioni TypeScript; gli stili sono inclusi, non serve un framework CSS e gli export inutilizzati possono essere rimossi dal bundler. Gli SDK sono proprietari: consulta Versioni e compatibilità per la distribuzione ufficiale e il metodo di installazione disponibile.

Registra un client pubblico con l’icona PNG richiesta e un callback web esatto; usa HTTPS in produzione oppure HTTP localhost in sviluppo. Consulta Registrazione delle app per le regole complete. I componenti React usano il ritorno nella stessa scheda: per i deep link nativi usa il client OAuth e il gestore del sistema operativo.

Collega l’utente e mostra il consumo#

Questo esempio usa uno store in memoria per una sola sessione: dopo un reload occorre ricollegarsi. Sostituiscilo con un adapter per l’utente corrente prima del rilascio. Nella pagina di callback esegui completeBrowserConnection(options), salva i token restituiti e solo dopo monta UsagePanel con un client stabile.

import {ConnectPuraLLM, UsagePanel} from '@pura-ai/react';
import {PuraInferenceClient, completeBrowserConnection, type StoredTokens} from '@pura-ai/sdk';

const options = {
  apiBase: 'https://ai.puradigital.it/v1',
  clientId: 'YOUR_REGISTERED_PUBLIC_CLIENT_ID',
  redirectUri: 'https://your-app.example/pura/callback',
};
// Minimal single-tab demo only: reconnect after reload. Use your application's
// per-user session adapter for production; never embed a client secret.
let tokens: StoredTokens | null = null;
const store = {get: async () => tokens, set: async (value: StoredTokens) => {tokens = value;}};
const client = new PuraInferenceClient({...options, store});

// On the registered callback page, in the same tab, before mounting UsagePanel:
// await store.set(await completeBrowserConnection(options));
export function Connect() {
  return <ConnectPuraLLM options={options} onError={console.error} />;
}
export function ConnectedUsage() {
  return <UsagePanel client={client} />;
}

ConnectPuraLLM#

ConnectPuraLLM mostra un bottone bianco con il logo ufficiale e il testo “Connect Pura LLM”. Delega all’SDK PKCE, state, storage pending e navigazione; previene i doppi clic e invoca onError se l’autorizzazione fallisce. Sono supportate le normali proprietà HTML del bottone e style; etichetta e comportamento del clic sono fissi. Non passare un client secret nelle opzioni React.

UsagePanel e aggiornamenti#

UsagePanel chiama soltanto client.usage(). Passa un client stabile e cambia refreshKey dopo un’inferenza per rileggere il consumo. Il pannello mostra caricamento, errori, stato bloccato, percentuali mensili e settimanali e date di reset ISO. Ignora risposte obsolete dopo lo smontaggio o il cambio del client. Consumo e limiti restano condivisi fra le app dell’account: consulta Consumo e limiti.

La UI non implementa storage dei token, logica di refresh OAuth, budget monetari o fallback sul wallet. Per un’app confidential/BFF conserva token e secret sul backend e passa al pannello un adapter usage() che chiama un tuo endpoint autenticato. Consulta Token e concorrenza per lo store e i lock di refresh.

Demo completa e verifiche#

Il pacchetto npm include examples/App.tsx con callback, chat e aggiornamento del consumo. Montalo nella tua app React e sostituisci client ID e callback con quelli registrati. La demo mantiene i token in memoria per una sola sessione browser: adatta la persistenza alla tua applicazione. Prima del rilascio verifica consenso negato, callback scaduta, due utenti distinti, aggiornamento dopo chat e stati di errore del pannello; segui Test e rilascio.