Node.js SDK (polylingo)

Officiële TypeScript-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; request 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. Retourneert de 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; weglaten om de API automatisch te laten detecteren
  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. Retourneert het gebruik van het plan voor de geauthenticeerde sleutel.

const u = await client.usage()

Jobs (client.jobs)

client.jobs.create(params)

POST /jobs. Zet asynchrone taken in de wachtrij en 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. Pollt de 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 deze completed of failed is, of totdat de timeout is bereikt.

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

De levenscyclus van een taak 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 jobs 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. Zelfde semantiek, met pollInterval, timeout en onProgress.

Grote payloads en langdurige vertalingen verdienen de voorkeur om jobs te gebruiken 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.2

• Onderhoud: standaard API basis-URL is https://api.usepolylingo.com/v1.

0.1.0

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