convex-cms 0.0.1

package/dist/component/mediaFolderMutations.js

@@ -0,0 +1,849 @@
+/**
+ * Media Folder Mutation Functions
+ *
+ * Provides mutation functions for creating, updating, moving, and deleting media folders.
+ * Media folders organize media assets into a hierarchical structure with path validation.
+ *
+ * Folder Hierarchy:
+ * - Root folders have no parentId
+ * - Nested folders reference their parent folder
+ * - Path is automatically computed from the folder hierarchy (e.g., "/images/blog/2026")
+ * - Moving folders updates paths for the folder and all descendants
+ */
+import { mutation, query } from "./_generated/server.js";
+import { v } from "convex/values";
+import { createMediaFolderArgs, updateMediaFolderArgs, moveFolderArgs, mediaItemDoc, mutationAuthContext, } from "./validators.js";
+import { mediaFolderNotFound, mediaFolderDeleted, mediaFolderNotDeleted, mediaFolderNameInvalid, mediaFolderNameDuplicate, mediaFolderDepthExceeded, mediaFolderPathTooLong, mediaFolderHasContents, mediaFolderCircularMove, mediaFolderParentDeleted, mediaFolderCreateFailed, internalError, } from "./lib/errors.js";
+import { requireMutationAuth } from "./lib/mutationAuth.js";
+import { isDeleted } from "./lib/softDelete.js";
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Maximum depth of folder nesting.
+ * Prevents excessively deep hierarchies that could impact performance.
+ */
+const MAX_FOLDER_DEPTH = 10;
+/**
+ * Maximum length of a folder path.
+ * Prevents extremely long paths that could cause issues.
+ */
+const MAX_PATH_LENGTH = 500;
+/**
+ * Invalid characters in folder names.
+ * These characters are not allowed because they could break path parsing.
+ */
+const INVALID_NAME_CHARS = /[/\\:*?"<>|]/;
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Validates a folder name.
+ *
+ * @param name - The folder name to validate
+ * @throws Error if the name is invalid
+ */
+function validateFolderName(name) {
+    // Check for empty or whitespace-only names
+    const trimmed = name.trim();
+    if (trimmed.length === 0) {
+        throw mediaFolderNameInvalid(name, "Name cannot be empty");
+    }
+    // Check for invalid characters
+    if (INVALID_NAME_CHARS.test(trimmed)) {
+        throw mediaFolderNameInvalid(name, `Contains invalid characters. The following are not allowed: / \\ : * ? " < > |`);
+    }
+    // Check length
+    if (trimmed.length > 255) {
+        throw mediaFolderNameInvalid(name, "Name cannot exceed 255 characters");
+    }
+}
+/**
+ * Builds the full path for a folder based on its parent.
+ *
+ * @param name - The folder name
+ * @param parentPath - The parent folder's path (empty string for root)
+ * @returns The full path for the folder
+ */
+function buildFolderPath(name, parentPath) {
+    const trimmedName = name.trim();
+    if (!parentPath || parentPath === "/") {
+        return `/${trimmedName}`;
+    }
+    return `${parentPath}/${trimmedName}`;
+}
+/**
+ * Calculates the depth of a path.
+ *
+ * @param path - The folder path
+ * @returns The depth (number of segments)
+ */
+function getPathDepth(path) {
+    if (!path || path === "/")
+        return 0;
+    // Split by "/" and filter out empty strings
+    return path.split("/").filter((segment) => segment.length > 0).length;
+}
+// =============================================================================
+// Create Media Folder Mutation
+// =============================================================================
+/**
+ * Mutation to create a new media folder.
+ *
+ * Creates a folder in the media library hierarchy. Folders can be nested
+ * within other folders up to MAX_FOLDER_DEPTH levels deep. The full path
+ * is automatically computed based on the parent folder hierarchy.
+ *
+ * Validation Rules:
+ * - Folder name must not be empty or whitespace-only
+ * - Folder name must not contain: / \ : * ? " < > |
+ * - Folder name must not exceed 255 characters
+ * - Full path must not exceed MAX_PATH_LENGTH characters
+ * - Folder depth must not exceed MAX_FOLDER_DEPTH levels
+ * - Parent folder must exist and not be soft-deleted (if provided)
+ * - Folder name must be unique within the parent folder
+ *
+ * @param name - The folder name (required)
+ * @param parentId - Optional parent folder ID for nesting
+ * @param description - Optional description of the folder
+ * @param sortOrder - Optional custom sort order
+ * @param createdBy - Optional user ID for audit trail
+ *
+ * @returns The created media folder document
+ *
+ * @throws Error if the folder name is invalid
+ * @throws Error if the parent folder does not exist
+ * @throws Error if the parent folder has been deleted
+ * @throws Error if the folder depth would exceed the maximum
+ * @throws Error if the path length would exceed the maximum
+ * @throws Error if a folder with the same name already exists in the parent
+ *
+ * @example
+ * ```typescript
+ * // Create a root folder
+ * const imagesFolder = await ctx.runMutation(api.mediaFolderMutations.createMediaFolder, {
+ *   name: "Images",
+ *   description: "All image assets",
+ *   createdBy: currentUserId,
+ * });
+ *
+ * // Create a nested folder
+ * const blogFolder = await ctx.runMutation(api.mediaFolderMutations.createMediaFolder, {
+ *   name: "Blog",
+ *   parentId: imagesFolder._id,
+ *   description: "Blog post images",
+ *   createdBy: currentUserId,
+ * });
+ *
+ * // Result: blogFolder.path === "/Images/Blog"
+ * ```
+ */
+export const createMediaFolder = mutation({
+    args: {
+        ...createMediaFolderArgs.fields,
+        /** Optional auth context for mutation-level authorization */
+        _auth: v.optional(mutationAuthContext),
+    },
+    returns: mediaItemDoc,
+    handler: async (ctx, args) => {
+        const { name, parentId, description, sortOrder, createdBy, _auth } = args;
+        // Authorization check - mediaFolders.create permission
+        requireMutationAuth(_auth, "mediaItems", "create");
+        // Validate folder name
+        validateFolderName(name);
+        // Determine parent path and validate parent folder
+        let parentPath = "";
+        if (parentId !== undefined) {
+            // Fetch parent folder
+            const parentFolder = await ctx.db.get(parentId);
+            if (!parentFolder) {
+                throw mediaFolderNotFound(parentId);
+            }
+            if (isDeleted(parentFolder)) {
+                throw mediaFolderDeleted(parentId);
+            }
+            parentPath = parentFolder.path;
+            // Check folder depth limit
+            const parentDepth = getPathDepth(parentPath);
+            if (parentDepth >= MAX_FOLDER_DEPTH) {
+                throw mediaFolderDepthExceeded(MAX_FOLDER_DEPTH, parentDepth + 1);
+            }
+        }
+        // Build the full path
+        const path = buildFolderPath(name, parentPath);
+        // Check path length limit
+        if (path.length > MAX_PATH_LENGTH) {
+            throw mediaFolderPathTooLong(MAX_PATH_LENGTH, path.length);
+        }
+        // Check for duplicate folder name in the same parent
+        const existingFolder = await ctx.db
+            .query("mediaItems")
+            .withIndex("by_path", (q) => q.eq("path", path))
+            .filter((q) => q.and(q.eq(q.field("kind"), "folder"), q.eq(q.field("deletedAt"), undefined)))
+            .first();
+        if (existingFolder) {
+            throw mediaFolderNameDuplicate(name.trim(), parentPath || undefined);
+        }
+        // Create the folder
+        const folderId = await ctx.db.insert("mediaItems", {
+            kind: "folder",
+            name: name.trim(),
+            parentId,
+            path,
+            description,
+            sortOrder,
+            createdBy,
+        });
+        // Retrieve and return the created folder
+        const folder = await ctx.db.get(folderId);
+        if (!folder) {
+            throw mediaFolderCreateFailed();
+        }
+        return folder;
+    },
+});
+// =============================================================================
+// Update Media Folder Mutation
+// =============================================================================
+/**
+ * Mutation to update a media folder's metadata.
+ *
+ * Updates the folder name, description, or sort order. If the name is changed,
+ * the path is automatically updated for this folder and all its descendants.
+ *
+ * @param id - The folder ID to update
+ * @param name - Optional new folder name
+ * @param description - Optional new description
+ * @param sortOrder - Optional new sort order
+ *
+ * @returns The updated media folder document
+ *
+ * @throws Error if the folder does not exist
+ * @throws Error if the folder has been deleted
+ * @throws Error if the new name is invalid
+ * @throws Error if a folder with the new name already exists in the same parent
+ *
+ * @example
+ * ```typescript
+ * const updated = await ctx.runMutation(api.mediaFolderMutations.updateMediaFolder, {
+ *   id: folderId,
+ *   name: "Blog Images",
+ *   description: "Updated description",
+ * });
+ * ```
+ */
+export const updateMediaFolder = mutation({
+    args: {
+        ...updateMediaFolderArgs.fields,
+        /** Optional auth context for mutation-level authorization */
+        _auth: v.optional(mutationAuthContext),
+    },
+    returns: mediaItemDoc,
+    handler: async (ctx, args) => {
+        const { id, name, description, sortOrder, _auth } = args;
+        // Authorization check - mediaFolders.update permission
+        requireMutationAuth(_auth, "mediaItems", "update");
+        const folder = await ctx.db.get(id);
+        if (!folder) {
+            throw mediaFolderNotFound(id);
+        }
+        if (isDeleted(folder)) {
+            throw mediaFolderDeleted(id);
+        }
+        // Build updates object
+        const updates = {};
+        // Handle name change (requires path update)
+        if (name !== undefined && name.trim() !== folder.name) {
+            validateFolderName(name);
+            // Get parent path
+            let parentPath = "";
+            if (folder.parentId) {
+                const parentFolder = await ctx.db.get(folder.parentId);
+                if (parentFolder) {
+                    parentPath = parentFolder.path;
+                }
+            }
+            // Build new path
+            const newPath = buildFolderPath(name, parentPath);
+            // Check path length
+            if (newPath.length > MAX_PATH_LENGTH) {
+                throw mediaFolderPathTooLong(MAX_PATH_LENGTH, newPath.length);
+            }
+            // Check for duplicate name in same parent
+            const existingFolder = await ctx.db
+                .query("mediaItems")
+                .withIndex("by_path", (q) => q.eq("path", newPath))
+                .filter((q) => q.eq(q.field("deletedAt"), undefined))
+                .first();
+            if (existingFolder && existingFolder._id !== id) {
+                throw mediaFolderNameDuplicate(name.trim(), parentPath || undefined);
+            }
+            updates.name = name.trim();
+            const oldPath = folder.path;
+            updates.path = newPath;
+            // Update all descendant folder paths
+            await updateDescendantPaths(ctx, oldPath, newPath);
+        }
+        if (description !== undefined) {
+            updates.description = description;
+        }
+        if (sortOrder !== undefined) {
+            updates.sortOrder = sortOrder;
+        }
+        // Apply updates if any
+        if (Object.keys(updates).length > 0) {
+            await ctx.db.patch(id, updates);
+        }
+        // Retrieve and return the updated folder
+        const updatedFolder = await ctx.db.get(id);
+        if (!updatedFolder) {
+            throw new Error("Failed to retrieve updated media folder");
+        }
+        return updatedFolder;
+    },
+});
+/**
+ * Updates paths for all descendant folders when a parent folder is renamed.
+ */
+async function updateDescendantPaths(ctx, oldParentPath, newParentPath) {
+    // Find all folders whose path starts with the old path
+    const descendants = await ctx.db
+        .query("mediaItems")
+        .filter((q) => q.eq(q.field("deletedAt"), undefined))
+        .collect();
+    for (const descendant of descendants) {
+        if (descendant.path.startsWith(oldParentPath + "/") &&
+            descendant.path !== oldParentPath) {
+            const newDescendantPath = descendant.path.replace(oldParentPath, newParentPath);
+            await ctx.db.patch(descendant._id, { path: newDescendantPath });
+        }
+    }
+}
+// =============================================================================
+// Move Media Folder Mutation
+// =============================================================================
+/**
+ * Mutation to move a folder to a different parent.
+ *
+ * Moves a folder and all its contents (assets and subfolders) to a new
+ * location in the hierarchy. Updates paths for the folder and all descendants.
+ *
+ * @param id - The folder ID to move
+ * @param newParentId - The new parent folder ID (undefined for root level)
+ *
+ * @returns The moved media folder document
+ *
+ * @throws Error if the folder does not exist
+ * @throws Error if the folder has been deleted
+ * @throws Error if the new parent does not exist
+ * @throws Error if the new parent has been deleted
+ * @throws Error if moving would create a circular reference
+ * @throws Error if moving would exceed the maximum depth
+ *
+ * @example
+ * ```typescript
+ * // Move folder to a different parent
+ * const moved = await ctx.runMutation(api.mediaFolderMutations.moveMediaFolder, {
+ *   id: folderId,
+ *   newParentId: newParentFolderId,
+ * });
+ *
+ * // Move folder to root level
+ * const movedToRoot = await ctx.runMutation(api.mediaFolderMutations.moveMediaFolder, {
+ *   id: folderId,
+ *   newParentId: undefined,
+ * });
+ * ```
+ */
+export const moveMediaFolder = mutation({
+    args: {
+        ...moveFolderArgs.fields,
+        /** Optional auth context for mutation-level authorization */
+        _auth: v.optional(mutationAuthContext),
+    },
+    returns: mediaItemDoc,
+    handler: async (ctx, args) => {
+        const { id, newParentId, _auth } = args;
+        // Authorization check - mediaFolders.update permission (move is a form of update)
+        requireMutationAuth(_auth, "mediaItems", "update");
+        const folder = await ctx.db.get(id);
+        if (!folder) {
+            throw mediaFolderNotFound(id);
+        }
+        if (isDeleted(folder)) {
+            throw mediaFolderDeleted(id);
+        }
+        // No change needed if parent is the same
+        if (folder.parentId === newParentId) {
+            return folder;
+        }
+        // Determine new parent path
+        let newParentPath = "";
+        if (newParentId !== undefined) {
+            // Fetch new parent folder
+            const newParentFolder = await ctx.db.get(newParentId);
+            if (!newParentFolder) {
+                throw mediaFolderNotFound(newParentId);
+            }
+            if (isDeleted(newParentFolder)) {
+                throw mediaFolderDeleted(newParentId);
+            }
+            // Check for circular reference
+            // Cannot move a folder into itself or one of its descendants
+            if (newParentFolder.path.startsWith(folder.path + "/") ||
+                newParentFolder._id === id) {
+                throw mediaFolderCircularMove(id);
+            }
+            newParentPath = newParentFolder.path;
+            // Check depth limit
+            const newParentDepth = getPathDepth(newParentPath);
+            const folderSubtreeDepth = await getMaxSubtreeDepth(ctx, folder.path);
+            const totalDepth = newParentDepth + 1 + folderSubtreeDepth;
+            if (totalDepth > MAX_FOLDER_DEPTH) {
+                throw mediaFolderDepthExceeded(MAX_FOLDER_DEPTH, totalDepth);
+            }
+        }
+        // Build new path
+        const oldPath = folder.path;
+        const newPath = buildFolderPath(folder.name, newParentPath);
+        // Check path length
+        if (newPath.length > MAX_PATH_LENGTH) {
+            throw mediaFolderPathTooLong(MAX_PATH_LENGTH, newPath.length);
+        }
+        // Check for duplicate name in new parent
+        const existingFolder = await ctx.db
+            .query("mediaItems")
+            .withIndex("by_path", (q) => q.eq("path", newPath))
+            .filter((q) => q.eq(q.field("deletedAt"), undefined))
+            .first();
+        if (existingFolder && existingFolder._id !== id) {
+            throw mediaFolderNameDuplicate(folder.name, newParentPath || undefined);
+        }
+        // Update the folder
+        await ctx.db.patch(id, {
+            parentId: newParentId,
+            path: newPath,
+        });
+        // Update all descendant folder paths
+        await updateDescendantPaths(ctx, oldPath, newPath);
+        // Retrieve and return the moved folder
+        const movedFolder = await ctx.db.get(id);
+        if (!movedFolder) {
+            throw internalError("Failed to retrieve moved media folder");
+        }
+        return movedFolder;
+    },
+});
+/**
+ * Gets the maximum depth of descendants under a folder path.
+ */
+async function getMaxSubtreeDepth(ctx, folderPath) {
+    const descendants = await ctx.db
+        .query("mediaItems")
+        .filter((q) => q.eq(q.field("deletedAt"), undefined))
+        .collect();
+    let maxDepth = 0;
+    const baseDepth = getPathDepth(folderPath);
+    for (const descendant of descendants) {
+        if (descendant.path.startsWith(folderPath + "/")) {
+            const descendantDepth = getPathDepth(descendant.path);
+            const relativeDepth = descendantDepth - baseDepth;
+            if (relativeDepth > maxDepth) {
+                maxDepth = relativeDepth;
+            }
+        }
+    }
+    return maxDepth;
+}
+// =============================================================================
+// Delete Media Folder Mutation
+// =============================================================================
+/**
+ * Validator for delete folder arguments.
+ */
+export const deleteMediaFolderArgs = {
+    id: v.id("mediaItems"),
+    deletedBy: v.optional(v.string()),
+    hardDelete: v.optional(v.boolean()),
+    recursive: v.optional(v.boolean()),
+};
+/**
+ * Mutation to delete a media folder.
+ *
+ * Supports two modes:
+ * - Soft delete (default): Sets deletedAt timestamp, folder can be restored
+ * - Hard delete: Permanently removes the folder from the database
+ *
+ * By default, deletion fails if the folder contains assets or subfolders.
+ * Use recursive: true to delete the folder and all its contents.
+ *
+ * @param id - The folder ID to delete
+ * @param deletedBy - Optional user ID for audit trail
+ * @param hardDelete - If true, permanently deletes the folder
+ * @param recursive - If true, deletes folder and all contents
+ *
+ * @returns The deleted media folder document
+ *
+ * @throws Error if the folder does not exist
+ * @throws Error if the folder is already deleted (for soft delete)
+ * @throws Error if the folder has contents and recursive is not true
+ *
+ * @example
+ * ```typescript
+ * // Soft delete an empty folder
+ * const deleted = await ctx.runMutation(api.mediaFolderMutations.deleteMediaFolder, {
+ *   id: folderId,
+ *   deletedBy: currentUserId,
+ * });
+ *
+ * // Recursively delete folder and all contents
+ * const deleted = await ctx.runMutation(api.mediaFolderMutations.deleteMediaFolder, {
+ *   id: folderId,
+ *   deletedBy: currentUserId,
+ *   recursive: true,
+ * });
+ * ```
+ */
+export const deleteMediaFolder = mutation({
+    args: {
+        ...deleteMediaFolderArgs,
+        /** Optional auth context for mutation-level authorization */
+        _auth: v.optional(mutationAuthContext),
+    },
+    returns: mediaItemDoc,
+    handler: async (ctx, args) => {
+        const { id, 
+        // deletedBy,
+        hardDelete = false, recursive = false, _auth, } = args;
+        // Authorization check - mediaFolders.delete permission
+        requireMutationAuth(_auth, "mediaItems", "delete");
+        const folder = await ctx.db.get(id);
+        if (!folder) {
+            throw mediaFolderNotFound(id);
+        }
+        // For soft delete, check if already deleted
+        if (!hardDelete && isDeleted(folder)) {
+            throw mediaFolderDeleted(id);
+        }
+        // Check for contents (subfolders and assets)
+        const subfolders = await ctx.db
+            .query("mediaItems")
+            .withIndex("by_parent", (q) => q.eq("parentId", id))
+            .filter((q) => q.eq(q.field("deletedAt"), undefined))
+            .take(1);
+        const assets = await ctx.db
+            .query("mediaItems")
+            .withIndex("by_parent", (q) => q.eq("parentId", id))
+            .filter((q) => q.eq(q.field("deletedAt"), undefined))
+            .take(1);
+        const hasContents = subfolders.length > 0 || assets.length > 0;
+        if (hasContents && !recursive) {
+            throw mediaFolderHasContents(id, subfolders.length, assets.length);
+        }
+        // If recursive, delete all contents first
+        if (recursive && hasContents) {
+            await deleteContentsRecursively(ctx, id, hardDelete);
+        }
+        if (hardDelete) {
+            // Permanently delete the folder
+            await ctx.db.delete(id);
+            return {
+                ...folder,
+                deletedAt: Date.now(),
+            };
+        }
+        else {
+            // Soft delete
+            const now = Date.now();
+            await ctx.db.patch(id, {
+                deletedAt: now,
+            });
+            return {
+                ...folder,
+                deletedAt: now,
+            };
+        }
+    },
+});
+/**
+ * Recursively deletes all contents of a folder.
+ */
+async function deleteContentsRecursively(ctx, folderId, hardDelete) {
+    // Get all subfolders
+    const subfolders = await ctx.db
+        .query("mediaItems")
+        .withIndex("by_kind_and_parent", (q) => q.eq("kind", "folder").eq("parentId", folderId))
+        .filter((q) => q.eq(q.field("deletedAt"), undefined))
+        .collect();
+    // Recursively delete subfolders first
+    for (const subfolder of subfolders) {
+        await deleteContentsRecursively(ctx, subfolder._id, hardDelete);
+        if (hardDelete) {
+            await ctx.db.delete(subfolder._id);
+        }
+        else {
+            await ctx.db.patch(subfolder._id, { deletedAt: Date.now() });
+        }
+    }
+    // Delete/soft-delete all assets in this folder
+    const assets = await ctx.db
+        .query("mediaItems")
+        .withIndex("by_kind_and_parent", (q) => q.eq("kind", "asset").eq("parentId", folderId))
+        .filter((q) => q.eq(q.field("deletedAt"), undefined))
+        .collect();
+    for (const item of assets) {
+        // Type guard for asset (we already filtered by kind="asset" in the query)
+        if (item.kind !== "asset")
+            continue;
+        const asset = item;
+        if (hardDelete) {
+            // For hard delete, also delete the storage file
+            try {
+                await ctx.storage.delete(asset.storageId);
+            }
+            catch (error) {
+                console.warn(`Could not delete storage file for asset ${asset._id}:`, error instanceof Error ? error.message : error);
+            }
+            await ctx.db.delete(asset._id);
+        }
+        else {
+            await ctx.db.patch(asset._id, { deletedAt: Date.now() });
+        }
+    }
+}
+// =============================================================================
+// Restore Media Folder Mutation
+// =============================================================================
+/**
+ * Validator for restore folder arguments.
+ */
+export const restoreMediaFolderArgs = {
+    id: v.id("mediaItems"),
+    restoredBy: v.optional(v.string()),
+    recursive: v.optional(v.boolean()),
+};
+/**
+ * Mutation to restore a soft-deleted media folder.
+ *
+ * Removes the deletedAt timestamp from the folder.
+ * Optionally restores all contents recursively.
+ *
+ * @param id - The folder ID to restore
+ * @param restoredBy - Optional user ID for audit trail
+ * @param recursive - If true, restores folder and all contents
+ *
+ * @returns The restored media folder document
+ *
+ * @throws Error if the folder does not exist
+ * @throws Error if the folder is not deleted
+ * @throws Error if the parent folder is still deleted
+ *
+ * @example
+ * ```typescript
+ * const restored = await ctx.runMutation(api.mediaFolderMutations.restoreMediaFolder, {
+ *   id: folderId,
+ *   restoredBy: currentUserId,
+ *   recursive: true,
+ * });
+ * ```
+ */
+export const restoreMediaFolder = mutation({
+    args: {
+        ...restoreMediaFolderArgs,
+        /** Optional auth context for mutation-level authorization */
+        _auth: v.optional(mutationAuthContext),
+    },
+    returns: mediaItemDoc,
+    handler: async (ctx, args) => {
+        const { id, 
+        // restoredBy,
+        recursive = false, _auth } = args;
+        // Authorization check - use update permission for restore
+        requireMutationAuth(_auth, "mediaItems", "update");
+        const folder = await ctx.db.get(id);
+        if (!folder) {
+            throw mediaFolderNotFound(id);
+        }
+        if (!isDeleted(folder)) {
+            throw mediaFolderNotDeleted(id);
+        }
+        // Check that parent folder is not deleted (if it exists)
+        if (folder.parentId) {
+            const parentFolder = await ctx.db.get(folder.parentId);
+            if (parentFolder && isDeleted(parentFolder)) {
+                throw mediaFolderParentDeleted(id, folder.parentId);
+            }
+        }
+        // Restore the folder
+        await ctx.db.patch(id, {
+            deletedAt: undefined,
+        });
+        // If recursive, restore all contents
+        if (recursive) {
+            await restoreContentsRecursively(ctx, id);
+        }
+        // Retrieve and return the restored folder
+        const restoredFolder = await ctx.db.get(id);
+        if (!restoredFolder) {
+            throw internalError("Failed to restore media folder");
+        }
+        return restoredFolder;
+    },
+});
+/**
+ * Recursively restores all contents of a folder.
+ */
+async function restoreContentsRecursively(ctx, folderId) {
+    // Get all soft-deleted subfolders
+    const subfolders = await ctx.db
+        .query("mediaItems")
+        .withIndex("by_kind_and_parent", (q) => q.eq("kind", "folder").eq("parentId", folderId))
+        .filter((q) => q.neq(q.field("deletedAt"), undefined))
+        .collect();
+    for (const subfolder of subfolders) {
+        await ctx.db.patch(subfolder._id, { deletedAt: undefined });
+        await restoreContentsRecursively(ctx, subfolder._id);
+    }
+    // Restore all soft-deleted assets in this folder
+    const assets = await ctx.db
+        .query("mediaItems")
+        .withIndex("by_kind_and_parent", (q) => q.eq("kind", "asset").eq("parentId", folderId))
+        .filter((q) => q.neq(q.field("deletedAt"), undefined))
+        .collect();
+    for (const asset of assets) {
+        await ctx.db.patch(asset._id, { deletedAt: undefined });
+    }
+}
+// =============================================================================
+// Query Functions
+// =============================================================================
+/**
+ * Query to get a media folder by ID.
+ *
+ * @param id - The folder ID
+ * @param includeDeleted - If true, returns soft-deleted folders
+ *
+ * @returns The folder document or null if not found
+ */
+export const getMediaFolder = query({
+    args: {
+        id: v.id("mediaItems"),
+        includeDeleted: v.optional(v.boolean()),
+    },
+    returns: v.union(mediaItemDoc, v.null()),
+    handler: async (ctx, args) => {
+        const { id, includeDeleted = false } = args;
+        const item = await ctx.db.get(id);
+        // Must be a folder
+        if (!item || item.kind !== "folder") {
+            return null;
+        }
+        if (!includeDeleted && isDeleted(item)) {
+            return null;
+        }
+        return item;
+    },
+});
+/**
+ * Query to list folders in a parent folder.
+ *
+ * @param parentId - The parent folder ID (undefined for root folders)
+ * @param includeDeleted - If true, includes soft-deleted folders
+ * @param deletedOnly - If true, shows only soft-deleted folders (ignores parentId)
+ *
+ * @returns Array of folder documents sorted by sortOrder, then name
+ */
+export const listMediaFolders = query({
+    args: {
+        parentId: v.optional(v.id("mediaItems")),
+        includeDeleted: v.optional(v.boolean()),
+        deletedOnly: v.optional(v.boolean()),
+    },
+    returns: v.array(mediaItemDoc),
+    handler: async (ctx, args) => {
+        const { parentId, includeDeleted = false, deletedOnly = false } = args;
+        // When viewing trash (deletedOnly), show all deleted folders regardless of parent
+        let query = deletedOnly
+            ? ctx.db
+                .query("mediaItems")
+                .withIndex("by_kind", (q) => q.eq("kind", "folder"))
+            : ctx.db
+                .query("mediaItems")
+                .withIndex("by_kind_and_parent", (q) => q.eq("kind", "folder").eq("parentId", parentId));
+        if (deletedOnly) {
+            query = query.filter((q) => q.neq(q.field("deletedAt"), undefined));
+        }
+        else if (!includeDeleted) {
+            query = query.filter((q) => q.eq(q.field("deletedAt"), undefined));
+        }
+        const folders = await query.collect();
+        // Sort by sortOrder (nulls last), then by name
+        // Note: sortOrder is only defined on folders, so these are safe after kind filter
+        folders.sort((a, b) => {
+            const aOrder = a.kind === "folder" ? a.sortOrder : undefined;
+            const bOrder = b.kind === "folder" ? b.sortOrder : undefined;
+            if (aOrder !== undefined && bOrder !== undefined) {
+                return aOrder - bOrder;
+            }
+            if (aOrder !== undefined)
+                return -1;
+            if (bOrder !== undefined)
+                return 1;
+            return a.name.localeCompare(b.name);
+        });
+        return folders;
+    },
+});
+/**
+ * Query to get a folder by its path.
+ *
+ * @param path - The full folder path (e.g., "/Images/Blog")
+ * @param includeDeleted - If true, returns soft-deleted folders
+ *
+ * @returns The folder document or null if not found
+ */
+export const getMediaFolderByPath = query({
+    args: {
+        path: v.string(),
+        includeDeleted: v.optional(v.boolean()),
+    },
+    returns: v.union(mediaItemDoc, v.null()),
+    handler: async (ctx, args) => {
+        const { path, includeDeleted = false } = args;
+        let query = ctx.db
+            .query("mediaItems")
+            .withIndex("by_path", (q) => q.eq("path", path))
+            .filter((q) => q.eq(q.field("kind"), "folder"));
+        if (!includeDeleted) {
+            query = query.filter((q) => q.eq(q.field("deletedAt"), undefined));
+        }
+        return await query.first();
+    },
+});
+/**
+ * Query to get the folder tree (all folders as a flat list with hierarchy info).
+ *
+ * @param includeDeleted - If true, includes soft-deleted folders
+ *
+ * @returns Array of all folders
+ */
+export const getFolderTree = query({
+    args: {
+        includeDeleted: v.optional(v.boolean()),
+    },
+    returns: v.array(mediaItemDoc),
+    handler: async (ctx, args) => {
+        const { includeDeleted = false } = args;
+        let query = ctx.db
+            .query("mediaItems")
+            .withIndex("by_kind", (q) => q.eq("kind", "folder"));
+        if (!includeDeleted) {
+            query = query.filter((q) => q.eq(q.field("deletedAt"), undefined));
+        }
+        const folders = await query.collect();
+        // Sort by path for hierarchical display
+        folders.sort((a, b) => a.path.localeCompare(b.path));
+        return folders;
+    },
+});
+//# sourceMappingURL=mediaFolderMutations.js.map