> ## 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 clase SquareCloudAPI es el punto de entrada al SDK. Se instancia con una clave de API y expone cada módulo — aplicaciones, bases de datos, workspaces, usuario y servicio de plataforma — a través de un único cliente.

<Info>
  Esta página documenta **`@squarecloud/api` v4**. Si estás actualizando desde la v3, lee primero la [guía de migración v3 → v4](/es/sdks/js/migrating_to_v4).
</Info>

## Requisitos

* **Node.js 20.0.0** o más reciente
* Una clave de API válida — solicita una en el [Panel de Square Cloud](https://squarecloud.app/es/dashboard)

## Instalación

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

## Instanciar el cliente

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

### Constructor

| Parámetro | Tipo     | Obligatorio | Descripción                                                                           |
| --------- | -------- | ----------- | ------------------------------------------------------------------------------------- |
| `apiKey`  | `string` | Sí          | Tu clave de API de Square Cloud. El cliente lanzará un error si esto no es un string. |

## Módulos

El cliente expone toda la plataforma v2 a través de módulos dedicados. Cada módulo es una propiedad de la instancia de `SquareCloudAPI`.

| Propiedad          | Módulo                                                   | Documentación                                              |
| ------------------ | -------------------------------------------------------- | ---------------------------------------------------------- |
| `api.user`         | Usuario autenticado, plan, apps y bases de datos propias | Esta página                                                |
| `api.applications` | Listar, obtener, subir e inspeccionar aplicaciones       | [Gestionar aplicaciones](/es/sdks/js/managing_application) |
| `api.databases`    | Crear, obtener y gestionar bases de datos                | [Bases de datos](/es/sdks/js/databases)                    |
| `api.workspaces`   | Crear, listar y gestionar workspaces                     | [Workspaces](/es/sdks/js/workspaces)                       |
| `api.service`      | Estado agregado de la plataforma                         | Esta página                                                |
| `api.cache`        | Caché en memoria poblada por eventos del SDK             | Esta página                                                |

## Obtener el usuario autenticado

`api.user.get()` devuelve una instancia de [`User`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/user.ts) que contiene los detalles de la cuenta, el plan actual, las aplicaciones propias y las bases de datos propias.

```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` y `user.databases` son instancias de [`Collection`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/collection.ts) (una subclase de `Map`). Itéralas como cualquier `Map`:

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

## Obtener una sola aplicación

Usa `api.applications.fetch(id)` para recuperar una `Application` completamente poblada (o `WebsiteApplication`, cuando la app tiene un dominio de sitio web).

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

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

if (app.isWebsite()) {
    // acotado a WebsiteApplication — `.network` está disponible
    await app.network.purgeCache();
}
```

La sobrecarga heredada `api.applications.get(id)` todavía existe, pero devuelve la `BaseApplication` más ligera y solo se conserva por compatibilidad con versiones anteriores. **Prefiere `.fetch()` para v4.**

## Listar el historial de snapshots (a nivel de cuenta)

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

Consulta [Snapshots](/es/sdks/js/snapshots) para más detalles sobre los payloads de snapshots.

## Estado de la plataforma

`api.service.status()` expone el estado de salud agregado de la plataforma (los mismos datos que se muestran en la página de estado pública).

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

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // resumen legible para humanos
```

<Note>
  A diferencia de la mayoría de los endpoints v2, esta ruta **no** envuelve su payload en el sobre estándar `{ status, response }`.
</Note>

## Caché del cliente

El cliente mantiene una caché en memoria que el SDK mantiene sincronizada a medida que realizas llamadas:

```typescript theme={null}
api.cache.user;   // último User obtenido
// cada instancia de aplicación también expone app.cache.status / .logs / .snapshots
```

El SDK emite eventos tipados a los que puedes suscribirte:

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

## Manejo de errores

Las solicitudes fallidas lanzan un `SquareCloudAPIError`. El error expone una propiedad `code` estable sobre la que puedes hacer un switch para distinguir los modos de fallo.

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