convex-cms 0.0.1

package/dist/component/mediaVariantMutations.js

@@ -0,0 +1,737 @@
+/**
+ * Media Variant Mutation Functions
+ *
+ * Provides mutation functions for creating, updating, and deleting media variants.
+ * Variants are optimized versions of media assets (thumbnails, responsive sizes,
+ * format conversions).
+ *
+ * Key operations:
+ * - Create variant: Register a completed variant after external processing
+ * - Request generation: Queue a variant for async processing
+ * - Update status: Update processing status (for job queue integration)
+ * - Delete variant: Soft or hard delete variants
+ * - Bulk operations: Generate multiple variants from presets
+ */
+import { v } from "convex/values";
+import { isDeleted } from "./lib/softDelete.js";
+import { mutation, internalMutation } from "./_generated/server.js";
+import { createMediaVariantArgs, requestVariantGenerationArgs, updateVariantStatusArgs, deleteMediaVariantArgs, deleteAssetVariantsArgs, mediaVariantDoc, mediaVariantWithUrlDoc, 
+// variantTypeValidator,
+// variantStatusValidator,
+generateVariantsResult, } from "./validators.js";
+import { classifyMimeType } from "./lib/metadataExtractor.js";
+import { emitEvent } from "./eventEmitter.js";
+import { DEFAULT_VARIANT_PRESETS } from "./mediaVariants.js";
+// =============================================================================
+// Create Variant (completed)
+// =============================================================================
+/**
+ * Mutation to create a media variant that has already been processed.
+ *
+ * Use this when variant processing happens externally (e.g., in a serverless
+ * function or image processing service) and you need to register the
+ * completed variant in the CMS.
+ *
+ * @param assetId - Parent media asset ID
+ * @param storageId - Storage ID of the variant file
+ * @param variantType - Type of variant (thumbnail, responsive, format)
+ * @param width - Width in pixels
+ * @param height - Height in pixels
+ * @param format - Output format (webp, avif, jpeg, etc.)
+ * @param mimeType - MIME type of the variant
+ * @param size - File size in bytes
+ * @param quality - Quality setting used (0-100)
+ * @param preset - Named preset if applicable
+ * @param autoGenerated - Whether this was auto-generated
+ * @param createdBy - User ID who created this variant
+ * @returns The created variant document with URL
+ *
+ * @example
+ * ```typescript
+ * // After processing an image externally and uploading the result
+ * const variant = await ctx.runMutation(api.mediaVariantMutations.createMediaVariant, {
+ *   assetId: assetId,
+ *   storageId: uploadedStorageId,
+ *   variantType: "responsive",
+ *   width: 480,
+ *   height: 320,
+ *   format: "webp",
+ *   mimeType: "image/webp",
+ *   size: 25600,
+ *   quality: 80,
+ *   preset: "small",
+ *   autoGenerated: true,
+ * });
+ * ```
+ */
+export const createMediaVariant = mutation({
+    args: createMediaVariantArgs.fields,
+    returns: mediaVariantWithUrlDoc,
+    handler: async (ctx, args) => {
+        const { assetId, storageId, variantType, width, height, format, mimeType, size, quality, preset, autoGenerated = false, createdBy, } = args;
+        // Validate parent asset exists and is not deleted
+        const item = await ctx.db.get(assetId);
+        if (!item || item.kind !== "asset") {
+            throw new Error(`Media asset not found: ${assetId}`);
+        }
+        if (isDeleted(item)) {
+            throw new Error(`Cannot create variant for deleted asset: ${assetId}`);
+        }
+        const asset = item;
+        // Check for duplicate variant (same dimensions, format, and preset)
+        const existingVariants = await ctx.db
+            .query("mediaVariants")
+            .withIndex("by_asset", (q) => q.eq("assetId", assetId))
+            .filter((q) => q.and(q.eq(q.field("variantType"), variantType), q.eq(q.field("width"), width), q.eq(q.field("height"), height), q.eq(q.field("format"), format), q.eq(q.field("deletedAt"), undefined)))
+            .first();
+        if (existingVariants) {
+            throw new Error(`Variant already exists for asset ${assetId} with type=${variantType}, ` +
+                `dimensions=${width}x${height}, format=${format}`);
+        }
+        // Create the variant record
+        const variantId = await ctx.db.insert("mediaVariants", {
+            assetId,
+            storageId,
+            variantType,
+            width,
+            height,
+            format,
+            mimeType,
+            size,
+            quality,
+            preset,
+            autoGenerated,
+            status: "completed",
+            processingCompletedAt: Date.now(),
+            createdBy,
+        });
+        // Get the created variant
+        const variant = await ctx.db.get(variantId);
+        if (!variant) {
+            throw new Error("Failed to create variant");
+        }
+        // Resolve URL
+        const url = await ctx.storage.getUrl(storageId);
+        // Emit event
+        await emitEvent(ctx, {
+            eventType: "mediaAsset.updated",
+            resourceType: "mediaAsset",
+            resourceId: assetId.toString(),
+            action: "updated",
+            payload: {
+                name: asset.name,
+                mimeType: asset.mimeType,
+                type: classifyMimeType(asset.mimeType),
+                size: asset.size ?? 0,
+            },
+            userId: createdBy,
+            metadata: {
+                variantCreated: true,
+                variantId: variantId.toString(),
+                variantType,
+                variantFormat: format,
+                variantPreset: preset,
+            },
+        });
+        return {
+            ...variant,
+            url,
+        };
+    },
+});
+// =============================================================================
+// Request Variant Generation
+// =============================================================================
+/**
+ * Mutation to request async generation of a variant.
+ *
+ * Creates a variant record with "pending" status. An external processing
+ * system should pick up pending variants, process them, upload the result,
+ * and update the status to "completed".
+ *
+ * @param assetId - Parent media asset ID
+ * @param variantType - Type of variant to generate
+ * @param width - Target width (optional)
+ * @param height - Target height (optional)
+ * @param format - Output format
+ * @param quality - Quality setting (0-100)
+ * @param preset - Named preset to use
+ * @param requestedBy - User ID requesting the variant
+ * @returns The created variant document (pending status)
+ *
+ * @example
+ * ```typescript
+ * // Request a thumbnail variant be generated
+ * const pendingVariant = await ctx.runMutation(api.mediaVariantMutations.requestVariantGeneration, {
+ *   assetId: assetId,
+ *   variantType: "thumbnail",
+ *   width: 150,
+ *   height: 150,
+ *   format: "webp",
+ *   quality: 80,
+ *   preset: "thumbnail",
+ * });
+ *
+ * // The variant now has status: "pending"
+ * // An external processor should pick it up and generate the image
+ * ```
+ */
+export const requestVariantGeneration = mutation({
+    args: requestVariantGenerationArgs.fields,
+    returns: mediaVariantDoc,
+    handler: async (ctx, args) => {
+        const { assetId, variantType, width, height, format, quality, preset, requestedBy, } = args;
+        // Validate parent asset exists and is not deleted
+        const item = await ctx.db.get(assetId);
+        if (!item || item.kind !== "asset") {
+            throw new Error(`Media asset not found: ${assetId}`);
+        }
+        if (isDeleted(item)) {
+            throw new Error(`Cannot create variant for deleted asset: ${assetId}`);
+        }
+        const asset = item;
+        // Validate asset is an image (variants only make sense for images)
+        const assetType = classifyMimeType(asset.mimeType);
+        if (assetType !== "image") {
+            throw new Error(`Variants can only be generated for images. Asset type: ${assetType}`);
+        }
+        // Check for existing pending/processing variant with same parameters
+        const existingPending = await ctx.db
+            .query("mediaVariants")
+            .withIndex("by_asset", (q) => q.eq("assetId", assetId))
+            .filter((q) => q.and(q.eq(q.field("variantType"), variantType), q.eq(q.field("width"), width), q.eq(q.field("height"), height), q.eq(q.field("format"), format), q.or(q.eq(q.field("status"), "pending"), q.eq(q.field("status"), "processing"))))
+            .first();
+        if (existingPending) {
+            // Return existing pending variant instead of creating duplicate
+            return existingPending;
+        }
+        // Check for existing completed variant
+        const existingCompleted = await ctx.db
+            .query("mediaVariants")
+            .withIndex("by_asset", (q) => q.eq("assetId", assetId))
+            .filter((q) => q.and(q.eq(q.field("variantType"), variantType), q.eq(q.field("width"), width), q.eq(q.field("height"), height), q.eq(q.field("format"), format), q.eq(q.field("status"), "completed"), q.eq(q.field("deletedAt"), undefined)))
+            .first();
+        if (existingCompleted) {
+            // Variant already exists, return it
+            return existingCompleted;
+        }
+        // Create placeholder storage ID (will be updated when processing completes)
+        // For pending variants, we use a placeholder that will be replaced
+        const variantId = await ctx.db.insert("mediaVariants", {
+            assetId,
+            storageId: asset.storageId, // Placeholder - will be replaced
+            variantType,
+            width,
+            height,
+            format,
+            mimeType: getMimeTypeFromFormat(format),
+            size: 0, // Unknown until processed
+            quality,
+            preset,
+            autoGenerated: true,
+            status: "pending",
+            createdBy: requestedBy,
+        });
+        const variant = await ctx.db.get(variantId);
+        if (!variant) {
+            throw new Error("Failed to create pending variant");
+        }
+        return variant;
+    },
+});
+// =============================================================================
+// Update Variant Status
+// =============================================================================
+/**
+ * Mutation to update the status of a variant during processing.
+ *
+ * Used by the processing system to:
+ * - Mark a variant as "processing" when it starts
+ * - Mark as "completed" with final storage ID and dimensions
+ * - Mark as "failed" with error message
+ *
+ * @param id - Variant ID to update
+ * @param status - New status
+ * @param storageId - Storage ID of completed variant
+ * @param size - Final file size
+ * @param mimeType - Final MIME type
+ * @param width - Final width
+ * @param height - Final height
+ * @param errorMessage - Error message if failed
+ * @returns Updated variant document
+ *
+ * @example
+ * ```typescript
+ * // Mark as processing
+ * await ctx.runMutation(api.mediaVariantMutations.updateVariantStatus, {
+ *   id: variantId,
+ *   status: "processing",
+ * });
+ *
+ * // ... process the image ...
+ *
+ * // Mark as completed
+ * await ctx.runMutation(api.mediaVariantMutations.updateVariantStatus, {
+ *   id: variantId,
+ *   status: "completed",
+ *   storageId: processedStorageId,
+ *   size: 25600,
+ *   width: 480,
+ *   height: 320,
+ * });
+ * ```
+ */
+export const updateVariantStatus = mutation({
+    args: updateVariantStatusArgs.fields,
+    returns: mediaVariantDoc,
+    handler: async (ctx, args) => {
+        const { id, status, storageId, size, mimeType, width, height, errorMessage, } = args;
+        const variant = await ctx.db.get(id);
+        if (!variant) {
+            throw new Error(`Variant not found: ${id}`);
+        }
+        const updates = { status };
+        if (status === "processing") {
+            updates.processingStartedAt = Date.now();
+        }
+        else if (status === "completed") {
+            updates.processingCompletedAt = Date.now();
+            if (storageId)
+                updates.storageId = storageId;
+            if (size !== undefined)
+                updates.size = size;
+            if (mimeType)
+                updates.mimeType = mimeType;
+            if (width !== undefined)
+                updates.width = width;
+            if (height !== undefined)
+                updates.height = height;
+        }
+        else if (status === "failed") {
+            updates.processingCompletedAt = Date.now();
+            if (errorMessage)
+                updates.errorMessage = errorMessage;
+        }
+        await ctx.db.patch(id, updates);
+        const updatedVariant = await ctx.db.get(id);
+        if (!updatedVariant) {
+            throw new Error("Failed to update variant");
+        }
+        return updatedVariant;
+    },
+});
+// =============================================================================
+// Delete Variant
+// =============================================================================
+/**
+ * Mutation to delete a media variant.
+ *
+ * Supports soft delete (default) and hard delete.
+ * Hard delete also removes the storage file.
+ *
+ * @param id - Variant ID to delete
+ * @param hardDelete - If true, permanently delete and remove storage file
+ * @param deletedBy - User ID performing the deletion
+ * @returns Deleted variant document
+ *
+ * @example
+ * ```typescript
+ * // Soft delete (can be recovered)
+ * await ctx.runMutation(api.mediaVariantMutations.deleteMediaVariant, {
+ *   id: variantId,
+ * });
+ *
+ * // Hard delete (permanent)
+ * await ctx.runMutation(api.mediaVariantMutations.deleteMediaVariant, {
+ *   id: variantId,
+ *   hardDelete: true,
+ * });
+ * ```
+ */
+export const deleteMediaVariant = mutation({
+    args: deleteMediaVariantArgs.fields,
+    returns: mediaVariantDoc,
+    handler: async (ctx, args) => {
+        const { id, hardDelete = false } = args;
+        const variant = await ctx.db.get(id);
+        if (!variant) {
+            throw new Error(`Variant not found: ${id}`);
+        }
+        if (hardDelete) {
+            // Delete storage file if it's not a placeholder
+            if (variant.status === "completed") {
+                try {
+                    await ctx.storage.delete(variant.storageId);
+                }
+                catch {
+                    // Storage file might already be deleted
+                }
+            }
+            // Hard delete the variant record
+            await ctx.db.delete(id);
+        }
+        else {
+            // Soft delete
+            await ctx.db.patch(id, { deletedAt: Date.now() });
+        }
+        return variant;
+    },
+});
+// =============================================================================
+// Delete All Variants for Asset
+// =============================================================================
+/**
+ * Mutation to delete all variants for a media asset.
+ *
+ * Useful when deleting the parent asset or when regenerating
+ * all variants from scratch.
+ *
+ * @param assetId - Parent asset ID
+ * @param hardDelete - If true, permanently delete and remove storage files
+ * @param deletedBy - User ID performing the deletion
+ * @returns Summary of deleted variants
+ *
+ * @example
+ * ```typescript
+ * // Soft delete all variants
+ * const result = await ctx.runMutation(api.mediaVariantMutations.deleteAssetVariants, {
+ *   assetId: assetId,
+ * });
+ * console.log(`Deleted ${result.deleted} variants`);
+ *
+ * // Hard delete all variants
+ * await ctx.runMutation(api.mediaVariantMutations.deleteAssetVariants, {
+ *   assetId: assetId,
+ *   hardDelete: true,
+ * });
+ * ```
+ */
+export const deleteAssetVariants = mutation({
+    args: deleteAssetVariantsArgs.fields,
+    returns: v.object({
+        deleted: v.number(),
+        assetId: v.id("mediaItems"),
+    }),
+    handler: async (ctx, args) => {
+        const { assetId, hardDelete = false } = args;
+        const variants = await ctx.db
+            .query("mediaVariants")
+            .withIndex("by_asset", (q) => q.eq("assetId", assetId))
+            .filter((q) => q.eq(q.field("deletedAt"), undefined))
+            .collect();
+        let deletedCount = 0;
+        for (const variant of variants) {
+            if (hardDelete) {
+                // Delete storage file
+                if (variant.status === "completed") {
+                    try {
+                        await ctx.storage.delete(variant.storageId);
+                    }
+                    catch {
+                        // Storage file might already be deleted
+                    }
+                }
+                await ctx.db.delete(variant._id);
+            }
+            else {
+                await ctx.db.patch(variant._id, { deletedAt: Date.now() });
+            }
+            deletedCount++;
+        }
+        return {
+            deleted: deletedCount,
+            assetId,
+        };
+    },
+});
+// =============================================================================
+// Generate Variants from Presets
+// =============================================================================
+/**
+ * Mutation to request generation of multiple variants from presets.
+ *
+ * Creates pending variant records for each preset. An external processor
+ * should pick up and process these variants.
+ *
+ * @param assetId - Parent asset ID
+ * @param presets - Array of preset names to generate
+ * @param requestedBy - User ID requesting the variants
+ * @returns Summary of created variant requests
+ *
+ * @example
+ * ```typescript
+ * // Generate thumbnail and responsive sizes
+ * const result = await ctx.runMutation(api.mediaVariantMutations.generateFromPresets, {
+ *   assetId: assetId,
+ *   presets: ["thumbnail", "small", "medium", "large"],
+ * });
+ *
+ * console.log(`Queued ${result.succeeded} variants for processing`);
+ * ```
+ */
+export const generateFromPresets = mutation({
+    args: {
+        assetId: v.id("mediaItems"),
+        presets: v.array(v.string()),
+        requestedBy: v.optional(v.string()),
+    },
+    returns: generateVariantsResult,
+    handler: async (ctx, args) => {
+        const { assetId, presets, requestedBy } = args;
+        // Validate asset exists and is an image
+        const item = await ctx.db.get(assetId);
+        if (!item || item.kind !== "asset") {
+            throw new Error(`Media asset not found: ${assetId}`);
+        }
+        if (isDeleted(item)) {
+            throw new Error(`Cannot generate variants for deleted asset: ${assetId}`);
+        }
+        const asset = item;
+        const assetMediaType = classifyMimeType(asset.mimeType);
+        if (assetMediaType !== "image") {
+            throw new Error(`Variants can only be generated for images. Asset type: ${assetMediaType}`);
+        }
+        const results = [];
+        for (const presetName of presets) {
+            const preset = DEFAULT_VARIANT_PRESETS[presetName];
+            if (!preset) {
+                results.push({
+                    preset: presetName,
+                    success: false,
+                    error: `Unknown preset: ${presetName}`,
+                });
+                continue;
+            }
+            try {
+                // Check for existing variant
+                const existing = await ctx.db
+                    .query("mediaVariants")
+                    .withIndex("by_asset_and_preset", (q) => q.eq("assetId", assetId).eq("preset", presetName))
+                    .filter((q) => q.and(q.eq(q.field("deletedAt"), undefined), q.or(q.eq(q.field("status"), "pending"), q.eq(q.field("status"), "processing"), q.eq(q.field("status"), "completed"))))
+                    .first();
+                if (existing) {
+                    results.push({
+                        preset: presetName,
+                        success: true,
+                        variantId: existing._id,
+                    });
+                    continue;
+                }
+                // Create pending variant
+                const variantId = await ctx.db.insert("mediaVariants", {
+                    assetId,
+                    storageId: asset.storageId, // Placeholder
+                    variantType: preset.variantType,
+                    width: "width" in preset ? preset.width : undefined,
+                    height: "height" in preset ? preset.height : undefined,
+                    format: preset.format,
+                    mimeType: getMimeTypeFromFormat(preset.format),
+                    size: 0,
+                    quality: preset.quality,
+                    preset: presetName,
+                    autoGenerated: true,
+                    status: "pending",
+                    createdBy: requestedBy,
+                });
+                results.push({
+                    preset: presetName,
+                    success: true,
+                    variantId,
+                });
+            }
+            catch (error) {
+                results.push({
+                    preset: presetName,
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        const succeeded = results.filter((r) => r.success).length;
+        const failed = results.filter((r) => !r.success).length;
+        // Emit event for bulk variant generation request
+        await emitEvent(ctx, {
+            eventType: "mediaAsset.updated",
+            resourceType: "mediaAsset",
+            resourceId: assetId.toString(),
+            action: "updated",
+            payload: {
+                name: asset.name,
+                mimeType: asset.mimeType,
+                type: classifyMimeType(asset.mimeType),
+                size: asset.size ?? 0,
+            },
+            userId: requestedBy,
+            metadata: {
+                variantsRequested: true,
+                presetsRequested: presets,
+                succeeded,
+                failed,
+            },
+        });
+        return {
+            total: presets.length,
+            succeeded,
+            failed,
+            results: results.map((r) => ({
+                ...r,
+                variantId: r.variantId ? r.variantId : undefined,
+            })),
+        };
+    },
+});
+// =============================================================================
+// Restore Variant (undo soft delete)
+// =============================================================================
+/**
+ * Mutation to restore a soft-deleted variant.
+ *
+ * @param id - Variant ID to restore
+ * @param restoredBy - User ID performing the restoration
+ * @returns Restored variant document
+ *
+ * @example
+ * ```typescript
+ * await ctx.runMutation(api.mediaVariantMutations.restoreMediaVariant, {
+ *   id: variantId,
+ *   restoredBy: userId,
+ * });
+ * ```
+ */
+export const restoreMediaVariant = mutation({
+    args: {
+        id: v.id("mediaVariants"),
+        restoredBy: v.optional(v.string()),
+    },
+    returns: mediaVariantDoc,
+    handler: async (ctx, args) => {
+        const { id } = args;
+        const variant = await ctx.db.get(id);
+        if (!variant) {
+            throw new Error(`Variant not found: ${id}`);
+        }
+        if (!isDeleted(variant)) {
+            // Already restored, return as-is
+            return variant;
+        }
+        // Verify parent asset is not deleted
+        const asset = await ctx.db.get(variant.assetId);
+        if (!asset) {
+            throw new Error(`Cannot restore variant: parent asset not found: ${variant.assetId}`);
+        }
+        if (isDeleted(asset)) {
+            throw new Error(`Cannot restore variant: parent asset is deleted: ${variant.assetId}`);
+        }
+        await ctx.db.patch(id, { deletedAt: undefined });
+        const restoredVariant = await ctx.db.get(id);
+        if (!restoredVariant) {
+            throw new Error("Failed to restore variant");
+        }
+        return restoredVariant;
+    },
+});
+// =============================================================================
+// Internal: Process Pending Variant
+// =============================================================================
+/**
+ * Internal mutation for the processing system to mark a variant as processing.
+ *
+ * This is called when a processor picks up a pending variant from the queue.
+ */
+export const markVariantProcessing = internalMutation({
+    args: {
+        id: v.id("mediaVariants"),
+    },
+    returns: v.union(mediaVariantDoc, v.null()),
+    handler: async (ctx, args) => {
+        const { id } = args;
+        const variant = await ctx.db.get(id);
+        if (!variant || variant.status !== "pending") {
+            return null;
+        }
+        await ctx.db.patch(id, {
+            status: "processing",
+            processingStartedAt: Date.now(),
+        });
+        return await ctx.db.get(id);
+    },
+});
+/**
+ * Internal mutation to complete a variant after processing.
+ */
+export const completeVariant = internalMutation({
+    args: {
+        id: v.id("mediaVariants"),
+        storageId: v.id("_storage"),
+        size: v.number(),
+        width: v.optional(v.number()),
+        height: v.optional(v.number()),
+    },
+    returns: mediaVariantDoc,
+    handler: async (ctx, args) => {
+        const { id, storageId, size, width, height } = args;
+        const variant = await ctx.db.get(id);
+        if (!variant) {
+            throw new Error(`Variant not found: ${id}`);
+        }
+        await ctx.db.patch(id, {
+            status: "completed",
+            storageId,
+            size,
+            width: width ?? variant.width,
+            height: height ?? variant.height,
+            processingCompletedAt: Date.now(),
+        });
+        const completed = await ctx.db.get(id);
+        if (!completed) {
+            throw new Error("Failed to complete variant");
+        }
+        return completed;
+    },
+});
+/**
+ * Internal mutation to mark a variant as failed.
+ */
+export const failVariant = internalMutation({
+    args: {
+        id: v.id("mediaVariants"),
+        errorMessage: v.string(),
+    },
+    returns: mediaVariantDoc,
+    handler: async (ctx, args) => {
+        const { id, errorMessage } = args;
+        const variant = await ctx.db.get(id);
+        if (!variant) {
+            throw new Error(`Variant not found: ${id}`);
+        }
+        await ctx.db.patch(id, {
+            status: "failed",
+            errorMessage,
+            processingCompletedAt: Date.now(),
+        });
+        const failed = await ctx.db.get(id);
+        if (!failed) {
+            throw new Error("Failed to update variant");
+        }
+        return failed;
+    },
+});
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get MIME type from format string.
+ */
+function getMimeTypeFromFormat(format) {
+    const mimeTypes = {
+        jpeg: "image/jpeg",
+        jpg: "image/jpeg",
+        png: "image/png",
+        webp: "image/webp",
+        avif: "image/avif",
+        gif: "image/gif",
+        svg: "image/svg+xml",
+    };
+    return mimeTypes[format.toLowerCase()] || `image/${format}`;
+}
+//# sourceMappingURL=mediaVariantMutations.js.map