@cludz/sdk 0.2.3

package/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Bump and Publish
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Publish to JSR
+        run: bunx jsr publish

package/README.md

@@ -0,0 +1,66 @@
+# Cludz API JavaScript SDK
+
+A clean, modular, and high-performance JavaScript SDK for [Cludz API](https://docs.cludz.net/), built for **Bun**.
+
+## Installation
+
+This SDK is designed to be used directly in your Bun projects.
+
+```bash
+bunx jsr add @cludz/sdk
+```
+
+## Quick Start
+
+```javascript
+import { Cludz } from '@cludz/sdk';
+
+const cludz = new Cludz({
+  api: 'https://api.cludz.net/',
+  key: 'your_api_key_here'
+});
+
+// Download a video
+const video = await cludz.downloader.youtube.download('https://youtube.com/watch?v=...');
+console.log(video.data.url);
+```
+
+## Modules
+
+### Downloader
+- `cludz.downloader.youtube.search(query, limit)`
+- `cludz.downloader.youtube.searchDownload(query, format)`
+- `cludz.downloader.youtube.download(url, format)`
+- `cludz.downloader.tiktok.download(url, format)`
+- `cludz.downloader.download(platform, url, format)` (Supports: instagram, facebook, pinterest, twitter, soundcloud, twitch)
+
+### Tools
+- `cludz.tools.webCheck(url)`
+- `cludz.tools.dns(domain)`
+- `cludz.tools.ssl(domain)`
+- `cludz.tools.meta(url)`
+- `cludz.tools.qr(text)`: Returns a Bun Response (Image).
+- `cludz.tools.barcode(text, options)`: Returns a Bun Response (Image).
+
+### Image
+- `cludz.image.meme(source, topText, bottomText)`: Generate a meme. `source` can be a URL, local path, Buffer, or Blob.
+- `cludz.image.compress(source, quality)`: Compress an image (quality 1-100).
+- `cludz.image.convert(source, format)`: Convert image format (jpeg, png, webp, avif).
+- `cludz.image.crop(source, { left, top, width, height })`: Crop an image.
+- *Note: All image methods return a standard `Response` object containing the binary image data.*
+
+### Account
+- `cludz.account.me()`: Get current account info.
+- `cludz.account.status()`: Get API health/monitoring.
+
+## Error Handling
+
+The SDK throws descriptive errors when a request fails:
+
+```javascript
+try {
+  await cludz.tools.qr('Hello this is QR code');
+} catch (error) {
+  console.error('Error:', error.message);
+}
+```

package/bun.lock

@@ -0,0 +1,26 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "sdk",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
+
+    "@types/node": ["@types/node@25.2.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ=="],
+
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/index.ts

@@ -0,0 +1,110 @@
+// import { AI } from "./modules/ai";
+import { Downloader } from "./modules/downloader";
+import { Tools } from "./modules/tools";
+import { Account } from "./modules/account";
+import { Image } from "./modules/image";
+import { Tasks } from "./modules/tasks";
+export { Storage } from "./modules/storage";
+export type { StorageSource } from "./modules/storage";
+
+import type { CludzOptions, RequestOptions } from "./types";
+
+/**
+ * The main Cludz SDK client.
+ * Provides access to various modules including downloader, tools, account, image, and tasks.
+ */
+export class Cludz {
+    /** The base URL of the Cludz API. */
+    public readonly baseUrl: string;
+    /** The API key used for authentication. */
+    public readonly key?: string;
+    
+    // public readonly ai: AI;
+    /** Module for downloading media from supported platforms. */
+    public readonly downloader: Downloader;
+    /** Module for various utility tools (QR, DNS, SSL, etc.). */
+    public readonly tools: Tools;
+    /** Module for account management and status monitoring. */
+    public readonly account: Account;
+    /** Module for image processing and manipulation. */
+    public readonly image: Image;
+    /** Module for managing and waiting for background tasks. */
+    public readonly tasks: Tasks;
+
+    /**
+     * Initializes a new instance of the Cludz client.
+     * @param options Configuration options for the client.
+     * @throws Error if the API URL is not provided.
+     */
+    constructor(options: CludzOptions) {
+        if (!options.api) throw new Error("API URL is required");
+        
+        this.baseUrl = options.api.replace(/\/$/, "");
+        this.key = options.key;
+
+        // this.ai = new AI(this);
+        this.downloader = new Downloader(this);
+        this.tools = new Tools(this);
+        this.account = new Account(this);
+        this.image = new Image(this);
+        this.tasks = new Tasks(this);
+    }
+
+    /**
+     * Internal request handler using fetch.
+     * @param endpoint The API endpoint to request (e.g., "/v1/youtube/download").
+     * @param options Request configuration including method, query params, and body.
+     * @returns A promise that resolves to the parsed JSON data or a Response object for binary content.
+     * @throws Error if the API returns a non-OK response.
+     * @internal
+     */
+    async _request<T = any>(endpoint: string, options: RequestOptions = {}): Promise<T | Response> {
+        const url = new URL(`${this.baseUrl}${endpoint}`);
+        
+        if (options.query) {
+            Object.entries(options.query).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.append(key, value.toString());
+                }
+            });
+        }
+
+        const headers: Record<string, string> = {
+            "Accept": "application/json",
+        };
+
+        if (this.key) {
+            headers["X-API-Key"] = this.key;
+        }
+
+        const fetchOptions: RequestInit = {
+            method: options.method || "GET",
+            headers,
+        };
+
+        if (options.body) {
+            if (options.body instanceof FormData) {
+                fetchOptions.body = options.body;
+                // Don't set Content-Type, fetch will set it with boundary
+            } else {
+                fetchOptions.body = JSON.stringify(options.body);
+                headers["Content-Type"] = "application/json";
+            }
+        }
+
+        const response = await fetch(url.toString(), fetchOptions);
+        
+        const contentType = response.headers.get("content-type");
+        if (contentType && (contentType.includes("image/") || contentType.includes("application/pdf"))) {
+            return response;
+        }
+
+        const data = await response.json() as any;
+
+        if (!response.ok) {
+            throw new Error(data.message || data.statusMessage || `API Error: ${response.status}`);
+        }
+
+        return data as T;
+    }
+}

