ayezee-astro-cms 1.3.0 → 1.5.0

package/dist/integration.d.ts

@@ -50,6 +50,31 @@ export interface AyezeeCmsOptions {
      * @default true
      */
     enableAnalytics?: boolean;
+    /**
+     * Report site version to CMS dashboard for tracking
+     * @default true
+     */
+    reportVersion?: boolean;
+    /**
+     * Site URL for version reporting (auto-detected if not provided)
+     * @default process.env.SITE_URL or process.env.URL
+     */
+    siteUrl?: string;
+    /**
+     * Environment name for version reporting
+     * @default process.env.NODE_ENV or 'production'
+     */
+    environment?: string;
+    /**
+     * Generate TypeScript types for module data
+     * @default true
+     */
+    generateTypes?: boolean;
+    /**
+     * Generate a wrapper file that auto-initializes the CMS helper
+     * @default true
+     */
+    generateWrapper?: boolean;
 }
 /**
  * AyeZee CMS Astro Integration

package/dist/integration.js

@@ -15,6 +15,8 @@
  */
 import fs from 'fs';
 import path from 'path';
+// Package version - automatically updated during build
+const PACKAGE_VERSION = '1.5.0';
 /**
  * Load environment variables from .env file
  */
@@ -48,6 +50,240 @@ function slugify(text) {
         .replace(/[\s_-]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+/**
+ * Get Astro version from package.json
+ */
+function getAstroVersion() {
+    try {
+        const pkgPath = path.join(process.cwd(), 'node_modules', 'astro', 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            return pkg.version;
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return undefined;
+}
+/**
+ * Convert a field type to a TypeScript type
+ */
+function fieldTypeToTsType(fieldType) {
+    switch (fieldType) {
+        case 'number':
+        case 'rating':
+            return 'number';
+        case 'checkbox':
+        case 'toggle':
+            return 'boolean';
+        case 'select':
+        case 'radio':
+            return 'string';
+        case 'multiselect':
+        case 'tags':
+            return 'string[]';
+        case 'json':
+        case 'object':
+            return 'Record<string, unknown>';
+        case 'date':
+        case 'datetime':
+            return 'string'; // ISO date string
+        case 'image':
+        case 'file':
+        case 'url':
+        case 'text':
+        case 'textarea':
+        case 'richtext':
+        case 'email':
+        case 'phone':
+        default:
+            return 'string';
+    }
+}
+/**
+ * Convert a string to PascalCase for type names
+ */
+function toPascalCase(str) {
+    return str
+        .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ''))
+        .replace(/^(.)/, (c) => c.toUpperCase());
+}
+/**
+ * Generate TypeScript types for all modules
+ */
+function generateTypeDefinitions(modules) {
+    const lines = [
+        '/**',
+        ' * Auto-generated TypeScript types for CMS modules',
+        ' * Generated by ayezee-astro-cms integration',
+        ' * DO NOT EDIT - This file is regenerated on each build',
+        ' */',
+        '',
+        '// Base type for all module data items',
+        'export interface ModuleDataItem<T = Record<string, unknown>> {',
+        '  id: string;',
+        '  data: T;',
+        '  sortOrder?: number;',
+        '  status?: string;',
+        '  createdAt: string;',
+        '  updatedAt?: string;',
+        '}',
+        '',
+    ];
+    for (const module of modules) {
+        const typeName = toPascalCase(module.instanceKey);
+        const dataTypeName = `${typeName}Data`;
+        const itemTypeName = `${typeName}Item`;
+        // Generate the data shape interface
+        lines.push(`// Module: ${module.label} (${module.instanceKey})`);
+        lines.push(`export interface ${dataTypeName} {`);
+        for (const field of module.fields) {
+            const tsType = fieldTypeToTsType(field.fieldType);
+            const optional = field.required ? '' : '?';
+            const comment = field.label !== field.key ? ` // ${field.label}` : '';
+            lines.push(`  ${field.key}${optional}: ${tsType};${comment}`);
+        }
+        lines.push('}');
+        lines.push('');
+        // Generate the full item type (with id, createdAt, etc.)
+        lines.push(`export type ${itemTypeName} = ModuleDataItem<${dataTypeName}>;`);
+        lines.push('');
+    }
+    // Generate a union type of all module keys for type-safe lookups
+    lines.push('// All available module instance keys');
+    lines.push('export type ModuleInstanceKey =');
+    for (let i = 0; i < modules.length; i++) {
+        const comma = i < modules.length - 1 ? '' : ';';
+        lines.push(`  | '${modules[i].instanceKey}'${comma}`);
+    }
+    lines.push('');
+    // Generate a mapping type for getModuleData
+    lines.push('// Type mapping for getModuleData helper');
+    lines.push('export interface ModuleDataMap {');
+    for (const module of modules) {
+        const itemTypeName = `${toPascalCase(module.instanceKey)}Item`;
+        lines.push(`  '${module.instanceKey}': ${itemTypeName}[];`);
+    }
+    lines.push('}');
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Generate wrapper file that auto-initializes the CMS helper
+ */
+function generateWrapperFile() {
+    return `/**
+ * Auto-generated CMS wrapper with pre-initialized helper
+ * Generated by ayezee-astro-cms integration
+ * DO NOT EDIT - This file is regenerated on each build
+ */
+
+import cmsData from './cms-cache.json';
+import {
+  initCmsHelper,
+  getProject,
+  getModules,
+  getModule,
+  getModuleByLabel,
+  getModuleBySlug,
+  getModulesByCategory,
+  getModulesByDataType,
+  getForms,
+  getCollections,
+  getSingletons,
+  getModuleData,
+  getModuleDataByLabel,
+  getModuleDataBySlug,
+  getTurnstileConfig,
+  isTurnstileEnabled,
+  getFormConfig,
+  getCacheInfo,
+  getAnalyticsConfig,
+  isAnalyticsEnabled,
+  getAnalyticsWebsiteId,
+  type CMSCache,
+  type CachedModule,
+  type ModuleDataItem,
+  type ModuleField,
+  type AnalyticsConfig,
+} from 'ayezee-astro-cms';
+
+// Auto-initialize on import
+initCmsHelper(cmsData as unknown as CMSCache);
+
+// Re-export everything for convenience
+export {
+  getProject,
+  getModules,
+  getModule,
+  getModuleByLabel,
+  getModuleBySlug,
+  getModulesByCategory,
+  getModulesByDataType,
+  getForms,
+  getCollections,
+  getSingletons,
+  getModuleData,
+  getModuleDataByLabel,
+  getModuleDataBySlug,
+  getTurnstileConfig,
+  isTurnstileEnabled,
+  getFormConfig,
+  getCacheInfo,
+  getAnalyticsConfig,
+  isAnalyticsEnabled,
+  getAnalyticsWebsiteId,
+};
+
+// Re-export types
+export type {
+  CMSCache,
+  CachedModule,
+  ModuleDataItem,
+  ModuleField,
+  AnalyticsConfig,
+};
+
+// Export the raw cache data for advanced use cases
+export { cmsData };
+`;
+}
+/**
+ * Report site version to CMS dashboard
+ */
+async function reportSiteVersion(baseUrl, apiKey, siteUrl, environment, astroVersion, logger) {
+    try {
+        const response = await fetch(`${baseUrl}/sites`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` }),
+            },
+            body: JSON.stringify({
+                siteUrl,
+                environment,
+                packageVersion: PACKAGE_VERSION,
+                astroVersion,
+                metadata: {
+                    nodeVersion: process.version,
+                    platform: process.platform,
+                    buildTime: new Date().toISOString(),
+                },
+            }),
+        });
+        if (response.ok) {
+            logger.info(`📡 Reported site version to dashboard`);
+        }
+        else {
+            logger.warn(`⚠️  Failed to report site version: ${response.status}`);
+        }
+    }
+    catch (error) {
+        // Don't fail the build if version reporting fails
+        logger.warn(`⚠️  Could not report site version (non-critical)`);
+    }
+}
 /**
  * AyeZee CMS Astro Integration
  */
@@ -57,7 +293,7 @@ export function ayezeeCms(options = {}) {
         name: 'ayezee-cms',
         hooks: {
             'astro:config:setup': async ({ config, logger, injectScript }) => {
-                logger.info('🚀 AyeZee CMS: Fetching data...');
+                logger.info(`🚀 AyeZee CMS v${PACKAGE_VERSION}: Fetching data...`);
                 // Load environment variables from .env
                 loadEnvFile();
                 // Get configuration
@@ -68,21 +304,104 @@ export function ayezeeCms(options = {}) {
                 const cacheFileName = options.cacheFileName || 'cms-cache.json';
                 const skipOnError = options.skipOnError || false;
                 const enableAnalytics = options.enableAnalytics !== false;
-                // Validate config
+                const reportVersion = options.reportVersion !== false;
+                const siteUrl = options.siteUrl || process.env.SITE_URL || process.env.URL || process.env.VERCEL_URL;
+                const environment = options.environment || process.env.NODE_ENV || 'production';
+                // Validate config with helpful error messages
                 if (!cmsDomain || !projectSlug) {
-                    const errorMsg = 'Missing environment variables:';
-                    if (!cmsDomain)
-                        logger.error(`   - PUBLIC_CMS_DOMAIN`);
-                    if (!projectSlug)
-                        logger.error(`   - PUBLIC_PROJECT_SLUG`);
+                    logger.error('');
+                    logger.error('❌ AyeZee CMS Configuration Error');
+                    logger.error('═══════════════════════════════════════════════════════════');
+                    logger.error('');
+                    logger.error('Missing required environment variables:');
+                    if (!cmsDomain) {
+                        logger.error('   ✗ PUBLIC_CMS_DOMAIN - The URL of your CMS dashboard');
+                        logger.error('     Example: PUBLIC_CMS_DOMAIN=https://cms.yourdomain.com');
+                    }
+                    if (!projectSlug) {
+                        logger.error('   ✗ PUBLIC_PROJECT_SLUG - Your project identifier');
+                        logger.error('     Example: PUBLIC_PROJECT_SLUG=my-project');
+                    }
+                    logger.error('');
+                    logger.error('Add these to your .env file:');
+                    logger.error('');
+                    logger.error('   PUBLIC_CMS_DOMAIN=https://your-cms-domain.com');
+                    logger.error('   PUBLIC_PROJECT_SLUG=your-project-slug');
+                    logger.error('   PUBLIC_AYEZEE_API_KEY=AZ_your_api_key (optional)');
+                    logger.error('');
+                    logger.error('═══════════════════════════════════════════════════════════');
+                    logger.error('');
                     if (skipOnError) {
                         logger.warn('⚠️  Skipping CMS data fetch due to missing config');
+                        logger.warn('   Build will continue with cached data (if available)');
                         return;
                     }
-                    throw new Error(`AyeZee CMS integration requires PUBLIC_CMS_DOMAIN and PUBLIC_PROJECT_SLUG`);
+                    throw new Error(`AyeZee CMS integration requires PUBLIC_CMS_DOMAIN and PUBLIC_PROJECT_SLUG. ` +
+                        `See the error messages above for details.`);
                 }
+                const generateTypes = options.generateTypes !== false;
+                const generateWrapper = options.generateWrapper !== false;
                 logger.info(`   Domain: ${cmsDomain}`);
                 logger.info(`   Project: ${projectSlug}`);
+                logger.info(`   Environment: ${environment}`);
+                // Get the data directory path
+                const dataDir = path.join(process.cwd(), outputDir);
+                const cachePath = path.join(dataDir, cacheFileName);
+                // Check if we can skip fetching in development mode
+                const isDev = environment === 'development' || process.env.NODE_ENV === 'development';
+                const forceFresh = process.env.CMS_FRESH === 'true';
+                const cacheExists = fs.existsSync(cachePath);
+                if (isDev && cacheExists && !forceFresh) {
+                    logger.info('');
+                    logger.info('📦 Using cached CMS data (dev mode)');
+                    logger.info('   Run with CMS_FRESH=true to fetch fresh data');
+                    logger.info('');
+                    // Still generate types and wrapper from existing cache
+                    if (generateTypes || generateWrapper) {
+                        try {
+                            const existingCache = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+                            if (generateTypes && existingCache.modules) {
+                                const typesContent = generateTypeDefinitions(existingCache.modules);
+                                const typesPath = path.join(dataDir, 'cms-types.ts');
+                                fs.writeFileSync(typesPath, typesContent, 'utf-8');
+                                logger.info(`✅ Generated types: ${path.relative(process.cwd(), typesPath)}`);
+                            }
+                            if (generateWrapper) {
+                                const wrapperContent = generateWrapperFile();
+                                const wrapperPath = path.join(dataDir, 'cms.ts');
+                                fs.writeFileSync(wrapperPath, wrapperContent, 'utf-8');
+                                logger.info(`✅ Generated wrapper: ${path.relative(process.cwd(), wrapperPath)}`);
+                            }
+                        }
+                        catch {
+                            logger.warn('⚠️  Could not generate types/wrapper from cached data');
+                        }
+                    }
+                    // Handle analytics injection from cached data
+                    if (enableAnalytics) {
+                        try {
+                            const existingCache = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+                            if (existingCache.analytics) {
+                                analyticsConfig = existingCache.analytics;
+                                injectScript('head-inline', `
+                  (function() {
+                    var script = document.createElement('script');
+                    script.defer = true;
+                    script.src = '${analyticsConfig.baseUrl}/script.js';
+                    script.setAttribute('data-website-id', '${analyticsConfig.websiteId}');
+                    document.head.appendChild(script);
+                  })();
+                  `);
+                                logger.info('📊 Umami analytics script injected from cache');
+                            }
+                        }
+                        catch {
+                            // Ignore errors reading cache for analytics
+                        }
+                    }
+                    logger.info('');
+                    return;
+                }
                 try {
                     // Build API URL
                     let domain = cmsDomain;
@@ -91,9 +410,9 @@ export function ayezeeCms(options = {}) {
                         domain = `${protocol}://${domain}`;
                     }
                     const baseUrl = `${domain}/api/v1/projects/${projectSlug}`;
-                    // Fetch modules
-                    logger.info('📡 Fetching modules...');
-                    const modulesResponse = await fetch(`${baseUrl}/modules`, {
+                    // Fetch all modules with data in a single API call
+                    logger.info('📡 Fetching modules with data...');
+                    const modulesResponse = await fetch(`${baseUrl}/modules?include=data`, {
                         headers: {
                             ...(apiKey && { 'Authorization': `Bearer ${apiKey}` }),
                         },
@@ -112,44 +431,21 @@ export function ayezeeCms(options = {}) {
                         analyticsConfig = modulesResult.data.analytics;
                         logger.info(`📊 Analytics configured: ${analyticsConfig.websiteId}`);
                     }
-                    // Fetch data for each module
-                    const modulesWithData = [];
-                    for (const module of modules) {
-                        try {
-                            const dataResponse = await fetch(`${baseUrl}/modules/${module.instanceKey}/data`, {
-                                headers: {
-                                    ...(apiKey && { 'Authorization': `Bearer ${apiKey}` }),
-                                },
-                            });
-                            if (!dataResponse.ok) {
-                                throw new Error(`HTTP ${dataResponse.status}: ${dataResponse.statusText}`);
-                            }
-                            const dataResult = await dataResponse.json();
-                            const itemCount = dataResult.data?.pagination?.total || 0;
-                            logger.info(`   📦 ${module.label}: ${itemCount} items`);
-                            modulesWithData.push({
-                                ...module,
-                                slug: slugify(module.label),
-                                data: dataResult.data?.data || [],
-                                pagination: dataResult.data?.pagination || {
-                                    total: 0,
-                                    count: 0,
-                                },
-                                parameters: dataResult.data?.module?.parameters || {},
-                            });
-                        }
-                        catch (error) {
-                            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-                            logger.warn(`   ⚠️  Failed to fetch ${module.label}: ${errorMessage}`);
-                            modulesWithData.push({
-                                ...module,
-                                slug: slugify(module.label),
-                                data: [],
-                                pagination: { total: 0, count: 0 },
-                                parameters: {},
-                            });
-                        }
-                    }
+                    // Transform modules to include slug and ensure consistent shape
+                    const modulesWithData = modules.map((module) => {
+                        const itemCount = module.data?.length || 0;
+                        logger.info(`   📦 ${module.label}: ${itemCount} items`);
+                        return {
+                            ...module,
+                            slug: slugify(module.label),
+                            data: module.data || [],
+                            pagination: module.pagination || {
+                                total: itemCount,
+                                count: itemCount,
+                            },
+                            parameters: module.parameters || {},
+                        };
+                    });
                     // Create cache data
                     const cacheData = {
                         project: modulesResult.data.project,
@@ -158,17 +454,28 @@ export function ayezeeCms(options = {}) {
                         fetchedAt: new Date().toISOString(),
                         version: '1.0',
                     };
-                    // Get the data directory path
-                    const dataDir = path.join(process.cwd(), outputDir);
                     // Ensure directory exists
                     if (!fs.existsSync(dataDir)) {
                         fs.mkdirSync(dataDir, { recursive: true });
                     }
                     // Write cache file
-                    const cachePath = path.join(dataDir, cacheFileName);
                     fs.writeFileSync(cachePath, JSON.stringify(cacheData, null, 2), 'utf-8');
                     logger.info(`✅ Cached data to: ${path.relative(process.cwd(), cachePath)}`);
                     logger.info(`📅 Fetched at: ${cacheData.fetchedAt}`);
+                    // Generate TypeScript types
+                    if (generateTypes) {
+                        const typesContent = generateTypeDefinitions(modulesWithData);
+                        const typesPath = path.join(dataDir, 'cms-types.ts');
+                        fs.writeFileSync(typesPath, typesContent, 'utf-8');
+                        logger.info(`✅ Generated types: ${path.relative(process.cwd(), typesPath)}`);
+                    }
+                    // Generate wrapper file
+                    if (generateWrapper) {
+                        const wrapperContent = generateWrapperFile();
+                        const wrapperPath = path.join(dataDir, 'cms.ts');
+                        fs.writeFileSync(wrapperPath, wrapperContent, 'utf-8');
+                        logger.info(`✅ Generated wrapper: ${path.relative(process.cwd(), wrapperPath)}`);
+                    }
                     // Inject Umami analytics script if configured
                     if (enableAnalytics && analyticsConfig) {
                         logger.info('📊 Injecting Umami analytics script...');
@@ -183,13 +490,49 @@ export function ayezeeCms(options = {}) {
               `);
                         logger.info('✅ Umami analytics script injected');
                     }
+                    // Report site version to dashboard (non-blocking)
+                    if (reportVersion && siteUrl) {
+                        const astroVersion = getAstroVersion();
+                        reportSiteVersion(baseUrl, apiKey, siteUrl, environment, astroVersion, logger);
+                    }
+                    logger.info('');
+                    logger.info('🎉 AyeZee CMS data fetched successfully!');
+                    logger.info('');
                 }
                 catch (error) {
                     const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-                    logger.error('❌ Failed to fetch CMS data:');
-                    logger.error(`   ${errorMessage}`);
+                    logger.error('');
+                    logger.error('❌ Failed to fetch CMS data');
+                    logger.error('═══════════════════════════════════════════════════════════');
+                    logger.error('');
+                    logger.error(`Error: ${errorMessage}`);
+                    logger.error('');
+                    // Provide helpful troubleshooting tips
+                    if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('fetch failed')) {
+                        logger.error('Troubleshooting tips:');
+                        logger.error('   1. Is the CMS dashboard running?');
+                        logger.error(`   2. Can you access ${cmsDomain} in your browser?`);
+                        logger.error('   3. Check your network connection');
+                        logger.error('   4. If using localhost, ensure the dashboard is started');
+                    }
+                    else if (errorMessage.includes('401') || errorMessage.includes('403')) {
+                        logger.error('Troubleshooting tips:');
+                        logger.error('   1. Check that PUBLIC_AYEZEE_API_KEY is correct');
+                        logger.error('   2. Verify the API key has read permissions');
+                        logger.error('   3. Ensure the project slug matches your dashboard project');
+                    }
+                    else if (errorMessage.includes('404')) {
+                        logger.error('Troubleshooting tips:');
+                        logger.error('   1. Verify PUBLIC_PROJECT_SLUG is correct');
+                        logger.error('   2. Check that the project exists in the dashboard');
+                        logger.error(`   3. Project slug should match: ${projectSlug}`);
+                    }
+                    logger.error('');
+                    logger.error('═══════════════════════════════════════════════════════════');
+                    logger.error('');
                     if (skipOnError) {
-                        logger.warn('⚠️  Continuing build without CMS data');
+                        logger.warn('⚠️  Continuing build with cached data (skipOnError: true)');
+                        logger.warn('   The site will use previously cached CMS data if available.');
                         return;
                     }
                     throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ayezee-astro-cms",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "AyeZee CMS integration for Astro with automatic data fetching, form handling, validation, and analytics",
   "type": "module",
   "main": "./dist/index.js",