@djangocfg/layouts 2.1.36 → 2.1.38

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

@@ -0,0 +1,209 @@
+'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);
+        });
+    }
+  }, []);
+
+  /**
+   * Subscribe to push notifications
+   * @returns subscription on success, null on failure
+   */
+  const subscribe = async (): Promise<PushSubscription | null> => {
+    if (!state.isSupported) {
+      pwaLogger.warn('[usePushNotifications] Push notifications not supported');
+      return null;
+    }
+
+    if (!options?.vapidPublicKey) {
+      pwaLogger.error('[usePushNotifications] VAPID public key required');
+      return null;
+    }
+
+    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 null;
+      }
+
+      // 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 null;
+      }
+
+      // 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 (legacy endpoint support)
+      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 subscription;
+    } 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 null;
+    }
+  };
+
+  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/PushNotifications/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Push Notifications Snippet
+ *
+ * Web Push Notifications management with Django-CFG integration
+ * Includes push history, subscription management, and Django API integration
+ *
+ * @example Usage
+ * ```tsx
+ * import { DjangoPushProvider, useDjangoPushContext } from '@/snippets/PushNotifications';
+ *
+ * // In layout
+ * export default function Layout({ children }) {
+ *   return (
+ *     <DjangoPushProvider
+ *       vapidPublicKey={process.env.NEXT_PUBLIC_VAPID_KEY}
+ *       autoSubscribe={false}
+ *     >
+ *       {children}
+ *       <PushPrompt requirePWA={true} />
+ *     </DjangoPushProvider>
+ *   );
+ * }
+ *
+ * // In component
+ * function PushDemo() {
+ *   const { isSubscribed, pushes, subscribe, sendPush } = useDjangoPushContext();
+ *
+ *   return (
+ *     <div>
+ *       {!isSubscribed && <button onClick={subscribe}>Subscribe</button>}
+ *       <div>Received {pushes.length} notifications</div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @note For backwards compatibility, you can also use `PushProvider` and `usePush`
+ * aliases which point to the same Django implementation.
+ */
+
+// Main API - Django Push Integration
+export { DjangoPushProvider, useDjangoPushContext } from './context/DjangoPushContext';
+export type { PushMessage } from './context/DjangoPushContext';
+
+// Backwards compatibility aliases
+export { DjangoPushProvider as PushProvider } from './context/DjangoPushContext';
+export { useDjangoPushContext as usePush } from './context/DjangoPushContext';
+
+// Components
+export { PushPrompt } from './components/PushPrompt';
+
+// Hooks
+export { usePushNotifications } from './hooks/usePushNotifications';
+export { useDjangoPush } from './hooks/useDjangoPush';
+
+// Config
+export { DEFAULT_VAPID_PUBLIC_KEY } from './config';
+
+// Utilities
+export {
+  urlBase64ToUint8Array,
+  isValidVapidKey,
+  getVapidKeyInfo,
+  safeUrlBase64ToUint8Array,
+  VapidKeyError,
+  type VapidKeyErrorCode,
+} from './utils/vapid';
+
+export {
+  pwaLogger,
+  enablePWADebug,
+  disablePWADebug,
+  isPWADebugEnabled,
+} from './utils/logger';
+
+export {
+  STORAGE_KEYS,
+  markPushDismissed,
+  isPushDismissedRecently,
+  clearAllPushData,
+} from './utils/localStorage';
+
+// Types - Configuration
+export type { PushNotificationsConfig } from './types';
+
+// Types
+export type { PushNotificationState, PushNotificationOptions } from './types';

package/src/snippets/PushNotifications/types/config.ts

@@ -0,0 +1,28 @@
+/**
+ * Push Notifications Configuration Types
+ *
+ * Configuration for Web Push Notifications with VAPID authentication
+ */
+
+export interface PushNotificationsConfig {
+  /** Enable push notifications */
+  enabled?: boolean;
+
+  /** VAPID public key for push notifications (required when enabled) */
+  vapidPublicKey: string;
+
+  /** API endpoint for subscription (default: '/api/push/subscribe') */
+  subscribeEndpoint?: string;
+
+  /** Only show push prompt if PWA is installed (default: true) */
+  requirePWA?: boolean;
+
+  /** Delay before showing push prompt after PWA install (ms) */
+  delayMs?: number;
+
+  /** Number of days before re-showing dismissed push prompt */
+  resetAfterDays?: number;
+
+  /** Auto-subscribe on mount if permission already granted */
+  autoSubscribe?: boolean;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Push Notifications Types - Central Export
+ */
+
+// Configuration
+export type { PushNotificationsConfig } from './config';
+
+// Push Notifications
+export type { PushNotificationState, PushNotificationOptions } from './push';

package/src/snippets/PushNotifications/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;
+}

package/src/snippets/PushNotifications/utils/localStorage.ts

@@ -0,0 +1,60 @@
+/**
+ * LocalStorage utilities for Push Notifications state persistence
+ */
+
+/**
+ * Storage keys
+ */
+export const STORAGE_KEYS = {
+  PUSH_DISMISSED: 'pwa_push_dismissed_at',
+} as const;
+
+/**
+ * Check if push prompt was dismissed recently
+ * @param resetDays Number of days before re-showing (default: 7)
+ */
+export function isPushDismissedRecently(resetDays: number = 7): boolean {
+  return isDismissedRecentlyHelper(resetDays, STORAGE_KEYS.PUSH_DISMISSED);
+}
+
+/**
+ * Mark push prompt as dismissed
+ */
+export function markPushDismissed(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(STORAGE_KEYS.PUSH_DISMISSED, Date.now().toString());
+  } catch {
+    // Fail silently
+  }
+}
+
+/**
+ * Helper: Check if a key was dismissed recently
+ * @internal
+ */
+function isDismissedRecentlyHelper(resetDays: number, key: string): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    const dismissed = localStorage.getItem(key);
+    if (!dismissed) return false;
+    const dismissedAt = parseInt(dismissed, 10);
+    const daysSince = (Date.now() - dismissedAt) / (1000 * 60 * 60 * 24);
+    return daysSince < resetDays;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clear all push notification data
+ */
+export function clearAllPushData(): void {
+  if (typeof window === 'undefined') return;
+
+  try {
+    localStorage.removeItem(STORAGE_KEYS.PUSH_DISMISSED);
+  } catch {
+    // Fail silently
+  }
+}

package/src/snippets/PushNotifications/utils/logger.ts

@@ -0,0 +1,149 @@
+/**
+ * PWA Logger with Conditional Logging
+ *
+ * Provides logging utilities that respect environment and debug settings:
+ * - In production: Only errors are logged
+ * - In development: All levels are logged
+ * - Debug mode: Can be enabled in production via localStorage
+ *
+ * @example
+ * ```typescript
+ * import { pwaLogger } from '../utils/logger';
+ *
+ * pwaLogger.info('Info message'); // Only in dev
+ * pwaLogger.warn('Warning message'); // Only in dev
+ * pwaLogger.error('Error message'); // Always logged
+ * pwaLogger.debug('Debug message'); // Only when debug enabled
+ * ```
+ *
+ * Enable debug mode in production:
+ * ```typescript
+ * import { enablePWADebug } from '../utils/logger';
+ * enablePWADebug();
+ * // or in console:
+ * localStorage.setItem('pwa_debug', 'true');
+ * ```
+ */
+
+import { consola } from 'consola';
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+/**
+ * Check if debug mode is enabled via localStorage
+ */
+function isDebugEnabled(): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    return localStorage.getItem('pwa_debug') === 'true';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * PWA Logger instance with conditional logging
+ */
+export const pwaLogger = {
+  /**
+   * Info level logging
+   * Only logs in development or when debug is enabled
+   */
+  info: (...args: Parameters<typeof consola.info>): void => {
+    if (isDevelopment || isDebugEnabled()) {
+      consola.info(...args);
+    }
+  },
+
+  /**
+   * Warning level logging
+   * Only logs in development or when debug is enabled
+   */
+  warn: (...args: Parameters<typeof consola.warn>): void => {
+    if (isDevelopment || isDebugEnabled()) {
+      consola.warn(...args);
+    }
+  },
+
+  /**
+   * Error level logging
+   * Always logs (production + development)
+   */
+  error: (...args: Parameters<typeof consola.error>): void => {
+    consola.error(...args);
+  },
+
+  /**
+   * Debug level logging
+   * Only logs when debug is explicitly enabled
+   */
+  debug: (...args: Parameters<typeof consola.debug>): void => {
+    if (isDebugEnabled()) {
+      consola.debug(...args);
+    }
+  },
+
+  /**
+   * Success level logging
+   * Only logs in development or when debug is enabled
+   */
+  success: (...args: Parameters<typeof consola.success>): void => {
+    if (isDevelopment || isDebugEnabled()) {
+      consola.success(...args);
+    }
+  },
+};
+
+/**
+ * Enable debug mode
+ *
+ * This allows seeing debug logs in production.
+ * Call this function or set localStorage manually:
+ * `localStorage.setItem('pwa_debug', 'true')`
+ *
+ * @example
+ * ```typescript
+ * import { enablePWADebug } from '@djangocfg/layouts/snippets';
+ * enablePWADebug();
+ * // Reload page to see debug logs
+ * ```
+ */
+export function enablePWADebug(): void {
+  if (typeof window !== 'undefined') {
+    try {
+      localStorage.setItem('pwa_debug', 'true');
+      consola.info('[PWA] Debug mode enabled. Reload page to see debug logs.');
+    } catch (e) {
+      consola.error('[PWA] Failed to enable debug mode:', e);
+    }
+  }
+}
+
+/**
+ * Disable debug mode
+ *
+ * @example
+ * ```typescript
+ * import { disablePWADebug } from '@djangocfg/layouts/snippets';
+ * disablePWADebug();
+ * ```
+ */
+export function disablePWADebug(): void {
+  if (typeof window !== 'undefined') {
+    try {
+      localStorage.removeItem('pwa_debug');
+      consola.info('[PWA] Debug mode disabled.');
+    } catch (e) {
+      consola.error('[PWA] Failed to disable debug mode:', e);
+    }
+  }
+}
+
+/**
+ * Check if debug mode is currently active
+ *
+ * @returns true if debug mode is enabled
+ */
+export function isPWADebugEnabled(): boolean {
+  return isDebugEnabled();
+}