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

# Snapshots

> Liste, crie, baixe e restaure snapshots da aplicação.

<Info>
  `app.backup` / `app.backups` e a classe `Backup` foram removidos. Use `app.snapshots` (o [`SnapshotsModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/snapshots.ts)), cujas entradas são instâncias de `Snapshot` (`DatabaseSnapshot` para snapshots de banco de dados).
</Info>

`app.snapshots` expõe o [`SnapshotsModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/snapshots.ts).

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

## Limites de taxa

* Os resultados de `app.snapshots.list()` ficam em cache no servidor por **30 minutos**.
* `app.snapshots.create()` (e o equivalente para bancos de dados) é limitado a **1 requisição a cada 5 segundos por usuário** e **1 requisição a cada 3 minutos por recurso** (aplicação ou banco de dados).
* Cada plano também tem uma **cota diária de snapshots**. Quando ela se esgota, a criação falha com `429` e `code: "DAILY_SNAPSHOTS_LIMIT_REACHED"` — diferente do erro genérico de rate limit curto `KEEP_CALM`.

```typescript theme={null}
try {
    await app.snapshots.create();
} catch (error) {
    if (error.code === "DAILY_SNAPSHOTS_LIMIT_REACHED") {
        console.log("Cota diária de snapshots atingida para este plano");
    }
}
```

## Listando snapshots

`app.snapshots.list()` retorna um array de instâncias `Snapshot`.

```typescript theme={null}
const snapshots = await app.snapshots.list();

for (const snap of snapshots) {
    console.log(snap.url);          // URL assinada para download (válida por 30 dias)
    console.log(snap.size);         // bytes
    console.log(snap.modifiedAt);   // Date
    console.log(snap.key);          // query string assinada
}
```

Cada snapshot pode ser baixado diretamente:

```typescript theme={null}
const buffer = await snapshots[0].download();
```

## Criando um novo snapshot

`app.snapshots.create()` dispara um novo snapshot e retorna a URL assinada e a chave.

```typescript theme={null}
const fresh = await app.snapshots.create();
console.log(fresh.url); // válida por 30 dias
console.log(fresh.key);
```

## Download em uma única etapa

`app.snapshots.download()` cria um snapshot e o baixa como `Buffer`.

```typescript theme={null}
import { writeFile } from "node:fs/promises";

const buffer = await app.snapshots.download();
await writeFile("./backup.zip", buffer);
```

## Restaurando a partir de um snapshot

`app.snapshots.restore({ snapshotId, versionId })` reverte a aplicação para uma versão anterior do snapshot.

```typescript theme={null}
await app.snapshots.restore({
    snapshotId: "00000000-0000-4000-8000-000000000000",
    versionId: "abc123def4567890",
});
```

| Campo        | Tipo     | Descrição                                      |
| ------------ | -------- | ---------------------------------------------- |
| `snapshotId` | `string` | Identificador do snapshot (UUID v4)            |
| `versionId`  | `string` | Identificador de versão retornado por `list()` |

## Listando snapshots de toda a conta

`api.user.snapshots(scope?)` retorna todos os snapshots que você possui em todas as aplicações ou bancos de dados. `scope` tem como padrão `"applications"`.

```typescript theme={null}
const appSnapshots = await api.user.snapshots(); // scope padrão é "applications"
const dbSnapshots  = await api.user.snapshots("databases");
```

<Note>
  `api.user.snapshots()` requer um plano pago ativo. Contas sem um plano pago recebem `402` com `code: "UPGRADE_REQUIRED"`.
</Note>