@muhgholy/next-drive 4.5.0 → 4.7.0

package/README.md

@@ -55,17 +55,6 @@ This package uses [subpath exports](https://nodejs.org/api/packages.html#subpath
 }
 ```
 
-**For projects using bundlers (Vite, Webpack, etc.):**
-
-```json
-{
-	"compilerOptions": {
-		"module": "esnext",
-		"moduleResolution": "bundler"
-	}
-}
-```
-
 > ⚠️ The legacy `"moduleResolution": "node"` is **not supported** and will cause build errors with subpath imports like `@muhgholy/next-drive/server`.
 
 **FFmpeg** (for video thumbnails):
@@ -280,18 +269,28 @@ Upload files programmatically from server-side code:
 ```typescript
 import { driveUpload } from "@muhgholy/next-drive/server";
 
-// Upload from file path
+// Upload to specific folder by ID
 const file = await driveUpload(
 	"/tmp/photo.jpg",
 	{ userId: "123" },
 	{
 		name: "photo.jpg",
-		parentId: "folderId", // Optional: folder ID or null for root
+		folder: { id: "folderId" }, // Optional: folder ID
 		accountId: "LOCAL", // Optional: storage account ID
 		enforce: false, // Optional: bypass quota check
 	}
 );
 
+// Upload to folder by path (creates folders if not exist)
+const file = await driveUpload(
+	"/tmp/photo.jpg",
+	{ userId: "123" },
+	{
+		name: "photo.jpg",
+		folder: { path: "images/2024/january" }, // Creates folders recursively
+	}
+);
+
 // Upload from stream
 import fs from "fs";
 const stream = fs.createReadStream("/tmp/video.mp4");
