প্রকল্প সম্পর্কে

এটি Alegra API-এর জন্য একটি হালকা এবং টাইপড TypeScript ক্লায়েন্ট, যা ইন্টিগ্রেশন লেয়ারের জন্য তৈরি। এটি কন্টাক্টস, আইটেমস এবং ইনভয়েস রিসোর্সগুলোর জন্য অথেন্টিকেশন, পেজিনেশন এবং রিট্রাই মেকানিজমের মাধ্যমে রেট লিমিট হ্যান্ডলিং কভার করে। এটি একটি আন-অফিসিয়াল প্রজেক্ট, যার সাথে Alegra-এর কোনো সম্পর্ক নেই এবং লেখকের মতে পর্যাপ্ত তথ্যের অভাবে এর ডকুমেন্টেশন স্প্যানিশ ভাষায় লেখা হয়েছে। অথেন্টিকেশন এটি ইমেল এবং API টোকেন (পাসওয়ার্ড নয়) সহ HTTP Basic ব্যবহার করে। টোকেনটি Alegra অ্যাকাউন্টের ইন্টিগ্রেশন/API সেকশন থেকে তৈরি করা হয়। বেস URL হলো https://api.alegra.com/api/v1 এবং অথেন্টিকেশন ব্যর্থ হলে HTTP 401 রেসপন্স আসে। README-তে ক্রেডেনশিয়ালগুলো কোডের পরিবর্তে এনভায়রনমেন্ট ভেরিয়েবলে রাখার পরামর্শ দেওয়া হয়েছে এবং একটি .env.example ফাইল অন্তর্ভুক্ত করা হয়েছে। পেজিনেশন API-টি start (অফসেট) এবং limit প্যারামিটারের মাধ্যমে প্রতি পৃষ্ঠায় সর্বোচ্চ ৩০টি রেকর্ড রিটার্ন করে। ক্লায়েন্টটি মেমোরিতে সব ডেটা লোড না করে পৃষ্ঠা অনুযায়ী ডেটা সংগ্রহের জন্য একটি অ্যাসিনক্রোনাস জেনারেটর প্রদান করে, পাশাপাশি একক পৃষ্ঠা বা সমস্ত ফলাফল সংগ্রহের মেথড রয়েছে। উপলব্ধ রিসোর্স এবং মেথডগুলো হলো: কন্টাক্টস (listar, obtener, paginar, listarTodos), আইটেমস (listar, obtener, paginar, listarTodos) এবং ইনভয়েস (listar, obtener, paginar, listarTodas)। যেসব এন্ডপয়েন্ট কভার করা হয়নি, সেগুলোর জন্য একটি জেনেরিক request কল ব্যবহার করে সরাসরি ক্লায়েন্ট ব্যবহার করা সম্ভব। রেট লিমিট এবং রিট্রাই README-তে প্রতি ব্যবহারকারীর জন্য প্রতি মিনিটে ১৫০টি অনুরোধের (সেকেন্ডে প্রায় ২.৫টি) সীমাবদ্ধতার কথা উল্লেখ করা হয়েছে। এই সীমা অতিক্রম করলে 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 থাকলে সেটি) অনুযায়ী অপেক্ষা করে, আর কোনোটি না থাকলে জিটারসহ এক্সপোনেনশিয়াল ব্যাক-অফ প্রয়োগ করে। 4xx এরর রিট্রাই করা হয় না, তবে নেটওয়ার্ক ফেইলিউরের ক্ষেত্রে রিট্রাই করা হয়। কনফিগারযোগ্য অপশনগুলোর মধ্যে রয়েছে minRequestIntervalMs (অনুরোধের মধ্যবর্তী প্রতিরোধমূলক ব্যবধান), maxRetries, retryBaseMs এবং timeoutMs। প্রতিটি অনুরোধের টাইমআউট AbortController দিয়ে বাস্তবায়ন করা হয়েছে। 429-এর ক্ষেত্রে রিট্রাই শেষ হয়ে গেলে AlegraRateLimitError থ্রো করা হয়, যাতে retryAfterSeconds অন্তর্ভুক্ত থাকতে পারে। এরর হ্যান্ডলিং API এরর এবং ব্যবহারের সীমা শেষ হওয়ার পার্থক্য করার জন্য AlegraApiError (status, endpoint এবং body সহ) এবং AlegraRateLimitError ক্লাসগুলো প্রদান করা হয়েছে। প্রয়োজনীয়তা এবং ডেভেলপমেন্ট নেটিভ fetch ব্যবহারের কারণে Node.js 18 বা তার পরবর্তী সংস্করণ প্রয়োজন এবং এর কোনো রানটাইম ডিপেন্ডেন্সি নেই; এটি Node, Deno এবং এজ এনভায়রনমেন্টের জন্য পোর্টেবল। ডেভেলপমেন্ট ফ্লো-তে npm run build, সিমুলেটেড fetch এবং ডামি ডেটা দিয়ে vitest-এর মাধ্যমে টেস্টিং এবং টাইপ ভেরিফিকেশন (lint:types) অন্তর্ভুক্ত। উদাহরণগুলোতে ডামি ডেটা এবং এনভায়রনমেন্ট ভেরিয়েবল ব্যবহার করা হয়েছে। লাইসেন্স MIT; চেঞ্জলগে তালিকাভুক্ত সংস্করণটি হলো 0.1.0, যা প্রথম পাবলিক ভার্সন। পরিধি README-তে সতর্ক করা হয়েছে যে, অফিসিয়াল API পরিবর্তিত হলে অন্তর্ভুক্ত API সামারি টেবিলটি আপডেট করতে হবে এবং স্প্যানিশ ডকুমেন্টেশনের অভাবের কারণেই এই সামারিটি দেওয়া হয়েছে। পারফরম্যান্স সংক্রান্ত কোনো দাবি বা অন্য ক্লায়েন্টের সাথে কোনো তুলনা করা হয়নি।