Cliente

Esta página documenta o @squarecloud/api v5. Se você está migrando da v4, leia primeiro o guia de migração v4 → v5. Vindo da v3, veja o guia de migração v3 → v4.

Requisitos

Node.js 20.0.0 ou superior
Uma chave de API válida — solicite uma no Dashboard da Square Cloud

Instalação

npm
yarn
pnpm

npm install @squarecloud/api

yarn add @squarecloud/api

pnpm add @squarecloud/api

Instanciando o cliente

TypeScript
JavaScript (ESM)
JavaScript (CommonJS)

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

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

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

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

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

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

Construtor

Parâmetro	Tipo	Obrigatório	Descrição
`apiKey`	`string`	Sim	Sua chave de API da Square Cloud. O cliente lança um erro se o valor não for uma string.

Módulos

O cliente expõe toda a plataforma v2 por meio de módulos dedicados. Cada módulo é uma propriedade da instância SquareCloudAPI.

Propriedade	Módulo	Documentação
`api.user`	Usuário autenticado, plano, apps e bancos próprios	Esta página
`api.applications`	Listar, buscar, enviar e inspecionar aplicações	Gerenciando aplicações
`api.databases`	Criar, buscar e gerenciar bancos de dados	Bancos de dados
`api.workspaces`	Criar, listar e gerenciar workspaces	Workspaces
`api.service`	Status agregado da plataforma	Esta página
`api.cache`	Cache em memória atualizado por eventos do SDK	Esta página

Obtendo o usuário autenticado

api.user.get() retorna uma instância de User contendo os dados da conta, o plano atual, as aplicações e os bancos pertencentes ao usuário.

const user = await api.user.get();

console.log(user.id);          // "abcdef0123456789abcdef01"
console.log(user.name);        // "João da Silva"
console.log(user.email);       // "joao@example.com"
console.log(user.locale);      // "pt-BR"
console.log(user.plan.name);   // ex.: "standard"
console.log(user.plan.duration); // duração do plano, ex.: "monthly"
console.log(user.plan.memory);   // { limit: 2048, available: 512, used: 1536 } (MB)
console.log(user.createdAt);   // Date

console.log(user.applications); // Collection<string, BaseApplication>
console.log(user.databases);    // Collection<string, Database>

user.applications e user.databases são instâncias de Collection (uma subclasse de Map). Itere normalmente:

for (const [id, app] of user.applications) {
    console.log(`${app.name} (${id}) — ${app.ram}MB ${app.language}`);
}

Buscando uma aplicação específica

Use api.applications.fetch(id) para obter uma Application (ou WebsiteApplication, quando a aplicação possui domínio web) totalmente populada.

const app = await api.applications.fetch("abc123def456abc123def456");

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

if (app.isWebsite()) {
    // tipo refinado para WebsiteApplication — `.network` está disponível
    await app.network.purgeCache();
}

A sobrecarga legada api.applications.get(id) ainda existe, mas retorna o BaseApplication mais simples e é mantida apenas por compatibilidade. Prefira .fetch() na v5.

Listando histórico de snapshots da conta

const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");

Veja Snapshots para detalhes do payload.

Status da plataforma

api.service.status() expõe o status agregado da plataforma (mesmos dados da página pública de status).

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

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // resumo legível

Diferente da maioria dos endpoints v2, esta rota não envolve o payload no envelope padrão { status, response }.

Cache do cliente

O cliente mantém um cache em memória que o SDK mantém sincronizado:

api.cache.user;   // último User buscado
// cada aplicação expõe também app.cache.status / .logs / .snapshots

O SDK emite eventos tipados aos quais você pode se inscrever:

api.on("userUpdate", (previous, current) => {
    console.log("usuário alterado:", current.name);
});

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

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

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

Tratamento de erros

Requisições que falham lançam SquareCloudAPIError. O erro expõe uma propriedade code estável para você diferenciar os tipos de falha.

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

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

Códigos de erro (APIErrorCode)

APIErrorCode é uma const/union exportada pelo SDK (reexportada de @squarecloud/api-types) que lista todos os valores que err.code pode assumir. A v5 renomeou vários códigos por consistência; os nomes antigos são mantidos como aliases de tipo depreciados, mas o SDK agora lança apenas os novos nomes.

