Skip to content

/get-started/client/

Call it with @vol-a/client

@vol-a/client wraps every route in a typed call. It runs in Node 24 and in browsers, and it never puts a key, a token or a secret in a URL.

Terminal
pnpm add @vol-a/client

This program reads the live examples instance, using the read-only key that instance hands to every visitor, so you can run it right now:

read.ts
import { VolaClient } from "@vol-a/client";
// The examples instance's read-only key, the one its site hands to every visitor.
const baseUrl = "https://examples.vol-a.com/vola";
const config = (await (await fetch(`${baseUrl}/examples/config`)).json()) as {
api_key: string;
instance_type: string;
instance_id: string;
};
const vola = new VolaClient({ baseUrl, apiKey: config.api_key });
const { folder, files } = await vola.folders.list(
config.instance_type,
config.instance_id,
"images",
);
console.log(`${folder?.path}: ${files.length} files`);
const file = files.find((f) => f.filename === "aurora.jpg");
if (!file) throw new Error("no aurora.jpg in the demo pack");
console.log(file.filename, file.size, file.mime_type);
// A Range read: a streaming Response with the 206's headers.
const part = await vola.files.download(config.instance_type, config.instance_id, file.id, {
range: { start: 0, end: 1023 },
});
console.log(part.status, part.headers.get("content-range"));
// A thumbnail: 202 is not the image, so the client says which one you got.
const thumb = await vola.files.thumb(config.instance_type, config.instance_id, file.id, 256);
console.log(thumb.status, thumb.status === "ready" ? `${thumb.blob.size} bytes` : "try again");
What it printed
images: 4 files
aurora.jpg 41134 image/jpeg
206 bytes 0-1023/41134
ready 1960 bytes

A thumbnail can answer 202. That status counts as success, and its body is a grey placeholder, so vola.files.thumb tells you which one you got through status: ready, generating or failed. Retry generating with a backoff, and don’t cache it.

A failed call throws a VolaError carrying the server’s status, code and message. A file that needs an unlock it doesn’t have throws VolaLockedError, and a wrong key or damaged bytes throw VolaIntegrityError.

Resumable uploads that continue after an abort, folders, share links, keyrings and their unlock tokens, statistics and UDC collections. The package README has an example of each.

v1.1.0released built 402bea0