Vaze SDK

@darseen/vaze The official JavaScript/TypeScript SDK for Vaze, a self-hosted, local-first file storage and hosting service. This SDK provides a simple and type-safe way to interact with your Vaze instance's API from your Node.js backend or frontend applications.

Installation

Install the package using your preferred package manager:

npm install @darseen/vaze
# or
yarn add @darseen/vaze
# or
pnpm add @darseen/vaze

Initialization

To use the SDK, you must instantiate the Vaze client. You can provide your configuration either directly through the constructor options or via environment variables. Using Constructor Options

import Vaze from "@darseen/vaze";

const vaze = new Vaze({
  vazeUrl: "http://your-server-ip:3000",
  apiKey: "YOUR_API_KEY",
});

Using Environment Variables

If you set VAZE_URL and VAZE_API_KEY in your environment, you can initialize the client without passing arguments:

import Vaze from "@darseen/vaze";

// Automatically picks up process.env.VAZE_URL and process.env.VAZE_API_KEY
const vaze = new Vaze();

API Documentation

The SDK is divided into two main modules: files and folders. All methods are asynchronous and return a standard ApiResponse object containing either data or an error. Files API Access file-related methods via vaze.files.getAll(options?) Retrieve a paginated list of all files.

• options (optional):
  • limit
  • offset
  • orderBy
  • orderDirection

const { data, error } = await vaze.files.getAll({
  limit: 10,
  orderBy: "createdAt",
  orderDirection: "DESC",
});

if (data) {
  console.log(data.files);
}

getById(id) Retrieve a specific file by its ID.

const { data, error } = await vaze.files.getById("file-id");

getByName(name, options?) Search for files by name. Returns an empty files array when nothing matches.

const { data, error } = await vaze.files.getByName("document.pdf", {
  limit: 5,
});

upload(data) Upload one or multiple files to your Vaze instance.

• data:
  • files (File[]): An array of standard web File objects.
  • folder? (string): The path of the target folder, created if it doesn't exist.

const { data, error } = await vaze.files.upload({
  files,
  folder: "optional-folder-name", // example: "documents" or "projects/work" (supports sub-folders)
});

download(id) Download a file's contents by its ID.

const { data, error } = await vaze.files.download("file-id-123");

if (data) {
  console.log(data.filename); // original file name
  console.log(data.contentType); // e.g. "image/png"
  const buffer = Buffer.from(await data.blob.arrayBuffer());
}

rename(data) Rename an existing file.

• data:
  • id (string): The ID of the file to rename.
  • name (string): The new name for the file.

const { data, error } = await vaze.files.rename({
  id: "file-id-123",
  name: "new-document-name.pdf",
});

delete(id) Delete a file by its ID.

const { data, error } = await vaze.files.delete("file-id-123");

Folders API Access folder-related methods via vaze.folders. get(options?) Retrieve folders and their contents.

• options (optional):
  • id
  • path example: "projects/work"
  • limit
  • offset
  • orderBy
  • orderDirection

const { data, error } = await vaze.folders.get({
  path: "/documents/work",
  limit: 20,
});

if (data) {
  console.log("Files:", data.files);
  console.log("Sub-folders:", data.folders);
}

create(folder) Create a new folder.

• folder: The name or path of the new folder. Example: "projects" or "projects/work"

const { data, error } = await vaze.folders.create("projects/work");

rename(data) Rename an existing folder.

• data:
  • id: The ID of the folder to rename.
  • name: The new name.

const { data, error } = await vaze.folders.rename({
  id: "folder-id-456",
  name: "new-name",
});

delete(id) Delete a folder by its ID.

const { data, error } = await vaze.folders.delete("folder-id");

Health Check

vaze.health() pings the instance to verify connectivity.

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

if (data) {
  console.log(data.message); // "Vaze is running!"
}

Types

This SDK is built with TypeScript and exports all necessary types to ensure type safety in your applications. Types such as File, Folder, ApiResponse, ListOptions, and VazeOptions.