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

# Client

> La classe SquareCloudAPI est le point d'entrée du SDK. Elle est instanciée avec une clé d'API et expose chaque module — applications, bases de données, workspaces, utilisateur et service de plateforme — via un client unique.

<Info>
  Cette page documente **`@squarecloud/api` v4**. Si vous effectuez une mise à niveau depuis la v3, lisez d'abord le [guide de migration v3 → v4](/fr/sdks/js/migrating_to_v4).
</Info>

## Prérequis

* **Node.js 20.0.0** ou une version plus récente
* Une clé d'API valide — demandez-en une sur le [tableau de bord Square Cloud](https://squarecloud.app/fr/dashboard)

## Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @squarecloud/api
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @squarecloud/api
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @squarecloud/api
    ```
  </Tab>
</Tabs>

## Instanciation du client

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { SquareCloudAPI } from "@squarecloud/api";

    const api = new SquareCloudAPI(process.env.SQUARE_API_KEY!);
    ```
  </Tab>

  <Tab title="JavaScript (ESM)">
    ```javascript theme={null}
    import { SquareCloudAPI } from "@squarecloud/api";

    const api = new SquareCloudAPI(process.env.SQUARE_API_KEY);
    ```
  </Tab>

  <Tab title="JavaScript (CommonJS)">
    ```javascript theme={null}
    const { SquareCloudAPI } = require("@squarecloud/api");

    const api = new SquareCloudAPI(process.env.SQUARE_API_KEY);
    ```
  </Tab>
</Tabs>

### Constructeur

| Paramètre | Type     | Requis | Description                                                                                          |
| --------- | -------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `apiKey`  | `string` | Oui    | Votre 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é          | Module                                                                    | Documentation                                                |
| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `api.user`         | Utilisateur authentifié, plan, applications et bases de données possédées | Cette page                                                   |
| `api.applications` | Lister, récupérer, envoyer et inspecter les applications                  | [Gestion des applications](/fr/sdks/js/managing_application) |
| `api.databases`    | Créer, récupérer et gérer les bases de données                            | [Bases de données](/fr/sdks/js/databases)                    |
| `api.workspaces`   | Créer, lister et gérer les workspaces                                     | [Workspaces](/fr/sdks/js/workspaces)                         |
| `api.service`      | État global de la plateforme                                              | Cette page                                                   |
| `api.cache`        | Cache en mémoire alimenté par les événements du SDK                       | Cette page                                                   |

## Récupérer l'utilisateur authentifié

`api.user.get()` renvoie une instance [`User`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/user.ts) contenant les détails du compte, le plan actuel, les applications possédées et les bases de données possédées.

```typescript theme={null}
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`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/collection.ts) (une sous-classe de `Map`). Parcourez-les comme n'importe quelle `Map` :

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

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

```typescript theme={null}
const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");
```

Consultez [Snapshots](/fr/sdks/js/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).

```typescript theme={null}
const status = await api.service.status();

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // résumé lisible par un humain
```

<Note>
  Contrairement à la plupart des endpoints v2, cette route n'**enveloppe pas** sa charge utile dans l'enveloppe standard `{ status, response }`.
</Note>

## Cache du client

Le client maintient un cache en mémoire que le SDK garde synchronisé au fil de vos appels :

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

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

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