ayezee-astro-cms 1.2.2 → 1.4.0

package/README.md

@@ -1,10 +1,11 @@
 # @ayezee/astro-cms
 
-AyeZee CMS integration for Astro with automatic data fetching, form handling, and validation.
+AyeZee CMS integration for Astro with automatic data fetching, form handling, validation, and analytics.
 
 ## Features
 
 - 🚀 **Automatic Data Fetching** - Fetches CMS data during build time
+- 📊 **Analytics Integration** - Auto-inject Umami analytics from dashboard settings
 - 📦 **Type-Safe** - Full TypeScript support with proper types
 - 🔄 **Build-Time Caching** - No runtime API calls needed
 - ✅ **Form Validation** - Client-side and server-side validation support
@@ -86,6 +87,9 @@ ayezeeCms({
 
   // Skip build if fetch fails (defaults to false)
   skipOnError?: boolean;
+
+  // Enable automatic Umami analytics injection (defaults to true)
+  enableAnalytics?: boolean;
 });
 ```
 
@@ -169,6 +173,28 @@ const info = getCacheInfo();
 // Returns: { fetchedAt, version, moduleCount }
 ```
 
+#### Analytics
+
+```ts
+import {
+  getAnalyticsConfig,
+  isAnalyticsEnabled,
+  getAnalyticsWebsiteId,
+} from '@ayezee/astro-cms';
+
+// Get full analytics configuration
+const analytics = getAnalyticsConfig();
+// Returns: { websiteId: string, baseUrl: string } | null
+
+// Check if analytics is enabled
+const enabled = isAnalyticsEnabled();
+// Returns: boolean
+
+// Get just the website ID
+const websiteId = getAnalyticsWebsiteId();
+// Returns: string | null
+```
+
 ## TypeScript Support
 
 The package exports all necessary types:
@@ -183,6 +209,54 @@ import type {
 } from '@ayezee/astro-cms';
 ```
 
+## Analytics Integration
+
+The integration automatically injects Umami analytics if configured in your AyeZee Dashboard.
+
+### How It Works
+
+1. **Configure in Dashboard**: Set up Umami analytics in your project settings at `/admin/projects/{slug}/settings?tab=analytics`
+2. **Automatic Injection**: The integration fetches your analytics config and automatically injects the Umami tracking script
+3. **Zero Configuration**: No need to manually add script tags or manage website IDs
+
+### Analytics Configuration
+
+Analytics is enabled by default. The script will only be injected if you've configured Umami in the dashboard.
+
+To disable automatic analytics injection:
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  integrations: [
+    ayezeeCms({
+      enableAnalytics: false, // Disable automatic Umami script injection
+    }),
+  ],
+});
+```
+
+### Manual Analytics Setup
+
+If you need more control over when/where the analytics script loads, you can disable auto-injection and add it manually:
+
+```astro
+---
+import { getAnalyticsConfig } from '@ayezee/astro-cms';
+import cmsData from '../data/cms-cache.json';
+
+const analytics = cmsData.analytics;
+---
+
+{analytics && (
+  <script
+    defer
+    src={`${analytics.baseUrl}/script.js`}
+    data-website-id={analytics.websiteId}
+  ></script>
+)}
+```
+
 ## Advanced Usage
 
 ### Custom Cache Location

package/dist/cms-helper.d.ts

@@ -66,6 +66,10 @@ export interface CachedModule {
     createdAt: string;
     updatedAt: string;
 }
+export interface AnalyticsConfig {
+    websiteId: string;
+    baseUrl: string;
+}
 export interface CMSCache {
     project: {
         id: string;
@@ -74,6 +78,7 @@ export interface CMSCache {
         domain?: string;
     };
     modules: CachedModule[];
+    analytics?: AnalyticsConfig | null;
     fetchedAt: string;
     version: string;
 }
@@ -174,3 +179,15 @@ export declare function getCacheInfo(): {
     version: string;
     moduleCount: number;
 };
+/**
+ * Get analytics configuration if enabled
+ */
+export declare function getAnalyticsConfig(): AnalyticsConfig | null;
+/**
+ * Check if analytics is enabled for this project
+ */
+export declare function isAnalyticsEnabled(): boolean;
+/**
+ * Get the Umami website ID if analytics is configured
+ */
+export declare function getAnalyticsWebsiteId(): string | null;

package/dist/cms-helper.js

@@ -187,4 +187,22 @@ export function getCacheInfo() {
         moduleCount: getCache().modules.length,
     };
 }
