> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/fr/integrations-et-api/typescript-sdk.md).

# SDK TypeScript VergeOS (tsvergeos)

## Vue d’ensemble

tsvergeos est un SDK TypeScript pour gérer l’infrastructure VergeOS via l’API REST. Il fournit une interface sans dépendances, compatible avec l’élimination du code mort, entièrement typée, pour automatiser le cycle de vie des VM, le réseau, le stockage, les opérations multi-locataires et la gestion multi-site, ce qui le rend idéal pour les scripts d’automatisation, le développement d’outils et les intégrations.

## Fonctionnalités clés

* **Aucune dépendance**: Rien à auditer, rien à casser
* **Compatible avec l’élimination du code mort**: Importez uniquement les services que vous utilisez ; les services inutilisés sont éliminés du code mort
* **Couverture complète des types**: Chaque ressource, paramètre et réponse est typé avec une documentation TSDoc
* **93 services**: Couverture complète de tous les points de terminaison de l’API VergeOS
* **Prise en charge multi-site intégrée**: Interrogez et gérez plusieurs déploiements VergeOS depuis un seul `SiteManager`
* **Multiplateforme**: Fonctionne avec Node.js 20+, Deno, Bun et les navigateurs modernes
* **Filtrage**: Prise en charge des filtres OData avec à la fois un `Filter` constructeur fluide et un `buildFilter` raccourci

## Prérequis

* Node.js 20+ (prend aussi en charge Deno et Bun)
* VergeOS 6.x (API v4)

## Installation

### Depuis npm (recommandé)

```bash
npm install @vergeio/tsvergeos
```

### Avec pnpm / yarn / bun

```bash
pnpm add @vergeio/tsvergeos
# ou
yarn add @vergeio/tsvergeos
# ou
bun add @vergeio/tsvergeos
```

## Authentification

Le SDK prend en charge plusieurs méthodes d'authentification :

### Clé API (recommandé)

```typescript
import { VergeClient } from "@vergeio/tsvergeos";

const client = await VergeClient.connect({
  host: "192.168.1.100",
  apiKey: "your-api-key",
  verifySsl: false, // pour les certificats auto-signés
});
```

{% hint style="info" %}
**Vérification du certificat SSL**
{% endhint %}

Définissez `verifySsl: false` uniquement pour les environnements avec des certificats auto-signés. Pour les environnements de production avec des certificats valides, omettez ce paramètre ou définissez-le sur `true`.

### Nom d’utilisateur / mot de passe

```typescript
const client = await VergeClient.connect({
  host: "192.168.1.100",
  username: "admin",
  password: "secret",
});
```

### Variables d'environnement

```bash
export VERGEOS_HOST=192.168.1.100
export VERGEOS_API_KEY=your-api-key
# Facultatif :
export VERGEOS_VERIFY_SSL=false
export VERGEOS_TIMEOUT=60
```

```typescript
const client = await VergeClient.connectFromEnv();
```

{% hint style="success" %}
**Recommandé pour la production**
{% endhint %}

L'utilisation de variables d'environnement permet de garder les identifiants hors de votre code source et facilite l'utilisation d'identifiants différents selon les environnements.

## Enregistrement des services

Le SDK utilise des imports compatibles avec l’élimination du code mort — les services sont enregistrés via des imports à effet de bord, de sorte que les services inutilisés sont supprimés de votre bundle.

### Trois niveaux d’importation

```typescript
// 1. Par défaut : ~48 services les plus utilisés (VM, réseaux, locataires, stockage, etc.)
import { VergeClient } from "@vergeio/tsvergeos";

// 2. Complet : les 93 services (alarmes, paramètres de mise à jour, niveaux de stockage, etc.)
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/full";

// 3. Individuel : choisissez exactement ce dont vous avez besoin
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/alarm";
import "@vergeio/tsvergeos/services/storage-tier";
```

{% hint style="warning" %}
**Services non enregistrés**
{% endhint %}

