offline-cloudinary 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2025-12-15
+
+### Breaking Changes
+
+- **Main export location changed**: Moved from `src/index.js` to root `index.js`
+- **Port configuration**: Now requires `CLOUDINARY_OFFLINE_PORT` environment variable
+- **Public ID format**: `public_id` is now a UUID instead of a file path
+- **Upload response URL**: The `url` field now returns an HTTP endpoint (`http://localhost:PORT/file/{id}`) instead of a file path
+- **Secure URL**: The `secure_url` field also now returns an HTTP endpoint (`http://localhost:PORT/file/{id}`) instead of a file path
+
+### Added
+
+- **HTTP Server Emulator**: New `startEmulator()` function to run a local Express server that serves uploaded files
+- **File viewing endpoint**: GET `/file/:id` endpoint to view/download uploaded files via HTTP
+- **Upload tracking**: Internal `uploads.json` file maps UUIDs to file paths
+- **New environment variable**: `CLOUDINARY_OFFLINE_PORT` for configuring the server port
+- **Express integration**: Built-in CORS and Express routing support
+
+### Changed
+
+- File tracking now uses a JSON mapping file (`uploads.json`) instead of direct file paths
+- Upload method now generates UUID-based public IDs for better privacy and consistency
+- Files can now be accessed via HTTP URLs when the emulator is running
+
+### Migration Guide from v1.x to v2.x
+
+#### 1. Update your `.env` file
+
+Add the new port configuration:
+
+```env
+CLOUDINARY_OFFLINE_PATH=./offline_uploads
+CLOUDINARY_OFFLINE_PORT=3000
+```
+
+#### 2. Start the emulator
+
+```js
+import { startEmulator, offlineCloudinary } from "offline-cloudinary";
+
+// Start the HTTP server
+startEmulator();
+```
+
+#### 3. Update public_id handling
+
+**Before (v1):**
+```js
+const result = await offlineCloudinary.upload("./photo.jpg");
+// result.public_id was a file path like "./offline_uploads/photo.jpg"
+```
+
+**After (v2):**
+```js
+const result = await offlineCloudinary.upload("./photo.jpg");
+// result.public_id is now a UUID like "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+// result.url is "http://localhost:3000/file/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+// result.secure_url is the actual file path
+```
+
+#### 4. Update destroy calls
+
+Use the UUID from upload response:
+
+```js
+const uploadResult = await offlineCloudinary.upload("./photo.jpg");
+await offlineCloudinary.destroy(uploadResult.public_id); // Pass the UUID
+```
+
+---
+
+## [1.0.0] - Initial Release
+
+### Added
+
+- Initial release with basic upload, delete, and clearStorage functionality
+- Environment-based path configuration via `CLOUDINARY_OFFLINE_PATH`
+- Cloudinary-like response format
+- Support for nested folder structures
+- Custom filename option
+
+[2.0.0]: https://github.com/MaxEssien/offline-cloudinary/compare/v1.0.0...v2.0.0
+[1.0.0]: https://github.com/MaxEssien/offline-cloudinary/releases/tag/v1.0.0

package/README.md

@@ -6,9 +6,10 @@ An **offline Cloudinary-like file manager** for Node.js — designed for develop
 
 ## Features
 
-- Local file uploads and deletions  
+- Local file uploads and deletions with HTTP server emulator
 - Cloudinary-style API responses  
 - Simple environment-based configuration  
+- Built-in Express server to serve uploaded files via HTTP
 - Clear all stored uploads with one command  
 - Perfect for testing, prototyping, or offline development  
 
@@ -30,20 +31,25 @@ yarn add offline-cloudinary
 
 ## Setup
 
-In your project’s `.env` file, define the base path for all offline uploads:
+In your project's `.env` file, define the configuration for offline uploads:
 
-```
+```env
 CLOUDINARY_OFFLINE_PATH=./offline_uploads
+CLOUDINARY_OFFLINE_PORT=3000
 ```
 
-This path will serve as your “offline cloud” — all uploaded files will be stored here.
+- **`CLOUDINARY_OFFLINE_PATH`**: Base directory where uploaded files will be stored
+- **`CLOUDINARY_OFFLINE_PORT`**: Port number for the HTTP server emulator
 
 ---
 
-## Usage Example
+## Quick Start
 
 ```js
