Pular para o conteúdo principal
Esta página documenta o @squarecloud/api v4. Se você está migrando da v3, leia primeiro o guia de migração v3 → v4.

​
Requisitos

​
Instalação

npm install @squarecloud/api

​
Instanciando o cliente

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

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

​
Construtor

ParâmetroTipoObrigatórioDescrição
apiKeystringSimSua 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.
PropriedadeMóduloDocumentação
api.userUsuário autenticado, plano, apps e bancos própriosEsta página
api.applicationsListar, buscar, enviar e inspecionar aplicaçõesGerenciando aplicações
api.databasesCriar, buscar e gerenciar bancos de dadosBancos de dados
api.workspacesCriar, listar e gerenciar workspacesWorkspaces
api.serviceStatus agregado da plataformaEsta página
api.cacheCache em memória atualizado por eventos do SDKEsta 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);   // "free" | "standard" | ...
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 v4.

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