cloudinary-lite 1.0.0

package/index.js

@@ -0,0 +1,160 @@
+/**
+ * cloudinary-lite
+ * Zero-dependency, lightweight helper library for Cloudinary.
+ * Supported in both browser and server environments.
+ */
+
+/**
+ * Uploads a file directly to Cloudinary from the browser using an unsigned preset.
+ * 
+ * @param {Object} params
+ * @param {File|Blob} params.file - The file object to upload.
+ * @param {string} params.cloudName - Your Cloudinary Cloud Name.
+ * @param {string} params.uploadPreset - The name of the unsigned upload preset.
+ * @param {string} [params.folder] - Optional folder path to save the asset.
+ * @returns {Promise<string>} - The secure URL of the uploaded asset.
+ */
+export async function uploadUnsigned({ file, cloudName, uploadPreset, folder = 'others' }) {
+  if (!file || !cloudName || !uploadPreset) {
+    throw new Error('Missing required arguments: file, cloudName, and uploadPreset are required.');
+  }
+
+  const url = `https://api.cloudinary.com/v1_1/${cloudName}/upload`;
+  const formData = new FormData();
+  formData.append('file', file);
+  formData.append('upload_preset', uploadPreset);
+  formData.append('folder', folder);
+
+  const response = await fetch(url, {
+    method: 'POST',
+    body: formData
+  });
+
+  if (!response.ok) {
+    const errorData = await response.json();
+    throw new Error(errorData.error?.message || 'Cloudinary upload failed');
+  }
+
+  const data = await response.json();
+  if (data && data.secure_url) {
+    return data.secure_url;
+  } else {
+    throw new Error('Failed to get secure URL from Cloudinary upload response');
+  }
+}
+
+/**
+ * Deletes an asset from Cloudinary. 
+ * Secure operation - MUST only be called in server environments (Node.js).
+ * 
+ * @param {Object} params
+ * @param {string} params.publicId - The Cloudinary public ID of the resource.
+ * @param {string} [params.resourceType] - The resource type: 'image', 'raw', or 'video'.
+ * @param {string} params.cloudName - Your Cloudinary Cloud Name.
+ * @param {string} params.apiKey - Your Cloudinary API Key.
+ * @param {string} params.apiSecret - Your Cloudinary API Secret.
+ * @returns {Promise<boolean>} - True if deletion succeeded, false otherwise.
+ */
+export async function deleteSigned({ publicId, resourceType = 'image', cloudName, apiKey, apiSecret }) {
+  if (!publicId || !cloudName || !apiKey || !apiSecret) {
+    throw new Error('Missing required arguments for deletion: publicId, cloudName, apiKey, and apiSecret are required.');
+  }
+
+  // Use dynamic import of Node's native 'crypto' module so frontend bundlers
+  // do not compile Node-specific APIs if this function is not imported.
+  const crypto = await import('crypto');
+
+  const timestamp = Math.round(new Date().getTime() / 1000);
+  
+  // Generate SHA-1 signature
+  const signatureData = `public_id=${publicId}&timestamp=${timestamp}${apiSecret}`;
+  const signature = crypto.createHash('sha1').update(signatureData).digest('hex');
+
+  const url = `https://api.cloudinary.com/v1_1/${cloudName}/${resourceType}/destroy`;
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      public_id: publicId,
+      timestamp,
+      api_key: apiKey,
+      signature
+    })
+  });
+
+  if (!response.ok) {
+    const errorData = await response.json();
+    throw new Error(errorData.error?.message || 'Failed to destroy resource');
+  }
+
+  const result = await response.json();
+  return result.result === 'ok';
+}
+
+/**
+ * Helper to parse a Cloudinary URL and extract its public ID and resource type.
+ * 
+ * @param {string} url - The complete Cloudinary URL.
+ * @returns {Object|null} - An object containing { public_id, resource_type } or null.
+ */
+export function parseCloudinaryUrl(url) {
+  if (!url || typeof url !== 'string' || !url.includes('cloudinary.com')) {
+    return null;
+  }
+
+  try {
+    const parsed = new URL(url);
+    const path = parsed.pathname;
+    
+    // Split pathname: /de3t60fd7/image/upload/v1722513904/alumni/profile-photos/abc123xyz.jpg
+    const parts = path.split('/').filter(Boolean);
+    if (parts.length < 4) {
+      return null;
+    }
+
+    const resourceType = parts[1]; // e.g. "image" or "raw"
+    
+    // Find version index (starts with v followed by numbers)
+    let versionIndex = -1;
+    for (let i = 3; i < parts.length; i++) {
+      const part = parts[i];
+      if (part.startsWith('v') && !isNaN(part.slice(1)) && /^\d+$/.test(part.slice(1))) {
+        versionIndex = i;
+        break;
+      }
+    }
+
+    // Fallback if version not found (take index after upload)
+    if (versionIndex === -1) {
+      const uploadIndex = parts.indexOf('upload');
+      if (uploadIndex !== -1) {
+        versionIndex = uploadIndex + 1;
+      }
+    }
+
+    if (versionIndex === -1) {
+      return null;
+    }
+
+    const publicIdParts = parts.slice(versionIndex + 1);
+    const publicIdWithExt = publicIdParts.join('/');
+
+    let publicId = publicIdWithExt;
+    if (resourceType !== 'raw') {
+      const dotIndex = publicIdWithExt.lastIndexOf('.');
+      if (dotIndex !== -1) {
+        publicId = publicIdWithExt.slice(0, dotIndex);
+      }
+    }
+
+    return {
+      public_id: publicId,
+      resource_type: resourceType
+    };
+  } catch (_) {
+    return null;
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "cloudinary-lite",
+  "version": "1.0.0",
+  "description": "Zero-dependency, lightweight helper for Cloudinary uploads (unsigned client-side) and secure deletes (signed server-side).",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 0"
+  },
+  "keywords": [
+    "cloudinary",
+    "lite",
+    "upload",
+    "delete",
+    "unsigned",
+    "client",
+    "server"
+  ],
+  "author": "Saiful Islam",
+  "license": "MIT"
+}

