whale-code 6.5.5 → 6.5.7

package/dist/server/handlers/media.js

@@ -10,893 +10,1215 @@
 //
 // Note: file_path is handled client-side in server-tools.ts (converted to base64
 // before reaching this handler).
+
 import { sanitizeFilterValue } from "../lib/utils.js";
 const BUCKET = "product-images";
-const ALL_ACTIONS = [
-    "upload", "bulk_upload", "list", "get", "update", "bulk_update",
-    "delete", "bulk_delete", "search", "move", "archive", "unarchive",
-    "tag", "folders_list", "folders_create", "folders_update", "folders_delete",
-    "link_product", "unlink_product", "usage", "analytics", "duplicate", "replace",
-];
+const ALL_ACTIONS = ["upload", "bulk_upload", "list", "get", "update", "bulk_update", "delete", "bulk_delete", "search", "move", "archive", "unarchive", "tag", "folders_list", "folders_create", "folders_update", "folders_delete", "link_product", "unlink_product", "usage", "analytics", "duplicate", "replace"];
 const LIST_COLUMNS = "id, file_name, file_url, file_size, file_type, category, folder, status, title, alt_text, custom_tags, usage_count, linked_product_ids, created_at, updated_at";
 const VALID_CATEGORIES = ["product_photos", "marketing", "menus", "brand", "social_media", "print_marketing", "promotional", "brand_assets", "ai_generated"];
 const VALID_STATUSES = ["active", "archived", "processing"];
 const VALID_SORT_COLUMNS = ["created_at", "updated_at", "file_name", "file_size", "usage_count", "title"];
 const UPDATE_WHITELIST = ["title", "alt_text", "notes", "category", "status", "folder", "custom_tags"];
