التثبيت والإعداد

تثبيت الحزمة

# npm
npm install @ithbatiam/sdk

# yarn
yarn add @ithbatiam/sdk

# pnpm
pnpm add @ithbatiam/sdk

المتطلبات

• Node.js 18+ للاستخدام على جانب الـ Server (يستخدم fetch الأصلي)
• TypeScript 5.0+ يُوصى به (الحزمة تتضمن Types مدمجة)
• أي متصفح حديث يدعم fetch للاستخدام على جانب الـ Client

تهيئة الـ Client

import { IthbatSDK } from '@ithbatiam/sdk';

const sdk = new IthbatSDK({
  tenantId: 'YOUR_TENANT_ID',
  basePath: 'https://api.ithbat.io/api/v1',
});

في معظم التطبيقات، أنشئ Instance واحد وصدّره كـ Singleton على مستوى الـ Module.

// lib/ithbat.ts
import { IthbatSDK } from '@ithbatiam/sdk';

export const sdk = new IthbatSDK({
  tenantId: process.env.ITHBAT_TENANT_ID!,
  basePath: process.env.ITHBAT_BASE_PATH ?? 'https://api.ithbat.io/api/v1',
});

خيارات التهيئة

الـ Constructor لـ IthbatSDK يقبل الخيارات التالية:

interface IthbatConfig {
  basePath: string;
  tenantId?: string;
  accessToken?: string;
  headers?: Record<string, string>;
  timeout?: number;
}

الخيار	النوع	الافتراضي	الوصف
basePath	string	—	مطلوب. الـ Base URL الكامل مع مسار الـ API، مثل https://api.ithbat.io/api/v1.
tenantId	string	—	UUID الخاص بالـ Tenant. يُرسل كـ Header X-Tenant-ID مع كل Request.
accessToken	string	—	Bearer Token مبدئي. يمكنك تعيينه لاحقًا عبر sdk.setAccessToken().
headers	Record<string, string>	—	Headers إضافية تُدمج مع كل Request.
timeout	number	30000	Request Timeout بالمللي ثانية.

Environment Variables

نوصي بتخزين الـ Tenant ID والـ Base Path في Environment Variables:

# .env
ITHBAT_TENANT_ID=3f8a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
ITHBAT_BASE_PATH=https://api.ithbat.io/api/v1

ثم هيّئ الـ Client:

import { IthbatSDK } from '@ithbatiam/sdk';

export const sdk = new IthbatSDK({
  basePath: process.env.ITHBAT_BASE_PATH!,
  tenantId: process.env.ITHBAT_TENANT_ID,
});

مصادقة M2M (Machine-to-Machine)

للعمليات الإدارية على جانب الـ Server، احصل على Token عبر Client Credentials باستخدام sdk.authenticate(). هذه الدالة تستدعي OAuth /token Endpoint وتطبّق الـ Access Token على Instance الـ SDK تلقائيًا:

import { IthbatSDK } from '@ithbatiam/sdk';

const sdk = new IthbatSDK({
  basePath: process.env.ITHBAT_BASE_PATH!,
  tenantId: process.env.ITHBAT_TENANT_ID,
});

await sdk.authenticate(
  process.env.ITHBAT_CLIENT_ID!,
  process.env.ITHBAT_CLIENT_SECRET!,
);

const users = await sdk.users.listUsers({ page: 1, limit: 25 });

تحذير

لا تكشف الـ Client Secret أبدًا على جانب الـ Client. استخدم Client Credentials فقط من سياق Server مثل Node.js API Route أو Background Worker.

إعداد TypeScript

الـ SDK يأتي مع TypeScript Declarations كاملة. لا حاجة لحزم @types إضافية.

أضف التالي لـ tsconfig.json إذا لم يكن موجودًا:

{
  "compilerOptions": {
    "target": "ES2020",
    "moduleResolution": "bundler",
    "strict": true
  }
}

الـ SDK يستخدم Export Conditions مع moduleResolution: "bundler". إذا كنت تستخدم إعدادًا قديمًا بـ "moduleResolution": "node"، استخدم CJS Build:

const { IthbatSDK } = require('@ithbatiam/sdk');

معالجة الأخطاء

جميع دوال SDK ترمي IthbatError. استخدمه لفحص تفاصيل الخطأ:

import { IthbatSDK, IthbatError } from '@ithbatiam/sdk';

try {
  await sdk.auth.login({ email: '[email protected]', password: 'wrong' });
} catch (error) {
  if (error instanceof IthbatError) {
    console.error(error.statusCode); // e.g., 401
    console.error(error.code);       // e.g., "INVALID_CREDENTIALS"
    console.error(error.message);    // Human-readable description
  }
}

يمكنك استخدام Helper Methods على الـ SDK لتصنيف الأخطاء بدون استيراد IthbatError مباشرة:

try {
  await sdk.users.createUser({ email: 'bad-email' });
} catch (error) {
  if (sdk.isValidationError(error)) {
    const fields = sdk.getValidationErrors(error);
    fields.forEach((f) => console.error(`${f.field}: ${f.message}`));
  } else if (sdk.isAuthError(error)) {
    window.location.href = '/login';
  }
}

Error Codes الشائعة:

Code	HTTP Status	المعنى
INVALID_CREDENTIALS	401	البريد الإلكتروني أو كلمة المرور غير صحيحة
ACCOUNT_LOCKED	423	الحساب مقفل بسبب محاولات تسجيل دخول فاشلة
ACCOUNT_SUSPENDED	403	الحساب موقوف بواسطة مسؤول
EMAIL_NOT_VERIFIED	403	لم يتم التحقق من البريد الإلكتروني
MFA_REQUIRED	200	نجح تسجيل الدخول لكن MFA Challenge مطلوب
VALIDATION_ERROR	400	فشل الـ Request Body في الـ Validation
NOT_FOUND	404	المورد المطلوب غير موجود
PERMISSION_DENIED	403	المُستدعي يفتقر للصلاحية المطلوبة
RATE_LIMITED	429	Requests كثيرة — انتظر وأعد المحاولة
NETWORK_ERROR	0	فشل إرسال الـ Request (offline، timeout، إلخ)