@djangocfg/layouts 2.1.37 → 2.1.39

package/src/snippets/PushNotifications/@docs/guides/vapid-setup.md

@@ -0,0 +1,352 @@
+# VAPID Setup Guide
+
+Complete guide to generating and configuring VAPID keys for Web Push Notifications.
+
+## What is VAPID?
+
+**VAPID** (Voluntary Application Server Identification) is a standard that authenticates your web push notifications.
+
+### Why VAPID?
+
+Without VAPID, push services can't verify that push notifications actually come from your server. VAPID provides:
+
+- **Authentication** - Proves notifications come from you
+- **Security** - Prevents notification spoofing
+- **Privacy** - Required by modern push services
+
+## Key Pairs
+
+VAPID uses a **public/private key pair**:
+
+| Key | Location | Purpose |
+|-----|----------|---------|
+| **Public** | Frontend + Backend | Identify your app to push service |
+| **Private** | Backend ONLY | Sign push notifications |
+
+⚠️ **CRITICAL**: Never expose private key in frontend code!
+
+## Step 1: Generate VAPID Keys
+
+### Option A: Using web-push (Recommended)
+
+```bash
+# Install web-push globally
+npm install -g web-push
+
+# Generate keys
+web-push generate-vapid-keys
+```
+
+**Output:**
+```
+=======================================
+
+Public Key:
+BM8xTpJKZ1234567890abcdefghijklmnopqrstuvwxyz...
+
+Private Key:
+abc123def456ghi789jkl012mno345pqr678stu901vwx...
+
+=======================================
+```
+
+### Option B: Using npx (No install)
+
+```bash
+npx web-push generate-vapid-keys
+```
+
+### Option C: Programmatically
+
+```javascript
+// generate-vapid.js
+const webpush = require('web-push');
+
+const vapidKeys = webpush.generateVAPIDKeys();
+
+console.log('Public Key:', vapidKeys.publicKey);
+console.log('Private Key:', vapidKeys.privateKey);
+```
+
+```bash
+node generate-vapid.js
+```
+
+## Step 2: Store Keys Securely
+
+### Frontend Environment Variables
+
+Create/update `.env.local` (frontend):
+
+```bash
+# .env.local (frontend - Next.js app)
+NEXT_PUBLIC_VAPID_PUBLIC_KEY=BM8xTpJKZ1234567890abcdefghijklmnopqrstuvwxyz...
+```
+
+**Notes:**
+- ✅ `NEXT_PUBLIC_` prefix makes it available in browser
+- ✅ Public key is safe to expose
+- ✅ Commit `.env.example` with placeholder
+- ❌ Never commit `.env.local` with real keys
+
+### Backend Environment Variables
+
+Create/update `.env` (backend - Django):
+
+```bash
+# .env (backend - Django)
+VAPID_PUBLIC_KEY=BM8xTpJKZ1234567890abcdefghijklmnopqrstuvwxyz...
+VAPID_PRIVATE_KEY=abc123def456ghi789jkl012mno345pqr678stu901vwx...
+VAPID_MAILTO=mailto:your-email@example.com
+```
+
+**Notes:**
+- ⚠️ **CRITICAL**: Private key NEVER in frontend
+- ⚠️ Never commit `.env` to git
+- ✅ Use secure environment (production secrets manager)
+- ✅ `VAPID_MAILTO` should be valid email with `mailto:` prefix
+
+### Example .env.example
+
+Create `.env.example` (safe to commit):
+
+```bash
+# Frontend (.env.example)
+NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_public_key_here
+
+# Backend (.env.example)
+VAPID_PUBLIC_KEY=your_public_key_here
+VAPID_PRIVATE_KEY=your_private_key_here
+VAPID_MAILTO=mailto:your-email@example.com
+```
+
+## Step 3: Configure Frontend
+
+### Using PushNotifications Snippet
+
+```tsx
+// app/layout.tsx
+import { DjangoPushProvider } from '@/snippets/PushNotifications';
+
+const VAPID_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!;
+
+export default function Layout({ children }) {
+  return (
+    <DjangoPushProvider vapidPublicKey={VAPID_KEY}>
+      {children}
+    </DjangoPushProvider>
+  );
+}
+```
+
+### Manual Configuration
+
+```tsx
+import { usePushNotifications } from '@/snippets/PushNotifications';
+
+function Component() {
+  const { subscribe } = usePushNotifications({
+    vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
+    subscribeEndpoint: '/api/push/subscribe',
+  });
+
+  return <button onClick={subscribe}>Subscribe</button>;
+}
+```
+
+## Step 4: Configure Backend (Django)
+
+### Install Dependencies
+
+```bash
+pip install pywebpush
+```
+
+### Django Settings
+
+```python
+# settings.py
+import os
+
+# VAPID Configuration
+VAPID_PUBLIC_KEY = os.getenv('VAPID_PUBLIC_KEY')
+VAPID_PRIVATE_KEY = os.getenv('VAPID_PRIVATE_KEY')
+VAPID_MAILTO = os.getenv('VAPID_MAILTO', 'mailto:admin@example.com')
+
+# Validate VAPID keys
+if not VAPID_PUBLIC_KEY or not VAPID_PRIVATE_KEY:
+    raise ValueError("VAPID keys not configured. Run: web-push generate-vapid-keys")
+```
+
+### Django View (Subscribe Endpoint)
+
+```python
+# views.py
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.conf import settings
+import json
+
+@csrf_exempt
+def push_subscribe(request):
+    if request.method == 'POST':
+        subscription_info = json.loads(request.body)
+
+        # Store subscription in database
+        # (Your model here)
+
+        return JsonResponse({
+            'success': True,
+            'publicKey': settings.VAPID_PUBLIC_KEY
+        })
+
+    return JsonResponse({'error': 'Method not allowed'}, status=405)
+```
+
+### Send Push Notification
+
+```python
+# utils/push.py
+from pywebpush import webpush, WebPushException
+from django.conf import settings
+import json
+
+def send_push_notification(subscription_info, notification_data):
+    """
+    Send push notification to a subscriber
+
+    Args:
+        subscription_info: PushSubscription object from frontend
+        notification_data: dict with 'title', 'body', 'icon', etc.
+    """
+    try:
+        webpush(
+            subscription_info=subscription_info,
+            data=json.dumps(notification_data),
+            vapid_private_key=settings.VAPID_PRIVATE_KEY,
+            vapid_claims={
+                "sub": settings.VAPID_MAILTO
+            }
+        )
+        return True
+    except WebPushException as e:
+        print(f"Push failed: {e}")
+        return False
+```
+
+## Step 5: Verify Configuration
+
+### Frontend Verification
+
+```tsx
+// Check if VAPID key is loaded
+console.log('VAPID Key:', process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY?.slice(0, 10) + '...');
+```
+
+Expected output:
+```
+VAPID Key: BM8xTpJKZ1...
+```
+
+### Backend Verification
+
+```python
+# Django shell
+python manage.py shell
+
+>>> from django.conf import settings
+>>> print(f"Public: {settings.VAPID_PUBLIC_KEY[:10]}...")
+>>> print(f"Private: {settings.VAPID_PRIVATE_KEY[:10]}...")
+>>> print(f"Mailto: {settings.VAPID_MAILTO}")
+```
+
+Expected output:
+```
+Public: BM8xTpJKZ1...
+Private: abc123def4...
+Mailto: mailto:you@example.com
+```
+
+## Security Checklist
+
+- [ ] ✅ Public key in `NEXT_PUBLIC_` env var (frontend)
+- [ ] ✅ Private key in backend-only env var (no `NEXT_PUBLIC_`)
+- [ ] ✅ `.env.local` and `.env` in `.gitignore`
+- [ ] ✅ `.env.example` committed with placeholders
+- [ ] ⚠️ Private key NEVER in frontend code
+- [ ] ⚠️ Private key NEVER in git
+- [ ] ⚠️ Production keys in secure secrets manager
+- [ ] ✅ VAPID_MAILTO is valid email with `mailto:` prefix
+
+## Troubleshooting
+
+### Error: "VAPID key must be base64 URL-safe"
+
+**Problem**: Invalid key format
+
+**Solution**: Regenerate keys with `web-push generate-vapid-keys`
+
+### Error: "Public key not found"
+
+**Problem**: Environment variable not loaded
+
+**Solution**:
+1. Check `.env.local` exists in frontend root
+2. Restart dev server (`npm run dev`)
+3. Verify: `console.log(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY)`
+
+### Error: "Push notification failed"
+
+**Problem**: Private key or mailto incorrect
+
+**Solution**:
+1. Check backend `.env` has `VAPID_PRIVATE_KEY` and `VAPID_MAILTO`
+2. Verify mailto format: `mailto:email@example.com`
+3. Restart Django server
+
+## Production Deployment
+
+### Vercel (Frontend)
+
+```bash
+# Add environment variable in Vercel dashboard
+vercel env add NEXT_PUBLIC_VAPID_PUBLIC_KEY production
+```
+
+Or via CLI:
+```bash
+vercel env add NEXT_PUBLIC_VAPID_PUBLIC_KEY
+# Paste key when prompted
+```
+
+### Heroku (Backend)
+
+```bash
+heroku config:set VAPID_PUBLIC_KEY="BM8xT..."
+heroku config:set VAPID_PRIVATE_KEY="abc123..."
+heroku config:set VAPID_MAILTO="mailto:you@example.com"
+```
+
+### Docker
+
+```yaml
+# docker-compose.yml
+services:
+  backend:
+    environment:
+      - VAPID_PUBLIC_KEY=${VAPID_PUBLIC_KEY}
+      - VAPID_PRIVATE_KEY=${VAPID_PRIVATE_KEY}
+      - VAPID_MAILTO=${VAPID_MAILTO}
+```
+
+## Next Steps
+
+- [Django Integration Guide](./django-integration.md) - Connect backend
+- [Service Worker Setup](./service-worker.md) - Configure SW
+- [Main README](../../README.md) - API reference
+
+## References
+
+- [Web Push Protocol](https://datatracker.ietf.org/doc/html/rfc8030)
+- [VAPID Specification](https://datatracker.ietf.org/doc/html/rfc8292)
+- [web-push Library](https://github.com/web-push-libs/web-push)

package/src/snippets/PushNotifications/README.md

@@ -0,0 +1,328 @@
+# Push Notifications
+
+Web Push Notifications snippet for web applications.
+
+## Responsibility
+
+**Web Push Notifications management**
+
+- Push subscription/unsubscription
+- Permission management
+- VAPID key handling
+- Django-CFG backend integration
+- Push message accumulation and display
+
+## Quick Start
+
+### Basic Usage
+
+```tsx
+// app/layout.tsx
+import { PushProvider, usePush, PushPrompt } from '@/snippets/PushNotifications';
+
+const VAPID_KEY = process.env.NEXT_PUBLIC_VAPID_KEY;
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <PushProvider vapidPublicKey={VAPID_KEY}>
+          {children}
+          <PushPrompt requirePWA={true} />
+        </PushProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Django Integration
+
+```tsx
+// app/layout.tsx
+import { DjangoPushProvider } from '@/snippets/PushNotifications';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <DjangoPushProvider
+          vapidPublicKey={process.env.NEXT_PUBLIC_VAPID_KEY}
+          autoSubscribe={false}
+        >
+          {children}
+        </DjangoPushProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## API
+
+### `<PushProvider>`
+
+Generic push notifications provider:
+
+```tsx
+<PushProvider
+  vapidPublicKey={VAPID_KEY}
+  subscribeEndpoint="/api/push/subscribe"  // Optional
+  sendEndpoint="/api/push/send"            // Optional
+  onPushReceived={(push) => console.log(push)}
+>
+  {children}
+</PushProvider>
+```
+
+### `<DjangoPushProvider>`
+
+Django-CFG specific provider:
+
+```tsx
+<DjangoPushProvider
+  vapidPublicKey={VAPID_KEY}
+  autoSubscribe={false}
+  onSubscribed={(subscription) => console.log('Subscribed!', subscription)}
+  onSubscribeError={(error) => console.error('Error:', error)}
+  onUnsubscribed={() => console.log('Unsubscribed')}
+>
+  {children}
+</DjangoPushProvider>
+```
+
+### `<PushPrompt />`
+
+Push notification permission prompt:
+
+```tsx
+<PushPrompt
+  vapidPublicKey={VAPID_KEY}
+  requirePWA={true}              // Only show if PWA installed (default: true)
+  delayMs={5000}                 // Delay before showing (default: 5000)
+  resetAfterDays={7}             // Auto-reset after days (default: 7)
+  onEnabled={() => console.log('Enabled!')}
+  onDismissed={() => console.log('Dismissed')}
+/>
+```
+
+**Behavior:**
+- Shows after PWA is installed (if `requirePWA={true}`)
+- Waits for delay before showing
+- Dismissible (saved to localStorage)
+- Auto-resets after configured days
+- Respects user's permission choice
+
+### Hooks
+
+#### `usePush()`
+
+Access push state and actions:
+
+```tsx
+import { usePush } from '@/snippets/PushNotifications';
+
+function NotifyButton() {
+  const {
+    isSupported,
+    permission,
+    isSubscribed,
+    subscription,
+    pushes,
+    subscribe,
+    unsubscribe,
+    sendPush,
+    clearPushes,
+    removePush,
+  } = usePush();
+
+  return (
+    <div>
+      {!isSubscribed && (
+        <button onClick={subscribe}>Enable Notifications</button>
+      )}
+      {pushes.map(push => (
+        <div key={push.id}>{push.title}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+#### `useDjangoPushContext()`
+
+Django-specific push context:
+
+```tsx
+import { useDjangoPushContext } from '@/snippets/PushNotifications';
+
+function NotifyButton() {
+  const {
+    isSupported,
+    permission,
+    isSubscribed,
+    subscription,
+    isLoading,
+    error,
+    subscribe,
+    unsubscribe,
+    sendTestPush,
+  } = useDjangoPushContext();
+
+  const handleTest = async () => {
+    await sendTestPush({
+      title: 'Test',
+      body: 'This is a test notification',
+      url: '/dashboard',
+    });
+  };
+
+  return (
+    <div>
+      {!isSubscribed && (
+        <button onClick={subscribe} disabled={isLoading}>
+          Enable Notifications
+        </button>
+      )}
+      {isSubscribed && (
+        <button onClick={handleTest}>Send Test</button>
+      )}
+    </div>
+  );
+}
+```
+
+#### `usePushNotifications()`
+
+Low-level push hook (used internally):
+
+```tsx
+import { usePushNotifications } from '@/snippets/PushNotifications';
+
+function Component() {
+  const {
+    isSupported,
+    permission,
+    isSubscribed,
+    subscription,
+    subscribe,
+    unsubscribe,
+  } = usePushNotifications({
+    vapidPublicKey: VAPID_KEY,
+    subscribeEndpoint: '/api/push/subscribe',
+  });
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+## Usage with PWA Install
+
+Use together with the PWAInstall snippet:
+
+```tsx
+import { PwaProvider, A2HSHint } from '@/snippets/PWAInstall';
+import { DjangoPushProvider, PushPrompt } from '@/snippets/PushNotifications';
+
+export default function Layout({ children }) {
+  return (
+    <PwaProvider>
+      <DjangoPushProvider vapidPublicKey={VAPID_KEY}>
+        {children}
+
+        {/* PWA Install hint */}
+        <A2HSHint resetAfterDays={3} />
+
+        {/* Push notification prompt (shown after PWA install) */}
+        <PushPrompt
+          requirePWA={true}
+          delayMs={5000}
+          resetAfterDays={7}
+        />
+      </DjangoPushProvider>
+    </PwaProvider>
+  );
+}
+```
+
+## Browser Support
+
+| Platform | Browser | Support |
+|----------|---------|---------|
+| iOS | Safari 16.4+ | ✅ Push supported |
+| iOS | Chrome/Firefox | ❌ No push support |
+| Android | Chrome | ✅ Full support |
+| Android | Firefox | ✅ Full support |
+| Desktop | Chrome/Edge/Firefox | ✅ Full support |
+
+## Architecture
+
+```
+PushNotifications/
+├── context/
+│   ├── PushContext.tsx         # Generic push state
+│   └── DjangoPushContext.tsx   # Django integration
+├── components/
+│   └── PushPrompt.tsx          # Permission prompt
+├── hooks/
+│   ├── usePushNotifications.ts # Core push logic
+│   └── useDjangoPush.ts        # Django push logic
+├── utils/
+│   ├── vapid.ts               # VAPID key utils
+│   ├── localStorage.ts        # Persistence
+│   └── logger.ts              # Logging
+└── types/
+    └── push.ts
+```
+
+## Separation from PWA Install
+
+This snippet is **completely independent** from PWA installation:
+
+- **PWAInstall** → Handles device installation
+- **PushNotifications** → Handles web push subscriptions
+
+Both can be used together or separately.
+
+## VAPID Keys
+
+Generate VAPID keys using:
+
+```bash
+npx web-push generate-vapid-keys
+```
+
+Store public key in environment:
+```env
+NEXT_PUBLIC_VAPID_KEY=BM8xT...
+```
+
+## Service Worker
+
+Ensure your service worker handles push events:
+
+```js
+// public/sw.js
+self.addEventListener('push', (event) => {
+  const data = event.data.json();
+
+  event.waitUntil(
+    self.registration.showNotification(data.title, {
+      body: data.body,
+      icon: data.icon || '/icon-192.png',
+      badge: data.badge || '/badge-72.png',
+      data: data.data,
+    })
+  );
+});
+
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close();
+
+  if (event.notification.data?.url) {
+    event.waitUntil(
+      clients.openWindow(event.notification.data.url)
+    );
+  }
+});
+```

package/src/snippets/{PWA → PushNotifications}/config.ts

@@ -1,7 +1,7 @@
 /**
- * PWA Configuration
+ * Push Notifications Configuration
  *
- * Centralized constants for PWA functionality.
+ * Centralized constants for push notifications functionality.
  *
  * SECURITY NOTE:
  * - VAPID_PRIVATE_KEY should NEVER be in frontend code