> ## 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 de Blob: instalar y crear el cliente

> Instala @squarecloud/blob y crea un cliente SquareCloudBlob con una clave de API o un token de subida. La única opción es maxRetries.

<Info>
  Esta página documenta **`@squarecloud/blob` v4**. ¿Actualizas desde la v3? Lee la [guía de migración v3 → v4](/es/sdks/blob/migrating_to_v4).
</Info>

`@squarecloud/blob` es el SDK oficial de JavaScript para [Square Cloud Blob Storage](/es/services/blob). Cubre todos los endpoints de la [API de Blob](/es/blob-reference/authentication), además del [gateway S3](/es/blob-reference/s3-compatibility).

## Requisitos

* **Node.js 20** o más reciente, o cualquier navegador moderno. El SDK solo usa `fetch`, `FormData` y `Blob`.
* Se distribuye como **ESM y CommonJS**, **sin dependencias en tiempo de ejecución**.
* `@aws-sdk/client-s3` es una **peer dependency opcional**, solo necesaria si llamas a [`s3()`](/es/sdks/blob/s3).

## Instalación

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

## Crear el cliente

Los ejemplos leen la clave de la variable de entorno `SQUARECLOUD_API_KEY`. Defínela en la terminal donde los ejecutes:

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

Comprueba el cliente con una primera llamada. `stats()` lee tu uso:

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

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

Imprime el número de objetos y los bytes que ocupan, por ejemplo:

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

### Constructor

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

| Parámetro | Tipo | Valor por defecto | Descripción |
| - | - | - | - |
| `credential` | `string` | obligatorio | Una **clave de API**, o un **token de subida** (`squp_...`) que solo puede llamar a `put()`. |
| `options.maxRetries` | `number` | `2` | Cuántas veces se reintenta una petición que es seguro repetir (un `GET` o una parte de multipart) tras un error de red o un `5xx`. `0` desactiva los reintentos. Consulta [Política de reintentos](/es/sdks/blob/errors#política-de-reintentos). |

## Credenciales

La credencial se envía **tal cual** en el encabezado `Authorization`, sin el prefijo `Bearer`.

| Credencial | De dónde viene | Qué puede hacer |
| - | - | - |
| Clave de API | [Panel de Square Cloud](https://squarecloud.app/es/account/security) | Todos los métodos, sujetos a sus [scopes](/es/blob-reference/authentication#scopes) `blob:read` / `blob:write`. |
| Token de subida (`squp_...`) | [`blob.uploadTokens.create()`](/es/sdks/blob/uploads#subir-desde-el-navegador), en tu servidor | Solo `put()`. Cualquier otro método falla con `403 UPLOAD_TOKEN_NOT_ALLOWED`. |

<Warning>
  Nunca envíes una clave de API a un navegador. Genera un token de subida en tu servidor y entrega al cliente solo el token.
</Warning>

## Lo que no puedes configurar

`maxRetries` es la **única** opción. El cliente no acepta:

* **Una URL base.** Está fijada en `https://blob.squarecloud.app/v1/`.
* **Un `fetch` personalizado.** Las peticiones usan el `fetch` global.
* **Un timeout ni un `AbortSignal`.** Una llamada dura lo que espere `fetch`, y no hay forma de cancelarla.
* **Encabezados personalizados.**

## Métodos

Todos los métodos devuelven datos planos (sin clases), salvo `s3()`, que devuelve un `S3Client`. Las opciones y los resultados usan los nombres de campo de la propia API, casi siempre en snake\_case (`security_hash`, `expires_at`), así que la [referencia de la API de Blob](/es/blob-reference/authentication) se aplica tal cual.

| Grupo | Métodos | Página |
| - | - | - |
| `blob` | `put(file, options)` | [Subidas](/es/sdks/blob/uploads) |
| `blob.uploadTokens` | `create(options)` | [Subidas](/es/sdks/blob/uploads#subir-desde-el-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](/es/sdks/blob/objects) |
| `blob.shares` | `create(object, options)`, `list()`, `revoke(id)` | [Compartir](/es/sdks/blob/sharing) |
| `blob.rules` / `blob` | `get()`, `set(rules)` / `stats()` | [Reglas y estadísticas](/es/sdks/blob/rules_and_stats) |
| `blob` | `s3Credentials()`, `s3()` | [S3](/es/sdks/blob/s3) |

El paquete también exporta `SquareCloudBlobError`, el tipo `BlobErrorCode` y todos los tipos de opciones y resultados (`PutOptions`, `PutResult`, `ListedObject`, `ObjectInfo`, `Share`, `Rule`, ...). Consulta [Errores](/es/sdks/blob/errors).

## IDs de objeto

Cada objeto se identifica con un **id opaco**, como `pub/...` para un objeto público o `prv/...` para uno privado.

* **Guarda el id exactamente como se devuelve.** Nunca construyas uno a mano ni lo analices.
* **Cambiar `private` o `expire` cambia el id.** Reemplaza siempre el id que tengas guardado por el que devuelve [`update()`](/es/sdks/blob/objects#actualizar-objetos).
* **Usa la `url` de la respuesta** en lugar de construir URLs. Los objetos privados tienen `url: null`: obtén un enlace con [`downloadUrl()`](/es/sdks/blob/objects#enlaces-de-descarga) o con un [enlace compartido](/es/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 pasos

<CardGroup cols={3}>
  <Card title="Subidas" icon="upload" href="/es/sdks/blob/uploads">
    Sube archivos y genera tokens de subida.
  </Card>

  <Card title="Inicio rápido de la API de Blob" icon="code" href="/es/blob-reference/quickstart">
    URL base y una primera subida con curl.
  </Card>

  <Card title="Planes de Blob Storage" icon="box-archive" href="/es/services/blob">
    Lo que incluye cada plan.
  </Card>
</CardGroup>


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