SDK JavaScript : démarrage rapide et client

Cette page documente @squarecloud/api v6, une réécriture du SDK. Vous venez de la v5 ? Lisez le guide de migration v5 → v6.

Prérequis

Node.js 22 ou plus récent, Deno, Bun ou un runtime edge. Le SDK n’a besoin que de fetch, FormData, Blob et des web streams.
Une clé API (voir Clé API et scopes).

Le paquet est distribué en builds ESM et CommonJS, n’a aucune dépendance d’exécution et inclut ses propres types TypeScript : vous n’avez plus besoin de @squarecloud/api-types.

Installation

npm
pnpm
yarn
bun
deno

npm install @squarecloud/api

pnpm add @squarecloud/api

yarn add @squarecloud/api

bun add @squarecloud/api

deno add npm:@squarecloud/api

Clé API et scopes

Créez une clé sur squarecloud.app/account/security. Le SDK l’envoie telle quelle dans l’en-tête Authorization (sans préfixe Bearer). Une clé peut être limitée à des scopes (apps:read, apps:deploy, apps:control, ai:chat, …) et à des applications ou bases de données précises :

Un appel hors de ces limites lève une SquareCloudAPIError avec 403 MISSING_SCOPE ou RESOURCE_NOT_ALLOWED.
Les méthodes de liste (account.me(), apps.statusAll(), …) ne renvoient que les ressources que la clé peut voir.
Une clé inconnue, révoquée ou expirée donne 401 ACCESS_DENIED.

Gardez la clé sur le serveur. Le SDK fonctionne aussi dans un navigateur, mais cela exposerait la clé à chaque visiteur.

Les exemples lisent la clé depuis la variable d’environnement SQUARECLOUD_API_KEY. Définissez-la dans le terminal où vous les exécutez :

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

Créer le client

TypeScript / ESM
CommonJS

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

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

const { user, applications } = await api.account.me();
console.log(`Hi ${user.name}, you have ${applications.length} apps`);

const { SquareCloudAPI } = require("@squarecloud/api");

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY);

Le premier exemple affiche le nom de votre compte et le nombre d’applications que la clé peut voir :

Hi Jane, you have 3 apps

Une clé vide ou composée uniquement d’espaces lève une TypeError dans le constructeur, avant toute requête.

Options

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

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!, {
    baseUrl: BASE_URL, // "https://api.squarecloud.app/v2" (default)
    timeoutMs: 30_000,
    maxRetries: 2,
    userAgent: "my-bot/1.0",
    fetch, // any fetch-compatible function (proxy, tracing, tests)
});

Option	Par défaut	Description
`baseUrl`	`https://api.squarecloud.app/v2`	URL de base de l’API. Un `/` final est supprimé. Également exportée sous le nom `BASE_URL`.
`timeoutMs`	`30000`	Timeout par tentative, couvrant toute la réponse. Voir Timeouts.
`maxRetries`	`2`	Nouvelles tentatives des seuls échecs sans risque (jusqu’à 3 tentatives). Une valeur négative compte comme `0`. Voir Nouvelles tentatives.
`userAgent`	`squarecloud-sdk-js/<version>`	Remplace entièrement l’en-tête `User-Agent`.
`fetch`	le `fetch` global	Un `fetch` personnalisé pour les proxys, le traçage ou les tests.

La clé API est stockée comme une propriété ordinaire de l’objet client. Ne faites pas de console.log du client et ne le sérialisez pas.

Modules

Propriété	Couvre	Page
`api.account`	`me()`, `snapshots({ scope })`	Compte et Snapshots
`api.service`	`status()`	Statut de la plateforme
`api.apps`	Récupération, suppression, statut, cycle de vie, logs, métriques, domaines, load balancers	Gérer les applications
`api.apps.create` / `commit`	Envois	Commit et envoi
`api.apps.files`	Gestionnaire de fichiers	Gérer les fichiers
`api.apps.envs`	Variables d’environnement	Variables d’environnement
`api.apps.deploys`	Deploys par webhook et par GitHub App	Deploys
`api.apps.network`	Analytics, logs, DNS, domaine personnalisé, cache	Réseau
`api.apps.realtime`	Logs et statut en direct	Temps réel
`api.apps.snapshots` / `api.databases.snapshots` / `api.downloadSnapshot`	Sauvegardes	Snapshots
`api.databases`	Bases de données gérées	Bases de données
`api.workspaces`	Workspaces, membres et applications partagées	Workspaces
`api.ai`	`chat()`	IA

Les seuls exports d’exécution sont SquareCloudAPI, SquareCloudAPIError et BASE_URL. Tous les autres exports (App, RuntimeStats, ErrorCode, …) sont des types :

import type { App, Snapshot } from "@squarecloud/api";

Conventions

L’identifiant d’abord, des données brutes en retour

Chaque méthode prend l’identifiant de la ressource comme premier argument et renvoie des données brutes (pas de classes, pas de cache). Les noms de champs sont ceux de l’API (created_at, version_id, lastModified, joinedAt, netIO, …), la référence de l’API s’applique donc telle quelle.

Les mutations se résolvent en void, sauf si l’API renvoie des données (envs.*, deploys.setWebhook, deploys.linkGithubApp, databases.resetCredentials et les méthodes create).
Un résultat de type chaîne n’est jamais undefined : il vaut "" quand l’API n’en envoie pas.
Les listes arrivent complètes en un seul appel : il n’y a pas de pagination.

