Node.js SDK (polylingo)

PolyLingo REST API-এর জন্য অফিসিয়াল TypeScript-প্রথম ক্লায়েন্ট। এটি রানটাইম fetch (Node.js 18+) ব্যবহার করে, ESM এবং CJS হিসেবে সরবরাহ করা হয়, এবং 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 // স্ট্রিং
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 — অ্যাসিঙ্ক্রোনাস কাজের জন্য কিউতে যুক্ত করুন। 202 JSON বডি (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 JSON অবজেক্টের শীর্ষ স্তরে translations এবং usage ফেরত দেয় (নেস্টেড নয় 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, // পোলের মধ্যে মিলিসেকেন্ড; ডিফল্ট 5_000
  timeout: 600_000,     // পোলিংয়ের **মোট** মিলিসেকেন্ড বাজেট; ডিফল্ট ২০ মিনিট
  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. ফায়ার-অ্যান্ড-ফরগেট পোলিং: jobs.create → আপনার ওয়ার্কার নির্দিষ্ট ইন্টারভালে jobs.get কল করে যতক্ষণ না completed বা failed।
2. বিল্ট-ইন পোলিং: jobs.translate — একই সেমান্টিক্স, pollInterval, timeout, এবং onProgress সহ।

বড় পে-লোড এবং দীর্ঘমেয়াদী অনুবাদের জন্য HTTP টাইমআউট এড়াতে জবস ব্যবহার করা উচিত translate এর পরিবর্তে।

TypeScript

প্যাকেজ অপশন, ফলাফল, এবং এররগুলোর জন্য টাইপ এক্সপোর্ট করে। প্রয়োজন অনুযায়ী polylingo থেকে নামকৃত টাইপ ইমপোর্ট করুন (প্রকাশিত dist/index.d.ts দেখুন)।

চেঞ্জলগ

0.1.0

• প্রাথমিক রিলিজ: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate।