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

# SDK JavaScript: início rápido e cliente

> Instale o SDK JavaScript (@squarecloud/api v6), crie um cliente com sua chave de API e siga as convenções: ids, aplicações de workspace e timeouts.

<Info>
  Esta página documenta o **`@squarecloud/api` v6**, uma reescrita do SDK. Vindo da v5? Leia o [guia de migração v5 → v6](/pt-br/sdks/js/migrating_to_v6).
</Info>

## Requisitos

* **Node.js 22** ou superior, **Deno**, **Bun** ou um edge runtime. O SDK precisa apenas de `fetch`, `FormData`, `Blob` e web streams.
* Uma chave de API (veja [Chave de API e escopos](#chave-de-api-e-escopos)).

O pacote inclui builds ESM e CommonJS, não tem **nenhuma dependência em tempo de execução** e traz seus próprios tipos TypeScript: você não precisa mais do `@squarecloud/api-types`.

## Instalação

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

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

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

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

  <Tab title="deno">
    ```bash theme={"system"}
    deno add npm:@squarecloud/api
    ```
  </Tab>
</Tabs>

## Chave de API e escopos

Crie uma chave em [squarecloud.app/account/security](https://squarecloud.app/pt-br/account/security). O SDK a envia como está no header `Authorization` (sem o prefixo `Bearer`).

Uma chave pode ser limitada a **escopos** (`apps:read`, `apps:deploy`, `apps:control`, `ai:chat`, ...) e a aplicações ou bancos de dados específicos:

* Uma chamada fora desses limites lança um [`SquareCloudAPIError`](/pt-br/sdks/js/errors) com 403 `MISSING_SCOPE` ou `RESOURCE_NOT_ALLOWED`.
* Métodos de listagem (`account.me()`, `apps.statusAll()`, ...) retornam apenas os recursos que a chave pode ver.
* Uma chave desconhecida, revogada ou expirada resulta em 401 `ACCESS_DENIED`.

<Warning>
  Mantenha a chave no servidor. O SDK também roda no navegador, mas isso exporia a chave a todos os visitantes.
</Warning>

Os exemplos leem a chave da variável de ambiente `SQUARECLOUD_API_KEY`. Defina-a no terminal em que você vai executá-los:

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={"system"}
    export SQUARECLOUD_API_KEY="your-api-key"
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={"system"}
    $env:SQUARECLOUD_API_KEY = "your-api-key"
    ```
  </Tab>
</Tabs>

## Criando o cliente

<Tabs>
  <Tab title="TypeScript / ESM">
    ```typescript theme={"system"}
    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`);
    ```
  </Tab>

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

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

O primeiro exemplo imprime o nome da sua conta e o número de aplicações que a chave pode ver:

```text theme={"system"}
Hi Jane, you have 3 apps
```

Uma chave vazia ou composta apenas de espaços lança um `TypeError` no construtor, antes de qualquer requisição.

### Opções

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

| Opção | Padrão | Descrição |
| - | - | - |
| `baseUrl` | `https://api.squarecloud.app/v2` | URL base da API. Uma `/` final é removida. Também exportada como `BASE_URL`. |
| `timeoutMs` | `30000` | Timeout **por tentativa**, cobrindo a resposta inteira. Veja [Timeouts](#timeouts). |
| `maxRetries` | `2` | Novas tentativas apenas de falhas seguras (até 3 tentativas). Um valor negativo conta como `0`. Veja [Novas tentativas](/pt-br/sdks/js/errors#novas-tentativas). |
| `userAgent` | `squarecloud-sdk-js/<version>` | Substitui todo o header `User-Agent`. |
| `fetch` | o `fetch` global | Um `fetch` personalizado para proxies, tracing ou testes. |

<Warning>
  A chave de API é armazenada como uma propriedade comum do objeto do cliente. Não use `console.log` nem serialize o cliente.
</Warning>

## Módulos

| Propriedade | Cobre | Página |
| - | - | - |
| `api.account` | `me()`, `snapshots({ scope })` | [Conta](#conta) e [Snapshots](/pt-br/sdks/js/snapshots) |
| `api.service` | `status()` | [Status da plataforma](#status-da-plataforma) |
| `api.apps` | Obter, excluir, status, ciclo de vida, logs, métricas, domínios, load balancers | [Gerenciando aplicações](/pt-br/sdks/js/managing_application) |
| `api.apps.create` / `commit` | Uploads | [Commit e upload](/pt-br/sdks/js/commit_and_upload) |
| `api.apps.files` | Gerenciador de arquivos | [Gerenciando arquivos](/pt-br/sdks/js/managing_files) |
| `api.apps.envs` | Variáveis de ambiente | [Variáveis de ambiente](/pt-br/sdks/js/environment_variables) |
| `api.apps.deploys` | Deploys via webhook e GitHub App | [Deploys](/pt-br/sdks/js/deploys) |
| `api.apps.network` | Analytics, logs, DNS, domínio personalizado, cache | [Rede](/pt-br/sdks/js/network) |
| `api.apps.realtime` | Logs e status ao vivo | [Tempo real](/pt-br/sdks/js/realtime) |
| `api.apps.snapshots` / `api.databases.snapshots` / `api.downloadSnapshot` | Backups | [Snapshots](/pt-br/sdks/js/snapshots) |
| `api.databases` | Bancos de dados gerenciados | [Bancos de dados](/pt-br/sdks/js/databases) |
| `api.workspaces` | Workspaces, membros e aplicações compartilhadas | [Workspaces](/pt-br/sdks/js/workspaces) |
| `api.ai` | `chat()` | [IA](/pt-br/sdks/js/ai) |

Os únicos exports de runtime são `SquareCloudAPI`, `SquareCloudAPIError` e `BASE_URL`. Todos os outros exports (`App`, `RuntimeStats`, `ErrorCode`, ...) são tipos:

```typescript theme={"system"}
import type { App, Snapshot } from "@squarecloud/api";
```

## Convenções

### Ids primeiro, dados simples de volta

Todo método recebe o id do recurso como primeiro argumento e retorna **dados simples** (sem classes, sem cache). Os nomes dos campos são os da própria API (`created_at`, `version_id`, `lastModified`, `joinedAt`, `netIO`, ...), então a [referência da API](/pt-br/api-reference/authentication) se aplica diretamente.

* Mutações resolvem para `void`, a menos que a API retorne dados (`envs.*`, `deploys.setWebhook`, `deploys.linkGithubApp`, `databases.resetCredentials` e os métodos `create`).
* Um resultado string nunca é `undefined`: ele é `""` quando a API não envia nada.
* Listas vêm completas em uma única chamada: não há paginação.

Os métodos são arrow functions, então você pode desestruturá-los:

```typescript theme={"system"}
const { restart, logs } = api.apps;

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

### Aplicações de workspace

Todo `appId` também aceita a forma composta `<appId>-<workspaceId>` para atuar sobre uma aplicação compartilhada com você por meio de um [workspace](/pt-br/sdks/js/workspaces). `workspaces.get()` e `workspaces.list()` retornam ids brutos; você mesmo monta o id composto:

```typescript theme={"system"}
await api.apps.restart(`${appId}-${workspaceId}`);
```

### Ids são codificados

Ids no caminho da URL são codificados com percent-encoding. Um id vazio, `.` ou `..` chegaria a uma rota diferente, então ele falha localmente com `INVALID_ID` (status `0`) antes que qualquer coisa seja enviada. As rotas de workspace enviam seus ids no corpo: nelas, o `INVALID_ID` (400) vem do servidor.

### Datas

Os argumentos `start` e `end` (veja [Rede](/pt-br/sdks/js/network)) aceitam uma string ISO 8601 ou um `Date`. As datas nas respostas permanecem como a API as envia (strings ISO, ou milissegundos Unix onde a API os usa).

## Timeouts

| Chamada | Timeout |
| - | - |
| Todas as outras chamadas | `timeoutMs` (30 s) por tentativa |
| Chamadas que o servidor mantém abertas: `start`/`stop`/`restart` de aplicações, `start`/`stop` de bancos de dados, `databases.create`, `create`/`restore` de snapshots, `ai.chat` | Pelo menos **120 s** (um `timeoutMs` maior prevalece) |
| Uploads (`apps.create`, `apps.commit`), `files.write` acima de 1 MiB, `downloadSnapshot` | Nenhum: passe um `signal` para cancelar |
| `apps.realtime` | Apenas até os headers da resposta chegarem |

Um `timeoutMs` de `0` ou menos, `Infinity` ou `>= 2^31` desativa **todos** os timeouts, incluindo os mínimos de 120 s.

Apenas cinco métodos aceitam um `AbortSignal`: `apps.create`, `apps.commit`, `files.write`, `apps.realtime` e `downloadSnapshot`.

```typescript theme={"system"}
const controller = new AbortController();
setTimeout(() => controller.abort(), 60_000);

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

Uma chamada abortada rejeita com o `reason` do signal, não com um `SquareCloudAPIError`. Um loop de `realtime()` abortado simplesmente termina.

## Conta

`api.account.me()` retorna o usuário autenticado, além das aplicações e bancos de dados que a chave pode ver.

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

| Campo | Descrição |
| - | - |
| `user` | `id`, `name`, `email`, `locale`, `created_at` e `plan` (`name`, `memory`, `duration`: o Unix ms em que o plano **expira**, `null` se nunca expirar) |
| `applications` | Array de `{ id, name, desc?, ram, lang, domain?, custom?, cluster, created_at }` |
| `databases` | Array de `{ id, name, ram, type, cluster, created_at }` |

`api.account.snapshots({ scope })` lista todos os snapshots da conta: veja [Snapshots](/pt-br/sdks/js/snapshots#snapshots-da-conta).

## Status da plataforma

`api.service.status()` retorna o status público da plataforma. A rota não exige uma chave válida, mas o cliente ainda requer uma chave não vazia.

```typescript theme={"system"}
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` significa que a própria verificação não pôde ser executada: não é evidência de uma indisponibilidade.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Gerenciando aplicações" icon="server" href="/pt-br/sdks/js/managing_application">
    Status, ciclo de vida, logs e métricas.
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/pt-br/sdks/js/errors">
    Classe de erro, novas tentativas e rate limits.
  </Card>

  <Card title="Introdução à API" icon="code" href="/pt-br/api-reference/introduction">
    URL base, autenticação e uma primeira requisição.
  </Card>

  <Card title="Início rápido da CLI" icon="terminal" href="/pt-br/cli-reference/quickstart">
    Faça deploy e gerencie aplicações pelo terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.