> ## 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 Blob: instalar e criar o cliente

> Instale o @squarecloud/blob e crie um cliente SquareCloudBlob com uma chave de API ou um token de upload. A única opção é maxRetries.

<Info>
  Esta página documenta o **`@squarecloud/blob` v4**. Atualizando da v3? Leia o [guia de migração v3 → v4](/pt-br/sdks/blob/migrating_to_v4).
</Info>

`@squarecloud/blob` é o SDK oficial em JavaScript para o [Blob Storage da Square Cloud](/pt-br/services/blob). Ele cobre todos os endpoints da [API de Blob](/pt-br/blob-reference/authentication), além do [gateway S3](/pt-br/blob-reference/s3-compatibility).

## Requisitos

* **Node.js 20** ou superior, ou qualquer navegador moderno. O SDK usa apenas `fetch`, `FormData` e `Blob`.
* Distribuído como **ESM e CommonJS**, com **zero dependências em tempo de execução**.
* `@aws-sdk/client-s3` é uma **peer dependency opcional**, necessária apenas se você chamar [`s3()`](/pt-br/sdks/blob/s3).

## Instalação

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

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

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

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

## Criando o cliente

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>

<Tabs>
  <Tab title="ESM / TypeScript">
    ```typescript theme={"system"}
    import { SquareCloudBlob } from "@squarecloud/blob";

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>

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

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

Confira o cliente com uma primeira chamada. `stats()` lê o seu uso:

```typescript theme={"system"}
const { usage } = await blob.stats();

console.log(`${usage.objects} objects, ${usage.storage} bytes`);
```

Ele imprime o número de objetos e os bytes que eles ocupam, por exemplo:

```text theme={"system"}
12 objects, 5242880 bytes
```

### Construtor

```typescript theme={"system"}
new SquareCloudBlob(credential, { maxRetries: 2 });
```

| Parâmetro | Tipo | Padrão | Descrição |
| - | - | - | - |
| `credential` | `string` | obrigatório | Uma **chave de API**, ou um **token de upload** (`squp_...`) que só pode chamar `put()`. |
| `options.maxRetries` | `number` | `2` | Quantas vezes uma requisição segura para repetir (um `GET` ou uma parte de multipart) é tentada novamente após um erro de rede ou um `5xx`. `0` desativa as novas tentativas. Veja [Política de novas tentativas](/pt-br/sdks/blob/errors#política-de-novas-tentativas). |

## Credenciais

A credencial é enviada **como está** no header `Authorization`, sem o prefixo `Bearer`.

| Credencial | De onde vem | O que pode fazer |
| - | - | - |
| Chave de API | [Dashboard da Square Cloud](https://squarecloud.app/pt-br/account/security) | Todos os métodos, sujeitos aos seus [escopos](/pt-br/blob-reference/authentication#escopos) `blob:read` / `blob:write`. |
| Token de upload (`squp_...`) | [`blob.uploadTokens.create()`](/pt-br/sdks/blob/uploads#upload-a-partir-do-navegador), no seu servidor | Apenas `put()`. Qualquer outro método falha com `403 UPLOAD_TOKEN_NOT_ALLOWED`. |

<Warning>
  Nunca envie uma chave de API para um navegador. Gere um token de upload no seu servidor e entregue apenas o token ao cliente.
</Warning>

## O que você não pode configurar

`maxRetries` é a **única** opção. O cliente não aceita:

* **Uma URL base.** Ela é fixa em `https://blob.squarecloud.app/v1/`.
* **Um `fetch` personalizado.** As requisições usam o `fetch` global.
* **Um timeout ou um `AbortSignal`.** Uma chamada dura o tempo que o `fetch` esperar, e não há como cancelá-la.
* **Headers personalizados.**

## Métodos

Todo método retorna dados simples (sem classes), exceto `s3()`, que retorna um `S3Client`. Opções e resultados usam os próprios nomes de campos da API, em sua maioria em snake\_case (`security_hash`, `expires_at`), então a [referência da API de Blob](/pt-br/blob-reference/authentication) se aplica diretamente.

| Grupo | Métodos | Página |
| - | - | - |
| `blob` | `put(file, options)` | [Uploads](/pt-br/sdks/blob/uploads) |
| `blob.uploadTokens` | `create(options)` | [Uploads](/pt-br/sdks/blob/uploads#upload-a-partir-do-navegador) |
| `blob` | `list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)` | [Objetos](/pt-br/sdks/blob/objects) |
| `blob.shares` | `create(object, options)`, `list()`, `revoke(id)` | [Compartilhamento](/pt-br/sdks/blob/sharing) |
| `blob.rules` / `blob` | `get()`, `set(rules)` / `stats()` | [Regras e estatísticas](/pt-br/sdks/blob/rules_and_stats) |
| `blob` | `s3Credentials()`, `s3()` | [S3](/pt-br/sdks/blob/s3) |

O pacote também exporta `SquareCloudBlobError`, o tipo `BlobErrorCode` e todos os tipos de opções e resultados (`PutOptions`, `PutResult`, `ListedObject`, `ObjectInfo`, `Share`, `Rule`, ...). Veja [Erros](/pt-br/sdks/blob/errors).

## Ids de objetos

Todo objeto é identificado por um **id opaco**, como `pub/...` para um objeto público ou `prv/...` para um privado.

* **Armazene o id exatamente como retornado.** Nunca monte um manualmente e nunca o interprete.
* **Alterar `private` ou `expire` altera o id.** Sempre substitua o id armazenado pelo que [`update()`](/pt-br/sdks/blob/objects#atualizando-objetos) retorna.
* **Use a `url` da resposta** em vez de montar URLs. Objetos privados têm `url: null`: obtenha um link com [`downloadUrl()`](/pt-br/sdks/blob/objects#links-de-download) ou um [compartilhamento](/pt-br/sdks/blob/sharing).

```typescript theme={"system"}
const { id, url } = await blob.put("./photo.png", { name: "photo", prefix: "avatars" });
// save `id` as-is; use `url` to serve the file
```

## Próximos passos

<CardGroup cols={3}>
  <Card title="Uploads" icon="upload" href="/pt-br/sdks/blob/uploads">
    Envie arquivos e gere tokens de upload.
  </Card>

  <Card title="Guia rápido da API do Blob" icon="code" href="/pt-br/blob-reference/quickstart">
    URL base e um primeiro upload com curl.
  </Card>

  <Card title="Planos do Blob Storage" icon="box-archive" href="/pt-br/services/blob">
    O que cada plano inclui.
  </Card>
</CardGroup>


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