cloudinary-lite 1.0.0 → 1.1.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org/'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Publish Package
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/index.js

@@ -158,3 +158,101 @@ export function parseCloudinaryUrl(url) {
     return null;
   }
 }
+
+/**
+ * Generates a transformed/scaled Cloudinary URL on the fly.
+ * 
+ * @param {string} url - The original Cloudinary secure URL.
+ * @param {Object|string} options - An object of transformations (e.g. { width: 300, height: 300, crop: 'fill', quality: 'auto', format: 'auto' }) or a raw transformation string (e.g. 'w_300,h_300,c_fill').
+ * @returns {string} - The transformed Cloudinary URL.
+ */
+export function getTransformedUrl(url, options) {
+  if (!url || typeof url !== 'string' || !url.includes('cloudinary.com')) {
+    return url;
+  }
+
+  let transformStr = '';
+  if (typeof options === 'string') {
+    transformStr = options;
+  } else if (options && typeof options === 'object') {
+    const parts = [];
+    if (options.width) parts.push(`w_${options.width}`);
+    if (options.height) parts.push(`h_${options.height}`);
+    if (options.crop) parts.push(`c_${options.crop}`);
+    if (options.quality) parts.push(`q_${options.quality}`);
+    if (options.fetch_format || options.format) parts.push(`f_${options.fetch_format || options.format}`);
+    if (options.gravity) parts.push(`g_${options.gravity}`);
+    
+    if (options.raw) parts.push(options.raw);
+    
+    transformStr = parts.join(',');
+  }
+
+  if (!transformStr) {
+    return url;
+  }
+
+  try {
+    const parsed = new URL(url);
+    const path = parsed.pathname;
+    const pathParts = path.split('/').filter(Boolean);
+
+    const uploadIndex = pathParts.indexOf('upload');
+    if (uploadIndex === -1) {
+      return url;
+    }
+
+    pathParts.splice(uploadIndex + 1, 0, transformStr);
+    
+    parsed.pathname = '/' + pathParts.join('/');
+    return parsed.toString();
+  } catch (_) {
+    return url;
+  }
+}
+
+/**
+ * Cloudinary Crop modes (`c_` transformations).
+ * @enum {string}
+ */
+export const Crop = Object.freeze({
+  FILL: 'fill',
+  LFILL: 'lfill',
+  FILL_PAD: 'fill_pad',
+  FIT: 'fit',
+  LIMIT: 'limit',
+  MFIT: 'mfit',
+  PAD: 'pad',
+  LPAD: 'lpad',
+  MPAD: 'mpad',
+  SCALE: 'scale',
+  THUMB: 'thumb',
+  CROP: 'crop'
+});
+
+/**
+ * Cloudinary Quality modes (`q_` transformations).
+ * @enum {string}
+ */
+export const Quality = Object.freeze({
+  AUTO: 'auto',
+  AUTO_BEST: 'auto:best',
+  AUTO_GOOD: 'auto:good',
+  AUTO_ECO: 'auto:eco',
+  AUTO_LOW: 'auto:low'
+});
+
+/**
+ * Cloudinary Format modes (`f_` transformations).
+ * @enum {string}
+ */
+export const Format = Object.freeze({
+  AUTO: 'auto',
+  JPG: 'jpg',
+  PNG: 'png',
+  WEBP: 'webp',
+  GIF: 'gif',
+  AVIF: 'avif',
+  PDF: 'pdf'
+});
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudinary-lite",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Zero-dependency, lightweight helper for Cloudinary uploads (unsigned client-side) and secure deletes (signed server-side).",
   "type": "module",
   "main": "index.js",

package/readme.md

@@ -117,6 +117,76 @@ console.log(parsed);
 
 ---
 
+### 4. Dynamic URL Scaling & Transformations (Universal Helper)
+
+Generate resized, cropped, or transformed Cloudinary asset URLs on-the-fly.
+
+```javascript
+import { getTransformedUrl, Crop, Quality, Format } from 'cloudinary-lite';
+
+const originalUrl = 'https://res.cloudinary.com/de3t60fd7/image/upload/v1722513904/alumni/profile-photos/abc123xyz.jpg';
+
+// Option A: Pass options object using built-in enums (or plain strings)
+const resizedUrl = getTransformedUrl(originalUrl, {
+  width: 300,
+  height: 300,
+  crop: Crop.FILL,
+  quality: Quality.AUTO,
+  format: Format.AUTO
+});
+console.log(resizedUrl);
+// Output:
+// https://res.cloudinary.com/de3t60fd7/image/upload/w_300,h_300,c_fill,q_auto,f_auto/v1722513904/alumni/profile-photos/abc123xyz.jpg
+
+// Option B: Pass raw transformation string
+const rawTransformedUrl = getTransformedUrl(originalUrl, 'w_150,h_150,c_thumb,g_face');
+console.log(rawTransformedUrl);
+// Output:
+// https://res.cloudinary.com/de3t60fd7/image/upload/w_150,h_150,c_thumb,g_face/v1722513904/alumni/profile-photos/abc123xyz.jpg
+```
+
+---
+
+### 5. Configuration Enums (Helper Constants)
+
+The library exports frozen objects (`Crop`, `Quality`, `Format`) to provide autocomplete, prevent typos, and document standard Cloudinary transformation values.
+
+```javascript
+import { Crop, Quality, Format } from 'cloudinary-lite';
+```
+
+#### `Crop`
+*   `Crop.FILL`: `'fill'`
+*   `Crop.LFILL`: `'lfill'`
+*   `Crop.FILL_PAD`: `'fill_pad'`
+*   `Crop.FIT`: `'fit'`
+*   `Crop.LIMIT`: `'limit'`
+*   `Crop.MFIT`: `'mfit'`
+*   `Crop.PAD`: `'pad'`
+*   `Crop.LPAD`: `'lpad'`
+*   `Crop.MPAD`: `'mpad'`
+*   `Crop.SCALE`: `'scale'`
+*   `Crop.THUMB`: `'thumb'`
+*   `Crop.CROP`: `'crop'`
+
+#### `Quality`
+*   `Quality.AUTO`: `'auto'`
+*   `Quality.AUTO_BEST`: `'auto:best'`
+*   `Quality.AUTO_GOOD`: `'auto:good'`
+*   `Quality.AUTO_ECO`: `'auto:eco'`
+*   `Quality.AUTO_LOW`: `'auto:low'`
+
+#### `Format`
+*   `Format.AUTO`: `'auto'`
+*   `Format.JPG`: `'jpg'`
+*   `Format.PNG`: `'png'`
+*   `Format.WEBP`: `'webp'`
+*   `Format.GIF`: `'gif'`
+*   `Format.AVIF`: `'avif'`
+*   `Format.PDF`: `'pdf'`
+
+---
+
 ## License
 
 MIT