TypeScript SDK (@zinn-digital/sdk) प्रयोग गर्दै

@zinn-digital/sdk npm मा प्रकाशित गरिएको, Zinn Digital® API का लागि हाम्रो आधिकारिक TypeScript क्लाइन्ट हो। यसमा रहेको प्रत्येक पाथ, प्यारामिटर र प्रतिक्रिया उही OpenAPI स्पेसिफिकेसनबाट उत्पन्न गरिएको हो जसबाट API निर्माण गरिएको छ, र जब त्यो स्पेसिफिकेसन परिवर्तन हुन्छ तब स्वचालित रूपमा नयाँ संस्करण प्रकाशित हुन्छ। यो गाइडले यसलाई स्थापना गर्दछ, प्रमाणीकरण गर्दछ र तपाइँका पहिलो कलहरू गर्दछ।

स्थापना गर्नुहोस्

npm install @zinn-digital/sdk

यो fetch भएको कुनै पनि JavaScript रनटाइममा काम गर्दछ: Node.js, ब्राउजर र एज रनटाइमहरू। यसमा एउटा रनटाइम निर्भरता (dependency), openapi-fetch छ, र यो MIT-इजाजतपत्र प्राप्त छ।

API कुञ्जी सिर्जना गर्नुहोस्

आफ्नो ड्यासबोर्डको API कुञ्जीहरू पृष्ठ (app.zinndigital.com/api-keys) खोल्नुहोस् र कुञ्जी सिर्जना गर्नुहोस् थिच्नुहोस्। कुञ्जीलाई एउटा नाम दिनुहोस् र तपाईंको कोडलाई आवश्यक पर्ने अनुमतिहरू मात्र दिनुहोस् — उदाहरणका लागि साइटहरू सूचीकृत गर्न sites.view। कुञ्जी एक पटक मात्र देखाइन्छ; यसलाई वातावरण चर (environment variable) वा आफ्नो गोप्य भण्डार (secret store) मा भण्डारण गर्नुहोस्, स्रोत कोडमा कहिल्यै पनि होइन। तपाईं सोही पृष्ठमा जुनसुकै बेला कुञ्जी खारेज गर्न सक्नुहुन्छ।

होस्टिङ क्षेत्रहरू र योजनाहरू जस्ता सार्वजनिक क्याटलग एन्डपोइन्टहरूलाई कुनै पनि कुञ्जीको आवश्यकता पर्दैन।

तपाईंको पहिलो कलहरू

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 को अर्थ की (key) सँग एन्डपोइन्टलाई चाहिने अनुमति छैन — धेरै अनुमति भएको की पुन: प्रयोग गर्नुको सट्टा त्यो अनुमति भएको की सिर्जना गर्नुहोस्।

अब कहाँ जाने

• हाम्रो वेबसाइटको गाइड: zinndigital.com/developers/sdk-typescript
• प्रत्येक एन्डपोइन्ट, यसका प्यारामिटरहरू र यसको अनुमति: zinndigital.com/developers/api
• npm मा रहेको प्याकेज: npmjs.com/package/@zinn-digital/sdk