@djangocfg/layouts 2.1.36 → 2.1.38

package/src/snippets/PushNotifications/components/PushPrompt.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+/**
+ * Push Notification Prompt
+ *
+ * Shows after PWA is installed to request push notification permission
+ * Auto-dismisses after user action or timeout
+ */
+
+import React, { useState, useEffect } from 'react';
+import { Bell, X } from 'lucide-react';
+import { Button } from '@djangocfg/ui-nextjs';
+
+import { usePushNotifications } from '../hooks/usePushNotifications';
+import { isStandalone } from '../utils/platform';
+import { pwaLogger } from '../utils/logger';
+import { markPushDismissed, isPushDismissedRecently } from '../utils/localStorage';
+import type { PushNotificationOptions } from '../types';
+
+const DEFAULT_RESET_DAYS = 7;
+
+interface PushPromptProps extends PushNotificationOptions {
+  /**
+   * Only show if PWA is installed
+   * @default true
+   */
+  requirePWA?: boolean;
+
+  /**
+   * Delay before showing prompt (ms)
+   * @default 5000
+   */
+  delayMs?: number;
+
+  /**
+   * Number of days before re-showing dismissed prompt
+   * @default 7
+   */
+  resetAfterDays?: number;
+
+  /**
+   * Callback when push is enabled
+   */
+  onEnabled?: () => void;
+
+  /**
+   * Callback when push is dismissed
+   */
+  onDismissed?: () => void;
+}
+
+export function PushPrompt({
+  vapidPublicKey,
+  subscribeEndpoint = '/api/push/subscribe',
+  requirePWA = true,
+  delayMs = 5000,
+  resetAfterDays = DEFAULT_RESET_DAYS,
+  onEnabled,
+  onDismissed,
+}: PushPromptProps) {
+  const { isSupported, permission, isSubscribed, subscribe } = usePushNotifications({
+    vapidPublicKey,
+    subscribeEndpoint,
+  });
+
+  const [show, setShow] = useState(false);
+  const [enabling, setEnabling] = useState(false);
+
+  // Check if should show
+  useEffect(() => {
+    if (!isSupported || isSubscribed || permission === 'denied') {
+      return;
+    }
+
+    // Check if PWA is installed (standalone mode)
+    if (requirePWA && !isStandalone()) {
+      return;
+    }
+
+    // Check if previously dismissed
+    if (typeof window !== 'undefined') {
+      if (isPushDismissedRecently(resetAfterDays)) {
+        return; // Still within reset period
+      }
+    }
+
+    // Show after delay
+    const timer = setTimeout(() => setShow(true), delayMs);
+    return () => clearTimeout(timer);
+  }, [isSupported, isSubscribed, permission, requirePWA, resetAfterDays, delayMs]);
+
+  const handleEnable = async () => {
+    setEnabling(true);
+    try {
+      const success = await subscribe();
+      if (success) {
+        setShow(false);
+        onEnabled?.();
+      }
+    } catch (error) {
+      pwaLogger.error('[PushPrompt] Enable failed:', error);
+    } finally {
+      setEnabling(false);
+    }
+  };
+
+  const handleDismiss = () => {
+    setShow(false);
+    markPushDismissed();
+    onDismissed?.();
+  };
+
+  if (!show) return null;
+
+  return (
+    <div className="fixed bottom-4 left-4 right-4 z-50 animate-in slide-in-from-bottom-4 duration-300">
+      <div className="bg-zinc-900 border border-zinc-700 rounded-lg p-4 shadow-lg">
+        <div className="flex items-start gap-3">
+          {/* Icon */}
+          <div className="flex-shrink-0">
+            <Bell className="w-5 h-5 text-blue-400" />
+          </div>
+
+          {/* Content */}
+          <div className="flex-1 min-w-0">
+            <p className="text-sm font-medium text-white mb-1">Enable notifications</p>
+            <p className="text-xs text-zinc-400 mb-3">
+              Stay updated with important updates and alerts
+            </p>
+
+            {/* Actions */}
+            <div className="flex gap-2">
+              <Button
+                onClick={handleEnable}
+                loading={enabling}
+                size="sm"
+                variant="default"
+              >
+                Enable
+              </Button>
+              <Button
+                onClick={handleDismiss}
+                size="sm"
+                variant="ghost"
+              >
+                Not now
+              </Button>
+            </div>
+          </div>
+
+          {/* Close button */}
+          <Button
+            onClick={handleDismiss}
+            size="sm"
+            variant="ghost"
+            className="flex-shrink-0 p-1"
+            aria-label="Dismiss"
+          >
+            <X className="w-4 h-4" />
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/snippets/PushNotifications/config.ts

@@ -0,0 +1,20 @@
+/**
+ * Push Notifications Configuration
+ *
+ * Centralized constants for push notifications functionality.
+ *
+ * SECURITY NOTE:
+ * - VAPID_PRIVATE_KEY should NEVER be in frontend code
+ * - Private keys must only exist in backend/API routes
+ * - Frontend only needs the public key (NEXT_PUBLIC_* env vars)
+ * - VAPID_MAILTO should also remain on backend only
+ */
+
+// Default VAPID public key (safe to expose in frontend)
+export const DEFAULT_VAPID_PUBLIC_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY || '';
+
+// NOTE: VAPID private key and mailto should only exist in:
+// - Backend environment variables (not NEXT_PUBLIC_*)
+// - API route handlers (app/api/push/*)
+// - Service worker generation scripts
+// NEVER import or use private keys in frontend code

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/PushNotifications/hooks/useDjangoPush.ts

@@ -0,0 +1,259 @@
+'use client';
+
+/**
+ * Django Push Notifications Hook
+ *
+ * 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/snippets';
+ *
+ * function NotificationsButton() {
+ *   const { subscribe, unsubscribe, isSubscribed } = useDjangoPush({
+ *     vapidPublicKey: 'YOUR_VAPID_KEY'
+ *   });
+ *
+ *   return (
+ *     <button onClick={isSubscribed ? unsubscribe : subscribe}>
+ *       {isSubscribed ? 'Unsubscribe' : 'Subscribe'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+
+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 { apiWebPush } from '@djangocfg/api/clients';
+
+interface UseDjangoPushOptions extends PushNotificationOptions {
+  /**
+   * Callback when subscription created
+   */
+  onSubscribed?: (subscription: PushSubscription) => void;
+
+  /**
+   * Callback when subscription failed
+   */
+  onSubscribeError?: (error: Error) => void;
+
+  /**
+   * Callback when unsubscribed
+   */
+  onUnsubscribed?: () => void;
+}
+
+interface UseDjangoPushReturn {
+  // State (from usePushNotifications)
+  isSupported: boolean;
+  permission: NotificationPermission;
+  isSubscribed: boolean;
+  subscription: PushSubscription | null;
+
+  // Local state
+  isLoading: boolean;
+  error: Error | null;
+
+  // Actions
+  subscribe: () => Promise<boolean>;
+  unsubscribe: () => Promise<boolean>;
+  sendTestPush: (message: { title: string; body: string; url?: string }) => Promise<boolean>;
+}
+
+/**
+ * Hook for Django-CFG push notifications integration
+ */
+export function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushReturn {
+  const { onSubscribed, onSubscribeError, onUnsubscribed, ...pushOptions } = options;
+
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // 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> => {
+    // Auth check - require login for push subscriptions
+    if (!isAuthenticated) {
+      openAuthDialog({
+        message: 'Please sign in to enable push notifications',
+      });
+      return false;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      // Step 1: Browser subscription via usePushNotifications
+      const subscription = await pushNotifications.subscribe();
+
+      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');
+
+      // Step 2: Save to Django backend
+      const result = await apiWebPush.web_push.webpushSubscribeCreate({
+        endpoint: subscription.endpoint,
+        keys: {
+          p256dh: arrayBufferToBase64(subscription.getKey('p256dh')),
+          auth: arrayBufferToBase64(subscription.getKey('auth')),
+        },
+      });
+
+      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);
+    }
+  }, [isAuthenticated, openAuthDialog, pushNotifications.subscribe, onSubscribed, onSubscribeError]);
+
+  /**
+   * Unsubscribe from push notifications
+   */
+  const unsubscribe = useCallback(async (): Promise<boolean> => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      // Unsubscribe via usePushNotifications (handles browser API)
+      const success = await pushNotifications.unsubscribe();
+
+      if (!success) {
+        return false;
+      }
+
+      pwaLogger.info('[useDjangoPush] Browser unsubscribed');
+
+      // 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));
+      pwaLogger.error('[useDjangoPush] Unsubscribe failed:', error);
+      setError(error);
+      return false;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [pushNotifications.unsubscribe, onUnsubscribed]);
+
+  /**
+   * Send test push notification
+   */
+  const sendTestPush = useCallback(
+    async (message: { title: string; body: string; url?: string }): Promise<boolean> => {
+      if (!pushNotifications.isSubscribed) {
+        const err = new Error('Not subscribed');
+        setError(err);
+        return false;
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const result = await apiWebPush.web_push.webpushSendCreate({
+          title: message.title,
+          body: message.body,
+          url: message.url || '/',
+          icon: '/icon.png',
+        });
+
+        pwaLogger.info('[useDjangoPush] Test push sent:', result);
+        return result.success;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        pwaLogger.error('[useDjangoPush] Send test push failed:', error);
+        setError(error);
+        return false;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [pushNotifications.isSubscribed]
+  );
+
+  return {
+    // State from usePushNotifications
+    isSupported: pushNotifications.isSupported,
+    permission: pushNotifications.permission,
+    isSubscribed: pushNotifications.isSubscribed,
+    subscription: pushNotifications.subscription,
+
+    // Local state
+    isLoading,
+    error,
+
+    // Actions
+    subscribe,
+    unsubscribe,
+    sendTestPush,
+  };
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Convert ArrayBuffer to base64 string
+ */
+function arrayBufferToBase64(buffer: ArrayBuffer | null): string {
+  if (!buffer) return '';
+
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return window.btoa(binary);
+}