VergeOS TypeScript SDK (tsvergeos)

tsvergeos ist ein TypeScript-SDK zur Verwaltung von VergeOS über die REST API und bietet eine dependanzfreie, tree-shakeable, typisierte Schnittstelle zur Automatisierung von VMs, Netzwerken, Speicher, Mandanten und Multi-Site.

Übersicht

tsvergeos ist ein TypeScript-SDK zur Verwaltung der VergeOS-Infrastruktur über die REST-API. Es bietet eine Zero-Dependency-, tree-shakebare, vollständig typisierte Schnittstelle zur Automatisierung von VM-Lebenszyklus, Netzwerken, Speicher, Multi-Tenant-Operationen und Multi-Site-Verwaltung und ist damit ideal für Automatisierungsskripte, Tool-Entwicklung und Integrationen.

Hauptmerkmale

• Keine Abhängigkeiten: Nichts zu prüfen, nichts zu brechen
• Tree-Shakebar: Importiere nur die Dienste, die du verwendest; ungenutzte Dienste werden als Dead Code entfernt
• Vollständige Typabdeckung: Jede Ressource, jeder Parameter und jede Antwort ist mit TSDoc-Dokumentation typisiert
• 93 Dienste: Vollständige Abdeckung jedes VergeOS-API-Endpunkts
• Multi-Site integriert: Abfrage und Verwaltung mehrerer VergeOS-Deployments von einer einzigen SiteManager
• Plattformübergreifend: Funktioniert in Node.js 20+, Deno, Bun und modernen Browsern
• Filterung: OData-Filterunterstützung mit sowohl einem fließenden Filter Builder als auch einer funktionalen buildFilter Kurzschreibweise

Anforderungen

• Node.js 20+ (unterstützt auch Deno und Bun)
• VergeOS 6.x (API v4)

Installation

Über npm (empfohlen)

npm install @vergeio/tsvergeos

Mit pnpm / yarn / bun

pnpm add @vergeio/tsvergeos
# oder
yarn add @vergeio/tsvergeos
# oder
bun add @vergeio/tsvergeos

Authentifizierung

Das SDK unterstützt mehrere Authentifizierungsmethoden:

API-Schlüssel (empfohlen)

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

const client = await VergeClient.connect({
  host: "192.168.1.100",
  apiKey: "your-api-key",
  verifySsl: false, // für selbstsignierte Zertifikate
});

SSL-Zertifikatsprüfung

Setzen Sie verifySsl: false nur für Umgebungen mit selbstsignierten Zertifikaten. In Produktionsumgebungen mit gültigen Zertifikaten lassen Sie diesen Parameter weg oder setzen Sie ihn auf true.

Benutzername / Passwort

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

Umgebungsvariablen

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

const client = await VergeClient.connectFromEnv();

Empfohlen für die Produktion

Die Verwendung von Umgebungsvariablen hält Anmeldedaten aus Ihrem Quellcode heraus und erleichtert die Verwendung unterschiedlicher Anmeldedaten in verschiedenen Umgebungen.

Dienstregistrierung

Das SDK verwendet tree-shakebare Imports — Dienste werden über Side-Effect-Imports registriert, sodass ungenutzte Dienste aus deinem Bundle als Dead Code entfernt werden.

Drei Import-Ebenen

// 1. Standard: ~48 am häufigsten genutzte Dienste (VMs, Netzwerke, Mandanten, Speicher usw.)
import { VergeClient } from "@vergeio/tsvergeos";

// 2. Vollständig: alle 93 Dienste (Alarme, Update-Einstellungen, Speicherstufen usw.)
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/full";

// 3. Einzelne: genau die auswählen, die du brauchst
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/alarm";
import "@vergeio/tsvergeos/services/storage-tier";

Nicht registrierte Dienste

Der Standard-Import enthält nicht jeden Dienst. Wenn du auf einen Dienst zugreifst, der nicht registriert ist (z. B., client.alarms ohne ihn zu importieren), erhältst du undefined. Für Dashboards, Admin-Tools oder Backend-Skripte, bei denen die Bundle-Größe keine Rolle spielt, verwende import '@vergeio/tsvergeos/full' um alles zu registrieren.

Nur Typ-Importe

Typ-Imports haben unabhängig davon, welche Dienste registriert sind, keinen Einfluss auf die Bundle-Größe:

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

