Passer au contenu principal
Cette page documente @squarecloud/api v4. Si vous effectuez une mise à niveau depuis la v3, lisez d’abord le guide de migration v3 → v4.

​
Prérequis

​
Installation

npm install @squarecloud/api

​
Instanciation du client

import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARE_API_KEY!);

​
Constructeur

ParamètreTypeRequisDescription
apiKeystringOuiVotre clé d’API Square Cloud. Le client lève une exception si ce n’est pas une chaîne de caractères.

​
Modules

Le client expose l’intégralité de la plateforme v2 via des modules dédiés. Chaque module est une propriété de l’instance SquareCloudAPI.
PropriétéModuleDocumentation
api.userUtilisateur authentifié, plan, applications et bases de données possédéesCette page
api.applicationsLister, récupérer, envoyer et inspecter les applicationsGestion des applications
api.databasesCréer, récupérer et gérer les bases de donnéesBases de données
api.workspacesCréer, lister et gérer les workspacesWorkspaces
api.serviceÉtat global de la plateformeCette page
api.cacheCache en mémoire alimenté par les événements du SDKCette page

​
Récupérer l’utilisateur authentifié

api.user.get() renvoie une instance User contenant les détails du compte, le plan actuel, les applications possédées et les bases de données possédées. 
const user = await api.user.get();

console.log(user.id);          // "abcdef0123456789abcdef01"
console.log(user.name);        // "John Doe"
console.log(user.email);       // "john@example.com"
console.log(user.locale);      // "en-US"
console.log(user.plan.name);   // "free" | "standard" | ...
console.log(user.createdAt);   // Date

console.log(user.applications); // Collection<string, BaseApplication>
console.log(user.databases);    // Collection<string, Database>
user.applications et user.databases sont des instances Collection (une sous-classe de Map). Parcourez-les comme n’importe quelle Map : 
for (const [id, app] of user.applications) {
    console.log(`${app.name} (${id}) — ${app.ram}MB ${app.language}`);
}

​
Récupérer une application unique

Utilisez api.applications.fetch(id) pour récupérer une Application entièrement renseignée (ou une WebsiteApplication, lorsque l’application possède un domaine de site web). 
const app = await api.applications.fetch("abc123def456abc123def456");

console.log(app.id, app.name, app.cluster, app.createdAt);

if (app.isWebsite()) {
    // affinée en WebsiteApplication — `.network` est disponible
    await app.network.purgeCache();
}
La surcharge héritée api.applications.get(id) existe toujours, mais elle renvoie la BaseApplication plus légère et n’est conservée que pour la rétrocompatibilité. Préférez .fetch() pour la v4.

​
Lister l’historique des snapshots (à l’échelle du compte)

const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");
Consultez Snapshots pour plus de détails sur les charges utiles des snapshots.

​
État de la plateforme

api.service.status() expose l’état de santé agrégé de la plateforme (les mêmes données affichées sur la page de statut publique). 
const status = await api.service.status();

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // résumé lisible par un humain
Contrairement à la plupart des endpoints v2, cette route n’enveloppe pas sa charge utile dans l’enveloppe standard { status, response }.

​
Cache du client

Le client maintient un cache en mémoire que le SDK garde synchronisé au fil de vos appels : 
api.cache.user;   // dernier User récupéré
// chaque instance d'application expose également app.cache.status / .logs / .snapshots
Le SDK émet des événements typés auxquels vous pouvez vous abonner : 
api.on("userUpdate", (previous, current) => {
    console.log("user changed:", current.name);
});

api.on("statusUpdate", (application, previous, current) => {
    console.log(`${application.name} → ${current.status}`);
});

api.on("logsUpdate", (application, previous, current) => {
    console.log(`new logs for ${application.name}`);
});

api.on("snapshotsUpdate", (application, previous, current) => {
    console.log(`${current.length} snapshots for ${application.name}`);
});

​
Gestion des erreurs

Les requêtes en échec lèvent une SquareCloudAPIError. L’erreur expose une propriété code stable sur laquelle vous pouvez brancher un switch pour distinguer les modes de défaillance. 
import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

try {
    const app = await api.applications.fetch("invalid-id");
} catch (err) {
    if (err instanceof SquareCloudAPIError) {
        console.error(err.code);    // e.g. "APP_NOT_FOUND"
        console.error(err.message);
    }
}