convex-cms 0.0.2 → 0.0.3

package/src/component/mediaFolderMutations.ts

@@ -1,1046 +0,0 @@
-/**
- * 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, type MutationCtx } from "./_generated/server.js";
-import type { Id } from "./_generated/dataModel.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: string): void {
-	// 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: string, parentPath: string): string {
-	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: string): number {
-	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 as unknown) as string);
-			}
-
-			if (isDeleted(parentFolder)) {
-				throw mediaFolderDeleted((parentId as unknown) as string);
-			}
-
-			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 as unknown) as string);
-		}
-
-		if (isDeleted(folder)) {
-			throw mediaFolderDeleted((id as unknown) as string);
-		}
-
-		// Build updates object
-		const updates: Record<string, unknown> = {};
-
-		// 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: MutationCtx,
-	oldParentPath: string,
-	newParentPath: string,
-): Promise<void> {
-	// 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 as unknown) as string);
-		}
-
-		if (isDeleted(folder)) {
-			throw mediaFolderDeleted((id as unknown) as string);
-		}
-
-		// 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 as unknown) as string);
-			}
-
-			if (isDeleted(newParentFolder)) {
-				throw mediaFolderDeleted((newParentId as unknown) as string);
-			}
-
-			// 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 as unknown) as string);
-			}
-
-			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: MutationCtx,
-	folderPath: string,
-): Promise<number> {
-	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 as unknown) as string);
-		}
-
-		// For soft delete, check if already deleted
-		if (!hardDelete && isDeleted(folder)) {
-			throw mediaFolderDeleted((id as unknown) as string);
-		}
-
-		// 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 as unknown) as string,
-				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: MutationCtx,
-	folderId: Id<"mediaItems">,
-	hardDelete: boolean,
-): Promise<void> {
-	// 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 as unknown) as string);
-		}
-
-		if (!isDeleted(folder)) {
-			throw mediaFolderNotDeleted((id as unknown) as string);
-		}
-
-		// 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 as unknown) as string,
-					(folder.parentId as unknown) as string,
-				);
-			}
-		}
-
-		// 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: MutationCtx,
-	folderId: Id<"mediaItems">,
-): Promise<void> {
-	// 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;
-	},
-});