منصوبے کے بارے میں

Alegra API کے لیے TypeScript میں ایک ہلکا پھلکا اور ٹائپڈ کلائنٹ، جو انٹیگریشن لیئر کے لیے ڈیزائن کیا گیا ہے۔ یہ رابطوں (contacts)، آئٹمز (items) اور انوائسز (factures) کے وسائل پر تصدیق، صفحہ بندی اور ری ٹرائیز کے ساتھ ریٹ لمٹس کے انتظام کا احاطہ کرتا ہے۔ یہ ایک غیر سرکاری پروجیکٹ ہے جس کا Alegra کے ساتھ کوئی تعلق نہیں ہے، اور اس کی دستاویزات ہسپانوی میں ہیں کیونکہ مصنف کے مطابق دستیاب معلومات کم ہیں۔ تصدیق یہ ای میل اور API ٹوکن (پاس ورڈ نہیں) کے ساتھ HTTP Basic استعمال کرتا ہے۔ ٹوکن Alegra کے اکاؤنٹ میں انٹیگریشنز/API سیکشن سے حاصل کیا جاتا ہے۔ بنیادی URL https://api.alegra.com/api/v1 ہے اور تصدیق کی ناکامی پر HTTP 401 کا جواب ملتا ہے۔ README میں اس بات کی سفارش کی گئی ہے کہ کریڈنشلز کو کوڈ کے بجائے انوائرمنٹ ویری ایبلز میں محفوظ کیا جائے؛ اس کے لیے ایک .env.example فائل شامل ہے۔ صفحہ بندی (Pagination) API پیرامیٹرز start (offset) اور limit کے ذریعے فی صفحہ زیادہ سے زیادہ 30 ریکارڈز واپس کرتی ہے۔ کلائنٹ ایک اسنکرونس جنریٹر فراہم کرتا ہے تاکہ تمام ڈیٹا کو میموری میں لوڈ کیے بغیر صفحہ بہ صفحہ براؤز کیا جا سکے، اس کے علاوہ ایک ہی صفحہ حاصل کرنے یا تمام نتائج جمع کرنے کے طریقے بھی موجود ہیں۔ دستیاب وسائل اور ان کے طریقے یہ ہیں: contacts (listar, obtener, paginar, listarTodos)، items (listar, obtener, paginar, listarTodos) اور facturas (listar, obtener, paginar, listarTodas)۔ ان اینڈ پوائنٹس کے لیے جو کور نہیں ہیں، ایک جنرل request کال کے ذریعے براہ راست کلائنٹ استعمال کیا جا سکتا ہے جو کوئری پیرامیٹرز قبول کرتا ہے۔ ریٹ لمٹس اور ری ٹرائیز README میں فی صارف فی منٹ 150 درخواستوں (تقریباً 2.5 فی سیکنڈ) کی حد بتائی گئی ہے۔ اس حد سے تجاوز کرنے پر API HTTP 429 کا جواب دیتی ہے اور X-Rate-Limit-Limit، X-Rate-Limit-Remaining اور X-Rate-Limit-Reset (ونڈو ری سیٹ کرنے کے لیے باقی سیکنڈز) ہیڈرز میں صورتحال بتاتی ہے؛ مصنف کے مطابق، Alegra Retry-After نہیں بھیجتا۔ کلائنٹ 429 اور 5xx کی صورت میں خودکار طور پر دوبارہ کوشش کرتا ہے: 429 کے کیس میں یہ X-Rate-Limit-Reset (یا Retry-After اگر موجود ہو) کا انتظار کرتا ہے، اور اگر کوئی نہیں ہوتا تو jitter کے ساتھ ایکسپونینشل بیک آف لاگو کرتا ہے۔ 4xx غلطیوں پر دوبارہ کوشش نہیں کی جاتی، لیکن نیٹ ورک کی ناکامیوں پر ری ٹرائیز کیے جاتے ہیں۔ قابل ترتیب آپشنز میں minRequestIntervalMs (درخواستوں کے درمیان احتیاطی وقفہ)، maxRetries، retryBaseMs اور timeoutMs شامل ہیں۔ فی درخواست ٹائم آؤٹ AbortController کے ذریعے نافذ کیا گیا ہے۔ اگر 429 کے لیے ری ٹرائیز ختم ہو جائیں تو AlegraRateLimitError پھینکا جاتا ہے، جس میں retryAfterSeconds شامل ہو سکتا ہے۔ غلطیاں API کی ناکامیوں اور استعمال کی حد ختم ہونے کے درمیان فرق کرنے کے لیے AlegraApiError (status, endpoint اور body کے ساتھ) اور AlegraRateLimitError کلاسز فراہم کی گئی ہیں۔ ضروریات اور ترقی نیٹو fetch کے استعمال کی وجہ سے Node.js 18 یا اس سے اوپر کے ورژن کی ضرورت ہے، اور رن ٹائم پر اس کی کوئی ڈیپینڈینسی نہیں ہے؛ اسے Node، Deno اور edge ماحول کے لیے پورٹیبل کے طور پر پیش کیا گیا ہے۔ ڈویلپمنٹ فلو میں npm run build، سیمولیٹڈ fetch اور فرضی ڈیٹا کے ساتھ vitest ٹیسٹ، اور ٹائپ ویریفیکیشن (lint:types) شامل ہیں۔ مثالوں میں فرضی ڈیٹا اور انوائرمنٹ ویری ایبلز کے ذریعے کریڈنشلز استعمال کیے گئے ہیں۔ لائسنس MIT ہے؛ چینج لاگ میں درج ورژن 0.1.0 ہے، جو پہلا عوامی ورژن ہے۔ دائرہ کار README میں خبردار کیا گیا ہے کہ اگر آفیشل API تبدیل ہوتی ہے تو شامل Alegra API کا خلاصہ ٹیبل اپ ڈیٹ کیا جانا چاہیے، اور یہ خلاصہ ہسپانوی میں دستاویزات کی کمی کی وجہ سے موجود ہے۔ کارکردگی کے حوالے سے کوئی دعوے یا دیگر کلائنٹس کے ساتھ موازنہ پیش نہیں کیا گیا ہے۔