@nextsparkjs/theme-default 0.1.0-beta.17 → 0.1.0-beta.170

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

@@ -0,0 +1,251 @@
+/**
+ * CustomerAPIController - Controller for interacting with the Customers API
+ * Encapsulates all CRUD operations for /api/v1/customers endpoints
+ *
+ * Requires:
+ * - API Key with customers:read, customers:write scopes (or superadmin with *)
+ * - x-team-id header for team context
+ */
+const BaseAPIController = require('./BaseAPIController')
+const entitiesConfig = require('../../fixtures/entities.json')
+
+const { slug } = entitiesConfig.entities.customers
+
+class CustomerAPIController extends BaseAPIController {
+  /**
+   * @param {string} baseUrl - Base URL for API requests
+   * @param {string|null} apiKey - API key for authentication
+   * @param {string|null} teamId - Team ID for x-team-id header
+   */
+  constructor(baseUrl = 'http://localhost:5173', apiKey = null, teamId = null) {
+    super(baseUrl, apiKey, teamId, { slug })
+    // Counter for generating unique account numbers
+    this.accountCounter = Date.now()
+  }
+
+  // ============================================================
+  // SEMANTIC ALIASES (for backward compatibility)
+  // ============================================================
+
+  /**
+   * GET /api/v1/customers - Get list of customers
+   * @param {Object} options - Query options
+   * @param {number} [options.page] - Page number
+   * @param {number} [options.limit] - Results per page
+   * @param {string} [options.office] - Filter by office
+   * @param {string} [options.salesRep] - Filter by salesRep
+   * @param {string} [options.metas] - Metadata parameter ('all', 'key1,key2', etc.)
+   * @param {string} [options.search] - Search in name/account/office
+   * @param {Object} [options.headers] - Additional headers
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  getCustomers(options = {}) {
+    return this.list(options)
+  }
+
+  /**
+   * GET /api/v1/customers/{id} - Get specific customer by ID
+   * @param {string} id - Customer ID
+   * @param {Object} options - Additional options
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  getCustomerById(id, options = {}) {
+    return this.getById(id, options)
+  }
+
+  /**
+   * POST /api/v1/customers - Create new customer
+   * @param {Object} customerData - Customer data
+   * @param {string} customerData.name - Customer name (required)
+   * @param {number} customerData.account - Account number (required, must be unique)
+   * @param {string} customerData.office - Customer office (required)
+   * @param {string} [customerData.phone] - Phone number
+   * @param {string} [customerData.salesRep] - Sales representative
+   * @param {string[]} [customerData.visitDays] - Array of visit days
+   * @param {string[]} [customerData.contactDays] - Array of contact days
+   * @param {Object} [customerData.metas] - Metadata object
+   * @param {Object} options - Additional options
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  createCustomer(customerData, options = {}) {
+    return this.create(customerData, options)
+  }
+
+  /**
+   * PATCH /api/v1/customers/{id} - Update customer
+   * @param {string} id - Customer ID
+   * @param {Object} updateData - Data to update
+   * @param {Object} options - Additional options
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  updateCustomer(id, updateData, options = {}) {
+    return this.update(id, updateData, options)
+  }
+
+  /**
+   * DELETE /api/v1/customers/{id} - Delete customer
+   * @param {string} id - Customer ID
+   * @param {Object} options - Additional options
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  deleteCustomer(id, options = {}) {
+    return this.delete(id, options)
+  }
+
+  // ============================================================
+  // DATA GENERATORS
+  // ============================================================
+
+  /**
+   * Generate a unique account number
+   * Uses timestamp + counter to ensure uniqueness
+   * @returns {number} Unique account number
+   */
+  generateUniqueAccount() {
+    this.accountCounter++
+    // Use last 9 digits to stay within INTEGER range
+    return parseInt(String(this.accountCounter).slice(-9))
+  }
+
+  /**
+   * Generate random customer data for testing
+   * @param {Object} overrides - Specific data to override
+   * @returns {Object} Generated customer data
+   */
+  generateRandomData(overrides = {}) {
+    return this.generateRandomCustomerData(overrides)
+  }
+
+  /**
+   * Generate random customer data for testing
+   * @param {Object} overrides - Specific data to override
+   * @returns {Object} Generated customer data
+   */
+  generateRandomCustomerData(overrides = {}) {
+    const timestamp = Date.now()
+    const randomId = Math.random().toString(36).substring(2, 8)
+
+    return {
+      name: `Test Customer ${randomId} - ${timestamp}`,
+      account: this.generateUniqueAccount(),
+      office: `Office-${randomId}`,
+      phone: `+1-555-${Math.floor(1000 + Math.random() * 9000)}`,
+      salesRep: `Sales Rep ${randomId}`,
+      visitDays: [],
+      contactDays: [],
+      ...overrides
+    }
+  }
+
+  /**
+   * Create a test customer and return its data
+   * @param {Object} customerData - Customer data (optional)
+   * @returns {Cypress.Chainable} Promise resolving with created customer data
+   */
+  createTestCustomer(customerData = {}) {
+    return this.createTestEntity(customerData)
+  }
+
+  /**
+   * Clean up a test customer (delete it)
+   * @param {string} id - Customer ID
+   * @returns {Cypress.Chainable} Delete response
+   */
+  cleanupTestCustomer(id) {
+    return this.cleanup(id)
+  }
+
+  // ============================================================
+  // ENTITY-SPECIFIC VALIDATORS
+  // ============================================================
+
+  /**
+   * Validate customer object structure
+   * @param {Object} customer - Customer object
+   * @param {boolean} allowMetas - If metas property is allowed
+   */
+  validateCustomerObject(customer, allowMetas = false) {
+    // Base fields
+    this.validateBaseEntityFields(customer)
+
+    // Required entity fields
+    expect(customer).to.have.property('name')
+    expect(customer.name).to.be.a('string')
+
+    expect(customer).to.have.property('account')
+    // Account can be number or string depending on how PostgreSQL returns it
+    expect(typeof customer.account === 'number' || typeof customer.account === 'string').to.be.true
+
+    expect(customer).to.have.property('office')
+    expect(customer.office).to.be.a('string')
+
+    // Optional fields that can be null
+    if (customer.phone !== null && customer.phone !== undefined) {
+      expect(customer.phone).to.be.a('string')
+    }
+
+    if (customer.salesRep !== null && customer.salesRep !== undefined) {
+      expect(customer.salesRep).to.be.a('string')
+    }
+
+    // JSONB array fields
+    expect(customer).to.have.property('visitDays')
+    expect(customer.visitDays).to.be.an('array')
+
+    expect(customer).to.have.property('contactDays')
+    expect(customer.contactDays).to.be.an('array')
+
+    // Validate metas if present
+    if (allowMetas && customer.hasOwnProperty('metas')) {
+      expect(customer.metas).to.be.an('object')
+    }
+  }
+
+  // ============================================================
+  // METADATA HELPERS
+  // ============================================================
+
+  /**
+   * Generate sample metadata for testing
+   * @param {string} type - Type of metadata ('contactPreferences', 'billing', 'notes')
+   * @returns {Object} Sample metadata
+   */
+  generateSampleMetadata(type = 'contactPreferences') {
+    const sampleMetas = {
+      contactPreferences: {
+        preferredTime: 'morning',
+        preferredChannel: 'phone',
+        language: 'es',
+        doNotContact: false
+      },
+      billing: {
+        paymentTerms: 'net30',
+        creditLimit: 50000,
+        taxExempt: false,
+        currency: 'USD'
+      },
+      notes: {
+        lastContact: '2025-12-01T10:00:00Z',
+        nextFollowUp: '2025-12-15T10:00:00Z',
+        accountManager: 'John Doe',
+        priority: 'high'
+      },
+      customFields: {
+        industry: 'Technology',
+        segment: 'Enterprise',
+        referralSource: 'Website',
+        loyaltyTier: 'Gold'
+      }
+    }
+
+    return { [type]: sampleMetas[type] || sampleMetas.contactPreferences }
+  }
+}
+
+// Export class for use in tests
+module.exports = CustomerAPIController
+
+// For global use in Cypress
+if (typeof window !== 'undefined') {
+  window.CustomerAPIController = CustomerAPIController
+}

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/tests/cypress/src/controllers/PagesAPIController.js

