⚙️ Invitation Handlers

Invitation handlers provide core business logic functions for invitation management operations in Nodeblocks applications. These handlers encapsulate common patterns for invitation database operations, data transformation, and response formatting.

---

🎯 Overview

Invitation handlers are designed to:

• Encapsulate invitation business logic in reusable functions
• Handle invitation database operations with proper error management
• Transform invitation data between different formats
• Ensure type safety with TypeScript integration
• Support composition with other invitation blocks

---

📋 Invitation Handler Types

Invitation Async Handlers

Functions that perform asynchronous invitation operations (database calls, API requests, etc.).

Invitation Sync Handlers

Functions that perform synchronous invitation operations (data transformation, validation, etc.).

Invitation Terminator Handlers

Functions that format and return the final invitation response.

---

🔧 Available Invitation Handlers

createInvitation

Creates a new invitation in the database.

Purpose: Handles creation of invitations with entity management

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody: Invitation creation data
  • context.db: Database connection
  • context.configuration.invitation.status.pending: Pending status configuration

Returns: Result<RouteHandlerPayload, Error> - Success with invitationId or error

Payload Requirements:

• params.requestBody must contain invitation data
• context.db must be available for database operations
• context.configuration.invitation.status.pending should be configured

Key Features:

• Validates request body is present and not empty
• Uses configuration for pending status or defaults to 'pending'
• Creates base entity with timestamps and ID
• Inserts invitation into database
• Returns invitationId on success
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { createInvitation } = handlers;

// Use in composition
const invitationPipeline = compose(createInvitation, generateToken, sendEmail);

---

sendInvitationEmail

Sends invitation email with one-time token.

Purpose: Handles email delivery for invitation notifications

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.data.invitation: Invitation object from previous handler
  • context.data.token: One-time token from previous handler
  • context.mailService: Mail service for sending emails
  • context.configuration.invitation.emailConfig: Email configuration
  • context.configuration.invitation.enabled: Whether invitations are enabled

Returns: Result<RouteHandlerPayload, Error> - Success with invitationEmailSent flag or error

Payload Requirements:

• context.data.invitation and token must be available from previous handlers
• context.mailService must be available for email sending
• context.configuration.invitation must be enabled and properly configured

Key Features:

• Validates invitation and token are provided
• Checks invitation email configuration is complete and enabled
• Validates mail service is available
• Generates email HTML using template and token
• Sends invitation email using mail service
• Returns email sending result on success
• Handles configuration and email sending errors

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { sendInvitationEmail } = handlers;

// Use in composition
const invitationPipeline = compose(generateToken, sendInvitationEmail, terminator);

---

findInvitations

Finds multiple invitations with optional filtering.

Purpose: Handles querying invitations with filter support

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestQuery: Optional filter criteria for invitations
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with invitations array or error

Payload Requirements:

• params.requestQuery is optional - if provided, used as MongoDB filter
• context.db must be available for database operations

Key Features:

• Accepts optional filter from request query
• Returns all invitations if no filter provided
• Returns array of invitations
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { findInvitations } = handlers;

// Use in composition
const invitationPipeline = compose(findInvitations, listTerminator);

---

buildCheckInvitationTokenPayload

Builds payload for invitation token validation with target specification.

Purpose: Configures token validation for invitation workflow

Parameters:

• payload: RouteHandlerPayload - Contains request context and data

Returns: Result<RouteHandlerPayload, Error> - Success with checkToken configuration

Payload Requirements:

• No specific requirements - this handler always succeeds

Key Features:

• Merges checkToken configuration with invitation target
• Sets target to INVITATION_TARGET constant
• Always succeeds (no error conditions)
• Returns updated payload with checkToken configuration
• Used as preparation step for invitation token validation

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { buildCheckInvitationTokenPayload } = handlers;

// Use in composition
const invitationPipeline = compose(buildCheckInvitationTokenPayload, checkToken);

---

buildInvitationOnetimeTokenPayload