package/jsr.json

@@ -0,0 +1,6 @@
+{
+  "name": "@cludz/sdk",
+  "version": "0.2.3",
+  "license": "MIT",
+  "exports": "./index.ts"
+}

package/modules/account.ts

@@ -0,0 +1,26 @@
+import type { Cludz } from "../index";
+import type { ApiResponse, AccountInfo, MonitoringStats } from "../types";
+
+/**
+ * Module for account management and status monitoring.
+ */
+export class Account {
+    /** @internal */
+    constructor(private sdk: Cludz) {}
+
+    /**
+     * Retrieves current account information and API key details.
+     * @returns A promise that resolves to the account information.
+     */
+    async me(): Promise<ApiResponse<AccountInfo>> {
+        return this.sdk._request("/v1/me") as Promise<ApiResponse<AccountInfo>>;
+    }
+
+    /**
+     * Retrieves API status and overall monitoring statistics.
+     * @returns A promise that resolves to the monitoring statistics.
+     */
+    async status(): Promise<MonitoringStats> {
+        return this.sdk._request("/monitoring/stats") as Promise<MonitoringStats>;
+    }
+}

package/modules/ai.ts

@@ -0,0 +1,33 @@
+import type { Cludz } from "../index";
+import type { ApiResponse } from "../types";
+
+// AI is currently not available.
+// /**
+//  * Module for interacting with Cludz AI models.
+//  */
+// export class AI {
+//     /** @internal */
+//     constructor(private sdk: Cludz) {}
+
+//     /**
+//      * Sends a message to the Mimo AI model (Flash V2).
+//      * @param text The message or prompt to send.
+//      * @returns A promise that resolves to the AI's response text.
+//      */
+//     async mimo(text: string): Promise<ApiResponse<string>> {
+//         return this.sdk._request("/v1/ai/mimo/chat", {
+//             query: { text }
+//         }) as Promise<ApiResponse<string>>;
+//     }
+
+//     /**
+//      * Sends a message to the GPT AI model (OSS 120B).
+//      * @param text The message or prompt to send.
+//      * @returns A promise that resolves to the AI's response text.
+//      */
+//     async gpt(text: string): Promise<ApiResponse<string>> {
+//         return this.sdk._request("/v1/ai/gpt/chat", {
+//             query: { text }
+//         }) as Promise<ApiResponse<string>>;
+//     }
+// }

package/modules/downloader.ts

