TypeScript SDK

Manajemen CRUD File & Folder

Operasi CRUD menyeluruh untuk file dan folder virtual: telusuri hierarki, ubah nama/pindahkan aset dengan sinkronisasi otomatis penyimpanan, timpa file biner in-place, dan lakukan penghapusan atomik.

Mendaftar File & Folder (`listContents`)

Dapatkan seluruh file, folder, dan rekam jejak breadcrumbs pada root proyek maupun di dalam subfolder tertentu:

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: "prj_LXAlEW70v24YSc0y",
});

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: "prj_LXAlEW70v24YSc0y",
  folderId: "fld_ARaZjwdP...",
});

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

Mengambil Metadata Aset (`getFile`)

Ambil metadata relasional dan dapatkan URL unduhan presigned untuk aset privat:

examples/get-file.ts
// Mengambil metadata file dan tautan unduhan presigned sementara
const { file, downloadUrl } = await cz.storage.getFile("fil_tsvSl4yY...");

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

Memperbarui & Mengganti File (`updateFile` & `replaceFile`)

Ubah nama file, pindahkan antar folder, atau ganti muatan binernya secara in-place dengan mempertahankan fileId yang sama:

examples/update-file.ts
// 1. Pembaruan Metadata (Ubah nama file atau pindahkan ke folder lain)
// Otomatis memindahkan objek terkait di penyimpanan untuk sinkronisasi key & URL CDN
const renamedFile = await cz.storage.updateFile({
  fileId: "fil_tsvSl4yY...",
  name: "hero-banner-2026.webp",
  folderId: "fld_ARaZjwdP...", // 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: "fil_tsvSl4yY...",
  file: newFileBuffer,
  fileName: "hero-banner-v2.webp",
  mimeType: "image/webp",
  onProgress: ({ percent }) => console.log(`Mengganti: ${percent}%`),
});

Parameter (`UpdateFileOptions`)

PropertyTypeDefaultDescription
fileId*requiredstring—ID file target yang akan diperbarui (Prefixed ID mis. 'fil_...').
namestring—Nama file baru. Otomatis memindahkan jalur key objek penyimpanan.
folderIdstring | null—ID folder target (mis. 'fld_...' atau null / 'root'). Otomatis memindahkan objek penyimpanan.
isTrashboolean—Flag status tempat sampah / soft-delete.
fileFile | Blob | Buffer | Uint8Array—Muatan biner baru opsional untuk menimpa konten file di penyimpanan.
mimeTypestring—Tipe MIME yang diperbarui saat menimpa file biner.
onProgress({ loaded, total, percent }) => void—Callback progres unggah saat mengganti muatan biner.

Unggah Langsung Klien via Presigned URL (`createPresignedUpload` & `completeUpload`)

Hasilkan URL unggah presigned berdurasi terbatas agar browser atau aplikasi mobile klien dapat mengunggah aset biner langsung ke Cloudizero Storage Engine tanpa membebani egress atau memori server Anda:

examples/presigned-upload.ts
// 1. Backend: Buat tiket unggah presigned berdurasi terbatas
const ticket = await cz.storage.createPresignedUpload({
  projectId: "prj_LXAlEW70v24YSc0y",
  fileName: "podcast-episode.mp3",
  fileSize: 1024 * 1024 * 45, // 45 MB
  mimeType: "audio/mpeg",
});

// Kembalikan 'ticket' ke frontend:
// { uploadUrl, fileId, storageKey, finalFileName }

// 2. Browser / Client: Unggah biner langsung ke Cloudizero Storage Engine via PUT
// await fetch(ticket.uploadUrl, { method: "PUT", body: audioFile, headers: { "Content-Type": audioFile.type } });

// 3. Backend: Rekam metadata dan finalisasi aset di katalog Cloudizero
const file = await cz.storage.completeUpload({
  fileId: ticket.fileId,
  projectId: "prj_LXAlEW70v24YSc0y",
  fileName: ticket.finalFileName,
  mimeType: "audio/mpeg",
  fileSize: 1024 * 1024 * 45,
  storageKey: ticket.storageKey,
});

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

