# SDK

> Le client TypeScript typé pour Node, le navigateur et les runtimes edge.

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

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

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

```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();
```

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

```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: Scriptez vos déploiements, suivez les logs et gérez vos ressources depuis le terminal, avec curl ou en TypeScript typé, le tout avec une seule clé API.

---

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