@@ -318,13 +317,14 @@ const file = await driveUpload(
 
 **Options:**
 
-| Option      | Type             | Required | Description                                              |
-| ----------- | ---------------- | -------- | -------------------------------------------------------- |
-| `name`      | `string`         | Yes      | File name with extension                                 |
-| `parentId`  | `string \| null` | No       | Parent folder ID (null or 'root' for root)               |
-| `accountId` | `string`         | No       | Storage account ID ('LOCAL' for local storage)           |
-| `mime`      | `string`         | No       | MIME type (auto-detected from extension if not provided) |
-| `enforce`   | `boolean`        | No       | Bypass quota check (default: false)                      |
+| Option       | Type                              | Required | Description                                              |
+| ------------ | --------------------------------- | -------- | -------------------------------------------------------- |
+| `name`       | `string`                          | Yes      | File name with extension                                 |
+| `folder.id`  | `string`                          | No       | Parent folder ID                                         |
+| `folder.path`| `string`                          | No       | Folder path (e.g., `images/2024`) - creates if not exist |
+| `accountId`  | `string`                          | No       | Storage account ID ('LOCAL' for local storage)           |
+| `mime`       | `string`                          | No       | MIME type (auto-detected from extension if not provided) |
+| `enforce`    | `boolean`                         | No       | Bypass quota check (default: false)                      |
 
 ### Get Signed URL
 
@@ -583,25 +583,122 @@ GOOGLE_REDIRECT_URI=http://localhost:3000/api/drive?action=callback
 
 ---
 
-## API Endpoints
-
-All operations use `?action=` query parameter:
-
-| Action            | Method | Description          |
-| ----------------- | ------ | -------------------- |
-| `upload`          | POST   | Chunked file upload  |
-| `list`            | GET    | List folder contents |
-| `serve`           | GET    | Serve file content   |
-| `thumbnail`       | GET    | Get file thumbnail   |
-| `rename`          | PATCH  | Rename file/folder   |
-| `trash`           | POST   | Move to trash        |
-| `deletePermanent` | DELETE | Delete permanently   |
-| `restore`         | POST   | Restore from trash   |
-| `emptyTrash`      | DELETE | Empty all trash      |
-| `createFolder`    | POST   | Create folder        |
-| `move`            | POST   | Move to new parent   |
-| `search`          | GET    | Search by name       |
-| `quota`           | GET    | Get storage usage    |
+## Image Optimization
+
+Serve optimized images with dynamic compression, resizing, and format conversion using query parameters.
+
+### URL Format
+
+```
+/api/drive?action=serve&id={fileId}&quality={preset}&display={context}&size={preset}&format={format}
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `quality` | `low` / `medium` / `high` / `1-100` | Compression level |
+| `display` | string | Context-based quality adjustment |
+| `size` | string | Predefined dimensions preset |
+| `format` | `jpeg` / `webp` / `avif` / `png` | Output format |
+
+### Quality Presets
+
+| Preset | Base Quality | Use Case |
+|--------|--------------|----------|
+| `low` | 30 | Thumbnails, previews |
+| `medium` | 50 | General content |
+| `high` | 75 | High-quality display |
+| `1-100` | Custom | Fine-tuned control |
+
+> Quality is dynamically adjusted based on file size. Larger files get more aggressive compression.
+
+### Display Presets (Quality Context)
+
+| Display | Quality Factor | Use Case |
+|---------|----------------|----------|
+| `article-header` | 0.9 | Hero/banner images |
+| `article-image` | 0.85 | In-content images |
+| `thumbnail` | 0.7 | Small previews |
+| `avatar` | 0.8 | Profile pictures |
+| `logo` | 0.95 | Branding/logos |
+| `card` | 0.8 | Card components |
+| `gallery` | 0.85 | Gallery/grid |
+| `og` | 0.9 | Open Graph/social |
+| `icon` | 0.75 | Small icons |
+| `cover` | 0.9 | Full-width covers |
+| `story` | 0.85 | Story/vertical |
+
+### Size Presets (Dimensions)
+
+**Square Sizes:**
+| Size | Dimensions |
+|------|------------|
+| `xs` | 64×64 |
+| `sm` | 128×128 |
+| `md` | 256×256 |
+| `lg` | 512×512 |
+| `xl` | 1024×1024 |
+| `2xl` | 1600×1600 |
+| `icon` | 48×48 |
+| `thumb` | 150×150 |
+| `square` | 600×600 |
+| `avatar-sm` | 64×64 |
+| `avatar-md` | 128×128 |
+| `avatar-lg` | 256×256 |
+
+**Landscape (16:9):**
+| Size | Dimensions |
+|------|------------|
+| `landscape-sm` | 480×270 |
+| `landscape` | 800×450 |
+| `landscape-lg` | 1280×720 |
+| `landscape-xl` | 1920×1080 |
+
+**Portrait (9:16):**
+| Size | Dimensions |
+|------|------------|
+| `portrait-sm` | 270×480 |
+| `portrait` | 450×800 |
+| `portrait-lg` | 720×1280 |
+
+**Wide/Banner:**
+| Size | Dimensions | Ratio |
+|------|------------|-------|
+| `wide` | 1200×630 | OG standard |
+| `banner` | 1200×400 | 3:1 |
+| `banner-sm` | 800×200 | 4:1 |
+
+**Other:**
+| Size | Dimensions | Ratio |
+|------|------------|-------|
+| `photo-4x3` | 800×600 | 4:3 |
+| `photo-3x2` | 900×600 | 3:2 |
+| `story` | 1080×1920 | 9:16 |
+| `video` | 1280×720 | 16:9 |
+| `video-sm` | 640×360 | 16:9 |
+| `card-sm` | 300×200 | 3:2 |
+| `card` | 400×300 | 4:3 |
+| `card-lg` | 600×400 | 3:2 |
+
+### Examples
+
+```html
+<!-- Article header with OG dimensions -->
+<img src="/api/drive?action=serve&id=123&display=article-header&size=wide&format=webp">
+
+<!-- Thumbnail with aggressive compression -->
+<img src="/api/drive?action=serve&id=123&display=thumbnail&size=thumb&format=webp">
+
+<!-- Avatar -->
+<img src="/api/drive?action=serve&id=123&display=avatar&size=avatar-md&format=webp">
+
+<!-- Gallery image -->
+<img src="/api/drive?action=serve&id=123&display=gallery&size=landscape&format=webp">
+
+<!-- Just quality, no resize -->
+<img src="/api/drive?action=serve&id=123&quality=medium&format=webp">
+```
 
 ---
 

package/dist/{chunk-YUU5BFE7.js → chunk-OWKTTRQC.js}

@@ -356,13 +356,120 @@ var extractImageMetadata = async (filePath) => {
     return null;
   }
 };
-var parseQuality = (q) => {
-  if (!q) return 80;
-  if (q === "low") return 40;
-  if (q === "medium") return 60;
-  if (q === "high") return 80;
-  const n = parseInt(q, 10);
-  return isNaN(n) ? 80 : Math.min(100, Math.max(1, n));
+var DISPLAY_PRESETS = {
+  "article-header": 0.9,
+  // Hero/banner images - high quality
+  "article-image": 0.85,
+  // In-content images
+  "thumbnail": 0.7,
+  // Small previews - lower quality ok
+  "avatar": 0.8,
+  // Profile pictures
+  "logo": 0.95,
+  // Branding - needs clarity
+  "card": 0.8,
+  // Card components
+  "gallery": 0.85,
+  // Gallery/grid images
+  "og": 0.9,
+  // Open Graph/social sharing
+  "icon": 0.75,
+  // Small icons
+  "cover": 0.9,
+  // Full-width covers
+  "story": 0.85
+  // Story/vertical format
+};
+var SIZE_PRESETS = {
+  // Square sizes
+  "xs": { width: 64, height: 64 },
+  "sm": { width: 128, height: 128 },
+  "md": { width: 256, height: 256 },
+  "lg": { width: 512, height: 512 },
+  "xl": { width: 1024, height: 1024 },
+  "2xl": { width: 1600, height: 1600 },
+  // Named squares
+  "icon": { width: 48, height: 48 },
+  "thumb": { width: 150, height: 150 },
+  "square": { width: 600, height: 600 },
+  "avatar-sm": { width: 64, height: 64 },
+  "avatar-md": { width: 128, height: 128 },
+  "avatar-lg": { width: 256, height: 256 },
+  // Landscape (16:9)
+  "landscape-sm": { width: 480, height: 270 },
+  "landscape": { width: 800, height: 450 },
+  "landscape-lg": { width: 1280, height: 720 },
+  "landscape-xl": { width: 1920, height: 1080 },
+  // Portrait (9:16)
+  "portrait-sm": { width: 270, height: 480 },
+  "portrait": { width: 450, height: 800 },
+  "portrait-lg": { width: 720, height: 1280 },
+  // Wide/Banner (OG, social)
+  "wide": { width: 1200, height: 630 },
+  // Open Graph standard
+  "banner": { width: 1200, height: 400 },
+  // Banner/header
+  "banner-sm": { width: 800, height: 200 },
+  // Classic photo ratios
+  "photo-4x3": { width: 800, height: 600 },
+  // 4:3
+  "photo-3x2": { width: 900, height: 600 },
+  // 3:2
+  // Story/vertical (9:16)
+  "story": { width: 1080, height: 1920 },
+  // Video thumbnails
+  "video": { width: 1280, height: 720 },
+  "video-sm": { width: 640, height: 360 },
+  // Card sizes
+  "card-sm": { width: 300, height: 200 },
+  "card": { width: 400, height: 300 },
+  "card-lg": { width: 600, height: 400 }
+};
+var getImageSettings = (fileSizeInBytes, qualityPreset, display, size) => {
+  let baseQuality = 80;
+  if (qualityPreset === "low") baseQuality = 30;
+  else if (qualityPreset === "medium") baseQuality = 50;
+  else if (qualityPreset === "high") baseQuality = 75;
+  else if (qualityPreset) {
+    const n = parseInt(qualityPreset, 10);
+    if (!isNaN(n)) baseQuality = Math.min(100, Math.max(1, n));
+  }
+  const displayFactor = display && DISPLAY_PRESETS[display] ? DISPLAY_PRESETS[display] : 1;
+  baseQuality = Math.round(baseQuality * displayFactor);
+  let quality = baseQuality;
+  let effort = 4;
+  let pngCompression = 6;
+  if (fileSizeInBytes) {
+    const sizeInKB = fileSizeInBytes / 1024;
+    if (sizeInKB > 500) {
+      quality = Math.min(baseQuality, 25);
+      effort = 9;
+      pngCompression = 9;
+    } else if (sizeInKB > 300) {
+      quality = Math.min(baseQuality, 30);
+      effort = 8;
+      pngCompression = 9;
+    } else if (sizeInKB > 150) {
+      quality = Math.min(baseQuality, 35);
+      effort = 7;
+      pngCompression = 8;
+    } else if (sizeInKB > 90) {
+      quality = Math.min(baseQuality, 40);
+      effort = 6;
+      pngCompression = 8;
+    } else if (sizeInKB > 50) {
+      quality = Math.min(baseQuality, 50);
+      effort = 5;
+      pngCompression = 7;
+    }
+  }
+  const dimensions = size && SIZE_PRESETS[size] ? SIZE_PRESETS[size] : void 0;
+  return {
+    quality: Math.max(1, Math.min(100, quality)),
+    effort,
+    pngCompression,
+    ...dimensions && { width: dimensions.width, height: dimensions.height }
+  };
 };
 var objectIdSchema = z.string().refine((val) => isValidObjectId(val), {
   message: "Invalid ObjectId format"
@@ -1310,6 +1417,46 @@ var driveDelete = async (source, options) => {
   const owner = drive.owner;
   await provider.delete([driveId], owner, accountId);
 };
+var resolveFolderByPath = async (folderPath, owner, accountId) => {
+  const normalizedPath = folderPath.replace(/^\/+|\/+$/g, "");
+  if (!normalizedPath) {
+    throw new Error("Folder path cannot be empty");
+  }
+  const segments = normalizedPath.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) {
+    throw new Error("Invalid folder path");
+  }
+  let providerName = "LOCAL";
+  if (accountId && accountId !== "LOCAL") {
+    const account = await drive_default.db.model("StorageAccount").findOne({ _id: accountId, owner });
+    if (!account) {
+      throw new Error("Invalid Storage Account");
+    }
+    if (account.metadata.provider === "GOOGLE") {
+      providerName = "GOOGLE";
+    }
+  }
+  let currentParentId = null;
+  for (const segmentName of segments) {
+    const existingFolder = await drive_default.findOne({
+      owner,
+      "provider.type": providerName,
+      storageAccountId: accountId || null,
+      parentId: currentParentId,
+      name: segmentName,
+      "information.type": "FOLDER",
+      trashedAt: null
+    });
+    if (existingFolder) {
+      currentParentId = String(existingFolder._id);
+    } else {
+      const provider = providerName === "GOOGLE" ? GoogleDriveProvider : LocalStorageProvider;
+      const newFolder = await provider.createFolder(segmentName, currentParentId, owner, accountId);
+      currentParentId = newFolder.id;
+    }
+  }
+  return currentParentId;
+};
 var driveUpload = async (source, key, options) => {
   const config = getDriveConfig();
   let provider = LocalStorageProvider;
@@ -1399,12 +1546,20 @@ var driveUpload = async (source, key, options) => {
         throw new Error("Storage quota exceeded");
       }
     }
+    let resolvedParentId = null;
+    if (options.folder?.path) {
+      resolvedParentId = await resolveFolderByPath(options.folder.path, key, accountId);
+    } else if (options.folder?.id && options.folder.id !== "root") {
+      resolvedParentId = options.folder.id;
+    } else if (options.parentId && options.parentId !== "root") {
+      resolvedParentId = options.parentId;
+    }
     const drive = new drive_default({
       owner: key,
       storageAccountId: accountId || null,
       provider: { type: provider.name },
       name: options.name,
-      parentId: options.parentId === "root" || !options.parentId ? null : options.parentId,
+      parentId: resolvedParentId,
       order: await getNextOrderValue(key),
       information: { type: "FILE", sizeInBytes: fileSize, mime: mimeType, path: "" },
       status: "UPLOADING"
@@ -1548,24 +1703,32 @@ var driveAPIHandler = async (req, res) => {
         return;
       }
       if (action === "serve") {
-        const { stream, mime, size } = await itemProvider.openStream(drive, itemAccountId);
+        const { stream, mime, size: fileSize } = await itemProvider.openStream(drive, itemAccountId);
         const safeFilename = sanitizeContentDispositionFilename(drive.name);
         const format = req.query.format;
         const quality = req.query.quality;
+        const display = req.query.display;
+        const sizePreset = req.query.size;
         const isImage = mime.startsWith("image/");
-        const shouldTransform = isImage && (format || quality);
+        const shouldTransform = isImage && (format || quality || display || sizePreset);
         res.setHeader("Content-Disposition", `inline; filename="${safeFilename}"`);
         if (config.cors?.enabled) {
           res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
         }
         if (shouldTransform) {
           try {
-            const qValue = parseQuality(quality);
+            const settings = getImageSettings(fileSize, quality, display, sizePreset);
             let targetFormat = format || mime.split("/")[1];
             if (targetFormat === "jpg") targetFormat = "jpeg";
             const cacheDir = path.join(config.storage.path, "file", drive._id.toString(), "cache");
-            const cacheFilename = `optimized_q${qValue}_${targetFormat}.bin`;
-            const cachePath = path.join(cacheDir, cacheFilename);
+            const cacheKey = [
+              "opt",
+              `q${settings.quality}`,
+              `e${settings.effort}`,
+              settings.width ? `${settings.width}x${settings.height}` : "orig",
+              targetFormat
+            ].join("_");
+            const cachePath = path.join(cacheDir, `${cacheKey}.bin`);
             if (fs.existsSync(cachePath)) {
               const cacheStat = fs.statSync(cachePath);
               res.setHeader("Content-Type", `image/${targetFormat}`);
@@ -1579,18 +1742,24 @@ var driveAPIHandler = async (req, res) => {
               return;
             }
             if (!fs.existsSync(cacheDir)) fs.mkdirSync(cacheDir, { recursive: true });
-            const pipeline = sharp();
+            let pipeline = sharp();
+            if (settings.width && settings.height) {
+              pipeline = pipeline.resize(settings.width, settings.height, {
+                fit: "inside",
+                withoutEnlargement: true
+              });
+            }
             if (targetFormat === "jpeg") {
-              pipeline.jpeg({ quality: qValue, mozjpeg: true });
+              pipeline = pipeline.jpeg({ quality: settings.quality, mozjpeg: true });
               res.setHeader("Content-Type", "image/jpeg");
             } else if (targetFormat === "png") {
-              pipeline.png({ quality: qValue });
+              pipeline = pipeline.png({ compressionLevel: settings.pngCompression, adaptiveFiltering: true });
               res.setHeader("Content-Type", "image/png");
             } else if (targetFormat === "webp") {
-              pipeline.webp({ quality: qValue });
+              pipeline = pipeline.webp({ quality: settings.quality, effort: settings.effort });
               res.setHeader("Content-Type", "image/webp");
             } else if (targetFormat === "avif") {
-              pipeline.avif({ quality: qValue });
+              pipeline = pipeline.avif({ quality: settings.quality, effort: settings.effort });
               res.setHeader("Content-Type", "image/avif");
             }
             res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
@@ -1603,7 +1772,7 @@ var driveAPIHandler = async (req, res) => {
           }
         }
         res.setHeader("Content-Type", mime);
-        if (size) res.setHeader("Content-Length", size);
+        if (fileSize) res.setHeader("Content-Length", fileSize);
         stream.pipe(res);
         return;
       }
@@ -2137,5 +2306,5 @@ var driveAPIHandler = async (req, res) => {
 };
 
 export { driveAPIHandler, driveConfiguration, driveDelete, driveFilePath, driveFileSchemaZod, driveGetUrl, driveInfo, driveList, driveReadFile, driveUpload, getDriveConfig, getDriveInformation };
-//# sourceMappingURL=chunk-YUU5BFE7.js.map
-//# sourceMappingURL=chunk-YUU5BFE7.js.map
+//# sourceMappingURL=chunk-OWKTTRQC.js.map
+//# sourceMappingURL=chunk-OWKTTRQC.js.map