TypeScript SDK

File & Folder CRUD Management

Full CRUD operations for files and virtual folders: browse hierarchies, rename/move assets with automatic R2 synchronization, replace binary files in-place, and perform atomic deletions.

Listing Files & Folders (`listContents`)

Retrieve all files, folders, and breadcrumbs in a project root or within a specific virtual subfolder:

examples/list.ts

import { Cloudizero } from "@cloudizero/sdk";

const cz = new Cloudizero({ apiKey: process.env.CLOUDIZERO_API_KEY! });

// Daftar konten root direktori
const rootContents = await cz.storage.listContents({
  projectId: "ca2454ff-7f1e-421b-b134-4c800f6d58de",
});

console.log("Root Folders:", rootContents.folders);
console.log("Root Files:", rootContents.files);

// Daftar konten subfolder spesifik berdasarkan folderId
const folderContents = await cz.storage.listContents({
  projectId: "ca2454ff-7f1e-421b-b134-4c800f6d58de",
  folderId: "3b9c1e2a-4d5f-...",
});

console.log("Current Breadcrumbs:", folderContents.breadcrumbs);

Fetching Asset Metadata (`getFile`)

Fetch relational metadata and obtain a presigned download URL for private assets:

examples/get-file.ts

// Mengambil metadata file dan tautan unduhan presigned sementara
const { file, downloadUrl } = await cz.storage.getFile("f29b8214-7e8c-...");

console.log("File Name:", file.name);
console.log("Size:", file.size);
console.log("Direct Download:", downloadUrl);

Updating & Replacing Files (`updateFile` & `replaceFile`)

Rename files, move them across folders, or replace their binary payload in-place while preserving the same fileId:

examples/update-file.ts

// 1. Pembaruan Metadata (Ubah nama file atau pindahkan ke folder lain)
// Otomatis memindahkan objek terkait di Cloudflare R2 untuk sinkronisasi r2Key & URL CDN
const renamedFile = await cz.storage.updateFile({
  fileId: "f29b8214-7e8c-...",
  name: "hero-banner-2026.webp",
  folderId: "3b9c1e2a-4d5f-...", // atau null / "root" untuk pindah ke root proyek
});

// 2. Penggantian Biner In-Place (Timpa konten file dengan mempertahankan fileId yang sama)
const replacedFile = await cz.storage.replaceFile({
  fileId: "f29b8214-7e8c-...",
  file: newFileBuffer,
  fileName: "hero-banner-v2.webp",
  mimeType: "image/webp",
  onProgress: ({ percent }) => console.log(`Mengganti: ${percent}%`),
});

Parameters (`UpdateFileOptions`)

Property	Type	Default	Description
fileId*required	string	—	UUID of the target file to update.
name	string	—	New file name. Automatically moves the R2 object key to match.
folderId	string \| null	—	Target folder UUID (or null / 'root'). Automatically moves the R2 object key.
isTrash	boolean	—	Soft-delete trash status flag.
file	File \| Blob \| Buffer \| Uint8Array	—	Optional new binary payload to overwrite the file content in R2.
mimeType	string	—	Updated MIME type when replacing file binary.
onProgress	({ loaded, total, percent }) => void	—	Upload progress callback when replacing binary content.

Virtual Folder CRUD (`createFolder`, `updateFolder`, `deleteFolder`)

Create, inspect, rename, move, and recursively delete virtual folders via the SDK:

examples/folders-crud.ts

// 1. Buat folder virtual
const folder = await cz.storage.createFolder({
  projectId: "ca2454ff-7f1e-421b-b134-4c800f6d58de",
  name: "Marketing Assets",
  parentId: null, // opsional: parent folder ID untuk folder bersarang
});

// 2. Ambil informasi folder atau daftar folder
const folderInfo = await cz.storage.getFolder(folder.id);
const rootFolders = await cz.storage.listFolders({
  projectId: "ca2454ff-7f1e-421b-b134-4c800f6d58de",
  parentId: "root",
});

// 3. Ubah nama atau pindahkan folder (otomatis sinkronisasi subfolder dan r2Key)
const updatedFolder = await cz.storage.updateFolder({
  folderId: folder.id,
  name: "Brand & Marketing",
  parentId: null,
});

// 4. Hapus folder (menghapus subfolder dan objek R2 secara rekursif)
const deleted = await cz.storage.deleteFolder(folder.id);
console.log(`Dihapus ${deleted.deletedFoldersCount} folder dan ${deleted.deletedFilesCount} file`);

Folder SDK Methods

Property	Type	Default	Description
createFolder(options)*required	CreateFolderOptions => Promise<StorageFolder>	—	Creates a folder in a project ({ projectId, name, parentId?, path? }).
getFolder(folderId)*required	string => Promise<StorageFolder>	—	Fetches a single folder record by its UUID.
listFolders(options)*required	ListFoldersOptions => Promise<StorageFolder[]>	—	Lists folders in a project directory ({ projectId, parentId? }).
updateFolder(options)*required	UpdateFolderOptions => Promise<StorageFolder>	—	Renames or moves a folder ({ folderId, name?, parentId? }) and cascades R2 keys.
deleteFolder(folderId)*required	string => Promise<DeleteFolderResult>	—	Recursively deletes a folder, its subfolders, and all contained R2 objects.

Permanently Deleting Assets (`deleteFile`)

Deleting an asset is atomic: Cloudizero simultaneously purges the binary object from Cloudflare R2 and removes its record from Neon Postgres.

examples/delete.ts

// Hapus file secara permanen dari Cloudflare R2 dan Neon DB
const res = await cz.storage.deleteFile("f29b8214-7e8c-...");

if (res.success) {
  console.log("Aset berhasil dihapus:", res.message);
}

Irreversible Action

Deleted files and folders cannot be recovered. Ensure you prompt for confirmation in user interfaces before triggering deletion.