feat: Implement license-aware UI for revenue optimization (Phase 3A)

Business Objective: Transform WHOOSH from license-unaware to comprehensive license-integrated experience that drives upgrade conversions and maximizes customer lifetime value through usage visibility. Implementation Summary: 1. SECURE BACKEND PROXY INTEGRATION: - License API proxy endpoints (/api/license/status, /api/license/quotas) - Server-side license ID resolution (no frontend exposure) - Mock data support for development and testing - Intelligent upgrade suggestion algorithms 2. COMPREHENSIVE FRONTEND LICENSE INTEGRATION: - License API Client with caching and error handling - Global License Context for state management - License Status Header for always-visible tier information - Feature Gate Component for conditional rendering - License Dashboard with quotas, features, upgrade suggestions - Upgrade Prompt Components for revenue optimization 3. APPLICATION-WIDE INTEGRATION: - License Provider integrated into App context hierarchy - License status header in main navigation - License dashboard route at /license - Example feature gates in Analytics page - Version bump: → 1.2.0 Key Business Benefits: ✅ Revenue Optimization: Strategic feature gating drives conversions ✅ User Trust: Transparent license information builds confidence ✅ Proactive Upgrades: Usage-based suggestions with ROI estimates ✅ Self-Service: Clear upgrade paths reduce sales friction Security-First Design: 🔒 All license operations server-side via proxy 🔒 No sensitive license data exposed to frontend 🔒 Feature enforcement at API level prevents bypass 🔒 Graceful degradation for license API failures Technical Implementation: - React 18+ with TypeScript and modern hooks - Context API for license state management - Tailwind CSS following existing patterns - Backend proxy pattern for security compliance - Comprehensive error handling and loading states Files Created/Modified: Backend: - /backend/app/api/license.py - Complete license proxy API - /backend/app/main.py - Router integration Frontend: - /frontend/src/services/licenseApi.ts - API client with caching - /frontend/src/contexts/LicenseContext.tsx - Global license state - /frontend/src/hooks/useLicenseFeatures.ts - Feature checking logic - /frontend/src/components/license/* - Complete license UI components - /frontend/src/App.tsx - Context integration and routing - /frontend/package.json - Version bump to 1.2.0 This Phase 3A implementation provides the complete foundation for license-aware user experiences, driving revenue optimization through intelligent feature gating and upgrade suggestions while maintaining excellent UX and security best practices. Ready for KACHING integration and Phase 3B advanced features. 🤖 Generated with Claude Code (claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-01 16:20:24 +10:00
parent 268214d971
commit a880b26951
15 changed files with 4511 additions and 21 deletions
--- a/frontend/src/contexts/LicenseContext.tsx
+++ b/frontend/src/contexts/LicenseContext.tsx
@@ -0,0 +1,417 @@
+/**
+ * License Context Provider
+ * 
+ * This context manages global license state throughout the WHOOSH application.
+ * It provides license-aware functionality including tier status, feature availability,
+ * quota monitoring, and upgrade suggestions to all components.
+ * 
+ * Key Responsibilities:
+ * - Centralized license state management
+ * - Automatic license data refresh and caching
+ * - Feature availability checking for gates
+ * - Quota monitoring and limit warnings
+ * - Upgrade suggestion management
+ * - License status change notifications
+ * 
+ * Business Integration:
+ * - Powers revenue optimization through strategic feature gating
+ * - Enables proactive upgrade suggestions based on usage patterns
+ * - Provides transparent license information to build user trust
+ * - Supports self-service upgrade workflows
+ * 
+ * Technical Implementation:
+ * - React Context API for global state management
+ * - Automatic refresh intervals for real-time data
+ * - Error handling with graceful degradation
+ * - TypeScript for reliable license operations
+ */
+
+import React, { createContext, useContext, useState, useEffect, useCallback, ReactNode } from 'react';
+import { 
+  LicenseStatus, 
+  LicenseQuotas, 
+  UpgradeSuggestion, 
+  FeatureAvailability,
+  AvailableTiers,
+  licenseApi 
+} from '../services/licenseApi';
+
+/**
+ * License Context State Interface
+ * 
+ * Defines the complete license state available to all components.
+ * This interface ensures type safety and provides comprehensive license information.
+ */
+interface LicenseContextState {
+  // Core license data
+  licenseStatus: LicenseStatus | null;
+  quotas: LicenseQuotas | null;
+  upgradeSuggestions: UpgradeSuggestion[];
+  availableTiers: AvailableTiers | null;
+  
+  // Loading and error states
+  isLoading: boolean;
+  error: string | null;
+  
+  // Feature checking methods
+  hasFeature: (feature: string) => boolean;
+  checkFeature: (feature: string) => Promise<FeatureAvailability | null>;
+  
+  // Tier checking methods
+  isOnTier: (tier: string) => boolean;
+  hasTierOrHigher: (tier: string) => boolean;
+  
+  // Quota utilities
+  getQuotaUsage: (quotaType: keyof LicenseQuotas) => number;
+  isApproachingLimit: (quotaType: keyof LicenseQuotas, threshold?: number) => boolean;
+  
+  // Upgrade management
+  getUrgentSuggestions: () => UpgradeSuggestion[];
+  refreshLicenseData: () => Promise<void>;
+  
+  // Cache management
+  clearCache: () => void;
+  lastRefresh: Date | null;
+}
+
+const LicenseContext = createContext<LicenseContextState | undefined>(undefined);
+
+/**
+ * License Provider Props
+ */
+interface LicenseProviderProps {
+  children: ReactNode;
+  refreshInterval?: number; // milliseconds, default 5 minutes
+  enableAutoRefresh?: boolean; // default true
+}
+
+/**
+ * License Provider Component
+ * 
+ * Wraps the application to provide license context to all child components.
+ * Manages license data fetching, caching, and automatic refresh cycles.
+ * 
+ * Features:
+ * - Automatic license data initialization on mount
+ * - Periodic refresh for real-time quota updates
+ * - Intelligent error handling and retry logic
+ * - Performance optimization through batched API calls
+ */
+export const LicenseProvider: React.FC<LicenseProviderProps> = ({
+  children,
+  refreshInterval = 5 * 60 * 1000, // 5 minutes default
+  enableAutoRefresh = true,
+}) => {
+  // Core license state
+  const [licenseStatus, setLicenseStatus] = useState<LicenseStatus | null>(null);
+  const [quotas, setQuotas] = useState<LicenseQuotas | null>(null);
+  const [upgradeSuggestions, setUpgradeSuggestions] = useState<UpgradeSuggestion[]>([]);
+  const [availableTiers, setAvailableTiers] = useState<AvailableTiers | null>(null);
+  
+  // Loading and error state
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [lastRefresh, setLastRefresh] = useState<Date | null>(null);
+
+  /**
+   * Tier hierarchy for comparison operations
+   * Used for hasTierOrHigher functionality
+   */
+  const tierHierarchy = {
+    evaluation: 0,
+    standard: 1,
+    enterprise: 2,
+  };
+
+  /**
+   * Fetch all license data from API
+   * 
+   * Uses batched API calls for optimal performance during initial load
+   * and refresh operations. Handles errors gracefully to prevent app crashes.
+   */
+  const fetchLicenseData = useCallback(async (showLoading: boolean = true) => {
+    if (showLoading) {
+      setIsLoading(true);
+    }
+    setError(null);
+
+    try {
+      // Use batched API call for efficiency
+      const data = await licenseApi.batchFetchLicenseData();
+      
+      // Update all state at once to prevent multiple re-renders
+      setLicenseStatus(data.status);
+      setQuotas(data.quotas);
+      setUpgradeSuggestions(data.suggestions);
+      setAvailableTiers(data.tiers);
+      setLastRefresh(new Date());
+      
+      // Clear any previous errors
+      setError(null);
+      
+    } catch (err) {
+      console.error('Failed to fetch license data:', err);
+      setError('Failed to load license information');
+      
+      // Don't clear existing data on error - allow graceful degradation
+      if (!licenseStatus) {
+        // Only show loading error if we have no data at all
+        setError('Unable to load license information. Some features may be limited.');
+      }
+    } finally {
+      setIsLoading(false);
+    }
+  }, [licenseStatus]);
+
+  /**
+   * Initialize license data on component mount
+   */
+  useEffect(() => {
+    fetchLicenseData();
+  }, [fetchLicenseData]);
+
+  /**
+   * Set up automatic refresh interval
+   * 
+   * Keeps license data fresh for real-time quota updates and status changes.
+   * Respects the enableAutoRefresh prop for environments where it's not needed.
+   */
+  useEffect(() => {
+    if (!enableAutoRefresh || refreshInterval <= 0) {
+      return;
+    }
+
+    const interval = setInterval(() => {
+      // Refresh silently (don't show loading state)
+      fetchLicenseData(false);
+    }, refreshInterval);
+
+    return () => clearInterval(interval);
+  }, [fetchLicenseData, refreshInterval, enableAutoRefresh]);
+
+  /**
+   * Feature availability checking
+   * 
+   * Synchronous feature check based on current license status.
+   * Falls back to false if license data is not available.
+   */
+  const hasFeature = useCallback((feature: string): boolean => {
+    if (!licenseStatus) return false;
+    return licenseStatus.features.includes(feature);
+  }, [licenseStatus]);
+
+  /**
+   * Asynchronous feature checking with detailed information
+   * 
+   * Provides detailed feature availability information including upgrade path.
+   * Uses API call for most current information.
+   */
+  const checkFeature = useCallback(async (feature: string): Promise<FeatureAvailability | null> => {
+    return await licenseApi.checkFeatureAvailability(feature);
+  }, []);
+
+  /**
+   * Tier checking methods
+   */
+  const isOnTier = useCallback((tier: string): boolean => {
+    return licenseStatus?.tier === tier;
+  }, [licenseStatus]);
+
+  const hasTierOrHigher = useCallback((targetTier: string): boolean => {
+    if (!licenseStatus) return false;
+    
+    const currentLevel = tierHierarchy[licenseStatus.tier as keyof typeof tierHierarchy] ?? -1;
+    const targetLevel = tierHierarchy[targetTier as keyof typeof tierHierarchy] ?? 999;
+    
+    return currentLevel >= targetLevel;
+  }, [licenseStatus]);
+
+  /**
+   * Quota utility methods
+   */
+  const getQuotaUsage = useCallback((quotaType: keyof LicenseQuotas): number => {
+    if (!quotas || !quotas[quotaType]) return 0;
+    return quotas[quotaType].percentage;
+  }, [quotas]);
+
+  const isApproachingLimit = useCallback((
+    quotaType: keyof LicenseQuotas, 
+    threshold: number = 80
+  ): boolean => {
+    const usage = getQuotaUsage(quotaType);
+    return usage >= threshold;
+  }, [getQuotaUsage]);
+
+  /**
+   * Upgrade suggestion utilities
+   */
+  const getUrgentSuggestions = useCallback((): UpgradeSuggestion[] => {
+    return upgradeSuggestions.filter(suggestion => suggestion.urgency === 'high');
+  }, [upgradeSuggestions]);
+
+  /**
+   * Manual refresh function
+   * 
+   * Allows components to trigger a fresh license data fetch.
+   * Useful after user actions that might change license status.
+   */
+  const refreshLicenseData = useCallback(async (): Promise<void> => {
+    await fetchLicenseData();
+  }, [fetchLicenseData]);
+
+  /**
+   * Clear license cache
+   * 
+   * Forces fresh data on next API call.
+   * Useful when license changes are expected.
+   */
+  const clearCache = useCallback((): void => {
+    licenseApi.clearCache();
+  }, []);
+
+  // Context value object
+  const contextValue: LicenseContextState = {
+    // Core data
+    licenseStatus,
+    quotas,
+    upgradeSuggestions,
+    availableTiers,
+    
+    // State
+    isLoading,
+    error,
+    
+    // Feature methods
+    hasFeature,
+    checkFeature,
+    
+    // Tier methods
+    isOnTier,
+    hasTierOrHigher,
+    
+    // Quota methods
+    getQuotaUsage,
+    isApproachingLimit,
+    
+    // Upgrade methods
+    getUrgentSuggestions,
+    refreshLicenseData,
+    
+    // Cache management
+    clearCache,
+    lastRefresh,
+  };
+
+  return (
+    <LicenseContext.Provider value={contextValue}>
+      {children}
+    </LicenseContext.Provider>
+  );
+};
+
+/**
+ * License Context Hook
+ * 
+ * Provides access to license context in functional components.
+ * Includes helpful error message if used outside of LicenseProvider.
+ */
+export const useLicense = (): LicenseContextState => {
+  const context = useContext(LicenseContext);
+  if (!context) {
+    throw new Error('useLicense must be used within a LicenseProvider');
+  }
+  return context;
+};
+
+/**
+ * Convenience hooks for common license operations
+ * 
+ * These hooks provide simplified interfaces for the most common license
+ * checks, making it easier to implement license-aware features.
+ */
+
+/**
+ * Hook for feature availability checking
+ * Returns boolean for simple feature gates
+ */
+export const useHasFeature = (feature: string): boolean => {
+  const { hasFeature } = useLicense();
+  return hasFeature(feature);
+};
+
+/**
+ * Hook for tier checking
+ * Returns boolean for tier-based logic
+ */
+export const useIsOnTier = (tier: string): boolean => {
+  const { isOnTier } = useLicense();
+  return isOnTier(tier);
+};
+
+/**
+ * Hook for tier hierarchy checking
+ * Returns boolean for tier-or-higher logic
+ */
+export const useHasTierOrHigher = (tier: string): boolean => {
+  const { hasTierOrHigher } = useLicense();
+  return hasTierOrHigher(tier);
+};
+
+/**
+ * Hook for quota monitoring
+ * Returns quota usage percentage for progress bars and warnings
+ */
+export const useQuotaUsage = (quotaType: keyof LicenseQuotas): number => {
+  const { getQuotaUsage } = useLicense();
+  return getQuotaUsage(quotaType);
+};
+
+/**
+ * Hook for approaching limit warnings
+ * Returns boolean for quota limit warnings
+ */
+export const useIsApproachingLimit = (
+  quotaType: keyof LicenseQuotas, 
+  threshold?: number
+): boolean => {
+  const { isApproachingLimit } = useLicense();
+  return isApproachingLimit(quotaType, threshold);
+};
+
+/**
+ * Hook for urgent upgrade suggestions
+ * Returns high-priority suggestions for prominent display
+ */
+export const useUrgentSuggestions = (): UpgradeSuggestion[] => {
+  const { getUrgentSuggestions } = useLicense();
+  return getUrgentSuggestions();
+};
+
+/**
+ * Hook for current license status
+ * Returns complete license status object
+ */
+export const useLicenseStatus = (): LicenseStatus | null => {
+  const { licenseStatus } = useLicense();
+  return licenseStatus;
+};
+
+/**
+ * Hook for license loading state
+ * Useful for showing loading indicators during license operations
+ */
+export const useLicenseLoading = (): boolean => {
+  const { isLoading } = useLicense();
+  return isLoading;
+};
+
+/**
+ * Hook for license error handling
+ * Returns current license error state for error boundaries
+ */
+export const useLicenseError = (): string | null => {
+  const { error } = useLicense();
+  return error;
+};
+
+export default LicenseContext;