Builds a payload for generating invitation one-time tokens.

Purpose: Prepares invitation-specific data and request information for the generateOnetimeToken handler

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.data.invitationId: Invitation ID from previous handler
  • context.configuration.invitation.target: Invitation target configuration

Returns: Result<RouteHandlerPayload, Error> - Success with token payload data or error

Payload Requirements:

• context.data.invitationId must be available from previous handler
• context.configuration.invitation.target should be configured

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { buildInvitationOnetimeTokenPayload } = handlers;

// Use in composition
const invitationPipeline = compose(createInvitation, buildInvitationOnetimeTokenPayload, generateOnetimeToken, sendEmail);

---

getInvitationIdFromTokenInfo

Extracts invitation ID from token information in request context.

Purpose: Extracts invitationId from token data for invitation processing

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.data.tokenInfo.invitationId: Invitation ID from token

Returns: Result<RouteHandlerPayload, Error> - Success with invitationId or error

Payload Requirements:

• context.data.tokenInfo.invitationId must be available from previous handler

Key Features:

• Extracts invitationId from token info in context
• Validates invitationId is provided
• Returns invitationId on success
• Returns 400 error if invitationId is missing
• Used as preparation step for invitation processing

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { getInvitationIdFromTokenInfo } = handlers;

// Use in composition
const invitationPipeline = compose(getInvitationIdFromTokenInfo, getInvitationById, isPendingInvitation);

---

getInvitationById

Retrieves a single invitation by its unique identifier.

Purpose: Fetches invitation details from database using invitation ID

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.invitationId or context.data.invitationId: Invitation ID to retrieve
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with invitation object or error

Payload Requirements:

• Invitation ID must be provided in params.requestParams.invitationId or context.data.invitationId
• context.db must be available for database operations

Key Features:

• Validates invitationId is provided
• Finds invitation by ID in database
• Returns 404 if invitation not found
• Returns invitation data on success
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { getInvitationById } = handlers;

// Use in composition
const invitationPipeline = compose(getInvitationById, isPendingInvitation, updateInvitation);

---

verifyInvitationPayload

Verifies invitation authenticity using token information.

Purpose: Validates invitation ID against token information for security

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.invitationId or context.data.invitationId: Invitation ID to verify
  • context.data.tokenInfo.invitationId: Invitation ID from token

Returns: Result<RouteHandlerPayload, Error> - Success with verified invitationId or error

Payload Requirements:

• Invitation ID must be provided in params or context data
• context.data.tokenInfo.invitationId must be available from previous handler
• Both IDs must match for verification to succeed

Key Features:

• Extracts invitationId from multiple sources
• Validates tokenInfo contains invitationId
• Compares invitationId with token invitationId for security
• Returns verification flag on success
• Returns 400 error if IDs don't match
• Ensures invitation authenticity

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { verifyInvitationPayload } = handlers;

// Use in composition
const invitationPipeline = compose(verifyInvitationPayload, getInvitationById, isPendingInvitation);

---

isPendingInvitation

Validates that an invitation is in pending status.

Purpose: Ensures invitation can be processed by checking its status

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.data.invitation: Invitation object from previous handler
  • context.configuration.invitation.status.pending: Pending status configuration

Returns: Result<RouteHandlerPayload, Error> - Success with isPendingInvitation flag or error

Payload Requirements:

• context.data.invitation must be available from previous handler
• context.configuration.invitation.status.pending should be configured

Key Features:

• Validates invitation is provided in context
• Uses configuration for pending status or defaults to 'pending'
• Checks invitation status matches pending status
• Returns pending flag on success
• Returns 400 error if invitation is not pending
• Ensures invitation can be processed

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { isPendingInvitation } = handlers;

// Use in composition
const invitationPipeline = compose(getInvitationById, isPendingInvitation, buildAcceptInvitationPayload);

---

buildAcceptInvitationPayload

Builds payload for accepting an invitation with updated status and timestamp.

