@cloudizero/sdk

Official TypeScript SDK for the Cloudizero Zero-Egress Digital Asset Management & Media Delivery Platform.

Seamlessly upload, manage, and deliver media files and virtual folders directly to Cloudizero zero-egress storage with zero bandwidth egress penalties and instant relational indexing.

📦 Installation

npm install @cloudizero/sdk
# or
pnpm add @cloudizero/sdk
# or
yarn add @cloudizero/sdk

🚀 Quick Start

1. Initialize Client

Generate an API Key in your Cloudizero dashboard (/api-keys), then initialize the SDK:

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

// 1. Zero-config (reads CLOUDIZERO_API_KEY from environment, defaults to https://api.cloudizero.com)
const cz = new Cloudizero();

// 2. Or explicit configuration (overriding baseUrl / cdnUrl if needed):
const czCustom = new Cloudizero({
  apiKey: process.env.CLOUDIZERO_API_KEY!, // e.g. "cz_live_9f8a..."
  baseUrl: "https://api.cloudizero.com", // default
  cdnUrl: "https://cdn.cloudizero.com", // default
});

📂 File CRUD Operations

1. Create / Upload File (upload)

Direct File Upload (Node.js / Next.js / Express)

Upload buffers, byte arrays, or streams directly from your backend services:

import fs from "fs";

const fileBuffer = fs.readFileSync("./avatar.png");

const uploaded = await cz.storage.upload({
  file: fileBuffer,
  fileName: "avatar.png",
  projectId: "prj_LXAlEW70v24YSc0y",
  folderId: "fld_ARaZjwdPpUqXhDHf", // optional target Folder ID (or omit for root)
  mimeType: "image/png",
});

console.log("Uploaded successfully!");
console.log("File ID:", uploaded.id);
console.log("Storage Key:", uploaded.r2Key);
console.log("Public URL:", uploaded.url);

Direct Client Upload via Presigned URL (Browser & Mobile Apps)

For browser and mobile applications, keep your secret API key safely on your backend server. Use the presigned upload handshake so clients stream bytes directly to Cloudizero Zero-Egress Storage Engine without proxying through your server:

// 1. Backend Route (e.g. Next.js / Express): Generate signed upload ticket
const ticket = await cz.storage.createPresignedUpload({
  projectId: "prj_LXAlEW70v24YSc0y",
  fileName: "user-presentation.mp4",
  fileSize: 45 * 1024 * 1024,
  mimeType: "video/mp4",
});
// Return { uploadUrl, fileId, storageKey, finalFileName } to frontend

// 2. Client Browser: Stream binary directly to Cloudizero Storage Engine
await fetch(ticket.uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": "video/mp4" },
  body: selectedFile,
});

// 3. Backend Route: Finalize asset and record metadata in Cloudizero Database
const asset = await cz.storage.completeUpload({
  fileId: ticket.fileId,
  projectId: "prj_LXAlEW70v24YSc0y",
  fileName: ticket.finalFileName,
  mimeType: "video/mp4",
  fileSize: 45 * 1024 * 1024,
  storageKey: ticket.storageKey,
});
console.log("Registered Asset URL:", asset.url);

Large File & Video Uploads (Chunked Multipart Support up to 50 GB)

Files larger than 50 MB automatically utilize Cloudizero's parallel chunked multipart architecture with zero configuration, featuring automatic retries, concurrency management, and resume capabilities:

// Automatically uses chunked multipart streaming for gigabyte files
const largeVideo = await cz.storage.upload({
  file: largeFileBuffer, // File, Blob, Buffer, or Uint8Array
  fileName: "keynote-presentation-4k.mp4",
  projectId: "prj_LXAlEW70v24YSc0y",
  mimeType: "video/mp4",
  onProgress: ({ percent, loaded, total }) => {
    console.log(`Chunked upload: ${percent}% (${(loaded / 1024 / 1024).toFixed(1)} MB / ${(total / 1024 / 1024).toFixed(1)} MB)`);
  },
});

Automated WebP Image Optimization at Rest (optimize: "webp")

Transcode raster images (JPEG, PNG) to WebP synchronously at rest during upload to save up to 75% storage quota with immediate CDN distribution readiness:

// 1. Shorthand: Transcode raster images to WebP (default quality: 85)
const optimized = await cz.storage.upload({
  file: imageBuffer,
  fileName: "hero-banner.jpg",
  projectId: "prj_LXAlEW70v24YSc0y",
  optimize: "webp", // or optimize: true
});

console.log(optimized.name);     // "hero-banner.webp"
console.log(optimized.mimeType); // "image/webp"
console.log(optimized.url);      // "https://cdn.cloudizero.com/.../hero-banner.webp"

