@djangocfg/layouts 2.1.37 → 2.1.38

package/src/snippets/PushNotifications/context/DjangoPushContext.tsx

@@ -0,0 +1,190 @@
+'use client';
+
+/**
+ * Django Push Context
+ *
+ * Provider for Django-CFG push notifications integration.
+ * Wraps useDjangoPush hook in React context for easy consumption.
+ *
+ * @example
+ * ```tsx
+ * import { DjangoPushProvider, useDjangoPushContext } from '@djangocfg/layouts/PWA';
+ *
+ * // In layout
+ * <DjangoPushProvider vapidPublicKey={process.env.NEXT_PUBLIC_VAPID_KEY}>
+ *   {children}
+ * </DjangoPushProvider>
+ *
+ * // In component
+ * function NotifyButton() {
+ *   const { subscribe, isSubscribed } = useDjangoPushContext();
+ *   return <button onClick={subscribe}>Subscribe</button>;
+ * }
+ * ```
+ */
+
+import React, { createContext, useContext, useState, useEffect, useCallback } from 'react';
+import { useDjangoPush } from '../hooks/useDjangoPush';
+import { pwaLogger } from '../utils/logger';
+import type { PushNotificationOptions } from '../types';
+
+export interface PushMessage {
+  id: string;
+  title: string;
+  body: string;
+  icon?: string;
+  badge?: string;
+  tag?: string;
+  timestamp: number;
+  data?: Record<string, unknown>;
+}
+
+interface DjangoPushContextValue {
+  // State
+  isSupported: boolean;
+  permission: NotificationPermission;
+  isSubscribed: boolean;
+  subscription: PushSubscription | null;
+  isLoading: boolean;
+  error: Error | null;
+
+  // Push history
+  pushes: PushMessage[];
+
+  // Actions
+  subscribe: () => Promise<boolean>;
+  unsubscribe: () => Promise<boolean>;
+  sendTestPush: (message: { title: string; body: string; url?: string }) => Promise<boolean>;
+  sendPush: (message: Omit<PushMessage, 'id' | 'timestamp'>) => Promise<void>;
+  clearPushes: () => void;
+  removePush: (id: string) => void;
+}
+
+const DjangoPushContext = createContext<DjangoPushContextValue | undefined>(undefined);
+
+interface DjangoPushProviderProps extends PushNotificationOptions {
+  children: React.ReactNode;
+
+  /**
+   * Auto-subscribe on mount if permission granted
+   * @default false
+   */
+  autoSubscribe?: boolean;
+
+  /**
+   * Callback when subscription created
+   */
+  onSubscribed?: (subscription: PushSubscription) => void;
+
+  /**
+   * Callback when subscription failed
+   */
+  onSubscribeError?: (error: Error) => void;
+
+  /**
+   * Callback when unsubscribed
+   */
+  onUnsubscribed?: () => void;
+}
+
+/**
+ * Provider for Django push notifications
+ */
+export function DjangoPushProvider({
+  children,
+  vapidPublicKey,
+  autoSubscribe = false,
+  onSubscribed,
+  onSubscribeError,
+  onUnsubscribed,
+}: DjangoPushProviderProps) {
+  const djangoPush = useDjangoPush({
+    vapidPublicKey,
+    onSubscribed,
+    onSubscribeError,
+    onUnsubscribed,
+  });
+
+  // Auto-subscribe on mount if permission already granted
+  useEffect(() => {
+    if (
+      autoSubscribe &&
+      djangoPush.isSupported &&
+      djangoPush.permission === 'granted' &&
+      !djangoPush.isSubscribed &&
+      !djangoPush.isLoading
+    ) {
+      pwaLogger.info('[DjangoPushProvider] Auto-subscribing (permission already granted)');
+      djangoPush.subscribe();
+    }
+  }, [autoSubscribe, djangoPush.isSupported, djangoPush.permission, djangoPush.isSubscribed, djangoPush.isLoading]);
+
+  const [pushes, setPushes] = useState<PushMessage[]>([]);
+
+  // Listen for push messages from service worker
+  useEffect(() => {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) {
+      return;
+    }
+
+    const handleMessage = (event: MessageEvent) => {
+      if (event.data && event.data.type === 'PUSH_RECEIVED') {
+        const push: PushMessage = {
+          id: crypto.randomUUID(),
+          timestamp: Date.now(),
+          ...event.data.notification,
+        };
+
+        setPushes(prev => [push, ...prev]);
+        pwaLogger.info('[DjangoPushProvider] Push received:', push);
+      }
+    };
+
+    navigator.serviceWorker.addEventListener('message', handleMessage);
+    return () => navigator.serviceWorker.removeEventListener('message', handleMessage);
+  }, []);
+
+  const sendPush = useCallback(
+    async (message: Omit<PushMessage, 'id' | 'timestamp'>) => {
+      await djangoPush.sendTestPush({
+        title: message.title,
+        body: message.body,
+        url: message.data?.url as string | undefined,
+      });
+    },
+    [djangoPush]
+  );
+
+  const clearPushes = useCallback(() => {
+    setPushes([]);
+    pwaLogger.info('[DjangoPushProvider] Push history cleared');
+  }, []);
+
+  const removePush = useCallback((id: string) => {
+    setPushes(prev => prev.filter(p => p.id !== id));
+    pwaLogger.info('[DjangoPushProvider] Push removed:', id);
+  }, []);
+
+  const value: DjangoPushContextValue = {
+    ...djangoPush,
+    pushes,
+    sendPush,
+    clearPushes,
+    removePush,
+  };
+
+  return <DjangoPushContext.Provider value={value}>{children}</DjangoPushContext.Provider>;
+}
+
+/**
+ * Hook to access Django push context
+ */
+export function useDjangoPushContext(): DjangoPushContextValue {
+  const context = useContext(DjangoPushContext);
+
+  if (context === undefined) {
+    throw new Error('useDjangoPushContext must be used within DjangoPushProvider');
+  }
+
+  return context;
+}