-import offlineCloudinary from "offline-cloudinary";
+import { startEmulator, offlineCloudinary } from "offline-cloudinary";
+
+// Start the HTTP server to serve uploaded files
+startEmulator();
 
 (async () => {
   try {
@@ -54,6 +60,11 @@ import offlineCloudinary from "offline-cloudinary";
     });
 
     console.log("Upload result:", uploadResult);
+    // uploadResult.url: "http://localhost:3000/file/{uuid}"
+    // uploadResult.public_id: UUID identifier
+
+    // Access the file via HTTP
+    console.log(`View file at: ${uploadResult.url}`);
 
     // Delete the uploaded file
     const deleteResult = await offlineCloudinary.destroy(uploadResult.public_id);
@@ -72,16 +83,39 @@ import offlineCloudinary from "offline-cloudinary";
 
 ## API Reference
 
-### **`new OfflineCloudinary()`**
-Automatically instantiated when imported.  
+### **`startEmulator()`**
+
+Starts the Express HTTP server to serve uploaded files.
+
+**Important**: Must be called to enable HTTP access to uploaded files via the `url` field.
+
+**Environment Variables Required:**
+- `CLOUDINARY_OFFLINE_PORT` - Port number for the server
+
+**Example:**
+```js
+import { startEmulator } from "offline-cloudinary";
+
+startEmulator();
+// Server running on port specified in CLOUDINARY_OFFLINE_PORT
+```
+
+---
+
+### **`offlineCloudinary`**
+
+The main instance for file operations. Automatically instantiated when imported.  
 Throws an error if `CLOUDINARY_OFFLINE_PATH` is not set.
 
 ---
 
-### **`upload(tempFilePath, options)`**
+### **`offlineCloudinary.upload(tempFilePath, options)`**
 
 Uploads a file from a temporary path to your offline storage.
 
+**Environment Variables Required:**
+- `CLOUDINARY_OFFLINE_PORT` - Used to generate the HTTP URL
+
 **Parameters**
 | Name | Type | Description |
 |------|------|--------------|
@@ -90,33 +124,67 @@ Uploads a file from a temporary path to your offline storage.
 | `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, ...
+  asset_id: "uuid-v4",
+  public_id: "uuid-v4",           // UUID identifier for this file
+  version: 1702654321000,          // Timestamp
+  version_id: "uuid-v4",
+  signature: "hex-string",
+  width: null,
+  height: null,
+  format: "jpg",                   // File extension
+  resource_type: "image",
+  created_at: "2025-12-15T10:30:00.000Z",
+  tags: [],
+  pages: 1,
+  bytes: 102400,                   // File size in bytes
+  type: "upload",
+  etag: "hex-string",
+  placeholder: false,
+  url: "http://localhost:3000/file/{uuid}",      // HTTP URL to access file
+  secure_url: "/path/to/actual/file.jpg"         // Actual file system path
 }
 ```
 
+**Example:**
+```js
+const result = await offlineCloudinary.upload("./photo.jpg", {
+  folder: "users/avatars",
+  fileName: "profile-pic"
+});
+
+console.log(result.url);        // "http://localhost:3000/file/abc123..."
+console.log(result.public_id);  // "abc123-def456-789..."
+```
+
 ---
 
-### **`destroy(public_id)`**
+### **`offlineCloudinary.destroy(public_id)`**
 
-Deletes a file from your offline storage.
+Deletes a file from your offline storage using its UUID.
 
 **Parameters**
 | Name | Type | Description |
 |------|------|--------------|
-| `public_id` | `string` | Full path returned by the upload method |
+| `public_id` | `string` | UUID returned by the upload method |
 
 **Returns**
 ```js
 { result: "ok" }
 ```
 
+**Example:**
+```js
+const uploadResult = await offlineCloudinary.upload("./photo.jpg");
+await offlineCloudinary.destroy(uploadResult.public_id);
+```
+
 ---
 
-### **`clearStorage()`**
+### **`offlineCloudinary.clearStorage()`**
 
 Deletes all files and folders in your offline Cloudinary storage.
 
@@ -125,12 +193,19 @@ Deletes all files and folders in your offline Cloudinary storage.
 { result: "ok" }
 ```
 
+**Example:**
+```js
+await offlineCloudinary.clearStorage();
+console.log("All files deleted");
+```
+
 ---
 
 ## Example .env
 
-```
+```env
 CLOUDINARY_OFFLINE_PATH=./uploads
+CLOUDINARY_OFFLINE_PORT=3000
 ```
 
 ---
@@ -140,6 +215,7 @@ CLOUDINARY_OFFLINE_PATH=./uploads
 ```
 project/
 ├── .env
+├── uploads.json                    # Auto-generated UUID mapping
 ├── uploads/
 │   └── users/
 │       └── avatars/
@@ -149,6 +225,42 @@ project/
 
 ---
 
+## Migration from v1.x to v2.x
+
+### Breaking Changes
+
+1. **New environment variable required**: `CLOUDINARY_OFFLINE_PORT`
+2. **Import changed**: Now exports `{ startEmulator, offlineCloudinary }` instead of default export
+3. **public_id format**: Now returns UUID instead of file path
+4. **URL field**: Now returns HTTP endpoint instead of file path
+5. **Must call startEmulator()** to serve files via HTTP
+
+### Migration Steps
+
+**Before (v1.x):**
+```js
+import offlineCloudinary from "offline-cloudinary";
+
+const result = await offlineCloudinary.upload("./photo.jpg");
+// result.public_id was a file path
+```
+
+**After (v2.x):**
+```js
+import { startEmulator, offlineCloudinary } from "offline-cloudinary";
+
+// Add CLOUDINARY_OFFLINE_PORT=3000 to your .env
+
+startEmulator(); // Start the HTTP server
+
+const result = await offlineCloudinary.upload("./photo.jpg");
+// result.public_id is now a UUID
+// result.url is "http://localhost:3000/file/{uuid}"
+// result.secure_url is "http://localhost:3000/file/{uuid}"
+```
+
+---
+
 ## Author
 
 **Max Essien**  
@@ -162,5 +274,12 @@ project/
 This project is licensed under the **MIT License** — free for personal and commercial use.
 
 ---
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history and migration guides.
+
+---
+
 **Offline Cloudinary** — your Cloudinary, anywhere, even offline.
 

package/index.js

@@ -0,0 +1,21 @@
+import express from "express";
+import fileRoutes from "./src/routes/fileRoutes.js";
+import offlineCloudinary from "./src/utils/offline-cloudinary";
+import cors from "cors";
+
+const app = express();
+
+app.use(cors());
+
+app.use("/file", fileRoutes);
+
+const startEmulator = () => {
+  const portNumber = process.env.CLOUDINARY_OFFLINE_PORT;
+  if (!portNumber)
+    throw new Error("Please set CLOUDINARY_OFFLINE_PORT in your .env file");
+  app.listen(portNumber, () =>
+    console.log("Offline Cloudinary running on port", portNumber)
+  );
+};
+
+export { startEmulator, offlineCloudinary };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "offline-cloudinary",
-  "version": "1.0.0",
-  "description": "An offline Cloudinary-like file manager for local uploads and deletions.",
-  "main": "src/utils/OfflineCloudinary.js",
+  "version": "2.0.0",
+  "description": "An offline Cloudinary-like file manager with HTTP server emulator for local uploads, deletions, and testing without internet access.",
+  "main": "index.js",
   "type": "module",
   "keywords": [
     "cloudinary",
@@ -12,7 +12,12 @@
     "mock",
     "testing",
     "file-system",
-    "nodejs"
+    "nodejs",
+    "express",
+    "server",
+    "emulator",
+    "http",
+    "file-upload"
   ],
   "author": "Max Essien",
   "license": "MIT",
@@ -20,12 +25,25 @@
     "type": "git",
     "url": "https://github.com/MaxEssien/offline-cloudinary"
   },
-  "files": ["src"],
+  "files": [
+    "src",
+    "index.js",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "test": "node src/utils/OfflineCloudinary.js"
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   },
   "bugs": {
     "url": "https://github.com/MaxEssien/offline-cloudinary/issues"
   },
-  "homepage": "https://github.com/MaxEssien/offline-cloudinary#readme"
+  "homepage": "https://github.com/MaxEssien/offline-cloudinary#readme",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^5.2.1"
+  }
 }

package/src/controllers/fileControllers.js

@@ -0,0 +1,10 @@
+import offlineCloudinary from '../utils/offline-cloudinary.js';
+import fs from 'fs/promises';
+
+export const viewImage = async(req, res)=>{
+    const uploadId = req.params.id
+    const data = await fs.readFile("uploads.json", "utf-8")
+    const mappings = JSON.parse(data)
+    res.setHeader("Content-Disposition", "inline")
+    return res.sendFile(`${offlineCloudinary.rootPath}/${mappings[uploadId]}`)
+}

package/src/routes/fileRoutes.js

@@ -0,0 +1,8 @@
+import express from "express";
+import { viewImage } from "../controllers/fileControllers.js";
+
+const router = express.Router()
+
+router.get("/:id", viewImage)
+
+export default router

package/src/{index.js → utils/offline-cloudinary.js}

@@ -5,9 +5,7 @@ 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"
-      );
+      throw new Error("Please set CLOUDINARY_OFFLINE_PATH in your .env file");
     }
     this.rootPath = process.env.CLOUDINARY_OFFLINE_PATH;
   }
@@ -19,7 +17,12 @@ class OfflineCloudinary {
    * @returns Cloudinary-like response
    */
   async upload(tempFilePath, options = {}) {
-    await fs.access(tempFilePath).catch(()=>{throw new Error(`File not found: ${tempFilePath}`)})
+    const portNumber = process.env.CLOUDINARY_OFFLINE_PORT;
+    if (!portNumber)
+      throw new Error("Please set CLOUDINARY_OFFLINE_PORT in your .env file");
+    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);
@@ -29,7 +32,7 @@ class OfflineCloudinary {
 
     // Generate unique filename
     const ext = path.extname(tempFilePath);
-    if (!ext?.trim()) throw new Error("Unsupported file type")
+    if (!ext?.trim()) throw new Error("Unsupported file type");
     const fileName = name + ext;
 
     const finalPath = path.join(fullFolderPath, fileName);
@@ -42,10 +45,19 @@ class OfflineCloudinary {
 
     const now = new Date().toISOString();
 
+    const uploadId = crypto.randomUUID();
+
+    const data = await fs.readFile("uploads.json", "utf-8");
+
+    const mappings = JSON.parse(data);
+    mappings[uploadId] = finalPath;
+
+    await fs.writeFile("uploads.json", JSON.stringify(mappings));
+
     // Return Cloudinary-like response
     return {
       asset_id: crypto.randomUUID(),
-      public_id: finalPath,
+      public_id: uploadId,
       version: Date.now(),
       version_id: crypto.randomUUID(),
       signature: crypto.randomBytes(16).toString("hex"),
@@ -60,8 +72,8 @@ class OfflineCloudinary {
       type: "upload",
       etag: crypto.randomBytes(8).toString("hex"),
       placeholder: false,
-      url: finalPath,
-      secure_url: finalPath,
+      url: `http://localhost:${portNumber}/file/${uploadId}`,
+      secure_url: `http://localhost:${portNumber}/file/${uploadId}`,
     };
   }
 
@@ -71,8 +83,10 @@ class OfflineCloudinary {
    * @returns {object} { result: "ok" } if deleted or { result: "not found" }
    */
   async destroy(public_id) {
-    const filePath = public_id;
-    await fs.unlink(filePath);
+    const uploadId = public_id;
+    const data = await fs.readFile("uploads.json", "utf-8");
+    const mappings = JSON.parse(data);
+    await fs.unlink(mappings[uploadId]);
     return { result: "ok" };
   }
 
@@ -80,13 +94,13 @@ class OfflineCloudinary {
    * 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"}
+  async clearStorage() {
+    await fs.rm(this.rootPath, { recursive: true, force: true });
+    await fs.mkdir(this.rootPath);
+    return { result: "ok" };
   }
 }
 
-const offlineCloudinary = new OfflineCloudinary()
+const offlineCloudinary = new OfflineCloudinary();
 
-export default offlineCloudinary;
+export default offlineCloudinary;

package/src/utils/uploads.json

@@ -0,0 +1 @@
+{}