+
 // Detect mime type from base64 magic bytes
 function detectMime(base64) {
-    if (base64.startsWith("iVBORw0KGgo"))
-        return "image/png";
-    if (base64.startsWith("/9j/"))
-        return "image/jpeg";
-    if (base64.startsWith("R0lGOD"))
-        return "image/gif";
-    if (base64.startsWith("UklGR"))
-        return "image/webp";
-    if (base64.startsWith("JVBER"))
-        return "application/pdf";
-    // Blender files start with "BLENDER" → base64 of "BLENDER" starts with "QkxFTkRFUg"
-    if (base64.startsWith("QkxFTkRFUg"))
-        return "application/x-blender";
-    return "application/octet-stream";
+  if (base64.startsWith("iVBORw0KGgo")) return "image/png";
+  if (base64.startsWith("/9j/")) return "image/jpeg";
+  if (base64.startsWith("R0lGOD")) return "image/gif";
+  if (base64.startsWith("UklGR")) return "image/webp";
+  if (base64.startsWith("JVBER")) return "application/pdf";
+  // Blender files start with "BLENDER" → base64 of "BLENDER" starts with "QkxFTkRFUg"
+  if (base64.startsWith("QkxFTkRFUg")) return "application/x-blender";
+  return "application/octet-stream";
 }
 function mimeToExt(mime) {
-    const map = {
-        "image/png": "png", "image/jpeg": "jpg", "image/gif": "gif",
-        "image/webp": "webp", "image/svg+xml": "svg", "application/pdf": "pdf",
-        "application/x-blender": "blend",
-    };
-    return map[mime] || "bin";
+  const map = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/svg+xml": "svg",
+    "application/pdf": "pdf",
+    "application/x-blender": "blend"
+  };
+  return map[mime] || "bin";
 }
 export async function handleMedia(sb, args, storeId) {
-    const action = args.action || "upload";
-    if (!storeId)
-        return { success: false, error: "store_id is required" };
-    switch (action) {
-        // ── UPLOAD ─────────────────────────────────────────────────────────────────
-        case "upload": {
-            let base64 = args.base64;
-            const fileUrl = args.file_url;
-            if (!base64 && !fileUrl) {
-                return { success: false, error: "Provide base64 (file contents), file_url (public URL), or file_path (local — handled by CLI)" };
-            }
-            if (base64)
-                base64 = base64.replace(/^data:[^;]+;base64,/, "").replace(/\s/g, "");
-            if (!base64 && fileUrl) {
-                if (fileUrl.startsWith("/") || /^[A-Z]:\\/i.test(fileUrl)) {
-                    return {
-                        success: false,
-                        error: `Local file paths cannot be used as file_url. Use file_path instead: media(action="upload", file_path="${fileUrl}"). The CLI reads the file locally and uploads it.`,
-                    };
-                }
-                let fetchUrl = fileUrl;
-                if (!fetchUrl.startsWith("http://") && !fetchUrl.startsWith("https://")) {
-                    fetchUrl = `https://${fetchUrl}`;
-                }
-                const resp = await fetch(fetchUrl);
-                if (!resp.ok)
-                    return { success: false, error: `Failed to fetch file_url: ${resp.status}` };
-                const buf = await resp.arrayBuffer();
-                base64 = Buffer.from(buf).toString("base64");
-            }
-            const mime = args.mime_type || detectMime(base64);
-            const ext = mimeToExt(mime);
-            const originalName = args.file_name || "";
-            const folder = args.folder || "uploads";
-            const id = crypto.randomUUID();
-            const fileName = originalName
-                ? `${id}-${originalName.replace(/[^a-zA-Z0-9._-]/g, "_")}`
-                : `${id}.${ext}`;
-            const storagePath = `${folder}/${storeId.toUpperCase()}/${fileName}`;
-            const buffer = Buffer.from(base64, "base64");
-            const { error: uploadErr } = await sb.storage
-                .from(BUCKET)
-                .upload(storagePath, buffer, { contentType: mime, upsert: true });
-            if (uploadErr)
-                return { success: false, error: `Upload failed: ${uploadErr.message}` };
-            const { data: urlData } = sb.storage.from(BUCKET).getPublicUrl(storagePath);
-            const cdnUrl = urlData.publicUrl;
-            const insertData = {
-                store_id: storeId,
-                file_name: fileName,
-                file_path: storagePath,
-                file_url: cdnUrl,
-                file_size: buffer.length,
-                file_type: mime,
-                category: args.category || "product_photos",
-                source: "media-upload",
-                folder,
-            };
-            if (args.title)
-                insertData.title = args.title;
-            if (args.alt_text)
-                insertData.alt_text = args.alt_text;
-            if (args.notes)
-                insertData.notes = args.notes;
-            if (args.tags)
-                insertData.custom_tags = args.tags;
-            const { data: mediaRow, error: mediaErr } = await sb
-                .from("store_media")
-                .insert(insertData)
-                .select("id")
-                .single();
-            if (mediaErr)
-                console.error("[media] store_media insert error:", mediaErr.message);
+  const action = args.action || "upload";
+  if (!storeId) return {
+    success: false,
+    error: "store_id is required"
+  };
+  switch (action) {
+    // ── UPLOAD ─────────────────────────────────────────────────────────────────
+    case "upload":
+      {
+        let base64 = args.base64;
+        const fileUrl = args.file_url;
+        if (!base64 && !fileUrl) {
+          return {
+            success: false,
+            error: "Provide base64 (file contents), file_url (public URL), or file_path (local — handled by CLI)"
+          };
+        }
+        if (base64) base64 = base64.replace(/^data:[^;]+;base64,/, "").replace(/\s/g, "");
+        if (!base64 && fileUrl) {
+          if (fileUrl.startsWith("/") || /^[A-Z]:\\/i.test(fileUrl)) {
             return {
-                success: true,
-                data: {
-                    media_id: mediaRow?.id || id,
-                    file_url: cdnUrl,
-                    file_name: fileName,
-                    file_size: buffer.length,
-                    mime_type: mime,
-                    storage_path: storagePath,
-                },
+              success: false,
+              error: `Local file paths cannot be used as file_url. Use file_path instead: media(action="upload", file_path="${fileUrl}"). The CLI reads the file locally and uploads it.`
             };
+          }
+          let fetchUrl = fileUrl;
+          if (!fetchUrl.startsWith("http://") && !fetchUrl.startsWith("https://")) {
+            fetchUrl = `https://${fetchUrl}`;
+          }
+          const resp = await fetch(fetchUrl);
+          if (!resp.ok) return {
+            success: false,
+            error: `Failed to fetch file_url: ${resp.status}`
+          };
+          const buf = await resp.arrayBuffer();
+          base64 = Buffer.from(buf).toString("base64");
         }
-        // ── BULK UPLOAD ────────────────────────────────────────────────────────────
-        case "bulk_upload": {
-            const files = args.files;
-            if (!files || !Array.isArray(files) || files.length === 0) {
-                return { success: false, error: "bulk_upload requires files: [{base64, file_name}]" };
-            }
-            const folder = args.folder || "uploads";
-            const category = args.category || "product_photos";
-            const readErrors = args._read_errors || [];
-            const results = await Promise.allSettled(files.map(async (file) => {
-                const b64 = file.base64.replace(/^data:[^;]+;base64,/, "").replace(/\s/g, "");
-                const mime = args.mime_type || detectMime(b64);
-                const ext = mimeToExt(mime);
-                const fid = crypto.randomUUID();
-                const originalName = file.file_name || "";
-                const fName = originalName
-                    ? `${fid}-${originalName.replace(/[^a-zA-Z0-9._-]/g, "_")}`
-                    : `${fid}.${ext}`;
-                const storagePath = `${folder}/${storeId.toUpperCase()}/${fName}`;
-                const buffer = Buffer.from(b64, "base64");
-                const { error: uploadErr } = await sb.storage
-                    .from(BUCKET)
-                    .upload(storagePath, buffer, { contentType: mime, upsert: true });
-                if (uploadErr)
-                    throw new Error(`Storage: ${uploadErr.message}`);
-                const { data: urlData } = sb.storage.from(BUCKET).getPublicUrl(storagePath);
-                const cdnUrl = urlData.publicUrl;
-                const insertData = {
-                    store_id: storeId, file_name: fName, file_path: storagePath,
-                    file_url: cdnUrl, file_size: buffer.length, file_type: mime,
-                    category, source: "media-upload", folder,
-                };
-                if (args.title)
-                    insertData.title = args.title;
-                if (args.alt_text)
-                    insertData.alt_text = args.alt_text;
-                if (args.notes)
-                    insertData.notes = args.notes;
-                if (args.tags)
-                    insertData.custom_tags = args.tags;
-                const { data: mediaRow, error: mediaErr } = await sb
-                    .from("store_media")
-                    .insert(insertData)
-                    .select("id")
-                    .single();
-                if (mediaErr)
-                    console.error("[media] bulk insert error:", mediaErr.message);
-                return {
-                    media_id: mediaRow?.id || fid, file_url: cdnUrl, file_name: fName,
-                    file_size: buffer.length, mime_type: mime, storage_path: storagePath,
-                };
-            }));
-            const uploaded = [];
-            const failed = [];
-            results.forEach((r, i) => {
-                if (r.status === "fulfilled") {
-                    uploaded.push(r.value);
-                }
-                else {
-                    failed.push({ file_name: files[i].file_name || `file_${i}`, error: r.reason?.message || String(r.reason) });
-                }
+        const mime = args.mime_type || detectMime(base64);
+        const ext = mimeToExt(mime);
+        const originalName = args.file_name || "";
+        const folder = args.folder || "uploads";
+        const id = crypto.randomUUID();
+        const fileName = originalName ? `${id}-${originalName.replace(/[^a-zA-Z0-9._-]/g, "_")}` : `${id}.${ext}`;
+        const storagePath = `${folder}/${storeId.toUpperCase()}/${fileName}`;
+        const buffer = Buffer.from(base64, "base64");
+        const {
+          error: uploadErr
+        } = await sb.storage.from(BUCKET).upload(storagePath, buffer, {
+          contentType: mime,
+          upsert: true
+        });
+        if (uploadErr) return {
+          success: false,
+          error: `Upload failed: ${uploadErr.message}`
+        };
+        const {
+          data: urlData
+        } = sb.storage.from(BUCKET).getPublicUrl(storagePath);
+        const cdnUrl = urlData.publicUrl;
+        const insertData = {
+          store_id: storeId,
+          file_name: fileName,
+          file_path: storagePath,
+          file_url: cdnUrl,
+          file_size: buffer.length,
+          file_type: mime,
+          category: args.category || "product_photos",
+          source: "media-upload",
+          folder
+        };
+        if (args.title) insertData.title = args.title;
+        if (args.alt_text) insertData.alt_text = args.alt_text;
+        if (args.notes) insertData.notes = args.notes;
+        if (args.tags) insertData.custom_tags = args.tags;
+        const {
+          data: mediaRow,
+          error: mediaErr
+        } = await sb.from("store_media").insert(insertData).select("id").single();
+        if (mediaErr) console.error("[media] store_media insert error:", mediaErr.message);
+        return {
+          success: true,
+          data: {
+            media_id: mediaRow?.id || id,
+            file_url: cdnUrl,
+            file_name: fileName,
+            file_size: buffer.length,
+            mime_type: mime,
+            storage_path: storagePath
+          }
+        };
+      }
+
+    // ── BULK UPLOAD ────────────────────────────────────────────────────────────
+    case "bulk_upload":
+      {
+        const files = args.files;
+        if (!files || !Array.isArray(files) || files.length === 0) {
+          return {
+            success: false,
+            error: "bulk_upload requires files: [{base64, file_name}]"
+          };
+        }
+        const folder = args.folder || "uploads";
+        const category = args.category || "product_photos";
+        const readErrors = args._read_errors || [];
+        const results = await Promise.allSettled(files.map(async file => {
+          const b64 = file.base64.replace(/^data:[^;]+;base64,/, "").replace(/\s/g, "");
+          const mime = args.mime_type || detectMime(b64);
+          const ext = mimeToExt(mime);
+          const fid = crypto.randomUUID();
+          const originalName = file.file_name || "";
+          const fName = originalName ? `${fid}-${originalName.replace(/[^a-zA-Z0-9._-]/g, "_")}` : `${fid}.${ext}`;
+          const storagePath = `${folder}/${storeId.toUpperCase()}/${fName}`;
+          const buffer = Buffer.from(b64, "base64");
+          const {
+            error: uploadErr
+          } = await sb.storage.from(BUCKET).upload(storagePath, buffer, {
+            contentType: mime,
+            upsert: true
+          });
+          if (uploadErr) throw new Error(`Storage: ${uploadErr.message}`);
+          const {
+            data: urlData
+          } = sb.storage.from(BUCKET).getPublicUrl(storagePath);
+          const cdnUrl = urlData.publicUrl;
+          const insertData = {
+            store_id: storeId,
+            file_name: fName,
+            file_path: storagePath,
+            file_url: cdnUrl,
+            file_size: buffer.length,
+            file_type: mime,
+            category,
+            source: "media-upload",
+            folder
+          };
+          if (args.title) insertData.title = args.title;
+          if (args.alt_text) insertData.alt_text = args.alt_text;
+          if (args.notes) insertData.notes = args.notes;
+          if (args.tags) insertData.custom_tags = args.tags;
+          const {
+            data: mediaRow,
+            error: mediaErr
+          } = await sb.from("store_media").insert(insertData).select("id").single();
+          if (mediaErr) console.error("[media] bulk insert error:", mediaErr.message);
+          return {
+            media_id: mediaRow?.id || fid,
+            file_url: cdnUrl,
+            file_name: fName,
+            file_size: buffer.length,
+            mime_type: mime,
+            storage_path: storagePath
+          };
+        }));
+        const uploaded = [];
+        const failed = [];
+        results.forEach((r, i) => {
+          if (r.status === "fulfilled") {
+            uploaded.push(r.value);
+          } else {
+            failed.push({
+              file_name: files[i].file_name || `file_${i}`,
+              error: r.reason?.message || String(r.reason)
             });
-            for (const e of readErrors)
-                failed.push({ file_name: "(read error)", error: e });
-            return {
-                success: uploaded.length > 0,
-                data: {
-                    uploaded_count: uploaded.length,
-                    failed_count: failed.length,
-                    total_size: uploaded.reduce((sum, u) => sum + u.file_size, 0),
-                    files: uploaded,
-                    ...(failed.length > 0 ? { errors: failed } : {}),
-                },
-            };
+          }
+        });
+        for (const e of readErrors) failed.push({
+          file_name: "(read error)",
+          error: e
+        });
+        return {
+          success: uploaded.length > 0,
+          data: {
+            uploaded_count: uploaded.length,
+            failed_count: failed.length,
+            total_size: uploaded.reduce((sum, u) => sum + u.file_size, 0),
+            files: uploaded,
+            ...(failed.length > 0 ? {
+              errors: failed
+            } : {})
+          }
+        };
+      }
+
+    // ── LIST ───────────────────────────────────────────────────────────────────
+    case "list":
+      {
+        const limit = Math.min(Number(args.limit) || 50, 200);
+        const offset = Number(args.offset) || 0;
+        const sortBy = VALID_SORT_COLUMNS.includes(args.sort_by) ? args.sort_by : "created_at";
+        const sortOrder = args.sort_order === "asc";
+        let query = sb.from("store_media").select(LIST_COLUMNS, {
+          count: "exact"
+        }).eq("store_id", storeId).order(sortBy, {
+          ascending: sortOrder
+        }).range(offset, offset + limit - 1);
+
+        // Default: exclude archived unless explicitly requested
+        if (args.status) {
+          query = query.eq("status", args.status);
+        } else if (!args.include_archived) {
+          query = query.neq("status", "archived");
         }
-        // ── LIST ───────────────────────────────────────────────────────────────────
-        case "list": {
-            const limit = Math.min(Number(args.limit) || 50, 200);
-            const offset = Number(args.offset) || 0;
-            const sortBy = VALID_SORT_COLUMNS.includes(args.sort_by) ? args.sort_by : "created_at";
-            const sortOrder = args.sort_order === "asc";
-            let query = sb.from("store_media")
-                .select(LIST_COLUMNS, { count: "exact" })
-                .eq("store_id", storeId)
-                .order(sortBy, { ascending: sortOrder })
-                .range(offset, offset + limit - 1);
-            // Default: exclude archived unless explicitly requested
-            if (args.status) {
-                query = query.eq("status", args.status);
-            }
-            else if (!args.include_archived) {
-                query = query.neq("status", "archived");
-            }
-            if (args.folder)
-                query = query.eq("folder", args.folder);
-            if (args.category)
-                query = query.eq("category", args.category);
-            if (args.file_type) {
-                const ft = sanitizeFilterValue(args.file_type);
-                query = query.ilike("file_type", `${ft}%`);
-            }
-            if (args.tags && Array.isArray(args.tags)) {
-                query = query.overlaps("custom_tags", args.tags);
-            }
-            const { data, error, count } = await query;
-            if (error)
-                return { success: false, error: error.message };
-            return {
-                success: true,
-                data: { total: count || 0, count: data?.length || 0, offset, files: data },
-            };
+        if (args.folder) query = query.eq("folder", args.folder);
+        if (args.category) query = query.eq("category", args.category);
+        if (args.file_type) {
+          const ft = sanitizeFilterValue(args.file_type);
+          query = query.ilike("file_type", `${ft}%`);
         }
-        // ── GET ────────────────────────────────────────────────────────────────────
-        case "get": {
-            const mediaId = args.media_id;
-            if (!mediaId)
-                return { success: false, error: "media_id required" };
-            const { data, error } = await sb.from("store_media").select("*").eq("id", mediaId).eq("store_id", storeId).single();
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data };
-        }
-        // ── UPDATE ─────────────────────────────────────────────────────────────────
-        case "update": {
-            const mediaId = args.media_id;
-            if (!mediaId)
-                return { success: false, error: "media_id required" };
-            const updates = {};
-            for (const key of UPDATE_WHITELIST) {
-                if (args[key] !== undefined)
-                    updates[key] = args[key];
-            }
-            // Accept description as alias for notes
-            if (args.description !== undefined && updates.notes === undefined) {
-                updates.notes = args.description;
-            }
-            // Accept tags as alias for custom_tags
-            if (args.tags !== undefined && updates.custom_tags === undefined) {
-                updates.custom_tags = args.tags;
-            }
-            if (Object.keys(updates).length === 0) {
-                return { success: false, error: `Nothing to update. Updatable fields: ${UPDATE_WHITELIST.join(", ")}` };
-            }
-            // Validate enums
-            if (updates.category && !VALID_CATEGORIES.includes(updates.category)) {
-                return { success: false, error: `Invalid category. Valid: ${VALID_CATEGORIES.join(", ")}` };
-            }
-            if (updates.status && !VALID_STATUSES.includes(updates.status)) {
-                return { success: false, error: `Invalid status. Valid: ${VALID_STATUSES.join(", ")}` };
-            }
-            const { data, error } = await sb.from("store_media")
-                .update(updates)
-                .eq("id", mediaId)
-                .eq("store_id", storeId)
-                .select("*")
-                .single();
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data };
-        }
-        // ── BULK UPDATE ────────────────────────────────────────────────────────────
-        // Two modes:
-        //   1. Uniform:  media_ids[] + shared fields → applies same update to all
-        //   2. Per-item: items[] → each item has {id, title?, alt_text?, tags?, ...}
-        case "bulk_update": {
-            const items = args.items;
-            // ── Per-item mode ──
-            if (items && Array.isArray(items) && items.length > 0) {
-                if (items.length > 500) {
-                    return { success: false, error: `Too many items (${items.length}). Max 500 per call.` };
-                }
-                // Validate all items up-front
-                for (let i = 0; i < items.length; i++) {
-                    const item = items[i];
-                    if (!item.id && !item.media_id) {
-                        return { success: false, error: `items[${i}] missing id` };
-                    }
-                    if (item.category && !VALID_CATEGORIES.includes(item.category)) {
-                        return { success: false, error: `items[${i}] invalid category: ${item.category}` };
-                    }
-                    if (item.status && !VALID_STATUSES.includes(item.status)) {
-                        return { success: false, error: `items[${i}] invalid status: ${item.status}` };
-                    }
-                }
-                // Process in parallel batches of 25
-                const BATCH_SIZE = 25;
-                let updatedCount = 0;
-                let failedCount = 0;
-                const errors = [];
-                for (let i = 0; i < items.length; i += BATCH_SIZE) {
-                    const batch = items.slice(i, i + BATCH_SIZE);
-                    const results = await Promise.allSettled(batch.map(async (item) => {
-                        const itemId = (item.id || item.media_id);
-                        const updates = {};
-                        for (const key of UPDATE_WHITELIST) {
-                            if (item[key] !== undefined)
-                                updates[key] = item[key];
-                        }
-                        if (item.description !== undefined && updates.notes === undefined) {
-                            updates.notes = item.description;
-                        }
-                        if (item.tags !== undefined && updates.custom_tags === undefined) {
-                            updates.custom_tags = item.tags;
-                        }
-                        if (Object.keys(updates).length === 0)
-                            return null; // skip no-ops
-                        const { error } = await sb.from("store_media")
-                            .update(updates)
-                            .eq("id", itemId)
-                            .eq("store_id", storeId);
-                        if (error)
-                            throw new Error(`${itemId}: ${error.message}`);
-                        return itemId;
-                    }));
-                    for (const r of results) {
-                        if (r.status === "fulfilled" && r.value !== null)
-                            updatedCount++;
-                        else if (r.status === "rejected") {
-                            failedCount++;
-                            errors.push(r.reason?.message || String(r.reason));
-                        }
-                    }
-                }
-                return {
-                    success: updatedCount > 0,
-                    data: {
-                        updated_count: updatedCount,
-                        failed_count: failedCount,
-                        ...(errors.length > 0 ? { errors: errors.slice(0, 10) } : {}),
-                    },
-                };
-            }
-            // ── Uniform mode ──
-            const ids = args.media_ids;
-            if (!ids || !Array.isArray(ids) || ids.length === 0) {
-                return { success: false, error: "Provide items[] (per-item updates) or media_ids[] + shared fields (uniform update)" };
-            }
-            const updates = {};
-            for (const key of UPDATE_WHITELIST) {
-                if (args[key] !== undefined)
-                    updates[key] = args[key];
-            }
-            if (args.description !== undefined && updates.notes === undefined) {
-                updates.notes = args.description;
-            }
-            if (args.tags !== undefined && updates.custom_tags === undefined) {
-                updates.custom_tags = args.tags;
-            }
-            if (Object.keys(updates).length === 0) {
-                return { success: false, error: `Nothing to update. Updatable fields: ${UPDATE_WHITELIST.join(", ")}` };
-            }
-            if (updates.category && !VALID_CATEGORIES.includes(updates.category)) {
-                return { success: false, error: `Invalid category. Valid: ${VALID_CATEGORIES.join(", ")}` };
-            }
-            if (updates.status && !VALID_STATUSES.includes(updates.status)) {
-                return { success: false, error: `Invalid status. Valid: ${VALID_STATUSES.join(", ")}` };
-            }
-            const { data, error } = await sb.from("store_media")
-                .update(updates)
-                .in("id", ids)
-                .eq("store_id", storeId)
-                .select("id");
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { updated_count: data?.length || 0 } };
-        }
-        // ── DELETE ─────────────────────────────────────────────────────────────────
-        case "delete": {
-            const mediaId = args.media_id;
-            if (!mediaId)
-                return { success: false, error: "media_id required" };
-            const { data: row } = await sb.from("store_media").select("file_path").eq("id", mediaId).eq("store_id", storeId).single();
-            if (row?.file_path) {
-                await sb.storage.from(BUCKET).remove([row.file_path]);
-            }
-            const { error } = await sb.from("store_media").delete().eq("id", mediaId).eq("store_id", storeId);
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { deleted: mediaId } };
-        }
-        // ── BULK DELETE ────────────────────────────────────────────────────────────
-        case "bulk_delete": {
-            const ids = args.media_ids;
-            if (!ids || !Array.isArray(ids) || ids.length === 0) {
-                return { success: false, error: "media_ids[] required" };
-            }
-            // Fetch file paths for storage cleanup
-            const { data: rows } = await sb.from("store_media")
-                .select("id, file_path")
-                .in("id", ids)
-                .eq("store_id", storeId);
-            const filePaths = (rows || []).map(r => r.file_path).filter(Boolean);
-            if (filePaths.length > 0) {
-                await sb.storage.from(BUCKET).remove(filePaths);
-            }
-            const { error } = await sb.from("store_media").delete().in("id", ids).eq("store_id", storeId);
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { deleted_count: rows?.length || 0 } };
-        }
-        // ── SEARCH ─────────────────────────────────────────────────────────────────
-        case "search": {
-            const query = args.query;
-            if (!query)
-                return { success: false, error: "query required for search" };
-            const sq = sanitizeFilterValue(query);
-            const limit = Math.min(Number(args.limit) || 50, 200);
-            const offset = Number(args.offset) || 0;
-            const sortBy = VALID_SORT_COLUMNS.includes(args.sort_by) ? args.sort_by : "created_at";
-            const sortOrder = args.sort_order === "asc";
-            let q = sb.from("store_media")
-                .select(LIST_COLUMNS, { count: "exact" })
-                .eq("store_id", storeId)
-                .or(`file_name.ilike.%${sq}%,title.ilike.%${sq}%,alt_text.ilike.%${sq}%,notes.ilike.%${sq}%`)
-                .order(sortBy, { ascending: sortOrder })
-                .range(offset, offset + limit - 1);
-            // Filters
-            if (args.status) {
-                q = q.eq("status", args.status);
-            }
-            else if (!args.include_archived) {
-                q = q.neq("status", "archived");
-            }
-            if (args.folder)
-                q = q.eq("folder", args.folder);
-            if (args.category)
-                q = q.eq("category", args.category);
-            if (args.file_type) {
-                const ft = sanitizeFilterValue(args.file_type);
-                q = q.ilike("file_type", `${ft}%`);
-            }
-            if (args.tags && Array.isArray(args.tags)) {
-                q = q.overlaps("custom_tags", args.tags);
-            }
-            if (args.date_from)
-                q = q.gte("created_at", args.date_from);
-            if (args.date_to)
-                q = q.lte("created_at", args.date_to);
-            if (args.min_usage !== undefined)
-                q = q.gte("usage_count", Number(args.min_usage));
-            if (args.max_usage !== undefined)
-                q = q.lte("usage_count", Number(args.max_usage));
-            const { data, error, count } = await q;
-            if (error)
-                return { success: false, error: error.message };
+        if (args.tags && Array.isArray(args.tags)) {
+          query = query.overlaps("custom_tags", args.tags);
+        }
+        const {
+          data,
+          error,
+          count
+        } = await query;
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            total: count || 0,
+            count: data?.length || 0,
+            offset,
+            files: data
+          }
+        };
+      }
+
+    // ── GET ────────────────────────────────────────────────────────────────────
+    case "get":
+      {
+        const mediaId = args.media_id;
+        if (!mediaId) return {
+          success: false,
+          error: "media_id required"
+        };
+        const {
+          data,
+          error
+        } = await sb.from("store_media").select("*").eq("id", mediaId).eq("store_id", storeId).single();
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data
+        };
+      }
+
+    // ── UPDATE ─────────────────────────────────────────────────────────────────
+    case "update":
+      {
+        const mediaId = args.media_id;
+        if (!mediaId) return {
+          success: false,
+          error: "media_id required"
+        };
+        const updates = {};
+        for (const key of UPDATE_WHITELIST) {
+          if (args[key] !== undefined) updates[key] = args[key];
+        }
+        // Accept description as alias for notes
+        if (args.description !== undefined && updates.notes === undefined) {
+          updates.notes = args.description;
+        }
+        // Accept tags as alias for custom_tags
+        if (args.tags !== undefined && updates.custom_tags === undefined) {
+          updates.custom_tags = args.tags;
+        }
+        if (Object.keys(updates).length === 0) {
+          return {
+            success: false,
+            error: `Nothing to update. Updatable fields: ${UPDATE_WHITELIST.join(", ")}`
+          };
+        }
+
+        // Validate enums
+        if (updates.category && !VALID_CATEGORIES.includes(updates.category)) {
+          return {
+            success: false,
+            error: `Invalid category. Valid: ${VALID_CATEGORIES.join(", ")}`
+          };
+        }
+        if (updates.status && !VALID_STATUSES.includes(updates.status)) {
+          return {
+            success: false,
+            error: `Invalid status. Valid: ${VALID_STATUSES.join(", ")}`
+          };
+        }
+        const {
+          data,
+          error
+        } = await sb.from("store_media").update(updates).eq("id", mediaId).eq("store_id", storeId).select("*").single();
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data
+        };
+      }
+
+    // ── BULK UPDATE ────────────────────────────────────────────────────────────
+    // Two modes:
+    //   1. Uniform:  media_ids[] + shared fields → applies same update to all
+    //   2. Per-item: items[] → each item has {id, title?, alt_text?, tags?, ...}
+    case "bulk_update":
+      {
+        const items = args.items;
+
+        // ── Per-item mode ──
+        if (items && Array.isArray(items) && items.length > 0) {
+          if (items.length > 500) {
             return {
-                success: true,
-                data: { total: count || 0, count: data?.length || 0, offset, query, files: data },
+              success: false,
+              error: `Too many items (${items.length}). Max 500 per call.`
             };
-        }
-        // ── MOVE ───────────────────────────────────────────────────────────────────
-        case "move": {
-            const folder = args.folder;
-            if (!folder)
-                return { success: false, error: "folder required" };
-            const ids = args.media_ids || (args.media_id ? [args.media_id] : []);
-            if (ids.length === 0)
-                return { success: false, error: "media_id or media_ids[] required" };
-            const { data, error } = await sb.from("store_media")
-                .update({ folder })
-                .in("id", ids)
-                .eq("store_id", storeId)
-                .select("id");
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { moved_count: data?.length || 0, folder } };
-        }
-        // ── ARCHIVE ────────────────────────────────────────────────────────────────
-        case "archive": {
-            const ids = args.media_ids || (args.media_id ? [args.media_id] : []);
-            if (ids.length === 0)
-                return { success: false, error: "media_id or media_ids[] required" };
-            const { data, error } = await sb.from("store_media")
-                .update({ status: "archived" })
-                .in("id", ids)
-                .eq("store_id", storeId)
-                .select("id");
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { archived_count: data?.length || 0 } };
-        }
-        // ── UNARCHIVE ──────────────────────────────────────────────────────────────
-        case "unarchive": {
-            const ids = args.media_ids || (args.media_id ? [args.media_id] : []);
-            if (ids.length === 0)
-                return { success: false, error: "media_id or media_ids[] required" };
-            const { data, error } = await sb.from("store_media")
-                .update({ status: "active" })
-                .in("id", ids)
-                .eq("store_id", storeId)
-                .select("id");
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { unarchived_count: data?.length || 0 } };
-        }
-        // ── TAG ────────────────────────────────────────────────────────────────────
-        case "tag": {
-            const ids = args.media_ids || (args.media_id ? [args.media_id] : []);
-            if (ids.length === 0)
-                return { success: false, error: "media_id or media_ids[] required" };
-            const setTags = args.set;
-            const addTags = args.add;
-            const removeTags = args.remove;
-            if (!setTags && !addTags && !removeTags) {
-                return { success: false, error: "Provide set (replace all), add (append), or remove (delete specific tags)" };
+          }
+
+          // Validate all items up-front
+          for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            if (!item.id && !item.media_id) {
+              return {
+                success: false,
+                error: `items[${i}] missing id`
+              };
             }
-            if (setTags) {
-                // Direct replacement
-                const { data, error } = await sb.from("store_media")
-                    .update({ custom_tags: setTags })
-                    .in("id", ids)
-                    .eq("store_id", storeId)
-                    .select("id, custom_tags");
-                if (error)
-                    return { success: false, error: error.message };
-                return { success: true, data: { updated_count: data?.length || 0, tags: setTags } };
+            if (item.category && !VALID_CATEGORIES.includes(item.category)) {
+              return {
+                success: false,
+                error: `items[${i}] invalid category: ${item.category}`
+              };
             }
-            // Incremental add/remove — read-modify-write per item
-            const { data: rows, error: fetchErr } = await sb.from("store_media")
-                .select("id, custom_tags")
-                .in("id", ids)
-                .eq("store_id", storeId);
-            if (fetchErr)
-                return { success: false, error: fetchErr.message };
-            let updatedCount = 0;
-            for (const row of rows || []) {
-                let tags = row.custom_tags || [];
-                if (addTags) {
-                    const newTags = addTags.filter(t => !tags.includes(t));
-                    tags = [...tags, ...newTags];
-                }
-                if (removeTags) {
-                    tags = tags.filter(t => !removeTags.includes(t));
-                }
-                const { error: upErr } = await sb.from("store_media")
-                    .update({ custom_tags: tags })
-                    .eq("id", row.id)
-                    .eq("store_id", storeId);
-                if (!upErr)
-                    updatedCount++;
+            if (item.status && !VALID_STATUSES.includes(item.status)) {
+              return {
+                success: false,
+                error: `items[${i}] invalid status: ${item.status}`
+              };
             }
-            return { success: true, data: { updated_count: updatedCount } };
-        }
-        // ── FOLDERS LIST ───────────────────────────────────────────────────────────
-        case "folders_list": {
-            const { data, error } = await sb.from("media_folders")
-                .select("*")
-                .eq("store_id", storeId)
-                .order("name", { ascending: true });
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { count: data?.length || 0, folders: data } };
-        }
-        // ── FOLDERS CREATE ─────────────────────────────────────────────────────────
-        case "folders_create": {
-            const name = args.name;
-            if (!name)
-                return { success: false, error: "name required" };
-            const insertData = { store_id: storeId, name };
-            if (args.parent_folder_id)
-                insertData.parent_folder_id = args.parent_folder_id;
-            if (args.color)
-                insertData.color = args.color;
-            if (args.icon)
-                insertData.icon = args.icon;
-            const { data, error } = await sb.from("media_folders")
-                .insert(insertData)
-                .select("*")
-                .single();
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data };
-        }
-        // ── FOLDERS UPDATE ─────────────────────────────────────────────────────────
-        case "folders_update": {
-            const folderId = args.folder_id;
-            if (!folderId)
-                return { success: false, error: "folder_id required" };
-            const updates = {};
-            if (args.name !== undefined)
-                updates.name = args.name;
-            if (args.parent_folder_id !== undefined)
-                updates.parent_folder_id = args.parent_folder_id;
-            if (args.color !== undefined)
-                updates.color = args.color;
-            if (args.icon !== undefined)
-                updates.icon = args.icon;
-            if (Object.keys(updates).length === 0) {
-                return { success: false, error: "Nothing to update. Fields: name, parent_folder_id, color, icon" };
+          }
+
+          // Process in parallel batches of 25
+          const BATCH_SIZE = 25;
+          let updatedCount = 0;
+          let failedCount = 0;
+          const errors = [];
+          for (let i = 0; i < items.length; i += BATCH_SIZE) {
+            const batch = items.slice(i, i + BATCH_SIZE);
+            const results = await Promise.allSettled(batch.map(async item => {
+              const itemId = item.id || item.media_id;
+              const updates = {};
+              for (const key of UPDATE_WHITELIST) {
+                if (item[key] !== undefined) updates[key] = item[key];
+              }
+              if (item.description !== undefined && updates.notes === undefined) {
+                updates.notes = item.description;
+              }
+              if (item.tags !== undefined && updates.custom_tags === undefined) {
+                updates.custom_tags = item.tags;
+              }
+              if (Object.keys(updates).length === 0) return null; // skip no-ops
+
+              const {
+                error
+              } = await sb.from("store_media").update(updates).eq("id", itemId).eq("store_id", storeId);
+              if (error) throw new Error(`${itemId}: ${error.message}`);
+              return itemId;
+            }));
+            for (const r of results) {
+              if (r.status === "fulfilled" && r.value !== null) updatedCount++;else if (r.status === "rejected") {
+                failedCount++;
+                errors.push(r.reason?.message || String(r.reason));
+              }
             }
-            const { data, error } = await sb.from("media_folders")
-                .update(updates)
-                .eq("id", folderId)
-                .eq("store_id", storeId)
-                .select("*")
-                .single();
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data };
-        }
-        // ── FOLDERS DELETE ─────────────────────────────────────────────────────────
-        case "folders_delete": {
-            const folderId = args.folder_id;
-            if (!folderId)
-                return { success: false, error: "folder_id required" };
-            // Optionally move orphaned media to another folder
-            if (args.move_contents_to) {
-                await sb.from("store_media")
-                    .update({ folder: args.move_contents_to })
-                    .eq("folder_id", folderId)
-                    .eq("store_id", storeId);
+          }
+          return {
+            success: updatedCount > 0,
+            data: {
+              updated_count: updatedCount,
+              failed_count: failedCount,
+              ...(errors.length > 0 ? {
+                errors: errors.slice(0, 10)
+              } : {})
             }
-            // FK is ON DELETE SET NULL — safe to delete
-            const { error } = await sb.from("media_folders")
-                .delete()
-                .eq("id", folderId)
-                .eq("store_id", storeId);
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { deleted: folderId } };
-        }
-        // ── LINK PRODUCT ───────────────────────────────────────────────────────────
-        case "link_product": {
-            const mediaId = args.media_id;
-            const productId = args.product_id;
-            if (!mediaId || !productId)
-                return { success: false, error: "media_id and product_id required" };
-            const { error } = await sb.rpc("link_media_to_product", {
-                p_media_id: mediaId,
-                p_product_id: productId,
-            });
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { linked: true, media_id: mediaId, product_id: productId } };
-        }
-        // ── UNLINK PRODUCT ─────────────────────────────────────────────────────────
-        case "unlink_product": {
-            const mediaId = args.media_id;
-            const productId = args.product_id;
-            if (!mediaId || !productId)
-                return { success: false, error: "media_id and product_id required" };
-            const { error } = await sb.rpc("unlink_media_from_product", {
-                p_media_id: mediaId,
-                p_product_id: productId,
-            });
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data: { unlinked: true, media_id: mediaId, product_id: productId } };
-        }
-        // ── USAGE ──────────────────────────────────────────────────────────────────
-        case "usage": {
-            const mediaId = args.media_id;
-            if (!mediaId)
-                return { success: false, error: "media_id required" };
-            // Get the media's file_url
-            const { data: media, error: mediaErr } = await sb.from("store_media")
-                .select("file_url")
-                .eq("id", mediaId)
-                .eq("store_id", storeId)
-                .single();
-            if (mediaErr)
-                return { success: false, error: mediaErr.message };
-            if (!media?.file_url)
-                return { success: false, error: "Media not found or has no file_url" };
-            // Query media_references for this URL
-            const { data: refs, error: refErr } = await sb.from("media_references")
-                .select("entity_type, entity_id, entity_name, field_name, created_at")
-                .eq("media_url", media.file_url)
-                .eq("store_id", storeId)
-                .order("created_at", { ascending: false });
-            if (refErr)
-                return { success: false, error: refErr.message };
-            return {
-                success: true,
-                data: {
-                    media_id: mediaId,
-                    reference_count: refs?.length || 0,
-                    references: refs,
-                },
-            };
+          };
         }