package/src/snippets/{PWA → PushNotifications}/hooks/useDjangoPush.ts

@@ -3,21 +3,26 @@
 /**
  * Django Push Notifications Hook
  *
- * Integrates @djangocfg/layouts/PWA with Django-CFG backend API.
+ * Integrates usePushNotifications with Django-CFG backend API.
  * Uses generated TypeScript client from @djangocfg/api for type-safe integration.
+ * Requires authentication - opens AuthDialog if user is not logged in.
+ *
+ * Architecture:
+ * - usePushNotifications: handles all browser Push API operations
+ * - useDjangoPush: adds Django backend sync on top
  *
  * @example
  * ```tsx
- * import { useDjangoPush } from '@djangocfg/layouts/PWA';
+ * import { useDjangoPush } from '@djangocfg/layouts/snippets';
  *
  * function NotificationsButton() {
- *   const { subscribe, isSubscribed, permission } = useDjangoPush({
+ *   const { subscribe, unsubscribe, isSubscribed } = useDjangoPush({
  *     vapidPublicKey: 'YOUR_VAPID_KEY'
  *   });
  *
  *   return (
- *     <button onClick={subscribe} disabled={isSubscribed}>
- *       {isSubscribed ? 'Subscribed' : 'Enable Notifications'}
+ *     <button onClick={isSubscribed ? unsubscribe : subscribe}>
+ *       {isSubscribed ? 'Unsubscribe' : 'Subscribe'}
  *     </button>
  *   );
  * }
@@ -25,21 +30,20 @@
  */
 
 import { useState, useCallback } from 'react';
+import { toast } from 'sonner';
 import { usePushNotifications } from './usePushNotifications';
 import { pwaLogger } from '../utils/logger';
 import type { PushNotificationOptions } from '../types';
 
+// Auth
+import { useAuth } from '@djangocfg/api/auth';
+import { useAuthDialog } from '../../AuthDialog';
+
 // Import Django API client
 // @ts-ignore - optional peer dependency
