Node.js SDK (polylingo)

Offisiell TypeScript-først klient for PolyLingo REST API. Den bruker runtime fetch (Node.js 18+), leveres som ESM og CJS, og har ingen runtime-avhengigheter utover Node.

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

For rå HTTP-detaljer, se API-referanse.

Installasjon

npm install polylingo

Node.js: >= 18

Konstruktør

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // påkrevd
  baseURL: 'https://api.usepolylingo.com/v1', // valgfritt; dette er standard
  timeout: 120_000, // valgfritt; forespørselstimeout i millisekunder (standard 120_000)
})

Metoder

client.health()

GET /health — ingen autentisering kreves på serveren; klienten sender fortsatt Authorization-header hvis konfigurert.

Returnerer { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — liste over støttede språk.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // valgfritt — utelatt = automatisk gjenkjenning i API
  source: 'en',       // valgfritt hint
  model: 'standard',  // valgfritt: 'standard' | 'advanced'
})

r.translations.es // streng
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',    // valgfritt
  model: 'standard', // valgfritt
})

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

client.usage()

GET /usage — planbruk for den autentiserte nøkkelen.

const u = await client.usage()

Jobber — client.jobs

client.jobs.create(params)

POST /jobs — sett asynkront arbeid i kø. Returnerer 202 JSON-kropp (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. Når status === 'completed', returnerer API translations og usage på øverste nivå i JSON-objektet (ikke under result).

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

client.jobs.translate(params) — bekvemmelighet

Sender inn en jobb, og poller deretter til completed eller failed, eller til polling-budsjettet er brukt opp.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms mellom polls; standard 5_000
  timeout: 600_000,     // **total** ms budsjett for polling; standard 20 minutter
  onProgress: (pos) => console.log(`Køposisjon: ${pos}`), // valgfritt; kalles mens i kø/behandler
})

done.translations.de
done.usage.total_tokens

Jobbens livssyklus på API bruker statusene pending, processing, completed og failed.

Feilhåndtering

Alle feil fra SDK (bortsett fra feil) utvider PolyLingoError:

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

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

Async jobbmønster (oppsummering)

1. Fire-and-forget polling: jobs.create → din arbeider kaller jobs.get med jevne mellomrom til completed eller failed.
2. Innebygd polling: jobs.translate — samme semantikk, med pollInterval, timeout og onProgress.

Store payloads og langvarige oversettelser bør foretrekke jobs fremfor synkron translate for å unngå HTTP timeouts.

TypeScript

Pakken eksporterer typer for alternativer, resultater og feil. Importer navngitte typer fra polylingo etter behov (se publisert dist/index.d.ts).

Endringslogg

0.1.0

• Første utgivelse: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.