SDK de VergeOS para TypeScript (tsvergeos)

tsvergeos es un SDK de TypeScript para administrar VergeOS a través de la API REST, que ofrece una interfaz tipada, sin dependencias y compatible con tree-shaking para automatizar VM, redes, almacenamiento, inquilinos y entornos multisitio.

Descripción general

tsvergeos es un SDK de TypeScript para gestionar la infraestructura de VergeOS a través de la API REST. Proporciona una interfaz sin dependencias, compatible con tree-shaking y completamente tipada para automatizar el ciclo de vida de las VM, la red, el almacenamiento, las operaciones multitenant y la gestión multisede, lo que lo hace ideal para scripts de automatización, desarrollo de herramientas e integraciones.

Características clave

• Sin dependencias: Nada que auditar, nada que romper
• Compatible con tree-shaking: Importa solo los servicios que uses; los servicios no utilizados se eliminan como código muerto
• Cobertura completa de tipos: Cada recurso, parámetro y respuesta está tipado con documentación TSDoc
• 93 servicios: Cobertura completa de cada endpoint de la API de VergeOS
• Multisitio integrado: Consulta y administra múltiples implementaciones de VergeOS desde un único SiteManager
• Multiplataforma: Funciona en Node.js 20+, Deno, Bun y navegadores modernos
• Filtrado: Compatibilidad con filtros OData tanto con un Filtro constructor fluido y un buildFilter atajo

Requisitos

• Node.js 20+ (también compatible con Deno y Bun)
• VergeOS 6.x (API v4)

Instalación

Desde npm (recomendado)

npm install @vergeio/tsvergeos

Usando pnpm / yarn / bun

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

Autenticación

El SDK admite múltiples métodos de autenticación:

Clave de API (recomendado)

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

const client = await VergeClient.connect({
  host: "192.168.1.100",
  apiKey: "tu-clave-api",
  verifySsl: false, // para certificados autofirmados
});

Verificación de certificado SSL

Establezca verifySsl: false solo para entornos con certificados autofirmados. Para entornos de producción con certificados válidos, omita este parámetro o establézcalo en true.

Nombre de usuario / contraseña

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

Variables de entorno

export VERGEOS_HOST=192.168.1.100
export VERGEOS_API_KEY=tu-clave-api
# Opcional:
export VERGEOS_VERIFY_SSL=false
export VERGEOS_TIMEOUT=60

const client = await VergeClient.connectFromEnv();

Recomendado para producción

Usar variables de entorno mantiene las credenciales fuera de su código fuente y facilita el uso de diferentes credenciales en distintos entornos.

Registro de servicios

El SDK usa importaciones compatibles con tree-shaking: los servicios se registran mediante importaciones con efectos secundarios, de modo que los servicios no utilizados se eliminan como código muerto de tu paquete.

Tres niveles de importación

// 1. Predeterminado: ~48 servicios más utilizados (VM, redes, inquilinos, almacenamiento, etc.)
import { VergeClient } from "@vergeio/tsvergeos";

// 2. Completo: los 93 servicios (alarmas, configuración de actualizaciones, niveles de almacenamiento, etc.)
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/full";

// 3. Individual: elige exactamente lo que necesitas
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/alarm";
import "@vergeio/tsvergeos/services/storage-tier";

Servicios no registrados

La importación predeterminada no incluye todos los servicios. Si accedes a un servicio que no está registrado (por ejemplo, client.alarms sin importarlo), obtendrás undefined. Para paneles, herramientas de administración o scripts de backend donde el tamaño del paquete no importa, usa import '@vergeio/tsvergeos/full' para registrar todo.

Importaciones solo de tipos

Las importaciones de tipos no tienen impacto en el tamaño del paquete, independientemente de qué servicios estén registrados:

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

Recursos disponibles

El SDK proporciona acceso a 93 servicios que cubren la API completa de VergeOS:

Categoría	Recursos
Computación	VM, unidades, dispositivos, NIC, instantáneas de máquina, estadísticas
Redes	Redes, reglas, alias, direcciones, hosts, zonas/registros/vistas DNS
VPN	Interfaces y peers de WireGuard, conexiones y fases de IPSec
Almacenamiento	Volúmenes, instantáneas de volúmenes, comparticiones CIFS/NFS, sincronizaciones, navegador, niveles de almacenamiento
NAS	Servicios NAS, usuarios, archivos
Inquilinos	Inquilinos, nodos, almacenamiento, instantáneas, Capa 2
Recetas	Recetas de VM e inquilinos, instancias, catálogos, repositorios
Instantáneas	Perfiles de instantáneas, períodos, instantáneas en la nube
Sitios	API sites servicio — sincronizaciones entrantes/salientes, períodos de perfil de sincronización (distintos del SiteManager)
Sistema	Sistema, clústeres, nodos, configuración, registros, tareas
Monitorización	Alarmas, tipos de alarma, webhooks, URL de webhook
Autenticación	Usuarios, grupos, miembros, permisos, claves de API
Etiquetas	Etiquetas, categorías, miembros
Actualizaciones	Configuración de actualizaciones, fuentes, paquetes, ramas
Otros	Certificados, cloud-init, grupos de recursos

Ejemplos de uso

Administración de máquinas virtuales

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

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

// Listar todas las VMs
const vms = await client.vms.list();
for (const vm of vms) {
  console.log(`${vm.name}: ${vm.ram}MB de RAM, ${vm.cpu_cores} núcleos`);
}