Antigo (alias depreciado)	Novo
`ID_INVALID`	`INVALID_ID`
`CODE_INVALID`	`INVALID_CODE`
`NAME_INVALID`	`INVALID_NAME`
`MEMORY_INVALID`	`INVALID_MEMORY`
`DATABASE_TYPE_INVALID`	`INVALID_DATABASE_TYPE`
`DATABASE_VERSION_INVALID`	`INVALID_DATABASE_VERSION`
`UNKNOWN_WORKSPACE`	`WORKSPACE_NOT_FOUND`
`UNKNOWN_MEMBER`	`MEMBER_NOT_FOUND`
`MAX_APPLICATIONS_REACHED`	`APPLICATIONS_LIMIT_REACHED`
`MAX_MEMBERS_REACHED`	`MEMBERS_LIMIT_REACHED`
`FAILED_WORKSPACE_CREATION`	`WORKSPACE_CREATION_FAILED`
`FAILED_DATABASE_CREATION`	`DATABASE_CREATION_FAILED`
`FAILED_CLUSTER_SELECTION`	`CLUSTER_SELECTION_FAILED`
`FEW_MEMORY`	`INSUFFICIENT_MEMORY`
`FAILED_READ`	`READ_FAILED`
`FAILED_DELETE`, `DELETE_ERROR`	`DELETE_FAILED`
`FAILED_RENAME`	`RENAME_FAILED`
`FAILED_TO_SAVE`	`SAVE_FAILED`
`FAILED_RESET`	`RESET_FAILED`
`FAILED_UPLOAD`	`UPLOAD_FAILED`
`FAILED_UPLOAD_DATA`	`STORAGE_UPLOAD_FAILED`
`COMMIT_ERROR`	`COMMIT_FAILED`
`INTERNAL_ERROR`	`INTERNAL_SERVER_ERROR`
`REGEX_VALIDATION`	`INVALID_DOMAIN`
`CAN_NOT_SET_SUBDOMAIN`	`CANNOT_SET_SUBDOMAIN`
`INVALID_APP` (apenas em métricas)	`METRICS_NOT_SUPPORTED`
`SUBSCRIPTION_REQUIRED`	`UPGRADE_REQUIRED`

Códigos inalterados: KEEP_CALM (429 curto, tente novamente em alguns segundos), ACCESS_DENIED (401), PAYLOAD_TOO_LARGE (413), RATE_LIMIT_EXCEEDED. Novos na v5:

Código	Significado
`DAILY_SNAPSHOTS_LIMIT_REACHED`	429, a cota diária de snapshots do plano foi atingida (diferente de `KEEP_CALM`)
`UPLOAD_ABORTED`	O cliente abortou um upload em andamento
`LOAD_BALANCER_LIMIT_REACHED`	403, ao anexar um domínio personalizado além do limite de apps por domínio do plano
`FILE_TOO_LARGE`	413, em um upload acima de 100MB ou na leitura de um arquivo grande

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

try {
    const snapshots = await api.user.snapshots("applications");
} catch (err) {
    if (err instanceof SquareCloudAPIError) {
        switch (err.code) {
            case "UPGRADE_REQUIRED":
                console.error("é necessário um plano pago ativo para snapshots de toda a conta");
                break;
            default:
                console.error(err.code, err.message);
        }
    }
}

Serviços

Runtimes

Plataforma

Solução de Problemas

CLI

SDKs

Changelog

Requisitos

Instalação

Instanciando o cliente

Construtor

Módulos

Obtendo o usuário autenticado

Buscando uma aplicação específica

Listando histórico de snapshots da conta

Status da plataforma

Cache do cliente

Tratamento de erros

Códigos de erro (APIErrorCode)

​Requisitos

​Instalação

​Instanciando o cliente

​Construtor

​Módulos

​Obtendo o usuário autenticado

​Buscando uma aplicação específica

​Listando histórico de snapshots da conta

​Status da plataforma

​Cache do cliente

​Tratamento de erros

​Códigos de erro (APIErrorCode)

Requisitos

Instalação

Instanciando o cliente

Construtor

Módulos

Obtendo o usuário autenticado

Buscando uma aplicação específica

Listando histórico de snapshots da conta

Status da plataforma

Cache do cliente

Tratamento de erros

Códigos de erro (APIErrorCode)