@nextsparkjs/theme-default 0.1.0-beta.92 → 0.1.0-beta.95

package/blocks/hero/fields.ts

@@ -21,7 +21,7 @@ const heroDesignFields: FieldDefinition[] = [
   {
     name: 'backgroundImage',
     label: 'Background Image',
-    type: 'image',
+    type: 'media-library',
     tab: 'design',
     required: false,
     helpText: 'Optional background image (recommended: 1920x1080px minimum)',

package/blocks/hero-with-form/fields.ts

@@ -34,7 +34,7 @@ const heroWithFormContentFields: FieldDefinition[] = [
   {
     name: 'backgroundImage',
     label: 'Background Image',
-    type: 'image',
+    type: 'media-library',
     tab: 'content',
     required: true,
     helpText: 'Full-width background image (recommended: 1920x1080px minimum)',

package/blocks/jumbotron/fields.ts

@@ -148,7 +148,7 @@ const jumbotronDesignFields: FieldDefinition[] = [
   {
     name: 'backgroundImage',
     label: 'Background Image',
-    type: 'image',
+    type: 'media-library',
     tab: 'design',
     required: false,
     helpText: 'Optional background image (recommended: 1920x1080px minimum)',

package/blocks/logo-cloud/fields.ts

@@ -30,7 +30,7 @@ const logoCloudContentFields: FieldDefinition[] = [
       {
         name: 'image',
         label: 'Logo Image',
-        type: 'image',
+        type: 'media-library',
         tab: 'content',
         required: true,
         helpText: 'Logo image URL (recommended: transparent PNG, 200x100px)',

package/blocks/split-content/fields.ts

@@ -46,7 +46,7 @@ const splitContentFields: FieldDefinition[] = [
   {
     name: 'image',
     label: 'Image',
-    type: 'image',
+    type: 'media-library',
     tab: 'content',
     required: true,
     helpText: 'Featured image (recommended: 800x600px minimum)',

package/blocks/testimonials/fields.ts

@@ -58,7 +58,7 @@ const testimonialsContentFields: FieldDefinition[] = [
       {
         name: 'avatar',
         label: 'Avatar Image',
-        type: 'image',
+        type: 'media-library',
         tab: 'content',
         required: false,
         description: 'Profile picture of the person',

package/blocks/video-hero/fields.ts

@@ -28,7 +28,7 @@ const videoHeroContentFields: FieldDefinition[] = [
   {
     name: 'videoThumbnail',
     label: 'Custom Thumbnail',
-    type: 'image',
+    type: 'media-library',
     tab: 'content',
     required: false,
     helpText: 'Optional custom thumbnail shown before video plays (recommended: 1920x1080px)',

package/config/app.config.ts

@@ -333,6 +333,23 @@ export const APP_CONFIG_OVERRIDES = {
     },
   },
 
+  // =============================================================================
+  // MEDIA LIBRARY OVERRIDES
+  // =============================================================================
+  // Uncomment and modify to customize media upload limits and accepted file types.
+  //
+  // media: {
+  //   maxSizeMB: 10,           // General fallback max size
+  //   maxSizeImageMB: 10,      // Max size for image/* files (overrides maxSizeMB)
+  //   maxSizeVideoMB: 50,      // Max size for video/* files (overrides maxSizeMB)
+  //   acceptedTypes: ['image/*', 'video/*', 'application/pdf'],
+  //   allowedMimeTypes: [
+  //     'image/jpeg', 'image/png', 'image/webp',
+  //     'video/mp4', 'video/webm',
+  //     'application/pdf',
+  //   ],
+  // },
+
   // =============================================================================
   // DEV KEYRING - MOVED TO dev.config.ts
   // =============================================================================

package/messages/en/navigation.json

@@ -4,5 +4,6 @@
   "support": "Support",
   "docs": "Documentation",
   "dashboard": "Dashboard",
-  "pages": "Pages"
+  "pages": "Pages",
+  "media": "Media"
 }

package/messages/es/navigation.json

@@ -4,5 +4,6 @@
   "support": "Soporte",
   "docs": "Documentación",
   "dashboard": "Panel",
-  "pages": "Páginas"
+  "pages": "Páginas",
+  "media": "Multimedia"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/theme-default",
-  "version": "0.1.0-beta.92",
+  "version": "0.1.0-beta.95",
   "private": false,
   "type": "module",
   "main": "./config/theme.config.ts",
@@ -24,4 +24,4 @@
     "type": "theme",
     "name": "default"
   }
-}
+}

package/styles/globals.css

@@ -12,6 +12,20 @@
    IMPORTS
    ============================================= */
 @import "tailwindcss";
+
+/* =============================================
+   TAILWIND v4 DARK MODE CONFIGURATION
+
+   Por defecto Tailwind v4 usa @media (prefers-color-scheme: dark)
+   para las variantes dark:. Esto causa problemas porque:
+   - next-themes usa la clase .dark en el HTML
+   - El sistema operativo puede tener dark mode aunque la app use light
+
+   Esta configuración hace que Tailwind use el selector de clase .dark
+   en lugar de la media query, sincronizándose con next-themes.
+   ============================================= */
+@custom-variant dark (&:where(.dark, .dark *));
+
 @plugin "@tailwindcss/container-queries";
 @import "@nextsparkjs/core/styles/ui.css";
 @import "@nextsparkjs/core/styles/utilities.css";

package/tests/cypress/e2e/api/entities/media/media-crud.cy.ts

@@ -0,0 +1,600 @@
+/**
+ * Media API - CRUD Tests
+ *
+ * Comprehensive test suite for Media API endpoints.
+ * Tests GET, PATCH, DELETE operations and upload functionality.
+ *
+ * Entity characteristics:
+ * - No team context required (global media library)
+ * - Soft delete (status → deleted)
+ * - Supports filtering by type, search by filename
+ * - Pagination via limit/offset
+ * - Sorting via orderBy/orderDir
+ */
+
+/// <reference types="cypress" />
+
+import * as allure from 'allure-cypress'
+
+const MediaAPIController = require('../../../../src/controllers/MediaAPIController.js')
+
+describe('Media API - CRUD Operations', {
+  tags: ['@api', '@feat-media-library', '@crud', '@regression']
+}, () => {
+  // Test constants
+  const SUPERADMIN_API_KEY = 'test_api_key_for_testing_purposes_only_not_a_real_secret_key_abc123'
+  const BASE_URL = Cypress.config('baseUrl') || 'http://localhost:5173'
+
+  // Controller instance
+  let mediaAPI: InstanceType<typeof MediaAPIController>
+
+  // Track created media for cleanup
+  let createdMedia: any[] = []
+
+  before(() => {
+    // Initialize controller with superadmin credentials
+    mediaAPI = new MediaAPIController(BASE_URL, SUPERADMIN_API_KEY)
+  })
+
+  beforeEach(() => {
+    allure.epic('API')
+    allure.feature('Media Library')
+  })
+
+  afterEach(() => {
+    // Cleanup created media after each test
+    createdMedia.forEach((media) => {
+      if (media?.id) {
+        mediaAPI.deleteMedia(media.id)
+      }
+    })
+    createdMedia = []
+  })
+
+  // ============================================
+  // GET /api/v1/media - List Media
+  // ============================================
+  describe('GET /api/v1/media - List Media', () => {
+    it('MEDIA_API_001: Should list media with valid API key', { tags: '@smoke' }, () => {
+      allure.story('CRUD Operations')
+      allure.severity('critical')
+
+      mediaAPI.getMedia().then((response: any) => {
+        mediaAPI.validateSuccessResponse(response, 200)
+        expect(response.body.data).to.be.an('array')
+        expect(response.body.info).to.have.property('limit')
+        expect(response.body.info).to.have.property('offset')
+        expect(response.body.info).to.have.property('total')
+
+        cy.log(`Found ${response.body.data.length} media items`)
+      })
+    })
+
+    it('MEDIA_API_002: Should list media with pagination (limit/offset)', () => {
+      mediaAPI.getMedia({ limit: 5, offset: 0 }).then((response: any) => {
+        mediaAPI.validateSuccessResponse(response, 200)
+        expect(response.body.info.limit).to.eq(5)
+        expect(response.body.info.offset).to.eq(0)
+        expect(response.body.data.length).to.be.at.most(5)
+
+        cy.log(`Page 1 with limit 5: ${response.body.data.length} media items`)
+      })
+    })
+
+    it('MEDIA_API_003: Should filter media by type=image', () => {
+      mediaAPI.getMedia({ type: 'image' }).then((response: any) => {
+        mediaAPI.validateSuccessResponse(response, 200)
+        expect(response.body.data).to.be.an('array')
+
+        // All returned items should have type=image
+        response.body.data.forEach((media: any) => {
+          expect(media.type).to.eq('image')
+        })
+
+        cy.log(`Found ${response.body.data.length} images`)
+      })
+    })
+
+    it('MEDIA_API_004: Should filter media by type=video', () => {
+      mediaAPI.getMedia({ type: 'video' }).then((response: any) => {
+        mediaAPI.validateSuccessResponse(response, 200)
+        expect(response.body.data).to.be.an('array')
+
+        // All returned items should have type=video
+        response.body.data.forEach((media: any) => {
+          expect(media.type).to.eq('video')
+        })
+
+        cy.log(`Found ${response.body.data.length} videos`)
+      })
+    })
+
+    it('MEDIA_API_005: Should search media by filename', () => {
+      // This test assumes there's existing media with searchable filenames
+      // If no media exists, search returns empty array (still valid)
+      const searchTerm = 'test'
+
+      mediaAPI.getMedia({ search: searchTerm }).then((response: any) => {
+        mediaAPI.validateSuccessResponse(response, 200)
+        expect(response.body.data).to.be.an('array')
+
+        cy.log(`Search '${searchTerm}' found ${response.body.data.length} results`)
+      })
+    })
+
+    it('MEDIA_API_006: Should sort media by filename (ascending)', () => {
+      mediaAPI.getMedia({ orderBy: 'filename', orderDir: 'asc', limit: 10 }).then((response: any) => {
+        mediaAPI.validateSuccessResponse(response, 200)
+        expect(response.body.data).to.be.an('array')
+
+        if (response.body.data.length > 1) {
+          // Verify ascending order
+          const filenames = response.body.data.map((m: any) => m.filename)
+          const sorted = [...filenames].sort()
+          expect(filenames).to.deep.eq(sorted)
+        }
+
+        cy.log(`Sorted ${response.body.data.length} items by filename (asc)`)
+      })
+    })
+
+    it('MEDIA_API_007: Should sort media by uploadedAt (descending)', () => {
+      mediaAPI.getMedia({ orderBy: 'uploadedAt', orderDir: 'desc', limit: 10 }).then((response: any) => {
+        mediaAPI.validateSuccessResponse(response, 200)
+        expect(response.body.data).to.be.an('array')
+
+        if (response.body.data.length > 1) {
+          // Verify descending order by uploadedAt
+          const timestamps = response.body.data.map((m: any) => new Date(m.uploadedAt).getTime())
+          for (let i = 0; i < timestamps.length - 1; i++) {
+            expect(timestamps[i]).to.be.at.least(timestamps[i + 1])
+          }
+        }
+
+        cy.log(`Sorted ${response.body.data.length} items by uploadedAt (desc)`)
+      })
+    })
+
+    it('MEDIA_API_008: Should return empty array for non-matching search', () => {
+      const nonExistentTerm = 'NonExistentMediaFilename123456789'
+
+      mediaAPI.getMedia({ search: nonExistentTerm }).then((response: any) => {
+        mediaAPI.validateSuccessResponse(response, 200)
+        expect(response.body.data).to.be.an('array')
+        expect(response.body.data.length).to.eq(0)
+
+        cy.log('Search with non-matching term returns empty array')
+      })
+    })
+
+    it('MEDIA_API_009: Should reject request without API key', () => {
+      const noAuthAPI = new MediaAPIController(BASE_URL, null)
+
+      noAuthAPI.getMedia().then((response: any) => {
+        expect(response.status).to.eq(401)
+        expect(response.body).to.have.property('success', false)
+
+        cy.log('Request without API key rejected with 401')
+      })
+    })
+  })
+
+  // ============================================
+  // GET /api/v1/media/{id} - Get Media by ID
+  // ============================================
+  describe('GET /api/v1/media/{id} - Get Media by ID', () => {
+    let testMediaId: string
+
+    beforeEach(() => {
+      // Get first media item from list for testing
+      mediaAPI.getMedia({ limit: 1 }).then((response: any) => {
+        if (response.body.data.length > 0) {
+          testMediaId = response.body.data[0].id
+        }
+      })
+    })
+
+    it('MEDIA_API_010: Should get media by valid ID', () => {
+      cy.then(() => {
+        if (!testMediaId) {
+          cy.log('No media items available to test')
+          return
+        }
+
+        mediaAPI.getMediaById(testMediaId).then((response: any) => {
+          mediaAPI.validateSuccessResponse(response, 200)
+
+          const media = response.body.data
+          mediaAPI.validateMediaObject(media)
+          expect(media.id).to.eq(testMediaId)
+
+          cy.log(`Retrieved media: ${media.filename}`)
+        })
+      })
+    })
+
+    it('MEDIA_API_011: Should return 404 for non-existent media', () => {
+      const fakeId = 'non-existent-media-id-12345'
+
+      mediaAPI.getMediaById(fakeId).then((response: any) => {
+        expect(response.status).to.eq(404)
+        expect(response.body).to.have.property('success', false)
+
+        cy.log('Non-existent media returns 404')
+      })
+    })
+  })
+
+  // ============================================
+  // PATCH /api/v1/media/{id} - Update Media Metadata
+  // ============================================
+  describe('PATCH /api/v1/media/{id} - Update Media Metadata', () => {
+    let testMediaId: string
+
+    beforeEach(() => {
+      // Get first media item for testing
+      mediaAPI.getMedia({ limit: 1 }).then((response: any) => {
+        if (response.body.data.length > 0) {
+          testMediaId = response.body.data[0].id
+        }
+      })
+    })
+
+    it('MEDIA_API_020: Should update media alt text', () => {
+      cy.then(() => {
+        if (!testMediaId) {
+          cy.log('No media items available to test')
+          return
+        }
+
+        const updateData = {
+          alt: 'Updated alt text for testing'
+        }
+
+        mediaAPI.updateMedia(testMediaId, updateData).then((response: any) => {
+          mediaAPI.validateSuccessResponse(response, 200)
+
+          const media = response.body.data
+          expect(media.alt).to.eq(updateData.alt)
+
+          cy.log(`Updated media alt: ${media.alt}`)
+        })
+      })
+    })
+
+    it('MEDIA_API_021: Should update media caption', () => {
+      cy.then(() => {
+        if (!testMediaId) {
+          cy.log('No media items available to test')
+          return
+        }
+
+        const updateData = {
+          caption: 'Updated caption for testing'
+        }
+
+        mediaAPI.updateMedia(testMediaId, updateData).then((response: any) => {
+          mediaAPI.validateSuccessResponse(response, 200)
+
+          const media = response.body.data
+          expect(media.caption).to.eq(updateData.caption)
+
+          cy.log(`Updated media caption: ${media.caption}`)
+        })
+      })
+    })
+
+    it('MEDIA_API_022: Should update both alt and caption', () => {
+      cy.then(() => {
+        if (!testMediaId) {
+          cy.log('No media items available to test')
+          return
+        }
+
+        const updateData = {
+          alt: 'Updated alt text',
+          caption: 'Updated caption'
+        }
+
+        mediaAPI.updateMedia(testMediaId, updateData).then((response: any) => {
+          mediaAPI.validateSuccessResponse(response, 200)
+
+          const media = response.body.data
+          expect(media.alt).to.eq(updateData.alt)
+          expect(media.caption).to.eq(updateData.caption)
+
+          cy.log(`Updated both alt and caption`)
+        })
+      })
+    })
+
+    it('MEDIA_API_023: Should return 404 for non-existent media', () => {
+      const fakeId = 'non-existent-media-id-12345'
+
+      mediaAPI.updateMedia(fakeId, { alt: 'New Alt' }).then((response: any) => {
+        expect(response.status).to.eq(404)
+        expect(response.body).to.have.property('success', false)
+
+        cy.log('Update non-existent media returns 404')
+      })
+    })
+
+    it('MEDIA_API_024: Should reject empty update body', () => {
+      cy.then(() => {
+        if (!testMediaId) {
+          cy.log('No media items available to test')
+          return
+        }
+
+        mediaAPI.updateMedia(testMediaId, {}).then((response: any) => {
+          expect(response.status).to.eq(400)
+          expect(response.body).to.have.property('success', false)
+
+          cy.log('Empty update body rejected')
+        })
+      })
+    })
+
+    it('MEDIA_API_025: Should reject invalid update fields (only alt/caption allowed)', () => {
+      cy.then(() => {
+        if (!testMediaId) {
+          cy.log('No media items available to test')
+          return
+        }
+
+        // Try to update filename (should be rejected)
+        const invalidUpdate = {
+          filename: 'hacked-filename.jpg'
+        }
+
+        mediaAPI.updateMedia(testMediaId, invalidUpdate).then((response: any) => {
+          // Should return 400 (validation error) or ignore the invalid field
+          // Backend should only allow alt/caption updates
+          expect(response.status).to.be.oneOf([200, 400])
+
+          if (response.status === 200) {
+            // If 200, filename should NOT be changed
+            expect(response.body.data.filename).to.not.eq(invalidUpdate.filename)
+          }
+
+          cy.log('Invalid field update handled correctly')
+        })
+      })
+    })
+  })
+
+  // ============================================
+  // DELETE /api/v1/media/{id} - Soft Delete Media
+  // ============================================
+  describe('DELETE /api/v1/media/{id} - Soft Delete Media', () => {
+    let testMediaId: string
+
+    beforeEach(() => {
+      // Get a media item that can be deleted
+      mediaAPI.getMedia({ limit: 1, type: 'image' }).then((response: any) => {
+        if (response.body.data.length > 0) {
+          testMediaId = response.body.data[0].id
+        }
+      })
+    })
+
+    it('MEDIA_API_030: Should soft delete media by valid ID', () => {
+      cy.then(() => {
+        if (!testMediaId) {
+          cy.log('No media items available to test deletion')
+          return
+        }
+
+        // Delete the media
+        mediaAPI.deleteMedia(testMediaId).then((response: any) => {
+          mediaAPI.validateSuccessResponse(response, 200)
+          expect(response.body.data).to.have.property('success', true)
+          expect(response.body.data).to.have.property('id', testMediaId)
+
+          cy.log(`Soft deleted media: ${testMediaId}`)
+
+          // Verify soft delete: item should return 404 or status=deleted
+          mediaAPI.getMediaById(testMediaId).then((getResponse: any) => {
+            // After soft delete, GET should return 404 (filtered out)
+            expect(getResponse.status).to.eq(404)
+
+            cy.log('Verified soft deletion - media no longer accessible')
+          })
+        })
+      })
+    })
+
+    it('MEDIA_API_031: Should return 404 for non-existent media', () => {
+      const fakeId = 'non-existent-media-id-12345'
+
+      mediaAPI.deleteMedia(fakeId).then((response: any) => {
+        expect(response.status).to.eq(404)
+        expect(response.body).to.have.property('success', false)
+
+        cy.log('Delete non-existent media returns 404')
+      })
+    })
+
+    it('MEDIA_API_032: Should return 404 when deleting already deleted media', () => {
+      cy.then(() => {
+        if (!testMediaId) {
+          cy.log('No media items available to test')
+          return
+        }
+
+        // Delete once
+        mediaAPI.deleteMedia(testMediaId).then((deleteResponse: any) => {
+          expect(deleteResponse.status).to.eq(200)
+
+          // Try to delete again
+          mediaAPI.deleteMedia(testMediaId).then((secondDeleteResponse: any) => {
+            expect(secondDeleteResponse.status).to.eq(404)
+            expect(secondDeleteResponse.body).to.have.property('success', false)
+
+            cy.log('Second delete attempt correctly returns 404')
+          })
+        })
+      })
+    })
+  })
+
+  // ============================================
+  // Authentication Tests
+  // ============================================
+  describe('Authentication', () => {
+    it('MEDIA_API_040: Should accept session authentication', () => {
+      // Login as superadmin and use session cookies
+      cy.login('superadmin@tmt.dev', 'Test1234')
+
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}/api/v1/media`,
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(200)
+        expect(response.body.success).to.be.true
+
+        cy.log('Session authentication successful')
+      })
+    })
+
+    it('MEDIA_API_041: Should accept API key authentication', () => {
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}/api/v1/media`,
+        headers: {
+          'Authorization': `Bearer ${SUPERADMIN_API_KEY}`
+        },
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(200)
+        expect(response.body.success).to.be.true
+
+        cy.log('API key authentication successful')
+      })
+    })
+
+    it('MEDIA_API_042: Should return 401 without authentication', () => {
+      cy.request({
+        method: 'GET',
+        url: `${BASE_URL}/api/v1/media`,
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+        expect(response.body.success).to.be.false
+
+        cy.log('No authentication returns 401')
+      })
+    })
+  })
+
+  // ============================================
+  // Edge Cases & Error Handling
+  // ============================================
+  describe('Edge Cases & Error Handling', () => {
+    it('MEDIA_API_050: Should handle invalid limit parameter', () => {
+      mediaAPI.getMedia({ limit: -1 }).then((response: any) => {
+        // Backend should either reject with 400 or use default limit
+        expect(response.status).to.be.oneOf([200, 400])
+
+        if (response.status === 200) {
+          // If accepted, should use default limit (not negative)
+          expect(response.body.info.limit).to.be.greaterThan(0)
+        }
+
+        cy.log('Invalid limit handled correctly')
+      })
+    })
+
+    it('MEDIA_API_051: Should handle invalid offset parameter', () => {
+      mediaAPI.getMedia({ offset: -1 }).then((response: any) => {
+        // Backend should either reject with 400 or use default offset (0)
+        expect(response.status).to.be.oneOf([200, 400])
+
+        if (response.status === 200) {
+          expect(response.body.info.offset).to.be.at.least(0)
+        }
+
+        cy.log('Invalid offset handled correctly')
+      })
+    })
+
+    it('MEDIA_API_052: Should handle invalid type filter', () => {
+      mediaAPI.getMedia({ type: 'invalid-type' }).then((response: any) => {
+        // Backend should either reject with 400 or return empty results
+        expect(response.status).to.be.oneOf([200, 400])
+
+        if (response.status === 200) {
+          // Should return empty array for invalid type
+          expect(response.body.data).to.be.an('array')
+        }
+
+        cy.log('Invalid type filter handled correctly')
+      })
+    })
+
+    it('MEDIA_API_053: Should handle invalid orderBy field', () => {
+      mediaAPI.getMedia({ orderBy: 'invalid-field' }).then((response: any) => {
+        // Backend should either reject with 400 or ignore invalid orderBy
+        expect(response.status).to.be.oneOf([200, 400])
+
+        cy.log('Invalid orderBy handled correctly')
+      })
+    })
+  })
+
+  // ============================================
+  // Integration - Read -> Update -> Delete Lifecycle
+  // ============================================
+  describe('Integration - Read -> Update -> Delete Lifecycle', () => {
+    it('MEDIA_API_100: Should complete lifecycle: Read -> Update -> Delete', () => {
+      // Get first available media item
+      mediaAPI.getMedia({ limit: 1 }).then((listResponse: any) => {
+        if (listResponse.body.data.length === 0) {
+          cy.log('No media items available for lifecycle test')
+          return
+        }
+
+        const mediaId = listResponse.body.data[0].id
+
+        // 1. READ
+        mediaAPI.getMediaById(mediaId).then((readResponse: any) => {
+          mediaAPI.validateSuccessResponse(readResponse, 200)
+          const originalFilename = readResponse.body.data.filename
+
+          cy.log(`1. Read media: ${originalFilename}`)
+
+          // 2. UPDATE
+          const updateData = {
+            alt: 'Lifecycle Test Alt',
+            caption: 'Lifecycle Test Caption'
+          }
+
+          mediaAPI.updateMedia(mediaId, updateData).then((updateResponse: any) => {
+            mediaAPI.validateSuccessResponse(updateResponse, 200)
+            expect(updateResponse.body.data.alt).to.eq(updateData.alt)
+            expect(updateResponse.body.data.caption).to.eq(updateData.caption)
+
+            cy.log(`2. Updated media metadata`)
+
+            // 3. DELETE
+            mediaAPI.deleteMedia(mediaId).then((deleteResponse: any) => {
+              mediaAPI.validateSuccessResponse(deleteResponse, 200)
+              expect(deleteResponse.body.data).to.have.property('success', true)
+
+              cy.log(`3. Deleted media: ${mediaId}`)
+
+              // 4. VERIFY DELETION
+              mediaAPI.getMediaById(mediaId).then((verifyResponse: any) => {
+                expect(verifyResponse.status).to.eq(404)
+
+                cy.log('4. Verified deletion - media no longer accessible')
+                cy.log('Full lifecycle completed successfully!')
+              })
+            })
+          })
+        })
+      })
+    })
+  })
+})

package/tests/cypress/src/controllers/MediaAPIController.js

@@ -0,0 +1,231 @@
+/**
+ * MediaAPIController - Controller for interacting with the Media API
+ * Encapsulates all CRUD operations for /api/v1/media endpoints
+ *
+ * Requires:
+ * - API Key with media:read, media:write, media:delete scopes (or superadmin with *)
+ */
+const BaseAPIController = require('./BaseAPIController')
+
+class MediaAPIController extends BaseAPIController {
+  /**
+   * @param {string} baseUrl - Base URL for API requests
+   * @param {string|null} apiKey - API key for authentication
+   */
+  constructor(baseUrl = 'http://localhost:5173', apiKey = null) {
+    // Media does not require x-team-id (no team context)
+    super(baseUrl, apiKey, null, { slug: 'media' })
+  }
+
+  // ============================================================
+  // SEMANTIC ALIASES (for backward compatibility)
+  // ============================================================
+
+  /**
+   * GET /api/v1/media - Get list of media items
+   * @param {Object} options - Query options
+   * @param {number} [options.limit] - Results per page (default: 20)
+   * @param {number} [options.offset] - Offset for pagination (default: 0)
+   * @param {string} [options.type] - Filter by type (image, video, document, audio)
+   * @param {string} [options.search] - Search in filename
+   * @param {string} [options.orderBy] - Sort field (filename, uploadedAt, size, etc.)
+   * @param {string} [options.orderDir] - Sort direction (asc, desc)
+   * @param {Object} [options.headers] - Additional headers
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  getMedia(options = {}) {
+    return this.list(options)
+  }
+
+  /**
+   * GET /api/v1/media/{id} - Get specific media item by ID
+   * @param {string} id - Media ID
+   * @param {Object} options - Additional options
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  getMediaById(id, options = {}) {
+    return this.getById(id, options)
+  }
+
+  /**
+   * PATCH /api/v1/media/{id} - Update media metadata
+   * @param {string} id - Media ID
+   * @param {Object} updateData - Data to update
+   * @param {string} [updateData.alt] - Alt text for image
+   * @param {string} [updateData.caption] - Caption for media
+   * @param {Object} options - Additional options
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  updateMedia(id, updateData, options = {}) {
+    return this.update(id, updateData, options)
+  }
+
+  /**
+   * DELETE /api/v1/media/{id} - Soft delete media item (status -> deleted)
+   * @param {string} id - Media ID
+   * @param {Object} options - Additional options
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  deleteMedia(id, options = {}) {
+    return this.delete(id, options)
+  }
+
+  /**
+   * POST /api/v1/media/upload - Upload file(s)
+   * @param {File|File[]} files - File or array of files to upload
+   * @param {Object} options - Additional options
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  uploadMedia(files, options = {}) {
+    const { headers = {} } = options
+    const formData = new FormData()
+
+    // Handle single file or array of files
+    const fileArray = Array.isArray(files) ? files : [files]
+    fileArray.forEach((file) => {
+      formData.append('files', file)
+    })
+
+    // Note: For FormData, Content-Type should be auto-set by browser/Cypress
+    const uploadHeaders = { ...this.getHeaders(headers) }
+    delete uploadHeaders['Content-Type'] // Let Cypress set multipart boundary
+
+    return cy.request({
+      method: 'POST',
+      url: `${this.baseUrl}/api/v1/media/upload`,
+      headers: uploadHeaders,
+      body: formData,
+      failOnStatusCode: false
+    })
+  }
+
+  // ============================================================
+  // DATA GENERATORS
+  // ============================================================
+
+  /**
+   * Generate random media data for testing
+   * @param {Object} overrides - Specific data to override
+   * @returns {Object} Generated media data
+   */
+  generateRandomMediaData(overrides = {}) {
+    const timestamp = Date.now()
+    const randomId = Math.random().toString(36).substring(2, 8)
+
+    return {
+      filename: `test-image-${randomId}-${timestamp}.jpg`,
+      alt: `Alt text for test image ${randomId}`,
+      caption: `Caption for test image ${randomId}`,
+      type: 'image',
+      size: Math.floor(100000 + Math.random() * 900000), // Random size
+      mimeType: 'image/jpeg',
+      ...overrides
+    }
+  }
+
+  /**
+   * Create a test media item and return its data
+   * Note: This creates a DB record without actual file upload (for testing)
+   * @param {Object} mediaData - Media data (optional)
+   * @returns {Cypress.Chainable} Promise resolving with created media data
+   */
+  createTestMedia(mediaData = {}) {
+    const data = this.generateRandomMediaData(mediaData)
+    return this.create(data).then((response) => {
+      if (response.status === 201) {
+        return response.body.data
+      }
+      throw new Error(`Failed to create test media: ${response.status}`)
+    })
+  }
+
+  /**
+   * Clean up a test media item (delete it)
+   * @param {string} id - Media ID
+   * @returns {Cypress.Chainable} Delete response
+   */
+  cleanupTestMedia(id) {
+    return this.deleteMedia(id)
+  }
+
+  // ============================================================
+  // ENTITY-SPECIFIC VALIDATORS
+  // ============================================================
+
+  /**
+   * Validate media object structure
+   * @param {Object} media - Media object
+   */
+  validateMediaObject(media) {
+    // Base fields
+    this.validateBaseEntityFields(media)
+
+    // Required media fields
+    expect(media).to.have.property('filename')
+    expect(media.filename).to.be.a('string')
+
+    expect(media).to.have.property('url')
+    expect(media.url).to.be.a('string')
+
+    expect(media).to.have.property('type')
+    expect(media.type).to.be.oneOf(['image', 'video', 'document', 'audio'])
+
+    expect(media).to.have.property('size')
+    expect(media.size).to.be.a('number')
+
+    expect(media).to.have.property('mimeType')
+    expect(media.mimeType).to.be.a('string')
+
+    expect(media).to.have.property('status')
+    expect(media.status).to.be.oneOf(['active', 'deleted'])
+
+    // Optional fields
+    if (media.alt !== null && media.alt !== undefined) {
+      expect(media.alt).to.be.a('string')
+    }
+
+    if (media.caption !== null && media.caption !== undefined) {
+      expect(media.caption).to.be.a('string')
+    }
+
+    if (media.thumbnailUrl !== null && media.thumbnailUrl !== undefined) {
+      expect(media.thumbnailUrl).to.be.a('string')
+    }
+
+    // Timestamps
+    expect(media).to.have.property('uploadedAt')
+    if (media.uploadedAt) {
+      expect(media.uploadedAt).to.be.a('string')
+    }
+  }
+
+  /**
+   * Validate upload response structure
+   * @param {Object} response - Upload response body
+   */
+  validateUploadResponse(response) {
+    expect(response).to.have.property('success', true)
+    expect(response).to.have.property('urls')
+    expect(response.urls).to.be.an('array')
+
+    expect(response).to.have.property('media')
+    expect(response.media).to.be.an('array')
+
+    expect(response).to.have.property('count')
+    expect(response.count).to.be.a('number')
+    expect(response.count).to.eq(response.urls.length)
+    expect(response.count).to.eq(response.media.length)
+
+    expect(response).to.have.property('storage')
+    expect(response.storage).to.have.property('provider')
+    expect(response.storage).to.have.property('bucket')
+  }
+}
+
+// Export class for use in tests
+module.exports = MediaAPIController
+
+// For global use in Cypress
+if (typeof window !== 'undefined') {
+  window.MediaAPIController = MediaAPIController
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 NextSpark
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.