Overview

@darseen/vaze is the official TypeScript/JavaScript client for the Vaze API. It works in Node.js and any runtime with the Fetch API, and ships with full type definitions.

Installation

npm install @darseen/vaze

Create a client

import Vaze from "@darseen/vaze";

const vaze = new Vaze({
  vazeUrl: "https://files.example.com", // your Vaze instance URL
  apiKey: "your-api-key", // created in the dashboard
});

Both options can also be provided through environment variables, in which case new Vaze() needs no arguments:

Environment variable	Equivalent option
`VAZE_URL`	`vazeUrl`
`VAZE_API_KEY`	`apiKey`

The constructor throws if no URL and no API key or headers can be resolved, so misconfiguration fails fast at startup rather than on the first request.

An app that signs people in can skip API keys and send their session instead. Pass headers, either an object or a function the SDK calls before every request, and leave apiKey out. A session works for every role, while API keys need the api-keys:manage scope.

With Better Auth in an Expo app, hand the SDK the cookie the Expo client stores:

import { expoClient } from "@better-auth/expo/client";
import Vaze from "@darseen/vaze";
import { createAuthClient } from "better-auth/react";
import * as SecureStore from "expo-secure-store";

const auth = createAuthClient({
  baseURL: "https://files.example.com/api/auth",
  plugins: [expoClient({ scheme: "vaze", storage: SecureStore })],
});

const vaze = new Vaze({
  vazeUrl: "https://files.example.com",
  headers: async (): Promise<Record<string, string>> => {
    const cookie = await auth.getCookie();
    return cookie ? { cookie } : {};
  },
  // keep React Native's own cookie jar out of it
  fetch: (input, init) => fetch(input, { ...init, credentials: "omit" }),
});

fetch swaps in your own fetch implementation for every request, which also covers timeouts, retries and logging.

Fetching URLs yourself

Image loaders and download managers fetch outside the SDK. authHeaders() returns the headers the SDK would send, ready to pass along with URLs such as files.thumbnailUrl:

const headers = await vaze.authHeaders();

<Image source={{ uri: vaze.files.thumbnailUrl(file.id), headers }} />;

Response shape

Every SDK method returns the same result envelope instead of throwing on API errors:

type ApiResponse<T> =
  | { data: T; error: null }
  | { data: null; error: { message: string; status?: number } };

status is the HTTP status of a failed request, such as 401 once a session has expired. It is missing when no response arrived at all.

Check error before using data:

const { data, error } = await vaze.files.getAll();

if (error) {
  console.error(error.message);
  return;
}

console.log(data.files); // typed as File[]

Network failures are caught and surfaced the same way, so a single error check covers everything.

Health check

Verify connectivity and that your instance is up:

const { data, error } = await vaze.health();
// data => { message: "Vaze is running!" }

Setup check

A new instance has no accounts until someone registers, and that first account becomes the admin. setupStatus() tells a client which screen to show:

const { data } = await vaze.setupStatus();
// data => { needed: true } until the admin account exists

Current account

me() returns the account behind the client and the scopes it can use, so an app can hide what would fail:

const { data } = await vaze.me();
// data => { user: { id, name, email, image, role }, scopes: ["files:read", ...] }

const canUpload = data?.scopes.includes("files:write");

To change the profile, password or signed-in devices, see vaze.account.

Stats

stats() returns the numbers behind the dashboard's home page: storage, files added per day, public hosting traffic, API key usage, accounts, and alerts for what needs attention. Each section is null when the caller can't see it; see the API reference for the full shape.

const { data } = await vaze.stats();

if (data?.files) {
  console.log(data.files.total, data.files.storage.used);
  console.log(data.files.recent); // File[] with absolute URLs
}

// these fields are absent on servers that predate them
for (const { file, requests } of data?.hosting?.top ?? []) {
  console.log(file.url, requests); // absolute URLs here too
}

for (const alert of data?.alerts ?? []) {
  if (alert.type === "keys-expiring") console.log(`${alert.count} keys expire soon`);
}

Installation

Create a client

Act as a signed-in user

Fetching URLs yourself

Response shape

Health check

Setup check

Current account

Stats

What's next

Files

Folders

Account

API keys

Activity

Users

Instance settings

On this page