UserNotification

• UserNotification
  • Overview
  • Data Structure
    • State Schema
    • Enums and Types
  • Core Functionality
    • Notification Management
    • User Identity Resolution
  • API Methods
    • Notification Operations
    • Notification Queries
  • Key Features

Overview

The UserNotification class manages in-app notifications for individual users. It stores and tracks notifications delivered to users through the platform's notification system, providing read/unread tracking, status management, and pagination support.

General Purpose:

• Store and manage in-app notifications for individual users
• Track notification read/unread status and timestamps
• Support notification archival and deletion
• Provide paginated notification lists with filtering
• Serve both program management users and end users (members)

Architecture Pattern:

• Instance-based class where each instance represents a user's notification inbox
• instanceId format: uses prefixed user ID (M{userId} for members, PM{userId} for program management users)
• Notifications are added automatically by the NotificationManager when in-app channel is enabled

Data Structure

State Schema

interface UserNotificationState {
    private: {
        userId: string
        notifications: UserNotificationItem[]
    }
    public: {}
}

interface UserNotificationItem {
    id: string
    userId: string
    templateId: string
    subject?: string
    content: string
    metadata?: Record<string, any>
    status: UserNotificationStatus
    createdAt: Date
    readAt?: Date
}

Enums and Types

enum UserNotificationStatus {
    UNREAD = 'unread',
    READ = 'read',
    ARCHIVED = 'archived'
}

Core Functionality

Notification Management

• Add Notification: Internal method called by NotificationManager to add new notifications
• Mark as Read: Update notification status to read and set readAt timestamp
• Update Status: Change notification status (unread, read, archived)
• Delete Notification: Permanently remove a notification from user's inbox
• List Notifications: Retrieve paginated list with optional status filtering
• Unread Count: Get quick count of unread notifications

User Identity Resolution

The class supports two user types with prefixed instance IDs:

• Members (End Users): instanceId = M{userId}
• Program Management Users: instanceId = PM{userId}

The authorizer ensures users can only access their own notifications:

• enduser identity can only access member notifications (M prefix) matching their userId
• program_management_user identity can only access PM notifications (PM prefix) matching their userId

API Methods

Notification Operations

• addNotification (WRITE) - Add a notification for the user (internal)

  • Permission: All ClassIdentities (internal service method)
  • Input: { templateId: string, subject?: string, content: string, metadata?: Record<string, any> }
  • Returns: Created notification object

• markNotificationAsRead (WRITE) - Mark a notification as read

  • Permission: program_management_user, enduser
  • Input: { notificationId: string }
  • Returns: 204 No Content

• updateNotificationStatus (WRITE) - Update notification status

  • Permission: program_management_user, enduser
  • Input: { notificationId: string, status: UserNotificationStatus }
  • Returns: 204 No Content

• deleteNotification (WRITE) - Delete a notification

  • Permission: program_management_user, enduser
  • Input: { notificationId: string }
  • Returns: 204 No Content

Notification Queries

• listUserNotifications (READ) - List user notifications

  • Permission: program_management_user, enduser
  • Input: { status?: UserNotificationStatus, page?: number, limit?: number }
  • Returns: { notifications: UserNotificationItem[], totalCount: number, page: number, limit: number, totalPages: number }

• getUnreadCount (READ) - Get count of unread notifications

  • Permission: program_management_user, enduser
  • Returns: { unreadCount: number }

Key Features

1. User-Specific Notifications

   • Each user has their own notification instance
   • Isolated notification storage per user
   • Automatic instance creation on first notification

2. Multi-User Type Support

   • Supports both member (enduser) and program management user notifications
   • Prefixed instance IDs for user type identification
   • Authorizer enforces user-specific access control

3. Status Tracking

   • Three status levels: unread, read, archived
   • Automatic readAt timestamp on mark as read
   • Status filtering in list queries

4. Pagination Support

   • Standard pagination structure (page, limit, totalCount, totalPages)
   • Configurable page size (1-100 items per page)
   • Default 10 items per page

5. Integration with NotificationManager

   • Automatically receives notifications from NotificationManager
   • Notifications added via tasks when in-app channel is enabled
   • Template ID reference for notification source tracking

6. Metadata Support

   • Optional metadata field for custom data
   • Flexible structure for additional notification context
   • Preserved through notification lifecycle