@squarecloud/blob

Official Square Cloud Blob SDK for NodeJS.

Installation

npm install @squarecloud/blob
# or
yarn add @squarecloud/blob
# or
pnpm add @squarecloud/blob

Requires Node.js 20 or newer.

Documentation

Visit our official API documentation for more information about this service.

Getting Started

• Login and get your API Key at https://squarecloud.app/account.

import { SquareCloudBlob } from "@squarecloud/blob"
// CommonJS => const { SquareCloudBlob } = require("@squarecloud/blob");

const blob = new SquareCloudBlob("Your API Key")
const { objects } = await blob.objects.list()

Listing objects

Listing is paginated: when continuationToken is returned, pass it back to fetch the next page. The listing is cached server-side for ~30 minutes, so changes made outside the SDK may take a while to show up.

let page = await blob.objects.list({ prefix: "my_prefix" }) // prefix is optional
console.log(page.objects)

while (page.continuationToken) {
  page = await blob.objects.list({ continuationToken: page.continuationToken })
  console.log(page.objects)
}

Creating an object

• Check supported file types here.
• Uploading requires a paid plan.

const blobObject = await blob.objects.create({
  file: "path/to/file.png", // Absolute path to your file
  name: "my_image",         // File name without extension (a-z, A-Z, 0-9, _, 3-32 chars)
  prefix: "my_prefix",      // Optional prefix (same pattern as name)
  expiresIn: 30,            // Optional expiration in days (1-365)
  securityHash: true,       // Optional: append a security hash to the file name
  autoDownload: true,       // Optional: public URL downloads the file instead of rendering it
})

console.log(blobObject.url)

Note

For safety reasons, text/html and image/svg+xml files are always stored as application/octet-stream: their public URL downloads the file instead of rendering it inline.

Files must be between 1 KiB and 100 MB. The API allows at most 4 concurrent uploads per user — the SDK queues uploads to respect this limit and automatically retries with backoff when the API reports too many concurrent uploads.

Advanced usage with Buffer

import { MimeTypes } from "@squarecloud/blob"
// CommonJS => const { MimeTypes } = require("@squarecloud/blob")

const blobObject = await blob.objects.create({
  file: Buffer.from("content"),
  name: "my_image",
  mimeType: MimeTypes.IMAGE_JPEG, // Also accepts an string "image/jpeg"
})

console.log(blobObject.url)

Deleting object

Accepts the object id (userId/key) or its public URL. Deleting an object that does not exist throws an error with code OBJECT_NOT_FOUND. The API deletes one object per request — to delete many, call it for each object sequentially.

await blob.objects.delete("ID/prefix/name1_xxx-xxx.mp4")

Checking account stats

Returns the number of objects, storage used and the price estimate for your account. Cached server-side for 60 seconds.

const stats = await blob.stats()

console.log(stats.usage.objects)         // Total objects in your account
console.log(stats.usage.storage)         // Storage used, in bytes
console.log(stats.billing.totalEstimate) // Price estimate, in BRL

Handling errors

API and validation errors throw SquareCloudBlobError, which exposes the raw API error code via error.code:

import { SquareCloudBlobError } from "@squarecloud/blob"

try {
  await blob.objects.delete("ID/my_file.png")
} catch (error) {
  if (error instanceof SquareCloudBlobError && error.code === "OBJECT_NOT_FOUND") {
    // Already gone
  }
}

Extras

Mime types handling

• Check supported file types here.

import { MimeTypeUtil } from "@squarecloud/blob"

// Get a supported mime type from a file extension
console.log(MimeTypeUtil.fromExtension("jpeg"))   // "image/jpeg"       | Supported
console.log(MimeTypeUtil.fromExtension("json"))   // "application/json" | Supported
console.log(MimeTypeUtil.fromExtension("potato")) // "text/plain"       | Unsupported, defaults to text/plain

Contributing

Feel free to contribute with suggestions or bug reports at our GitHub repository.

Authors

• @joaotonaco
• @JoaoOtavioS