Storage

pb.storage is an instance of PulsaStorage. It uses a 3-step presigned URL flow — no files pass through the Pulsabase API server directly.

upload(filename, file, options?)

Upload a file. The SDK handles the full presigned URL flow automatically.

// From a file input (browser)
const fileInput = document.getElementById('file') as HTMLInputElement;
const file = fileInput.files![0];
const obj = await pb.storage.upload(file.name, file, {
  path: 'data/public',            // or 'data/private'
  contentType: 'image/jpeg',      // auto-detected if omitted
});

console.log(obj.id);  // UUID — store this in your database

From Node.js / React Native:

import fs from 'fs';
const buffer = fs.readFileSync('./avatar.jpg');
const obj = await pb.storage.upload('avatar.jpg', buffer, { path: 'data/public' });

Options

Property	Type	Default	Description
path	string	'data/public'	Storage path / folder slug
contentType	string	'application/octet-stream'	MIME type

Returns: StorageObject

{
  id: string;           // UUID — use this to reference the file
  project_id: string;
  path: string;
  filename: string;
  s3_key: string;       // Internal S3 key (for reference only)
  content_type: string;
  size: number;         // bytes
  owner_id?: string;    // User ID if authenticated
  created_at: string;
  updated_at: string;
}

---

download(objectId)

Get a presigned download URL for a stored file.

const { presigned_url, expires_in_seconds, object } = await pb.storage.download(objectId);

// Download in browser
window.open(presigned_url);

Returns:

{
  presigned_url: string;     // Temporary direct URL (typically valid 1h)
  expires_in_seconds: number;
  object: StorageObject;
}

---

downloadBlob(objectId)

Download the file content directly as a Blob. Convenience wrapper around download().

const blob = await pb.storage.downloadBlob(objectId);
const url = URL.createObjectURL(blob);

---

list(options?)

List stored files for the current project.

const { objects, total } = await pb.storage.list({
  path: 'data/public',
  limit: 50,
  offset: 0,
});

Option	Type	Description
path	string	Filter by folder path
limit	number	Number of results (default: 100)
offset	number	Pagination offset

---

remove(objectId)

Delete a file by its UUID.

await pb.storage.remove(objectId);

---

usage()

Get storage usage statistics for the current project.

const stats = await pb.storage.usage();
// {
//   used_bytes: 1048576,
//   max_bytes: 5368709120,
//   object_count: 42,
//   used_percent: 0.019
// }

---

How the Upload Flow Works

1. POST /storage/upload → IDP validates permissions → returns presigned_url + s3_key
2. PUT {presigned_url} → file goes directly to MinIO/S3 (never through Pulsabase API)
3. POST /storage/upload/confirm → records metadata (size, path, owner) in the database

This pattern allows large file uploads without overloading the API server.