JavaScript SDK

The official type-safe JavaScript/TypeScript client for SuperFiles.

JavaScript SDK

files-sdk-superfiles is the official JavaScript / TypeScript client for SuperFiles. It works in Node.js, Bun, Deno, and modern browsers (via a bundler).

Installation

npm install files-sdk-superfiles
# or
pnpm add files-sdk-superfiles
# or
yarn add files-sdk-superfiles

Initialise the client

import { SuperFilesClient } from "files-sdk-superfiles";

const sf = new SuperFilesClient({
  baseUrl: "https://api.superfiles.montr.online",  // or your self-hosted URL
  apiKey: process.env.SUPERFILES_API_KEY,
});

The client infers the base URL from SUPERFILES_API_URL and the API key from SUPERFILES_API_KEY if you omit them:

// env vars only
const sf = new SuperFilesClient();

Buckets

List buckets

const { buckets } = await sf.buckets.list();

Create a bucket

const bucket = await sf.buckets.create({
  name: "my-media",
  public: false,
});

Get a bucket

const bucket = await sf.buckets.get("my-media");

Update a bucket

const bucket = await sf.buckets.update("my-media", { public: true });

Delete a bucket

await sf.buckets.delete("my-media");

Storage

Upload a file (Node.js)

import fs from "node:fs";

const result = await sf.storage.upload("my-bucket", "images/avatar.jpg", {
  body: fs.createReadStream("./avatar.jpg"),
  contentType: "image/jpeg",
});

console.log(result.url); // CDN URL (if bucket is public)

Upload from a Buffer

const result = await sf.storage.upload("my-bucket", "docs/report.pdf", {
  body: Buffer.from(pdfBytes),
  contentType: "application/pdf",
});

Download a file

const response = await sf.storage.download("my-bucket", "images/avatar.jpg");
const buffer = Buffer.from(await response.arrayBuffer());

Presigned upload URL (client-side uploads)

Generate a short-lived URL your client can POST to directly — the API key never leaves the server:

// Server-side
const { url, fields } = await sf.storage.presignUpload("my-bucket", "uploads/photo.jpg", {
  contentType: "image/jpeg",
  expiresIn: 300, // 5 minutes
});

// Send `url` + `fields` to the browser

// Browser-side
const form = new FormData();
for (const [key, value] of Object.entries(fields)) {
  form.append(key, value);
}
form.append("file", file);
await fetch(url, { method: "POST", body: form });

Presigned download URL

const { url } = await sf.storage.presignDownload("my-bucket", "private/doc.pdf", {
  expiresIn: 3600,
});

Delete an object

await sf.storage.delete("my-bucket", "images/old-avatar.jpg");

List objects

const { items, nextCursor } = await sf.storage.list("my-bucket", {
  prefix: "images/",
  limit: 50,
});

Copy / move

// Copy
await sf.storage.copy("my-bucket", "images/original.jpg", "my-bucket", "images/copy.jpg");

// Move / rename
await sf.storage.move("my-bucket", "images/old-name.jpg", "my-bucket", "images/new-name.jpg");

CDN

Build a CDN URL

const url = sf.cdn.buildUrl("my-bucket", "photos/hero.jpg", {
  width: 1200,
  height: 630,
  fit: "cover",
  format: "webp",
  quality: 85,
});
// → "https://cdn.superfiles.montr.online/my-bucket/photos/hero.jpg?w=1200&h=630&fit=cover&format=webp&q=85"

Invalidate CDN cache

await sf.cdn.invalidate("my-bucket", "photos/hero.jpg");

API Keys

// List
const { keys } = await sf.apiKeys.list();

// Create
const key = await sf.apiKeys.create({
  name: "CI/CD deploy key",
  scopes: ["storage:read", "storage:write"],
});
console.log(key.key); // sf_live_... shown only once!

// Revoke
await sf.apiKeys.revoke(key.id);

Create a public share link for a file or folder (no API key required to access):

const share = await sf.shares.create({
  bucket: "my-bucket",
  prefix: "reports/q4/",
  expiresIn: 86400 * 7, // 7 days
});

console.log(share.url); // https://api.superfiles.montr.online/share/<token>

Error handling

All methods throw a SuperFilesError on non-2xx responses:

import { SuperFilesError } from "files-sdk-superfiles";

try {
  await sf.storage.download("my-bucket", "missing.txt");
} catch (err) {
  if (err instanceof SuperFilesError) {
    console.error(err.code);    // e.g. "storage.object_not_found"
    console.error(err.status);  // 404
    console.error(err.message);
  }
}