Buat, periksa, ubah nama, pindahkan, dan hapus folder virtual secara rekursif via SDK:

examples/folders-crud.ts
// 1. Buat folder virtual
const folder = await cz.storage.createFolder({
  projectId: "prj_LXAlEW70v24YSc0y",
  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: "prj_LXAlEW70v24YSc0y",
  parentId: "root",
});

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

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

Metode Folder SDK

PropertyTypeDefaultDescription
createFolder(options)*requiredCreateFolderOptions => Promise<StorageFolder>—Membuat folder di proyek ({ projectId, name, parentId?, path? }).
getFolder(folderId)*requiredstring => Promise<StorageFolder>—Mengambil rekaman folder tunggal berdasarkan ID-nya (mis. 'fld_...').
listFolders(options)*requiredListFoldersOptions => Promise<StorageFolder[]>—Mendaftar folder di dalam direktori proyek ({ projectId, parentId? }).
updateFolder(options)*requiredUpdateFolderOptions => Promise<StorageFolder>—Mengubah nama atau memindahkan folder ({ folderId, name?, parentId? }) dan cascade storage key.
deleteFolder(folderId)*requiredstring => Promise<DeleteFolderResult>—Menghapus folder secara rekursif beserta subfolder dan seluruh objek penyimpanan di dalamnya.

Intelijen Dokumen & Ekstraksi Halaman PDF (`getFilePages` & `extractPdfPages`)

Akses hasil ekstraksi halaman resolusi tinggi, thumbnail, dan daftar bab dari dokumen multi-halaman (seperti PDF), atau picu proses ekstraksi secara terprogram:

examples/pdf-extraction.ts
// 1. Dapatkan daftar halaman, dimensi, URL CDN, dan bab dokumen PDF
const doc = await cz.storage.getFilePages("fil_tsvSl4yYKEOlO4KN");

console.log(`Total Halaman: ${doc.pageCount}`);
console.log("Status Pemrosesan:", doc.processingStatus);
console.log("Thumbnail Dokumen:", doc.thumbnailUrl);
console.log("Halaman Pertama:", doc.pages[0]?.url);
console.log("Daftar Bab:", doc.chapters);

// 2. Memicu antrean ekstraksi halaman PDF (asinkron)
const job = await cz.storage.extractPdfPages("fil_tsvSl4yYKEOlO4KN");
console.log("Status Antrean:", job.message);

Pencarian Multimodal Hibrida (`search`)

Pencarian berbasis bahasa alami yang memadukan vektor semantik (768 dimensi) dengan pencocokan kata kunci eksak di seluruh aset proyek:

examples/search.ts
// Pencarian multimodal hibrida (vektor semantik + kata kunci)
const searchResults = await cz.storage.search({
  projectId: "prj_LXAlEW70v24YSc0y",
  query: "sunset over the beach with palm trees",
});

console.log(`Mode Pencarian: ${searchResults.mode} (${searchResults.totalCount} hasil)`);

searchResults.results.forEach((match) => {
  console.log(`- ${match.name} [Skor: ${match.similarityScore}, Tipe: ${match.matchType}]`);
  console.log(`  CDN URL: ${match.url}`);
});

AI Visual Describe & Teks Alt WCAG (`describeImage`)

Gunakan AI vision multimodal untuk menganalisis aset gambar secara otomatis, menghasilkan teks alt aksesibilitas WCAG, tag SEO, deskripsi visual, dan palet warna:

examples/ai-describe.ts
// Analisis visual AI untuk teks alt WCAG, tag SEO, dan palet warna
const aiResult = await cz.storage.describeImage("fil_tsvSl4yYKEOlO4KN", {
  locale: "id", // atau "en" untuk bahasa Inggris
  force: false,
});

