Blob SDK: install and create the client

Install @squarecloud/blob and create a SquareCloudBlob client with an API key or an upload token. The only option is maxRetries.

This page documents @squarecloud/blob v4. Upgrading from v3? Read the v3 → v4 migration guide.

@squarecloud/blob is the official JavaScript SDK for Square Cloud Blob Storage. It covers every Blob API endpoint plus the S3 gateway.

Requirements

• Node.js 20 or newer, or any modern browser. The SDK only uses fetch, FormData and Blob.
• Ships as ESM and CommonJS, with zero runtime dependencies.
• @aws-sdk/client-s3 is an optional peer dependency, only needed if you call s3().

Installation

npm

npm install @squarecloud/blob

yarn

yarn add @squarecloud/blob

pnpm

pnpm add @squarecloud/blob

bun

bun add @squarecloud/blob

Creating the client

The examples read the key from the SQUARECLOUD_API_KEY environment variable. Set it in the terminal where you run them:

macOS / Linux

export SQUARECLOUD_API_KEY="your-api-key"

Windows (PowerShell)

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

ESM / TypeScript

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

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

CommonJS

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

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

Check the client with a first call. stats() reads your usage:

const { usage } = await blob.stats();

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

It prints the number of objects and the bytes they use, for example:

12 objects, 5242880 bytes

Constructor

new SquareCloudBlob(credential, { maxRetries: 2 });

Parameter	Type	Default	Description
credential	string	required	An API key, or an upload token (squp_...) that can only call put().
options.maxRetries	number	2	How many times a safe-to-repeat request (a GET or a multipart part) is retried after a network error or a 5xx. 0 disables retries. See Retry policy.

Credentials

The credential is sent as-is in the Authorization header, with no Bearer prefix.

Credential	Where it comes from	What it can do
API key	Square Cloud dashboard	Every method, subject to its blob:read / blob:write scopes.
Upload token (squp_...)	blob.uploadTokens.create(), on your server	Only put(). Any other method fails with 403 UPLOAD_TOKEN_NOT_ALLOWED.

Never ship an API key to a browser. Mint an upload token on your server and hand only the token to the client.

What you cannot configure

maxRetries is the only option. The client does not accept:

• A base URL. It is fixed at https://blob.squarecloud.app/v1/.
• A custom fetch. Requests use the global fetch.
• A timeout or an AbortSignal. A call lasts as long as fetch waits, and there is no way to cancel it.
• Custom headers.

Methods

Every method returns plain data (no classes), except s3(), which returns an S3Client. Options and results use the API’s own field names, mostly snake_case (security_hash, expires_at), so the Blob API reference applies as-is.

Group	Methods	Page
blob	put(file, options)	Uploads
blob.uploadTokens	create(options)	Uploads
blob	list(options), listPage(options), info(id), downloadUrl(id, options), update(ids, changes), delete(ids), copy(source, destination, options), move(source, destination, options)	Objects
blob.shares	create(object, options), list(), revoke(id)	Sharing
blob.rules / blob	get(), set(rules) / stats()	Rules and stats
blob	s3Credentials(), s3()	S3

The package also exports SquareCloudBlobError, the BlobErrorCode type and every option and result type (PutOptions, PutResult, ListedObject, ObjectInfo, Share, Rule, …). See Errors.

Object ids

Every object is identified by an opaque id, such as pub/... for a public object or prv/... for a private one.

• Store the id exactly as returned. Never build one by hand and never parse it.
• Changing private or expire changes the id. Always replace your stored id with the one update() returns.
• Use the url from the response instead of building URLs. Private objects have url: null: get a link with downloadUrl() or a share.

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

Next steps

Uploads

Upload files and mint upload tokens.

Blob API quickstart

Base URL and a first upload with curl.

Blob Storage plans

What each plan includes.