SDK

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

npm install @gheima/sdk

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() لصفحة واحدة.

// 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: عطل من جهة الخادم.

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;
}