# Push Notifications Setup Guide

## Overview
This feature enables real-time push notifications for build likes, comments, and new followers using the Web Push API and Service Workers.

## Files Created

### API Routes
1. **`app/api/notifications/subscribe/route.ts`** - Subscribe to push notifications
2. **`app/api/notifications/unsubscribe/route.ts`** - Unsubscribe from push notifications
3. **`app/api/notifications/send/route.ts`** - Send push notifications to subscribed users

### Service Worker
- **`public/sw.js`** - Handles receiving and displaying push notifications

### Database
- **`create-push-subscriptions-table.sql`** - Stores push subscriptions

### Updated Files
- **`app/settings/page.tsx`** - UI for managing push notification preferences

## Setup Instructions

### Step 1: Install Dependencies
Install the web-push package:
```bash
npm install web-push
npm install -D @types/web-push
```

### Step 2: Generate VAPID Keys
Run this command to generate public and private VAPID keys:
```bash
npx web-push generate-vapid-keys
```

This will output something like:
```
Public Key: BH_yL...
Private Key: xyz...
```

### Step 3: Configure Environment Variables
Add to your `.env.local`:
```
NEXT_PUBLIC_VAPID_PUBLIC_KEY=<your-public-key>
VAPID_PRIVATE_KEY=<your-private-key>
VAPID_SUBJECT=mailto:noreply@buildmate.com
```

### Step 4: Create Database Table
Run the SQL file in your Supabase SQL Editor:
```sql
-- Copy contents of create-push-subscriptions-table.sql
-- Paste and run in Supabase SQL Editor
```

The table stores:
- `id` - Primary key
- `user_id` - Reference to user
- `endpoint` - Push service endpoint
- `auth_key` - Authentication key for messages
- `p256dh_key` - Encryption key for messages
- `created_at` - Subscription creation timestamp

### Step 5: Test Push Notifications
1. Go to Settings page
2. In Notification Preferences, you should see "Enable Notifications" buttons for build likes, comments, and followers
3. Click to enable push notifications
4. Browser will request permission to send notifications
5. Once enabled, you're subscribed to push notifications

## Sending Push Notifications

To send push notifications from your backend, call the send endpoint:

```typescript
// Example: Send notification when someone likes a build
await fetch("/api/notifications/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userId: 123, // User who receives the notification
    notificationType: "buildLike", // Type of notification
    title: "New Build Like",
    body: "John liked your PC Build",
    url: "/builds/456", // URL to navigate to when clicked
    icon: "/buildmate-icon.png",
    badge: "/buildmate-badge.png"
  })
});
```

### Notification Types
- `buildLike` - When someone likes a build
- `comment` - When someone comments on a build
- `follower` - When someone follows a user

## Features

- **Real-time Notifications** - Instant push notifications to subscribed users
- **Service Worker Handling** - Background notification delivery
- **Automatic Cleanup** - Invalid subscriptions are automatically removed
- **User Control** - Users can enable/disable notifications in settings
- **Preference Tracking** - Notification preferences are saved in database

## How It Works

1. User enables push notifications in settings
2. Service worker is registered on first page load
3. Browser requests user permission for notifications
4. Push subscription is sent to backend and stored in database
5. When an event occurs (like, comment, follow), notification is sent to all subscribed users
6. Service worker receives and displays the notification to user

## Browser Support

Push notifications are supported in:
- Chrome/Chromium (all versions)
- Edge (all versions)
- Firefox (44+)
- Safari (16+)
- Not supported in private/incognito mode

## Troubleshooting

**Notifications not being sent?**
- Verify VAPID keys are correctly set
- Check that service worker is registered (F12 → Application → Service Workers)
- Ensure user has granted notification permission

**Service worker not registering?**
- Check browser console for errors
- Verify `/public/sw.js` exists
- Clear browser cache and try again

**Getting permission denied?**
- Check browser notification settings
- User may have blocked notifications for the domain
- Try in a new incognito window

## Security Notes

- VAPID keys should never be exposed in frontend (private key is backend-only)
- Push subscriptions are validated on the server before sending
- Invalid subscriptions are automatically cleaned up
- Database has proper indexes for efficient lookup