> ## 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 è il punto di ingresso all'SDK. Viene istanziata con una chiave API ed espone ogni modulo — applicazioni, database, workspace, utente e servizio della piattaforma — tramite un unico client.

<Info>
  Questa pagina documenta **`@squarecloud/api` v4**. Se stai effettuando l'upgrade da v3, leggi prima la [guida alla migrazione v3 → v4](/it/sdks/js/migrating_to_v4).
</Info>

## Requisiti

* **Node.js 20.0.0** o più recente
* Una chiave API valida — richiedine una nella [Dashboard di Square Cloud](https://squarecloud.app/it/dashboard)

## Installazione

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

## Istanziare il 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>

### Costruttore

| Parametro | Tipo     | Obbligatorio | Descrizione                                                                                             |
| --------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| `apiKey`  | `string` | Sì           | La tua chiave API di Square Cloud. Il client solleverà un'eccezione se questo valore non è una stringa. |

## Moduli

Il client espone l'intera piattaforma v2 tramite moduli dedicati. Ogni modulo è una proprietà dell'istanza `SquareCloudAPI`.

| Proprietà          | Modulo                                               | Documentazione                                              |
| ------------------ | ---------------------------------------------------- | ----------------------------------------------------------- |
| `api.user`         | Utente autenticato, piano, app e database posseduti  | Questa pagina                                               |
| `api.applications` | Elenca, recupera, carica e ispeziona le applicazioni | [Gestire le applicazioni](/it/sdks/js/managing_application) |
| `api.databases`    | Crea, recupera e gestisci i database                 | [Database](/it/sdks/js/databases)                           |
| `api.workspaces`   | Crea, elenca e gestisci i workspace                  | [Workspace](/it/sdks/js/workspaces)                         |
| `api.service`      | Stato aggregato della piattaforma                    | Questa pagina                                               |
| `api.cache`        | Cache in memoria popolata dagli eventi dell'SDK      | Questa pagina                                               |

## Ottenere l'utente autenticato

`api.user.get()` restituisce un'istanza [`User`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/user.ts) che contiene i dettagli dell'account, il piano attuale, le applicazioni possedute e i database posseduti.

```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` e `user.databases` sono istanze [`Collection`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/collection.ts) (una sottoclasse di `Map`). Iterale come qualsiasi `Map`:

```typescript theme={null}
for (const [id, app] of user.applications) {
    console.log(`${app.name} (${id}) — ${app.ram}MB ${app.language}`);
}
```

## Recuperare una singola applicazione

Usa `api.applications.fetch(id)` per recuperare un'`Application` completamente popolata (o `WebsiteApplication`, quando l'app ha un dominio del sito web).

```typescript theme={null}
const app = await api.applications.fetch("abc123def456abc123def456");

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

if (app.isWebsite()) {
    // narrowed to WebsiteApplication — `.network` is available
    await app.network.purgeCache();
}
```

L'overload legacy `api.applications.get(id)` esiste ancora, ma restituisce la più leggera `BaseApplication` ed è mantenuto solo per retrocompatibilità. **Preferisci `.fetch()` per v4.**

## Elencare la cronologia degli snapshot (a livello di account)

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

Consulta [Snapshots](/it/sdks/js/snapshots) per i dettagli sui payload degli snapshot.

## Stato della piattaforma

`api.service.status()` espone lo stato di salute aggregato della piattaforma (gli stessi dati mostrati nella pagina di stato pubblica).

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

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // human-readable summary
```

<Note>
  A differenza della maggior parte degli endpoint v2, questa route **non** avvolge il suo payload nella busta standard `{ status, response }`.
</Note>

## Cache del client

Il client mantiene una cache in memoria che l'SDK tiene sincronizzata man mano che effettui chiamate:

```typescript theme={null}
api.cache.user;   // last fetched User
// each application instance also exposes app.cache.status / .logs / .snapshots
```

L'SDK emette eventi tipizzati a cui puoi iscriverti:

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

## Gestione degli errori

Le richieste fallite sollevano un `SquareCloudAPIError`. L'errore espone una proprietà `code` stabile su cui puoi effettuare uno switch per discriminare le modalità di errore.

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