SDK de JavaScript: inicio rápido y cliente

Esta página documenta @squarecloud/api v6, una reescritura del SDK. ¿Vienes de la v5? Lee la guía de migración v5 → v6.

Requisitos

Node.js 22 o más reciente, Deno, Bun o un entorno edge. El SDK solo necesita fetch, FormData, Blob y web streams.
Una clave de API (consulta Clave de API y scopes).

El paquete incluye builds ESM y CommonJS, no tiene dependencias en tiempo de ejecución e incluye sus propios tipos de TypeScript: ya no necesitas @squarecloud/api-types.

Instalación

npm
pnpm
yarn
bun
deno

npm install @squarecloud/api

pnpm add @squarecloud/api

yarn add @squarecloud/api

bun add @squarecloud/api

deno add npm:@squarecloud/api

Clave de API y scopes

Crea una clave en squarecloud.app/account/security. El SDK la envía tal cual en el encabezado Authorization (sin el prefijo Bearer). Una clave puede limitarse a scopes (apps:read, apps:deploy, apps:control, ai:chat, …) y a aplicaciones o bases de datos concretas:

Una llamada fuera de esos límites lanza un SquareCloudAPIError con 403 MISSING_SCOPE o RESOURCE_NOT_ALLOWED.
Los métodos de listado (account.me(), apps.statusAll(), …) solo devuelven los recursos que la clave puede ver.
Una clave desconocida, revocada o caducada da 401 ACCESS_DENIED.

Mantén la clave en el servidor. El SDK también funciona en el navegador, pero eso expondría la clave a todos los visitantes.

Los ejemplos leen la clave de la variable de entorno SQUARECLOUD_API_KEY. Defínela en la terminal donde los ejecutes:

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

Crear el cliente

TypeScript / ESM
CommonJS

import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!);

const { user, applications } = await api.account.me();
console.log(`Hi ${user.name}, you have ${applications.length} apps`);

const { SquareCloudAPI } = require("@squarecloud/api");

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY);

El primer ejemplo imprime el nombre de tu cuenta y el número de aplicaciones que la clave puede ver:

Hi Jane, you have 3 apps

Una clave vacía o compuesta solo por espacios lanza un TypeError en el constructor, antes de cualquier petición.

Opciones

import { BASE_URL, SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!, {
    baseUrl: BASE_URL, // "https://api.squarecloud.app/v2" (default)
    timeoutMs: 30_000,
    maxRetries: 2,
    userAgent: "my-bot/1.0",
    fetch, // any fetch-compatible function (proxy, tracing, tests)
});

Opción	Valor por defecto	Descripción
`baseUrl`	`https://api.squarecloud.app/v2`	URL base de la API. Se elimina una `/` final. También se exporta como `BASE_URL`.
`timeoutMs`	`30000`	Timeout por intento, que cubre toda la respuesta. Consulta Timeouts.
`maxRetries`	`2`	Reintentos solo de fallos seguros (hasta 3 intentos). Un valor negativo cuenta como `0`. Consulta Reintentos.
`userAgent`	`squarecloud-sdk-js/<version>`	Reemplaza todo el encabezado `User-Agent`.
`fetch`	el `fetch` global	Un `fetch` personalizado para proxies, trazas o tests.

La clave de API se guarda como una propiedad normal del objeto cliente. No hagas console.log del cliente ni lo serialices.

Módulos

Propiedad	Cubre	Página
`api.account`	`me()`, `snapshots({ scope })`	Cuenta y Snapshots
`api.service`	`status()`	Estado de la plataforma
`api.apps`	Obtener, eliminar, estado, ciclo de vida, logs, métricas, dominios, balanceadores de carga	Gestión de aplicaciones
`api.apps.create` / `commit`	Subidas	Commit y subida
`api.apps.files`	Gestor de archivos	Gestión de archivos
`api.apps.envs`	Variables de entorno	Variables de entorno
`api.apps.deploys`	Deploys por webhook y por GitHub App	Deploys
`api.apps.network`	Analíticas, logs, DNS, dominio personalizado, caché	Red
`api.apps.realtime`	Logs y estado en vivo	Tiempo real
`api.apps.snapshots` / `api.databases.snapshots` / `api.downloadSnapshot`	Copias de seguridad	Snapshots
`api.databases`	Bases de datos gestionadas	Bases de datos
`api.workspaces`	Workspaces, miembros y aplicaciones compartidas	Workspaces
`api.ai`	`chat()`	IA

Los únicos exports en tiempo de ejecución son SquareCloudAPI, SquareCloudAPIError y BASE_URL. Todos los demás exports (App, RuntimeStats, ErrorCode, …) son tipos:

import type { App, Snapshot } from "@squarecloud/api";

Convenciones

Primero el id, de vuelta datos planos

Todos los métodos reciben el id del recurso como primer argumento y devuelven datos planos (sin clases ni caché). Los nombres de los campos son los de la propia API (created_at, version_id, lastModified, joinedAt, netIO, …), así que la referencia de la API se aplica tal cual.

Las mutaciones se resuelven en void, salvo que la API devuelva datos (envs.*, deploys.setWebhook, deploys.linkGithubApp, databases.resetCredentials y los métodos create).
Un resultado de tipo string nunca es undefined: es "" cuando la API no envía nada.
Las listas llegan completas en una sola llamada: no hay paginación.

