> 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/es/integraciones-y-api/typescript-sdk.md).

# SDK de VergeOS para TypeScript (tsvergeos)

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

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

### Usando pnpm / yarn / bun

```bash
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)

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

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

{% hint style="info" %}
**Verificación de certificado SSL**
{% endhint %}

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

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

### Variables de entorno

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

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

{% hint style="success" %}
**Recomendado para producción**
{% endhint %}

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

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

{% hint style="warning" %}
**Servicios no registrados**
{% endhint %}

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:

```typescript
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

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

{% hint style="info" %}
**Estado de energía confiable**
{% endhint %}

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:

```typescript
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:

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

{% tabs %}
{% tab title="Constructor fluido de filtros" %}

```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="Atajo funcional" %}

```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="Paginación y selección de campos" %}

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

{% endtab %}
{% endtabs %}

### Gestión multisitio

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

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

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

{% hint style="success" %}
**Consultas multisitio**
{% endhint %}

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:

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

{% hint style="info" %}
**Tipos de error disponibles**
{% endhint %}

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

```typescript
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](https://github.com/verge-io/tsvergeos)
* [Paquete npm](https://www.npmjs.com/package/@vergeio/tsvergeos)

## 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](https://www.typescriptlang.org/docs/)
* [Documentación de la API de VergeOS](/knowledge-base/es/automation-api/verge-api-guide.md)
* [Python SDK](/automate-protect-and-extend/es/integraciones-y-api/python-sdk.md) - Alternativa de Python
* [Go SDK](/automate-protect-and-extend/es/integraciones-y-api/go-sdk.md) - Alternativa en Go
* [Módulo de PowerShell](/automate-protect-and-extend/es/integraciones-y-api/powershell-module.md) - alternativa de PowerShell
* [Proveedor de Terraform](/automate-protect-and-extend/es/integraciones-y-api/terraform-provider.md) - infraestructura como código


---

# 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/es/integraciones-y-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.