TypeScript
The TypeScript library is the @lingara/api package on npm. It runs on Node.js 22 or later, has no runtime dependencies, and ships type definitions for every request, response and stream event.
Where it runs
It is a server-side library. There is no browser build, and the client refuses a client secret when it finds itself in a page: a client secret in a browser is a published secret, readable by anyone who opens the page. Call the API from your own server and send your users only what they need.
How it reads
- Every call returns a promise. Pass
{ signal }with anAbortSignalto cancel one; the call then rejects with the signal’s own reason. - A stream is an async iterable, read with
for await. It is lazy: the request is sent when you ask for the first event. - Errors extend
LingaraError, so oneinstanceofcheck catches all four. Each carriesretryAfterwhen the API named a wait. - To use your own HTTP stack, pass a
fetchfunction in the options. The idle timeout on streams still applies.
The samples below install the package, create a client, stream a vocabulary list and handle an error.
TypeScript
npm install @lingara/api@0.1.0-alpha.6TypeScript
import { Lingara } from "@lingara/api";
const client = new Lingara({
clientId: process.env.LINGARA_CLIENT_ID!,
clientSecret: process.env.LINGARA_CLIENT_SECRET!,
});TypeScript
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);
}TypeScript
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;
}
}