package/readme.md

@@ -0,0 +1,122 @@
+# Cloudinary-Lite
+
+A zero-dependency, ultra-lightweight utility library to handle **unsigned client-side uploads** and **signed server-side deletions** with Cloudinary. Works seamlessly in all modern browser environments (React, Angular, Vue, Svelte, Vanilla JS) and Node.js server runtimes.
+
+---
+
+## Installation
+
+Install the package via NPM:
+
+```bash
+npm install cloudinary-lite
+```
+
+---
+
+## Credential Configuration
+
+### 1. Client-Side Upload (Public Credentials)
+For public client-side uploading, only the public **Cloud Name** and **Upload Preset** are required. You should **never** expose your API Secret on the client side.
+
+Define these in your frontend `.env` file (e.g. Vite format):
+```env
+VITE_CLOUDINARY_CLOUD_NAME=your_cloud_name
+VITE_CLOUDINARY_UPLOAD_PRESET=your_unsigned_preset
+```
+
+### 2. Server-Side Deletion (Secret Credentials)
+For server-side deletions, you need your private **API Key** and **API Secret** to sign the deletion requests securely.
+
+Define these in your server environment variables or `.env` file:
+```env
+CLOUDINARY_CLOUD_NAME=your_cloud_name
+CLOUDINARY_API_KEY=your_api_key
+CLOUDINARY_API_SECRET=your_api_secret
+```
+
+---
+
+## API Reference
+
+### 1. Unsigned Upload (Client-Side)
+
+Upload files directly from the browser to Cloudinary.
+
+```javascript
+import { uploadUnsigned } from 'cloudinary-lite';
+
+async function handleFileChange(event) {
+  const file = event.target.files[0];
+  if (!file) return;
+
+  try {
+    const secureUrl = await uploadUnsigned({
+      file,
+      cloudName: import.meta.env.VITE_CLOUDINARY_CLOUD_NAME,
+      uploadPreset: import.meta.env.VITE_CLOUDINARY_UPLOAD_PRESET,
+      folder: 'alumni/photos' // Optional folder path
+    });
+
+    console.log('Uploaded successfully! URL:', secureUrl);
+  } catch (error) {
+    console.error('Upload failed:', error.message);
+  }
+}
+```
+
+---
+
+### 2. Signed Deletion (Server-Side / Node.js)
+
+Delete assets securely from a backend server. This function dynamically imports Node's native `crypto` module to securely sign requests.
+
+```javascript
+import { deleteSigned } from 'cloudinary-lite';
+
+async function deleteUserAsset(publicId, resourceType) {
+  try {
+    const success = await deleteSigned({
+      publicId,
+      resourceType, // 'image', 'raw', or 'video'
+      cloudName: process.env.CLOUDINARY_CLOUD_NAME,
+      apiKey: process.env.CLOUDINARY_API_KEY,
+      apiSecret: process.env.CLOUDINARY_API_SECRET
+    });
+
+    if (success) {
+      console.log('Asset deleted successfully');
+    } else {
+      console.warn('Asset deletion did not return success state');
+    }
+  } catch (error) {
+    console.error('Failed to delete asset:', error.message);
+  }
+}
+```
+
+---
+
+### 3. Parse Cloudinary URLs (Universal Helper)
+
+Extract the `public_id` and the `resource_type` from a complete secure URL. Useful when you only store the file URL in the database and need to resolve it for deletion.
+
+```javascript
+import { parseCloudinaryUrl } from 'cloudinary-lite';
+
+const url = 'https://res.cloudinary.com/de3t60fd7/image/upload/v1722513904/alumni/profile-photos/abc123xyz.jpg';
+const parsed = parseCloudinaryUrl(url);
+
+console.log(parsed);
+// Output:
+// {
+//   public_id: "alumni/profile-photos/abc123xyz",
+//   resource_type: "image"
+// }
+```
+
+---
+
+## License
+
+MIT