Node.js SDK (polylingo)

Officiële TypeScript-first client voor de PolyLingo REST API. Het gebruikt de runtime fetch (Node.js 18+), wordt geleverd als ESM en CJS, en heeft geen runtime-afhankelijkheden buiten Node.

• npm: polylingo
• Bron: UsePolyLingo/polylingo-node

Voor ruwe HTTP-details, zie API-referentie.

Installatie

npm install polylingo

Node.js: >= 18

Constructor

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // verplicht
  baseURL: 'https://api.usepolylingo.com/v1', // optioneel; dit is de standaard
  timeout: 120_000, // optioneel; verzoek timeout in milliseconden (standaard 120_000)
})

Methoden

client.health()

GET /health — geen authenticatie vereist op de server; de client stuurt nog steeds de Authorization header als deze is geconfigureerd.

Retourneert { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — lijst met ondersteunde talen.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // optioneel — weggelaten = automatisch detecteren via de API
  source: 'en',       // optionele hint
  model: 'standard',  // optioneel: 'standard' | 'advanced'
})

r.translations.es // string
r.usage.total_tokens
r.usage.input_tokens
r.usage.output_tokens

client.batch(params)

POST /translate/batch

const b = await client.batch({
  items: [
    { id: 'a', content: 'Hello' },
    { id: 'b', content: '## Title', format: 'markdown' },
  ],
  targets: ['de'],
  source: 'en',    // optioneel
  model: 'standard', // optioneel
})

b.results[0].translations.de
b.usage.total_tokens

client.usage()

GET /usage — plan gebruik voor de geauthenticeerde sleutel.

const u = await client.usage()

Taken — client.jobs

client.jobs.create(params)

POST /jobs — zet asynchrone taak in de wachtrij. Lost op met de 202 JSON-body (job_id, status, created_at, …).

const job = await client.jobs.create({
  content: longMarkdown,
  targets: ['de', 'fr'],
  format: 'markdown',
})
console.log(job.job_id)

client.jobs.get(jobId)

GET /jobs/:id — poll status. Wanneer status === 'completed', retourneert de API translations en usage op het bovenste niveau van het JSON-object (niet genest onder result).

const status = await client.jobs.get(job.job_id)

client.jobs.translate(params) — gemaksmethode

Dient een taak in en pollt vervolgens totdat completed of failed, of totdat het polling-budget op is.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms tussen polls; standaard 5_000
  timeout: 600_000,     // **totaal** ms budget voor polling; standaard 20 minuten
  onProgress: (pos) => console.log(`Wachtrijpositie: ${pos}`), // optioneel; wordt aangeroepen tijdens wachtrij/verwerking
})

done.translations.de
done.usage.total_tokens

Levenscyclus van taken op de API gebruikt statussen pending, processing, completed en failed.

Foutafhandeling

Alle fouten van de SDK (behalve bugs) breiden PolyLingoError uit:

import PolyLingo, {
  PolyLingoError,
  AuthError,
  RateLimitError,
  JobFailedError,
} from 'polylingo'

try {
  await client.translate({ content: 'Hi', targets: ['es'] })
} catch (e) {
  if (e instanceof AuthError) { /* ongeldige sleutel */ }
  else if (e instanceof RateLimitError) { /* e.retryAfter */ }
  else if (e instanceof JobFailedError) { /* e.jobId */ }
  else if (e instanceof PolyLingoError) { /* e.status, e.error */ }
}

Async taken patroon (samenvatting)

1. Fire-and-forget polling: jobs.create → jouw worker roept jobs.get periodiek aan totdat completed of failed.
2. Ingebouwde polling: jobs.translate — dezelfde semantiek, met pollInterval, timeout en onProgress.

Grote payloads en langlopende vertalingen moeten de voorkeur geven aan jobs boven synchrone translate om HTTP timeouts te vermijden.

TypeScript

Het pakket exporteert types voor opties, resultaten en fouten. Importeer benoemde types uit polylingo indien nodig (zie gepubliceerde dist/index.d.ts).

Wijzigingslog

0.1.0

• Eerste release: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.