L’import par défaut n’inclut pas tous les services. Si vous accédez à un service qui n’est pas enregistré (par exemple, `client.alarms` sans l’importer), vous obtiendrez `undefined`. Pour les tableaux de bord, les outils d’administration ou les scripts backend où la taille du bundle n’a pas d’importance, utilisez `import '@vergeio/tsvergeos/full'` pour tout enregistrer.

### Imports de type uniquement

Les imports de type n’ont aucun impact sur le bundle, quel que soit le nombre de services enregistrés :

```typescript
import type {
  VM,
  Alarm,
  Network,
  Tenant,
  Volume,
} from "@vergeio/tsvergeos/types";
```

## Ressources disponibles

Le SDK fournit un accès à 93 services couvrant l’intégralité de l’API VergeOS :

| Catégorie        | Ressources                                                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Calcul**       | VM, lecteurs, périphériques, NIC, instantanés de machine, statistiques                                                        |
| **Réseautage**   | Réseaux, règles, alias, adresses, hôtes, zones/enregistrements/vues DNS                                                       |
| **VPN**          | Interfaces et pairs WireGuard, connexions et phases IPSec                                                                     |
| **Stockage**     | Volumes, instantanés de volume, partages CIFS/NFS, synchronisations, navigateur, niveaux de stockage                          |
| **NAS**          | Services NAS, utilisateurs, fichiers                                                                                          |
| **Locataires**   | Locataires, nœuds, stockage, instantanés, couche 2                                                                            |
| **Recettes**     | Recettes de VM et de locataires, instances, catalogues, dépôts                                                                |
| **Instantanés**  | Profils d’instantanés, périodes, instantanés cloud                                                                            |
| **Sites**        | API `sites` service — synchronisations entrantes/sortantes, périodes de profil de synchronisation (distinct du `SiteManager`) |
| **Système**      | Système, clusters, nœuds, paramètres, journaux, tâches                                                                        |
| **Surveillance** | Alarmes, types d’alarme, webhooks, URL de webhook                                                                             |
| **Auth**         | Utilisateurs, groupes, membres, permissions, clés API                                                                         |
| **Tags**         | Tags, catégories, membres                                                                                                     |
| **Mises à jour** | Paramètres de mise à jour, sources, packages, branches                                                                        |
| **Autre**        | Certificats, cloud-init, groupes de ressources                                                                                |

## Exemples d'utilisation

### Gestion des machines virtuelles

```typescript
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/vm";

const client = await VergeClient.connect({
  host: "192.168.1.100",
  apiKey: "your-api-key",
});

// Lister toutes les VM
const vms = await client.vms.list();
for (const vm of vms) {
  console.log(`${vm.name}: ${vm.ram} Mo de RAM, ${vm.cpu_cores} cœurs`);
}

// Obtenir une VM spécifique
const vm = await client.vms.get(42);
const vmByName = await client.vms.getByName("web-server");

// Créer une VM
const newVm = await client.vms.create({
  name: "test-vm",
  machine_type: "q35",
  ram: 2048,
  cpu_cores: 2,
  os_family: "linux",
});

// Opérations d’alimentation
await client.vms.powerOn(newVm.$key);
await client.vms.powerOff(newVm.$key); // arrêt ACPI gracieux

// Mettre à jour une VM
await client.vms.update(newVm.$key, { ram: 4096 });

// Supprimer une VM
await client.vms.delete(newVm.$key);
```

{% hint style="info" %}
**État d’alimentation fiable**
{% endhint %}

Le `powerstate` champ d’une ressource VM est souvent omis par l’API. Pour obtenir l’état d’alimentation en temps réel faisant autorité, interrogez le service d’état de la machine :

```typescript
import "@vergeio/tsvergeos/services/machine-status";

const status = await client.machineStatuses.getByMachine(newVm.$key);
console.log(status.running, status.status);
```

### Accès à la console

`getConsoleInfo()` renvoie les détails de connexion pour ouvrir une console WebSocket directe vers une VM. Trois méthodes d’authentification sont prises en charge — choisissez selon l’endroit où la console est rendue :

