SDK de Blob: instalar y crear el cliente

Esta página documenta @squarecloud/blob v4. ¿Actualizas desde la v3? Lee la guía de migración v3 → v4.

@squarecloud/blob es el SDK oficial de JavaScript para Square Cloud Blob Storage. Cubre todos los endpoints de la API de Blob, además del gateway S3.

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().

Instalación

npm
yarn
pnpm
bun

npm install @squarecloud/blob

yarn add @squarecloud/blob

pnpm add @squarecloud/blob

bun add @squarecloud/blob

Crear el cliente

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

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

ESM / TypeScript
CommonJS

import { SquareCloudBlob } from "@squarecloud/blob";

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);

const { SquareCloudBlob } = require("@squarecloud/blob");

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);

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

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:

12 objects, 5242880 bytes

Constructor

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.

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	Todos los métodos, sujetos a sus scopes `blob:read` / `blob:write`.
Token de subida (`squp_...`)	`blob.uploadTokens.create()`, en tu servidor	Solo `put()`. Cualquier otro método falla con `403 UPLOAD_TOKEN_NOT_ALLOWED`.

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.

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 se aplica tal cual.

Grupo	Métodos	Página
`blob`	`put(file, options)`	Subidas
`blob.uploadTokens`	`create(options)`	Subidas
`blob`	`list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)`	Objetos
`blob.shares`	`create(object, options)`, `list()`, `revoke(id)`	Compartir
`blob.rules` / `blob`	`get()`, `set(rules)` / `stats()`	Reglas y estadísticas
`blob`	`s3Credentials()`, `s3()`	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.

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().
Usa la url de la respuesta en lugar de construir URLs. Los objetos privados tienen url: null: obtén un enlace con downloadUrl() o con un enlace compartido.

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

Subidas

Sube archivos y genera tokens de subida.

Inicio rápido de la API de Blob

URL base y una primera subida con curl.

Planes de Blob Storage

Lo que incluye cada plan.

CLI

VS Code

SDKs

SDK de Blob: instalar y crear el cliente

Requisitos

Instalación

Crear el cliente

Constructor

Credenciales

Lo que no puedes configurar

Métodos

IDs de objeto

Próximos pasos

Subidas

Inicio rápido de la API de Blob

Planes de Blob Storage

​Requisitos

​Instalación

​Crear el cliente

​Constructor

​Credenciales

​Lo que no puedes configurar

​Métodos

​IDs de objeto

​Próximos pasos

Subidas

Inicio rápido de la API de Blob

Planes de Blob Storage

Requisitos

Instalación

Crear el cliente

Constructor

Credenciales

Lo que no puedes configurar

Métodos

IDs de objeto

Próximos pasos