TypeScript

Cette page est traduite de l'anglais. En cas de différence, la page anglaise fait foi. Lire la page en anglais

La bibliothèque TypeScript est le paquet @lingara/api sur npm. Elle fonctionne sous Node.js 22 ou version ultérieure, n’a aucune dépendance d’exécution et fournit des définitions de types pour chaque requête, réponse et événement de flux.

Où elle s’exécute

C’est une bibliothèque côté serveur. Il n’existe pas de version pour navigateur, et le client refuse un secret client lorsqu’il se trouve dans une page : un secret client dans un navigateur est un secret publié, lisible par quiconque ouvre la page. Appelez l’API depuis votre propre serveur et n’envoyez à vos utilisateurs que ce dont ils ont besoin.

À quoi elle ressemble

• Chaque appel renvoie une promesse. Passez { signal } avec un AbortSignal pour en annuler un ; l’appel est alors rejeté avec le motif propre au signal.
• Un flux est un itérable asynchrone, lu avec for await. Il est paresseux : la requête est envoyée quand vous demandez le premier événement.
• Les erreurs étendent LingaraError, si bien qu’une seule vérification instanceof intercepte les quatre. Chacune porte retryAfter quand l’API a indiqué un délai.
• Pour utiliser votre propre pile HTTP, passez une fonction fetch dans les options. Le délai d’inactivité des flux s’applique toujours.

Les exemples ci-dessous installent le paquet, créent un client, diffusent une liste de vocabulaire et gèrent une erreur.

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;
  }
}