Core Package Documentation

The foundation of the Spark Strand notifications system. This package provides a unified API for notification management with automatic provider routing and fallback strategies.

Installation

npm install @sparkstrand/notifications-core

The core package provides the unified notification service and is a peer dependency for all other notification packages.

Key Features

  • • Unified API: Single service interface for all notification operations
  • • App Management: Support for multiple independent applications
  • • Automatic provider routing: Smart selection of best available provider
  • • Fallback strategies: Failover, parallel, and hybrid delivery approaches
  • • Provider abstraction: Switch between Novu, Resend, Twilio, or custom providers
  • • TypeScript support: Full type safety and IntelliSense
  • • Batch operations: Send multiple notifications efficiently
  • • Real-time monitoring: Provider status, metrics, and delivery analytics

Setting Up Your App

How It Works

Your app registers with the notification service using your own provider API keys. The system creates isolated provider instances for your app and automatically routes notifications through the best available provider for each channel.

// App registration with provider keys
await notificationService.registerApp({
  appId: 'sporty-expats',
  name: 'SportyExpats',
  providers: {
    novu: { apiKey: 'novu-key', appId: 'novu-app' },
    resend: { apiKey: 'resend-key', fromEmail: 'notifications@sportyexpats.com' }
  }
});

Provider Isolation

Each registered app gets its own isolated provider instances:

  • • sporty-expats-novu: Novu provider with SportyExpats' API keys
  • • sporty-expats-resend: Resend provider with SportyExpats' API keys
  • • tax-done-novu: Novu provider with TaxDone's API keys
  • • venture-direction-twilio: Twilio provider with VentureDirection's credentials

Supported Providers

Novu

Full-featured notification platform

  • • Email notifications
  • • SMS via Twilio
  • • Push notifications
  • • In-app notifications
  • • Chat integrations

Resend

Modern email API for developers

  • • Transactional emails
  • • HTML email templates
  • • Email analytics
  • • Domain verification
  • • High deliverability

Twilio

SMS and voice communications

  • • SMS delivery
  • • Voice calls
  • • WhatsApp Business
  • • Global coverage
  • • Delivery receipts

Provider Routing & Fallbacks

Automatic Routing

The system automatically selects the best provider for each notification based on:

  • • Channel support: Provider must support the requested delivery channel
  • • Priority ranking: Lower priority numbers = higher priority
  • • Provider status: Only enabled and healthy providers are considered
  • • Rate limits: Providers within their rate limits are preferred

Fallback Strategies

Failover

Try primary provider, fall back to secondary if it fails

Parallel

Send via multiple providers simultaneously for redundancy

Hybrid

Combine strategies based on notification priority and channel

Usage Examples

Basic Notification

// Send a simple notification
const result = await notificationService.sendNotification(
  'user-123',
  'INFO',
  'Welcome!',
  'Thanks for joining our platform',
  { email: 'user@example.com' }
);

Bulk Notifications

// Send multiple notifications efficiently
const results = await notificationService.sendBulkNotifications({
  appId: 'sporty-expats',
  notifications: [
    { userId: 'user-1', type: 'INFO', title: 'Event Reminder', content: '...' },
    { userId: 'user-2', type: 'INFO', title: 'Event Reminder', content: '...' }
  ],
  globalOptions: { channels: { email: true, inApp: true } }
});

Best Practices

  • • Register early: Register your app during application startup
  • • Provider priority: Set appropriate priority levels for your providers
  • • Fallback strategy: Choose the right fallback strategy for your use case
  • • Rate limits: Configure appropriate rate limits per app and provider
  • • Error handling: Always wrap notification calls in try-catch blocks
  • • Monitoring: Use the built-in metrics and status endpoints
  • • Testing: Test with multiple providers to ensure fallback works