@djangocfg/layouts 2.1.35 → 2.1.37

package/src/snippets/PWA/hooks/usePushNotifications.ts

@@ -0,0 +1,205 @@
+'use client';
+
+/**
+ * Push Notifications Hook
+ *
+ * Manages push notification subscription state
+ * Integrates with @djangocfg/nextjs/pwa
+ */
+
+import { useState, useEffect } from 'react';
+import type { PushNotificationState, PushNotificationOptions } from '../types';
+import { pwaLogger } from '../utils/logger';
+import { urlBase64ToUint8Array, VapidKeyError } from '../utils/vapid';
+
+export function usePushNotifications(options?: PushNotificationOptions) {
+  const [state, setState] = useState<PushNotificationState>({
+    isSupported: false,
+    permission: 'default',
+    isSubscribed: false,
+    subscription: null,
+  });
+
+  // Check if push notifications are supported
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const isSupported = 'serviceWorker' in navigator && 'PushManager' in window && 'Notification' in window;
+
+    setState((prev) => ({
+      ...prev,
+      isSupported,
+      permission: isSupported ? Notification.permission : 'denied',
+    }));
+
+    // Check existing subscription
+    if (isSupported) {
+      navigator.serviceWorker.ready
+        .then((registration) => registration.pushManager.getSubscription())
+        .then((subscription) => {
+          setState((prev) => ({
+            ...prev,
+            isSubscribed: !!subscription,
+            subscription,
+          }));
+        })
+        .catch((error) => {
+          pwaLogger.error('[usePushNotifications] Failed to get subscription:', error);
+        });
+    }
+  }, []);
+
+  const subscribe = async (): Promise<boolean> => {
+    if (!state.isSupported) {
+      pwaLogger.warn('[usePushNotifications] Push notifications not supported');
+      return false;
+    }
+
+    if (!options?.vapidPublicKey) {
+      pwaLogger.error('[usePushNotifications] VAPID public key required');
+      return false;
+    }
+
+    try {
+      // Pre-flight check: Test network connectivity
+      pwaLogger.debug('[usePushNotifications] Running pre-flight checks...');
+
+      // Check if we're online
+      if (!navigator.onLine) {
+        pwaLogger.error('[usePushNotifications] No internet connection');
+        throw new Error('No internet connection. Please check your network and try again.');
+      }
+
+      // Request permission
+      const permission = await Notification.requestPermission();
+      setState((prev) => ({ ...prev, permission }));
+
+      if (permission !== 'granted') {
+        pwaLogger.warn('[usePushNotifications] Permission not granted:', permission);
+        return false;
+      }
+
+      // Subscribe to push
+      const registration = await navigator.serviceWorker.ready;
+
+      // Convert and validate VAPID key
+      let applicationServerKey: Uint8Array;
+      try {
+        pwaLogger.debug('[usePushNotifications] Converting VAPID key...');
+        applicationServerKey = urlBase64ToUint8Array(options.vapidPublicKey);
+        pwaLogger.info('[usePushNotifications] VAPID key validated successfully');
+      } catch (e) {
+        if (e instanceof VapidKeyError) {
+          pwaLogger.error(`[usePushNotifications] Invalid VAPID key: ${e.message} (code: ${e.code})`);
+        } else {
+          pwaLogger.error('[usePushNotifications] Failed to convert VAPID key:', e);
+        }
+        return false;
+      }
+
+      // Diagnostic logging (only in debug mode)
+      pwaLogger.debug('[usePushNotifications] Service Worker state:', {
+        controller: navigator.serviceWorker.controller ? 'active' : 'none',
+        registrationActive: registration.active ? 'yes' : 'no',
+        permission: Notification.permission,
+      });
+
+      // Check for existing subscription and unsubscribe
+      const existingSub = await registration.pushManager.getSubscription();
+      if (existingSub) {
+        pwaLogger.debug('[usePushNotifications] Unsubscribing from existing subscription...');
+        await existingSub.unsubscribe();
+      }
+
+      // Prepare subscription options
+      const subscribeOptions = {
+        userVisibleOnly: true,
+        applicationServerKey: applicationServerKey as unknown as BufferSource,
+      };
+
+      pwaLogger.debug('[usePushNotifications] Subscribing with VAPID key...');
+
+      // Attempt subscribe
+      const subscription = await registration.pushManager.subscribe(subscribeOptions);
+
+      // Send subscription to server
+      if (options.subscribeEndpoint) {
+        await fetch(options.subscribeEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(subscription),
+        });
+      }
+
+      setState((prev) => ({
+        ...prev,
+        isSubscribed: true,
+        subscription,
+      }));
+
+      pwaLogger.success('[usePushNotifications] Successfully subscribed to push notifications');
+      return true;
+    } catch (error: any) {
+      pwaLogger.error('[usePushNotifications] Subscribe failed:', error);
+
+      // Specific diagnostic for push service errors
+      if (error.name === 'AbortError' || error.message?.includes('push service error')) {
+        pwaLogger.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        pwaLogger.error('❌ PUSH SERVICE ERROR - Cannot connect to FCM');
+        pwaLogger.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        pwaLogger.error('');
+        pwaLogger.error('🔍 This is NOT a code bug - it\'s a network/security block.');
+        pwaLogger.error('');
+        pwaLogger.error('✅ Quick Fixes (try in order):');
+        pwaLogger.error('  1. Disable VPN/Proxy and refresh page');
+        pwaLogger.error('  2. Open Incognito window (Cmd+Shift+N)');
+        pwaLogger.error('  3. Try different browser (Safari, Firefox)');
+        pwaLogger.error('  4. Use mobile hotspot instead of WiFi');
+        pwaLogger.error('');
+        pwaLogger.error('🔧 Technical Details:');
+        pwaLogger.error('  • Browser tries to connect to FCM (ports 5228-5230)');
+        pwaLogger.error('  • VPN/Firewall/Privacy settings may block these ports');
+        pwaLogger.error('  • Check browser console for "AbortError" details');
+        pwaLogger.error('');
+        pwaLogger.error('📚 Learn more: https://web.dev/push-notifications-overview/');
+        pwaLogger.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+      } else if (error.message?.includes('No internet connection')) {
+        pwaLogger.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        pwaLogger.error('❌ NO INTERNET CONNECTION');
+        pwaLogger.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        pwaLogger.error('Please check your network connection and try again.');
+      } else {
+        pwaLogger.error('Unknown error:', error.name, error.message);
+      }
+
+      return false;
+    }
+  };
+
+  const unsubscribe = async (): Promise<boolean> => {
+    if (!state.subscription) {
+      pwaLogger.warn('[usePushNotifications] No active subscription to unsubscribe');
+      return false;
+    }
+
+    try {
+      await state.subscription.unsubscribe();
+      setState((prev) => ({
+        ...prev,
+        isSubscribed: false,
+        subscription: null,
+      }));
+      pwaLogger.info('[usePushNotifications] Successfully unsubscribed from push notifications');
+      return true;
+    } catch (error) {
+      pwaLogger.error('[usePushNotifications] Unsubscribe failed:', error);
+      return false;
+    }
+  };
+
+  return {
+    ...state,
+    subscribe,
+    unsubscribe,
+  };
+}

