Node.js SDK (polylingo)

Officiel TypeScript-første klient til PolyLingo REST API. Den bruger runtime fetch (Node.js 18+), leveres som ESM og CJS, og har ingen runtime-afhængigheder ud over Node.

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

For rå HTTP-detaljer, se API reference.

Installation

npm install polylingo

Node.js: >= 18

Constructor

import PolyLingo from 'polylingo'

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

Metoder

client.health()

GET /health — ingen auth krævet på serveren; klienten sender stadig Authorization header hvis konfigureret.

Returnerer { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — understøttede sprog liste.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // valgfrit — udeladt = auto-detektion på API
  source: 'en',       // valgfrit hint
  model: 'standard',  // valgfrit: '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',    // valgfrit
  model: 'standard', // valgfrit
})

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

client.usage()

GET /usage — plan brug for den autentificerede nøgle.

const u = await client.usage()

Jobs — client.jobs

client.jobs.create(params)

POST /jobs — sæt asynkront arbejde i kø. Returnerer 202 JSON-krop (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 niveau af JSON-objektet (ikke indlejret under result).

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

client.jobs.translate(params) — bekvemmelighed

Indsender et job, og poller derefter indtil completed eller failed, eller indtil polling-budgettet er opbrugt.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms mellem polls; standard 5_000
  timeout: 600_000,     // **total** ms budget for polling; standard 20 minutter
  onProgress: (pos) => console.log(`Queue position: ${pos}`), // valgfrit; kaldt mens i kø/behandling
})

done.translations.de
done.usage.total_tokens

Job livscyklus på API bruger statusserne pending, processing, completed og failed.

Fejlhåndtering

Alle fejl fra SDK (undtagen bugs) udvider 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øgle */ }
  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 mønster (resumé)

1. Fire-and-forget polling: jobs.create → din worker kalder jobs.get med jævne mellemrum indtil completed eller failed.
2. Indbygget polling: jobs.translate — samme semantik, med pollInterval, timeout og onProgress.

Store payloads og langvarige oversættelser bør foretrække jobs frem for synkron translate for at undgå HTTP timeouts.

TypeScript

Pakken eksporterer typer for muligheder, resultater og fejl. Importer navngivne typer fra polylingo efter behov (se publiceret dist/index.d.ts).

Changelog

0.1.0

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