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 قابلًا للتكرار بشكل غير متزامن — يمرّ على كل صفحة نيابةً عنك. ليس وعدًا، فلا تنتظره مباشرةً؛ كرّره، أو استدعِ ‎.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;
}