الدوال الإدارية

العمليات الإدارية تتطلب Access Token بالصلاحيات المناسبة. استخدم Client Credentials للحصول على Token من سياق Server.

معلومة

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

التهيئة بـ Client Credentials

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.authenticate(
  process.env.ITHBAT_CLIENT_ID!,
  process.env.ITHBAT_CLIENT_SECRET!,
);

sdk.setAccessToken(result.accessToken);

Pagination

جميع دوال العرض التي تُعيد قوائم تستخدم PagedResult<T>:

interface PagedResult<T> {
  items: T[];
  totalItems: number;
  totalPages: number;
  page: number;
  pageSize: number;
}

مرّر limit للتحكم بعدد النتائج لكل صفحة:

const result = await sdk.users.listUsers({ page: 1, limit: 25 });
console.log(result.totalItems);
result.items.forEach((user) => console.log(user.email));

إدارة المستخدمين

عرض المستخدمين

SDK: sdk.users.listUsers(params?)

REST: GET /api/v1/users — يتطلب user:read

const result = await sdk.users.listUsers({
  page: 1,
  limit: 25,
  search: 'jane',
  status: 'active',
});

console.log(result.totalItems);
result.items.forEach((user) => console.log(user.email));

Parameters:

الاسم	النوع	الوصف
`page`	`number`	رقم الصفحة (يبدأ من 1). الافتراضي: `1`.
`limit`	`number`	النتائج لكل صفحة. الافتراضي: `25`. الحد الأقصى: `100`.
`search`	`string`	بحث نصي حر عبر البريد والاسم الأول واسم العائلة.
`status`	`'active' \| 'suspended' \| 'locked'`	التصفية حسب حالة الحساب.
`roleId`	`string`	تصفية المستخدمين المعيّن لهم دور محدد.
`sort`	`string`	حقل الترتيب والاتجاه، مثل `createdAt:desc`.

Returns: PagedResult<UserResponse>

جلب مستخدم

SDK: sdk.users.getUser(userId)

REST: GET /api/v1/users/{id} — يتطلب user:read

