Member

Member

Overview

The Member class manages individual loyalty program member profiles and their complete lifecycle. Each member is represented as a separate instance. The class handles member registration, profile updates, family management, photo verification, eligibility processing, and company member type validation.

General Purpose:

Individual member profile and lifecycle management
Tab-based profile organization (Personal, Membership, Employment, Contact, Dependants) (Program Management)
Multi-tier membership support with payment integration
Family member and dependant management
Photo verification and approval workflows
Authentication method determination based on email domain
Eligibility rule processing for tier qualification
Workflow integration for status transitions and approvals

Data Structure

State Schema

Each Member instance maintains a singleton state with the member's complete profile:

interface MemberState {
  private: {
    profile: MemberProfile
  }
  public: {}
}

interface MemberProfile {
  id: string
  status: MemberStatus
  name: string
  middleName?: string
  surname: string
  staffId: string
  email: string
  phone: string
  company: { id: string }
  grade: string
  idPhoto?: string
  loginMethod: MemberLoginMethod
  address: { country: string; address: string }
  memberType: string
  memberSubType?: string
  memberships: Membership[]
  primaryMemberId?: string
  relation?: string
  family?: FamilyMember[]
  createdBy: Actor
  note?: string
  permissions?: MemberPermissions
  createdAt: Date
  updatedAt: Date
}

Member Status Lifecycle

enum MemberStatus {
  PENDING_INVITE = 'pending_invite',                  // Awaiting invitation email to be sent
  PENDING_INVITATION_ACCEPTANCE = 'pending_invitation_acceptance', // Invitation email sent, awaiting acceptance
  PENDING_APPROVAL = 'pending_approval',              // Awaiting approval after creation
  PENDING_ID_PHOTO = 'pending_id_photo',              // Awaiting photo upload
  PENDING_TIER = 'pending_tier',                      // Awaiting tier assignment
  ACTIVE = 'active',                                  // Fully activated member
  INACTIVE = 'inactive',                              // Deactivated member
  SUSPENDED = 'suspended',                            // Temporarily suspended member
  REJECTED = 'rejected'                               // Member creation/update rejected
}

Authentication Methods

enum MemberLoginMethod {
  SSO = 'sso',                    // Single Sign-On (domain-based)
  EMAIL_PASSWORD = 'email_password' // Email and password authentication
}

Payment Types

enum PaymentType {
  DDS = 'dds',    // Direct Debit System
  CPG = 'cpg'     // Corporate Payment Gateway
}

Core Functionality

Tab-Based Profile Management

Personal Tab: Name, staff ID, member type/subtype (with company eligibility validation)
Membership Tab: Tier assignments, payment configurations, membership periods
Employment Tab: Company association, grade/position information
Contact Tab: Phone, address, communication permissions
Dependants Tab: Family member management and relationships

Family Member Management

Family Addition: Add dependants with relationship tracking
Family Updates: Modify family member information and status
Family Removal: Remove dependants from member profile
Membership Status: Independent membership status for each family member

Photo Management

ID Photo Upload: Secure photo upload for verification with previous photo tracking
Photo Approval: Workflow-driven photo approval process with photo comparison support
Status Transitions: Automatic status updates based on photo lifecycle
Secure Access: File access tokens with expiration for photo URLs
Approval Context: Previous and new photo tracking for approval workflows

Document Management

Document Upload: Secure upload of images and documents with file type validation
Document Storage: Metadata stored in Member state, files managed by FileManager
Document Listing: Paginated list of documents with status enrichment
Status Tracking: Active and archived status for document lifecycle management
Secure Download: Temporary access URLs with expiration for both active and archived documents
Archival System: Archive/unarchive functionality with separate download permissions

Eligibility Rules

Rule Processing: Complex eligibility evaluation for tier qualification
Cross-Entity Lookups: Support for member, company, and external data sources
Field Definitions: Available through Tier class getEligibilityRuleDefinitions method

Status Management & Workflows

Lifecycle Management: Automated status transitions through workflow rules
Approval Integration: ApprovalManager integration for member operations
Event Tracking: Comprehensive event logging for all member activities
Business Rules: Configurable workflow rules for status changes
Validation Rules: Company member type eligibility validation during member creation and updates

API Methods

Personal Tab Methods

