/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.
pnpm add @vol-a/clientThis program reads the live examples instance, using the read-only key that instance hands to every visitor, so you can run it right now:
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");images: 4 filesaurora.jpg 41134 image/jpeg206 bytes 0-1023/41134ready 1960 bytesTwo answers to handle
Section titled “Two answers to handle”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.
What else it covers
Section titled “What else it covers”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