SDK

The TypeScript SDK wraps the API with types, retries, and pagination. It’s fetch-based and runs on Node 18+, the browser, and edge runtimes.

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 resources#

The client exposes one namespace per resource. Key methods:

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#

List methods return a Paginator that is async-iterable — it walks every page for you. It isn’t a promise, so don’t await it directly; iterate it, or call .all() to collect everything, or .page() for a single 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();

Errors#

Failed calls throw a typed error extending GheimaError (with status, code, message, details, requestId):

GheimaAuthError

401 — missing, malformed, or revoked key.

GheimaForbiddenError

403 — authenticated but not permitted (scope/role).

GheimaNotFoundError

404 — resource not found.

GheimaConflictError

409 — conflict, e.g. a name already in use.

GheimaValidationError

422 — invalid input; details lists the fields.

GheimaRateLimitError

429 — rate limited; retryAfter gives the seconds to wait.

GheimaServerError

5xx — server-side failure.

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