Migration vers la v4

Dernier correctif couvert ici : v4.0.1 (publié le 30/05/2026).

Prérequis

Node.js 20.0.0 ou plus récent (la v3 supportait Node 18)

Résumé des ruptures de compatibilité

v3.x	v4.x
`client.users.*`	`client.user.*`
`app.backup` / `app.backups`	`app.snapshots`
Export `Backup`	Export `Snapshot`
`app.deploys.list()` renvoie un `Deployment[]` plat	Renvoie un `Deployment[][]` (appelez `.flat()` pour l’ancienne forme)
`Deployment.id` formaté comme `git-${string}`	SHA-1 de commit brut (40 caractères hexadécimaux)
`app.network.dns()` renvoie un tableau	Renvoie `{ ownership, ssl }`
`app.network.analytics()` ne prend aucun argument	Requiert `{ start, end }` (chaîne ISO ou `Date`)
`app.network.purgeCache(paths?)`	`purgeCache()` — argument supprimé en v4.0.1, purge toujours l’intégralité du cache
`app.custom === undefined`	`app.custom === null`
`workspace.members` / `.applications` contenaient des tableaux de données	Renommés en `workspace.memberList` / `.applicationList` ; les noms d’origine sont désormais des modules
`app.commit(file, name, restart)`	`app.commit(file, name)` — troisième argument supprimé
`app.files.create(content, fullPath)`	`app.files.create(content, fileName, path)`

Renommages

`client.users` → `client.user`

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

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

api.users est toujours exporté sous forme d’accesseur déprécié qui redirige vers api.user, mais il affiche un avertissement à l’exécution.

Backups → Snapshots

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

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

L’export Backup est désormais un alias déprécié de Snapshot.

Application

`Application.custom`

app.custom vaut désormais null (au lieu de undefined en v3) lorsqu’aucun domaine personnalisé n’est associé.

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

Le troisième argument restart a été supprimé. Redémarrez manuellement après le 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 signature est désormais create(content, fileName, path = "/"). Migration :

// v3 — chemin combiné unique
await app.files.create(content, "./folder/test_file.txt");

// v4 — nom de fichier et répertoire séparés
await app.files.create(content, "test_file.txt", "/folder");

Deploys

Forme de `app.deploys.list()`

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

// v4
const timelines: Deployment[][] = await app.deploys.list();
const events = timelines.flat(); // même forme que la v3

`Deployment.id`

Désormais un SHA-1 de commit brut (40 caractères hexadécimaux) au lieu d’une chaîne formatée `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 } est désormais requis (chaîne 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 et v4.0.0
await app.network.purgeCache(["/static/old.js"]);

// v4.0.1 et versions ultérieures — purge sélective supprimée
await app.network.purgeCache();

Workspaces

// v3
workspace.members;      // données brutes des membres
workspace.applications; // données brutes des applications

// v4
workspace.memberList;        // données brutes des membres
workspace.applicationList;   // données brutes des applications
workspace.members.add(...);  // module members
workspace.applications.add(...); // module applications

Nouveautés de la v4

Au-delà des renommages et changements de signature ci-dessus, la v4 ajoute un ensemble substantiel de fonctionnalités :

Databases — cycle de vie complet, identifiants, snapshots et métriques (Databases)
Workspaces — collaboration d’équipe avec codes d’invitation et rôles (Workspaces)
Variables d’environnement — lister / définir / remplacer / supprimer (Variables d’environnement)
Métriques d’application — échantillons CPU/RAM/réseau sur 24 h (Gérer les applications)
Flux SSE en temps réel — app.realtime() (Realtime)
Analytics edge — analytics, erreurs, logs et percentiles de latence (Network)
Intégration GitHub App — app.deploys.linkGithubApp({ ... }) (Deploys)
Restauration de snapshot — app.snapshots.restore({ snapshotId, versionId }) et db.snapshots.restore(snapshotId, versionId)
Endpoints status-all — api.applications.statusAll(), api.databases.statusAll()
Statut du service — api.service.status()
Snapshots au niveau utilisateur — api.user.snapshots(scope)
Nouveaux champs User — User.locale, User.createdAt, User.databases
Nouveaux champs BaseApplication — domain, custom, createdAt
SquareCloudAPIError.code — public pour la gestion des erreurs par switch

Services

Runtimes

Plateforme

Dépannage

CLI

SDKs

Changelog

Prérequis

Résumé des ruptures de compatibilité

Renommages

`client.users` → `client.user`

Backups → Snapshots

Application

`Application.custom`

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

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

Deploys

Forme de `app.deploys.list()`

`Deployment.id`

Network

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

Nouveautés de la v4

​Prérequis

​Résumé des ruptures de compatibilité

​Renommages

​client.users → client.user

​Backups → Snapshots

​Application

​Application.custom

​app.commit(file, fileName, restart)

​app.files.create(content, path)

​Deploys

​Forme de app.deploys.list()

​Deployment.id

​Network

​app.network.dns()

​app.network.analytics()

​app.network.purgeCache()

​Workspaces

​Nouveautés de la v4

Prérequis

Résumé des ruptures de compatibilité

Renommages

`client.users` → `client.user`

Backups → Snapshots

Application

`Application.custom`

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

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

Deploys

Forme de `app.deploys.list()`

`Deployment.id`

Network

`app.network.dns()`

`app.network.analytics()`

`app.network.purgeCache()`

Workspaces

Nouveautés de la v4