Blob SDK: prefix rules and usage stats

Read and replace per-prefix Blob Storage rules with @squarecloud/blob (visibility, expiration, size, extensions, auto-delete) and read account usage stats.

Examples use the blob client from Creating the client.

Rules

Rules set defaults and limits for every object under a prefix: visibility, expiration, maximum size, allowed extensions, cache and automatic deletion. They apply to every upload under the prefix, whether it comes from the SDK, an upload token or the dashboard. See Update Settings for plan limits and matching.

rules.get()

const rules = await blob.rules.get();

Returns the saved rules as an array. Each rule has the fields below plus created_at, and active_from when it has delete_after_days.

active_from is optional: the API only sends it for rules with delete_after_days. In TypeScript, handle it being undefined.

rules.set(rules)

await blob.rules.set([
    { prefix: "tmp/", delete_after_days: 7 },
    { prefix: "avatars/", max_size: 5 * 1024 * 1024, extensions: ["png", "jpg"] },
]);

rules.set() replaces the whole list. Send every rule you want to keep; rules.set([]) removes them all. To add one rule, read the list first:

const current = await blob.rules.get();
await blob.rules.set([
    ...current.map(({ created_at, active_from, ...rule }) => rule),
    { prefix: "exports/", expire: "30d" },
]);

It returns the saved list, like rules.get().

Field	Type	Description
prefix	string	Required. The prefix the rule applies to, e.g. "a/b/".
private	boolean	Default visibility.
expire	string	Default expiration ("30d", "168h", …).
max_size	number	Maximum file size in bytes, 512 B to 10 GiB.
extensions	string[]	1 to 50 allowed extensions, matching ^[a-z0-9]{1,16}(\.[a-z0-9]{1,16})?$.
cache_control	string	Default Cache-Control.
delete_after_days	number	Deletes objects this many days after they were written, 7 to 3650 (Enterprise from 1).

delete_after_days only takes effect 24 hours after the rule is saved (see active_from). Once active, deleted objects cannot be recovered.

When a rule is rejected, the error’s extra carries the offending prefix:

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

try {
    await blob.rules.set(rules);
} catch (error) {
    if (error instanceof SquareCloudBlobError) {
        console.error(error.code, error.extra.prefix);
    }
}

rules.get() is a read and is retried. rules.set() gets a single attempt.

Stats

const stats = await blob.stats();

console.log(stats.usage.objects); // total objects
console.log(stats.usage.storage); // storage used, in bytes

Field	Description
usage.objects	Number of objects.
usage.storage	Storage used, in bytes.
plan.included	Storage included in your plan, in bytes.
billing	extraStorage, storagePrice, objectsPrice, totalEstimate.
month	days and average_storage for the current month.

Stats are an estimate, cached by the server for 60 seconds. billing is only an estimate of the storage above your plan, not an invoice.

See Account Stats.

Next steps

S3

Reach Blob Storage with any S3 client.

Settings API reference

The REST endpoints behind these methods.