@@ -0,0 +1,81 @@
+import type { Cludz } from "../index";
+import type { ApiResponse, TaskResult } from "../types";
+
+/**
+ * Module for downloading media from various platforms.
+ */
+export class Downloader {
+    /** @internal */
+    constructor(private sdk: Cludz) {}
+
+    /**
+     * YouTube-specific download and search methods.
+     */
+    public readonly youtube = {
+        /**
+         * Search for YouTube videos.
+         * @param query The search query.
+         * @param limit Maximum number of results to return (default: 1).
+         * @returns A promise that resolves to the search results.
+         */
+        search: (query: string, limit: number = 1): Promise<ApiResponse<TaskResult>> => {
+            return this.sdk._request("/v1/youtube/search", {
+                query: { query, limit }
+            }) as Promise<ApiResponse<TaskResult>>;
+        },
+
+        /**
+         * Download a YouTube video by search query (directs to the first result).
+         * @param query The search query.
+         * @param format The desired output format ("mp3" or "mp4"). Defaults to "mp4".
+         * @returns A promise that resolves to the task information.
+         */
+        searchDownload: (query: string, format: "mp3" | "mp4" = "mp4"): Promise<ApiResponse<TaskResult>> => {
+            return this.sdk._request("/v1/youtube/search/download", {
+                query: { query, format }
+            }) as Promise<ApiResponse<TaskResult>>;
+        },
+
+        /**
+         * Download a YouTube video by its URL.
+         * @param url The valid YouTube video URL.
+         * @param format The desired output format ("mp3" or "mp4"). Defaults to "mp4".
+         * @returns A promise that resolves to the task information.
+         */
+        download: (url: string, format: "mp3" | "mp4" = "mp4"): Promise<ApiResponse<TaskResult>> => {
+            return this.sdk._request("/v1/youtube/download", {
+                query: { url, format }
+            }) as Promise<ApiResponse<TaskResult>>;
+        }
+    };
+
+    /**
+     * TikTok-specific download methods.
+     */
+    public readonly tiktok = {
+        /**
+         * Download a TikTok video or audio.
+         * @param url The valid TikTok video URL.
+         * @param format The desired output format ("mp3" or "mp4"). Defaults to "mp4".
+         * @returns A promise that resolves to the task information.
+         */
+        download: (url: string, format: "mp3" | "mp4" = "mp4"): Promise<ApiResponse<TaskResult>> => {
+            return this.sdk._request("/v1/tiktok/download", {
+                query: { url, format }
+            }) as Promise<ApiResponse<TaskResult>>;
+        }
+    };
+
+    /**
+     * Generic downloader for other platforms.
+     * @param platform The platform identifier (e.g., "instagram", "facebook").
+     * @param url The media URL.
+     * @param format The desired output format ("mp3" or "mp4"). Defaults to "mp4".
+     * @returns A promise that resolves to the task information.
+     */
+    async download(platform: string, url: string, format: "mp3" | "mp4" = "mp4"): Promise<ApiResponse<TaskResult>> {
+        return this.sdk._request(`/v1/${platform}/download`, {
+            query: { url, format }
+        }) as Promise<ApiResponse<TaskResult>>;
+    }
+}

package/modules/image.ts