console.log("Teks Alt WCAG:", aiResult.altText);
console.log("Tag SEO:", aiResult.aiMetadata.tags);
console.log("Deskripsi Visual:", aiResult.aiMetadata.description);
console.log("Palet Warna Dominan:", aiResult.aiMetadata.dominantColors);

Transformasi Gambar CDN Dinamis di Edge (`getCdnUrl`)

Hasilkan URL CDN publik yang bersih dan otoritatif dengan manipulasi gambar on-the-fly di jaringan edge global Cloudizero:

examples/cdn-transformations.ts
// 1. Dapatkan URL CDN asli untuk aset penyimpanan
const originalUrl = cz.storage.getCdnUrl("usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/banner.png");
console.log("Original CDN URL:", originalUrl);
// => https://cdn.cloudizero.com/usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/banner.png

// 2. Transformasi gambar dinamis di edge (lebar, tinggi, kualitas, format WebP)
const optimizedThumb = cz.storage.getCdnUrl("usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/banner.png", {
  width: 400,
  height: 300,
  quality: 80,
  format: "webp",
  fit: "cover",
});
console.log("Optimized Thumbnail URL:", optimizedThumb);
// => https://cdn.cloudizero.com/usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/banner.png?w=400&h=300&q=80&format=webp&fit=cover

Profil Akun & Pemantauan Kuota Waktu-Nyata (`cz.getProfile`)

Pantau tier paket langganan, sisa kapasitas penyimpanan, dan batas limit akun secara terprogram:

examples/account-profile.ts
// Periksa profil akun, tier paket langganan, dan pemakaian kuota waktu-nyata
const profile = await cz.getProfile();

console.log(`Paket Langganan: ${profile.plan} (${profile.isTrial ? "Trial Aktif" : "Reguler"})`);
console.log(`Kapasitas Terpakai: ${profile.stats.totalStorageBytes} / ${profile.limits.storageBytes} byte (${profile.stats.storagePercent}%)`);
console.log(`Sisa Penyimpanan: ${profile.stats.remainingStorageBytes} byte`);
console.log(`Total Proyek: ${profile.stats.projectsCount} / ${profile.limits.maxProjects}`);
console.log(`Total File: ${profile.stats.filesCount}`);

Manajemen Siklus Hidup Proyek (`projects`)

Kelola boundary proyek Anda langsung melalui SDK: mendaftar, membuat, memperbarui, dan menghapus proyek.

examples/projects-crud.ts
// 1. Ambil daftar seluruh proyek yang dapat diakses
const projects = await cz.projects.list();

// 2. Buat proyek baru (memerlukan API key dengan Akses Global)
const newProject = await cz.projects.create({
  name: "Mobile App Assets",
  description: "Asset bucket untuk flutter mobile app",
});

// 3. Perbarui nama atau deskripsi proyek
const updated = await cz.projects.update(newProject.id, {
  name: "Mobile App Production Assets",
});

// 4. Perbarui urutan tampilan proyek
await cz.projects.reorder([newProject.id, "prj_LXAlEW70v24YSc0y"]);

// 5. Hapus proyek secara permanen beserta seluruh file dan foldernya
const res = await cz.projects.delete(newProject.id);
console.log(res.message);

Menghapus Aset Permanen (`deleteFile`)

Penghapusan aset bersifat atomik: Cloudizero secara simultan membersihkan objek biner dari penyimpanan dan menghapus rekamannya dari basis data.

examples/delete.ts
// Hapus file secara permanen dari penyimpanan dan database
const res = await cz.storage.deleteFile("fil_tsvSl4yYKEOlO4KN");

if (res.success) {
  console.log("Aset berhasil dihapus:", res.message);
}
Tindakan Permanen
File dan folder yang dihapus tidak dapat dipulihkan kembali. Pastikan Anda menampilkan dialog konfirmasi di antarmuka pengguna sebelum mengeksekusi aksi ini.