thrilltrack-explorer/docs/NOVU_SETUP.md

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:

# 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

import { notificationService } from '@/lib/notificationService';

await notificationService.createSubscriber({
  subscriberId: 'user-id',
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
});

Test Notification Trigger

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:

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:

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]