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) {
      // Re-prompt user or refresh API key
    } else if (error.status === 403) {
      // Key not authorized for this specific project
    }
  } 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

// Core Exported Types from @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 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;
  createdAt: string;
  updatedAt: string;
  url?: string;
}

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