updateMemberPersonal (WRITE) - Update member personal information
- Updates name, staff ID, member type/subtype (validates eligibility against company)
getMemberPersonal (READ) - Get member personal information
- Returns personal data with secure file access tokens for photos
- Includes pending approval information with old/new photo comparison data

Membership Tab Methods

addMembership (WRITE) - Add new membership to member
- Adds tier membership with payment configuration
- Validates tier status and company-paid payment type
- Automatically sets membership periods and payment schedules
listMemberships (READ) - List member memberships with pagination and filtering
- Returns paginated list of memberships with tier details enrichment
- Supports filtering by tier ID, tier group (base/upgrade/add-on), and membership status (active/expired/inactive/suspended)
- Status is stored in the membership record
- Enriches each membership with tier name, tier type (group, label), and fee information
- Response includes: { memberships: EnrichedMembership[], totalCount, page, limit, totalPages }

Employment Tab Methods

updateMemberEmployment (WRITE) - Update member employment information
- Updates grade/position information (company association cannot be changed after member creation)
getMemberEmployment (READ) - Get member employment information

Contact Tab Methods

updateMemberContact (WRITE) - Update member contact information
- Updates phone, address, communication permissions
getMemberContact (READ) - Get member contact information

Dependants Tab Methods

getMemberDependants (READ) - Get member dependants information
addMemberFamilyMember (WRITE) - Add a family member to member's dependants
- Creates new family member with relationship tracking
updateMemberFamilyMember (WRITE) - Update a family member in member's dependants
removeMemberFamilyMember (WRITE) - Remove a family member from member's dependants

Photo Management Methods

uploadMemberIdPhoto (WRITE) - Upload member's ID photo (program_management_user)
- Secure photo upload with validation
- Tracks previous photo path for approval workflow context
- Status transition: PENDING_ID_PHOTO → ACTIVE (with active membership) or PENDING_TIER (no active membership)
uploadMyIdPhoto (WRITE) - Upload member's own ID photo (enduser)
- Allows logged-in members to upload their own ID photo
- Status validation: Only ACTIVE or PENDING_ID_PHOTO members can upload
- Same workflow and approval process as uploadMemberIdPhoto
- Status transition: PENDING_ID_PHOTO → ACTIVE (with active membership) or PENDING_TIER (no active membership)
- Returns secure access URLs with expiration times
approveMemberIdPhoto (QUEUED_WRITE) - Approve or reject member's ID photo
- Workflow-driven approval process

Status and Approval Methods

updateMemberStatus (WRITE) - Update member status
- Direct status updates with workflow integration
- System-only statuses (pending_invite, pending_invitation_acceptance, pending_id_photo, pending_tier) cannot be set manually
sendInviteEmail (WRITE) - Send invitation email to member
- Only applicable for EMAIL_PASSWORD login method users
- SSO users receive welcome email automatically upon member creation approval (via approveMemberCreate)
- Member must have at least one active membership to receive invitation
- Sends invitation email and updates status from pending_invite to pending_invitation_acceptance
- Can re-send invitations to members already in pending_invitation_acceptance status (creates new OTP token)
- Only callable by program_management_user
approveMember (QUEUED_WRITE) - Approve member operations (create/update)
- General approval workflow for member operations
- After member creation approval:
  - For SSO users: Welcome email is sent automatically upon approval
  - For EMAIL_PASSWORD users: Status changes to pending_invite (invitation sent separately via sendInviteEmail)

Listing Methods

listMembers (READ) - List members with filtering and pagination
- Filtering, search, and pagination capabilities

Data Streaming Methods

streamMember (WRITE) - Manually stream member data to MongoDB
- Manual data synchronization to MongoDB collections

Integration Service Methods

updateEmployeePhoto (WRITE) - Update employee photo via integration service
- Allows external HR systems to update employee photos using base64-encoded photo data
- Uses integration_user authentication for secure API key-based access
- Automatically manages FileManager operations for photo storage
- Implements robust error handling with specific error wrapping:
  - Catches FileManager upload errors and wraps them in EMPLOYEE_PHOTO_UPLOAD_FAILED (code: 10018)
  - Preserves original error details (message and code) for debugging
  - Ensures clear error messages for integration consumers
- Triggers MEMBER_ID_PHOTO_UPLOAD workflow event for approval processing

Document Management Methods

