@blackcode_sa/metaestetics-api 1.15.14 → 1.15.17-staging.0

package/src/services/media/media.service.ts

@@ -1,418 +1,418 @@
-import { Auth } from "firebase/auth";
-import { Firestore, Timestamp } from "firebase/firestore";
-import { FirebaseApp } from "firebase/app";
-import {
-  ref,
-  uploadBytes,
-  getDownloadURL,
-  deleteObject,
-  getBytes,
-} from "firebase/storage";
-import {
-  doc,
-  getDoc,
-  setDoc,
-  updateDoc,
-  collection,
-  query,
-  where,
-  limit,
-  getDocs,
-  deleteDoc,
-  orderBy,
-} from "firebase/firestore";
-import { BaseService } from "../base.service";
-
-/**
- * Enum for media access levels
- */
-export enum MediaAccessLevel {
-  PUBLIC = "public",
-  PRIVATE = "private",
-  CONFIDENTIAL = "confidential",
-}
-
-/**
- * Type that allows a field to be either a URL string or a File object
- */
-export type MediaResource = string | File | Blob;
-
-/**
- * Media file metadata interface
- */
-export interface MediaMetadata {
-  id: string; // Unique ID for the media, also Firestore document ID
-  name: string; // Original file name or a descriptive name
-  url: string; // Publicly accessible download URL
-  contentType: string; // Mime type of the file
-  size: number; // Size of the file in bytes
-  createdAt: Timestamp; // Firestore Timestamp of creation
-  accessLevel: MediaAccessLevel; // Access level
-  ownerId: string; // ID of the entity that owns this media (e.g., patientId, clinicId)
-  collectionName: string; // Name of the collection this media belongs to (e.g., 'patient_profile_pictures', 'clinic_gallery')
-  path: string; // Full path in Firebase Storage
-  updatedAt?: Timestamp; // Firestore Timestamp of last update
-}
-
-export const MEDIA_METADATA_COLLECTION = "media_metadata";
-
-export class MediaService extends BaseService {
-  constructor(...args: ConstructorParameters<typeof BaseService>) {
-    super(...args);
-  }
-
-  /**
-   * Upload a media file, store its metadata, and return the metadata including the URL.
-   * @param file - The file to upload.
-   * @param ownerId - ID of the owner (user, patient, clinic, etc.).
-   * @param accessLevel - Access level (public, private, confidential).
-   * @param collectionName - The logical collection name this media belongs to (e.g., 'patient_profile_pictures', 'clinic_logos').
-   * @param originalFileName - Optional: the original name of the file, if not using file.name.
-   * @returns Promise with the media metadata.
-   */
-  async uploadMedia(
-    file: File | Blob,
-    ownerId: string,
-    accessLevel: MediaAccessLevel,
-    collectionName: string,
-    originalFileName?: string
-  ): Promise<MediaMetadata> {
-    const mediaId = this.generateId();
-    const fileNameToUse =
-      originalFileName || (file instanceof File ? file.name : file.toString());
-    // Using collectionName in the path for better organization
-    const uniqueFileName = `${mediaId}-${fileNameToUse}`;
-    const filePath = `media/${accessLevel}/${ownerId}/${collectionName}/${uniqueFileName}`;
-
-    console.log(`[MediaService] Uploading file to: ${filePath}`);
-    const storageRef = ref(this.storage, filePath);
-    try {
-      const uploadResult = await uploadBytes(storageRef, file, {
-        contentType: file.type,
-      });
-      console.log("[MediaService] File uploaded successfully", uploadResult);
-      const downloadURL = await getDownloadURL(uploadResult.ref);
-      console.log("[MediaService] Got download URL:", downloadURL);
-      const metadata: MediaMetadata = {
-        id: mediaId,
-        name: fileNameToUse,
-        url: downloadURL,
-        contentType: file.type,
-        size: file.size,
-        createdAt: Timestamp.now(),
-        accessLevel: accessLevel,
-        ownerId: ownerId,
-        collectionName: collectionName,
-        path: filePath,
-      };
-      const metadataDocRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
-      await setDoc(metadataDocRef, metadata);
-      console.log("[MediaService] Metadata stored in Firestore:", mediaId);
-      return metadata;
-    } catch (error) {
-      console.error("[MediaService] Error during media upload:", error);
-      throw error;
-    }
-  }
-
-  /**
-   * Get media metadata from Firestore by its ID.
-   * @param mediaId - ID of the media.
-   * @returns Promise with the media metadata or null if not found.
-   */
-  async getMediaMetadata(mediaId: string): Promise<MediaMetadata | null> {
-    console.log(`[MediaService] Getting media metadata for ID: ${mediaId}`);
-    const docRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
-    const docSnap = await getDoc(docRef);
-
-    if (docSnap.exists()) {
-      console.log("[MediaService] Metadata found:", docSnap.data());
-      return docSnap.data() as MediaMetadata;
-    }
-    console.log("[MediaService] No metadata found for ID:", mediaId);
-    return null;
-  }
-
-  /**
-   * Get media metadata from Firestore by its public URL.
-   * @param url - The public URL of the media file.
-   * @returns Promise with the media metadata or null if not found.
-   */
-  async getMediaMetadataByUrl(url: string): Promise<MediaMetadata | null> {
-    console.log(`[MediaService] Getting media metadata by URL: ${url}`);
-    const q = query(
-      collection(this.db, MEDIA_METADATA_COLLECTION),
-      where("url", "==", url),
-      limit(1)
-    );
-
-    try {
-      const querySnapshot = await getDocs(q);
-      if (!querySnapshot.empty) {
-        const metadata = querySnapshot.docs[0].data() as MediaMetadata;
-        console.log("[MediaService] Metadata found by URL:", metadata);
-        return metadata;
-      }
-      console.log("[MediaService] No metadata found for URL:", url);
-      return null;
-    } catch (error) {
-      console.error("[MediaService] Error fetching metadata by URL:", error);
-      throw error;
-    }
-  }
-
-  /**
-   * Delete media from storage and remove metadata from Firestore.
-   * @param mediaId - ID of the media to delete.
-   */
-  async deleteMedia(mediaId: string): Promise<void> {
-    console.log(`[MediaService] Deleting media with ID: ${mediaId}`);
-    const metadata = await this.getMediaMetadata(mediaId);
-
-    if (!metadata) {
-      console.warn(
-        `[MediaService] Metadata not found for media ID ${mediaId}. Cannot delete.`
-      );
-      // Optionally throw an error or return a status
-      return;
-    }
-
-    const storageFileRef = ref(this.storage, metadata.path);
-
-    try {
-      // Delete the file from Firebase Storage
-      await deleteObject(storageFileRef);
-      console.log(`[MediaService] File deleted from Storage: ${metadata.path}`);
-
-      // Delete the metadata from Firestore
-      const metadataDocRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
-      await deleteDoc(metadataDocRef);
-      console.log(
-        `[MediaService] Metadata deleted from Firestore for ID: ${mediaId}`
-      );
-    } catch (error) {
-      console.error(`[MediaService] Error deleting media ${mediaId}:`, error);
-      // Handle specific errors, e.g., file not found in storage, permissions issues
-      // If Firestore delete fails after storage delete, there might be an orphaned metadata entry.
-      // Consider how to handle such inconsistencies or if it's acceptable.
-      throw error;
-    }
-  }
-
-  /**
-   * Update media access level. This involves moving the file in Firebase Storage
-   * to a new path reflecting the new access level, and updating its metadata.
-   * @param mediaId - ID of the media to update.
-   * @param newAccessLevel - New access level.
-   * @returns Promise with the updated media metadata, or null if metadata not found.
-   */
-  async updateMediaAccessLevel(
-    mediaId: string,
-    newAccessLevel: MediaAccessLevel
-  ): Promise<MediaMetadata | null> {
-    console.log(
-      `[MediaService] Attempting to update access level for media ID: ${mediaId} to ${newAccessLevel}`
-    );
-    const metadata = await this.getMediaMetadata(mediaId);
-
-    if (!metadata) {
-      console.warn(
-        `[MediaService] Metadata not found for media ID ${mediaId}. Cannot update access level.`
-      );
-      return null;
-    }
-
-    if (metadata.accessLevel === newAccessLevel) {
-      console.log(
-        `[MediaService] Media ID ${mediaId} already has access level ${newAccessLevel}. Updating timestamp only.`
-      );
-      const metadataDocRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
-      try {
-        await updateDoc(metadataDocRef, { updatedAt: Timestamp.now() });
-        return { ...metadata, updatedAt: Timestamp.now() };
-      } catch (error) {
-        console.error(
-          `[MediaService] Error updating timestamp for media ID ${mediaId}:`,
-          error
-        );
-        throw error; // Re-throw to indicate the update wasn't fully successful
-      }
-    }
-
-    const oldStoragePath = metadata.path;
-    // Ensure the filename part remains consistent using metadata.id and metadata.name
-    const fileNamePart = `${metadata.id}-${metadata.name}`;
-    const newStoragePath = `media/${newAccessLevel}/${metadata.ownerId}/${metadata.collectionName}/${fileNamePart}`;
-
-    console.log(
-      `[MediaService] Moving file for ${mediaId} from ${oldStoragePath} to ${newStoragePath}`
-    );
-
-    const oldStorageFileRef = ref(this.storage, oldStoragePath);
-    const newStorageFileRef = ref(this.storage, newStoragePath);
-
-    try {
-      // 1. Download (get bytes of) the old file
-      console.log(`[MediaService] Downloading bytes from ${oldStoragePath}`);
-      const fileBytes = await getBytes(oldStorageFileRef);
-      console.log(
-        `[MediaService] Successfully downloaded ${fileBytes.byteLength} bytes from ${oldStoragePath}`
-      );
-
-      // 2. Upload the bytes to the new path
-      console.log(`[MediaService] Uploading bytes to ${newStoragePath}`);
-      await uploadBytes(newStorageFileRef, fileBytes, {
-        contentType: metadata.contentType,
-      });
-      console.log(
-        `[MediaService] Successfully uploaded bytes to ${newStoragePath}`
-      );
-
-      // 3. Get the new download URL
-      const newDownloadURL = await getDownloadURL(newStorageFileRef);
-      console.log(
-        `[MediaService] Got new download URL for ${newStoragePath}: ${newDownloadURL}`
-      );
-
-      // 4. Prepare metadata for update
-      const updateData = {
-        accessLevel: newAccessLevel,
-        path: newStoragePath,
-        url: newDownloadURL,
-        updatedAt: Timestamp.now(),
-      };
-
-      // 5. Update Firestore metadata
-      const metadataDocRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
-      console.log(
-        `[MediaService] Updating Firestore metadata for ${mediaId} with new data:`,
-        updateData
-      );
-      await updateDoc(metadataDocRef, updateData);
-      console.log(
-        `[MediaService] Successfully updated Firestore metadata for ${mediaId}`
-      );
-
-      // 6. Delete the old file from Firebase Storage (after metadata is updated)
-      try {
-        console.log(`[MediaService] Deleting old file from ${oldStoragePath}`);
-        await deleteObject(oldStorageFileRef);
-        console.log(
-          `[MediaService] Successfully deleted old file from ${oldStoragePath}`
-        );
-      } catch (deleteError) {
-        console.error(
-          `[MediaService] Failed to delete old file from ${oldStoragePath} for media ID ${mediaId}. This file is now orphaned. Error:`,
-          deleteError
-        );
-        // Do not re-throw here, as the primary operation (move and metadata update) was successful.
-        // Log this issue for potential manual cleanup.
-      }
-
-      return { ...metadata, ...updateData } as MediaMetadata;
-    } catch (error) {
-      console.error(
-        `[MediaService] Error updating media access level and moving file for ${mediaId}:`,
-        error
-      );
-      // Attempt to clean up if new file was created but process failed before metadata update
-      // This is a best-effort cleanup. If newDownloadURL is not defined, it means upload failed.
-      // If newDownloadURL is defined but metadata update failed, new file might exist.
-      if (
-        newStorageFileRef &&
-        (error as any).code !== "storage/object-not-found" &&
-        (error as any).message?.includes("uploadBytes")
-      ) {
-        // This check is a bit heuristic. Ideally, check if new file actually exists.
-        console.warn(
-          `[MediaService] Attempting to delete partially uploaded file at ${newStoragePath} due to error.`
-        );
-        try {
-          await deleteObject(newStorageFileRef);
-          console.warn(
-            `[MediaService] Cleaned up partially uploaded file at ${newStoragePath}.`
-          );
-        } catch (cleanupError) {
-          console.error(
-            `[MediaService] Failed to cleanup partially uploaded file at ${newStoragePath}:`,
-            cleanupError
-          );
-        }
-      }
-      throw error; // Re-throw the original error to the caller
-    }
-  }
-
-  /**
-   * List all media for an owner, optionally filtered by collection and access level.
-   * @param ownerId - ID of the owner.
-   * @param collectionName - Optional: Filter by collection name.
-   * @param accessLevel - Optional: Filter by access level.
-   * @param count - Optional: Number of items to fetch.
-   * @param startAfterId - Optional: ID of the document to start after (for pagination).
-   */
-  async listMedia(
-    ownerId: string,
-    collectionName?: string,
-    accessLevel?: MediaAccessLevel,
-    count?: number,
-    startAfterId?: string // Using ID for pagination simplicity with Firestore
-  ): Promise<MediaMetadata[]> {
-    console.log(`[MediaService] Listing media for owner: ${ownerId}`);
-    let qConstraints: any[] = [where("ownerId", "==", ownerId)];
-
-    if (collectionName) {
-      qConstraints.push(where("collectionName", "==", collectionName));
-    }
-    if (accessLevel) {
-      qConstraints.push(where("accessLevel", "==", accessLevel));
-    }
-
-    qConstraints.push(orderBy("createdAt", "desc")); // Example ordering
-
-    if (count) {
-      qConstraints.push(limit(count));
-    }
-
-    if (startAfterId) {
-      const startAfterDoc = await this.getMediaMetadata(startAfterId);
-      if (startAfterDoc) {
-        // Placeholder: Firestore's startAfter needs a DocumentSnapshot or field values.
-        // For robust pagination, pass the actual DocumentSnapshot or use field values from it.
-        // e.g., qConstraints.push(startAfter(snapshotOfStartAfterDoc));
-      }
-    }
-
-    const finalQuery = query(
-      collection(this.db, MEDIA_METADATA_COLLECTION),
-      ...qConstraints
-    );
-
-    try {
-      const querySnapshot = await getDocs(finalQuery);
-      const mediaList = querySnapshot.docs.map(
-        (doc) => doc.data() as MediaMetadata
-      );
-      console.log(`[MediaService] Found ${mediaList.length} media items.`);
-      return mediaList;
-    } catch (error) {
-      console.error("[MediaService] Error listing media:", error);
-      throw error;
-    }
-  }
-
-  /**
-   * Get download URL for media. (Convenience, as URL is in metadata)
-   * @param mediaId - ID of the media.
-   */
-  async getMediaDownloadUrl(mediaId: string): Promise<string | null> {
-    console.log(`[MediaService] Getting download URL for media ID: ${mediaId}`);
-    const metadata = await this.getMediaMetadata(mediaId);
-    if (metadata && metadata.url) {
-      console.log(`[MediaService] URL found: ${metadata.url}`);
-      return metadata.url;
-    }
-    console.log(`[MediaService] URL not found for media ID: ${mediaId}`);
-    return null;
-  }
-}
+import { Auth } from "firebase/auth";
+import { Firestore, Timestamp } from "firebase/firestore";
+import { FirebaseApp } from "firebase/app";
+import {
+  ref,
+  uploadBytes,
+  getDownloadURL,
+  deleteObject,
+  getBytes,
+} from "firebase/storage";
+import {
+  doc,
+  getDoc,
+  setDoc,
+  updateDoc,
+  collection,
+  query,
+  where,
+  limit,
+  getDocs,
+  deleteDoc,
+  orderBy,
+} from "firebase/firestore";
+import { BaseService } from "../base.service";
+
+/**
+ * Enum for media access levels
+ */
+export enum MediaAccessLevel {
+  PUBLIC = "public",
+  PRIVATE = "private",
+  CONFIDENTIAL = "confidential",
+}
+
+/**
+ * Type that allows a field to be either a URL string or a File object
+ */
+export type MediaResource = string | File | Blob;
+
+/**
+ * Media file metadata interface
+ */
+export interface MediaMetadata {
+  id: string; // Unique ID for the media, also Firestore document ID
+  name: string; // Original file name or a descriptive name
+  url: string; // Publicly accessible download URL
+  contentType: string; // Mime type of the file
+  size: number; // Size of the file in bytes
+  createdAt: Timestamp; // Firestore Timestamp of creation
+  accessLevel: MediaAccessLevel; // Access level
+  ownerId: string; // ID of the entity that owns this media (e.g., patientId, clinicId)
+  collectionName: string; // Name of the collection this media belongs to (e.g., 'patient_profile_pictures', 'clinic_gallery')
+  path: string; // Full path in Firebase Storage
+  updatedAt?: Timestamp; // Firestore Timestamp of last update
+}
+
+export const MEDIA_METADATA_COLLECTION = "media_metadata";
+
+export class MediaService extends BaseService {
+  constructor(...args: ConstructorParameters<typeof BaseService>) {
+    super(...args);
+  }
+
+  /**
+   * Upload a media file, store its metadata, and return the metadata including the URL.
+   * @param file - The file to upload.
+   * @param ownerId - ID of the owner (user, patient, clinic, etc.).
+   * @param accessLevel - Access level (public, private, confidential).
+   * @param collectionName - The logical collection name this media belongs to (e.g., 'patient_profile_pictures', 'clinic_logos').
+   * @param originalFileName - Optional: the original name of the file, if not using file.name.
+   * @returns Promise with the media metadata.
+   */
+  async uploadMedia(
+    file: File | Blob,
+    ownerId: string,
+    accessLevel: MediaAccessLevel,
+    collectionName: string,
+    originalFileName?: string
+  ): Promise<MediaMetadata> {
+    const mediaId = this.generateId();
+    const fileNameToUse =
+      originalFileName || (file instanceof File ? file.name : file.toString());
+    // Using collectionName in the path for better organization
+    const uniqueFileName = `${mediaId}-${fileNameToUse}`;
+    const filePath = `media/${accessLevel}/${ownerId}/${collectionName}/${uniqueFileName}`;
+
+    console.log(`[MediaService] Uploading file to: ${filePath}`);
+    const storageRef = ref(this.storage, filePath);
+    try {
+      const uploadResult = await uploadBytes(storageRef, file, {
+        contentType: file.type,
+      });
+      console.log("[MediaService] File uploaded successfully", uploadResult);
+      const downloadURL = await getDownloadURL(uploadResult.ref);
+      console.log("[MediaService] Got download URL:", downloadURL);
+      const metadata: MediaMetadata = {
+        id: mediaId,
+        name: fileNameToUse,
+        url: downloadURL,
+        contentType: file.type,
+        size: file.size,
+        createdAt: Timestamp.now(),
+        accessLevel: accessLevel,
+        ownerId: ownerId,
+        collectionName: collectionName,
+        path: filePath,
+      };
+      const metadataDocRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
+      await setDoc(metadataDocRef, metadata);
+      console.log("[MediaService] Metadata stored in Firestore:", mediaId);
+      return metadata;
+    } catch (error) {
+      console.error("[MediaService] Error during media upload:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get media metadata from Firestore by its ID.
+   * @param mediaId - ID of the media.
+   * @returns Promise with the media metadata or null if not found.
+   */
+  async getMediaMetadata(mediaId: string): Promise<MediaMetadata | null> {
+    console.log(`[MediaService] Getting media metadata for ID: ${mediaId}`);
+    const docRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
+    const docSnap = await getDoc(docRef);
+
+    if (docSnap.exists()) {
+      console.log("[MediaService] Metadata found:", docSnap.data());
+      return docSnap.data() as MediaMetadata;
+    }
+    console.log("[MediaService] No metadata found for ID:", mediaId);
+    return null;
+  }
+
+  /**
+   * Get media metadata from Firestore by its public URL.
+   * @param url - The public URL of the media file.
+   * @returns Promise with the media metadata or null if not found.
+   */
+  async getMediaMetadataByUrl(url: string): Promise<MediaMetadata | null> {
+    console.log(`[MediaService] Getting media metadata by URL: ${url}`);
+    const q = query(
+      collection(this.db, MEDIA_METADATA_COLLECTION),
+      where("url", "==", url),
+      limit(1)
+    );
+
+    try {
+      const querySnapshot = await getDocs(q);
+      if (!querySnapshot.empty) {
+        const metadata = querySnapshot.docs[0].data() as MediaMetadata;
+        console.log("[MediaService] Metadata found by URL:", metadata);
+        return metadata;
+      }
+      console.log("[MediaService] No metadata found for URL:", url);
+      return null;
+    } catch (error) {
+      console.error("[MediaService] Error fetching metadata by URL:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Delete media from storage and remove metadata from Firestore.
+   * @param mediaId - ID of the media to delete.
+   */
+  async deleteMedia(mediaId: string): Promise<void> {
+    console.log(`[MediaService] Deleting media with ID: ${mediaId}`);
+    const metadata = await this.getMediaMetadata(mediaId);
+
+    if (!metadata) {
+      console.warn(
+        `[MediaService] Metadata not found for media ID ${mediaId}. Cannot delete.`
+      );
+      // Optionally throw an error or return a status
+      return;
+    }
+
+    const storageFileRef = ref(this.storage, metadata.path);
+
+    try {
+      // Delete the file from Firebase Storage
+      await deleteObject(storageFileRef);
+      console.log(`[MediaService] File deleted from Storage: ${metadata.path}`);
+
+      // Delete the metadata from Firestore
+      const metadataDocRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
+      await deleteDoc(metadataDocRef);
+      console.log(
+        `[MediaService] Metadata deleted from Firestore for ID: ${mediaId}`
+      );
+    } catch (error) {
+      console.error(`[MediaService] Error deleting media ${mediaId}:`, error);
+      // Handle specific errors, e.g., file not found in storage, permissions issues
+      // If Firestore delete fails after storage delete, there might be an orphaned metadata entry.
+      // Consider how to handle such inconsistencies or if it's acceptable.
+      throw error;
+    }
+  }
+
+  /**
+   * Update media access level. This involves moving the file in Firebase Storage
+   * to a new path reflecting the new access level, and updating its metadata.
+   * @param mediaId - ID of the media to update.
+   * @param newAccessLevel - New access level.
+   * @returns Promise with the updated media metadata, or null if metadata not found.
+   */
+  async updateMediaAccessLevel(
+    mediaId: string,
+    newAccessLevel: MediaAccessLevel
+  ): Promise<MediaMetadata | null> {
+    console.log(
+      `[MediaService] Attempting to update access level for media ID: ${mediaId} to ${newAccessLevel}`
+    );
+    const metadata = await this.getMediaMetadata(mediaId);
+
+    if (!metadata) {
+      console.warn(
+        `[MediaService] Metadata not found for media ID ${mediaId}. Cannot update access level.`
+      );
+      return null;
+    }
+
+    if (metadata.accessLevel === newAccessLevel) {
+      console.log(
+        `[MediaService] Media ID ${mediaId} already has access level ${newAccessLevel}. Updating timestamp only.`
+      );
+      const metadataDocRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
+      try {
+        await updateDoc(metadataDocRef, { updatedAt: Timestamp.now() });
+        return { ...metadata, updatedAt: Timestamp.now() };
+      } catch (error) {
+        console.error(
+          `[MediaService] Error updating timestamp for media ID ${mediaId}:`,
+          error
+        );
+        throw error; // Re-throw to indicate the update wasn't fully successful
+      }
+    }
+
+    const oldStoragePath = metadata.path;
+    // Ensure the filename part remains consistent using metadata.id and metadata.name
+    const fileNamePart = `${metadata.id}-${metadata.name}`;
+    const newStoragePath = `media/${newAccessLevel}/${metadata.ownerId}/${metadata.collectionName}/${fileNamePart}`;
+
+    console.log(
+      `[MediaService] Moving file for ${mediaId} from ${oldStoragePath} to ${newStoragePath}`
+    );
+
+    const oldStorageFileRef = ref(this.storage, oldStoragePath);
+    const newStorageFileRef = ref(this.storage, newStoragePath);
+
+    try {
+      // 1. Download (get bytes of) the old file
+      console.log(`[MediaService] Downloading bytes from ${oldStoragePath}`);
+      const fileBytes = await getBytes(oldStorageFileRef);
+      console.log(
+        `[MediaService] Successfully downloaded ${fileBytes.byteLength} bytes from ${oldStoragePath}`
+      );
+
+      // 2. Upload the bytes to the new path
+      console.log(`[MediaService] Uploading bytes to ${newStoragePath}`);
+      await uploadBytes(newStorageFileRef, fileBytes, {
+        contentType: metadata.contentType,
+      });
+      console.log(
+        `[MediaService] Successfully uploaded bytes to ${newStoragePath}`
+      );
+
+      // 3. Get the new download URL
+      const newDownloadURL = await getDownloadURL(newStorageFileRef);
+      console.log(
+        `[MediaService] Got new download URL for ${newStoragePath}: ${newDownloadURL}`
+      );
+
+      // 4. Prepare metadata for update
+      const updateData = {
+        accessLevel: newAccessLevel,
+        path: newStoragePath,
+        url: newDownloadURL,
+        updatedAt: Timestamp.now(),
+      };
+
+      // 5. Update Firestore metadata
+      const metadataDocRef = doc(this.db, MEDIA_METADATA_COLLECTION, mediaId);
+      console.log(
+        `[MediaService] Updating Firestore metadata for ${mediaId} with new data:`,
+        updateData
+      );
+      await updateDoc(metadataDocRef, updateData);
+      console.log(
+        `[MediaService] Successfully updated Firestore metadata for ${mediaId}`
+      );
+
+      // 6. Delete the old file from Firebase Storage (after metadata is updated)
+      try {
+        console.log(`[MediaService] Deleting old file from ${oldStoragePath}`);
+        await deleteObject(oldStorageFileRef);
+        console.log(
+          `[MediaService] Successfully deleted old file from ${oldStoragePath}`
+        );
+      } catch (deleteError) {
+        console.error(
+          `[MediaService] Failed to delete old file from ${oldStoragePath} for media ID ${mediaId}. This file is now orphaned. Error:`,
+          deleteError
+        );
+        // Do not re-throw here, as the primary operation (move and metadata update) was successful.
+        // Log this issue for potential manual cleanup.
+      }
+
+      return { ...metadata, ...updateData } as MediaMetadata;
+    } catch (error) {
+      console.error(
+        `[MediaService] Error updating media access level and moving file for ${mediaId}:`,
+        error
+      );
+      // Attempt to clean up if new file was created but process failed before metadata update
+      // This is a best-effort cleanup. If newDownloadURL is not defined, it means upload failed.
+      // If newDownloadURL is defined but metadata update failed, new file might exist.
+      if (
+        newStorageFileRef &&
+        (error as any).code !== "storage/object-not-found" &&
+        (error as any).message?.includes("uploadBytes")
+      ) {
+        // This check is a bit heuristic. Ideally, check if new file actually exists.
+        console.warn(
+          `[MediaService] Attempting to delete partially uploaded file at ${newStoragePath} due to error.`
+        );
+        try {
+          await deleteObject(newStorageFileRef);
+          console.warn(
+            `[MediaService] Cleaned up partially uploaded file at ${newStoragePath}.`
+          );
+        } catch (cleanupError) {
+          console.error(
+            `[MediaService] Failed to cleanup partially uploaded file at ${newStoragePath}:`,
+            cleanupError
+          );
+        }
+      }
+      throw error; // Re-throw the original error to the caller
+    }
+  }
+
+  /**
+   * List all media for an owner, optionally filtered by collection and access level.
+   * @param ownerId - ID of the owner.
+   * @param collectionName - Optional: Filter by collection name.
+   * @param accessLevel - Optional: Filter by access level.
+   * @param count - Optional: Number of items to fetch.
+   * @param startAfterId - Optional: ID of the document to start after (for pagination).
+   */
+  async listMedia(
+    ownerId: string,
+    collectionName?: string,
+    accessLevel?: MediaAccessLevel,
+    count?: number,
+    startAfterId?: string // Using ID for pagination simplicity with Firestore
+  ): Promise<MediaMetadata[]> {
+    console.log(`[MediaService] Listing media for owner: ${ownerId}`);
+    let qConstraints: any[] = [where("ownerId", "==", ownerId)];
+
+    if (collectionName) {
+      qConstraints.push(where("collectionName", "==", collectionName));
+    }
+    if (accessLevel) {
+      qConstraints.push(where("accessLevel", "==", accessLevel));
+    }
+
+    qConstraints.push(orderBy("createdAt", "desc")); // Example ordering
+
+    if (count) {
+      qConstraints.push(limit(count));
+    }
+
+    if (startAfterId) {
+      const startAfterDoc = await this.getMediaMetadata(startAfterId);
+      if (startAfterDoc) {
+        // Placeholder: Firestore's startAfter needs a DocumentSnapshot or field values.
+        // For robust pagination, pass the actual DocumentSnapshot or use field values from it.
+        // e.g., qConstraints.push(startAfter(snapshotOfStartAfterDoc));
+      }
+    }
+
+    const finalQuery = query(
+      collection(this.db, MEDIA_METADATA_COLLECTION),
+      ...qConstraints
+    );
+
+    try {
+      const querySnapshot = await getDocs(finalQuery);
+      const mediaList = querySnapshot.docs.map(
+        (doc) => doc.data() as MediaMetadata
+      );
+      console.log(`[MediaService] Found ${mediaList.length} media items.`);
+      return mediaList;
+    } catch (error) {
+      console.error("[MediaService] Error listing media:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get download URL for media. (Convenience, as URL is in metadata)
+   * @param mediaId - ID of the media.
+   */
+  async getMediaDownloadUrl(mediaId: string): Promise<string | null> {
+    console.log(`[MediaService] Getting download URL for media ID: ${mediaId}`);
+    const metadata = await this.getMediaMetadata(mediaId);
+    if (metadata && metadata.url) {
+      console.log(`[MediaService] URL found: ${metadata.url}`);
+      return metadata.url;
+    }
+    console.log(`[MediaService] URL not found for media ID: ${mediaId}`);
+    return null;
+  }
+}