استخدام TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk هو عميل TypeScript الرسمي الخاص بنا لـ Zinn Digital® API، والمنشور على npm. يتم إنشاء كل مسار ومَعلمة واستجابة فيه من نفس مواصفات OpenAPI التي تم بناء واجهة برمجة التطبيقات منها، ويتم نشر إصدار جديد تلقائيًا كلما تغيرت تلك المواصفات. يقوم هذا الدليل بتثبيته، والمصادقة عليه، وإجراء مكالماتك الأولى.

التثبيت

npm install @zinn-digital/sdk

يعمل في أي بيئة تشغيل JavaScript تدعم fetch: مثل 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. يطبع السطر الأول مناطق الاستضافة، ثم سطرًا واحدًا لكل موقع.

أنواع لرمزك الخاص

يتم تصدير أنواع المخططات، بحيث يمكن لوظائفك الخاصة استخدام أشكال واجهة برمجة التطبيقات:

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

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

إن المسار أو المعلمة أو الحقل المكتوب بشكل غير صحيح يُعد خطأ في الترجمة البرمجية بدلاً من كونه طلباً يُنفذ الإجراء الخاطئ بصمت.

الأخطاء

يُرجع كل استدعاء { data, error, response }. في حالة الاستجابة غير التابعة للفئة 2xx، تكون data غير محددة ويكون error هو غلاف خطأ واجهة برمجة التطبيقات: 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