Verfügbare Ressourcen

Das SDK bietet Zugriff auf 93 Dienste, die die gesamte VergeOS-API abdecken:

Kategorie	Ressourcen
Compute	VMs, Laufwerke, Geräte, NICs, Maschinen-Snapshots, Statistiken
Netzwerk	Netzwerke, Regeln, Aliase, Adressen, Hosts, DNS-Zonen/-Einträge/-Ansichten
VPN	WireGuard-Schnittstellen und Peers, IPSec-Verbindungen und -Phasen
Speicher	Volumes, Volume-Snapshots, CIFS/NFS-Freigaben, Synchronisierungen, Browser, Speicherstufen
NAS	NAS-Dienste, Benutzer, Dateien
Mandanten	Mandanten, Knoten, Speicher, Snapshots, Layer 2
Rezepte	VM- und Mandanten-Rezepte, Instanzen, Kataloge, Repositories
Snapshots	Snapshot-Profile, Zeiträume, Cloud-Snapshots
Sites	API sites Dienst — eingehende/ausgehende Synchronisierungen, Zeiträume des Synchronisierungsprofils (getrennt vom SDKs SiteManager)
System	System, Cluster, Knoten, Einstellungen, Protokolle, Aufgaben
Überwachung	Alarme, Alarmtypen, Webhooks, Webhook-URLs
Auth	Benutzer, Gruppen, Mitglieder, Berechtigungen, API-Schlüssel
Tags	Tags, Kategorien, Mitglieder
Updates	Update-Einstellungen, Quellen, Pakete, Branches
Andere	Zertifikate, cloud-init, Ressourcengruppen

Anwendungsbeispiele

Virtuelle Maschinen verwalten

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

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

// Alle VMs auflisten
const vms = await client.vms.list();
for (const vm of vms) {
  console.log(`${vm.name}: ${vm.ram}MB RAM, ${vm.cpu_cores} cores`);
}

// Eine bestimmte VM abrufen
const vm = await client.vms.get(42);
const vmByName = await client.vms.getByName("web-server");

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

// Power-Operationen
await client.vms.powerOn(newVm.$key);
await client.vms.powerOff(newVm.$key); // geordnetes ACPI-Herunterfahren

// Eine VM aktualisieren
await client.vms.update(newVm.$key, { ram: 4096 });

// Eine VM löschen
await client.vms.delete(newVm.$key);

Zuverlässiger Energiezustand

Die powerstate Feld einer VM-Ressource wird von der API oft weggelassen. Für den maßgeblichen Live-Energiezustand frage den Machine-Status-Dienst ab:

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

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

Konsolenzugriff

getConsoleInfo() gibt Verbindungsdetails zum Öffnen einer direkten WebSocket-Konsole zu einer VM zurück. Es werden drei Authentifizierungsmethoden unterstützt — wähle je nachdem, wo die Konsole dargestellt wird:

// Browser-kompatibel: Token in WebSocket-URL eingebettet
const info = await client.vms.getConsoleInfo(42, {
  username: "admin",
  password: "secret",
});
if (info.isAvailable) {
  const rfb = new RFB(container, info.websocketUrl);
}

// Node / Deno / Bun: API-Schlüssel über Authorization-Header
const info = await client.vms.getConsoleInfo(42, { apiKey: "..." });
const ws = new WebSocket(info.websocketUrl, {
  headers: { Authorization: `Bearer ${info.apiKey}` },
});

Der Browser WebSocket Die API unterstützt keine benutzerdefinierten Header — verwende in Browsern Benutzername/Passwort oder ein bereits vorhandenes Token. Für eine Abkürzung ohne API-Aufruf zur Web-UI-Konsole verwende client.vms.getConsoleURL(42).

Ressourcen filtern

Das SDK unterstützt mehrere Filteransätze:

Fließender Filter-Builder

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

Funktionale Kurzschreibweise

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

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

Seitenauswahl und Feldauswahl

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

// Oder alle Seiten automatisch durchlaufen (asynchroner Generator)
for await (const vm of client.vms.listAll()) {
  console.log(vm.name);
}

Multi-Site-Verwaltung

Verwalte mehrere VergeOS-Deployments über einen einzigen Einstiegspunkt:

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

