@memberjunction/notifications

Unified notification engine for MemberJunction that handles in-app, email, and SMS delivery based on notification types and user preferences. This server-side package coordinates between the MJ entity system, template engine, and communication engine to deliver notifications through the appropriate channels.

Architecture

graph TD
    subgraph notif["@memberjunction/notifications"]
        NE["NotificationEngine\n(Singleton)"]
        TYPES["SendNotificationParams\nNotificationResult\nDeliveryChannels"]
    end

    subgraph entities["MJ Entity System"]
        UNT["UserNotificationTypes"]
        UNP["UserNotificationPreferences"]
        UNN["UserNotifications\n(In-App Records)"]
    end

    subgraph comm["@memberjunction/communication-engine"]
        CE["CommunicationEngine"]
    end

    subgraph templates["@memberjunction/templates"]
        TE["TemplateEngineServer"]
    end

    subgraph providers["Delivery Channels"]
        INAPP["In-App\n(Database Record)"]
        EMAIL["Email\n(via SendGrid)"]
        SMS["SMS\n(via Twilio)"]
    end

    NE -->|reads types| UNT
    NE -->|checks prefs| UNP
    NE -->|creates| UNN
    NE -->|sends via| CE
    CE -->|renders| TE
    UNN --> INAPP
    CE --> EMAIL
    CE --> SMS

    style notif fill:#7c5295,stroke:#563a6b,color:#fff
    style entities fill:#2d6a9f,stroke:#1a4971,color:#fff
    style comm fill:#2d8659,stroke:#1a5c3a,color:#fff
    style templates fill:#b8762f,stroke:#8a5722,color:#fff
    style providers fill:#2d8659,stroke:#1a5c3a,color:#fff

Installation

npm install @memberjunction/notifications

Usage

Sending a Notification

import { NotificationEngine } from '@memberjunction/notifications';
import { SendNotificationParams } from '@memberjunction/notifications';

const engine = NotificationEngine.Instance;
await engine.Config(false, contextUser);

const params: SendNotificationParams = {
    userId: 'user-uuid',
    typeNameOrId: 'Agent Completion',
    title: 'Agent Run Finished',
    message: 'Your AI agent has completed processing.',
    templateData: {
        agentName: 'Data Analyzer',
        duration: '2m 34s'
    },
    resourceTypeId: 'resource-type-uuid',
    resourceRecordId: 'agent-run-uuid',
    resourceConfiguration: { conversationId: 'conv-uuid' }
};

const result = await engine.SendNotification(params, contextUser);

if (result.success) {
    console.log('Channels used:', result.deliveryChannels);
    // { inApp: true, email: true, sms: false }
}

Forcing Delivery Channels

Override user preferences and type defaults by specifying exact channels:

const result = await engine.SendNotification({
    userId: 'user-uuid',
    typeNameOrId: 'System Alert',
    title: 'Critical Error',
    message: 'Database connection lost',
    forceDeliveryChannels: {
        inApp: true,
        email: true,
        sms: true
    }
}, contextUser);

Channel Resolution Logic

flowchart TD
    START["SendNotification()"] --> FORCE{"forceDeliveryChannels\nspecified?"}
    FORCE -->|Yes| USE_FORCE["Use forced channels directly"]
    FORCE -->|No| CHECK_PREFS{"User preference\nexists?"}
    CHECK_PREFS -->|Yes| CHECK_ENABLED{"Preference\nenabled?"}
    CHECK_ENABLED -->|No| ALL_OFF["All channels disabled\n(user opted out)"]
    CHECK_ENABLED -->|Yes| CHECK_ALLOW{"Type allows\nuser preference?"}
    CHECK_ALLOW -->|Yes| USE_PREFS["Use user preference\nper-channel settings"]
    CHECK_ALLOW -->|No| USE_DEFAULTS["Use type defaults"]
    CHECK_PREFS -->|No| USE_DEFAULTS

    style START fill:#2d6a9f,stroke:#1a4971,color:#fff
    style USE_FORCE fill:#2d8659,stroke:#1a5c3a,color:#fff
    style USE_PREFS fill:#2d8659,stroke:#1a5c3a,color:#fff
    style USE_DEFAULTS fill:#b8762f,stroke:#8a5722,color:#fff
    style ALL_OFF fill:#7c5295,stroke:#563a6b,color:#fff

The engine resolves delivery channels with this priority:

1. Force override: If forceDeliveryChannels is set, use it directly
2. User opt-out: If user preference exists but Enabled is false, all channels are disabled
3. User preference: If the notification type allows user preferences, use per-channel settings (InAppEnabled, EmailEnabled, SMSEnabled)
4. Type defaults: Fall back to DefaultInApp, DefaultEmail, DefaultSMS from the notification type

Delivery Channels

Channel	How It Works
In-App	Creates a UserNotification entity record in the database. Synchronous, instant.
Email	Renders the notification type’s EmailTemplateID via TemplateEngineServer, then sends through CommunicationEngine using SendGrid. Fire-and-forget (async).
SMS	Renders the notification type’s SMSTemplateID via TemplateEngineServer, then sends through CommunicationEngine using Twilio. Fire-and-forget (async).

Type Definitions

SendNotificationParams

Property	Type	Required	Description
userId	string	Yes	Target user ID
typeNameOrId	string	Yes	Notification type name or UUID
title	string	Yes	Short title (in-app display, email subject)
message	string	Yes	Full notification message
templateData	Record<string, unknown>	No	Data for email/SMS template rendering
resourceTypeId	string	No	Link notification to a resource type
resourceRecordId	string	No	Link notification to a specific record
resourceConfiguration	object	No	Navigation context stored as JSON
forceDeliveryChannels	DeliveryChannels	No	Override channel resolution

NotificationResult

Property	Type	Description
success	boolean	Overall operation success
inAppNotificationId	string	ID of created in-app notification
emailSent	boolean	Whether email delivery was initiated
smsSent	boolean	Whether SMS delivery was initiated
deliveryChannels	DeliveryChannels	Resolved channels used
errors	string[]	Error messages if any

DeliveryChannels

interface DeliveryChannels {
    inApp: boolean;
    email: boolean;
    sms: boolean;
}

Dependencies

Package	Purpose
@memberjunction/core	BaseEngine, Metadata, UserInfo, logging
@memberjunction/core-entities	UserNotification, UserNotificationType entities
@memberjunction/communication-engine	CommunicationEngine for email/SMS delivery
@memberjunction/communication-types	Message class
@memberjunction/templates	TemplateEngineServer for rendering
@memberjunction/sqlserver-dataprovider	UserCache for server-side user lookup

Development

npm run build    # Compile TypeScript