Migrando para a v4

Último patch coberto aqui: v4.0.1 (lançado em 30/05/2026).

Requisitos

Node.js 20.0.0 ou superior (a v3 suportava Node 18)

Resumo das breaking changes

v3.x	v4.x
`client.users.*`	`client.user.*`
`app.backup` / `app.backups`	`app.snapshots`
`Backup` (export)	`Snapshot` (export)
`app.deploys.list()` retornava `Deployment[]` plano	Retorna `Deployment[][]` (use `.flat()` para manter o formato antigo)
`Deployment.id` formatado como `git-${string}`	SHA-1 puro do commit (40 chars hex)
`app.network.dns()` retornava array	Retorna `{ ownership, ssl }`
`app.network.analytics()` sem argumentos	Exige `{ start, end }` (string ISO ou `Date`)
`app.network.purgeCache(paths?)`	`purgeCache()` — argumento removido na v4.0.1, sempre limpa o cache inteiro
`app.custom === undefined`	`app.custom === null`
`workspace.members` / `.applications` eram arrays	Renomeados para `workspace.memberList` / `.applicationList`; os nomes originais agora são módulos
`app.commit(file, name, restart)`	`app.commit(file, name)` — terceiro argumento removido
`app.files.create(content, fullPath)`	`app.files.create(content, fileName, path)`

Renomeações

`client.users` → `client.user`

// v3
await api.users.get();

// v4
await api.user.get();

api.users ainda é exportado como um getter depreciado que redireciona para api.user, mas exibe um aviso em tempo de execução.

Backups → Snapshots

// v3
await app.backups.create();
await app.backup.list();

// v4
await app.snapshots.create();
await app.snapshots.list();

O export Backup agora é um alias depreciado de Snapshot.

Aplicação

`Application.custom`

app.custom agora é null (era undefined na v3) quando nenhum domínio customizado está vinculado.

`app.commit(file, fileName, restart)`

O terceiro argumento restart foi removido. Reinicie manualmente após o commit:

// v3
await app.commit(buffer, "index.js", true);

// v4
await app.commit(buffer, "index.js");
await app.restart();

`app.files.create(content, path)`

A assinatura agora é create(content, fileName, path = "/"). Migração:

// v3 — caminho único combinado
await app.files.create(content, "./pasta/arquivo_teste.txt");

// v4 — nome do arquivo e diretório separados
await app.files.create(content, "arquivo_teste.txt", "/pasta");

Deploys

Formato de `app.deploys.list()`

// v3
const events: Deployment[] = await app.deploys.list();

// v4
const timelines: Deployment[][] = await app.deploys.list();
const events = timelines.flat(); // mesmo formato da v3

`Deployment.id`

Agora é um SHA-1 puro do commit (40 chars hex), em vez do formato `git-…`.

Rede

`app.network.dns()`

// v3
const records: DnsRecord[] = await app.network.dns();

// v4
const { ownership, ssl } = await app.network.dns();

`app.network.analytics()`

// v3
const data = await app.network.analytics();

// v4 — { start, end } é obrigatório (string ISO ou Date)
const data = await app.network.analytics({
    start: new Date(Date.now() - 24 * 60 * 60 * 1000),
    end:   new Date(),
});

`app.network.purgeCache()`

// v3 e v4.0.0
await app.network.purgeCache(["/static/old.js"]);

// v4.0.1 em diante — purge seletivo foi removido
await app.network.purgeCache();

Workspaces

// v3
workspace.members;      // dados brutos dos membros
workspace.applications; // dados brutos das aplicações

// v4
workspace.memberList;        // dados brutos dos membros
workspace.applicationList;   // dados brutos das aplicações
workspace.members.add(...);  // módulo de membros
workspace.applications.add(...); // módulo de aplicações

Novidades da v4

Além das renomeações e mudanças de assinatura acima, a v4 traz um conjunto considerável de novas funcionalidades:

Bancos de dados — ciclo de vida completo, credenciais, snapshots e métricas (Bancos de dados)
Workspaces — colaboração em equipe com códigos de convite e papéis (Workspaces)
Variáveis de ambiente — list / set / replace / delete (Variáveis de ambiente)
Métricas da aplicação — amostras de 24h de CPU/RAM/rede (Gerenciando aplicações)
Stream SSE em tempo real — app.realtime() (Tempo real)
Edge analytics — analytics, erros, logs e percentis de latência (Rede)
Integração via GitHub App — app.deploys.linkGithubApp({ ... }) (Deploys)
Restauração de snapshots — app.snapshots.restore({ snapshotId, versionId }) e db.snapshots.restore(snapshotId, versionId)
Endpoints status-all — api.applications.statusAll(), api.databases.statusAll()
Status da plataforma — api.service.status()
Snapshots do usuário — api.user.snapshots(scope)
Novos campos em User — User.locale, User.createdAt, User.databases
Novos campos em BaseApplication — domain, custom, createdAt
SquareCloudAPIError.code — público para switch baseado no tipo de erro

Serviços

Runtimes

Plataforma

Solução de Problemas

CLI

SDKs

Changelog

Requisitos

Resumo das breaking changes

Renomeações

`client.users` → `client.user`

Backups → Snapshots

Aplicação

`Application.custom`

`app.commit(file, fileName, restart)`

`app.files.create(content, path)`

Deploys

Formato de `app.deploys.list()`

`Deployment.id`

Rede

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

Novidades da v4

​Requisitos

​Resumo das breaking changes

​Renomeações

​client.users → client.user

​Backups → Snapshots

​Aplicação

​Application.custom

​app.commit(file, fileName, restart)

​app.files.create(content, path)

​Deploys

​Formato de app.deploys.list()

​Deployment.id

​Rede

​app.network.dns()

​app.network.analytics()

​app.network.purgeCache()

​Workspaces

​Novidades da v4

Requisitos

Resumo das breaking changes

Renomeações

`client.users` → `client.user`

Backups → Snapshots

Aplicação

`Application.custom`

`app.commit(file, fileName, restart)`

`app.files.create(content, path)`

Deploys

Formato de `app.deploys.list()`

`Deployment.id`

Rede

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

Novidades da v4