Desarrolladores/SDK de TypeScript

SDK de Hostwolf Apps para JavaScript y TypeScript

@hostwolf/apps-sdk es el cliente tipado oficial de la API de Hostwolf Apps. Con él puedes desplegar y gestionar tus apps desde código: proyectos, aplicaciones, despliegues y registros, variables de entorno, bases de datos gestionadas, autoescalado, volúmenes y más.

npm install https://app.hostwolf.net/dl/hostwolf-apps-sdk-0.2.1.tgz

El SDK se sirve desde app.hostwolf.net en lugar del registro de npm. El comando de arriba lo añade a tu package.json como "@hostwolf/apps-sdk": "https://app.hostwolf.net/dl/hostwolf-apps-sdk-0.2.1.tgz", y lo importas como @hostwolf/apps-sdk. pnpm, yarn y bun aceptan la misma URL. Cada versión tiene su propia URL; consulta Versiones.

Funciona en Node 18+, Bun y Deno, y no tiene dependencias en tiempo de ejecución.

Inicio rápido#

Crea un token de API en la consola en Claves y tokens → Tokens de API y luego:

import { HostwolfApps } from '@hostwolf/apps-sdk';

const hw = new HostwolfApps({ token: process.env.HOSTWOLF_APPS_TOKEN! });

const server = (await hw.servers.purchased()).find((s) => s.kind === 'app' && s.status === 'ready')!;
const { uuid: project } = await hw.projects.create({ name: 'shop' });

const app = await hw.applications.createFromGit({
    project_uuid: project,
    environment_name: 'production',
    server_uuid: server.server_uuid!,
    git_repository: 'https://github.com/acme/shop',
    git_branch: 'main',
    build_pack: 'nixpacks',
    ports_exposes: '3000',
});
await hw.applications.setEnvs(app.uuid, { NODE_ENV: 'production' });

const deployment = await hw.deployAndWait(app.uuid);
console.log(deployment.status, await hw.applications.logs(app.uuid, { lines: 20 }));

Los recursos se identifican por su uuid. Los objetos de respuesta usan los nombres de campo propios de la API (snake_case), y sus tipos de TypeScript se exportan, p. ej. Application, Deployment y ManagedDatabase.

Opciones#

new HostwolfApps({
    token: '12|abc...',                              // required
    baseUrl: 'https://console.app.hostwolf.net',     // default
    timeoutMs: 30_000,                               // per request
    maxRetries: 2,                                   // 429s, and 502/503/504 on GET
    maxRetryWaitMs: 10_000,                          // longer Retry-After waits fail fast instead
    language: 'de',                                  // error messages in en, de, fr, es or fi
    fetch: customFetch,                              // optional
});

Proyectos y entornos#

Aplicaciones#

Las apps se ejecutan en tus servidores de aplicaciones. server_uuid es el campo server_uuid de servers.purchased() (o el uuid de servers.list()). Omite domains para obtener una dirección *.app.hostwolf.net generada.

Variables de entorno#

Los contenedores en ejecución ven las variables cambiadas tras el siguiente despliegue.

Despliegues#

const { deployment_uuid } = await hw.applications.deploy(app.uuid);
const done = await hw.deployments.wait(deployment_uuid!, {
    timeoutMs: 10 * 60_000,
    onStatus: (status) => console.log(status), // queued, in_progress, finished
});

wait y deployAndWait lanzan un HostwolfAppsError con el código deployment_failed (y las últimas líneas del registro en el mensaje), deployment_cancelled o timeout. Pasa throwOnFailure: false para recibir el despliegue fallido en su lugar.

Servidores#

Comprar y cancelar servidores solo es posible en la consola, así que un token de API nunca puede comprar un servidor.

Varios servidores#

Ejecuta copias de una app en varios de tus servidores de aplicaciones. Hostwolf hace el build de la imagen una vez, inicia una copia en cada servidor y reparte la carga entre ellas.

await hw.applications.addServer(app.uuid, otherServer.server_uuid!);
await hw.deployAndWait(app.uuid);
console.log(await hw.applications.destinations(app.uuid)); // primary + copies

removeDestination(appUuid, destinationUuid) vuelve a detener la copia en ese servidor.

Bases de datos gestionadas#

PostgreSQL, MySQL/MariaDB y Redis en servidores de bases de datos de Hostwolf, separados de tus servidores de aplicaciones, con TLS, copias de seguridad nocturnas fuera del servidor y recuperación a un momento concreto para PostgreSQL.

const plans = await hw.databases.catalog();             // engines, plans, pool sizes, regions, prices
const db = await hw.databases.create({ engine: 'postgres', plan: 'small', region: 'vultr:ams' });
await hw.databases.waitUntilReady(db.uuid);
await hw.databases.attach(db.uuid, app.uuid);           // DATABASE_URL (pooled) + DATABASE_DIRECT_URL
await hw.deployAndWait(app.uuid);