const user = await sdk.users.getUser('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
console.log(user.displayName);
console.log(user.roles);

Returns: UserResponse

interface UserResponse {
  id: string;
  tenantId: string;
  email: string;
  firstName: string;
  fatherName: string;
  grandfatherName: string;
  familyName: string;
  displayName: string;
  status: 'active' | 'suspended' | 'locked';
  roles: string[];
  mfaEnabled: boolean;
  metadata?: Record<string, unknown>;
  externalIds?: Record<string, string>;
  lastLoginAt?: string;
  passwordChangedAt?: string;
  createdAt: string;
  updatedAt: string;
}

إنشاء مستخدم

SDK: sdk.users.createUser(params)

REST: POST /api/v1/users — يتطلب user:write

const user = await sdk.users.createUser({
  email: '[email protected]',
  firstName: 'New',
  familyName: 'User',
  password: 'TempPass123!',
  skipEmailVerification: true,
});

console.log(user.id);

Parameters:

الاسم	النوع	مطلوب	الوصف
`email`	`string`	نعم	يجب أن يكون فريدًا داخل الـ Tenant.
`firstName`	`string`	نعم
`familyName`	`string`	نعم
`password`	`string`	نعم	يجب أن يستوفي سياسة كلمة المرور الخاصة بالـ Tenant.
`fatherName`	`string`	لا
`grandfatherName`	`string`	لا
`skipEmailVerification`	`boolean`	لا	إذا `true`، البريد يُوسم كمحقق فورًا. الافتراضي: `false`.

تحديث مستخدم

SDK: sdk.users.updateUser(userId, params)

REST: PUT /api/v1/users/{id} — يتطلب user:write

جميع الحقول اختيارية. تُحدَّث فقط الحقول التي توفرها.

const updated = await sdk.users.updateUser(
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  {
    firstName: 'Janet',
    familyName: 'Smith',
  }
);

حذف مستخدم

SDK: sdk.users.deleteUser(userId)

REST: DELETE /api/v1/users/{id} — يتطلب user:write

يحذف المستخدم نهائيًا مع جميع بياناته المرتبطة. هذا الإجراء لا يمكن التراجع عنه.

await sdk.users.deleteUser('a1b2c3d4-e5f6-7890-abcd-ef1234567890');

إيقاف وإعادة تفعيل مستخدم

SDK: sdk.users.suspendUser(userId) / sdk.users.reactivateUser(userId)

REST: POST /api/v1/users/{id}/suspend / POST /api/v1/users/{id}/reactivate — يتطلب user:write

الإيقاف يُبطل الـ Sessions النشطة فورًا ويمنع تسجيل الدخول الجديد. إعادة التفعيل تستعيد الوصول بدون إعادة تعيين Credentials.

await sdk.users.suspendUser('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
await sdk.users.reactivateUser('a1b2c3d4-e5f6-7890-abcd-ef1234567890');

فتح حساب مقفل

SDK: sdk.users.unlockUser(userId)

REST: POST /api/v1/users/{id}/unlock — يتطلب user:write

يفتح حسابًا قُفل بسبب محاولات تسجيل دخول فاشلة كثيرة.

await sdk.users.unlockUser('a1b2c3d4-e5f6-7890-abcd-ef1234567890');

إدارة الأدوار

عرض الأدوار

SDK: sdk.roles.listRoles()

REST: GET /api/v1/roles — يتطلب role:read

const result = await sdk.roles.listRoles();
result.items.forEach((role) => console.log(role.name, role.permissions));

جلب دور

SDK: sdk.roles.getRole(roleId)

REST: GET /api/v1/roles/{id} — يتطلب role:read

const role = await sdk.roles.getRole('r9b8a7c6-...');

إنشاء دور

SDK: sdk.roles.createRole(params)

REST: POST /api/v1/roles — يتطلب role:write

const role = await sdk.roles.createRole({
  name: 'Support Agent',
  description: 'Can view users and read audit logs',
  permissions: ['user:read', 'audit:read'],
});

console.log(role.id);

تحديث دور

SDK: sdk.roles.updateRole(roleId, params)

REST: PUT /api/v1/roles/{id} — يتطلب role:write

await sdk.roles.updateRole('r9b8a7c6-...', {
  permissions: ['user:read', 'audit:read', 'user:write'],
});

حذف دور

SDK: sdk.roles.deleteRole(roleId)

REST: DELETE /api/v1/roles/{id} — يتطلب role:write

await sdk.roles.deleteRole('r9b8a7c6-...');

تعيين دور لمستخدم

SDK: sdk.roles.assignRole(userId, roleId)

REST: POST /api/v1/users/{id}/roles — يتطلب role:write

await sdk.roles.assignRole(
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  'r9b8a7c6-d5e4-3f21-bcde-fa0987654321'
);

إزالة دور من مستخدم

SDK: sdk.roles.removeRole(userId, roleId)

REST: DELETE /api/v1/users/{id}/roles/{roleId} — يتطلب role:write

await sdk.roles.removeRole(
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  'r9b8a7c6-d5e4-3f21-bcde-fa0987654321'
);

إدارة المجموعات

عرض المجموعات

SDK: sdk.groups.listGroups()

REST: GET /api/v1/groups — يتطلب group:read

const result = await sdk.groups.listGroups();

إنشاء مجموعة

SDK: sdk.groups.createGroup(params)

REST: POST /api/v1/groups — يتطلب group:write

const group = await sdk.groups.createGroup({
  name: 'Engineering',
  description: 'All engineering staff',
});

إضافة عضو لمجموعة

SDK: sdk.groups.addMember(groupId, userId)

REST: POST /api/v1/groups/{id}/members — يتطلب group:write

await sdk.groups.addMember(
  'g1a2b3c4-...',
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
);

إزالة عضو من مجموعة

SDK: sdk.groups.removeMember(groupId, userId)

REST: DELETE /api/v1/groups/{id}/members/{uid} — يتطلب group:write

await sdk.groups.removeMember('g1a2b3c4-...', 'a1b2c3d4-...');

تعيين دور لمجموعة

SDK: sdk.groups.addRole(groupId, roleId)

REST: POST /api/v1/groups/{id}/roles — يتطلب group:write

جميع أعضاء المجموعة يرثون الدور المعيّن.

await sdk.groups.addRole('g1a2b3c4-...', 'r9b8a7c6-...');

سجلات التدقيق

عرض أحداث التدقيق

SDK: sdk.audit.listEvents(params?)

REST: GET /api/v1/audit/events — يتطلب audit:read

const result = await sdk.audit.listEvents({
  page: 1,
  limit: 50,
  userId: 'a1b2c3d4-...',
  startDate: '2026-02-01T00:00:00Z',
  endDate: '2026-02-28T23:59:59Z',
});

result.items.forEach((event) => {
  console.log(event.action, event.actorEmail, event.createdAt);
});

عرض سجل تسجيل الدخول

SDK: sdk.audit.listLogins(params?)

REST: GET /api/v1/audit/logins — يتطلب audit:read

const logins = await sdk.audit.listLogins({ page: 1, limit: 25 });

عرض نشاط المستخدم

SDK: sdk.audit.getUserActivity(userId)

REST: GET /api/v1/audit/users/{userId}/activity — يتطلب audit:read

const activity = await sdk.audit.getUserActivity('a1b2c3d4-...');

إدارة الـ Sessions

جلب Sessions مستخدم

SDK: sdk.sessions.listForUser(userId)

REST: GET /api/v1/users/{id}/sessions — يتطلب user:read

const sessions = await sdk.sessions.listForUser('a1b2c3d4-...');
sessions.forEach((s) => console.log(s.id, s.ipAddress, s.createdAt));

إلغاء جميع Sessions المستخدم

SDK: sdk.sessions.revokeAllForUser(userId)

REST: DELETE /api/v1/users/{id}/sessions — يتطلب user:write

يُجبر المستخدم على تسجيل الدخول مجددًا على جميع الأجهزة.

await sdk.sessions.revokeAllForUser('a1b2c3d4-...');

التهيئة بـ Client Credentials​

Pagination​

إدارة المستخدمين​

عرض المستخدمين​

جلب مستخدم​

إنشاء مستخدم​

تحديث مستخدم​

حذف مستخدم​

إيقاف وإعادة تفعيل مستخدم​

فتح حساب مقفل​

إدارة الأدوار​

عرض الأدوار​

جلب دور​

إنشاء دور​

تحديث دور​

حذف دور​

تعيين دور لمستخدم​

إزالة دور من مستخدم​

إدارة المجموعات​

عرض المجموعات​

إنشاء مجموعة​

إضافة عضو لمجموعة​

إزالة عضو من مجموعة​

تعيين دور لمجموعة​

سجلات التدقيق​

عرض أحداث التدقيق​

عرض سجل تسجيل الدخول​

عرض نشاط المستخدم​

إدارة الـ Sessions​

جلب Sessions مستخدم​

إلغاء جميع Sessions المستخدم​