whale-code 6.4.0 → 6.5.0

package/dist/server/handlers/media.js

@@ -0,0 +1,902 @@
+// server/handlers/media.ts — Full media management (23 actions)
+//
+// Upload, search, organize, tag, link to products, track usage, analytics,
+// duplicate, replace — complete media catalog management for AI agents.
+//
+// Input methods for upload/replace:
+//   - file_path  → CLI reads local file, base64-encodes in-process (preferred)
+//   - base64     → raw base64 string (auto-strips data URI prefix)
+//   - file_url   → public URL to fetch and re-upload
+//
+// 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 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";
+}
+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";
+}
+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);
+            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 } : {}),
+                },
+            };
+        }
+        // ── 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 },
+            };
+        }
+        // ── 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 };
+            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 } };
+            }
+            // 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: `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(", ")}`,
+            };
+    }
+}