convex-cms 0.0.1

package/dist/component/mediaVariantMutations.d.ts

@@ -0,0 +1,468 @@
+/**
+ * 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 type { Id } from "./_generated/dataModel.js";
+/**
+ * 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 declare const createMediaVariant: import("convex/server").RegisteredMutation<"public", {
+    width?: number | undefined;
+    height?: number | undefined;
+    createdBy?: string | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    autoGenerated?: boolean | undefined;
+    format: string;
+    storageId: import("convex/values").GenericId<"_storage">;
+    mimeType: string;
+    size: number;
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+}, Promise<{
+    url: string | null;
+    _id: import("convex/values").GenericId<"mediaVariants">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    errorMessage?: string | undefined;
+    processingStartedAt?: number | undefined;
+    processingCompletedAt?: number | undefined;
+    format: string;
+    storageId: import("convex/values").GenericId<"_storage">;
+    mimeType: string;
+    size: number;
+    status: "pending" | "processing" | "completed" | "failed";
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+    autoGenerated: boolean;
+}>>;
+/**
+ * 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 declare const requestVariantGeneration: import("convex/server").RegisteredMutation<"public", {
+    width?: number | undefined;
+    height?: number | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    requestedBy?: string | undefined;
+    format: string;
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+}, Promise<{
+    _id: import("convex/values").GenericId<"mediaVariants">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    errorMessage?: string | undefined;
+    processingStartedAt?: number | undefined;
+    processingCompletedAt?: number | undefined;
+    format: string;
+    storageId: import("convex/values").GenericId<"_storage">;
+    mimeType: string;
+    size: number;
+    status: "pending" | "processing" | "completed" | "failed";
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+    autoGenerated: boolean;
+}>>;
+/**
+ * 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 declare const updateVariantStatus: import("convex/server").RegisteredMutation<"public", {
+    storageId?: import("convex/values").GenericId<"_storage"> | undefined;
+    mimeType?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    size?: number | undefined;
+    errorMessage?: string | undefined;
+    id: import("convex/values").GenericId<"mediaVariants">;
+    status: "pending" | "processing" | "completed" | "failed";
+}, Promise<{
+    _id: import("convex/values").GenericId<"mediaVariants">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    errorMessage?: string | undefined;
+    processingStartedAt?: number | undefined;
+    processingCompletedAt?: number | undefined;
+    format: string;
+    storageId: import("convex/values").GenericId<"_storage">;
+    mimeType: string;
+    size: number;
+    status: "pending" | "processing" | "completed" | "failed";
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+    autoGenerated: boolean;
+}>>;
+/**
+ * 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 declare const deleteMediaVariant: import("convex/server").RegisteredMutation<"public", {
+    hardDelete?: boolean | undefined;
+    deletedBy?: string | undefined;
+    id: import("convex/values").GenericId<"mediaVariants">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"mediaVariants">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    errorMessage?: string | undefined;
+    processingStartedAt?: number | undefined;
+    processingCompletedAt?: number | undefined;
+    format: string;
+    storageId: import("convex/values").GenericId<"_storage">;
+    mimeType: string;
+    size: number;
+    status: "pending" | "processing" | "completed" | "failed";
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+    autoGenerated: boolean;
+}>>;
+/**
+ * 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 declare const deleteAssetVariants: import("convex/server").RegisteredMutation<"public", {
+    hardDelete?: boolean | undefined;
+    deletedBy?: string | undefined;
+    assetId: import("convex/values").GenericId<"mediaItems">;
+}, Promise<{
+    deleted: number;
+    assetId: import("convex/values").GenericId<"mediaItems">;
+}>>;
+/**
+ * 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 declare const generateFromPresets: import("convex/server").RegisteredMutation<"public", {
+    requestedBy?: string | undefined;
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    presets: string[];
+}, Promise<{
+    total: number;
+    succeeded: number;
+    failed: number;
+    results: {
+        variantId: Id<"mediaVariants"> | undefined;
+        preset: string;
+        success: boolean;
+        error?: string;
+    }[];
+}>>;
+/**
+ * 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 declare const restoreMediaVariant: import("convex/server").RegisteredMutation<"public", {
+    restoredBy?: string | undefined;
+    id: import("convex/values").GenericId<"mediaVariants">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"mediaVariants">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    errorMessage?: string | undefined;
+    processingStartedAt?: number | undefined;
+    processingCompletedAt?: number | undefined;
+    format: string;
+    storageId: import("convex/values").GenericId<"_storage">;
+    mimeType: string;
+    size: number;
+    status: "pending" | "processing" | "completed" | "failed";
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+    autoGenerated: boolean;
+}>>;
+/**
+ * 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 declare const markVariantProcessing: import("convex/server").RegisteredMutation<"internal", {
+    id: import("convex/values").GenericId<"mediaVariants">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"mediaVariants">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    errorMessage?: string | undefined;
+    processingStartedAt?: number | undefined;
+    processingCompletedAt?: number | undefined;
+    format: string;
+    storageId: import("convex/values").GenericId<"_storage">;
+    mimeType: string;
+    size: number;
+    status: "pending" | "processing" | "completed" | "failed";
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+    autoGenerated: boolean;
+} | null>>;
+/**
+ * Internal mutation to complete a variant after processing.
+ */
+export declare const completeVariant: import("convex/server").RegisteredMutation<"internal", {
+    width?: number | undefined;
+    height?: number | undefined;
+    id: import("convex/values").GenericId<"mediaVariants">;
+    storageId: import("convex/values").GenericId<"_storage">;
+    size: number;
+}, Promise<{
+    _id: import("convex/values").GenericId<"mediaVariants">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    errorMessage?: string | undefined;
+    processingStartedAt?: number | undefined;
+    processingCompletedAt?: number | undefined;
+    format: string;
+    storageId: import("convex/values").GenericId<"_storage">;
+    mimeType: string;
+    size: number;
+    status: "pending" | "processing" | "completed" | "failed";
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+    autoGenerated: boolean;
+}>>;
+/**
+ * Internal mutation to mark a variant as failed.
+ */
+export declare const failVariant: import("convex/server").RegisteredMutation<"internal", {
+    id: import("convex/values").GenericId<"mediaVariants">;
+    errorMessage: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"mediaVariants">;
+    _creationTime: number;
+    width?: number | undefined;
+    height?: number | undefined;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    quality?: number | undefined;
+    preset?: string | undefined;
+    errorMessage?: string | undefined;
+    processingStartedAt?: number | undefined;
+    processingCompletedAt?: number | undefined;
+    format: string;
+    storageId: import("convex/values").GenericId<"_storage">;
+    mimeType: string;
+    size: number;
+    status: "pending" | "processing" | "completed" | "failed";
+    assetId: import("convex/values").GenericId<"mediaItems">;
+    variantType: "thumbnail" | "responsive" | "format";
+    autoGenerated: boolean;
+}>>;
+//# sourceMappingURL=mediaVariantMutations.d.ts.map

package/dist/component/mediaVariantMutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaVariantMutations.d.ts","sourceRoot":"","sources":["../../src/component/mediaVariantMutations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,2BAA2B,CAAC;AAsBpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyG7B,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGnC,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6C9B,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;GA8B7B,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;GAuC9B,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;gBA2BrB,MAAM;iBACL,OAAO;gBAER,MAAM;;GA+Gf,CAAC;AAMH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;GAyC9B,CAAC;AAMH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;UAoBhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;GAiC1B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;GA2BtB,CAAC"}