SDK JavaScript: início rápido e cliente

Esta página documenta o @squarecloud/api v6, uma reescrita do SDK. Vindo da v5? Leia o guia de migração v5 → v6.

Requisitos

Node.js 22 ou superior, Deno, Bun ou um edge runtime. O SDK precisa apenas de fetch, FormData, Blob e web streams.
Uma chave de API (veja Chave de API e escopos).

O pacote inclui builds ESM e CommonJS, não tem nenhuma dependência em tempo de execução e traz seus próprios tipos TypeScript: você não precisa mais do @squarecloud/api-types.

Instalação

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

Chave de API e escopos

Crie uma chave em squarecloud.app/account/security. O SDK a envia como está no header Authorization (sem o prefixo Bearer). Uma chave pode ser limitada a escopos (apps:read, apps:deploy, apps:control, ai:chat, …) e a aplicações ou bancos de dados específicos:

Uma chamada fora desses limites lança um SquareCloudAPIError com 403 MISSING_SCOPE ou RESOURCE_NOT_ALLOWED.
Métodos de listagem (account.me(), apps.statusAll(), …) retornam apenas os recursos que a chave pode ver.
Uma chave desconhecida, revogada ou expirada resulta em 401 ACCESS_DENIED.

Mantenha a chave no servidor. O SDK também roda no navegador, mas isso exporia a chave a todos os visitantes.

Os exemplos leem a chave da variável de ambiente SQUARECLOUD_API_KEY. Defina-a no terminal em que você vai executá-los:

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

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

Criando o 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);

O primeiro exemplo imprime o nome da sua conta e o número de aplicações que a chave pode ver:

Hi Jane, you have 3 apps

Uma chave vazia ou composta apenas de espaços lança um TypeError no construtor, antes de qualquer requisição.

Opções

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

Opção	Padrão	Descrição
`baseUrl`	`https://api.squarecloud.app/v2`	URL base da API. Uma `/` final é removida. Também exportada como `BASE_URL`.
`timeoutMs`	`30000`	Timeout por tentativa, cobrindo a resposta inteira. Veja Timeouts.
`maxRetries`	`2`	Novas tentativas apenas de falhas seguras (até 3 tentativas). Um valor negativo conta como `0`. Veja Novas tentativas.
`userAgent`	`squarecloud-sdk-js/<version>`	Substitui todo o header `User-Agent`.
`fetch`	o `fetch` global	Um `fetch` personalizado para proxies, tracing ou testes.

A chave de API é armazenada como uma propriedade comum do objeto do cliente. Não use console.log nem serialize o cliente.

Módulos

Propriedade	Cobre	Página
`api.account`	`me()`, `snapshots({ scope })`	Conta e Snapshots
`api.service`	`status()`	Status da plataforma
`api.apps`	Obter, excluir, status, ciclo de vida, logs, métricas, domínios, load balancers	Gerenciando aplicações
`api.apps.create` / `commit`	Uploads	Commit e upload
`api.apps.files`	Gerenciador de arquivos	Gerenciando arquivos
`api.apps.envs`	Variáveis de ambiente	Variáveis de ambiente
`api.apps.deploys`	Deploys via webhook e GitHub App	Deploys
`api.apps.network`	Analytics, logs, DNS, domínio personalizado, cache	Rede
`api.apps.realtime`	Logs e status ao vivo	Tempo real
`api.apps.snapshots` / `api.databases.snapshots` / `api.downloadSnapshot`	Backups	Snapshots
`api.databases`	Bancos de dados gerenciados	Bancos de dados
`api.workspaces`	Workspaces, membros e aplicações compartilhadas	Workspaces
`api.ai`	`chat()`	IA

Os únicos exports de runtime são SquareCloudAPI, SquareCloudAPIError e BASE_URL. Todos os outros exports (App, RuntimeStats, ErrorCode, …) são tipos:

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

Convenções

Ids primeiro, dados simples de volta

Todo método recebe o id do recurso como primeiro argumento e retorna dados simples (sem classes, sem cache). Os nomes dos campos são os da própria API (created_at, version_id, lastModified, joinedAt, netIO, …), então a referência da API se aplica diretamente.

