د TypeScript SDK (@zinn-digital/sdk) کارول

@zinn-digital/sdk د Zinn Digital® API لپاره زموږ رسمي TypeScript کلینټ دی، چې په npm کې خپور شوی دی. په دې کې هره لار، پیرامیټر او ځواب له ورته OpenAPI مشخصاتو څخه تولید شوی چې API ترې جوړ شوی، او هرکله چې دا مشخصات بدل شي، نو یوه نوې نسخه په اوتومات ډول خپریږي. دا لارښود دا نصبوي، تصدیق کوي او ستاسو لومړنۍ اړیکې نیسي.

نصب کول

npm install @zinn-digital/sdk

دا په هر هغه JavaScript رن‌ټایم کې کار کوي چې fetch لري: Node.js، براوزر او د ایج (edge) رن‌ټایمونه. دا د رن‌ټایم یوه انحصار (dependency) لري، openapi-fetch، او دا د MIT لخوا جواز لري.

د API یوه کیلي جوړه کړئ

د خپل ډشبورډ د د API کیلي‌ګانې پاڼه (app.zinndigital.com/api-keys) پرانیزئ او کیلي جوړه کړئ کېکاږئ. کیلي ته یو نوم ورکړئ او یوازې هغه اجازې وټاکئ چې ستاسو کوډ ورته اړتیا لري — د بېلګې په توګه د سایټونو لیست کولو لپاره sites.view. کیلي یوازې یو ځل ښودل کېږي؛ دا په یو چاپېریالي متحول (environment variable) یا په خپل پټ ذخیره‌تون کې خوندي کړئ، هیڅکله یې په سرچینه کوډ کې مه ږدئ. تاسو کولی شئ په ورته پاڼه کې هر وخت کیلي فسخه کړئ.

د عامه کټالوګ پای‌ټکي (endpoints)، لکه د کوربه‌توب سیمې او پلانونه، هیڅ ډول کیلي ته اړتیا نلري.

ستاسو لومړنۍ غوښتنې

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