Les méthodes sont des fonctions fléchées, vous pouvez donc les déstructurer :

const { restart, logs } = api.apps;

await restart(appId);
console.log(await logs(appId));

Applications de workspace

Chaque appId accepte aussi la forme composite <appId>-<workspaceId> pour agir sur une application partagée avec vous via un workspace. workspaces.get() et workspaces.list() renvoient les identifiants bruts ; c’est à vous de construire l’identifiant composite :

await api.apps.restart(`${appId}-${workspaceId}`);

Les identifiants sont encodés

Les identifiants dans le chemin de l’URL sont encodés en pourcentage. Un identifiant vide, . ou .. atteindrait une autre route : il échoue donc localement avec INVALID_ID (statut 0) avant tout envoi. Les routes de workspace envoient plutôt leurs identifiants dans le corps : là, INVALID_ID (400) vient du serveur.

Dates

Les arguments start et end (voir Réseau) acceptent une chaîne ISO 8601 ou une Date. Les dates des réponses restent telles que l’API les envoie (chaînes ISO, ou millisecondes Unix là où l’API les utilise).

Timeouts

Appel	Timeout
Tous les autres appels	`timeoutMs` (30 s) par tentative
Appels que le serveur maintient ouverts : `start`/`stop`/`restart` des applications, `start`/`stop` des bases de données, `databases.create`, `create`/`restore` de snapshot, `ai.chat`	Au moins 120 s (un `timeoutMs` plus grand l’emporte)
Envois (`apps.create`, `apps.commit`), `files.write` au-delà de 1 MiB, `downloadSnapshot`	Aucun : passez un `signal` pour annuler
`apps.realtime`	Uniquement jusqu’à l’arrivée des en-têtes de réponse

Un timeoutMs de 0 ou moins, Infinity ou >= 2^31 désactive tous les timeouts, planchers de 120 s compris. Seules cinq méthodes acceptent un AbortSignal : apps.create, apps.commit, files.write, apps.realtime et downloadSnapshot.

const controller = new AbortController();
setTimeout(() => controller.abort(), 60_000);

await api.apps.commit(appId, "./build.zip", { signal: controller.signal });

Un appel annulé est rejeté avec la reason du signal, et non avec une SquareCloudAPIError. Une boucle realtime() annulée se termine simplement.

Compte

api.account.me() renvoie l’utilisateur authentifié ainsi que les applications et bases de données que la clé peut voir.

const { user, applications, databases } = await api.account.me();

console.log(user.id, user.name, user.email, user.plan.name);
console.log(user.plan.memory); // { limit, available, used } in MB
console.log(user.plan.duration ? new Date(user.plan.duration) : "never expires");

Champ	Description
`user`	`id`, `name`, `email`, `locale`, `created_at` et `plan` (`name`, `memory`, `duration` : l’instant en ms Unix auquel le plan expire, `null` s’il n’expire jamais)
`applications`	Tableau de `{ id, name, desc?, ram, lang, domain?, custom?, cluster, created_at }`
`databases`	Tableau de `{ id, name, ram, type, cluster, created_at }`

api.account.snapshots({ scope }) liste tous les snapshots du compte : voir Snapshots.

Statut de la plateforme

api.service.status() renvoie le statut public de la plateforme. La route n’exige pas de clé valide, mais le client en demande tout de même une non vide.

const status = await api.service.status();

console.log(status.status); // "online" | "degraded" | "unknown"
console.log(status.message);

for (const [name, service] of Object.entries(status.services ?? {})) {
    console.log(name, service.status); // "operational" | "degraded" | "outage" | "maintenance" | "unknown"
}

unknown signifie que la vérification elle-même n’a pas pu s’exécuter : ce n’est pas la preuve d’une panne.

Prochaines étapes

Gérer les applications

Statut, cycle de vie, logs et métriques.

Erreurs

Classe d’erreur, nouvelles tentatives et limites de débit.

Introduction à l'API

URL de base, authentification et une première requête.

Démarrage rapide de la CLI

Déployez et gérez vos applications depuis le terminal.

CLI

VS Code

SDKs

SDK JavaScript : démarrage rapide et client

Prérequis

Installation

Clé API et scopes

Créer le client

Options

Modules

Conventions

L’identifiant d’abord, des données brutes en retour

Applications de workspace

Les identifiants sont encodés

Dates

Timeouts

Compte

Statut de la plateforme

Prochaines étapes

Gérer les applications

Erreurs

Introduction à l'API

Démarrage rapide de la CLI

​Prérequis

​Installation

​Clé API et scopes

​Créer le client

​Options

​Modules

​Conventions

​L’identifiant d’abord, des données brutes en retour

​Applications de workspace

​Les identifiants sont encodés

​Dates

​Timeouts

​Compte

​Statut de la plateforme

​Prochaines étapes

Gérer les applications

Erreurs

Introduction à l'API

Démarrage rapide de la CLI

Prérequis

Installation

Clé API et scopes

Créer le client

Options

Modules

Conventions

L’identifiant d’abord, des données brutes en retour

Applications de workspace

Les identifiants sont encodés

Dates

Timeouts

Compte

Statut de la plateforme

Prochaines étapes