package/src/snippets/PWA/index.ts

@@ -0,0 +1,95 @@
+/**
+ * PWA Install Flow (Simplified)
+ *
+ * Ultra-simple PWA installation for Cmdop
+ * No tracking, no metrics, no complexity — just install
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { InstallProvider, A2HSHint } from './PwaInstall';
+ * import { DEFAULT_VAPID_PUBLIC_KEY } from './config';
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <InstallProvider>
+ *       {children}
+ *       <A2HSHint resetAfterDays={3} />
+ *     </InstallProvider>
+ *   );
+ * }
+ * ```
+ */
+
+// Main API
+export { PwaProvider, useInstall } from './context/InstallContext';
+export { PushProvider, usePush } from './context/PushContext';
+export type { PushMessage, PushContextValue } from './context/PushContext';
+
+// Django Integration
+export { DjangoPushProvider, useDjangoPushContext } from './context/DjangoPushContext';
+export { A2HSHint } from './components/A2HSHint';
+export { PushPrompt } from './components/PushPrompt';
+export { DEFAULT_VAPID_PUBLIC_KEY } from './config';
+
+// Hooks
+export { useIsPWA, clearIsPWACache, type UseIsPWAOptions } from './hooks/useIsPWA';
+export { usePushNotifications } from './hooks/usePushNotifications';
+export { useDjangoPush } from './hooks/useDjangoPush';
+
+// Utilities
+export {
+  isStandalone,
+  isStandaloneReliable,
+  isMobileDevice,
+  hasValidManifest,
+  getDisplayMode,
+  onDisplayModeChange,
+} from './utils/platform';
+
+export {
+  pwaLogger,
+  enablePWADebug,
+  disablePWADebug,
+  isPWADebugEnabled,
+} from './utils/logger';
+
+export {
+  urlBase64ToUint8Array,
+  isValidVapidKey,
+  getVapidKeyInfo,
+  safeUrlBase64ToUint8Array,
+  VapidKeyError,
+  type VapidKeyErrorCode,
+} from './utils/vapid';
+
+export {
+  STORAGE_KEYS,
+  markA2HSDismissed,
+  markPushDismissed,
+  isA2HSDismissedRecently,
+  isPushDismissedRecently,
+  clearAllPWAData,
+} from './utils/localStorage';
+
+// Types - Platform
+export type { PlatformInfo } from './types';
+
+// Types - Install
+export type {
+  InstallPromptState,
+  BeforeInstallPromptEvent,
+  InstallOutcome,
+  IOSGuideState,
+} from './types';
+
+// Types - Push Notifications
+export type { PushNotificationState, PushNotificationOptions } from './types';
+
+// Types - Components
+export type {
+  InstallContextType,
+  InstallManagerProps,
+  AndroidInstallButtonProps,
+  IOSGuideModalProps,
+  InstallStep,
+} from './types';

