TypeScript

Questa pagina è tradotta dall'inglese. Se le due versioni differiscono, fa fede la pagina in inglese. Leggi la pagina in inglese

La libreria TypeScript è il pacchetto @lingara/api su npm. Funziona su Node.js 22 o successivo, non ha dipendenze di runtime e include le definizioni di tipo per ogni richiesta, risposta ed evento di stream.

Dove funziona

È una libreria lato server. Non esiste una build per browser, e il client rifiuta un client secret quando si accorge di trovarsi in una pagina: un client secret in un browser è un secret pubblicato, leggibile da chiunque apra la pagina. Chiama l’API dal tuo server e invia ai tuoi utenti solo ciò di cui hanno bisogno.

Come si usa

• Ogni chiamata restituisce una promise. Passa { signal } con un AbortSignal per annullarne una; la chiamata viene quindi rifiutata con il motivo proprio del segnale.
• Uno stream è un iterabile asincrono, letto con for await. È lazy: la richiesta viene inviata quando chiedi il primo evento.
• Gli errori estendono LingaraError, quindi un solo controllo instanceof li intercetta tutti e quattro. Ognuno contiene retryAfter quando l’API ha indicato un’attesa.
• Per usare il tuo stack HTTP, passa una funzione fetch nelle opzioni. Il timeout di inattività degli stream resta comunque valido.

Gli esempi qui sotto installano il pacchetto, creano un client, ricevono in streaming un elenco di vocaboli e gestiscono un errore.

npm install @lingara/api@0.1.0-alpha.6

import { Lingara } from "@lingara/api";

const client = new Lingara({
  clientId: process.env.LINGARA_CLIENT_ID!,
  clientSecret: process.env.LINGARA_CLIENT_SECRET!,
});

const stream = client.generateVocabulary({ level: 2, source_lang: "en", target_lang: "zh", count: 8 });
for await (const ev of stream) {
  if (ev.event === "item") console.log(ev.data.word, ev.data.translation);
}

import { ApiError, MaintenanceError, OAuthError, TransportError } from "@lingara/api";

try {
  await client.getUsage();
} catch (e) {
  if (e instanceof ApiError) {
    // A refusal from the API: e.status, e.code (stable) and e.message (localised).
    console.error(e.status, e.code, e.message, e.retryAfter ?? "");
  } else if (e instanceof OAuthError) {
    // The token endpoint refused the credentials or the scopes.
    console.error(e.status, e.error, e.description ?? "");
  } else if (e instanceof MaintenanceError) {
    console.error("under maintenance; retry after", e.retryAfter ?? "a while");
  } else if (e instanceof TransportError) {
    // No usable answer: connect, tls, reset, timeout, and so on.
    console.error("transport:", e.kind);
  } else {
    throw e;
  }
}