cat-sitting-planner/implementation_plan_pwa_push.md

Implementation Plan - PWA Push Notifications

This plan outlines the steps to implement Push Notifications for the Cat Sitting Planner PWA.

Goals

• Allow users to subscribe to Push Notifications from the browser.
• Send Push Notifications for existing events (New Booking, Cancellation, Completion, Instructions Update).
• Ensure integration with the Service Worker.

User Actions Required

• Generate VAPID Keys: Run npx web-push generate-vapid-keys in your terminal. Add the output to your .env (create if needed) or .env.local:

  NEXT_PUBLIC_VAPID_PUBLIC_KEY="<your_public_key>"
  VAPID_PRIVATE_KEY="<your_private_key>"
  VAPID_SUBJECT="mailto:your-email@example.com"
  

  Note: NEXT_PUBLIC_ prefix is needed for the frontend to access the public key.

Steps

1. Dependencies and Configuration

• Install web-push: npm install web-push && npm install -D @types/web-push
• Install serwist or ensure next-pwa can handle custom service workers. (We will use importScripts with next-pwa).

2. Database Schema

• Update prisma/schema.prisma: Add PushSubscription model linked to Plan.

  model PushSubscription {
    id        String   @id @default(cuid())
    planId    String
    plan      Plan     @relation(fields: [planId], references: [id], onDelete: Cascade)
    endpoint  String   @unique
    p256dh    String
    auth      String
    createdAt DateTime @default(now())
  }
  

• Run npx prisma migrate dev --name add_push_subscription

3. Service Worker

• Create public/push-sw.js: Implement the push event listener to show notifications. Implement the notificationclick event listener to focus/open the app.
• Update next.config.mjs: Configure next-pwa (Workbox) to import push-sw.js via importScripts.

4. Server Actions & Library

• Create lib/push.ts: Helper functions to initialize web-push and send notifications.
• Create app/actions/subscription.ts: subscribeUser(planId, subscription): Saves subscription to DB. unsubscribeUser(endpoint): Removes subscription.
• Update lib/notifications.ts: Add sendPlanNotification(planId, message, webhookUrl?). This function will:
  1. Send to Webhook (if exists).
  2. Fetch all subscriptions for planId.
  3. Send Web Push to all.
  4. Handle 410 (Gone) by deleting sub.

5. Backend Integration

• Update app/actions/booking.ts: Replace sendNotification with sendPlanNotification.
• Update app/actions/plan.ts: Replace sendNotification with sendPlanNotification.

6. Frontend Integration

• Create components/push-notification-manager.tsx: UI component to check permission, register SW (if not handled), and subscribe. Show "Enable Notifications" button.
• Add PushNotificationManager to Dashboard or Settings.

Verification

• Test on Localhost (requires HTTPS or localhost exception).
• Verify notifications appear for:
  • Booking creation
  • Booking completion
  • Cancellation
  • Instructions update