TypeScript

Esta página é uma tradução do inglês. Se as duas diferirem, a página em inglês é a correta. Ler a página em inglês

A biblioteca TypeScript é o pacote @lingara/api no npm. Funciona em Node.js 22 ou posterior, não tem dependências de runtime e inclui definições de tipos para cada pedido, resposta e evento de stream.

Onde funciona

É uma biblioteca do lado do servidor. Não existe versão para navegador, e o cliente recusa um segredo de cliente quando deteta que está numa página: um segredo de cliente num navegador é um segredo publicado, legível por qualquer pessoa que abra a página. Chame a API a partir do seu próprio servidor e envie aos seus utilizadores apenas aquilo de que precisam.

Como se utiliza

• Cada chamada devolve uma promise. Passe { signal } com um AbortSignal para cancelar uma; a chamada é então rejeitada com o motivo próprio do sinal.
• Um stream é um iterável assíncrono, lido com for await. É preguiçoso: o pedido é enviado quando pede o primeiro evento.
• Os erros estendem LingaraError, pelo que uma única verificação instanceof apanha os quatro. Cada um contém retryAfter quando a API indicou uma espera.
• Para usar a sua própria pilha HTTP, passe uma função fetch nas opções. O tempo limite de inatividade dos streams continua a aplicar-se.

Os exemplos abaixo instalam o pacote, criam um cliente, recebem em stream uma lista de vocabulário e tratam um erro.

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