-import { apiAccounts, apiWebPush } from '@djangocfg/api/clients';
+import { apiWebPush } from '@djangocfg/api/clients';
 
 interface UseDjangoPushOptions extends PushNotificationOptions {
-  /**
-   * Auto-subscribe on mount if permission granted
-   * @default false
-   */
-  autoSubscribe?: boolean;
-
   /**
    * Callback when subscription created
    */
@@ -57,11 +61,13 @@ interface UseDjangoPushOptions extends PushNotificationOptions {
 }
 
 interface UseDjangoPushReturn {
-  // State
+  // State (from usePushNotifications)
   isSupported: boolean;
   permission: NotificationPermission;
   isSubscribed: boolean;
   subscription: PushSubscription | null;
+
+  // Local state
   isLoading: boolean;
   error: Error | null;
 
@@ -75,35 +81,27 @@ interface UseDjangoPushReturn {
  * Hook for Django-CFG push notifications integration
  */
 export function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushReturn {
-  const {
-    autoSubscribe = false,
-    onSubscribed,
-    onSubscribeError,
-    onUnsubscribed,
-    ...pushOptions
-  } = options;
+  const { onSubscribed, onSubscribeError, onUnsubscribed, ...pushOptions } = options;
 
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
-  // Use base push notifications hook
+  // Auth check
+  const { isAuthenticated } = useAuth();
+  const { openAuthDialog } = useAuthDialog();
+
+  // Use base push notifications hook (handles all browser API)
   const pushNotifications = usePushNotifications(pushOptions);
 
   /**
    * Subscribe to push notifications and save to Django backend
    */
   const subscribe = useCallback(async (): Promise<boolean> => {
-    if (!pushNotifications.isSupported) {
-      const err = new Error('Push notifications not supported');
-      setError(err);
-      onSubscribeError?.(err);
-      return false;
-    }
-
-    if (!options.vapidPublicKey) {
-      const err = new Error('VAPID public key required');
-      setError(err);
-      onSubscribeError?.(err);
+    // Auth check - require login for push subscriptions
+    if (!isAuthenticated) {
+      openAuthDialog({
+        message: 'Please sign in to enable push notifications',
+      });
       return false;
     }
 
@@ -111,26 +109,20 @@ export function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushRetur
     setError(null);
 
     try {
-      // Step 1: Request permission
-      const permission = await Notification.requestPermission();
-      if (permission !== 'granted') {
-        throw new Error(`Permission ${permission}`);
-      }
+      // Step 1: Browser subscription via usePushNotifications
+      const subscription = await pushNotifications.subscribe();
 
-      // Step 2: Get service worker registration
-      const registration = await navigator.serviceWorker.ready;
-
-      // Step 3: Subscribe to push manager
-      const subscription = await registration.pushManager.subscribe({
-        userVisibleOnly: true,
-        applicationServerKey: urlBase64ToUint8Array(options.vapidPublicKey) as BufferSource,
-      });
+      if (!subscription) {
+        // Permission denied or other browser error
+        const err = new Error('Browser subscription failed');
+        setError(err);
+        onSubscribeError?.(err);
+        return false;
+      }
 
-      pwaLogger.info('[useDjangoPush] Browser subscription created:', {
-        endpoint: subscription.endpoint.substring(0, 50) + '...',
-      });
+      pwaLogger.info('[useDjangoPush] Browser subscription created');
 
-      // Step 4: Save to Django backend using generated API client
+      // Step 2: Save to Django backend
       const result = await apiWebPush.web_push.webpushSubscribeCreate({
         endpoint: subscription.endpoint,
         keys: {
@@ -142,43 +134,47 @@ export function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushRetur
       pwaLogger.info('[useDjangoPush] Subscription saved to Django:', result);
 
       onSubscribed?.(subscription);
+      toast.success('Push notifications enabled');
       return true;
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
       pwaLogger.error('[useDjangoPush] Subscribe failed:', error);
       setError(error);
       onSubscribeError?.(error);
+
+      toast.error('Subscription Failed', {
+        description: 'Could not save subscription to server. Please try again.',
+        duration: 5000,
+      });
+
       return false;
     } finally {
       setIsLoading(false);
     }
-  }, [
-    pushNotifications.isSupported,
-    options.vapidPublicKey,
-    onSubscribed,
-    onSubscribeError,
-  ]);
+  }, [isAuthenticated, openAuthDialog, pushNotifications.subscribe, onSubscribed, onSubscribeError]);
 
   /**
    * Unsubscribe from push notifications
    */
   const unsubscribe = useCallback(async (): Promise<boolean> => {
-    if (!pushNotifications.subscription) {
-      return false;
-    }
-
     setIsLoading(true);
     setError(null);
 
     try {
-      // Unsubscribe from push manager
-      await pushNotifications.subscription.unsubscribe();
+      // Unsubscribe via usePushNotifications (handles browser API)
+      const success = await pushNotifications.unsubscribe();
+
+      if (!success) {
+        return false;
+      }
+
       pwaLogger.info('[useDjangoPush] Browser unsubscribed');
 
-      // Note: Django backend will auto-cleanup inactive subscriptions
-      // No need to explicitly remove since subscription.endpoint becomes invalid
+      // Note: Django backend auto-cleans up inactive subscriptions
+      // when push delivery fails (410 Gone response)
 
       onUnsubscribed?.();
+      toast.success('Push notifications disabled');
       return true;
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
@@ -188,7 +184,7 @@ export function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushRetur
     } finally {
       setIsLoading(false);
     }
-  }, [pushNotifications.subscription, onUnsubscribed]);
+  }, [pushNotifications.unsubscribe, onUnsubscribed]);
 
   /**
    * Send test push notification
@@ -227,11 +223,13 @@ export function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushRetur
   );
 
   return {
-    // State
+    // State from usePushNotifications
     isSupported: pushNotifications.isSupported,
     permission: pushNotifications.permission,
     isSubscribed: pushNotifications.isSubscribed,
     subscription: pushNotifications.subscription,
+
+    // Local state
     isLoading,
     error,
 
@@ -246,22 +244,6 @@ export function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushRetur
 // Utilities
 // ============================================================================
 
-/**
- * Convert base64 VAPID key to Uint8Array
- */
-function urlBase64ToUint8Array(base64String: string): Uint8Array {
-  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
-  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
-
-  const rawData = window.atob(base64);
-  const outputArray = new Uint8Array(rawData.length);
-
-  for (let i = 0; i < rawData.length; ++i) {
-    outputArray[i] = rawData.charCodeAt(i);
-  }
-  return outputArray;
-}
-
 /**
  * Convert ArrayBuffer to base64 string
  */

package/src/snippets/{PWA → PushNotifications}/hooks/usePushNotifications.ts

@@ -49,15 +49,19 @@ export function usePushNotifications(options?: PushNotificationOptions) {
     }
   }, []);
 
-  const subscribe = async (): Promise<boolean> => {
+  /**
+   * 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 false;
+      return null;
     }
 
     if (!options?.vapidPublicKey) {
       pwaLogger.error('[usePushNotifications] VAPID public key required');
-      return false;
+      return null;
     }
 
     try {
@@ -76,7 +80,7 @@ export function usePushNotifications(options?: PushNotificationOptions) {
 
       if (permission !== 'granted') {
         pwaLogger.warn('[usePushNotifications] Permission not granted:', permission);
-        return false;
+        return null;
       }
 
       // Subscribe to push
@@ -94,7 +98,7 @@ export function usePushNotifications(options?: PushNotificationOptions) {
         } else {
           pwaLogger.error('[usePushNotifications] Failed to convert VAPID key:', e);
         }
-        return false;
+        return null;
       }
 
       // Diagnostic logging (only in debug mode)
@@ -122,7 +126,7 @@ export function usePushNotifications(options?: PushNotificationOptions) {
       // Attempt subscribe
       const subscription = await registration.pushManager.subscribe(subscribeOptions);
 
-      // Send subscription to server
+      // Send subscription to server (legacy endpoint support)
       if (options.subscribeEndpoint) {
         await fetch(options.subscribeEndpoint, {
           method: 'POST',
@@ -138,7 +142,7 @@ export function usePushNotifications(options?: PushNotificationOptions) {
       }));
 
       pwaLogger.success('[usePushNotifications] Successfully subscribed to push notifications');
-      return true;
+      return subscription;
     } catch (error: any) {
       pwaLogger.error('[usePushNotifications] Subscribe failed:', error);
 
@@ -172,7 +176,7 @@ export function usePushNotifications(options?: PushNotificationOptions) {
         pwaLogger.error('Unknown error:', error.name, error.message);
       }
 
-      return false;
+      return null;
     }
   };
 

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';