TypeScript SDK

Types & Error Handling

Safely catch SDK exceptions with CloudizeroError and leverage exported TypeScript types.

Handling `CloudizeroError`

All client network failures and API errors reject with an instance of CloudizeroError containing the HTTP status code:

examples/error-handling.ts

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

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

try {
  await cz.storage.upload({
    file: myFile,
    fileName: "document.pdf",
    projectId: "invalid-or-forbidden-id",
  });
} catch (error) {
  if (error instanceof CloudizeroError) {
    console.error("Cloudizero API Error:", error.message);
    console.error("HTTP Status Code:", error.status); // e.g. 403 or 401

    if (error.status === 401) {
      // Minta user input ulang atau refresh API key
    } else if (error.status === 403) {
      // Kunci tidak berwenang untuk proyek ini
    }
  } else {
    console.error("Unexpected Error:", error);
  }
}

Common Status Codes

Status	Meaning	Resolution
400 Bad Request	Missing required options or invalid file format.	Verify `fileName` and `projectId`.
401 Unauthorized	Missing or invalid API key.	Generate a new key at `/api-keys`.
403 Forbidden	API key restricted to another project ID.	Ensure the key scope matches the target project.
404 Not Found	Target file or folder not found.	Verify file or folder ID.

TypeScript Interfaces

Every response and parameter is strongly typed out-of-the-box:

@cloudizero/sdk/types.ts

// Tipe Utama yang Diekspor dari @cloudizero/sdk

export interface CloudizeroConfig {
  apiKey: string;
  baseUrl?: string;
  cdnUrl?: string;
}

export type UploadPayload =
  | File
  | Blob
  | Uint8Array
  | ArrayBuffer
  | { [key: string]: unknown };

export interface UploadOptions {
  file: UploadPayload;
  fileName: string;
  projectId: string;
  folderId?: string | null;
  mimeType?: string;
  width?: number | null;
  height?: number | null;
  onProgress?: (progress: { loaded: number; total: number; percent: number }) => void;
}

export interface UpdateFileOptions {
  fileId: string;
  name?: string;
  folderId?: string | null;
  isTrash?: boolean;
  file?: UploadPayload;
  mimeType?: string;
  width?: number | null;
  height?: number | null;
  onProgress?: (progress: { loaded: number; total: number; percent: number }) => void;
}

export interface ReplaceFileOptions {
  fileId: string;
  file: UploadPayload;
  fileName?: string;
  folderId?: string | null;
  mimeType?: string;
  width?: number | null;
  height?: number | null;
  onProgress?: (progress: { loaded: number; total: number; percent: number }) => void;
}

export interface UploadedFile {
  id: string;
  projectId: string;
  folderId: string | null;
  name: string;
  mimeType: string;
  size: number;
  width: number | null;
  height: number | null;
  r2Key: string;
  etag: string | null;
  isTrash?: boolean;
  createdAt: string;
  updatedAt: string;
  url?: string;
}

export interface StorageFolder {
  id: string;
  projectId: string;
  parentId: string | null;
  name: string;
  path: string;
  createdAt: string;
  updatedAt: string;
}

export interface CreateFolderOptions {
  projectId: string;
  name: string;
  parentId?: string | null;
  path?: string;
}

export interface ListFoldersOptions {
  projectId: string;
  parentId?: string | null;
}

export interface UpdateFolderOptions {
  folderId: string;
  name?: string;
  parentId?: string | null;
}

export interface DeleteFolderResult {
  success: boolean;
  message: string;
  deletedFoldersCount: number;
  deletedFilesCount: number;
}

export interface StorageContents {
  project: { id: string; name: string };
  isRoot: boolean;
  breadcrumbs: { id: string; name: string }[];
  folders: StorageFolder[];
  files: UploadedFile[];
}