// Eine bestimmte Site abfragen
const eastVms = await manager.site("dc-east").vms.list();

// Leseabfragen über alle Sites verteilen
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}`);
}

// Nur an Sites mit einem bestimmten Tag verteilen
const prodVms = await manager.tagged("production").vms.list();

// Oder einen vorab erstellten VergeClient synchron registrieren (keine Versionsprüfung)
const existing = new VergeClient({ host: "10.0.3.1", apiKey: "key-edge" });
manager.addSite("edge-01", existing, ["edge"]);

Multi-Site-Abfragen

Die SiteManager verteilt Leseabfragen parallel über alle registrierten Sites und gibt aggregierte Ergebnisse zusammen mit etwaigen Site-spezifischen Fehlern zurück. Verwende manager.tagged(tag) um die Verteilung auf eine Teilmenge von Sites zu beschränken. Änderungen laufen immer über eine benannte Site (manager.site("dc-east").vms.create(...)); der standortübergreifende Proxy stellt nur list().

Fehlerbehandlung

Alle Fehler erben von VergeError mit typisierten Unterklassen und Type-Guard-Funktionen:

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

try {
  const vm = await client.vms.get(999);
} catch (err) {
  if (isNotFoundError(err)) {
    console.log("VM nicht gefunden");
  } else if (isAuthError(err)) {
    console.log("Authentifizierung fehlgeschlagen");
  } else if (isApiError(err)) {
    console.log(`API error ${err.statusCode}: ${err.message}`);
  }
}

Verfügbare Fehlertypen

Fehlerklasse	Beschreibung
VergeError	Basiserror für alle SDK-Fehler
ApiError	Jeder HTTP-Fehler der API
NotFoundError	Ressource nicht gefunden (404)
AuthError	Authentifizierungsfehler (401/403)
ConflictError	Ressourcenzustandskonflikt (409)
ValidationError	Ungültige Eingabe auf Client-Seite
UnsupportedVersionError	Serverversion zu alt
TaskError	Asynchrone Aufgabe fehlgeschlagen
TaskTimeoutError	Aufgabe überschritt die Wartezeit
SiteError	Fehler bei Multi-Site-Operation

Client-Konfiguration

Der vollständige Satz an Konfigurationsoptionen:

interface ClientConfig {
  host: string; // Server-Hostname oder URL
  apiKey?: string; // API-Schlüssel für Bearer-Authentifizierung
  username?: string; // Benutzername für die Basic-Authentifizierung
  password?: string; // Passwort für die Basic-Authentifizierung
  verifySsl?: boolean; // TLS-Prüfung (Standard: true)
  timeout?: number; // Anforderungs-Timeout in ms (Standard: 30000)
  retries?: number; // Wiederholungsversuche (Standard: 3)
  retryBackoff?: number; // Wartezeit zwischen Wiederholungen in ms (Standard: 1000)
  fetch?: typeof fetch; // Benutzerdefinierte fetch-Implementierung
  signal?: AbortSignal; // Abbruchsignal
}

Häufige Anwendungsfälle

• Infrastrukturautomatisierung: VMs, Netzwerke und Speicher programmatisch bereitstellen
• CI/CD-Integration: Testumgebungen in Pipelines erstellen und zerstören
• Überwachung und Berichterstellung: Ressourcenstatus abfragen und Bestandsberichte erstellen
• Backup-Automatisierung: Snapshots und Cloud-Backups planen und verwalten
• Multi-Tenant-Bereitstellung: Mandantenerstellung und Ressourcenzuweisung automatisieren
• Multi-Site-Orchestrierung: Verwaltung und Abfrage über mehrere VergeOS-Deployments hinweg

Dokumentation und Ressourcen

Für die vollständige Dokumentation, einschließlich der kompletten API-Referenz und detaillierter Anwendungsbeispiele, besuche das offizielle Repository:

• GitHub-Repository
• npm-Paket

Support

Wenn Sie auf Probleme stoßen oder Funktionswünsche haben, eröffnen Sie bitte ein Issue im GitHub-Repository:

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

Weitere Ressourcen

• TypeScript-Dokumentation
• VergeOS-API-Dokumentation
• Python SDK - Python-Alternative
• Go-SDK - Go-Alternative
• PowerShell-Modul - PowerShell-Alternative
• Terraform-Provider - Infrastruktur als Code