@@ -0,0 +1,157 @@
+import type { Cludz } from "../index";
+
+/**
+ * Supported image source types.
+ * Can be a URL string, a local file path string, a Buffer, a Blob, or a File.
+ */
+export type ImageSource = string | Buffer | Blob | File;
+
+/**
+ * Module for image processing and manipulation.
+ * Supports environment-agnostic file resolution (Bun and Node.js).
+ */
+export class Image {
+    /** @internal */
+    constructor(private sdk: Cludz) {}
+
+    /**
+     * Resolves various image sources into a Blob or URL string.
+     * @param source The image source to resolve.
+     * @returns A promise that resolves to a Blob or a URL string.
+     * @private
+     */
+    private async resolveImage(source: ImageSource): Promise<Blob | string> {
+        if (typeof source === "string") {
+            if (source.startsWith("http://") || source.startsWith("https://")) {
+                return source;
+            } else {
+                // Assume local path - dynamic import to stay environment-agnostic where possible
+                try {
+                    // Try Bun first as it's the primary environment
+                    // @ts-ignore
+                    if (typeof Bun !== "undefined") {
+                        // @ts-ignore
+                        return Bun.file(source).blob();
+                    }
+                    // Fallback to Node.js
+                    const { readFile } = await import("node:fs/promises");
+                    const buffer = await readFile(source);
+                    return new Blob([buffer]);
+                } catch (error: any) {
+                    throw new Error(`Failed to read local image path: ${error.message}`);
+                }
+            }
+        }
+        
+        if (source instanceof Blob || (typeof File !== "undefined" && source instanceof File)) {
+            return source;
+        }
+
+        if (Buffer.isBuffer(source)) {
+            return new Blob([source]);
+        }
+
+        throw new Error("Invalid image source type. Supported: URL string, local path string, Buffer, or Blob/File.");
+    }
+
+    /**
+     * Generates a meme by adding text to an image.
+     * @param source The image source (URL, path, Buffer, Blob, or File).
+     * @param top The text to display at the top of the meme.
+     * @param bottom The text to display at the bottom of the meme.
+     * @returns A promise that resolves to a Response object containing the generated image.
+     */
+    async meme(source: ImageSource, top?: string, bottom?: string): Promise<Response> {
+        const image = await this.resolveImage(source);
+        const formData = new FormData();
+        
+        if (typeof image === "string") {
+            formData.append("image", image);
+        } else {
+            formData.append("image", image, "image.png");
+        }
+
+        if (top) formData.append("top", top);
+        if (bottom) formData.append("bottom", bottom);
+
+        return this.sdk._request("/v1/image/meme", {
+            method: "POST",
+            body: formData
+        }) as Promise<Response>;
+    }
+
+    /**
+     * Compresses an image to reduce its file size.
+     * @param source The image source (URL, path, Buffer, Blob, or File).
+     * @param quality Compression quality (1-100). Defaults to 80.
+     * @returns A promise that resolves to a Response object containing the compressed image.
+     */
+    async compress(source: ImageSource, quality: number = 80): Promise<Response> {
+        const image = await this.resolveImage(source);
+        const formData = new FormData();
+
+        if (typeof image === "string") {
+            formData.append("image", image);
+        } else {
+            formData.append("image", image, "image.png");
+        }
+
+        formData.append("quality", quality.toString());
+
+        return this.sdk._request("/v1/image/compress", {
+            method: "POST",
+            body: formData
+        }) as Promise<Response>;
+    }
+
+    /**
+     * Converts an image to a different format.
+     * @param source The image source (URL, path, Buffer, Blob, or File).
+     * @param format The target image format.
+     * @returns A promise that resolves to a Response object containing the converted image.
+     */
+    async convert(source: ImageSource, format: "jpeg" | "jpg" | "png" | "webp" | "avif"): Promise<Response> {
+        const image = await this.resolveImage(source);
+        const formData = new FormData();
+
+        if (typeof image === "string") {
+            formData.append("image", image);
+        } else {
+            formData.append("image", image, "image.png");
+        }
+
+        formData.append("format", format);
+
+        return this.sdk._request("/v1/image/convert", {
+            method: "POST",
+            body: formData
+        }) as Promise<Response>;
+    }
+
+    /**
+     * Crops an image to specific dimensions.
+     * @param source The image source (URL, path, Buffer, Blob, or File).
+     * @param options The crop dimensions (left, top, width, height).
+     * @returns A promise that resolves to a Response object containing the cropped image.
+     */
+    async crop(source: ImageSource, options: { left: number; top: number; width: number; height: number }): Promise<Response> {
+        const image = await this.resolveImage(source);
+        const formData = new FormData();
+
+        if (typeof image === "string") {
+            formData.append("image", image);
+        } else {
+            formData.append("image", image, "image.png");
+        }
+
+        formData.append("left", options.left.toString());
+        formData.append("top", options.top.toString());
+        formData.append("width", options.width.toString());
+        formData.append("height", options.height.toString());
+
+        return this.sdk._request("/v1/image/crop", {
+            method: "POST",
+            body: formData
+        }) as Promise<Response>;
+    }
+}

package/modules/storage.ts