package/src/snippets/PWA/types/components.ts

@@ -0,0 +1,101 @@
+/**
+ * Component Props Types
+ */
+
+import type { PlatformInfo } from './platform';
+import type { InstallOutcome } from './install';
+import type { PushNotificationState } from './push';
+
+/**
+ * Install context type
+ */
+export interface InstallContextType {
+  // State
+  platform: PlatformInfo;
+  isInstalled: boolean;
+  canPrompt: boolean;
+
+  // iOS Guide
+  showIOSGuide: boolean;
+  setShowIOSGuide: (show: boolean) => void;
+
+  // Actions
+  promptInstall: () => Promise<InstallOutcome>;
+  dismissIOSGuide: () => void;
+
+  // Push Notifications
+  pushState: PushNotificationState;
+  subscribeToPush: () => Promise<boolean>;
+  unsubscribeFromPush: () => Promise<boolean>;
+}
+
+/**
+ * Install manager props
+ */
+export interface InstallManagerProps {
+  /**
+   * Delay before showing iOS guide (ms)
+   * @default 2000
+   */
+  delayMs?: number;
+
+  /**
+   * Number of days before re-showing dismissed guide
+   * @default 7
+   */
+  resetDays?: number;
+
+  /**
+   * Custom class name for install button
+   */
+  buttonClassName?: string;
+
+  /**
+   * Custom button text
+   */
+  buttonText?: string;
+
+  /**
+   * Force show install UI (ignores platform detection)
+   * Useful for testing on desktop in development
+   * @default false
+   */
+  forceShow?: boolean;
+
+  /**
+   * Callback when install is successful
+   */
+  onInstallSuccess?: () => void;
+
+  /**
+   * Callback when install is dismissed
+   */
+  onInstallDismiss?: () => void;
+}
+
+/**
+ * Android install button props
+ */
+export interface AndroidInstallButtonProps {
+  onInstall: () => Promise<InstallOutcome>;
+  className?: string;
+  text?: string;
+}
+
+/**
+ * iOS guide modal props
+ */
+export interface IOSGuideModalProps {
+  onDismiss: () => void;
+  open?: boolean;
+}
+
+/**
+ * Install step for iOS guide
+ */
+export interface InstallStep {
+  number: number;
+  title: string;
+  icon: React.ComponentType<{ className?: string }>;
+  description: string;
+}