// Obtener una VM específica
const vm = await client.vms.get(42);
const vmByName = await client.vms.getByName("web-server");

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

// Operaciones de encendido
await client.vms.powerOn(newVm.$key);
await client.vms.powerOff(newVm.$key); // apagado ACPI ordenado

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

// Eliminar una VM
await client.vms.delete(newVm.$key);

Estado de energía confiable

La powerstate el campo de un recurso VM suele ser omitido por la API. Para obtener el estado de energía en vivo y autoritativo, consulta el servicio de estado de la máquina:

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

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

Acceso a la consola

getConsoleInfo() devuelve los detalles de conexión para abrir una consola WebSocket directa a una VM. Se admiten tres métodos de autenticación; elige según dónde se renderice la consola:

// Compatible con el navegador: token incrustado en la URL de 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: clave de API mediante el encabezado Authorization
const info = await client.vms.getConsoleInfo(42, { apiKey: "..." });
const ws = new WebSocket(info.websocketUrl, {
  headers: { Authorization: `Bearer ${info.apiKey}` },
});

El navegador WebSocket API no admite encabezados personalizados: usa nombre de usuario/contraseña o un token preexistente en navegadores. Para un atajo sin llamada a la API hacia la consola de la interfaz web, usa client.vms.getConsoleURL(42).

Recursos de filtrado

El SDK admite múltiples enfoques de filtrado:

Constructor fluido de filtros

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

Atajo funcional

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

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

Paginación y selección de campos

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

// O recorre automáticamente todas las páginas (generador asíncrono)
for await (const vm of client.vms.listAll()) {
  console.log(vm.name);
}

Gestión multisitio

Gestiona múltiples implementaciones de VergeOS desde un único punto de entrada:

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

// Consultar un sitio específico
const eastVms = await manager.site("dc-east").vms.list();

// Distribuir consultas de lectura entre todos los sitios
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}`);
}

// Distribuir solo a los sitios con una etiqueta determinada
const prodVms = await manager.tagged("production").vms.list();

// O registra sincrónicamente un VergeClient ya preparado (sin comprobación de versión)
const existing = new VergeClient({ host: "10.0.3.1", apiKey: "key-edge" });
manager.addSite("edge-01", existing, ["edge"]);

Consultas multisitio

La SiteManager distribuye consultas de lectura en paralelo entre todos los sitios registrados y devuelve resultados agregados junto con cualquier error por sitio. Usa manager.tagged(tag) para limitar la distribución a un subconjunto de sitios. Las mutaciones siempre pasan por un sitio con nombre (manager.site("dc-east").vms.create(...)); el proxy entre sitios expone solo list().

Manejo de errores

Todos los errores extienden VergeError con subclases tipadas y funciones de guardia de tipos:

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

try {
  const vm = await client.vms.get(999);
} catch (err) {
  if (isNotFoundError(err)) {
    console.log("VM no encontrada");
  } else if (isAuthError(err)) {
    console.log("La autenticación falló");
  } else if (isApiError(err)) {
    console.log(`Error de API ${err.statusCode}: ${err.message}`);
  }
}

Tipos de error disponibles

Clase de error	Descripción
VergeError	Error base para todos los errores del SDK
ApiError	Cualquier error HTTP de la API
NotFoundError	Recurso no encontrado (404)
AuthError	Fallo de autenticación (401/403)
ConflictError	Conflicto de estado del recurso (409)
ValidationError	Entrada no válida del lado del cliente
UnsupportedVersionError	Versión del servidor demasiado antigua
TaskError	La tarea asíncrona falló
TaskTimeoutError	La tarea superó el tiempo de espera
SiteError	Fallo en operación multisitio

Configuración del cliente

El conjunto completo de opciones de configuración:

interface ClientConfig {
  host: string; // Nombre de host o URL del servidor
  apiKey?: string; // Clave API para autenticación bearer
  username?: string; // Nombre de usuario para autenticación básica
  password?: string; // Contraseña para autenticación básica
  verifySsl?: boolean; // Verificación TLS (predeterminado: true)
  timeout?: number; // Tiempo de espera de la solicitud en ms (predeterminado: 30000)
  retries?: number; // Intentos de reintento (predeterminado: 3)
  retryBackoff?: number; // Espera entre reintentos en ms (predeterminado: 1000)
  fetch?: typeof fetch; // Implementación fetch personalizada
  signal?: AbortSignal; // Señal de cancelación
}

Casos de uso comunes

• Automatización de infraestructura: Aprovisione VMs, redes y almacenamiento mediante programación
• Integración CI/CD: Cree y destruya entornos de prueba en los pipelines
• Monitorización e informes: Consulte el estado de los recursos y genere informes de inventario
• Automatización de copias de seguridad: Programe y administre instantáneas y copias de seguridad en la nube
• Aprovisionamiento multitenencia: Automatice la creación de inquilinos y la asignación de recursos
• Orquestación multisitio: Gestiona y consulta varias implementaciones de VergeOS

Documentación y recursos

Para obtener documentación completa, incluida la referencia completa de la API y ejemplos de uso detallados, visita el repositorio oficial:

• Repositorio de GitHub
• Paquete npm

Soporte

Si encuentra problemas o tiene solicitudes de funciones, abra un issue en el repositorio de GitHub:

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

Recursos adicionales

• Documentación de TypeScript
• Documentación de la API de VergeOS
• Python SDK - Alternativa de Python
• Go SDK - Alternativa en Go
• Módulo de PowerShell - alternativa de PowerShell
• Proveedor de Terraform - infraestructura como código