// 2. Granular Quality Control (1 - 100)
const customOptimized = await cz.storage.upload({
  file: pngBuffer,
  fileName: "product-preview.png",
  projectId: "prj_LXAlEW70v24YSc0y",
  optimize: { format: "webp", quality: 80 },
});

// 3. Direct Client-Side Presigned Upload with WebP Optimization
const ticket = await cz.storage.createPresignedUpload({
  projectId: "prj_LXAlEW70v24YSc0y",
  fileName: "user-avatar.png",
  fileSize: 2 * 1024 * 1024,
  optimize: "webp",
});
// ticket.finalFileName -> "user-avatar.webp"
// ticket.storageKey -> ".../user-avatar.webp"

Note: Non-raster media formats (PDF, SVG, Video) and images > 20 MB are gracefully preserved without transcode. Corrupted image buffers automatically fall back to raw storage without interrupting your upload pipeline.

On-the-Fly Dynamic Edge Image Transformations

Generate clean CDN URLs with real-time responsive resizing, format conversion (WebP/AVIF auto-negotiation), and edge caching:

// Master original URL: https://cdn.cloudizero.com/user/project/banner.png
const originalUrl = cz.storage.getCdnUrl(uploaded.r2Key);

// Transformed responsive thumbnail: https://cdn.cloudizero.com/user/project/banner.png?w=400&format=auto
const thumbnail = cz.storage.getCdnUrl(uploaded.r2Key, {
  w: 400,
  format: "auto", // Automatically serves AVIF or WebP based on client browser
  q: 85,
});

2. Read File Details (getFile)

Retrieve file metadata along with a temporary presigned download URL:

const { file, downloadUrl } = await cz.storage.getFile("fil_tsvSl4yYKEOlO4KN");
console.log("File metadata:", file);
console.log("Presigned download URL:", downloadUrl);

3. Update File Metadata or Replace Binary (updateFile & replaceFile)

Update Metadata (Rename / Move Folder / Trash)

Renaming a file or moving it to another folder automatically moves the underlying object in storage so the human-readable storage key and CDN URL stay synchronized:

const updated = await cz.storage.updateFile({
  fileId: "fil_tsvSl4yYKEOlO4KN",
  name: "new-avatar-name.png",
  folderId: "fld_ARaZjwdPpUqXhDHf", // or null / "root" to move to project root
});

console.log("Updated Storage Key:", updated.r2Key);
console.log("Updated CDN URL:", updated.url);

Replace File Binary In-Place (replaceFile)

Overwrite an existing file's binary content while preserving its fileId (and optionally updating its filename or MIME type):

const newBuffer = fs.readFileSync("./avatar-v2.webp");

const replaced = await cz.storage.replaceFile({
  fileId: "fil_tsvSl4yYKEOlO4KN",
  file: newBuffer,
  fileName: "avatar-v2.webp", // optional: omit to keep existing filename & storage key
  mimeType: "image/webp",
});

console.log("Replaced file URL:", replaced.url);

4. Delete File (deleteFile)

Permanently delete a file from both storage and database:

await cz.storage.deleteFile("fil_tsvSl4yYKEOlO4KN");
console.log("File permanently removed from storage & DB");

📁 Folder CRUD Operations

1. Create Folder (createFolder)

const folder = await cz.storage.createFolder({
  projectId: "your-project-id",
  name: "Marketing Banners",
  parentId: null, // optional parent folder ID for nested folders
});

console.log("Created folder:", folder.id, folder.path); // e.g. "/marketing-banners"

2. Read & List Folders (getFolder, listFolders, listContents)

// Get a single folder by ID
const folderInfo = await cz.storage.getFolder("folder-id-here");

// List folders in project root (or pass parentId for subfolders)
const folders = await cz.storage.listFolders({
  projectId: "your-project-id",
  parentId: "root",
});

// List both folders, files, and breadcrumbs in a directory
const contents = await cz.storage.listContents({
  projectId: "your-project-id",
  folderId: folder.id, // or omit for root
});

3. Update Folder (updateFolder)

Rename a folder or move it under a new parent folder. All nested subfolder paths and underlying storage keys for files inside the folder tree are updated automatically:

const updatedFolder = await cz.storage.updateFolder({
  folderId: "folder-id-here",
  name: "Q4 Campaigns",
  parentId: "parent-folder-id", // or null / "root"
});

4. Delete Folder (deleteFolder)

Recursively deletes a folder, all its subfolders, and permanently removes all contained files from storage and database:

const result = await cz.storage.deleteFolder("folder-id-here");
console.log(`Deleted ${result.deletedFoldersCount} folders and ${result.deletedFilesCount} files`);

5. Batch Delete Files & Folders (batchDelete)

Permanently delete multiple files and folders in a single atomic request. Subtree expansion automatically purges all nested files within selected folder trees:

const batchResult = await cz.storage.batchDelete({
  projectId: "prj_LXAlEW70v24YSc0y",
  fileIds: ["fil_tsvSl4yYKEOlO4KN", "fil_ARaZjwdPpUqXhDHf"],
  folderIds: ["fld_subfolder_id"],
});

console.log(`Purged ${batchResult.deleted.totalPurgedFilesCount} total files across ${batchResult.deleted.explicitFoldersCount} folders.`);

📑 Document & PDF Page Processing

Cloudizero includes built-in asynchronous PDF page extraction and thumbnail generation:

1. Control Extraction on Upload (autoExtract)

By default, PDF uploads inherit your account's Storage & Document Intelligence preference configured in Settings > Preferences. You can also explicitly set autoExtract on individual uploads:

// Explicitly opt-out of auto-extract to save storage quota for raw PDF backups:
const rawPdf = await cz.storage.upload({
  file: pdfBuffer,
  fileName: "quarterly-taxes.pdf",
  projectId: "prj_...",
  autoExtract: false,
});

// Or explicitly enforce extraction:
const ebook = await cz.storage.upload({
  file: ebookBuffer,
  fileName: "engineering-handbook.pdf",
  projectId: "prj_...",
  autoExtract: true,
});

2. Extract PDF Pages On-Demand (extractPdfPages)

Trigger background extraction of all individual pages and cover thumbnails anytime:

const job = await cz.storage.extractPdfPages("fil_tsvSl4yYKEOlO4KN");
console.log("Extraction initiated:", job.message);

3. Get Extracted Pages & Table of Contents (getFilePages)

Fetch all extracted page image URLs, dimensions, and document chapters:

const pagesData = await cz.storage.getFilePages("fil_tsvSl4yYKEOlO4KN");

console.log("Status:", pagesData.processingStatus); // "ready" | "processing"
console.log("Total Pages:", pagesData.pageCount);
console.log("Cover Thumbnail:", pagesData.thumbnailUrl);

// Render pages via zero-egress CDN
pagesData.pages.forEach((page) => {
  console.log(`Page ${page.pageNumber}: ${page.url} (${page.width}x${page.height})`);
});

🔍 AI Intelligence & Multimodal Search

1. Hybrid Multimodal & Semantic Search (search)

Execute natural language semantic search combined with exact keyword matching powered by vector embeddings:

const searchResults = await cz.storage.search({
  projectId: "prj_LXAlEW70v24YSc0y",
  query: "sunset over the beach with palm trees",
});

console.log(`Search mode: ${searchResults.mode} (${searchResults.totalCount} matches)`);

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

2. Multimodal AI Visual Describe & Alt-Text (describeImage)

Analyze images using multimodal AI to generate accessible WCAG alt-text, SEO tags, descriptions, dominant colors, and vector embeddings:

const aiInsights = await cz.storage.describeImage("fil_tsvSl4yYKEOlO4KN", {
  locale: "en", // or "id" for Bahasa Indonesia
  force: false, // set true to bypass cache and regenerate
});

console.log("WCAG Alt-Text:", aiInsights.altText);
console.log("SEO Tags:", aiInsights.aiMetadata.tags);
console.log("Description:", aiInsights.aiMetadata.description);
console.log("Dominant Colors:", aiInsights.aiMetadata.dominantColors);

🏗️ Project Management (cz.projects)

Programmatically create and govern project containers (requires a Global Access API key for creation/deletion):

// 1. List accessible projects
const projects = await cz.projects.list();

// 2. Create a new project container
const newProject = await cz.projects.create({
  name: "Mobile App Assets",
  description: "Static media assets for iOS and Android apps",
});

// 3. Update project details
const updated = await cz.projects.update(newProject.id, {
  name: "Mobile & Web Assets",
});

// 4. Reorder projects display order
await cz.projects.reorder([newProject.id, "prj_other_id"]);

// 5. Delete project
await cz.projects.delete(newProject.id);

📊 Account Profile & Quota (cz.getProfile)

Inspect your account details, active subscription plan, and real-time storage usage:

const profile = await cz.getProfile();

console.log(`Active Plan: ${profile.plan}`);
console.log(`Storage Used: ${profile.stats.totalStorageBytes} / ${profile.limits.storageBytes} bytes (${profile.stats.storagePercent}%)`);
console.log(`Remaining Storage: ${profile.stats.remainingStorageBytes} bytes`);
console.log(`Total Projects: ${profile.stats.projectsCount}`);
console.log(`Total Files: ${profile.stats.filesCount}`);

🔒 Security Best Practice

• Secret API Key (cz_live_...): Keep in server-side environment variables (process.env.CLOUDIZERO_API_KEY).
• Project Restrictions: When generating an API key, you can restrict it to specific projects to follow the principle of least privilege.

📄 License

MIT © Cloudizero