Mutações resolvem para void, a menos que a API retorne dados (envs.*, deploys.setWebhook, deploys.linkGithubApp, databases.resetCredentials e os métodos create).
Um resultado string nunca é undefined: ele é "" quando a API não envia nada.
Listas vêm completas em uma única chamada: não há paginação.

Os métodos são arrow functions, então você pode desestruturá-los:

const { restart, logs } = api.apps;

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

Aplicações de workspace

Todo appId também aceita a forma composta <appId>-<workspaceId> para atuar sobre uma aplicação compartilhada com você por meio de um workspace. workspaces.get() e workspaces.list() retornam ids brutos; você mesmo monta o id composto:

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

Ids são codificados

Ids no caminho da URL são codificados com percent-encoding. Um id vazio, . ou .. chegaria a uma rota diferente, então ele falha localmente com INVALID_ID (status 0) antes que qualquer coisa seja enviada. As rotas de workspace enviam seus ids no corpo: nelas, o INVALID_ID (400) vem do servidor.

Datas

Os argumentos start e end (veja Rede) aceitam uma string ISO 8601 ou um Date. As datas nas respostas permanecem como a API as envia (strings ISO, ou milissegundos Unix onde a API os usa).

Timeouts

Chamada	Timeout
Todas as outras chamadas	`timeoutMs` (30 s) por tentativa
Chamadas que o servidor mantém abertas: `start`/`stop`/`restart` de aplicações, `start`/`stop` de bancos de dados, `databases.create`, `create`/`restore` de snapshots, `ai.chat`	Pelo menos 120 s (um `timeoutMs` maior prevalece)
Uploads (`apps.create`, `apps.commit`), `files.write` acima de 1 MiB, `downloadSnapshot`	Nenhum: passe um `signal` para cancelar
`apps.realtime`	Apenas até os headers da resposta chegarem

Um timeoutMs de 0 ou menos, Infinity ou >= 2^31 desativa todos os timeouts, incluindo os mínimos de 120 s. Apenas cinco métodos aceitam um AbortSignal: apps.create, apps.commit, files.write, apps.realtime e downloadSnapshot.

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

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

Uma chamada abortada rejeita com o reason do signal, não com um SquareCloudAPIError. Um loop de realtime() abortado simplesmente termina.

Conta

api.account.me() retorna o usuário autenticado, além das aplicações e bancos de dados que a chave pode 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	Descrição
`user`	`id`, `name`, `email`, `locale`, `created_at` e `plan` (`name`, `memory`, `duration`: o Unix ms em que o plano expira, `null` se nunca expirar)
`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 os snapshots da conta: veja Snapshots.

Status da plataforma

api.service.status() retorna o status público da plataforma. A rota não exige uma chave válida, mas o cliente ainda requer uma chave não vazia.

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 a própria verificação não pôde ser executada: não é evidência de uma indisponibilidade.

Próximos passos

Gerenciando aplicações

Status, ciclo de vida, logs e métricas.

Erros

Classe de erro, novas tentativas e rate limits.

Introdução à API

URL base, autenticação e uma primeira requisição.

Início rápido da CLI

Faça deploy e gerencie aplicações pelo terminal.

CLI

VS Code

SDKs

SDK JavaScript: início rápido e cliente

Requisitos

Instalação

Chave de API e escopos

Criando o cliente

Opções

Módulos

Convenções

Ids primeiro, dados simples de volta

Aplicações de workspace

Ids são codificados

Datas

Timeouts

Conta

Status da plataforma

Próximos passos

Gerenciando aplicações

Erros

Introdução à API

Início rápido da CLI

​Requisitos

​Instalação

​Chave de API e escopos

​Criando o cliente

​Opções

​Módulos

​Convenções

​Ids primeiro, dados simples de volta

​Aplicações de workspace

​Ids são codificados

​Datas

​Timeouts

​Conta

​Status da plataforma

​Próximos passos

Gerenciando aplicações

Erros

Introdução à API

Início rápido da CLI

Requisitos

Instalação

Chave de API e escopos

Criando o cliente

Opções

Módulos

Convenções

Ids primeiro, dados simples de volta

Aplicações de workspace

Ids são codificados

Datas

Timeouts

Conta

Status da plataforma

Próximos passos