-        // ── ANALYTICS ──────────────────────────────────────────────────────────────
-        case "analytics": {
-            // Run parallel aggregate queries
-            const [activeRes, archivedRes, allRes, orphanRes, typeRes, catRes, topRes] = await Promise.all([
-                sb.from("store_media").select("id", { count: "exact", head: true }).eq("store_id", storeId).eq("status", "active"),
-                sb.from("store_media").select("id", { count: "exact", head: true }).eq("store_id", storeId).eq("status", "archived"),
-                sb.from("store_media").select("file_size, file_type, category").eq("store_id", storeId),
-                sb.from("store_media").select("id", { count: "exact", head: true }).eq("store_id", storeId).eq("usage_count", 0).neq("status", "archived"),
-                sb.from("store_media").select("file_type").eq("store_id", storeId),
-                sb.from("store_media").select("category").eq("store_id", storeId),
-                sb.from("store_media").select("id, file_name, title, file_url, usage_count").eq("store_id", storeId).order("usage_count", { ascending: false }).limit(10),
-            ]);
-            // Compute total storage
-            const allRows = allRes.data || [];
-            const totalBytes = allRows.reduce((sum, r) => sum + (r.file_size || 0), 0);
-            // Type breakdown (group by prefix before /)
-            const typeBreakdown = {};
-            for (const row of typeRes.data || []) {
-                const prefix = (row.file_type || "unknown").split("/")[0];
-                typeBreakdown[prefix] = (typeBreakdown[prefix] || 0) + 1;
-            }
-            // Category breakdown
-            const catBreakdown = {};
-            for (const row of catRes.data || []) {
-                const cat = row.category || "unknown";
-                catBreakdown[cat] = (catBreakdown[cat] || 0) + 1;
-            }
-            return {
-                success: true,
-                data: {
-                    total_items: (activeRes.count || 0) + (archivedRes.count || 0),
-                    active_count: activeRes.count || 0,
-                    archived_count: archivedRes.count || 0,
-                    orphan_count: orphanRes.count || 0,
-                    total_storage_bytes: totalBytes,
-                    total_storage_mb: Math.round(totalBytes / 1_048_576 * 100) / 100,
-                    type_breakdown: typeBreakdown,
-                    category_breakdown: catBreakdown,
-                    top_used: topRes.data || [],
-                },
-            };
+
+        // ── Uniform mode ──
+        const ids = args.media_ids;
+        if (!ids || !Array.isArray(ids) || ids.length === 0) {
+          return {
+            success: false,
+            error: "Provide items[] (per-item updates) or media_ids[] + shared fields (uniform update)"
+          };
         }
-        // ── DUPLICATE ──────────────────────────────────────────────────────────────
-        case "duplicate": {
-            const mediaId = args.media_id;
-            if (!mediaId)
-                return { success: false, error: "media_id required" };
-            // Fetch source row
-            const { data: source, error: srcErr } = await sb.from("store_media")
-                .select("*")
-                .eq("id", mediaId)
-                .eq("store_id", storeId)
-                .single();
-            if (srcErr)
-                return { success: false, error: srcErr.message };
-            // Download source file from storage
-            const { data: fileData, error: dlErr } = await sb.storage
-                .from(BUCKET)
-                .download(source.file_path);
-            if (dlErr)
-                return { success: false, error: `Download source failed: ${dlErr.message}` };
-            const buffer = Buffer.from(await fileData.arrayBuffer());
-            // Upload with new UUID path
-            const newId = crypto.randomUUID();
-            const ext = source.file_name.split(".").pop() || "bin";
-            const newFileName = `${newId}.${ext}`;
-            const newPath = `${source.folder || "uploads"}/${storeId.toUpperCase()}/${newFileName}`;
-            const { error: upErr } = await sb.storage
-                .from(BUCKET)
-                .upload(newPath, buffer, { contentType: source.file_type, upsert: true });
-            if (upErr)
-                return { success: false, error: `Upload duplicate failed: ${upErr.message}` };
-            const { data: urlData } = sb.storage.from(BUCKET).getPublicUrl(newPath);
-            const cdnUrl = urlData.publicUrl;
-            const newTitle = args.new_title || (source.title ? `${source.title} (copy)` : null);
-            const { data: newRow, error: insertErr } = await sb.from("store_media")
-                .insert({
-                store_id: storeId,
-                file_name: newFileName,
-                file_path: newPath,
-                file_url: cdnUrl,
-                file_size: buffer.length,
-                file_type: source.file_type,
-                category: source.category,
-                source: "media-duplicate",
-                folder: source.folder,
-                title: newTitle,
-                alt_text: source.alt_text,
-                notes: source.notes,
-                custom_tags: source.custom_tags,
-            })
-                .select("id, file_name, file_url, title")
-                .single();
-            if (insertErr)
-                return { success: false, error: insertErr.message };
-            return {
-                success: true,
-                data: {
-                    original_id: mediaId,
-                    id: newRow.id,
-                    file_name: newRow.file_name,
-                    file_url: newRow.file_url,
-                    title: newRow.title,
-                },
-            };
+        const updates = {};
+        for (const key of UPDATE_WHITELIST) {
+          if (args[key] !== undefined) updates[key] = args[key];
         }
-        // ── REPLACE ────────────────────────────────────────────────────────────────
-        case "replace": {
-            const mediaId = args.media_id;
-            if (!mediaId)
-                return { success: false, error: "media_id required" };
-            let base64 = args.base64;
-            const fileUrl = args.file_url;
-            if (!base64 && !fileUrl) {
-                return { success: false, error: "Provide base64, file_url, or file_path (local — handled by CLI)" };
-            }
-            if (base64)
-                base64 = base64.replace(/^data:[^;]+;base64,/, "").replace(/\s/g, "");
-            if (!base64 && fileUrl) {
-                if (fileUrl.startsWith("/") || /^[A-Z]:\\/i.test(fileUrl)) {
-                    return { success: false, error: `Use file_path for local files: media(action="replace", media_id="...", file_path="${fileUrl}")` };
-                }
-                let fetchUrl = fileUrl;
-                if (!fetchUrl.startsWith("http://") && !fetchUrl.startsWith("https://")) {
-                    fetchUrl = `https://${fetchUrl}`;
-                }
-                const resp = await fetch(fetchUrl);
-                if (!resp.ok)
-                    return { success: false, error: `Failed to fetch file_url: ${resp.status}` };
-                const buf = await resp.arrayBuffer();
-                base64 = Buffer.from(buf).toString("base64");
-            }
-            // Fetch existing row
-            const { data: existing, error: getErr } = await sb.from("store_media")
-                .select("file_path")
-                .eq("id", mediaId)
-                .eq("store_id", storeId)
-                .single();
-            if (getErr)
-                return { success: false, error: getErr.message };
-            // Delete old storage file
-            if (existing.file_path) {
-                await sb.storage.from(BUCKET).remove([existing.file_path]);
+        if (args.description !== undefined && updates.notes === undefined) {
+          updates.notes = args.description;
+        }
+        if (args.tags !== undefined && updates.custom_tags === undefined) {
+          updates.custom_tags = args.tags;
+        }
+        if (Object.keys(updates).length === 0) {
+          return {
+            success: false,
+            error: `Nothing to update. Updatable fields: ${UPDATE_WHITELIST.join(", ")}`
+          };
+        }
+        if (updates.category && !VALID_CATEGORIES.includes(updates.category)) {
+          return {
+            success: false,
+            error: `Invalid category. Valid: ${VALID_CATEGORIES.join(", ")}`
+          };
+        }
+        if (updates.status && !VALID_STATUSES.includes(updates.status)) {
+          return {
+            success: false,
+            error: `Invalid status. Valid: ${VALID_STATUSES.join(", ")}`
+          };
+        }
+        const {
+          data,
+          error
+        } = await sb.from("store_media").update(updates).in("id", ids).eq("store_id", storeId).select("id");
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            updated_count: data?.length || 0
+          }
+        };
+      }
+
+    // ── DELETE ─────────────────────────────────────────────────────────────────
+    case "delete":
+      {
+        const mediaId = args.media_id;
+        if (!mediaId) return {
+          success: false,
+          error: "media_id required"
+        };
+        const {
+          data: row
+        } = await sb.from("store_media").select("file_path").eq("id", mediaId).eq("store_id", storeId).single();
+        if (row?.file_path) {
+          await sb.storage.from(BUCKET).remove([row.file_path]);
+        }
+        const {
+          error
+        } = await sb.from("store_media").delete().eq("id", mediaId).eq("store_id", storeId);
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            deleted: mediaId
+          }
+        };
+      }
+
+    // ── BULK DELETE ────────────────────────────────────────────────────────────
+    case "bulk_delete":
+      {
+        const ids = args.media_ids;
+        if (!ids || !Array.isArray(ids) || ids.length === 0) {
+          return {
+            success: false,
+            error: "media_ids[] required"
+          };
+        }
+
+        // Fetch file paths for storage cleanup
+        const {
+          data: rows
+        } = await sb.from("store_media").select("id, file_path").in("id", ids).eq("store_id", storeId);
+        const filePaths = (rows || []).map(r => r.file_path).filter(Boolean);
+        if (filePaths.length > 0) {
+          await sb.storage.from(BUCKET).remove(filePaths);
+        }
+        const {
+          error
+        } = await sb.from("store_media").delete().in("id", ids).eq("store_id", storeId);
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            deleted_count: rows?.length || 0
+          }
+        };
+      }
+
+    // ── SEARCH ─────────────────────────────────────────────────────────────────
+    case "search":
+      {
+        const query = args.query;
+        if (!query) return {
+          success: false,
+          error: "query required for search"
+        };
+        const sq = sanitizeFilterValue(query);
+        const limit = Math.min(Number(args.limit) || 50, 200);
+        const offset = Number(args.offset) || 0;
+        const sortBy = VALID_SORT_COLUMNS.includes(args.sort_by) ? args.sort_by : "created_at";
+        const sortOrder = args.sort_order === "asc";
+        let q = sb.from("store_media").select(LIST_COLUMNS, {
+          count: "exact"
+        }).eq("store_id", storeId).or(`file_name.ilike.%${sq}%,title.ilike.%${sq}%,alt_text.ilike.%${sq}%,notes.ilike.%${sq}%`).order(sortBy, {
+          ascending: sortOrder
+        }).range(offset, offset + limit - 1);
+
+        // Filters
+        if (args.status) {
+          q = q.eq("status", args.status);
+        } else if (!args.include_archived) {
+          q = q.neq("status", "archived");
+        }
+        if (args.folder) q = q.eq("folder", args.folder);
+        if (args.category) q = q.eq("category", args.category);
+        if (args.file_type) {
+          const ft = sanitizeFilterValue(args.file_type);
+          q = q.ilike("file_type", `${ft}%`);
+        }
+        if (args.tags && Array.isArray(args.tags)) {
+          q = q.overlaps("custom_tags", args.tags);
+        }
+        if (args.date_from) q = q.gte("created_at", args.date_from);
+        if (args.date_to) q = q.lte("created_at", args.date_to);
+        if (args.min_usage !== undefined) q = q.gte("usage_count", Number(args.min_usage));
+        if (args.max_usage !== undefined) q = q.lte("usage_count", Number(args.max_usage));
+        const {
+          data,
+          error,
+          count
+        } = await q;
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            total: count || 0,
+            count: data?.length || 0,
+            offset,
+            query,
+            files: data
+          }
+        };
+      }
+
+    // ── MOVE ───────────────────────────────────────────────────────────────────
+    case "move":
+      {
+        const folder = args.folder;
+        if (!folder) return {
+          success: false,
+          error: "folder required"
+        };
+        const ids = args.media_ids || (args.media_id ? [args.media_id] : []);
+        if (ids.length === 0) return {
+          success: false,
+          error: "media_id or media_ids[] required"
+        };
+        const {
+          data,
+          error
+        } = await sb.from("store_media").update({
+          folder
+        }).in("id", ids).eq("store_id", storeId).select("id");
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            moved_count: data?.length || 0,
+            folder
+          }
+        };
+      }
+
+    // ── ARCHIVE ────────────────────────────────────────────────────────────────
+    case "archive":
+      {
+        const ids = args.media_ids || (args.media_id ? [args.media_id] : []);
+        if (ids.length === 0) return {
+          success: false,
+          error: "media_id or media_ids[] required"
+        };
+        const {
+          data,
+          error
+        } = await sb.from("store_media").update({
+          status: "archived"
+        }).in("id", ids).eq("store_id", storeId).select("id");
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            archived_count: data?.length || 0
+          }
+        };
+      }
+
+    // ── UNARCHIVE ──────────────────────────────────────────────────────────────
+    case "unarchive":
+      {
+        const ids = args.media_ids || (args.media_id ? [args.media_id] : []);
+        if (ids.length === 0) return {
+          success: false,
+          error: "media_id or media_ids[] required"
+        };
+        const {
+          data,
+          error
+        } = await sb.from("store_media").update({
+          status: "active"
+        }).in("id", ids).eq("store_id", storeId).select("id");
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            unarchived_count: data?.length || 0
+          }
+        };
+      }
+
+    // ── TAG ────────────────────────────────────────────────────────────────────
+    case "tag":
+      {
+        const ids = args.media_ids || (args.media_id ? [args.media_id] : []);
+        if (ids.length === 0) return {
+          success: false,
+          error: "media_id or media_ids[] required"
+        };
+        const setTags = args.set;
+        const addTags = args.add;
+        const removeTags = args.remove;
+        if (!setTags && !addTags && !removeTags) {
+          return {
+            success: false,
+            error: "Provide set (replace all), add (append), or remove (delete specific tags)"
+          };
+        }
+        if (setTags) {
+          // Direct replacement
+          const {
+            data,
+            error
+          } = await sb.from("store_media").update({
+            custom_tags: setTags
+          }).in("id", ids).eq("store_id", storeId).select("id, custom_tags");
+          if (error) return {
+            success: false,
+            error: error.message
+          };
+          return {
+            success: true,
+            data: {
+              updated_count: data?.length || 0,
+              tags: setTags
             }
-            const mime = args.mime_type || detectMime(base64);
-            const ext = mimeToExt(mime);
-            const buffer = Buffer.from(base64, "base64");
-            const newId = crypto.randomUUID();
-            const originalName = args.file_name || "";
-            const newFileName = originalName
-                ? `${newId}-${originalName.replace(/[^a-zA-Z0-9._-]/g, "_")}`
-                : `${newId}.${ext}`;
-            const folder = args.folder || "uploads";
-            const newPath = `${folder}/${storeId.toUpperCase()}/${newFileName}`;
-            const { error: upErr } = await sb.storage
-                .from(BUCKET)
-                .upload(newPath, buffer, { contentType: mime, upsert: true });
-            if (upErr)
-                return { success: false, error: `Upload replacement failed: ${upErr.message}` };
-            const { data: urlData } = sb.storage.from(BUCKET).getPublicUrl(newPath);
-            const cdnUrl = urlData.publicUrl;
-            const { data, error } = await sb.from("store_media")
-                .update({
-                file_name: newFileName,
-                file_path: newPath,
-                file_url: cdnUrl,
-                file_size: buffer.length,
-                file_type: mime,
-            })
-                .eq("id", mediaId)
-                .eq("store_id", storeId)
-                .select("*")
-                .single();
-            if (error)
-                return { success: false, error: error.message };
-            return { success: true, data };
-        }
-        // ── DEFAULT ────────────────────────────────────────────────────────────────
-        default:
+          };
+        }
+
+        // Incremental add/remove — read-modify-write per item
+        const {
+          data: rows,
+          error: fetchErr
+        } = await sb.from("store_media").select("id, custom_tags").in("id", ids).eq("store_id", storeId);
+        if (fetchErr) return {
+          success: false,
+          error: fetchErr.message
+        };
+        let updatedCount = 0;
+        for (const row of rows || []) {
+          let tags = row.custom_tags || [];
+          if (addTags) {
+            const newTags = addTags.filter(t => !tags.includes(t));
+            tags = [...tags, ...newTags];
+          }
+          if (removeTags) {
+            tags = tags.filter(t => !removeTags.includes(t));
+          }
+          const {
+            error: upErr
+          } = await sb.from("store_media").update({
+            custom_tags: tags
+          }).eq("id", row.id).eq("store_id", storeId);
+          if (!upErr) updatedCount++;
+        }
+        return {
+          success: true,
+          data: {
+            updated_count: updatedCount
+          }
+        };
+      }
+
+    // ── FOLDERS LIST ───────────────────────────────────────────────────────────
+    case "folders_list":
+      {
+        const {
+          data,
+          error
+        } = await sb.from("media_folders").select("*").eq("store_id", storeId).order("name", {
+          ascending: true
+        });
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            count: data?.length || 0,
+            folders: data
+          }
+        };
+      }
+
+    // ── FOLDERS CREATE ─────────────────────────────────────────────────────────
+    case "folders_create":
+      {
+        const name = args.name;
+        if (!name) return {
+          success: false,
+          error: "name required"
+        };
+        const insertData = {
+          store_id: storeId,
+          name
+        };
+        if (args.parent_folder_id) insertData.parent_folder_id = args.parent_folder_id;
+        if (args.color) insertData.color = args.color;
+        if (args.icon) insertData.icon = args.icon;
+        const {
+          data,
+          error
+        } = await sb.from("media_folders").insert(insertData).select("*").single();
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data
+        };
+      }
+
+    // ── FOLDERS UPDATE ─────────────────────────────────────────────────────────
+    case "folders_update":
+      {
+        const folderId = args.folder_id;
+        if (!folderId) return {
+          success: false,
+          error: "folder_id required"
+        };
+        const updates = {};
+        if (args.name !== undefined) updates.name = args.name;
+        if (args.parent_folder_id !== undefined) updates.parent_folder_id = args.parent_folder_id;
+        if (args.color !== undefined) updates.color = args.color;
+        if (args.icon !== undefined) updates.icon = args.icon;
+        if (Object.keys(updates).length === 0) {
+          return {
+            success: false,
+            error: "Nothing to update. Fields: name, parent_folder_id, color, icon"
+          };
+        }
+        const {
+          data,
+          error
+        } = await sb.from("media_folders").update(updates).eq("id", folderId).eq("store_id", storeId).select("*").single();
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data
+        };
+      }
+
+    // ── FOLDERS DELETE ─────────────────────────────────────────────────────────
+    case "folders_delete":
+      {
+        const folderId = args.folder_id;
+        if (!folderId) return {
+          success: false,
+          error: "folder_id required"
+        };
+
+        // Optionally move orphaned media to another folder
+        if (args.move_contents_to) {
+          await sb.from("store_media").update({
+            folder: args.move_contents_to
+          }).eq("folder_id", folderId).eq("store_id", storeId);
+        }
+
+        // FK is ON DELETE SET NULL — safe to delete
+        const {
+          error
+        } = await sb.from("media_folders").delete().eq("id", folderId).eq("store_id", storeId);
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            deleted: folderId
+          }
+        };
+      }
+
+    // ── LINK PRODUCT ───────────────────────────────────────────────────────────
+    case "link_product":
+      {
+        const mediaId = args.media_id;
+        const productId = args.product_id;
+        if (!mediaId || !productId) return {
+          success: false,
+          error: "media_id and product_id required"
+        };
+        const {
+          error
+        } = await sb.rpc("link_media_to_product", {
+          p_media_id: mediaId,
+          p_product_id: productId
+        });
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            linked: true,
+            media_id: mediaId,
+            product_id: productId
+          }
+        };
+      }
+
+    // ── UNLINK PRODUCT ─────────────────────────────────────────────────────────
+    case "unlink_product":
+      {
+        const mediaId = args.media_id;
+        const productId = args.product_id;
+        if (!mediaId || !productId) return {
+          success: false,
+          error: "media_id and product_id required"
+        };
+        const {
+          error
+        } = await sb.rpc("unlink_media_from_product", {
+          p_media_id: mediaId,
+          p_product_id: productId
+        });
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data: {
+            unlinked: true,
+            media_id: mediaId,
+            product_id: productId
+          }
+        };
+      }
+
+    // ── USAGE ──────────────────────────────────────────────────────────────────
+    case "usage":
+      {
+        const mediaId = args.media_id;
+        if (!mediaId) return {
+          success: false,
+          error: "media_id required"
+        };
+
+        // Get the media's file_url
+        const {
+          data: media,
+          error: mediaErr
+        } = await sb.from("store_media").select("file_url").eq("id", mediaId).eq("store_id", storeId).single();
+        if (mediaErr) return {
+          success: false,
+          error: mediaErr.message
+        };
+        if (!media?.file_url) return {
+          success: false,
+          error: "Media not found or has no file_url"
+        };
+
+        // Query media_references for this URL
+        const {
+          data: refs,
+          error: refErr
+        } = await sb.from("media_references").select("entity_type, entity_id, entity_name, field_name, created_at").eq("media_url", media.file_url).eq("store_id", storeId).order("created_at", {
+          ascending: false
+        });
+        if (refErr) return {
+          success: false,
+          error: refErr.message
+        };
+        return {
+          success: true,
+          data: {
+            media_id: mediaId,
+            reference_count: refs?.length || 0,
+            references: refs
+          }
+        };
+      }
+
+    // ── ANALYTICS ──────────────────────────────────────────────────────────────
+    case "analytics":
+      {
+        // Run parallel aggregate queries
+        const [activeRes, archivedRes, allRes, orphanRes, typeRes, catRes, topRes] = await Promise.all([sb.from("store_media").select("id", {
+          count: "exact",
+          head: true
+        }).eq("store_id", storeId).eq("status", "active"), sb.from("store_media").select("id", {
+          count: "exact",
+          head: true
+        }).eq("store_id", storeId).eq("status", "archived"), sb.from("store_media").select("file_size, file_type, category").eq("store_id", storeId), sb.from("store_media").select("id", {
+          count: "exact",
+          head: true
+        }).eq("store_id", storeId).eq("usage_count", 0).neq("status", "archived"), sb.from("store_media").select("file_type").eq("store_id", storeId), sb.from("store_media").select("category").eq("store_id", storeId), sb.from("store_media").select("id, file_name, title, file_url, usage_count").eq("store_id", storeId).order("usage_count", {
+          ascending: false
+        }).limit(10)]);
+
+        // Compute total storage
+        const allRows = allRes.data || [];
+        const totalBytes = allRows.reduce((sum, r) => sum + (r.file_size || 0), 0);
+
+        // Type breakdown (group by prefix before /)
+        const typeBreakdown = {};
+        for (const row of typeRes.data || []) {
+          const prefix = (row.file_type || "unknown").split("/")[0];
+          typeBreakdown[prefix] = (typeBreakdown[prefix] || 0) + 1;
+        }
+
+        // Category breakdown
+        const catBreakdown = {};
+        for (const row of catRes.data || []) {
+          const cat = row.category || "unknown";
+          catBreakdown[cat] = (catBreakdown[cat] || 0) + 1;
+        }
+        return {
+          success: true,
+          data: {
+            total_items: (activeRes.count || 0) + (archivedRes.count || 0),
+            active_count: activeRes.count || 0,
+            archived_count: archivedRes.count || 0,
+            orphan_count: orphanRes.count || 0,
+            total_storage_bytes: totalBytes,
+            total_storage_mb: Math.round(totalBytes / 1_048_576 * 100) / 100,
+            type_breakdown: typeBreakdown,
+            category_breakdown: catBreakdown,
+            top_used: topRes.data || []
+          }
+        };
+      }
+
+    // ── DUPLICATE ──────────────────────────────────────────────────────────────
+    case "duplicate":
+      {
+        const mediaId = args.media_id;
+        if (!mediaId) return {
+          success: false,
+          error: "media_id required"
+        };
+
+        // Fetch source row
+        const {
+          data: source,
+          error: srcErr
+        } = await sb.from("store_media").select("*").eq("id", mediaId).eq("store_id", storeId).single();
+        if (srcErr) return {
+          success: false,
+          error: srcErr.message
+        };
+
+        // Download source file from storage
+        const {
+          data: fileData,
+          error: dlErr
+        } = await sb.storage.from(BUCKET).download(source.file_path);
+        if (dlErr) return {
+          success: false,
+          error: `Download source failed: ${dlErr.message}`
+        };
+        const buffer = Buffer.from(await fileData.arrayBuffer());
+
+        // Upload with new UUID path
+        const newId = crypto.randomUUID();
+        const ext = source.file_name.split(".").pop() || "bin";
+        const newFileName = `${newId}.${ext}`;
+        const newPath = `${source.folder || "uploads"}/${storeId.toUpperCase()}/${newFileName}`;
+        const {
+          error: upErr
+        } = await sb.storage.from(BUCKET).upload(newPath, buffer, {
+          contentType: source.file_type,
+          upsert: true
+        });
+        if (upErr) return {
+          success: false,
+          error: `Upload duplicate failed: ${upErr.message}`
+        };
+        const {
+          data: urlData
+        } = sb.storage.from(BUCKET).getPublicUrl(newPath);
+        const cdnUrl = urlData.publicUrl;
+        const newTitle = args.new_title || (source.title ? `${source.title} (copy)` : null);
+        const {
+          data: newRow,
+          error: insertErr
+        } = await sb.from("store_media").insert({
+          store_id: storeId,
+          file_name: newFileName,
+          file_path: newPath,
+          file_url: cdnUrl,
+          file_size: buffer.length,
+          file_type: source.file_type,
+          category: source.category,
+          source: "media-duplicate",
+          folder: source.folder,
+          title: newTitle,
+          alt_text: source.alt_text,
+          notes: source.notes,
+          custom_tags: source.custom_tags
+        }).select("id, file_name, file_url, title").single();
+        if (insertErr) return {
+          success: false,
+          error: insertErr.message
+        };
+        return {
+          success: true,
+          data: {
+            original_id: mediaId,
+            id: newRow.id,
+            file_name: newRow.file_name,
+            file_url: newRow.file_url,
+            title: newRow.title
+          }
+        };
+      }
+
+    // ── REPLACE ────────────────────────────────────────────────────────────────
+    case "replace":
+      {
+        const mediaId = args.media_id;
+        if (!mediaId) return {
+          success: false,
+          error: "media_id required"
+        };
+        let base64 = args.base64;
+        const fileUrl = args.file_url;
+        if (!base64 && !fileUrl) {
+          return {
+            success: false,
+            error: "Provide base64, file_url, or file_path (local — handled by CLI)"
+          };
+        }
+        if (base64) base64 = base64.replace(/^data:[^;]+;base64,/, "").replace(/\s/g, "");
+        if (!base64 && fileUrl) {
+          if (fileUrl.startsWith("/") || /^[A-Z]:\\/i.test(fileUrl)) {
             return {
-                success: false,
-                error: `Unknown action: ${action}. Available actions: ${ALL_ACTIONS.join(", ")}`,
+              success: false,
+              error: `Use file_path for local files: media(action="replace", media_id="...", file_path="${fileUrl}")`
             };
-    }
+          }
+          let fetchUrl = fileUrl;
+          if (!fetchUrl.startsWith("http://") && !fetchUrl.startsWith("https://")) {
+            fetchUrl = `https://${fetchUrl}`;
+          }
+          const resp = await fetch(fetchUrl);
+          if (!resp.ok) return {
+            success: false,
+            error: `Failed to fetch file_url: ${resp.status}`
+          };
+          const buf = await resp.arrayBuffer();
+          base64 = Buffer.from(buf).toString("base64");
+        }
+
+        // Fetch existing row
+        const {
+          data: existing,
+          error: getErr
+        } = await sb.from("store_media").select("file_path").eq("id", mediaId).eq("store_id", storeId).single();
+        if (getErr) return {
+          success: false,
+          error: getErr.message
+        };
+
+        // Delete old storage file
+        if (existing.file_path) {
+          await sb.storage.from(BUCKET).remove([existing.file_path]);
+        }
+        const mime = args.mime_type || detectMime(base64);
+        const ext = mimeToExt(mime);
+        const buffer = Buffer.from(base64, "base64");
+        const newId = crypto.randomUUID();
+        const originalName = args.file_name || "";
+        const newFileName = originalName ? `${newId}-${originalName.replace(/[^a-zA-Z0-9._-]/g, "_")}` : `${newId}.${ext}`;
+        const folder = args.folder || "uploads";
+        const newPath = `${folder}/${storeId.toUpperCase()}/${newFileName}`;
+        const {
+          error: upErr
+        } = await sb.storage.from(BUCKET).upload(newPath, buffer, {
+          contentType: mime,
+          upsert: true
+        });
+        if (upErr) return {
+          success: false,
+          error: `Upload replacement failed: ${upErr.message}`
+        };
+        const {
+          data: urlData
+        } = sb.storage.from(BUCKET).getPublicUrl(newPath);
+        const cdnUrl = urlData.publicUrl;
+        const {
+          data,
+          error
+        } = await sb.from("store_media").update({
+          file_name: newFileName,
+          file_path: newPath,
+          file_url: cdnUrl,
+          file_size: buffer.length,
+          file_type: mime
+        }).eq("id", mediaId).eq("store_id", storeId).select("*").single();
+        if (error) return {
+          success: false,
+          error: error.message
+        };
+        return {
+          success: true,
+          data
+        };
+      }
+
+    // ── DEFAULT ────────────────────────────────────────────────────────────────
+    default:
+      return {
+        success: false,
+        error: `Unknown action: ${action}. Available actions: ${ALL_ACTIONS.join(", ")}`
+      };
+  }
 }
+//# sourceMappingURL=media.js.map