انتقل إلى المحتوى الرئيسي

TypeScript SDK

حزمة Ithbat IAM TypeScript SDK (@ithbatiam/sdk) هي أسرع طريقة لدمج Ithbat IAM في تطبيق JavaScript أو TypeScript. تغلّف الـ REST API الكامل بواجهة typed تعتمد على Promises، فتركّز على تطبيقك بدل التعامل مع تفاصيل HTTP.

ما يوفره SDK​

المصادقة على جانب الـ Client — تسجيل المستخدمين، والتعامل مع تدفقات تسجيل الدخول (بريد إلكتروني/كلمة مرور، MFA Challenge)، وإدارة الـ Refresh Tokens وتسجيل الخروج. الـ IthbatSDK آمن للاستخدام في بيئة المتصفح والـ Node.js.

العمليات الإدارية — إنشاء وإدارة المستخدمين والأدوار والمجموعات والـ Tenants والـ Sessions وسجلات التدقيق من سياق Server باستخدام Service Account Token عبر Client Credentials.

TypeScript Types كاملة — كل Request Body وResponse وError Type منمَّط بالكامل.

البيئات المدعومة​

البيئةملاحظات
Node.js 18+دعم كامل. يستخدم fetch API الأصلي.
المتصفح (الحديث)دعم كامل عبر fetch الأصلي. الـ Tokens تُخزَّن في الذاكرة افتراضيًا.

التثبيت​

npm install @ithbatiam/sdk
# or
yarn add @ithbatiam/sdk
# or
pnpm add @ithbatiam/sdk

راجع دليل التثبيت لتعليمات الإعداد الكاملة.

مثال سريع​

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

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

const result = await sdk.auth.login({
  email: '[email protected]',
  password: 'SecurePass123!',
});

if (result.accessToken) {
  sdk.setAccessToken(result.accessToken);
  const me = await sdk.users.me();
  console.log(`Hello, ${me.displayName}`);
}

بعد استدعاء sdk.auth.login()، مرّر الـ Access Token عبر sdk.setAccessToken() ليُرفق تلقائيًا مع الـ Requests اللاحقة.

نطاقات SDK​

النطاقالغرض
sdk.authتسجيل الدخول، التسجيل، تسجيل الخروج، إعادة تعيين كلمة المرور، تحديث الـ Token، المستخدم الحالي
sdk.mfaإعداد MFA، التحقق، Backup Codes، SMS
sdk.usersإدارة المستخدمين (عرض، إنشاء، تحديث، حذف، إيقاف، تعيين الأدوار)
sdk.rolesإدارة الأدوار والصلاحيات
sdk.groupsإدارة المجموعات
sdk.tenantsإدارة الـ Tenants
sdk.sessionsإدارة الـ Sessions
sdk.auditاستعلامات سجل التدقيق
معلومة

الـ Namespaces مسطّحة — لا يوجد تداخل .admin. مثلاً: sdk.users.listUsers() وليس sdk.admin.users.list().

Instance Methods​

Methodالوصف
setAccessToken(token)تعيين الـ Bearer Token للـ Requests اللاحقة.
setTenantId(id)تعيين أو تغيير الـ Tenant ID المُرسل كـ X-Tenant-ID.
authenticate(clientId, clientSecret, scope?)الحصول على Access Token عبر Client Credentials وتطبيقه تلقائيًا.
isTokenExpired()تُعيد true إذا كان الـ Access Token الحالي منتهيًا أو على وشك الانتهاء (60 ثانية).
isAuthError(error)تُعيد true إذا كان الخطأ هو Response بـ 401.
isValidationError(error)تُعيد true إذا كان الخطأ هو فشل Validation بـ 400 مع تفاصيل الحقول.
getValidationErrors(error)ترجع مصفوفة أخطاء الـ Validation على مستوى الحقول.
destroy()تنظيف Instance الـ 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
  }
}

الموارد​