+/**
+ * Get analytics configuration if enabled
+ */
+export function getAnalyticsConfig() {
+    return getCache().analytics || null;
+}
+/**
+ * Check if analytics is enabled for this project
+ */
+export function isAnalyticsEnabled() {
+    return !!getCache().analytics;
+}
+/**
+ * Get the Umami website ID if analytics is configured
+ */
+export function getAnalyticsWebsiteId() {
+    return getCache().analytics?.websiteId || null;
+}
 // Types are already exported above, no need to re-export

package/dist/integration.d.ts

@@ -45,6 +45,26 @@ export interface AyezeeCmsOptions {
      * @default false
      */
     skipOnError?: boolean;
+    /**
+     * Enable automatic Umami analytics script injection
+     * @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;
 }
 /**
  * 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.4.0';
 /**
  * Load environment variables from .env file
  */
@@ -48,15 +50,67 @@ 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;
+}
+/**
+ * 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
  */
 export function ayezeeCms(options = {}) {
+    let analyticsConfig = null;
     return {
         name: 'ayezee-cms',
         hooks: {
-            'astro:config:setup': async ({ config, logger }) => {
-                logger.info('🚀 AyeZee CMS: Fetching data...');
+            'astro:config:setup': async ({ config, logger, injectScript }) => {
+                logger.info(`🚀 AyeZee CMS v${PACKAGE_VERSION}: Fetching data...`);
                 // Load environment variables from .env
                 loadEnvFile();
                 // Get configuration
@@ -66,21 +120,45 @@ export function ayezeeCms(options = {}) {
                 const outputDir = options.outputDir || 'src/data';
                 const cacheFileName = options.cacheFileName || 'cms-cache.json';
                 const skipOnError = options.skipOnError || false;
-                // Validate config
+                const enableAnalytics = options.enableAnalytics !== false;
+                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.`);
                 }
                 logger.info(`   Domain: ${cmsDomain}`);
                 logger.info(`   Project: ${projectSlug}`);
+                logger.info(`   Environment: ${environment}`);
                 try {
                     // Build API URL
                     let domain = cmsDomain;
@@ -105,6 +183,11 @@ export function ayezeeCms(options = {}) {
                     }
                     const modules = modulesResult.data.modules;
                     logger.info(`✅ Found ${modules.length} modules`);
+                    // Capture analytics configuration
+                    if (modulesResult.data.analytics) {
+                        analyticsConfig = modulesResult.data.analytics;
+                        logger.info(`📊 Analytics configured: ${analyticsConfig.websiteId}`);
+                    }
                     // Fetch data for each module
                     const modulesWithData = [];
                     for (const module of modules) {
@@ -147,6 +230,7 @@ export function ayezeeCms(options = {}) {
                     const cacheData = {
                         project: modulesResult.data.project,
                         modules: modulesWithData,
+                        analytics: analyticsConfig,
                         fetchedAt: new Date().toISOString(),
                         version: '1.0',
                     };
@@ -161,13 +245,63 @@ export function ayezeeCms(options = {}) {
                     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}`);
+                    // Inject Umami analytics script if configured
+                    if (enableAnalytics && analyticsConfig) {
+                        logger.info('📊 Injecting Umami analytics script...');
+                        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');
+                    }
+                    // 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,7 +1,7 @@
 {
   "name": "ayezee-astro-cms",
-  "version": "1.2.2",
-  "description": "AyeZee CMS integration for Astro with automatic data fetching, form handling, and validation",
+  "version": "1.4.0",
+  "description": "AyeZee CMS integration for Astro with automatic data fetching, form handling, validation, and analytics",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -40,7 +40,9 @@
     "ayezee",
     "integration",
     "form",
-    "validation"
+    "validation",
+    "analytics",
+    "umami"
   ],
   "author": "AyeZee Web Designs",
   "license": "MIT",