feat(imagekit): add folder management and cdn cache purging

- Organize uploads into type-specific folders (images, documents, etc.).
- Automatically purge cdn cache upon file deletion for immediate effect.

refactor(imagekit): streamline api endpoints and service logic
- Rename endpoints for clarity (`/auth` to `/signed-upload`, `/by-url`).
- Remove unused endpoints and service methods for file details and deletion by id.
- Simplify swagger documentation for controller endpoints.

fix(imagekit): make file lookup by url more robust
- Clean urls by removing query parameters before searching.
- Prevents lookup failures for urls with versioning or tracking params.

src/shared/modules/imagekitio/imagekitio.controller.ts

@@ -2,18 +2,11 @@ import {
   Controller,
   Get,
   Delete,
-  Param,
   Query,
   HttpCode,
   HttpStatus,
 } from '@nestjs/common';
-import {
-  ApiTags,
-  ApiOperation,
-  ApiResponse,
-  ApiParam,
-  ApiQuery,
-} from '@nestjs/swagger';
+import { ApiTags, ApiOperation, ApiQuery } from '@nestjs/swagger';
 import { ImagekitioService } from './imagekitio.service';
 import { FileType } from './enums/file-type.enum';
 
@@ -22,97 +15,22 @@ import { FileType } from './enums/file-type.enum';
 export class ImagekitioController {
   constructor(private readonly imagekitioService: ImagekitioService) {}
 
-  @Get('auth')
-  @ApiOperation({
-    summary: 'Get authentication parameters for client-side upload',
-    description:
-      'Returns token, expire, and signature required for direct upload to ImageKit from frontend. Optionally restrict by file type.',
-  })
-  @ApiQuery({
-    name: 'type',
-    required: false,
-    enum: FileType,
-    description: 'File type restriction',
-    example: FileType.IMAGE,
-  })
-  @ApiResponse({
-    status: 200,
-    description: 'Authentication parameters generated successfully',
-    schema: {
-      example: {
-        token: 'unique-token-string',
-        expire: 1234567890,
-        signature: 'generated-signature',
-        fileType: 'image',
-      },
-    },
-  })
-  getAuthParams(@Query('type') type?: FileType) {
+  @Get('signed-upload')
+  @ApiOperation({ summary: 'Get signed upload parameters' })
+  @ApiQuery({ name: 'type', enum: FileType, required: false })
+  getSignedUploadParams(@Query('type') type?: FileType) {
     return this.imagekitioService.getAuthenticationParameters(type);
   }
 
-  @Get('file-id-by-url')
-  @ApiOperation({
-    summary: 'Get file ID from ImageKit URL',
-    description:
-      'Retrieves the file ID and details from an ImageKit URL. Useful before deleting a file.',
-  })
-  @ApiQuery({
-    name: 'url',
-    required: true,
-    description: 'The ImageKit file URL',
-    example:
-      'https://ik.imagekit.io/eihvofxmgsdfb/my-images/krishna/krishna_KvmHprPX7.jpg',
-  })
-  @ApiResponse({
-    status: 200,
-    description: 'File ID retrieved successfully',
-    schema: {
-      example: {
-        fileId: '66c91e205ae88a1234d90abc',
-        name: 'krishna.jpg',
-        url: 'https://ik.imagekit.io/eihvofxmgsdfb/my-images/krishna/krishna_KvmHprPX7.jpg',
-      },
-    },
-  })
-  @ApiResponse({
-    status: 404,
-    description: 'File not found or already deleted',
-  })
-  async getFileIdByUrl(@Query('url') url: string): Promise<any> {
+  @Get('by-url')
+  @ApiOperation({ summary: 'Get file details by URL' })
+  async getFileByUrl(@Query('url') url: string): Promise<any> {
     return this.imagekitioService.getFileIdByUrl(url);
   }
 
   @Delete('by-url')
   @HttpCode(HttpStatus.OK)
-  @ApiOperation({
-    summary: 'Delete a file from ImageKit by URL',
-    description:
-      'Deletes a file from ImageKit storage using the file URL. This endpoint first retrieves the file ID from the URL, then deletes the file.',
-  })
-  @ApiQuery({
-    name: 'url',
-    required: true,
-    description: 'The ImageKit file URL to delete',
-    example:
-      'https://ik.imagekit.io/eihvofxmgsdfb/my-images/krishna/krishna_KvmHprPX7.jpg',
-  })
-  @ApiResponse({
-    status: 200,
-    description: 'File deleted successfully',
-    schema: {
-      example: {
-        message: 'File deleted successfully',
-        deletedUrl:
-          'https://ik.imagekit.io/eihvofxmgsdfb/my-images/krishna/krishna_KvmHprPX7.jpg',
-        fileId: '66c91e205ae88a1234d90abc',
-      },
-    },
-  })
-  @ApiResponse({
-    status: 404,
-    description: 'File not found or already deleted',
-  })
+  @ApiOperation({ summary: 'Delete file by URL' })
   async deleteFileByUrl(@Query('url') url: string) {
     const result = await this.imagekitioService.deleteFileByUrl(url);
     return {
@@ -120,49 +38,4 @@ export class ImagekitioController {
       ...result,
     };
   }
-
-  @Delete(':fileId')
-  @HttpCode(HttpStatus.OK)
-  @ApiOperation({
-    summary: 'Delete a file from ImageKit by file ID',
-    description: 'Deletes a file from ImageKit storage using the file ID',
-  })
-  @ApiParam({
-    name: 'fileId',
-    description: 'The ImageKit file ID to delete',
-    example: '5f8e7d6c5b4a3f2e1d0c9b8a',
-  })
-  @ApiResponse({
-    status: 200,
-    description: 'File deleted successfully',
-  })
-  @ApiResponse({
-    status: 404,
-    description: 'File not found',
-  })
-  async deleteFile(@Param('fileId') fileId: string) {
-    await this.imagekitioService.deleteFile(fileId);
-    return {
-      message: 'File deleted successfully',
-      fileId,
-    };
-  }
-
-  @Get('file/:fileId')
-  @ApiOperation({
-    summary: 'Get file details by file ID',
-    description: 'Retrieves details of a specific file from ImageKit',
-  })
-  @ApiParam({
-    name: 'fileId',
-    description: 'The ImageKit file ID',
-    example: '5f8e7d6c5b4a3f2e1d0c9b8a',
-  })
-  @ApiResponse({
-    status: 200,
-    description: 'File details retrieved successfully',
-  })
-  async getFileDetails(@Param('fileId') fileId: string): Promise<any> {
-    return this.imagekitioService.getFileDetails(fileId);
-  }
 }

src/shared/modules/imagekitio/imagekitio.service.ts

@@ -16,20 +16,41 @@ export class ImagekitioService {
     });
   }
 
+  /**
+   * Get folder path based on file type
+   * @param fileType - The file type (IMAGE, DOCUMENT, VIDEO)
+   * @returns Folder path for the file type
+   */
+  private getFolderPath(fileType: string): string {
+    const folderMap: Record<string, string> = {
+      IMAGE: 'images',
+      DOCUMENT: 'documents',
+      VIDEO: 'videos',
+    };
+    return folderMap[fileType.toUpperCase()] || 'others';
+  }
+
   /**
    * Get authentication parameters for client-side upload
-   * @param fileType - Optional file type restriction (image, document, video, audio, all)
-   * @returns Authentication parameters (token, expire, signature)
+   * @param fileType - Optional file type restriction (IMAGE, DOCUMENT, VIDEO)
+   * @returns Authentication parameters (token, expire, signature, folder)
    */
   getAuthenticationParameters(fileType?: string) {
     try {
+      // Determine folder based on file type
+      const folder = fileType ? this.getFolderPath(fileType) : 'others';
+
+      // Generate auth params
       const authParams = this.imagekit.getAuthenticationParameters();
+
       this.logger.log(
-        `Generated authentication parameters for ImageKit upload${fileType && fileType !== 'all' ? ` (type: ${fileType})` : ''}`,
+        `Generated authentication parameters for ImageKit upload${fileType ? ` (type: ${fileType}, folder: ${folder})` : ''}`,
       );
+
       return {
         ...authParams,
-        ...(fileType && fileType !== 'all' && { fileType }),
+        folder, // Folder where file should be uploaded
+        ...(fileType && { fileType }),
       };
     } catch (error) {
       this.logger.error('Failed to generate authentication parameters', error);
@@ -37,6 +58,15 @@ export class ImagekitioService {
     }
   }
 
+  /**
+   * Clean URL by removing query parameters
+   * @param url - The URL to clean
+   * @returns Clean URL without query parameters
+   */
+  private cleanUrl(url: string): string {
+    return url.split('?')[0];
+  }
+
   /**
    * Get file ID from ImageKit URL
    * @param url - The ImageKit file URL
@@ -44,21 +74,22 @@ export class ImagekitioService {
    */
   async getFileIdByUrl(url: string): Promise<any> {
     try {
-      // Extract the file path from the URL
-      // Example: https://ik.imagekit.io/eihvofxmgsdfb/krishna_QnwprENpT.jpg
-      // Extract: /krishna_QnwprENpT.jpg
+      // Clean URL (remove query parameters like ?updatedAt=...)
+      const cleanUrl = this.cleanUrl(url);
+
       const urlEndpoint = this.configService.get<string>(
         'imagekitio.urlEndpoint',
       );
-      if (!url.startsWith(urlEndpoint || '')) {
+      if (!cleanUrl.startsWith(urlEndpoint || '')) {
         throw new NotFoundException(
           'Invalid ImageKit URL - does not match your URL endpoint',
         );
       }
 
-      const filePath = url.replace(urlEndpoint || '', '');
+      // Extract file path from URL
+      const filePath = cleanUrl.replace(urlEndpoint || '', '');
 
-      // Extract filename from path
+      // Extract filename from path (last part after /)
       const fileName = filePath.split('/').pop() || '';
 
       if (!fileName) {
@@ -71,24 +102,21 @@ export class ImagekitioService {
       });
 
       if (!files || files.length === 0) {
-        this.logger.warn(
-          `File not found with URL: ${url} - it may have been already deleted`,
-        );
+        this.logger.warn(`File not found: ${fileName}`);
         throw new NotFoundException('File not found or already deleted');
       }
 
-      // Find the exact match by comparing the full URL
-      const exactMatch = files.find((file: any) => file.url === url);
+      // Find exact match by comparing clean URLs
+      const exactMatch = files.find(
+        (file: any) => this.cleanUrl(file.url) === cleanUrl,
+      );
 
       if (!exactMatch) {
-        // If no exact match, the file might have been deleted
-        this.logger.warn(
-          `No exact URL match found for: ${url} - file may have been already deleted`,
-        );
+        this.logger.warn(`No exact match found for: ${fileName}`);
         throw new NotFoundException('File not found or already deleted');
       }
 
-      this.logger.log(`Found file ID for URL: ${url}`);
+      this.logger.log(`Found file: ${fileName}`);
       return exactMatch;
     } catch (error) {
       if (error instanceof NotFoundException) {
@@ -100,7 +128,24 @@ export class ImagekitioService {
   }
 
   /**
-   * Delete a file from ImageKit by URL
+   * Purge CDN cache for a URL
+   * @param url - The ImageKit file URL to purge from cache
+   * @returns Purge result
+   */
+  async purgeCdnCache(url: string): Promise<any> {
+    try {
+      const cleanUrl = this.cleanUrl(url);
+      const result = await this.imagekit.purgeCache(cleanUrl);
+      this.logger.log(`Successfully purged CDN cache for: ${cleanUrl}`);
+      return result;
+    } catch (error) {
+      this.logger.error(`Failed to purge CDN cache for URL: ${url}`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Delete a file from ImageKit by URL and purge CDN cache
    * @param url - The ImageKit file URL
    * @returns Deletion result
    */
@@ -112,9 +157,20 @@ export class ImagekitioService {
       throw new NotFoundException('Could not retrieve file ID from URL');
     }
 
-    // Then delete the file using the file ID
+    // Delete the file using the file ID
     const result = await this.deleteFile(fileDetails.fileId);
-    this.logger.log(`Successfully deleted file from URL: ${url}`);
+
+    // Purge CDN cache to make deletion immediate
+    try {
+      await this.purgeCdnCache(url);
+      this.logger.log(
+        `Successfully deleted file and purged cache for URL: ${url}`,
+      );
+    } catch {
+      this.logger.warn(
+        `File deleted but CDN cache purge failed for: ${url}. Cache will expire naturally.`,
+      );
+    }
 
     return {
       ...result,
@@ -124,11 +180,11 @@ export class ImagekitioService {
   }
 
   /**
-   * Delete a file from ImageKit
+   * Delete a file from ImageKit (private method used internally)
    * @param fileId - The file ID to delete
    * @returns Deletion result
    */
-  async deleteFile(fileId: string): Promise<any> {
+  private async deleteFile(fileId: string): Promise<any> {
     try {
       const result = await this.imagekit.deleteFile(fileId);
       this.logger.log(`Successfully deleted file with ID: ${fileId}`);
@@ -138,36 +194,4 @@ export class ImagekitioService {
       throw error;
     }
   }
-
-  /**
-   * Get file details from ImageKit
-   * @param fileId - The file ID
-   * @returns File details
-   */
-  async getFileDetails(fileId: string): Promise<any> {
-    try {
-      const fileDetails = await this.imagekit.getFileDetails(fileId);
-      return fileDetails;
-    } catch (error) {
-      this.logger.error(`Failed to get file details for ID: ${fileId}`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * List files from ImageKit
-   * @param options - List options (skip, limit, etc.)
-   * @returns List of files
-   */
-  async listFiles(
-    options: { skip?: number; limit?: number } = {},
-  ): Promise<any> {
-    try {
-      const files = await this.imagekit.listFiles(options);
-      return files;
-    } catch (error) {
-      this.logger.error('Failed to list files', error);
-      throw error;
-    }
-  }
 }