@od-oneapp/storage 2026.1.1301

package/src/actions/productMediaActions.ts

@@ -0,0 +1,538 @@
+/**
+ * @fileoverview Product media business logic server actions
+ *
+ * Provides Next.js server actions specifically for product media operations.
+ * Includes business logic for product image management with vendor and admin contexts.
+ *
+ * Features:
+ * - Product-specific media uploads
+ * - Vendor and admin role support
+ * - Product media metadata management
+ * - Authorization checks
+ *
+ * @module @repo/storage/actions/productMediaActions
+ */
+
+'use server';
+
+import { safeEnv } from '../../env';
+import { sanitizeStorageKey, validateStorageKey } from '../../keys';
+import { canUserManageProduct, checkRateLimit, getSession } from '../auth-helpers';
+import { STORAGE_CONSTANTS } from '../constants';
+import { getStorage } from '../server';
+
+import type { MediaActionResponse } from '../../types';
+
+//==============================================================================
+// PRODUCT MEDIA BUSINESS LOGIC ACTIONS
+//==============================================================================
+
+/**
+ * Uploads multiple media files for a product while enforcing optional authentication, authorization, and rate limits.
+ *
+ * @param productId - The ID of the product to attach media to.
+ * @param files - Files to upload; each object must include `filename`, `contentType`, and binary `data`.
+ * @param options - Optional settings: `context` is the uploader role (`admin` | `vendor`); `altText`, `description`, and `tags` supply metadata.
+ * @returns The action response. On success, `data` is an array of uploaded items containing `key`, `url`, and a temporary `mediaId`; on failure, `error` describes the problem.
+ */
+export async function uploadProductMediaAction(
+  productId: string,
+  files: Array<{
+    filename: string;
+    contentType: string;
+    data: ArrayBuffer | Blob | Buffer | File;
+  }>,
+  options?: {
+    context: 'admin' | 'vendor';
+    altText?: string;
+    description?: string;
+    tags?: string[];
+  },
+): Promise<MediaActionResponse<Array<{ key: string; url: string; mediaId: string }>>> {
+  'use server';
+
+  try {
+    // Authentication check (configurable)
+    const featureEnv = safeEnv();
+    const session = await getSession();
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !session?.user) {
+      return {
+        success: false,
+        error: 'Unauthorized: Authentication required',
+      };
+    }
+
+    // Permission check for product access (only when auth enforced)
+    const hasPermission = session?.user
+      ? await canUserManageProduct(session.user.id, productId)
+      : false;
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !hasPermission) {
+      return {
+        success: false,
+        error: 'Forbidden: Insufficient permissions',
+      };
+    }
+
+    // Rate limiting
+    const env = safeEnv();
+    const rateLimitResult = await checkRateLimit(
+      session?.user?.id ?? 'anonymous',
+      'storage:upload',
+      env.STORAGE_RATE_LIMIT_REQUESTS,
+      env.STORAGE_RATE_LIMIT_WINDOW_MS,
+    );
+    if (env.STORAGE_ENABLE_RATE_LIMIT && !rateLimitResult.allowed) {
+      return {
+        success: false,
+        error: 'Rate limit exceeded. Please try again later.',
+      };
+    }
+
+    const storage = getStorage();
+    const results = [];
+
+    for (const [index, file] of files.entries()) {
+      // Sanitize filename to prevent path traversal attacks
+      const sanitizedFilename = sanitizeStorageKey(file.filename);
+
+      // Generate storage key with sanitized filename
+      const timestamp = Date.now();
+      const key = `products/${productId}/images/${timestamp}-${index}-${sanitizedFilename}`;
+
+      // Validate storage key to prevent path traversal
+      const keyValidation = validateStorageKey(key, {
+        maxLength: 1024,
+        forbiddenPatterns: [/\.\./, /\/\//],
+      });
+      if (!keyValidation.valid) {
+        return {
+          success: false,
+          error: `Invalid storage key: ${keyValidation.errors.join(', ')}`,
+        };
+      }
+
+      // Upload to storage
+      const uploadResult = await storage.upload(key, file.data, {
+        contentType: file.contentType,
+        metadata: {
+          productId,
+          uploadedBy: options?.context ?? 'admin',
+          altText: options?.altText ?? '',
+        },
+      });
+
+      // TODO: Create database record
+      // const mediaRecord = await createProductMediaRecord({
+      //   productId,
+      //   key,
+      //   url: uploadResult.url,
+      //   filename: file.filename,
+      //   contentType: file.contentType,
+      //   size: uploadResult.size,
+      //   altText: options?.altText,
+      //   description: options?.description,
+      //   tags: options?.tags,
+      //   sortOrder: index,
+      // });
+
+      // Generate signed URL for immediate use (or use uploadResult.url if available)
+      const signedUrl =
+        uploadResult.url ||
+        (await storage.getUrl(key, { expiresIn: STORAGE_CONSTANTS.PRODUCT_URL_EXPIRY_SECONDS }));
+
+      results.push({
+        key,
+        url: signedUrl,
+        mediaId: `temp-${timestamp}-${index}`, // TODO: Replace with actual mediaRecord.id
+      });
+    }
+
+    return {
+      success: true,
+      data: results,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to upload product media',
+    };
+  }
+}
+
+/**
+ * Retrieve a product's media entries and attach signed URLs for client access.
+ *
+ * The returned media items include metadata (id, key, altText, sortOrder, contentType, size)
+ * and a signed `url` valid for the configured expiry. If `options.variant` is provided and is
+ * not `'public'`, the storage key is adjusted to include the variant before generating the URL.
+ *
+ * @param productId - The identifier of the product whose media should be fetched
+ * @param options.context - Request context; affects visibility (e.g., `'admin'` may include deleted items)
+ * @param options.variant - Optional variant key (`'thumbnail' | 'gallery' | 'hero' | 'public'`); when set and not `'public'` the storage key is suffixed with the variant for URL generation
+ * @param options.expiresIn - Signed URL lifetime in seconds (defaults to 3600)
+ * @returns On success, a `MediaActionResponse` containing an array of media items each with `id`, `key`, `url`, optional `altText`, `sortOrder`, `contentType`, and `size`; on failure, an error message describing the problem
+ */
+export async function getProductMediaAction(
+  productId: string,
+  options?: {
+    context: 'admin' | 'customer' | 'vendor';
+    variant?: 'thumbnail' | 'gallery' | 'hero' | 'public';
+    expiresIn?: number;
+  },
+): Promise<
+  MediaActionResponse<
+    Array<{
+      id: string;
+      key: string;
+      url: string;
+      altText?: string;
+      sortOrder: number;
+      contentType: string;
+      size: number;
+    }>
+  >
+> {
+  'use server';
+
+  try {
+    // TODO: Get media from database
+    // const productMedia = await getProductMediaFromDatabase(productId, {
+    //   includeDeleted: options?.context === 'admin',
+    // });
+
+    // Mock data for now
+    const productMedia = [
+      {
+        id: 'media-1',
+        key: `products/${productId}/images/hero.jpg`,
+        altText: 'Product hero image',
+        sortOrder: 0,
+        contentType: 'image/jpeg',
+        size: 1024000,
+      },
+      {
+        id: 'media-2',
+        key: `products/${productId}/images/gallery-1.jpg`,
+        altText: 'Product gallery image 1',
+        sortOrder: 1,
+        contentType: 'image/jpeg',
+        size: 856000,
+      },
+    ];
+
+    const storage = getStorage();
+    const expiresIn = options?.expiresIn ?? 3600; // 1 hour default
+
+    // Generate signed URLs for all media
+    const mediaWithUrls = await Promise.all(
+      productMedia.map(async media => {
+        let { key } = media;
+
+        // For Cloudflare Images, append variant
+        if (options?.variant && options.variant !== 'public') {
+          key = `${media.key}/${options.variant}`;
+        }
+
+        const signedUrl = await storage.getUrl(key, { expiresIn });
+
+        return {
+          ...media,
+          url: signedUrl,
+        };
+      }),
+    );
+
+    return {
+      success: true,
+      data: mediaWithUrls,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to get product media',
+    };
+  }
+}
+
+/**
+ * Delete a product's media entry and remove its stored object when requested.
+ *
+ * Performs authentication and permission checks when enforcement is enabled. By default performs a soft delete of the media record; when `options.hardDelete` is true, also deletes the object from storage.
+ *
+ * @param options - Additional options controlling deletion behavior
+ * @param options.context - Invocation context, either `'admin'` or `'vendor'`
+ * @param options.hardDelete - If `true`, delete the storage object and perform a hard delete; if omitted or `false`, perform a soft delete
+ * @returns A MediaActionResponse<void> indicating success. On failure `success` is `false` and `error` contains a descriptive message.
+ */
+export async function deleteProductMediaAction(
+  productId: string,
+  mediaId: string,
+  options?: {
+    context: 'admin' | 'vendor';
+    hardDelete?: boolean;
+  },
+): Promise<MediaActionResponse<void>> {
+  'use server';
+
+  try {
+    // Authentication check (configurable)
+    const featureEnv = safeEnv();
+    const session = await getSession();
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !session?.user) {
+      return {
+        success: false,
+        error: 'Unauthorized: Authentication required',
+      };
+    }
+
+    // Permission check (only when auth enforced)
+    const hasPermission = session?.user
+      ? await canUserManageProduct(session.user.id, productId)
+      : false;
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !hasPermission) {
+      return {
+        success: false,
+        error: 'Forbidden: Insufficient permissions',
+      };
+    }
+
+    // TODO: Get media record from database
+    // const mediaRecord = await getProductMediaById(mediaId);
+    // if (!mediaRecord || mediaRecord.productId !== productId) {
+    //   throw new Error('Media not found');
+    // }
+
+    // Mock media record
+    const mediaRecord = {
+      id: mediaId,
+      key: `products/${productId}/images/example.jpg`,
+      productId,
+    };
+
+    if (options?.hardDelete) {
+      // Delete from storage
+      const storage = getStorage();
+      await storage.delete(mediaRecord.key);
+
+      // TODO: Hard delete from database
+      // await deleteProductMediaRecord(mediaId);
+    } else {
+      // TODO: Soft delete in database
+      // await softDeleteProductMediaRecord(mediaId, session.user.id);
+    }
+
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to delete product media',
+    };
+  }
+}
+
+/**
+ * Reorders media items for a product.
+ *
+ * When storage authentication is enforced, this action requires an authenticated user
+ * who has permission to manage the specified product; otherwise it returns an authorization error.
+ *
+ * @param productId - The ID of the product whose media order will be updated
+ * @param mediaOrder - Array of objects mapping `mediaId` to the desired `sortOrder`
+ * @param options.context - Optional caller context, e.g. 'admin' or 'vendor'
+ * @returns An object with `success: true` when the reorder operation completes; otherwise `success: false` and an `error` message describing the failure
+ */
+export async function reorderProductMediaAction(
+  productId: string,
+  _mediaOrder: Array<{ mediaId: string; sortOrder: number }>,
+  _options?: {
+    context: 'admin' | 'vendor';
+  },
+): Promise<MediaActionResponse<void>> {
+  'use server';
+
+  try {
+    // Authentication check (configurable)
+    const featureEnv = safeEnv();
+    const session = await getSession();
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !session?.user) {
+      return {
+        success: false,
+        error: 'Unauthorized: Authentication required',
+      };
+    }
+
+    // Permission check (only when auth enforced)
+    const hasPermission = session?.user
+      ? await canUserManageProduct(session.user.id, productId)
+      : false;
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !hasPermission) {
+      return {
+        success: false,
+        error: 'Forbidden: Insufficient permissions',
+      };
+    }
+
+    // TODO: Update sort order in database
+    // await updateMediaSortOrder(productId, mediaOrder);
+
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to reorder product media',
+    };
+  }
+}
+
+/**
+ * Generate presigned upload URLs for client-side direct uploads scoped to a product.
+ *
+ * @param productId - Product identifier used to scope generated storage keys
+ * @param filenames - Desired filenames to include in generated storage keys
+ * @param options - Optional settings for URL generation
+ * @param options.context - The request context, e.g. 'admin' or 'vendor'
+ * @param options.expiresIn - Signed URL lifetime in seconds; defaults to STORAGE_CONSTANTS.UPLOAD_URL_EXPIRY_SECONDS
+ * @param options.maxSizeBytes - Optional maximum allowed upload size in bytes (informational; enforcement depends on storage provider)
+ * @returns A MediaActionResponse containing an array of upload descriptors; each descriptor includes `filename`, `uploadUrl`, `key`, and optional form `fields`
+ */
+export async function getProductUploadPresignedUrlsAction(
+  productId: string,
+  filenames: string[],
+  options?: {
+    context: 'admin' | 'vendor';
+    expiresIn?: number;
+    maxSizeBytes?: number;
+  },
+): Promise<
+  MediaActionResponse<
+    Array<{
+      filename: string;
+      uploadUrl: string;
+      key: string;
+      fields?: Record<string, string>;
+    }>
+  >
+> {
+  'use server';
+
+  try {
+    // Authentication check (configurable)
+    const featureEnv = safeEnv();
+    const session = await getSession();
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !session?.user) {
+      return {
+        success: false,
+        error: 'Unauthorized: Authentication required',
+      };
+    }
+
+    // Permission check (only when auth enforced)
+    const hasPermission = session?.user
+      ? await canUserManageProduct(session.user.id, productId)
+      : false;
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !hasPermission) {
+      return {
+        success: false,
+        error: 'Forbidden: Insufficient permissions',
+      };
+    }
+
+    const storage = getStorage();
+    const expiresIn = options?.expiresIn ?? STORAGE_CONSTANTS.UPLOAD_URL_EXPIRY_SECONDS;
+
+    const uploadUrls = await Promise.all(
+      filenames.map(async (filename, index) => {
+        // Sanitize filename to prevent path traversal
+        const sanitizedFilename = sanitizeStorageKey(filename);
+        const timestamp = Date.now();
+        const key = `products/${productId}/images/${timestamp}-${index}-${sanitizedFilename}`;
+
+        // Validate storage key
+        const keyValidation = validateStorageKey(key, {
+          maxLength: 1024,
+          forbiddenPatterns: [/\.\./, /\/\//],
+        });
+        if (!keyValidation.valid) {
+          throw new Error(`Invalid storage key: ${keyValidation.errors.join(', ')}`);
+        }
+
+        // TODO: Use actual presigned POST URL when storage provider supports it
+        // For now, use signed GET URL as placeholder
+        const uploadUrl = await storage.getUrl(key, { expiresIn });
+
+        return {
+          filename,
+          uploadUrl,
+          key,
+          // fields: presignedPost.fields, // For S3-style presigned POST
+        };
+      }),
+    );
+
+    return {
+      success: true,
+      data: uploadUrls,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to generate upload URLs',
+    };
+  }
+}
+
+/**
+ * Performs bulk metadata updates for a product's media items.
+ *
+ * @param productId - ID of the product whose media items will be updated
+ * @param updates - List of update objects, each with a `mediaId` and optional `altText`, `description`, and `tags`
+ * @param options - Optional operation context; expected values are `'admin'` or `'vendor'`
+ * @returns A response object indicating success; on failure `error` contains a descriptive message (for example, `Unauthorized: Authentication required` or `Forbidden: Insufficient permissions`)
+ */
+export async function bulkUpdateProductMediaAction(
+  productId: string,
+  _updates: Array<{
+    mediaId: string;
+    altText?: string;
+    description?: string;
+    tags?: string[];
+  }>,
+  _options?: {
+    context: 'admin' | 'vendor';
+  },
+): Promise<MediaActionResponse<void>> {
+  'use server';
+
+  try {
+    // Authentication check (configurable)
+    const featureEnv = safeEnv();
+    const session = await getSession();
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !session?.user) {
+      return {
+        success: false,
+        error: 'Unauthorized: Authentication required',
+      };
+    }
+
+    // Permission check (only when auth enforced)
+    const hasPermission = session?.user
+      ? await canUserManageProduct(session.user.id, productId)
+      : false;
+    if (featureEnv.STORAGE_ENFORCE_AUTH && !hasPermission) {
+      return {
+        success: false,
+        error: 'Forbidden: Insufficient permissions',
+      };
+    }
+
+    // TODO: Bulk update in database
+    // await bulkUpdateProductMedia(productId, updates);
+
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to bulk update product media',
+    };
+  }
+}