Integration Guide

Step-by-step guides for integrating the Spark Strand notifications system into your applications. The system uses a self-service architecture where each app manages its own provider credentials.

Quick Start

1. Install Core Package

Start by installing the core notification package in your application.

npm install @sparkstrand/notifications-core

2. Configure Your Providers

Set up your own provider API keys in your application's environment variables.

# Your app's .env file
SPORTY_EXPATS_NOVU_API_KEY=sk_123...
SPORTY_EXPATS_NOVU_APP_ID=novu-app-id
SPORTY_EXPATS_RESEND_API_KEY=re_456...
SPORTY_EXPATS_FROM_EMAIL=notifications@sportyexpats.com

3. Register Your App

Register your application with the notification service during startup.

import { notificationService } from '@sparkstrand/notifications-core';
await notificationService.registerApp({
appId: 'sporty-expats',
name: 'SportyExpats',
providers: {
novu: { apiKey: process.env.SPORTY_EXPATS_NOVU_API_KEY, appId: process.env.SPORTY_EXPATS_NOVU_APP_ID },
resend: { apiKey: process.env.SPORTY_EXPATS_RESEND_API_KEY, fromEmail: process.env.SPORTY_EXPATS_FROM_EMAIL }
}
});

How It Works

App Registration

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

// App A: SportyExpats
sporty-expats-novu (with SportyExpats' Novu keys)
sporty-expats-resend (with SportyExpats' Resend keys)
// App B: TaxDone
tax-done-novu (with TaxDone's Novu keys)
tax-done-twilio (with TaxDone's Twilio keys)

Benefits

  • • Complete isolation: Each app's data and credentials are completely separate
  • • Independent deployment: Apps can be deployed and scaled independently
  • • Provider flexibility: Each app can use different providers and configurations
  • • Security: No shared credentials or cross-app data access
  • • Scalability: Apps can scale their notification usage independently

Platform Integration

Web Applications

  • • React applications
  • • Vue.js applications
  • • Angular applications
  • • Vanilla JavaScript
npm install @sparkstrand/notifications-react

Mobile Applications

  • • React Native
  • • Native iOS (Swift)
  • • Native Android (Kotlin)
  • • Flutter
npm install @sparkstrand/notifications-react-native

Desktop Applications

  • • Electron applications
  • • Native macOS apps
  • • Native Windows apps
  • • Cross-platform frameworks
npm install @sparkstrand/notifications-electron

Backend Services

  • • Node.js/Express
  • • Python/Django
  • • Go applications
  • • Java/Spring Boot
npm install @sparkstrand/notifications-core

Provider Configuration

Novu Provider

Full-featured notification platform supporting multiple channels.

novu: {
apiKey: 'your-novu-api-key',
appId: 'your-novu-app-id',
priority: 1, // Lower number = higher priority
supportedChannels: ['email', 'sms', 'push', 'inApp']
}

Resend Provider

Modern email API for transactional emails with high deliverability.

resend: {
apiKey: 'your-resend-api-key',
fromEmail: 'notifications@yourapp.com',
priority: 2,
supportedChannels: ['email']
}

Twilio Provider

SMS and voice communications with global coverage.

twilio: {
accountSid: 'your-twilio-account-sid',
authToken: 'your-twilio-auth-token',
fromPhoneNumber: '+1234567890',
priority: 3,
supportedChannels: ['sms']
}

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' },
{ appId: 'sporty-expats' }
);

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 } }
});

User Preferences

// Update user notification preferences
await notificationService.updateUserPreferences(
'sporty-expats',
'user-123',
{
email: true,
sms: false,
push: true,
inApp: true
}
);

Testing

Test Environment

Test your integration using the demo environment:

  • • Demo API: https://demo.notifications.sparkstrand.com/api
  • • Test credentials: Use your own provider test keys
  • • Sandbox mode: All notifications are logged but not delivered
  • • Rate limits: Higher limits for testing purposes

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
  • • Testing: Test with multiple providers to ensure fallback works
  • • Monitoring: Use the built-in metrics and status endpoints