Una base de datos se factura por hora en tu suscripción de servidor desde el momento en que se crea. create envía una Idempotency-Key, así que una llamada repetida nunca crea una segunda base de datos; pasa la tuya con { idempotencyKey }.

connection(uuid) devuelve dos URLs. url pasa por el pooler de conexiones (PgBouncer en el 6432, ProxySQL en el 6033): úsala en tu app. direct_url llega directamente a la base de datos: úsala para migraciones, LISTEN/NOTIFY, ajustes de sesión y transacciones largas. Redis tiene una sola URL.

upgrade sin { confirm: true } no cambia nada: lanza un HostwolfAppsError con el código confirm_required, y error.quote contiene el nuevo precio mensual para que lo muestres antes.

Autoescalado#

const { policy, blocker, status } = await hw.autoscaling.get(app.uuid);
await hw.autoscaling.enable(app.uuid, { min_copies: 1, max_copies: 4, monthly_cap_usd: 40 });

El autoescalado añade servidores de aplicaciones cerca de tus visitantes cuando la CPU se mantiene alta, y los quita cuando baja. Los servidores añadidos se facturan por hora al precio normal, hasta monthly_cap_usd. blocker dice por qué aún no se puede activar (por ejemplo, no hay ninguna suscripción de servidor activa). Los campos que omitas conservan su valor; disable(uuid) lo desactiva. cities lista los ids de región que acepta allowed_cities para la app, con el precio por hora allí; servers.regions() lista todas las ciudades.

Volúmenes de almacenamiento#

Almacenamiento en bloque para tus servidores de aplicaciones y VPS: de 10 a 1000 GB, montado en /mnt/volume-<id> en el servidor y facturado por hora. Las llamadas que aumentan la factura necesitan { confirm: true }; sin él no cambian nada y lanzan el código confirm_required con el precio en error.quote.

const offer = await hw.volumes.offer(server.uuid, { sizeGb: 50 });   // sizes allowed here and the price
const volume = await hw.volumes.create(server.uuid, { size_gb: 50, autogrow_max_gb: 200 }, { confirm: true });
await hw.volumes.waitFor(volume.id);                                  // mounted in about a minute
await hw.volumes.resize(server.uuid, volume.id, 100, { confirm: true });

Cuando se elimina un servidor, sus volúmenes se desvinculan y se conservan 7 días, sin coste (kept_until); mientras tanto, vincula uno a otro servidor de la misma ciudad, o se eliminará.

Volúmenes de apps#

Equipos#

Paginación#

Las listas que la API pagina vienen de dos formas: un método devuelve una sola página, y un método all… devuelve un iterador asíncrono sobre todos los elementos. collect convierte un iterador en un array:

import { collect } from '@hostwolf/apps-sdk';

const deployments = await collect(hw.deployments.allForApplication(app.uuid), 100);
for await (const event of hw.teams.allAuditEvents({ action: 'deploy' })) console.log(event.description);

Errores#

Las llamadas fallidas lanzan un HostwolfAppsError.

import { HostwolfAppsError } from '@hostwolf/apps-sdk';
try {
    await hw.applications.createFromDockerfile({ project_uuid, server_uuid, dockerfile });
} catch (e) {
    if (e instanceof HostwolfAppsError && e.isValidation) console.log(e.errors); // { field: ['message'] }
    else throw e;
}

Tiene estas propiedades:

• status: el estado HTTP, o 0 para errores de red, tiempos de espera agotados y despliegues fallidos.
• code: un código corto como validation_failed, unauthenticated, forbidden, not_found, rate_limited, confirm_required, deployment_failed o timeout.
• quote: con confirm_required, el precio que ha calculado la API (muéstralo y luego vuelve a llamar con { confirm: true }).
• retryAfter: en un 429, los segundos que faltan para poder repetir la llamada. Las esperas cortas se reintentan por ti; las más largas fallan al momento con este campo definido.
• message: una descripción legible, incluidos los errores por campo.
• errors: errores por campo de un 422, como { field: ['message'] }.
• body: el cuerpo de la respuesta. Un 403 por algo que Hostwolf hace por ti (como añadir servidores) incluye un enlace docs.
• Indicadores rápidos: isNotFound, isRateLimited, isValidation, isUnauthorized e isConfirmRequired.

Peticiones directas#

Si un endpoint aún no tiene método, llámalo directamente:

await hw.http.get(`/applications/${uuid}/scheduled-tasks`);
await hw.http.post(`/applications/${uuid}/scheduled-tasks`, { name: 'cleanup', command: 'npm run cleanup', frequency: '0 3 * * *' });

Las rutas son relativas a /api/v1. Consulta la referencia de la API para ver todos los endpoints.

Versiones#

Para actualizar, instala la URL con la versión más nueva.

Licencia#

MIT