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

# Cliente

> A classe SquareCloudAPI é o ponto de entrada do SDK. Ela é instanciada com uma chave de API e expõe todos os módulos — aplicações, bancos de dados, workspaces, usuário e status da plataforma — através de um único cliente.

<Info>
  Esta página documenta o **`@squarecloud/api` v4**. Se você está migrando da v3, leia primeiro o [guia de migração v3 → v4](/pt-br/sdks/js/migrating_to_v4).
</Info>

## Requisitos

* **Node.js 20.0.0** ou superior
* Uma chave de API válida — solicite uma no [Dashboard da Square Cloud](https://squarecloud.app/pt-br/dashboard)

## Instalação

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

## Instanciando o 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>

### Construtor

| Parâmetro | Tipo     | Obrigatório | Descrição                                                                                |
| --------- | -------- | ----------- | ---------------------------------------------------------------------------------------- |
| `apiKey`  | `string` | Sim         | Sua chave de API da Square Cloud. O cliente lança um erro se o valor não for uma string. |

## Módulos

O cliente expõe toda a plataforma v2 por meio de módulos dedicados. Cada módulo é uma propriedade da instância `SquareCloudAPI`.

| Propriedade        | Módulo                                             | Documentação                                                  |
| ------------------ | -------------------------------------------------- | ------------------------------------------------------------- |
| `api.user`         | Usuário autenticado, plano, apps e bancos próprios | Esta página                                                   |
| `api.applications` | Listar, buscar, enviar e inspecionar aplicações    | [Gerenciando aplicações](/pt-br/sdks/js/managing_application) |
| `api.databases`    | Criar, buscar e gerenciar bancos de dados          | [Bancos de dados](/pt-br/sdks/js/databases)                   |
| `api.workspaces`   | Criar, listar e gerenciar workspaces               | [Workspaces](/pt-br/sdks/js/workspaces)                       |
| `api.service`      | Status agregado da plataforma                      | Esta página                                                   |
| `api.cache`        | Cache em memória atualizado por eventos do SDK     | Esta página                                                   |

## Obtendo o usuário autenticado

`api.user.get()` retorna uma instância de [`User`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/user.ts) contendo os dados da conta, o plano atual, as aplicações e os bancos pertencentes ao usuário.

```typescript theme={null}
const user = await api.user.get();

console.log(user.id);          // "abcdef0123456789abcdef01"
console.log(user.name);        // "João da Silva"
console.log(user.email);       // "joao@example.com"
console.log(user.locale);      // "pt-BR"
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` são instâncias de [`Collection`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/collection.ts) (uma subclasse de `Map`). Itere normalmente:

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

## Buscando uma aplicação específica

Use `api.applications.fetch(id)` para obter uma `Application` (ou `WebsiteApplication`, quando a aplicação possui domínio web) totalmente populada.

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

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

if (app.isWebsite()) {
    // tipo refinado para WebsiteApplication — `.network` está disponível
    await app.network.purgeCache();
}
```

A sobrecarga legada `api.applications.get(id)` ainda existe, mas retorna o `BaseApplication` mais simples e é mantida apenas por compatibilidade. **Prefira `.fetch()` na v4.**

## Listando histórico de snapshots da conta

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

Veja [Snapshots](/pt-br/sdks/js/snapshots) para detalhes do payload.

## Status da plataforma

`api.service.status()` expõe o status agregado da plataforma (mesmos dados da página pública de status).

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

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // resumo legível
```

<Note>
  Diferente da maioria dos endpoints v2, esta rota **não** envolve o payload no envelope padrão `{ status, response }`.
</Note>

## Cache do cliente

O cliente mantém um cache em memória que o SDK mantém sincronizado:

```typescript theme={null}
api.cache.user;   // último User buscado
// cada aplicação expõe também app.cache.status / .logs / .snapshots
```

O SDK emite eventos tipados aos quais você pode se inscrever:

```typescript theme={null}
api.on("userUpdate", (previous, current) => {
    console.log("usuário alterado:", current.name);
});

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

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

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

## Tratamento de erros

Requisições que falham lançam `SquareCloudAPIError`. O erro expõe uma propriedade `code` estável para você diferenciar os tipos de falha.

```typescript theme={null}
import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

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