@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