TypeScript SDK (@zinn-digital/sdk) ব্যবহার করা

@zinn-digital/sdk হলো Zinn Digital® API-এর জন্য আমাদের অফিসিয়াল TypeScript ক্লায়েন্ট, যা npm-এ প্রকাশিত। এর প্রতিটি পাথ, প্যারামিটার এবং রেসপন্স তৈরি করা হয়েছে সেই একই OpenAPI স্পেসিফিকেশন থেকে যা দিয়ে এই API তৈরি, এবং যখনই সেই স্পেসিফিকেশন পরিবর্তিত হয় তখনই স্বয়ংক্রিয়ভাবে একটি নতুন সংস্করণ প্রকাশিত হয়। এই নির্দেশিকাটি এটি ইনস্টল করে, প্রমাণীকরণ করে এবং আপনার প্রথম কলগুলো সম্পন্ন করে।

ইনস্টল করুন

npm install @zinn-digital/sdk

এটি fetch থাকা যেকোনো JavaScript রানটাইমে কাজ করে: Node.js, ব্রাউজার এবং edge রানটাইম। এর একটি রানটাইম নির্ভরতা রয়েছে, openapi-fetch, এবং এটি MIT-লাইসেন্সপ্রাপ্ত।

একটি API কী তৈরি করুন

আপনার ড্যাশবোর্ডের API কীগুলি পৃষ্ঠাটি খুলুন (app.zinndigital.com/api-keys) এবং একটি কী তৈরি করুন চাপুন। কী-টির একটি নাম দিন এবং শুধুমাত্র সেই অনুমতিগুলি দিন যা আপনার কোডের প্রয়োজন — উদাহরণস্বরূপ সাইটগুলির তালিকা দেখতে sites.view। কী-টি একবারই দেখানো হয়; এটি একটি এনভায়রনমেন্ট ভেরিয়েবলে বা আপনার সিক্রেট স্টোরে সংরক্ষণ করুন, কখনই সোর্স কোডে নয়। আপনি একই পৃষ্ঠায় যেকোনো সময় একটি কী প্রত্যাহার করতে পারেন।

পাবলিক ক্যাটালগ এন্ডপয়েন্টগুলি, যেমন হোস্টিং অঞ্চল এবং পরিকল্পনাগুলির জন্য কোনো কী-এর প্রয়োজন হয় না।

আপনার প্রথম কলগুলি

import { createApiClient } from "@zinn-digital/sdk";

const api = createApiClient({ baseUrl: "https://api.zinndigital.com" });

// Public catalogue endpoints need no key.
const { data: regions } = await api.GET("/v1/catalog/regions");
console.log(regions?.data.map((r) => r.slug));

// Everything else uses a per-organisation API key.
api.use({
  onRequest({ request }) {
    request.headers.set("Authorization", `Bearer ${process.env.ZINN_API_KEY}`);
  },
});

const { data, error } = await api.GET("/v1/sites", { params: { query: { limit: 5 } } });
if (error) throw new Error(error.error.message);
for (const site of data.data) console.log(site.name, site.status);

এটি ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts দিয়ে রান করুন। প্রথম লাইনটি হোস্টিং অঞ্চলগুলি প্রিন্ট করে, তারপরে প্রতিটি সাইটের জন্য একটি করে লাইন।

আপনার নিজস্ব কোডের জন্য টাইপসমূহ

স্কিমা টাইপগুলি এক্সপোর্ট করা হয়েছে, যাতে আপনার নিজস্ব ফাংশনগুলি API-এর শেপগুলি ব্যবহার করতে পারে:

import type { components } from "@zinn-digital/sdk";

type Site = components["schemas"]["Site"];
type DnsRecord = components["schemas"]["DnsRecord"];

ভুল বানানযুক্ত পাথ, প্যারামিটার বা ক্ষেত্র নীরবে ভুল কাজ করা কোনো অনুরোধ হওয়ার পরিবর্তে একটি কম্পাইল ত্রুটি তৈরি করে।

ত্রুটিসমূহ

প্রতিটি কল { data, error, response } প্রদান করে। একটি অ-2xx প্রতিক্রিয়ায় data অনির্ধারিত থাকে এবং error হলো API-এর ত্রুটির খাম: error.error.code, মানুষের পাঠযোগ্য error.error.message এবং বৈধতা যাচাইয়ের ব্যর্থতার জন্য প্রতিটি ক্ষেত্রকে চিহ্নিত করে error.error.details। একটি 403-এর অর্থ হলো এন্ডপয়েন্টের প্রয়োজনীয় অনুমতি এই কি-তে নেই — অতিরিক্ত ক্ষমতাসম্পন্ন কি পুনরায় ব্যবহার করার পরিবর্তে নির্দিষ্ট ওই অনুমতিসহ একটি কি তৈরি করুন।

পরবর্তী গন্তব্য

• আমাদের ওয়েবসাইটের নির্দেশিকা: zinndigital.com/developers/sdk-typescript
• প্রতিটি এন্ডপয়েন্ট, এর প্যারামিটার এবং এর অনুমতি: zinndigital.com/developers/api
• npm-এ থাকা প্যাকেজ: npmjs.com/package/@zinn-digital/sdk