```typescript
// Compatible navigateur : jeton intégré dans l’URL WebSocket
const info = await client.vms.getConsoleInfo(42, {
  username: "admin",
  password: "secret",
});
if (info.isAvailable) {
  const rfb = new RFB(container, info.websocketUrl);
}

// Node / Deno / Bun : clé API via l’en-tête Authorization
const info = await client.vms.getConsoleInfo(42, { apiKey: "..." });
const ws = new WebSocket(info.websocketUrl, {
  headers: { Authorization: `Bearer ${info.apiKey}` },
});
```

L’API `WebSocket` du navigateur ne prend pas en charge les en-têtes personnalisés — utilisez un nom d’utilisateur/mot de passe ou un jeton existant dans les navigateurs. Pour un raccourci sans appel API vers la console de l’interface web, utilisez `client.vms.getConsoleURL(42)`.

### Filtrage des ressources

Le SDK prend en charge plusieurs approches de filtrage :

{% tabs %}
{% tab title="Constructeur de filtres fluide" %}

```typescript
import { Filter } from "@vergeio/tsvergeos";

const filter = new Filter()
  .eq("status", "running")
  .like("name", "web*")
  .gt("cpu_cores", 2)
  .build();

const vms = await client.vms.list({ filter });
```

{% endtab %}

{% tab title="Raccourci fonctionnel" %}

```typescript
import { buildFilter } from "@vergeio/tsvergeos";

const vms = await client.vms.list({
  filter: buildFilter({
    status: "running",
    name: "web*",
    cpu_cores: { gt: 2 },
  }),
});
```

{% endtab %}

{% tab title="Pagination et sélection des champs" %}

```typescript
const page = await client.vms.list({
  limit: 10,
  offset: 20,
  sort: "-created",
  fields: ["name", "status", "ram"],
});

// Ou parcourez automatiquement toutes les pages (générateur asynchrone)
for await (const vm of client.vms.listAll()) {
  console.log(vm.name);
}
```

{% endtab %}
{% endtabs %}

### Gestion multi-site

Gérez plusieurs déploiements VergeOS depuis un point d’entrée unique :

```typescript
import { SiteManager } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/vm";

const manager = new SiteManager();

await manager.addSite({
  name: "dc-east",
  host: "10.0.1.1",
  apiKey: "key-east",
  tags: ["production"],
});

await manager.addSite({
  name: "dc-west",
  host: "10.0.2.1",
  apiKey: "key-west",
  tags: ["production"],
});

// Interroger un site spécifique
const eastVms = await manager.site("dc-east").vms.list();

// Répartir les requêtes de lecture sur tous les sites
const allSiteVms = await manager.all.vms.list();
// → { data: SiteResource<VM>[], errors: SiteError[] }

for (const item of allSiteVms.data) {
  console.log(`${item.site}: ${item.resource.name}`);
}

// Répartir uniquement vers les sites portant un tag donné
const prodVms = await manager.tagged("production").vms.list();

// Ou enregistrez synchroniquement un VergeClient déjà créé (aucune vérification de version)
const existing = new VergeClient({ host: "10.0.3.1", apiKey: "key-edge" });
manager.addSite("edge-01", existing, ["edge"]);
```

{% hint style="success" %}
**Requêtes multi-site**
{% endhint %}

Le `SiteManager` répartit les requêtes de lecture sur tous les sites enregistrés en parallèle et renvoie des résultats agrégés ainsi que les erreurs éventuelles par site. Utilisez `manager.tagged(tag)` pour limiter la diffusion à un sous-ensemble de sites. Les mutations passent toujours par un site nommé (`manager.site("dc-east").vms.create(...)`); le proxy inter-sites n’expose que `list()`.

## Gestion des erreurs

Toutes les erreurs héritent de `VergeError` avec des sous-classes typées et des fonctions de garde de type :