Los métodos son arrow functions, así que puedes desestructurarlos:

const { restart, logs } = api.apps;

await restart(appId);
console.log(await logs(appId));

Aplicaciones de workspace

Todo appId acepta también la forma compuesta <appId>-<workspaceId> para actuar sobre una aplicación compartida contigo a través de un workspace. workspaces.get() y workspaces.list() devuelven ids sin procesar; el id compuesto lo construyes tú:

await api.apps.restart(`${appId}-${workspaceId}`);

Los ids se codifican

Los ids en la ruta de la URL se codifican con percent-encoding. Un id vacío, . o .. llegaría a otra ruta, así que falla localmente con INVALID_ID (estado 0) antes de enviar nada. Las rutas de workspace envían sus ids en el cuerpo: ahí, el INVALID_ID (400) viene del servidor.

Fechas

Los argumentos start y end (consulta Red) aceptan un string ISO 8601 o un Date. Las fechas de las respuestas se mantienen tal como las envía la API (strings ISO, o milisegundos Unix donde la API los usa).

Timeouts

Llamada	Timeout
Cualquier otra llamada	`timeoutMs` (30 s) por intento
Llamadas que el servidor mantiene abiertas: `start`/`stop`/`restart` de aplicaciones, `start`/`stop` de bases de datos, `databases.create`, `create`/`restore` de snapshots, `ai.chat`	Al menos 120 s (gana un `timeoutMs` mayor)
Subidas (`apps.create`, `apps.commit`), `files.write` por encima de 1 MiB, `downloadSnapshot`	Ninguno: pasa un `signal` para cancelar
`apps.realtime`	Solo hasta que llegan los encabezados de la respuesta

Un timeoutMs de 0 o menos, Infinity o >= 2^31 desactiva todos los timeouts, incluidos los mínimos de 120 s. Solo cinco métodos aceptan un AbortSignal: apps.create, apps.commit, files.write, apps.realtime y downloadSnapshot.

const controller = new AbortController();
setTimeout(() => controller.abort(), 60_000);

await api.apps.commit(appId, "./build.zip", { signal: controller.signal });

Una llamada abortada se rechaza con el reason del signal, no con un SquareCloudAPIError. Un bucle de realtime() abortado simplemente termina.

Cuenta

api.account.me() devuelve el usuario autenticado junto con las aplicaciones y bases de datos que la clave puede ver.

const { user, applications, databases } = await api.account.me();

console.log(user.id, user.name, user.email, user.plan.name);
console.log(user.plan.memory); // { limit, available, used } in MB
console.log(user.plan.duration ? new Date(user.plan.duration) : "never expires");

Campo	Descripción
`user`	`id`, `name`, `email`, `locale`, `created_at` y `plan` (`name`, `memory`, `duration`: el instante en ms Unix en que el plan caduca, `null` si nunca caduca)
`applications`	Array de `{ id, name, desc?, ram, lang, domain?, custom?, cluster, created_at }`
`databases`	Array de `{ id, name, ram, type, cluster, created_at }`

api.account.snapshots({ scope }) lista todos los snapshots de la cuenta: consulta Snapshots.

Estado de la plataforma

api.service.status() devuelve el estado público de la plataforma. La ruta no necesita una clave válida, pero el cliente sigue exigiendo una que no esté vacía.

const status = await api.service.status();

console.log(status.status); // "online" | "degraded" | "unknown"
console.log(status.message);

for (const [name, service] of Object.entries(status.services ?? {})) {
    console.log(name, service.status); // "operational" | "degraded" | "outage" | "maintenance" | "unknown"
}

unknown significa que la propia comprobación no pudo ejecutarse: no es una prueba de una caída.

Próximos pasos

Gestión de aplicaciones

Estado, ciclo de vida, logs y métricas.

Errores

Clase de error, reintentos y límites de tasa.

Introducción a la API

URL base, autenticación y una primera solicitud.

Inicio rápido de la CLI

Haz deploy y gestiona aplicaciones desde la terminal.

CLI

VS Code

SDKs

SDK de JavaScript: inicio rápido y cliente

Requisitos

Instalación

Clave de API y scopes

Crear el cliente

Opciones

Módulos

Convenciones

Primero el id, de vuelta datos planos

Aplicaciones de workspace

Los ids se codifican

Fechas

Timeouts

Cuenta

Estado de la plataforma

Próximos pasos

Gestión de aplicaciones

Errores

Introducción a la API

Inicio rápido de la CLI

​Requisitos

​Instalación

​Clave de API y scopes

​Crear el cliente

​Opciones

​Módulos

​Convenciones

​Primero el id, de vuelta datos planos

​Aplicaciones de workspace

​Los ids se codifican

​Fechas

​Timeouts

​Cuenta

​Estado de la plataforma

​Próximos pasos

Gestión de aplicaciones

Errores

Introducción a la API

Inicio rápido de la CLI

Requisitos

Instalación

Clave de API y scopes

Crear el cliente

Opciones

Módulos

Convenciones

Primero el id, de vuelta datos planos

Aplicaciones de workspace

Los ids se codifican

Fechas

Timeouts

Cuenta

Estado de la plataforma

Próximos pasos