mirror of
https://github.com/pacnpal/thrilltrack-explorer.git
synced 2025-12-23 07:31:12 -05:00
Refactor notification system
This commit is contained in:
gpt-engineer-app[bot]
238
docs/NOVU_SETUP.md
Normal file
238
docs/NOVU_SETUP.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# Novu Cloud Integration Setup Guide
|
||||
|
||||
This guide will help you set up and configure Novu Cloud for the ThrillWiki notification system.
|
||||
|
||||
## Overview
|
||||
|
||||
The notification system uses Novu Cloud for managing multi-channel notifications including:
|
||||
- In-app notifications
|
||||
- Email notifications
|
||||
- Push notifications
|
||||
- SMS notifications (planned)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. A Novu Cloud account (sign up at https://novu.co)
|
||||
2. Access to the Supabase project
|
||||
3. Environment variable configuration access
|
||||
|
||||
## Step 1: Create a Novu Cloud Account
|
||||
|
||||
1. Go to https://novu.co and sign up
|
||||
2. Create a new application in the Novu dashboard
|
||||
3. Note down your **Application Identifier** from the Settings page
|
||||
|
||||
## Step 2: Configure Environment Variables
|
||||
|
||||
Add the following environment variables to your `.env` file:
|
||||
|
||||
```bash
|
||||
# Novu Configuration
|
||||
VITE_NOVU_APPLICATION_IDENTIFIER="your-app-identifier"
|
||||
VITE_NOVU_SOCKET_URL="wss://ws.novu.co"
|
||||
VITE_NOVU_API_URL="https://api.novu.co"
|
||||
```
|
||||
|
||||
## Step 3: Add Novu API Key to Supabase Secrets
|
||||
|
||||
The Novu API key needs to be stored as a Supabase secret (already done via the setup):
|
||||
|
||||
1. Go to your Novu dashboard
|
||||
2. Navigate to Settings > API Keys
|
||||
3. Copy your API Key
|
||||
4. The secret `NOVU_API_KEY` should already be configured in Supabase
|
||||
|
||||
## Step 4: Create Novu Workflows
|
||||
|
||||
Create the following workflows in your Novu dashboard to match the templates in the database:
|
||||
|
||||
### 1. Review Reply (`review-reply`)
|
||||
**Trigger Identifier:** `review-reply`
|
||||
**Channels:** Email, In-App
|
||||
**Payload Variables:**
|
||||
- `reviewTitle` - Title of the review
|
||||
- `replyAuthor` - Name of the person who replied
|
||||
- `replyContent` - Content of the reply
|
||||
- `reviewUrl` - Link to the review
|
||||
|
||||
### 2. New Follower (`new-follower`)
|
||||
**Trigger Identifier:** `new-follower`
|
||||
**Channels:** Email, In-App, Push
|
||||
**Payload Variables:**
|
||||
- `followerName` - Name of the new follower
|
||||
- `followerProfile` - Link to the follower's profile
|
||||
|
||||
### 3. System Announcement (`system-announcement`)
|
||||
**Trigger Identifier:** `system-announcement`
|
||||
**Channels:** Email, In-App, Push
|
||||
**Payload Variables:**
|
||||
- `title` - Announcement title
|
||||
- `content` - Announcement content
|
||||
- `priority` - Priority level (info, warning, critical)
|
||||
|
||||
### 4. Weekly Digest (`weekly-digest`)
|
||||
**Trigger Identifier:** `weekly-digest`
|
||||
**Channels:** Email
|
||||
**Payload Variables:**
|
||||
- `userName` - User's name
|
||||
- `weekStart` - Start date of the week
|
||||
- `weekEnd` - End date of the week
|
||||
- `stats` - Activity statistics object
|
||||
- `highlights` - Array of highlighted content
|
||||
|
||||
### 5. Monthly Digest (`monthly-digest`)
|
||||
**Trigger Identifier:** `monthly-digest`
|
||||
**Channels:** Email
|
||||
**Payload Variables:**
|
||||
- `userName` - User's name
|
||||
- `month` - Month name
|
||||
- `stats` - Monthly statistics object
|
||||
- `topContent` - Array of popular content
|
||||
|
||||
### 6. Moderation Alert (`moderation-alert`)
|
||||
**Trigger Identifier:** `moderation-alert`
|
||||
**Channels:** Email, In-App
|
||||
**Payload Variables:**
|
||||
- `itemType` - Type of content (review, photo, etc.)
|
||||
- `itemId` - ID of the item
|
||||
- `submitterName` - Name of the submitter
|
||||
- `moderationUrl` - Link to moderation queue
|
||||
|
||||
### 7. Content Approved (`content-approved`)
|
||||
**Trigger Identifier:** `content-approved`
|
||||
**Channels:** Email, In-App
|
||||
**Payload Variables:**
|
||||
- `contentType` - Type of content
|
||||
- `contentTitle` - Title/name of content
|
||||
- `contentUrl` - Link to the approved content
|
||||
|
||||
### 8. Content Rejected (`content-rejected`)
|
||||
**Trigger Identifier:** `content-rejected`
|
||||
**Channels:** Email, In-App
|
||||
**Payload Variables:**
|
||||
- `contentType` - Type of content
|
||||
- `contentTitle` - Title/name of content
|
||||
- `rejectionReason` - Reason for rejection
|
||||
|
||||
## Step 5: Configure Webhook (Optional)
|
||||
|
||||
To track notification delivery status:
|
||||
|
||||
1. Go to Novu Dashboard > Settings > Webhooks
|
||||
2. Add a new webhook endpoint: `https://ydvtmnrszybqnbcqbdcy.supabase.co/functions/v1/novu-webhook`
|
||||
3. Select events: `notification.sent`, `notification.delivered`, `notification.read`, `notification.failed`
|
||||
|
||||
## Step 6: Test the Integration
|
||||
|
||||
Run these tests to ensure everything works:
|
||||
|
||||
### Test Subscriber Creation
|
||||
```typescript
|
||||
import { notificationService } from '@/lib/notificationService';
|
||||
|
||||
await notificationService.createSubscriber({
|
||||
subscriberId: 'user-id',
|
||||
email: 'user@example.com',
|
||||
firstName: 'John',
|
||||
lastName: 'Doe',
|
||||
});
|
||||
```
|
||||
|
||||
### Test Notification Trigger
|
||||
```typescript
|
||||
import { notificationService } from '@/lib/notificationService';
|
||||
|
||||
await notificationService.trigger({
|
||||
workflowId: 'review-reply',
|
||||
subscriberId: 'user-id',
|
||||
payload: {
|
||||
reviewTitle: 'Great ride!',
|
||||
replyAuthor: 'Jane Doe',
|
||||
replyContent: 'Thanks for the review!',
|
||||
reviewUrl: 'https://example.com/review/123',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Database Tables
|
||||
|
||||
1. **notification_templates** - Stores workflow configuration
|
||||
2. **notification_logs** - Tracks sent notifications
|
||||
3. **notification_channels** - Manages available channels
|
||||
4. **user_notification_preferences** - User preferences and Novu subscriber mapping
|
||||
|
||||
### Edge Functions
|
||||
|
||||
1. **create-novu-subscriber** - Creates/updates Novu subscribers
|
||||
2. **update-novu-preferences** - Syncs preferences with Novu
|
||||
3. **trigger-notification** - Triggers notification workflows
|
||||
4. **novu-webhook** - Handles Novu webhook events
|
||||
|
||||
### Frontend Components
|
||||
|
||||
1. **NotificationsTab** - User preferences management
|
||||
2. **NotificationCenter** - In-app notification display
|
||||
3. **notificationService** - Core notification logic
|
||||
|
||||
## Switching to Self-Hosted Novu
|
||||
|
||||
To switch to a self-hosted Novu instance:
|
||||
|
||||
1. Update environment variables:
|
||||
```bash
|
||||
VITE_NOVU_SOCKET_URL="wss://your-novu-instance.com"
|
||||
VITE_NOVU_API_URL="https://your-novu-instance.com/api"
|
||||
```
|
||||
|
||||
2. Update the Novu API key in Supabase secrets to match your self-hosted instance
|
||||
|
||||
3. No code changes required! The system is designed to work with both Cloud and self-hosted versions
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Notifications Not Sending
|
||||
|
||||
1. Check that `VITE_NOVU_APPLICATION_IDENTIFIER` is set
|
||||
2. Verify `NOVU_API_KEY` is configured in Supabase secrets
|
||||
3. Check edge function logs: https://supabase.com/dashboard/project/ydvtmnrszybqnbcqbdcy/functions
|
||||
4. Verify workflow IDs match between database and Novu dashboard
|
||||
|
||||
### User Not Receiving Notifications
|
||||
|
||||
1. Check user's notification preferences in the database
|
||||
2. Verify subscriber was created in Novu
|
||||
3. Check notification logs table for delivery status
|
||||
4. Verify user's email/push permission settings
|
||||
|
||||
### Webhook Not Working
|
||||
|
||||
1. Verify webhook URL is correct in Novu dashboard
|
||||
2. Check that `novu-webhook` edge function has `verify_jwt = false`
|
||||
3. Review edge function logs for errors
|
||||
|
||||
## Monitoring
|
||||
|
||||
Track notification performance:
|
||||
|
||||
1. View delivery rates in `notification_logs` table
|
||||
2. Monitor edge function logs for errors
|
||||
3. Check Novu dashboard analytics
|
||||
4. Query notification statistics:
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
status,
|
||||
COUNT(*) as count,
|
||||
AVG(EXTRACT(EPOCH FROM (delivered_at - created_at))) as avg_delivery_time_seconds
|
||||
FROM notification_logs
|
||||
WHERE created_at > NOW() - INTERVAL '7 days'
|
||||
GROUP BY status;
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
- Novu Documentation: https://docs.novu.co
|
||||
- Novu Discord: https://discord.gg/novu
|
||||
- ThrillWiki Support: [Add support contact]
|
||||
Reference in New Issue
Block a user