# Web Push Notifications Implementation Guide

## Overview

This guide explains how to implement Web Push notifications in your PWA using VAPID (self-hosted, no external service needed).

## Architecture

1. **VAPID Keys**: Generate once, store securely (like JWT secrets)
2. **Client**: Request permission, subscribe to push notifications
3. **Database**: Store push subscriptions per user
4. **Server**: Send notifications when list events occur
5. **Service Worker**: Receive and display notifications

## Setup Steps

### 1. Generate VAPID Keys

Run this once to generate your VAPID keys:

```bash
npx web-push generate-vapid-keys
```

Add to `.env`:
```
VAPID_PUBLIC_KEY=your_public_key_here
VAPID_PRIVATE_KEY=your_private_key_here
VAPID_SUBJECT=mailto:your-email@example.com
```

### 2. Install Dependencies

```bash
npm install web-push
```

### 3. Database Schema

Add `PushSubscription` model to store user subscriptions (see prisma/schema.prisma changes).

### 4. Client-Side Flow

1. User grants notification permission
2. Service worker subscribes to push manager
3. Subscription sent to server and stored in database
4. Server sends notifications when events occur
5. Service worker displays notifications

### 5. Notification Triggers

Notifications are sent when:
- Someone adds/removes an item from a shared list
- Someone invites you to a list
- Someone accepts your list invitation
- Someone removes you from a list

## Testing

### Local Testing
- Use Chrome DevTools > Application > Service Workers
- Use Chrome DevTools > Application > Push Messaging to simulate

### iOS Testing
- Must be installed to home screen
- iOS 16.4+ required
- Test on actual device (simulator doesn't support push)

### Android Testing
- Works in browser and installed PWA
- Test on actual device for best results

## Privacy & Best Practices

- Always request permission explicitly (don't auto-prompt)
- Allow users to disable notifications
- Store subscriptions securely
- Handle subscription expiration/updates
- Respect user preferences per list

## Troubleshooting

### Notifications not appearing
- Check permission status
- Verify service worker is active
- Check browser console for errors
- Ensure VAPID keys are correct

### iOS specific issues
- Must be installed to home screen
- Check iOS version (16.4+)
- Verify manifest.json is correct

### Subscription fails
- Check VAPID public key matches server
- Verify service worker scope
- Check network requests in DevTools