@@ -0,0 +1,249 @@
+import type { StorageOptions, FileInfo } from "../types";
+
+/**
+ * Supported storage source types.
+ * Can be a local file path string, a Buffer, a Blob, or a File.
+ */
+export type StorageSource = string | Buffer | Blob | File;
+
+/**
+ * Standalone module for interacting with Cludz Storage containers.
+ */
+export class Storage {
+    /** The base URL of the storage container. */
+    public readonly api: string;
+    /** The storage container identifier. */
+    public readonly id: string;
+    /** The access token for this storage container. */
+    public readonly token: string;
+
+    /**
+     * Initializes a new instance of the Storage client.
+     * @param options Configuration options for the storage container.
+     * @throws Error if any required option (api, id, token) is missing.
+     */
+    constructor(options: StorageOptions) {
+        if (!options.api) throw new Error("API URL is required");
+        if (!options.id) throw new Error("Storage ID is required");
+        if (!options.token) throw new Error("Token is required");
+
+        this.api = `${options.api.replace(/\/$/, "")}/storage/${options.id}`;
+        this.id = options.id;
+        this.token = options.token;
+    }
+
+    /**
+     * Constructs headers for storage requests.
+     * @param additional Optional additional headers.
+     * @returns A record of headers.
+     * @private
+     */
+    private getHeaders(additional: Record<string, string> = {}): Record<string, string> {
+        return {
+            Token: this.token,
+            ...additional,
+        };
+    }
+
+    /**
+     * Normalizes a storage path by ensuring it starts with a slash.
+     * @param p The path to normalize.
+     * @returns The normalized path.
+     * @private
+     */
+    private normalizePath(p: string): string {
+        return p.startsWith("/") ? p : `/${p}`;
+    }
+
+    /**
+     * Resolves various file sources into a Blob or File for FormData.
+     * @param source The file source (path, Buffer, Blob, or File).
+     * @param fileName Optional file name to use when resolving from generic sources.
+     * @returns A promise that resolves to a Blob or File.
+     * @private
+     */
+    private async resolveFile(source: StorageSource, fileName: string = "file"): Promise<Blob | File> {
+        if (typeof source === "string") {
+            try {
+                // Try Bun first
+                // @ts-ignore
+                if (typeof Bun !== "undefined") {
+                    // @ts-ignore
+                    return Bun.file(source);
+                }
+                // Fallback to Node.js
+                const { readFile } = await import("node:fs/promises");
+                const buffer = await readFile(source);
+                // Extract filename from path if not provided
+                const name = fileName === "file" ? source.split(/[\\/]/).pop() || "file" : fileName;
+                return new File([buffer], name);
+            } catch (error: any) {
+                throw new Error(`Failed to read local file path: ${error.message}`);
+            }
+        }
+
+        if (source instanceof Blob || (typeof File !== "undefined" && source instanceof File)) {
+            return source;
+        }
+
+        if (Buffer.isBuffer(source)) {
+            return new Blob([source]);
+        }
+
+        throw new Error("Invalid file source type. Supported: local path string, Buffer, or Blob/File.");
+    }
+
+    /**
+     * Uploads a file to a specific directory in the storage.
+     * @param targetDirectory The target directory in storage (e.g., "/Documents").
+     * @param source The file source (local path, Buffer, Blob, or File).
+     * @param fileName Optional filename to use in storage.
+     * @returns A promise that resolves when the upload is complete.
+     * @throws Error if the upload fails.
+     */
+    async upload(targetDirectory: string, source: StorageSource, fileName?: string): Promise<void> {
+        const url = `${this.api}${this.normalizePath(targetDirectory)}`;
+        const fileObj = await this.resolveFile(source, fileName);
+        
+        const finalFileName = fileName || (fileObj instanceof File ? fileObj.name : "file");
+
+        const formData = new FormData();
+        formData.append("file", fileObj, finalFileName);
+
+        const response = await fetch(url, {
+            method: "POST",
+            headers: this.getHeaders(),
+            body: formData,
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Upload failed: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+    }
+
+    /**
+     * Deletes a file or directory from the storage.
+     * @param targetPath The path of the item to delete.
+     * @returns A promise that resolves when the deletion is complete.
+     * @throws Error if the deletion fails.
+     */
+    async delete(targetPath: string): Promise<void> {
+        const url = `${this.api}${this.normalizePath(targetPath)}`;
+        const response = await fetch(url, {
+            method: "DELETE",
+            headers: this.getHeaders(),
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Delete failed: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+    }
+
+    /**
+     * Creates a new folder in the storage.
+     * @param parentPath The path to the parent directory.
+     * @param folderName The name of the new folder.
+     * @returns A promise that resolves when the folder is created.
+     * @throws Error if the folder creation fails.
+     */
+    async createFolder(parentPath: string, folderName: string): Promise<void> {
+        const url = `${this.api}${this.normalizePath(parentPath)}`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: this.getHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify({ type: "folder", name: folderName }),
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Create folder failed: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+    }
+
+    /**
+     * Creates an empty file in the storage.
+     * @param parentPath The path to the parent directory.
+     * @param fileName The name of the new file.
+     * @returns A promise that resolves when the file is created.
+     * @throws Error if the file creation fails.
+     */
+    async createFile(parentPath: string, fileName: string): Promise<void> {
+        const url = `${this.api}${this.normalizePath(parentPath)}`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: this.getHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify({ type: "file", name: fileName }),
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Create file failed: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+    }
+
+    /**
+     * Renames or moves a file or directory in the storage.
+     * @param targetPath The current path of the item.
+     * @param newName The new name for the item.
+     * @returns A promise that resolves when the item is renamed.
+     * @throws Error if the rename operation fails.
+     */
+    async rename(targetPath: string, newName: string): Promise<void> {
+        const url = `${this.api}${this.normalizePath(targetPath)}`;
+        const response = await fetch(url, {
+            method: "PUT",
+            headers: this.getHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify({ new_name: newName }),
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Rename failed: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+    }
+
+    /**
+     * Lists the contents of a directory in the storage.
+     * @param targetPath The path of the directory to list.
+     * @returns A promise that resolves to an array of file and directory information.
+     * @throws Error if the list operation fails.
+     */
+    async list(targetPath: string): Promise<FileInfo[]> {
+        const url = `${this.api}${this.normalizePath(targetPath)}`;
+        const response = await fetch(url, {
+            method: "GET",
+            headers: this.getHeaders(),
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`List failed: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+
+        const json = await response.json() as { data: FileInfo[] };
+        return json.data;
+    }
+
+    /**
+     * Downloads a file from the storage as a Blob.
+     * @param targetPath The path of the file in storage.
+     * @returns A promise that resolves to the file data as a Blob.
+     * @throws Error if the download operation fails.
+     */
+    async download(targetPath: string): Promise<Blob> {
+        const url = `${this.api}${this.normalizePath(targetPath)}`;
+        const response = await fetch(url, {
+            method: "GET",
+            headers: this.getHeaders(),
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Download failed: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+
+        return response.blob();
+    }
+}

package/modules/tasks.ts

@@ -0,0 +1,54 @@
+import type { Cludz } from "../index";
+import type { ApiResponse, TaskState, TaskData } from "../types";
+
+/**
+ * Module for managing and waiting for background tasks.
+ */
+export class Tasks {
+    /** @internal */
+    constructor(private sdk: Cludz) {}
+
+    /**
+     * Retrieves the current state of a specific background task.
+     * @template T The expected type of the task result data. Defaults to TaskData.
+     * @param id The unique task identifier.
+     * @returns A promise that resolves to the task state.
+     */
+    public get<T = TaskData>(id: string): Promise<ApiResponse<TaskState<T>>> {
+        return this.sdk._request(`/v1/tasks/${id}`) as Promise<ApiResponse<TaskState<T>>>;
+    }
+
+    /**
+     * Polls a task until it reaches a "Completed" or "Failed" state.
+     * @template T The expected type of the task result data. Defaults to TaskData.
+     * @param id The unique task identifier.
+     * @param interval Polling interval in milliseconds. Defaults to 1000.
+     * @param timeout Maximum time to wait in milliseconds. Defaults to 60000.
+     * @returns A promise that resolves to the final task state.
+     * @throws Error if the task fails or times out.
+     */
+    public async waitFor<T = TaskData>(
+        id: string,
+        interval: number = 1000,
+        timeout: number = 60000
+    ): Promise<TaskState<T>> {
+        const start = Date.now();
+        
+        while (Date.now() - start < timeout) {
+            const resp = await this.get(id);
+            const task = resp.data;
+
+            if (task.status === "Completed") {
+                return task as TaskState<T>;
+            }
+
+            if (task.status === "Failed") {
+                throw new Error(task.message || task.error || "Task failed");
+            }
+
+            await new Promise((resolve) => setTimeout(resolve, interval));
+        }
+
+        throw new Error(`Task timeout after ${timeout}ms`);
+    }
+}

package/modules/tools.ts

@@ -0,0 +1,97 @@
+import type { Cludz } from "../index";
+import type { ApiResponse, WebCheckResult, DnsResult, SslResult } from "../types";
+
+/**
+ * Options for barcode generation.
+ */
+export interface BarcodeOptions {
+    /** The barcode symbology type (e.g., "code128", "ean13"). */
+    type?: string;
+    /** Whether to show the text below the barcode. */
+    showText?: boolean;
+    /** Scaling factor for the barcode. */
+    scale?: number;
+    /** Height of the barcode in pixels. */
+    height?: number;
+}
+
+/**
+ * Module for various utility tools including network checks and media generation.
+ */
+export class Tools {
+    /** @internal */
+    constructor(private sdk: Cludz) {}
+
+    /**
+     * Performs a web connectivity check on a URL.
+     * @param url The URL to check.
+     * @returns A promise that resolves to the web check results.
+     */
+    async webCheck(url: string): Promise<ApiResponse<WebCheckResult>> {
+        return this.sdk._request("/v1/tools/web-check", {
+            query: { url }
+        }) as Promise<ApiResponse<WebCheckResult>>;
+    }
+
+    /**
+     * Retrieves DNS records for a specific domain.
+     * @param domain The domain name to query.
+     * @returns A promise that resolves to the DNS results.
+     */
+    async dns(domain: string): Promise<ApiResponse<DnsResult>> {
+        return this.sdk._request("/v1/tools/dns", {
+            query: { domain }
+        }) as Promise<ApiResponse<DnsResult>>;
+    }
+
+    /**
+     * Retrieves SSL certificate information for a domain.
+     * @param domain The domain name to query.
+     * @returns A promise that resolves to the SSL information.
+     */
+    async ssl(domain: string): Promise<ApiResponse<SslResult>> {
+        return this.sdk._request("/v1/tools/ssl", {
+            query: { domain }
+        }) as Promise<ApiResponse<SslResult>>;
+    }
+
+    /**
+     * Retrieves OpenGraph metadata for a given URL.
+     * @param url The URL to analyze.
+     * @returns A promise that resolves to the metadata.
+     */
+    async meta(url: string): Promise<ApiResponse> {
+        return this.sdk._request("/v1/tools/meta", {
+            query: { url }
+        }) as Promise<ApiResponse>;
+    }
+
+    /**
+     * Generates a QR Code image.
+     * @param text The text or URL to encode in the QR code.
+     * @returns A promise that resolves to a Response object containing the image.
+     */
+    async qr(text: string): Promise<Response> {
+        return this.sdk._request("/v1/tools/qr", {
+            query: { text }
+        }) as Promise<Response>;
+    }
+
+    /**
+     * Generates a Barcode image.
+     * @param text The text to encode in the barcode.
+     * @param options Configuration options for barcode generation.
+     * @returns A promise that resolves to a Response object containing the image.
+     */
+    async barcode(text: string, options: BarcodeOptions = {}): Promise<Response> {
+        return this.sdk._request("/v1/tools/barcode", {
+            query: {
+                text,
+                type: options.type,
+                show_text: options.showText ?? true,
+                scale: options.scale,
+                height: options.height
+            }
+        }) as Promise<Response>;
+    }
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@cludz/sdk",
+  "description": "Cludz API JavaScript SDK",
+  "version": "0.2.3",
+  "module": "index.ts",
+  "type": "module",
+  "private": false,
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/types.ts

@@ -0,0 +1,290 @@
+/**
+ * Options for initializing the Cludz client.
+ */
+export interface CludzOptions {
+    /** The base URL of the Cludz API. */
+    api: string;
+    /** The API key for authentication. */
+    key?: string;
+}
+
+/**
+ * Standard API response wrapper.
+ * @template T The type of the data returned by the API.
+ */
+export interface ApiResponse<T = any> {
+    /** HTTP status code. */
+    statusCode: number;
+    /** Short description of the status. */
+    statusMessage: string;
+    /** Detailed message from the server. */
+    message: string;
+    /** The actual response data. */
+    data: T;
+}
+
+/**
+ * Options for making an internal SDK request.
+ */
+export interface RequestOptions {
+    /** The HTTP method to use. */
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    /** URL query parameters. */
+    query?: Record<string, any>;
+    /** Request body data. */
+    body?: any;
+}
+
+/**
+ * Information about the current account and API key.
+ */
+export interface AccountInfo {
+    /** Account details. */
+    account: {
+        /** Unique account identifier. */
+        id: string;
+    };
+    /** API key details. */
+    token: {
+        /** Name of the API key. */
+        name: string;
+        /** Total number of requests made with this key. */
+        total_requests: number;
+        /** Last time the key was used. */
+        last_used_at: string | null;
+        /** When the key was created. */
+        created_at: string;
+    };
+    /** License details. */
+    license: {
+        /** License name. */
+        name: string;
+        /** Whether the license is currently active. */
+        is_active: boolean;
+        /** When the license expires. */
+        expires_at: string | null;
+    };
+    /** Rate limiting details. */
+    rate_limit: {
+        /** Maximum requests allowed per minute. */
+        limit_per_minute: number;
+        /** Requests used in the current minute. */
+        used_this_minute: number;
+        /** Requests remaining for the current minute. */
+        remaining: number;
+        /** When the rate limit resets. */
+        reset_at: string;
+        /** Seconds remaining until the rate limit resets. */
+        reset_in_seconds: number;
+    };
+}
+
+/**
+ * Statistics for API monitoring.
+ */
+export interface MonitoringStats {
+    /** Total requests processed. */
+    requests: number;
+    /** Server uptime string. */
+    uptime: string;
+    /** Current error rate percentage. */
+    error_rate: number;
+    /** Average response time in milliseconds. */
+    avg_response_time_ms: number;
+    /** Timestamp of the statistics. */
+    timestamp: string;
+}
+
+/**
+ * Represents a single YouTube search result.
+ */
+export interface YouTubeSearchResult {
+    /** YouTube video ID. */
+    id: string;
+    /** Video title. */
+    title: string;
+    /** YouTube video URL. */
+    url: string;
+    /** Thumbnail image URL. */
+    thumbnail: string;
+    /** Video description. */
+    description: string;
+    /** Duration in seconds. */
+    duration: number;
+    /** Formatted duration string (e.g., "3:45"). */
+    duration_string: string;
+    /** Number of views. */
+    views: number;
+    /** URL of the video webpage. */
+    webpage_url: string;
+}
+
+/**
+ * List of YouTube search results.
+ */
+export interface YouTubeSearchList {
+    /** Number of results returned. */
+    count: number;
+    /** The list of search results. */
+    list: YouTubeSearchResult[];
+}
+
+/**
+ * Result of a media download request.
+ */
+export interface DownloadResult {
+    /** The URL where the media can be downloaded. */
+    download_url: string;
+}
+
+/**
+ * Result of a web connectivity check.
+ */
+export interface WebCheckResult {
+    /** HTTP status code of the target URL. */
+    status: number;
+    /** HTTP status text. */
+    statusText: string;
+    /** Content type of the response. */
+    contentType: string;
+    /** Latency in a human-readable format. */
+    latency: string;
+}
+
+/**
+ * DNS lookup results.
+ */
+export interface DnsResult {
+    /** A (IPv4) records. */
+    A?: string[];
+    /** AAAA (IPv6) records. */
+    AAAA?: string[];
+    /** MX (Mail Exchange) records. */
+    MX?: { exchange: string; priority: number }[];
+    /** TXT (Text) records. */
+    TXT?: string[][];
+    /** NS (Name Server) records. */
+    NS?: string[];
+}
+
+/**
+ * SSL certificate information.
+ */
+export interface SslResult {
+    /** Certificate subject. */
+    subject: any;
+    /** Certificate issuer. */
+    issuer: any;
+    /** Start of validity period. */
+    valid_from: string;
+    /** End of validity period. */
+    valid_to: string;
+    /** Days remaining until expiration. */
+    remaining_days: number;
+}
+
+/**
+ * Result of starting a background task.
+ */
+export interface TaskResult {
+    /** Unique task identifier. */
+    taskId: string;
+    /** URL to poll for task status. */
+    status_url: string;
+}
+
+/**
+ * Unified interface representing all possible task result data.
+ * All fields are optional to support different task types.
+ */
+export interface TaskData {
+    /** Number of results (YouTube search). */
+    count?: number;
+    /** List of search results (YouTube search). */
+    list?: YouTubeSearchResult[];
+    /** URL for media download (Downloader). */
+    download_url?: string;
+    /** HTTP status code (Web check). */
+    status?: number;
+    /** HTTP status text (Web check). */
+    statusText?: string;
+    /** Response content type (Web check). */
+    contentType?: string;
+    /** Response latency (Web check). */
+    latency?: string;
+    /** IPv4 records (DNS). */
+    A?: string[];
+    /** IPv6 records (DNS). */
+    AAAA?: string[];
+    /** MX records (DNS). */
+    MX?: { exchange: string; priority: number }[];
+    /** TXT records (DNS). */
+    TXT?: string[][];
+    /** Name server records (DNS). */
+    NS?: string[];
+    /** Certificate subject (SSL). */
+    subject?: any;
+    /** Certificate issuer (SSL). */
+    issuer?: any;
+    /** Certificate valid from date (SSL). */
+    valid_from?: string;
+    /** Certificate valid to date (SSL). */
+    valid_to?: string;
+    /** Days remaining for SSL certificate (SSL). */
+    remaining_days?: number;
+}
+
+/**
+ * Current state of a background task.
+ * @template T The type of the result data when the task is completed. Defaults to TaskData.
+ */
+export interface TaskState<T = TaskData> {
+    /** Unique task identifier. */
+    id: string;
+    /** User ID associated with the task, if any. */
+    user_id: string | null;
+    /** Current status of the task. */
+    status: "Pending" | "Processing" | "Completed" | "Failed";
+    /** Progress percentage (0-100). */
+    progress: number;
+    /** Status message or update. */
+    message: string | null;
+    /** Final task result data. */
+    data: T | null;
+    /** Error message if the task failed. */
+    error: string | null;
+    /** When the task was created. */
+    created_at: string;
+    /** When the task was last updated. */
+    updated_at: string;
+}
+
+/**
+ * Options for initializing a Storage instance.
+ */
+export interface StorageOptions {
+    /** The base URL of the Cludz Storage API. */
+    api: string;
+    /** The storage container identifier. */
+    id: string;
+    /** The access token for this storage container. */
+    token: string;
+}
+
+/**
+ * Information about a file or directory in storage.
+ */
+export interface FileInfo {
+    /** Name of the item. */
+    name: string;
+    /** Size in bytes. */
+    size: number;
+    /** Whether the item is a directory. */
+    isDirectory: boolean;
+    /** Item checksum for integrity verification. */
+    checksum: string;
+    /** When the item was created. */
+    created_at: string;
+    /** When the item was last modified. */
+    modified_at: string;
+}