Purpose: Prepares invitation data with accepted status and acceptance timestamp

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • context.configuration.invitation.status.accepted: Accepted status configuration

Returns: Result<RouteHandlerPayload, Error> - Success with updated invitation data or error

Payload Requirements:

• context.configuration.invitation.status.accepted should be configured

Key Features:

• Uses configuration for accepted status or defaults to 'accepted'
• Updates base entity with timestamps
• Sets acceptedAt timestamp to current date
• Sets status to accepted
• Returns updated invitation data on success
• Prepares invitation for acceptance workflow

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { buildAcceptInvitationPayload } = handlers;

// Use in composition
const invitationPipeline = compose(getInvitationById, isPendingInvitation, buildAcceptInvitationPayload, updateInvitation);

---

updateInvitation

Updates invitation data in the database with validation and error handling.

Purpose: Updates invitation records with proper validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.invitationId or context.data.invitationId: Invitation ID to update
  • params.requestBody or context.data.invitation: Invitation data to update
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with invitationId or error

Payload Requirements:

• Invitation ID must be provided in params or context data
• Invitation data must be provided in request body or context data
• context.db must be available for database operations

Key Features:

• Validates invitationId is provided
• Validates invitation data is present and not empty
• Updates base entity with timestamps
• Checks if invitation exists before updating
• Returns invitationId on success
• Handles not found and update failures
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { updateInvitation } = handlers;

// Use in composition
const invitationPipeline = compose(getInvitationById, isPendingInvitation, buildAcceptInvitationPayload, updateInvitation);

---

deleteInvitation

Removes an invitation from the database by its unique identifier.

Purpose: Permanently deletes invitation records with validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.invitationId or context.data.invitationId: Invitation ID to delete
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with invitationId or error

Payload Requirements:

• Invitation ID must be provided in params.requestParams.invitationId or context.data.invitationId
• context.db must be available for database operations

Key Features:

• Validates invitationId is provided
• Deletes invitation by ID from database
• Returns 404 if invitation not found
• Returns deletion result on success
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { deleteInvitation } = handlers;

// Use in composition
const invitationPipeline = compose(getInvitationById, deleteInvitation, deleteTerminator);

---

🎯 Invitation Terminator Handlers

createInvitationTerminator

Terminates invitation creation with proper status code.

Purpose: Formats successful invitation creation response with 201 status

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.createInvitation: Creation result from previous handler

Returns: Response object with 201 statusCode

Payload Requirements:

• context.data.createInvitation must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { createInvitationTerminator } = handlers;

// Use in composition
const invitationPipeline = compose(createInvitation, createInvitationTerminator);

---

normalizeInvitationTerminator

Normalizes invitation data by removing database-specific fields.

Purpose: Cleans invitation data for API response

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.invitation: Invitation object from previous handler

Returns: Normalized invitation object

Payload Requirements:

• context.data.invitation must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { normalizeInvitationTerminator } = handlers;

// Use in composition
const invitationPipeline = compose(getInvitationById, normalizeInvitationTerminator);

---

normalizeInvitationsListTerminator

Normalizes invitations list by removing database-specific fields from each item.

Purpose: Cleans invitations array data for API response

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.invitations: Array of invitation objects from previous handler

Returns: Array of normalized invitation objects

Payload Requirements:

• context.data.invitations must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { normalizeInvitationsListTerminator } = handlers;

// Use in composition
const invitationPipeline = compose(findInvitations, normalizeInvitationsListTerminator);

---

deleteInvitationTerminator

Terminates invitation deletion with proper status code.

Purpose: Formats successful deletion response with 204 status

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.deleteInvitation: Deletion result from previous handler

Returns: Response object with 204 statusCode

Payload Requirements:

• context.data.deleteInvitation must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { deleteInvitationTerminator } = handlers;

// Use in composition
const invitationPipeline = compose(deleteInvitation, deleteInvitationTerminator);