> ## 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.

# Migrazione a v4

> Cosa è cambiato tra @squarecloud/api v3 e v4 — breaking change, rinomine e le patch minime necessarie per l'upgrade.

<Info>
  Ultima patch trattata qui: **v4.0.1** (rilasciata il 2026-05-30).
</Info>

## 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`

```typescript theme={null}
// 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

```typescript theme={null}
// 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:

```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)`

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

```typescript theme={null}
// 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()`

```typescript theme={null}
// 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()`

```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 } 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()`

```typescript theme={null}
// 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

```typescript theme={null}
// 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](/it/sdks/js/databases))
* **Workspaces** — collaborazione di team con codici di invito e ruoli ([Workspace](/it/sdks/js/workspaces))
* **Variabili d'ambiente** — list / set / replace / delete ([Variabili d'ambiente](/it/sdks/js/environment_variables))
* **Metriche delle applicazioni** — campioni di CPU/RAM/rete su 24h ([Gestire le applicazioni](/it/sdks/js/managing_application))
* **Stream SSE in tempo reale** — `app.realtime()` ([Realtime](/it/sdks/js/realtime))
* **Analytics edge** — analytics, errori, log e percentili di latenza ([Network](/it/sdks/js/network))
* **Integrazione GitHub App** — `app.deploys.linkGithubApp({ ... })` ([Deploys](/it/sdks/js/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`