Notification System

The notification service provides intelligent notification management with automatic email sending based on notification criticality and user preferences.
Perfect for: User notifications, system alerts, authentication flows, and subscription communications with smart email delivery.

Core Service Functions

The notification service is located in src/services/notification-service.ts and provides several key functions:

Main Notification Creation

// From src/services/notification-service.ts
export const createTypedNotificationService = async <
  T extends NotificationType,
>(
  notificationParams: CreateTypedNotification<T>
)
This is the main function for creating notifications with automatic email handling.

Available Service Functions

// Typed notification with automatic email handling
createTypedNotificationService(notificationParams)

// Basic notification creation
createNotificationService(notificationParams, options)

Critical vs Non-Critical Notifications

The system automatically classifies notifications into two categories:

🚨 Critical Notifications (Always Send Email)

Critical notifications bypass user preferences and always send emails: 
// From src/services/notification-service.ts
const criticalTypes: NotificationType[] = [
  'reset_password',
  'email_verification',
  'change_email_verification',
  'magic_link',
  'otp_code',
  'security_alert',
  'password_changed',
  'organization_invitation',
  'subscription_created',
  'subscription_updated',
  'subscription_canceled',
  'subscription_deleted',
]
Why critical: These notifications are essential for security, authentication, or billing and must reach the user regardless of their notification preferences.

📢 Non-Critical Notifications (Respect User Preferences)

All other notification types respect the user's email notification settings:
  • User must have enableEmailNotifications: true
  • Notification channel must be 'email' or 'both'
  • User can opt out of these notifications

Notification Types

The system supports 25+ notification types covering different areas:
Critical authentication notifications:
  • reset_password - Password reset requests
  • email_verification - Email address verification
  • change_email_verification - Email change confirmation
  • magic_link - Passwordless authentication
  • otp_code - Two-factor authentication codes
  • password_changed - Password change confirmation
  • security_alert - Security-related alerts

Smart Email Integration

The notification service automatically determines when to send emails:

Automatic Email Decision Logic

// From src/services/notification-service.ts
// Determine automatically if email is critical
const forceEmail = isCriticalNotification(notificationParams.type)

// Create notification with forced email option
return await createNotificationService(finalNotificationParams, {
  forceEmail,
})

User Preference Integration

For non-critical notifications, the system checks user settings: 
// From src/services/notification-service.ts
const shouldSendEmail =
  options.forceEmail ||
  (userSettings?.enableEmailNotifications &&
    (userSettings?.notificationChannel === 'email' ||
     userSettings?.notificationChannel === 'both'))

Multi-Language Support

The service automatically loads translations based on user language preferences: 
// From src/services/notification-service.ts
const userSettings = await getUserSettingsByUserIdDao(notificationParams.userId)
const userLanguage = userSettings?.language || 'fr'

const translations = await getTranslations({
  locale: userLanguage,
  namespace: `services.domain.notification.${notificationParams.type}`,
})

Authentication Integration

Better Auth seamlessly integrates with the notification service, creating typed notifications instead of sending emails directly. This ensures all authentication emails go through the centralized notification system.

Authentication Hooks Configuration

Better Auth is configured in src/lib/better-auth/auth.ts with hooks that create notifications: 
// From src/lib/better-auth/auth.ts
emailAndPassword: {
  enabled: true,
  requireEmailVerification: AuthAppConfig.requireEmailVerification,
  sendResetPassword: async ({ user, url }) => {
    await createTypedNotificationService({
      userId: user.id,
      type: NotificationTypeConst.reset_password,
      metadata: { url },
    })
  },
},

emailVerification: {
  sendVerificationEmail: async ({ user, url }) => {
    await createTypedNotificationService({
      userId: user.id,
      type: NotificationTypeConst.email_verification,
      metadata: { url },
    })
  },
  sendOnSignUp: true,
  autoSignInAfterVerification: true,
  expiresIn: 3600, // 1 hour
},

user: {
  changeEmail: {
    enabled: AuthAppConfig.changeEmail,
    sendChangeEmailVerification: async ({ user, newEmail, url }) => {
      await createTypedNotificationService({
        userId: user.id,
        type: NotificationTypeConst.change_email_verification,
        metadata: {
          url,
          newEmail, // New email address included in metadata
        },
      })
    },
  },
}

Authentication Notification Types

Better Auth creates these critical notification types automatically:
  • reset_password - Password reset requests
  • email_verification - Email address verification
  • change_email_verification - Email change confirmation
  • magic_link - Passwordless authentication
  • otp_code - Two-factor authentication codes
Centralized approach: All authentication emails go through the notification service, ensuring consistent handling, user preferences respect, and centralized logging.

Usage Examples

Creating a Basic Notification

// Use the typed notification service for automatic handling
await createTypedNotificationService({
  userId: user.id,
  type: NotificationTypeConst.payment_succeeded,
  metadata: {
    amount: '$29.99',
    planName: 'Pro Plan'
  }
})

Creating a Critical Notification

// Security alert (critical - always sends email)
await createTypedNotificationService({
  userId: user.id,
  type: NotificationTypeConst.security_alert,
  title: 'Suspicious login detected',
  message: 'We detected a login from a new device',
  metadata: {
    ipAddress: '192.168.1.1',
    location: 'Paris, France'
  }
})

Creating with Custom Title/Message

// Override automatic translations
await createTypedNotificationService({
  userId: user.id,
  type: NotificationTypeConst.payment_succeeded,
  title: 'Custom payment confirmation',
  message: 'Your payment has been processed successfully',
})

Specific Email Integrations

The service handles specific email integrations for different notification types:

Authentication Email Handling

// Password reset emails
if (parsed.data.type === 'reset_password' && parsed.data.metadata?.url) {
  await sendResetPasswordLinkEmailService({
    email: targetUser.email,
    url: parsed.data.metadata.url as string,
  })
}

// Email verification
if (parsed.data.type === 'email_verification' && parsed.data.metadata?.url) {
  await sendVerificationEmailService({
    email: targetUser.email,
    url: parsed.data.metadata.url,
  })
}

Subscription Integration

// Subscription emails use rich subscription data
if (parsed.data.type === 'subscription_created' && parsed.data.metadata?.subscription) {
  await sendSubscriptionCompletedEmailService(
    parsed.data.metadata.subscription
  )
}

Error Handling

The service includes graceful error handling for email failures: 
// From src/services/notification-service.ts
try {
  // Email sending logic...
} catch (emailError) {
  // Don't fail notification creation if email fails
  console.error("Erreur lors de l'envoi de l'email de notification:", emailError)
}
Graceful degradation: Notifications are still created even if email sending fails, ensuring the system remains functional.

User Interface

In-App Notifications Display

The application includes a built-in notification center that displays all user notifications with proper categorization and read/unread states. In-App Notifications Interface Features:
  • Real-time updates - Notifications appear instantly
  • Categorized display - Grouped by type and importance
  • Read/unread status - Clear visual indicators
  • Action buttons - Direct actions from notifications
  • Responsive design - Works on all device sizes
Notification Components:
  • Bell icon indicator - Shows unread count
  • Dropdown panel - Expandable notification list
  • Notification cards - Individual notification display
  • Timestamp display - Relative time formatting
  • Action buttons - Context-specific actions
Smart notifications ready! Your application has intelligent notification management with automatic email integration and user preference respect.
    Notification System | ShipSaaS Documentation | ShipSaaS - Launch your SaaS with AI in days