SDK overview

@buckt/sdk is the official TypeScript client for the Buckt API. It wraps every resource the API exposes — buckets, files, keys, AWS accounts, and billing — with strongly typed methods that share a single Buckt instance.

Install

npm install @buckt/sdk

The package ships ESM only. It targets Node 20+ and modern bundlers. No native dependencies, no build step in your project.

Initialize

buckt.ts

import { Buckt } from "@buckt/sdk";

const client = new Buckt({
  apiKey: process.env.BUCKT_API_KEY!,
});

Name	Type	Default	Description
apiKeyrequired	string	—	Server-side API key minted from the dashboard. Starts with `bkt_`. Never ship this to the browser.
baseUrl	string	"https://api.buckt.dev"	Override the API base URL. Useful for testing against a local or staging instance.

Resources

Each resource client lives on the Buckt instance:

buckets — provision, list, update, and delete buckets.
files — upload, list, get, and delete files.
keys — manage API keys.
awsAccounts — connect bring-your-own AWS accounts.
billing — read usage and subscription state.

Pagination

Every list() method returns { data, meta }. meta.nextCursor is the opaque token to pass back as cursor for the next page, or null when the list is exhausted.

let cursor: string | undefined;

do {
  const { data, meta } = await client.buckets.list({ cursor, limit: 50 });
  for (const bucket of data) {
    console.log(bucket.id, bucket.name);
  }
  cursor = meta.nextCursor ?? undefined;
} while (cursor);

The limit option caps the page size (default 25, max 100). Buckt may return fewer rows than limit even when more pages exist — always loop until nextCursor is null.

Errors

Every method throws a typed error subclass on non-2xx responses. See Errors for the full list and how to discriminate them with instanceof.