> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # Migrando para a v4 > O que mudou entre o @squarecloud/api v3 e v4 — breaking changes, renomeações e os ajustes mínimos para atualizar. Ú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` ```typescript theme={null} // 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 ```typescript theme={null} // 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: ```typescript theme={null} // 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: ```typescript theme={null} // 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()` ```typescript theme={null} // 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()` ```typescript theme={null} // v3 const records: DnsRecord[] = await app.network.dns(); // v4 const { ownership, ssl } = await app.network.dns(); ``` ### `app.network.analytics()` ```typescript theme={null} // 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()` ```typescript theme={null} // 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 ```typescript theme={null} // 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](/pt-br/sdks/js/databases)) * **Workspaces** — colaboração em equipe com códigos de convite e papéis ([Workspaces](/pt-br/sdks/js/workspaces)) * **Variáveis de ambiente** — list / set / replace / delete ([Variáveis de ambiente](/pt-br/sdks/js/environment_variables)) * **Métricas da aplicação** — amostras de 24h de CPU/RAM/rede ([Gerenciando aplicações](/pt-br/sdks/js/managing_application)) * **Stream SSE em tempo real** — `app.realtime()` ([Tempo real](/pt-br/sdks/js/realtime)) * **Edge analytics** — analytics, erros, logs e percentis de latência ([Rede](/pt-br/sdks/js/network)) * **Integração via GitHub App** — `app.deploys.linkGithubApp({ ... })` ([Deploys](/pt-br/sdks/js/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