SDK TypeScript VergeOS (tsvergeos)

tsvergeos est un SDK TypeScript pour gérer VergeOS via l’API REST, offrant une interface typée, sans dépendance et compatible tree-shaking pour automatiser les VM, le réseau, le stockage, les locataires et le multi-site.

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é)

npm install @vergeio/tsvergeos

Avec pnpm / yarn / bun

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é)

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

Vérification du certificat SSL

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

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

Variables d'environnement

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

const client = await VergeClient.connectFromEnv();

Recommandé pour la production

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

// 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";

Services non enregistrés

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 :

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

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

État d’alimentation fiable

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 :

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 :

// 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 :

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

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

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

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

Gestion multi-site

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

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"]);

Requêtes multi-site

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 :

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

Types d’erreur disponibles

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 :

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