Node.js SDK (polylingo)

Επίσημος πελάτης TypeScript-first για το PolyLingo REST API. Χρησιμοποιεί το runtime fetch (Node.js 18+), διανέμεται ως ESM και CJS, και δεν έχει εξαρτήσεις κατά το runtime πέραν του Node.

• npm: polylingo
• Πηγή: UsePolyLingo/polylingo-node

Για λεπτομέρειες HTTP, δείτε API reference.

Εγκατάσταση

npm install polylingo

Node.js: >= 18

Κατασκευαστής

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // απαιτείται
  baseURL: 'https://api.usepolylingo.com/v1', // προαιρετικό; αυτό είναι το προεπιλεγμένο
  timeout: 120_000, // προαιρετικό; χρονικό όριο αιτήματος σε χιλιοστά του δευτερολέπτου (προεπιλογή 120_000)
})

Μέθοδοι

client.health()

GET /health — δεν απαιτείται αυθεντικοποίηση στον διακομιστή· ο πελάτης στέλνει ακόμα την κεφαλίδα Authorization αν έχει ρυθμιστεί.

Επιστρέφει { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — λίστα υποστηριζόμενων γλωσσών.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // προαιρετικό — αν παραλειφθεί γίνεται αυτόματη ανίχνευση στο API
  source: 'en',       // προαιρετική υπόδειξη
  model: 'standard',  // προαιρετικό: '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',    // προαιρετικό
  model: 'standard', // προαιρετικό
})

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

client.usage()

GET /usage — χρήση σχεδίου για το αυθεντικοποιημένο κλειδί.

const u = await client.usage()

Εργασίες — client.jobs

client.jobs.create(params)

POST /jobs — τοποθετεί εργασία στην ουρά ασύγχρονης εργασίας. Επιστρέφει το JSON σώμα 202 (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 — ελέγχει την κατάσταση. Όταν status === 'completed', το API επιστρέφει translations και usage στο ανώτατο επίπεδο του JSON αντικειμένου (όχι μέσα σε result).

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

client.jobs.translate(params) — ευκολία

Υποβάλλει εργασία και μετά ελέγχει περιοδικά μέχρι να είναι completed ή failed, ή μέχρι να εξαντληθεί ο προϋπολογισμός ελέγχου.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms μεταξύ ελέγχων; προεπιλογή 5_000
  timeout: 600_000,     // **συνολικός** προϋπολογισμός ms για έλεγχο; προεπιλογή 20 λεπτά
  onProgress: (pos) => console.log(`Queue position: ${pos}`), // προαιρετικό; καλείται ενώ είναι στην ουρά/επεξεργασία
})

done.translations.de
done.usage.total_tokens

Ο κύκλος ζωής εργασίας στο API χρησιμοποιεί καταστάσεις pending, processing, completed, και failed.

Διαχείριση σφαλμάτων

Όλες οι αποτυχίες από το SDK (εκτός από σφάλματα κώδικα) επεκτείνουν PolyLingoError:

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

try {
  await client.translate({ content: 'Hi', targets: ['es'] })
} catch (e) {
  if (e instanceof AuthError) { /* άκυρο κλειδί */ }
  else if (e instanceof RateLimitError) { /* e.retryAfter */ }
  else if (e instanceof JobFailedError) { /* e.jobId */ }
  else if (e instanceof PolyLingoError) { /* e.status, e.error */ }
}

Πρότυπο ασύγχρονων εργασιών (περίληψη)

1. Fire-and-forget polling: jobs.create → ο εργάτης σας καλεί jobs.get περιοδικά μέχρι completed ή failed.
2. Ενσωματωμένο polling: jobs.translate — ίδια σημασιολογία, με pollInterval, timeout, και onProgress.

Μεγάλες αποστολές και μακροχρόνιες μεταφράσεις πρέπει να προτιμούν εργασίες αντί για συγχρονικό translate για να αποφύγουν χρονικά όρια HTTP.

TypeScript

Το πακέτο εξάγει τύπους για επιλογές, αποτελέσματα και σφάλματα. Εισάγετε ονομασμένους τύπους από το polylingo όπως χρειάζεται (δείτε το δημοσιευμένο dist/index.d.ts).

Αρχείο αλλαγών

0.1.0

• Αρχική έκδοση: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.