# SDK

> عميل TypeScript بأنواع كاملة لـ Node والمتصفّح وبيئات edge.

Source: https://gheima.ma/ar/docs/sdk

تغلّف حزمة TypeScript SDK واجهة البرمجة بالأنواع وإعادة المحاولة والترقيم. قائمة على fetch وتعمل على Node 18+ والمتصفّح وبيئات edge.

```bash
npm install @gheima/sdk
```

```typescript
import { GheimaClient } from '@gheima/sdk';

const gheima = new GheimaClient({
  apiKey: process.env.GHEIMA_API_KEY!,
  // baseUrl, timeoutMs (30000), maxRetries (2) are all optional
});

// Paginated lists are async-iterable
for await (const service of gheima.services.list()) {
  console.log(service.name, service.url);
}

// Create and deploy
const svc = await gheima.services.create({
  projectId: 'prj_1',
  name: 'web',
  repoUrl: 'https://github.com/me/app',
});
const { deploymentId } = await gheima.services.deploy(svc.id);

// Stream logs
for await (const entry of gheima.services.streamLogs(svc.id)) {
  console.log(entry.line);
}
```

### موارد الـ SDK

يعرض العميل namespace لكل مورد. أهم الدوال:

- `account`: get(), usage()
- `services`: list(), get(id), create(), update(id), delete(id), deploy(id), deployments(id), rollback(id, deploymentId), restart/pause/resume(id), scale(id), metrics(id), logs(id), streamLogs(id)
- `services.env`: list(id), set(id, key, value), remove(id, key)
- `databases`: list(), get(id), create(), delete(id), reveal(id), resetPassword(id), query(id, statement)
- `databases.snapshots / .branches`: list / create / restore|reset / delete (Postgres)
- `storage.buckets`: list(), get(id), create(name), delete(id), setPublic(id, isPublic), reveal(id)
- `storage.objects`: list(bucket, prefix?), presign(bucket, key, method?, expiresIn?), presignPut/presignGet, delete(bucket, key), rename(bucket, from, to)
- `projects`: list(), get(id), create({ name }), delete(id)
- `cron`: list(), get(id), create(), update(id), delete(id), runNow(id), toggle(id, enabled), runs(id)
- `domains`: list(serviceId), add(serviceId, domain), verify(domainId), remove(domainId)
- `alerts`: list(), create(), update(id), delete(id), events(id)
- `webhooks`: list(), get(id), create(), update(id), delete(id), test(id)
- `apiKeys`: list(), get(id), createKey(name, scopes?), revoke(id), delete(id)
- `activity / previews`: activity.list(); previews.list(), delete(id), toggleAutoCreate(serviceId, enabled)

### الترقيم

تُرجِع دوال القوائم كائن Paginator. يمكن المرور عليه بشكل غير متزامن، ويتنقّل بين كل الصفحات نيابةً عنك. ليس وعدًا (Promise)، فلا تستعمل await عليه مباشرةً. مُرّ عليه بحلقة، أو استدعِ ‎.all() لجمع كل العناصر، أو ‎.page() لصفحة واحدة.

```typescript
// one item at a time, across all pages
for await (const db of gheima.databases.list()) console.log(db.name);

// or collect them
const all = await gheima.services.list().all();

// or a single page
const { data, pagination } = await gheima.activity.list().page();
```

### الأخطاء

ترمي الاستدعاءات الفاشلة خطأً مكتوب النوع يمتدّ من GheimaError (مع status وcode وmessage وdetails وrequestId):

- `GheimaAuthError`: 401: المفتاح مفقود أو غير صالح الصيغة أو مُلغى.
- `GheimaForbiddenError`: 403: تمّت المصادقة، لكن صلاحية المفتاح أو دورك لا يسمح بالطلب.
- `GheimaNotFoundError`: 404: المورد غير موجود.
- `GheimaConflictError`: 409: تعارض، مثل اسم مستخدَم مسبقًا.
- `GheimaValidationError`: 422: إدخال غير صالح. يسرد details الحقول المعنية.
- `GheimaRateLimitError`: 429: تجاوزت حدّ الطلبات. يعطي retryAfter عدد الثواني قبل إعادة المحاولة.
- `GheimaServerError`: 5xx: عطل من جهة الخادم.

```typescript
import { GheimaRateLimitError, GheimaValidationError } from '@gheima/sdk';

try {
  await gheima.services.get('missing');
} catch (e) {
  if (e instanceof GheimaRateLimitError) console.log('retry after', e.retryAfter);
  else if (e instanceof GheimaValidationError) console.log(e.details);
  else throw e;
}
```

> Result: يمكنك برمجة النشر وتتبّع السجلات وإدارة الموارد من الطرفية، أو عبر curl، أو بشيفرة TypeScript محدّدة الأنواع، وكل ذلك بمفتاح API واحد.

---

All docs: https://gheima.ma/ar/docs.md