Saltar al contenido principal
Esta página documenta @squarecloud/api v4. Si estás actualizando desde la v3, lee primero la guía de migración v3 → v4.

​
Requisitos

​
Instalación

npm install @squarecloud/api

​
Instanciar el cliente

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

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

​
Constructor

ParámetroTipoObligatorioDescripción
apiKeystringSíTu clave de API de Square Cloud. El cliente lanzará un error si esto no es un string.

​
Módulos

El cliente expone toda la plataforma v2 a través de módulos dedicados. Cada módulo es una propiedad de la instancia de SquareCloudAPI.
PropiedadMóduloDocumentación
api.userUsuario autenticado, plan, apps y bases de datos propiasEsta página
api.applicationsListar, obtener, subir e inspeccionar aplicacionesGestionar aplicaciones
api.databasesCrear, obtener y gestionar bases de datosBases de datos
api.workspacesCrear, listar y gestionar workspacesWorkspaces
api.serviceEstado agregado de la plataformaEsta página
api.cacheCaché en memoria poblada por eventos del SDKEsta página

​
Obtener el usuario autenticado

api.user.get() devuelve una instancia de User que contiene los detalles de la cuenta, el plan actual, las aplicaciones propias y las bases de datos propias. 
const user = await api.user.get();

console.log(user.id);          // "abcdef0123456789abcdef01"
console.log(user.name);        // "John Doe"
console.log(user.email);       // "john@example.com"
console.log(user.locale);      // "en-US"
console.log(user.plan.name);   // "free" | "standard" | ...
console.log(user.createdAt);   // Date

console.log(user.applications); // Collection<string, BaseApplication>
console.log(user.databases);    // Collection<string, Database>
user.applications y user.databases son instancias de Collection (una subclase de Map). Itéralas como cualquier Map: 
for (const [id, app] of user.applications) {
    console.log(`${app.name} (${id}) — ${app.ram}MB ${app.language}`);
}

​
Obtener una sola aplicación

Usa api.applications.fetch(id) para recuperar una Application completamente poblada (o WebsiteApplication, cuando la app tiene un dominio de sitio web). 
const app = await api.applications.fetch("abc123def456abc123def456");

console.log(app.id, app.name, app.cluster, app.createdAt);

if (app.isWebsite()) {
    // acotado a WebsiteApplication — `.network` está disponible
    await app.network.purgeCache();
}
La sobrecarga heredada api.applications.get(id) todavía existe, pero devuelve la BaseApplication más ligera y solo se conserva por compatibilidad con versiones anteriores. Prefiere .fetch() para v4.

​
Listar el historial de snapshots (a nivel de cuenta)

const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");
Consulta Snapshots para más detalles sobre los payloads de snapshots.

​
Estado de la plataforma

api.service.status() expone el estado de salud agregado de la plataforma (los mismos datos que se muestran en la página de estado pública). 
const status = await api.service.status();

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // resumen legible para humanos
A diferencia de la mayoría de los endpoints v2, esta ruta no envuelve su payload en el sobre estándar { status, response }.

​
Caché del cliente

El cliente mantiene una caché en memoria que el SDK mantiene sincronizada a medida que realizas llamadas: 
api.cache.user;   // último User obtenido
// cada instancia de aplicación también expone app.cache.status / .logs / .snapshots
El SDK emite eventos tipados a los que puedes suscribirte: 
api.on("userUpdate", (previous, current) => {
    console.log("user changed:", current.name);
});

api.on("statusUpdate", (application, previous, current) => {
    console.log(`${application.name} → ${current.status}`);
});

api.on("logsUpdate", (application, previous, current) => {
    console.log(`new logs for ${application.name}`);
});

api.on("snapshotsUpdate", (application, previous, current) => {
    console.log(`${current.length} snapshots for ${application.name}`);
});

​
Manejo de errores

Las solicitudes fallidas lanzan un SquareCloudAPIError. El error expone una propiedad code estable sobre la que puedes hacer un switch para distinguir los modos de fallo. 
import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

try {
    const app = await api.applications.fetch("invalid-id");
} catch (err) {
    if (err instanceof SquareCloudAPIError) {
        console.error(err.code);    // e.g. "APP_NOT_FOUND"
        console.error(err.message);
    }
}