@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/bin/lib/analytics/analytics-reporter.cjs

@@ -0,0 +1,130 @@
+/**
+ * Analytics Reporter — Aggregated analytics report generation
+ * Generates reports from events, NPS, funnels, and cohorts
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class AnalyticsReporter {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.reportsDir = path.join(this.cwd, '.planning', 'analytics', 'reports');
+    this.ensureDir();
+  }
+
+  /**
+   * Generate aggregated analytics report
+   * @param {Object} options - Report options
+   * @returns {Object} Analytics report
+   */
+  generateReport(options = {}) {
+    const { calculateNPS } = require('./nps-tracker.cjs');
+    const { analyzeFunnel } = require('./funnel-analyzer.cjs');
+    const { AnalyticsCollector } = require('./analytics-collector.cjs');
+
+    const collector = new AnalyticsCollector(this.cwd);
+    const events = collector.getAllEvents();
+    const nps = calculateNPS(this.cwd);
+
+    // Group events by type
+    const eventsByType = {};
+    for (const event of events) {
+      if (!eventsByType[event.eventType]) {
+        eventsByType[event.eventType] = 0;
+      }
+      eventsByType[event.eventType]++;
+    }
+
+    return {
+      timestamp: new Date().toISOString(),
+      summary: {
+        totalEvents: events.length,
+        uniqueEventTypes: Object.keys(eventsByType).length,
+        npsScore: nps.score
+      },
+      events: {
+        byType: eventsByType,
+        recent: events.slice(-10)
+      },
+      nps,
+      recommendations: this.generateRecommendations(events, nps)
+    };
+  }
+
+  /**
+   * Save report to file
+   * @param {Object} report - Report to save
+   * @param {string} filename - Optional filename
+   * @returns {string} Path to saved report
+   */
+  saveReport(report, filename) {
+    const reportFilename = filename || `analytics-${Date.now()}.json`;
+    const reportPath = path.join(this.reportsDir, reportFilename);
+
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf8');
+    return reportPath;
+  }
+
+  /**
+   * Generate recommendations from analytics
+   * @param {Array} events - Events array
+   * @param {Object} nps - NPS data
+   * @returns {Array} Recommendations
+   */
+  generateRecommendations(events, nps) {
+    const recommendations = [];
+
+    if (nps.score < 0) {
+      recommendations.push({
+        category: 'nps',
+        priority: 'high',
+        suggestion: 'NPS is negative — investigate detractor feedback'
+      });
+    }
+
+    if (events.length < 100) {
+      recommendations.push({
+        category: 'tracking',
+        priority: 'medium',
+        suggestion: 'Low event volume — ensure all key actions are tracked'
+      });
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Ensure reports directory exists
+   */
+  ensureDir() {
+    if (!fs.existsSync(this.reportsDir)) {
+      fs.mkdirSync(this.reportsDir, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Generate analytics report
+ * @param {Object} options - Report options
+ * @param {string} cwd - Working directory
+ * @returns {Object} Analytics report
+ */
+function generateReport(options = {}, cwd) {
+  const reporter = new AnalyticsReporter(cwd);
+  return reporter.generateReport(options);
+}
+
+/**
+ * Save analytics report
+ * @param {Object} report - Report to save
+ * @param {string} filename - Filename
+ * @param {string} cwd - Working directory
+ * @returns {string} Path to saved report
+ */
+function saveReport(report, filename, cwd) {
+  const reporter = new AnalyticsReporter(cwd);
+  return reporter.saveReport(report, filename);
+}
+
+module.exports = { AnalyticsReporter, generateReport, saveReport };

package/ez-agents/bin/lib/analytics/cohort-analyzer.cjs

@@ -0,0 +1,138 @@
+/**
+ * Cohort Analyzer — Cohort-based usage pattern analysis
+ * Groups users by time/behavior and tracks retention
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class CohortAnalyzer {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.cohortsPath = path.join(this.cwd, '.planning', 'analytics', 'cohorts.json');
+    this.ensureFile();
+  }
+
+  /**
+   * Define a cohort by date range
+   * @param {string} name - Cohort name
+   * @param {string} startDate - Start date (ISO)
+   * @param {string} endDate - End date (ISO)
+   * @param {Array} users - User IDs in cohort
+   */
+  defineCohort(name, startDate, endDate, users) {
+    const cohorts = this.getCohorts();
+    
+    cohorts[name] = {
+      startDate,
+      endDate,
+      users,
+      size: users.length,
+      createdAt: new Date().toISOString()
+    };
+
+    this.saveCohorts(cohorts);
+  }
+
+  /**
+   * Calculate retention for a cohort
+   * @param {string} cohortName - Cohort name
+   * @param {Array} periods - Time periods to analyze
+   * @returns {Object} Retention data
+   */
+  calculateRetention(cohortName, periods = []) {
+    const cohorts = this.getCohorts();
+    const cohort = cohorts[cohortName];
+
+    if (!cohort) {
+      return { error: 'Cohort not found' };
+    }
+
+    const retention = [];
+    const initialSize = cohort.size;
+
+    for (const period of periods) {
+      const activeUsers = this.getActiveUsersInPeriod(cohortName, period);
+      retention.push({
+        period: period.name,
+        activeUsers: activeUsers.length,
+        retentionRate: initialSize > 0 ? Math.round((activeUsers.length / initialSize) * 100) : 0
+      });
+    }
+
+    return { cohort: cohortName, retention, initialSize };
+  }
+
+  /**
+   * Get active users in a period
+   * @param {string} cohortName - Cohort name
+   * @param {Object} period - Period definition
+   * @returns {Array} Active user IDs
+   */
+  getActiveUsersInPeriod(cohortName, period) {
+    // Placeholder - would track actual user activity
+    const cohorts = this.getCohorts();
+    const cohort = cohorts[cohortName];
+    if (!cohort) return [];
+    
+    // Return all users for now (placeholder)
+    return cohort.users;
+  }
+
+  /**
+   * Get all cohorts
+   * @returns {Object} All cohorts
+   */
+  getCohorts() {
+    if (!fs.existsSync(this.cohortsPath)) return {};
+    return JSON.parse(fs.readFileSync(this.cohortsPath, 'utf8'));
+  }
+
+  /**
+   * Save cohorts
+   * @param {Object} cohorts - Cohorts to save
+   */
+  saveCohorts(cohorts) {
+    fs.writeFileSync(this.cohortsPath, JSON.stringify(cohorts, null, 2), 'utf8');
+  }
+
+  /**
+   * Ensure cohorts file exists
+   */
+  ensureFile() {
+    const dir = path.dirname(this.cohortsPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    if (!fs.existsSync(this.cohortsPath)) {
+      fs.writeFileSync(this.cohortsPath, '{}', 'utf8');
+    }
+  }
+}
+
+/**
+ * Define a cohort
+ * @param {string} name - Cohort name
+ * @param {string} startDate - Start date
+ * @param {string} endDate - End date
+ * @param {Array} users - User IDs
+ * @param {string} cwd - Working directory
+ */
+function defineCohort(name, startDate, endDate, users, cwd) {
+  const analyzer = new CohortAnalyzer(cwd);
+  return analyzer.defineCohort(name, startDate, endDate, users);
+}
+
+/**
+ * Calculate cohort retention
+ * @param {string} cohortName - Cohort name
+ * @param {Array} periods - Periods to analyze
+ * @param {string} cwd - Working directory
+ * @returns {Object} Retention data
+ */
+function calculateRetention(cohortName, periods, cwd) {
+  const analyzer = new CohortAnalyzer(cwd);
+  return analyzer.calculateRetention(cohortName, periods);
+}
+
+module.exports = { CohortAnalyzer, defineCohort, calculateRetention };

package/ez-agents/bin/lib/analytics/funnel-analyzer.cjs

@@ -0,0 +1,147 @@
+/**
+ * Funnel Analyzer — User funnel step tracking and drop-off analysis
+ * Tracks conversion through defined funnel steps
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class FunnelAnalyzer {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.funnelPath = path.join(this.cwd, '.planning', 'analytics', 'funnels.json');
+    this.ensureFile();
+  }
+
+  /**
+   * Track user progression through funnel step
+   * @param {string} funnelName - Funnel name
+   * @param {string} userId - User ID
+   * @param {string} step - Current step name
+   */
+  trackStep(funnelName, userId, step) {
+    const funnels = this.getFunnels();
+    
+    if (!funnels[funnelName]) {
+      funnels[funnelName] = { steps: [], users: {} };
+    }
+
+    const funnel = funnels[funnelName];
+    
+    // Add step if new
+    if (!funnel.steps.includes(step)) {
+      funnel.steps.push(step);
+    }
+
+    // Track user progression
+    if (!funnel.users[userId]) {
+      funnel.users[userId] = [];
+    }
+    funnel.users[userId].push({ step, timestamp: new Date().toISOString() });
+
+    this.saveFunnels(funnels);
+  }
+
+  /**
+   * Analyze funnel conversion
+   * @param {string} funnelName - Funnel name
+   * @returns {Object} Funnel analysis { steps, dropOff }
+   */
+  analyzeFunnel(funnelName) {
+    const funnels = this.getFunnels();
+    const funnel = funnels[funnelName];
+
+    if (!funnel || funnel.steps.length === 0) {
+      return { steps: [], dropOff: [], totalUsers: 0 };
+    }
+
+    const stepCounts = {};
+    const userSteps = {};
+
+    // Count users at each step
+    for (const [userId, steps] of Object.entries(funnel.users)) {
+      const uniqueSteps = [...new Set(steps.map(s => s.step))];
+      for (const step of uniqueSteps) {
+        stepCounts[step] = (stepCounts[step] || 0) + 1;
+      }
+      userSteps[userId] = uniqueSteps.length;
+    }
+
+    // Calculate drop-off between steps
+    const dropOff = [];
+    for (let i = 0; i < funnel.steps.length - 1; i++) {
+      const current = stepCounts[funnel.steps[i]] || 0;
+      const next = stepCounts[funnel.steps[i + 1]] || 0;
+      dropOff.push({
+        from: funnel.steps[i],
+        to: funnel.steps[i + 1],
+        dropOff: current - next,
+        dropOffRate: current > 0 ? Math.round(((current - next) / current) * 100) : 0
+      });
+    }
+
+    return {
+      steps: funnel.steps.map(step => ({
+        name: step,
+        users: stepCounts[step] || 0
+      })),
+      dropOff,
+      totalUsers: Object.keys(funnel.users).length
+    };
+  }
+
+  /**
+   * Get all funnels
+   * @returns {Object} All funnels
+   */
+  getFunnels() {
+    if (!fs.existsSync(this.funnelPath)) return {};
+    return JSON.parse(fs.readFileSync(this.funnelPath, 'utf8'));
+  }
+
+  /**
+   * Save funnels
+   * @param {Object} funnels - Funnels to save
+   */
+  saveFunnels(funnels) {
+    fs.writeFileSync(this.funnelPath, JSON.stringify(funnels, null, 2), 'utf8');
+  }
+
+  /**
+   * Ensure funnels file exists
+   */
+  ensureFile() {
+    const dir = path.dirname(this.funnelPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    if (!fs.existsSync(this.funnelPath)) {
+      fs.writeFileSync(this.funnelPath, '{}', 'utf8');
+    }
+  }
+}
+
+/**
+ * Track funnel step
+ * @param {string} funnelName - Funnel name
+ * @param {string} userId - User ID
+ * @param {string} step - Step name
+ * @param {string} cwd - Working directory
+ */
+function trackStep(funnelName, userId, step, cwd) {
+  const analyzer = new FunnelAnalyzer(cwd);
+  return analyzer.trackStep(funnelName, userId, step);
+}
+
+/**
+ * Analyze funnel
+ * @param {string} funnelName - Funnel name
+ * @param {string} cwd - Working directory
+ * @returns {Object} Funnel analysis
+ */
+function analyzeFunnel(funnelName, cwd) {
+  const analyzer = new FunnelAnalyzer(cwd);
+  return analyzer.analyzeFunnel(funnelName);
+}
+
+module.exports = { FunnelAnalyzer, trackStep, analyzeFunnel };

package/ez-agents/bin/lib/analytics/nps-tracker.cjs

@@ -0,0 +1,147 @@
+/**
+ * NPS Tracker — NPS survey prompt and score tracking
+ * Calculates Net Promoter Score from user responses
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class NpsTracker {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.scoresPath = path.join(this.cwd, '.planning', 'analytics', 'nps-scores.json');
+    this.ensureFile();
+  }
+
+  /**
+   * Record an NPS score
+   * @param {number} score - Score 0-10
+   * @param {Object} metadata - Optional metadata
+   */
+  recordScore(score, metadata = {}) {
+    if (score < 0 || score > 10) {
+      throw new Error('NPS score must be between 0 and 10');
+    }
+
+    const data = {
+      score,
+      category: this.categorizeScore(score),
+      timestamp: new Date().toISOString(),
+      ...metadata
+    };
+
+    const scores = this.getScores();
+    scores.push(data);
+    fs.writeFileSync(this.scoresPath, JSON.stringify(scores, null, 2), 'utf8');
+  }
+
+  /**
+   * Calculate current NPS
+   * @returns {Object} NPS result { score, promoters, passives, detractors }
+   */
+  calculateNPS() {
+    const scores = this.getScores();
+    if (scores.length === 0) {
+      return { score: 0, promoters: 0, passives: 0, detractors: 0, total: 0 };
+    }
+
+    const promoters = scores.filter(s => s.score >= 9).length;
+    const passives = scores.filter(s => s.score >= 7 && s.score <= 8).length;
+    const detractors = scores.filter(s => s.score <= 6).length;
+    const total = scores.length;
+
+    const nps = Math.round(((promoters - detractors) / total) * 100);
+
+    return { score: nps, promoters, passives, detractors, total };
+  }
+
+  /**
+   * Get NPS trend over time
+   * @returns {Array} Trend data
+   */
+  getTrend() {
+    const scores = this.getScores();
+    const trend = [];
+    let cumulative = [];
+
+    for (const score of scores) {
+      cumulative.push(score);
+      const nps = this.calculateNPSFromScores(cumulative);
+      trend.push({
+        timestamp: score.timestamp,
+        nps: nps.score,
+        total: cumulative.length
+      });
+    }
+
+    return trend;
+  }
+
+  /**
+   * Categorize score
+   * @param {number} score - Score 0-10
+   * @returns {string} Category
+   */
+  categorizeScore(score) {
+    if (score >= 9) return 'promoter';
+    if (score >= 7) return 'passive';
+    return 'detractor';
+  }
+
+  /**
+   * Calculate NPS from array of scores
+   * @param {Array} scores - Array of score objects
+   * @returns {Object} NPS result
+   */
+  calculateNPSFromScores(scores) {
+    const promoters = scores.filter(s => s.score >= 9).length;
+    const detractors = scores.filter(s => s.score <= 6).length;
+    const total = scores.length;
+    return { score: Math.round(((promoters - detractors) / total) * 100) };
+  }
+
+  /**
+   * Get all scores
+   * @returns {Array} All scores
+   */
+  getScores() {
+    if (!fs.existsSync(this.scoresPath)) return [];
+    return JSON.parse(fs.readFileSync(this.scoresPath, 'utf8'));
+  }
+
+  /**
+   * Ensure scores file exists
+   */
+  ensureFile() {
+    const dir = path.dirname(this.scoresPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    if (!fs.existsSync(this.scoresPath)) {
+      fs.writeFileSync(this.scoresPath, '[]', 'utf8');
+    }
+  }
+}
+
+/**
+ * Record an NPS score
+ * @param {number} score - Score 0-10
+ * @param {Object} metadata - Metadata
+ * @param {string} cwd - Working directory
+ */
+function recordScore(score, metadata = {}, cwd) {
+  const tracker = new NpsTracker(cwd);
+  return tracker.recordScore(score, metadata);
+}
+
+/**
+ * Calculate current NPS
+ * @param {string} cwd - Working directory
+ * @returns {Object} NPS result
+ */
+function calculateNPS(cwd) {
+  const tracker = new NpsTracker(cwd);
+  return tracker.calculateNPS();
+}
+
+module.exports = { NpsTracker, recordScore, calculateNPS };