@@ -0,0 +1,226 @@
+/**
+ * PagesAPIController - Controller for interacting with the Pages API
+ * Encapsulates all CRUD operations for /api/v1/pages endpoints
+ *
+ * Requires:
+ * - API Key with pages:read, pages:write scopes (or superadmin with *)
+ * - x-team-id header for team context
+ *
+ * Entity characteristics:
+ * - Required fields: slug, title, blocks, locale
+ * - Optional fields: SEO fields
+ * - Unique constraint: slug + locale
+ * - Status system: draft, published, scheduled, archived
+ * - Uses PATCH for updates
+ */
+const BaseAPIController = require('./BaseAPIController')
+const entitiesConfig = require('../../fixtures/entities.json')
+
+const { slug } = entitiesConfig.entities.pages
+
+class PagesAPIController extends BaseAPIController {
+  /**
+   * @param {string} baseUrl - Base URL for API requests
+   * @param {string|null} apiKey - API key for authentication
+   * @param {string|null} teamId - Team ID for x-team-id header
+   */
+  constructor(baseUrl = 'http://localhost:5173', apiKey = null, teamId = null) {
+    super(baseUrl, apiKey, teamId, { slug })
+  }
+
+  // ============================================================
+  // SEMANTIC ALIASES (for better readability in tests)
+  // ============================================================
+
+  /**
+   * GET /api/v1/pages - List pages
+   * @param {Object} options - Query options
+   * @param {number} [options.page] - Page number
+   * @param {number} [options.limit] - Results per page
+   * @param {string} [options.status] - Filter by status (draft, published, scheduled, archived)
+   * @param {string} [options.locale] - Filter by locale
+   * @param {string} [options.search] - Search in title
+   * @param {string} [options.metas] - Metadata parameter
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  getPages(options = {}) {
+    return this.list(options)
+  }
+
+  /**
+   * GET /api/v1/pages/{id} - Get page by ID
+   * @param {string} id - Page ID
+   * @param {Object} options - Additional options
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  getPageById(id, options = {}) {
+    return this.getById(id, options)
+  }
+
+  /**
+   * POST /api/v1/pages - Create page
+   * @param {Object} pageData - Page data
+   * @param {string} pageData.slug - Page slug (required)
+   * @param {string} pageData.title - Page title (required)
+   * @param {string} pageData.locale - Page locale (required)
+   * @param {Array} pageData.blocks - Page blocks (required)
+   * @param {string} [pageData.status] - Status (draft, published, scheduled, archived)
+   * @param {string} [pageData.seoTitle] - SEO title
+   * @param {string} [pageData.seoDescription] - SEO description
+   * @param {Object} [pageData.metas] - Metadata object
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  createPage(pageData, options = {}) {
+    return this.create(pageData, options)
+  }
+
+  /**
+   * PATCH /api/v1/pages/{id} - Update page
+   * @param {string} id - Page ID
+   * @param {Object} updateData - Data to update
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  updatePage(id, updateData, options = {}) {
+    return this.update(id, updateData, options)
+  }
+
+  /**
+   * DELETE /api/v1/pages/{id} - Delete page
+   * @param {string} id - Page ID
+   * @returns {Cypress.Chainable} Cypress response
+   */
+  deletePage(id, options = {}) {
+    return this.delete(id, options)
+  }
+
+  // ============================================================
+  // DATA GENERATORS
+  // ============================================================
+
+  /**
+   * Generate random page data for testing
+   * @param {Object} overrides - Specific data to override
+   * @returns {Object} Generated page data
+   */
+  generateRandomData(overrides = {}) {
+    return PagesAPIController.generateRandomPageData(overrides)
+  }
+
+  /**
+   * Static method to generate random page data
+   * @param {Object} overrides - Specific data to override
+   * @returns {Object} Generated page data
+   */
+  static generateRandomPageData(overrides = {}) {
+    const timestamp = Date.now()
+    const randomId = Math.random().toString(36).substring(2, 8)
+
+    return {
+      slug: `test-page-${randomId}-${timestamp}`,
+      title: `Test Page ${randomId}`,
+      locale: 'en',
+      status: 'draft',
+      blocks: [],
+      ...overrides
+    }
+  }
+
+  /**
+   * Create a test page and return its data
+   * @param {Object} overrides - Data overrides
+   * @returns {Cypress.Chainable} Promise resolving with created page data
+   */
+  createTestPage(overrides = {}) {
+    return this.createTestEntity(overrides)
+  }
+
+  /**
+   * Clean up a test page
+   * @param {string} id - Page ID
+   * @returns {Cypress.Chainable} Delete response
+   */
+  cleanupTestPage(id) {
+    return this.cleanup(id)
+  }
+
+  // ============================================================
+  // ENTITY-SPECIFIC VALIDATORS
+  // ============================================================
+
+  /**
+   * Validate page object structure
+   * @param {Object} page - Page object
+   * @param {boolean} allowMetas - If metas property is allowed
+   */
+  validatePageObject(page, allowMetas = false) {
+    // Base fields
+    this.validateBaseEntityFields(page)
+
+    // Required page fields
+    expect(page).to.have.property('slug')
+    expect(page.slug).to.be.a('string')
+
+    expect(page).to.have.property('title')
+    expect(page.title).to.be.a('string')
+
+    expect(page).to.have.property('locale')
+    expect(page.locale).to.be.a('string')
+
+    expect(page).to.have.property('blocks')
+    expect(page.blocks).to.be.an('array')
+
+    // Status field (if present)
+    if (page.hasOwnProperty('status') && page.status !== null) {
+      expect(page.status).to.be.oneOf(['draft', 'published', 'scheduled', 'archived'])
+    }
+
+    // Metas if allowed
+    if (allowMetas && page.hasOwnProperty('metas')) {
+      expect(page.metas).to.be.an('object')
+    }
+  }
+
+  // ============================================================
+  // METADATA HELPERS
+  // ============================================================
+
+  /**
+   * Generate sample metadata for testing
+   * @param {string} type - Type of metadata ('seo', 'layout', 'settings')
+   * @returns {Object} Sample metadata
+   */
+  generateSampleMetadata(type = 'seo') {
+    const sampleMetas = {
+      seo: {
+        seoTitle: 'Custom Page SEO Title',
+        seoDescription: 'Custom SEO description for this page',
+        seoKeywords: 'test, page, cypress',
+        noindex: false,
+        nofollow: false,
+        ogImage: '/images/og-page.jpg'
+      },
+      layout: {
+        headerStyle: 'transparent',
+        footerVisible: true,
+        sidebarEnabled: false,
+        fullWidth: true
+      },
+      settings: {
+        cacheEnabled: true,
+        cacheTTL: 3600,
+        authRequired: false,
+        analyticsEnabled: true
+      }
+    }
+
+    return { [type]: sampleMetas[type] || sampleMetas.seo }
+  }
+}
+
+// Export for CommonJS
+module.exports = PagesAPIController
+
+// For global use in Cypress
+if (typeof window !== 'undefined') {
+  window.PagesAPIController = PagesAPIController
+}