# SDK

> The typed TypeScript client for Node, the browser, and edge runtimes.

Source: https://gheima.ma/docs/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.

```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 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. It is async-iterable and walks every page for you. It isn't a promise, so don't await it directly. Iterate it, call .all() to collect everything, or call .page() for a single 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();
```

### Errors

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

- `GheimaAuthError`: 401: the key is missing, malformed, or revoked.
- `GheimaForbiddenError`: 403: authenticated, but the key's scope or your role doesn't allow it.
- `GheimaNotFoundError`: 404: resource not found.
- `GheimaConflictError`: 409: conflict, such as 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.

```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: Script deploys, tail logs, and manage resources from the terminal, from curl, or from typed TypeScript, all with one API key.

---

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