package/src/snippets/PWA/types/index.ts

@@ -0,0 +1,26 @@
+/**
+ * PWA Types - Central Export
+ */
+
+// Platform
+export type { PlatformInfo } from './platform';
+
+// Install
+export type {
+  InstallPromptState,
+  BeforeInstallPromptEvent,
+  InstallOutcome,
+  IOSGuideState,
+} from './install';
+
+// Push Notifications
+export type { PushNotificationState, PushNotificationOptions } from './push';
+
+// Components
+export type {
+  InstallContextType,
+  InstallManagerProps,
+  AndroidInstallButtonProps,
+  IOSGuideModalProps,
+  InstallStep,
+} from './components';

package/src/snippets/PWA/types/install.ts

@@ -0,0 +1,38 @@
+/**
+ * PWA Installation Types
+ */
+
+/**
+ * Install prompt state
+ */
+export interface InstallPromptState {
+  isIOS: boolean;
+  isAndroid: boolean;
+  isSafari: boolean;
+  isChrome: boolean;
+  isInstalled: boolean;
+  canPrompt: boolean;
+  deferredPrompt: BeforeInstallPromptEvent | null;
+}
+
+/**
+ * BeforeInstallPrompt event (Android Chrome)
+ */
+export interface BeforeInstallPromptEvent extends Event {
+  prompt: () => Promise<void>;
+  userChoice: Promise<{ outcome: 'accepted' | 'dismissed'; platform: string }>;
+}
+
+/**
+ * Install outcome
+ */
+export type InstallOutcome = 'accepted' | 'dismissed' | null;
+
+/**
+ * iOS guide dismissal state
+ */
+export interface IOSGuideState {
+  dismissed: boolean;
+  dismissedAt: number | null;
+  shouldShow: boolean;
+}

package/src/snippets/PWA/types/platform.ts

@@ -0,0 +1,29 @@
+/**
+ * Platform Detection Types
+ */
+
+/**
+ * Platform detection result
+ */
+export interface PlatformInfo {
+  // Operating System
+  isIOS: boolean;
+  isAndroid: boolean;
+  isDesktop: boolean;
+
+  // Browser
+  isSafari: boolean;
+  isChrome: boolean;
+  isEdge: boolean;
+  isFirefox: boolean;
+
+  // Installation State
+  isStandalone: boolean;
+
+  // Capability
+  canPrompt: boolean;
+
+  // Composite checks
+  shouldShowAndroidPrompt: boolean;
+  shouldShowIOSGuide: boolean;
+}

package/src/snippets/PWA/types/push.ts

@@ -0,0 +1,21 @@
+/**
+ * Push Notification Types
+ */
+
+/**
+ * Push notification state
+ */
+export interface PushNotificationState {
+  isSupported: boolean;
+  permission: NotificationPermission;
+  isSubscribed: boolean;
+  subscription: PushSubscription | null;
+}
+
+/**
+ * Push notification options
+ */
+export interface PushNotificationOptions {
+  vapidPublicKey: string;
+  subscribeEndpoint?: string;
+}