```typescript
import {
  isNotFoundError,
  isAuthError,
  isApiError,
  isValidationError,
} from "@vergeio/tsvergeos";

try {
  const vm = await client.vms.get(999);
} catch (err) {
  if (isNotFoundError(err)) {
    console.log("VM introuvable");
  } else if (isAuthError(err)) {
    console.log("Échec de l’authentification");
  } else if (isApiError(err)) {
    console.log(`Erreur API ${err.statusCode} : ${err.message}`);
  }
}
```

{% hint style="info" %}
**Types d’erreur disponibles**
{% endhint %}

| Classe d’erreur           | Description                                   |
| ------------------------- | --------------------------------------------- |
| `VergeError`              | Erreur de base pour toutes les erreurs du SDK |
| `ApiError`                | Toute erreur HTTP de l’API                    |
| `NotFoundError`           | Ressource introuvable (404)                   |
| `AuthError`               | Échec d’authentification (401/403)            |
| `ConflictError`           | Conflit d’état de la ressource (409)          |
| `ValidationError`         | Entrée client invalide                        |
| `UnsupportedVersionError` | Version du serveur trop ancienne              |
| `TaskError`               | Échec de la tâche asynchrone                  |
| `TaskTimeoutError`        | La tâche a dépassé le délai d’attente         |
| `SiteError`               | Échec d’une opération multi-site              |

## Configuration du client

L’ensemble complet des options de configuration :

```typescript
interface ClientConfig {
  host: string; // Nom d’hôte ou URL du serveur
  apiKey?: string; // Clé API pour l’authentification Bearer
  username?: string; // Nom d’utilisateur pour l’authentification basique
  password?: string; // Mot de passe pour l’authentification basique
  verifySsl?: boolean; // Vérification TLS (par défaut : true)
  timeout?: number; // Délai d’attente de la requête en ms (par défaut : 30000)
  retries?: number; // Nombre de tentatives (par défaut : 3)
  retryBackoff?: number; // Délai entre les nouvelles tentatives en ms (par défaut : 1000)
  fetch?: typeof fetch; // Implémentation fetch personnalisée
  signal?: AbortSignal; // Signal d’annulation
}
```

## Cas d'utilisation courants

* **Automatisation de l'infrastructure**: Provisionner des VM, des réseaux et du stockage par programmation
* **Intégration CI/CD**: Créer et détruire des environnements de test dans les pipelines
* **Surveillance et reporting**: Interroger l'état des ressources et générer des rapports d'inventaire
* **Automatisation des sauvegardes**: Planifier et gérer les instantanés et les sauvegardes cloud
* **Provisionnement multi-locataire**: Automatiser la création des locataires et l'allocation des ressources
* **Orchestration multi-site**: Gérez et interrogez plusieurs déploiements VergeOS

## Documentation et ressources

Pour une documentation complète, y compris la référence API intégrale et des exemples d’utilisation détaillés, consultez le dépôt officiel :

* [Dépôt GitHub](https://github.com/verge-io/tsvergeos)
* [Package npm](https://www.npmjs.com/package/@vergeio/tsvergeos)

## Support

Si vous rencontrez des problèmes ou avez des demandes de fonctionnalités, veuillez ouvrir un ticket sur le dépôt GitHub :

<https://github.com/verge-io/tsvergeos/issues>

## Ressources supplémentaires

* [Documentation TypeScript](https://www.typescriptlang.org/docs/)
* [Documentation de l'API VergeOS](/knowledge-base/fr/automation-api/verge-api-guide.md)
* [SDK Python](/automate-protect-and-extend/fr/integrations-et-api/python-sdk.md) - Alternative Python
* [SDK Go](/automate-protect-and-extend/fr/integrations-et-api/go-sdk.md) - Alternative Go
* [Module PowerShell](/automate-protect-and-extend/fr/integrations-et-api/powershell-module.md) - alternative PowerShell
* [Fournisseur Terraform](/automate-protect-and-extend/fr/integrations-et-api/terraform-provider.md) - Infrastructure as code


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/automate-protect-and-extend/fr/integrations-et-api/typescript-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.