SDK

Le SDK TypeScript enveloppe l’API avec les types, les réessais et la pagination. Il est basé sur fetch et tourne sur Node 18+, le navigateur et les runtimes 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);
}

Ressources du SDK#

Le client expose un namespace par ressource. Méthodes principales :

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)

Pagination#

Les méthodes de liste renvoient un Paginator. Il est itérable de façon asynchrone et parcourt chaque page pour vous. Ce n’est pas une promesse : ne l’attendez pas directement avec await. Itérez-le, appelez .all() pour tout récupérer, ou .page() pour une seule 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();

Erreurs#

Les appels en échec lèvent une erreur typée qui étend GheimaError (avec status, code, message, details, requestId) :

GheimaAuthError

401 : clé manquante, malformée ou révoquée.

GheimaForbiddenError

403 : authentifié, mais la portée de la clé ou votre rôle ne le permet pas.

GheimaNotFoundError

404 : ressource introuvable.

GheimaConflictError

409 : conflit, par exemple un nom déjà utilisé.

GheimaValidationError

422 : entrée invalide. details liste les champs.

GheimaRateLimitError

429 : limite de débit atteinte. retryAfter donne le nombre de secondes à attendre.

GheimaServerError

5xx : échec côté serveur.

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