uploadDocument (WRITE) - Upload a document or image for the member
- Supports images (max 5MB: jpeg, jpg, png, gif, webp) and documents (max 10MB: pdf, doc, docx, xls, xlsx, txt, csv)
- Document metadata is stored in Member state for efficient tracking
- Uses FileManager for secure file storage
- Returns temporary download URL (expires in 5 minutes) along with document ID
listDocuments (READ) - List member documents with pagination
- Returns paginated list of documents with metadata
- Supports filtering by status (active/archived) through status field
- Sorted by upload date (newest first)
- Includes enriched status information with labels and isArchived flag
- Response includes: { documents, totalCount, page, limit, totalPages }
downloadDocument (READ) - Download an active member document
- Returns temporary access URL for active documents (expires in 5 minutes)
- Prevents download of archived documents (use downloadArchivedDocument instead)
- Returns error if document not found or archived
archiveDocument (WRITE) - Archive a member document
- Changes document status to archived
- Archived documents cannot be downloaded via regular downloadDocument endpoint
- Returns document ID on successful archival
unarchiveDocument (WRITE) - Unarchive a member document
- Changes document status back to active
- Makes document accessible through regular downloadDocument endpoint
- Returns document ID on successful unarchival
downloadArchivedDocument (READ) - Download an archived member document
- Specifically for accessing archived documents with separate permissions
- Returns temporary access URL (expires in 5 minutes)
- Can also download active documents (separate permission control)

Member Authentication Methods

discoverAuthMethod (STATIC) - Discover authentication method for member email
- Determines SSO or EMAIL_PASSWORD based on email domain
- For SSO domains, returns SSO login URL for identity provider
- For EMAIL_PASSWORD, checks if member exists and initiates OTP registration flow if not
- Public endpoint (no authentication required)
singleSignOn (STATIC) - Process SSO SAML response and authenticate member
- Handles SSO callback from identity provider (Azure AD, etc.)
- Validates SAML response and extracts user email
- Verifies member exists and is authorized for SSO login
- Activates pending members (pending_invitation_acceptance) automatically
- Generates JWT token and redirects to member web application
- Public endpoint (no authentication required)
acceptInvitation (WRITE) - Accept member invitation and set password
- Validates invitation token and sets member password
- Transitions member to active status
- Public endpoint (no authentication required)
inviteRedirect (STATIC) - HTML redirect endpoint for member invitations
- Redirect handler for email invitation links
- Public endpoint (no authentication required)
login (STATIC) - Authenticate member with email and password
- Verifies credentials and sends OTP to email
- Public endpoint (no authentication required)
checkOtp (WRITE) - Verify login OTP and issue access token
- Validates OTP and generates authentication token
- Requires member_otp identity
resendOtp (WRITE) - Resend login OTP to member email
- Re-sends OTP for failed delivery or expiration
- Requires member_otp identity
getMemberProfile (READ) - Get basic member profile information
- Returns member's core profile data (name, email, phone, company, status)
- Includes hasWaitingApproval boolean flag indicating pending ID photo approval
- Includes approval object with photo URLs when approval is pending
- Only accessible by the member themselves (enduser identity)

Password Management Methods

sendPasswordResetEmail (STATIC) - Send password reset email with token
- Sends password reset link to member email
- Public endpoint (no authentication required)
resetPassword (WRITE) - Reset password using token from email
- Validates reset token and updates password
- Public endpoint (no authentication required)
changePassword (WRITE) - Change password for logged-in member
- Requires current password verification
- Requires enduser identity (logged-in member)

Key Features

Instance-Based Architecture: Each member is a separate Rio instance with unique state
Tab-Based Organization: Profile organized into logical tabs for better management
Family Support: Comprehensive family member and dependant management
Authentication Integration: Automatic login method determination based on email domain
Photo Verification: Complete photo upload and approval workflow
Document Management: Secure document upload, listing, download, and archival with status tracking
Eligibility Processing: Rule processing for tier qualification and membership eligibility
Workflow Compatible: Extends WorkflowCompatibleStateManager for business process automation
MongoDB Integration: Automatic data streaming to MongoDB for analytics and reporting
Permission Management: Granular communication permissions (SMS, email)
Audit Trail: Complete audit logging through LogManager integration

Class Relations

The following diagram illustrates how Member integrates with other system components:

Member Class Relations

Keyboard shortcuts

Platinum