offline-cloudinary 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Max Essien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,166 @@
+# Offline Cloudinary
+
+An **offline Cloudinary-like file manager** for Node.js — designed for developers who need a simple, local alternative to Cloudinary for uploads, deletions, and testing without internet access.
+
+---
+
+## Features
+
+- Local file uploads and deletions  
+- Cloudinary-style API responses  
+- Simple environment-based configuration  
+- Clear all stored uploads with one command  
+- Perfect for testing, prototyping, or offline development  
+
+---
+
+## Installation
+
+```bash
+npm install offline-cloudinary
+```
+
+or with Yarn:
+
+```bash
+yarn add offline-cloudinary
+```
+
+---
+
+## Setup
+
+In your project’s `.env` file, define the base path for all offline uploads:
+
+```
+CLOUDINARY_OFFLINE_PATH=./offline_uploads
+```
+
+This path will serve as your “offline cloud” — all uploaded files will be stored here.
+
+---
+
+## Usage Example
+
+```js
+import offlineCloudinary from "offline-cloudinary";
+
+(async () => {
+  try {
+    // Upload a file
+    const uploadResult = await offlineCloudinary.upload("./temp/photo.jpg", {
+      folder: "users/avatars",
+      fileName: "max-essien"
+    });
+
+    console.log("Upload result:", uploadResult);
+
+    // Delete the uploaded file
+    const deleteResult = await offlineCloudinary.destroy(uploadResult.public_id);
+    console.log("Delete result:", deleteResult);
+
+    // Clear all files in the storage folder
+    const clearResult = await offlineCloudinary.clearStorage();
+    console.log("Storage cleared:", clearResult);
+  } catch (err) {
+    console.error("Error:", err.message);
+  }
+})();
+```
+
+---
+
+## API Reference
+
+### **`new OfflineCloudinary()`**
+Automatically instantiated when imported.  
+Throws an error if `CLOUDINARY_OFFLINE_PATH` is not set.
+
+---
+
+### **`upload(tempFilePath, options)`**
+
+Uploads a file from a temporary path to your offline storage.
+
+**Parameters**
+| Name | Type | Description |
+|------|------|--------------|
+| `tempFilePath` | `string` | Path to the source file to upload |
+| `options.folder` | `string` | Optional nested folder path |
+| `options.fileName` | `string` | Optional custom file name (without extension) |
+
+**Returns**
+A Cloudinary-like object containing:
+```js
+{
+  asset_id, public_id, version, format, resource_type,
+  created_at, bytes, url, secure_url, ...
+}
+```
+
+---
+
+### **`destroy(public_id)`**
+
+Deletes a file from your offline storage.
+
+**Parameters**
+| Name | Type | Description |
+|------|------|--------------|
+| `public_id` | `string` | Full path returned by the upload method |
+
+**Returns**
+```js
+{ result: "ok" }
+```
+
+---
+
+### **`clearStorage()`**
+
+Deletes all files and folders in your offline Cloudinary storage.
+
+**Returns**
+```js
+{ result: "ok" }
+```
+
+---
+
+## Example .env
+
+```
+CLOUDINARY_OFFLINE_PATH=./uploads
+```
+
+---
+
+## Example Folder Structure
+
+```
+project/
+├── .env
+├── uploads/
+│   └── users/
+│       └── avatars/
+│           └── max-essien.jpg
+└── index.js
+```
+
+---
+
+## Author
+
+**Max Essien**  
+📍 Lagos, Nigeria  
+🔗 [GitHub: @MaxEssien](https://github.com/MaxEssien)
+
+---
+
+## License
+
+This project is licensed under the **MIT License** — free for personal and commercial use.
+
+---
+**Offline Cloudinary** — your Cloudinary, anywhere, even offline.
+

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "offline-cloudinary",
+  "version": "1.0.0",
+  "description": "An offline Cloudinary-like file manager for local uploads and deletions.",
+  "main": "src/utils/OfflineCloudinary.js",
+  "type": "module",
+  "keywords": [
+    "cloudinary",
+    "offline",
+    "upload",
+    "local-storage",
+    "mock",
+    "testing",
+    "file-system",
+    "nodejs"
+  ],
+  "author": "Max Essien",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaxEssien/offline-cloudinary"
+  },
+  "files": ["src"],
+  "scripts": {
+    "test": "node src/utils/OfflineCloudinary.js"
+  },
+  "bugs": {
+    "url": "https://github.com/MaxEssien/offline-cloudinary/issues"
+  },
+  "homepage": "https://github.com/MaxEssien/offline-cloudinary#readme"
+}

package/src/index.js

@@ -0,0 +1,92 @@
+import fs from "fs/promises";
+import path from "path";
+import crypto from "crypto";
+
+class OfflineCloudinary {
+  constructor() {
+    if (!process.env.CLOUDINARY_OFFLINE_PATH) {
+      throw new Error(
+        "Please set CLOUDINARY_OFFLINE_PATH in your .env file"
+      );
+    }
+    this.rootPath = process.env.CLOUDINARY_OFFLINE_PATH;
+  }
+
+  /**
+   * Upload a file
+   * @param {string} tempFilePath - Path to the temporary file
+   * @param {object} options - { folder: 'nested/folder/path' }
+   * @returns Cloudinary-like response
+   */
+  async upload(tempFilePath, options = {}) {
+    await fs.access(tempFilePath).catch(()=>{throw new Error(`File not found: ${tempFilePath}`)})
+    const folder = options.folder || "";
+    const name = options?.fileName || crypto.randomUUID();
+    const fullFolderPath = path.join(this.rootPath, folder);
+
+    // Ensure folder exists
+    await fs.mkdir(fullFolderPath, { recursive: true });
+
+    // Generate unique filename
+    const ext = path.extname(tempFilePath);
+    if (!ext?.trim()) throw new Error("Unsupported file type")
+    const fileName = name + ext;
+
+    const finalPath = path.join(fullFolderPath, fileName);
+
+    // Copy file from temp path
+    await fs.copyFile(tempFilePath, finalPath);
+
+    // Get file stats
+    const stats = await fs.stat(finalPath);
+
+    const now = new Date().toISOString();
+
+    // Return Cloudinary-like response
+    return {
+      asset_id: crypto.randomUUID(),
+      public_id: finalPath,
+      version: Date.now(),
+      version_id: crypto.randomUUID(),
+      signature: crypto.randomBytes(16).toString("hex"),
+      width: null,
+      height: null,
+      format: ext.replace(".", ""),
+      resource_type: "image",
+      created_at: now,
+      tags: [],
+      pages: 1,
+      bytes: stats.size,
+      type: "upload",
+      etag: crypto.randomBytes(8).toString("hex"),
+      placeholder: false,
+      url: finalPath,
+      secure_url: finalPath,
+    };
+  }
+
+  /**
+   * Destroy a file by public_id
+   * @param {string} public_id
+   * @returns {object} { result: "ok" } if deleted or { result: "not found" }
+   */
+  async destroy(public_id) {
+    const filePath = public_id;
+    await fs.unlink(filePath);
+    return { result: "ok" };
+  }
+
+  /**
+   * Destroy every files and folder in the local offline cloudinary storage
+   * @returns {object} {result: ok} if successful
+   */
+  async clearStorage(){
+    await fs.rm(this.rootPath, {recursive: true, force: true})
+    await fs.mkdir(this.rootPath)
+    return {result: "ok"}
+  }
+}
+
+const offlineCloudinary = new OfflineCloudinary()
+
+export default offlineCloudinary;