Migrazione a v4

Ultima patch trattata qui: v4.0.1 (rilasciata il 2026-05-30).

Requisiti

Node.js 20.0.0 o più recente (v3 supportava Node 18)

Riepilogo dei breaking change

v3.x	v4.x
`client.users.*`	`client.user.*`
`app.backup` / `app.backups`	`app.snapshots`
Export `Backup`	Export `Snapshot`
`app.deploys.list()` restituisce un `Deployment[]` piatto	Restituisce `Deployment[][]` (chiama `.flat()` per la vecchia forma)
`Deployment.id` formattato come `git-${string}`	SHA-1 del commit puro (40 caratteri esadecimali)
`app.network.dns()` restituisce un array	Restituisce `{ ownership, ssl }`
`app.network.analytics()` non accetta argomenti	Richiede `{ start, end }` (stringa ISO o `Date`)
`app.network.purgeCache(paths?)`	`purgeCache()` — argomento rimosso in v4.0.1, purga sempre l’intera cache
`app.custom === undefined`	`app.custom === null`
`workspace.members` / `.applications` contenevano array di dati	Rinominati in `workspace.memberList` / `.applicationList`; i nomi originali sono ora moduli
`app.commit(file, name, restart)`	`app.commit(file, name)` — terzo argomento rimosso
`app.files.create(content, fullPath)`	`app.files.create(content, fileName, path)`

Rinomine

`client.users` → `client.user`

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

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

api.users è ancora esportato come getter deprecato che fa da proxy verso api.user, ma stampa un avviso a runtime.

Backups → Snapshots

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

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

L’export Backup è ora un alias deprecato di Snapshot.

Application

`Application.custom`

app.custom è ora null (era undefined in v3) quando nessun dominio personalizzato è associato.

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

Il terzo argomento restart è stato rimosso. Riavvia manualmente dopo il commit:

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

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

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

La firma è ora create(content, fileName, path = "/"). Migrazione:

// v3 — single combined path
await app.files.create(content, "./folder/test_file.txt");

// v4 — separate file name and directory
await app.files.create(content, "test_file.txt", "/folder");

Deploys

Forma di `app.deploys.list()`

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

// v4
const timelines: Deployment[][] = await app.deploys.list();
const events = timelines.flat(); // same shape as v3

`Deployment.id`

Ora un semplice SHA-1 del commit (40 caratteri esadecimali) invece di una stringa formattata `git-…`.

Network

`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 } is now required (ISO string or Date)
const data = await app.network.analytics({
    start: new Date(Date.now() - 24 * 60 * 60 * 1000),
    end:   new Date(),
});

`app.network.purgeCache()`

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

// v4.0.1 and later — selective purge removed
await app.network.purgeCache();

Workspaces

// v3
workspace.members;      // raw member data
workspace.applications; // raw application data

// v4
workspace.memberList;        // raw member data
workspace.applicationList;   // raw application data
workspace.members.add(...);  // members module
workspace.applications.add(...); // applications module

Novità in v4

Oltre alle rinomine e ai cambiamenti di firma descritti sopra, v4 aggiunge un consistente set di funzionalità:

Databases — ciclo di vita completo, credenziali, snapshot e metriche (Database)
Workspaces — collaborazione di team con codici di invito e ruoli (Workspace)
Variabili d’ambiente — list / set / replace / delete (Variabili d’ambiente)
Metriche delle applicazioni — campioni di CPU/RAM/rete su 24h (Gestire le applicazioni)
Stream SSE in tempo reale — app.realtime() (Realtime)
Analytics edge — analytics, errori, log e percentili di latenza (Network)
Integrazione GitHub App — app.deploys.linkGithubApp({ ... }) (Deploys)
Ripristino degli snapshot — app.snapshots.restore({ snapshotId, versionId }) e db.snapshots.restore(snapshotId, versionId)
Endpoint status-all — api.applications.statusAll(), api.databases.statusAll()
Stato del servizio — api.service.status()
Snapshot con ambito utente — api.user.snapshots(scope)
Nuovi campi User — User.locale, User.createdAt, User.databases
Nuovi campi BaseApplication — domain, custom, createdAt
SquareCloudAPIError.code — pubblico per la gestione degli errori basata su switch

Servizi

Runtimes

Piattaforma

Risoluzione dei problemi

CLI

SDKs

Changelog

Requisiti

Riepilogo dei breaking change

Rinomine

`client.users` → `client.user`

Backups → Snapshots

Application

`Application.custom`

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

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

Deploys

Forma di `app.deploys.list()`

`Deployment.id`

Network

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

Novità in v4

​Requisiti

​Riepilogo dei breaking change

​Rinomine

​client.users → client.user

​Backups → Snapshots

​Application

​Application.custom

​app.commit(file, fileName, restart)

​app.files.create(content, path)

​Deploys

​Forma di app.deploys.list()

​Deployment.id

​Network

​app.network.dns()

​app.network.analytics()

​app.network.purgeCache()

​Workspaces

​Novità in v4

Requisiti

Riepilogo dei breaking change

Rinomine

`client.users` → `client.user`

Backups → Snapshots

Application

`Application.custom`

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

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

Deploys

Forma di `app.deploys.list()`

`Deployment.id`

Network

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

Novità in v4