⚙️ Invitation handlers
Invitation handlers are route-pipeline functions, not Express middleware. They read RouteHandlerPayload values from params and context, merge successful values into context.data, or terminate a successful Result with an HTTP response descriptor.
Inventory
| Handler | Pipeline role | Inputs / context | Result / behavior / errors | Used by routes |
|---|---|---|---|---|
INVITATION_TARGET | Constant | N/A | Exact 'invitation' token target. | registerCredentialsRoute |
INVITATION_STATUS_PENDING | Constant | N/A | Exact 'pending' default status. | createInvitationRoute, registerCredentialsRoute |
INVITATION_STATUS_ACCEPTED | Constant | N/A | Exact 'accepted' default status. | registerCredentialsRoute |
createInvitation | Handler | requestBody, db.invitations, configuration | Writes invitationId; 400 or 500. | createInvitationRoute |
sendInvitationEmail | Handler | Invitation, token, mail config/service | Writes delivery flag; 400 or 500. | createInvitationRoute |
createInvitationTerminator | Terminator | Invitation ID, delivery flag | Returns { invitationId, statusCode: 201 }; missing data is 500. | createInvitationRoute |
findInvitations | Handler | requestQuery, db.invitations | Writes invitations; 500 on query failure. | findInvitationsRoute |
normalizeInvitationsListTerminator | Terminator | Invitations or paginated list | Removes _id from each invitation; preserves pagination metadata. | findInvitationsRoute |
buildCheckInvitationTokenPayload | Handler | Pipeline payload | Writes invitation token target. | registerCredentialsRoute |
getInvitationIdFromTokenInfo | Handler | tokenInfo.invitationId | Writes invitation ID; 400 when absent. | registerCredentialsRoute |
getInvitationById | Handler | Invitation ID, db.invitations | Writes invitation; 400, 404, or 500. | createInvitationRoute, getInvitationByIdRoute, registerCredentialsRoute |
normalizeInvitationTerminator | Terminator | context.data.invitation | Removes _id and returns the invitation; 404 when absent. | getInvitationByIdRoute |
verifyInvitationPayload | Handler | Invitation ID, token info | Writes validity flag; 400 on mismatch. | Custom composition only |
isPendingInvitation | Handler | Invitation, status configuration | Writes pending flag; 400 when not pending. | registerCredentialsRoute |
buildAcceptInvitationPayload | Handler | Status configuration | Writes accepted update payload. | registerCredentialsRoute |
updateInvitation | Handler | Invitation ID, update payload, db.invitations | Writes invitation ID; 400, 404, or 500. | registerCredentialsRoute |
deleteInvitation | Handler | Invitation ID, db.invitations | Writes delete result; 400, 404, or 500. | deleteInvitationRoute |
deleteInvitationTerminator | Terminator | Delete result | Returns { statusCode: 204 }; missing result is 500. | deleteInvitationRoute |
buildInvitationOnetimeTokenPayload | Handler | Invitation ID, token configuration | Writes target and token data; 400 on failure. | createInvitationRoute |
Details
INVITATION_TARGET
Implementation
'invitation' is written by buildCheckInvitationTokenPayload and is the fallback token target for buildInvitationOnetimeTokenPayload. It therefore reaches registerCredentialsRoute through the former and createInvitationRoute through the latter.
INVITATION_STATUS_PENDING
Implementation
'pending' is the fallback for configuration.invitation.status.pending in createInvitation and isPendingInvitation. Those handlers are used by createInvitationRoute and registerCredentialsRoute, respectively.
INVITATION_STATUS_ACCEPTED
Implementation
'accepted' is the fallback for configuration.invitation.status.accepted in buildAcceptInvitationPayload, used by registerCredentialsRoute.
createInvitation
Implementation
Reads params.requestBody and context.configuration.invitation.status.pending, creates a base entity, inserts it into context.db.invitations, and writes context.data.invitationId. An empty body is 400 Request body is required; a missing insertedId is 400 Failed to create invitation; a database exception is 500 with the same message. Used by createInvitationRoute.
sendInvitationEmail
Implementation
Reads context.data.invitation, context.data.token, context.configuration.invitation, and context.mailService; it sends to the invitation email and writes the sendMail() result as context.data.invitationEmailSent. Missing invitation/token is 400 Invitation and one-time token are required; disabled/incomplete configuration is 500 Invitation email configuration is incomplete or disabled; delivery failure is 500 Failed to send invitation email. Used by createInvitationRoute.
createInvitationTerminator
Implementation
Throws any error result; reads context.data.invitationId and context.data.invitationEmailSent, and returns { data: { invitationId }, statusCode: 201 }. A missing or falsey value causes 500 Unknown error creating invitation. It terminates createInvitationRoute.
findInvitations
Implementation
Reads params.requestQuery, queries context.db.invitations.find(filter || {}), converts the cursor with toArray(), and writes context.data.invitations. A database exception is 500 Failed to find invitations. Used by findInvitationsRoute.
normalizeInvitationsListTerminator
Implementation
Throws the prior error result and reads context.data.invitations; it removes _id from every invitation and returns either an array or { data, metadata: { pagination: context.data.invitations.metadata } }. It terminates findInvitationsRoute.
buildCheckInvitationTokenPayload
Implementation
Infallibly writes context.data.checkToken.target as INVITATION_TARGET. Used by registerCredentialsRoute.
getInvitationIdFromTokenInfo
Implementation
Reads context.data.tokenInfo.invitationId, writes context.data.invitationId, or returns 400 Invitation ID is required. Used by registerCredentialsRoute.
getInvitationById
Implementation
Reads context.data.invitationId before params.requestParams.invitationId, queries context.db.invitations.findOne({ id: { $eq: String(invitationId) } }), and writes context.data.invitation. Missing ID is 400 Invitation ID is required, no match is 404 Invitation not found, and database failure is 500 Failed to get invitation by id. Used by createInvitationRoute, getInvitationByIdRoute, and registerCredentialsRoute.
normalizeInvitationTerminator
Implementation
Throws the prior error result, reads context.data.invitation, returns 404 Invitation not found if absent, otherwise removes _id and returns the public invitation. It terminates getInvitationByIdRoute.
verifyInvitationPayload
Implementation
Reads context.data.invitationId or params.requestParams.invitationId and context.data.tokenInfo.invitationId; matching values write isValidInvitationPayload: true, otherwise it returns 400 Invalid invitation payload. Custom composition only; no exported route composes it.
isPendingInvitation
Implementation
Reads context.data.invitation and context.configuration.invitation.status.pending with INVITATION_STATUS_PENDING as fallback; a match writes isPendingInvitation: true. A missing invitation is 400 Invitation is required; a non-pending status is 400 Invitation is not pending. Used by registerCredentialsRoute.
buildAcceptInvitationPayload
Implementation
Reads context.configuration.invitation.status.accepted with INVITATION_STATUS_ACCEPTED as fallback and writes context.data.invitation as updateBaseEntity({ acceptedAt: new Date().toISOString(), status }). It has no error branch. Used by registerCredentialsRoute.
updateInvitation
Implementation
Reads the ID from data then path and invitation data from data then body; it applies updateBaseEntity, updates by string id, and writes context.data.invitationId. A missing ID is 400 Invitation ID is required; missing/empty payload is 400 Invitation Payload is required; no match is 404 Invitation not found; no modification or database failure is 400/500 Failed to update invitation. Used by registerCredentialsRoute.
deleteInvitation
Implementation
Reads the ID from data then path, deletes by string id, and writes context.data.deleteInvitation. A missing ID is 400 Invitation ID is required; no deletion is 404 Invitation not found; a database failure is 500 Failed to delete invitation. Used by deleteInvitationRoute.
deleteInvitationTerminator
Implementation
Throws the prior error result, requires context.data.deleteInvitation, and returns { statusCode: 204 }; missing data is 500 Unknown error deleting invitation. It terminates deleteInvitationRoute.
buildInvitationOnetimeTokenPayload
Implementation
Reads context.data.invitationId and context.configuration.invitation.target; it writes context.data.target and context.data.tokenData: { invitationId }, with INVITATION_TARGET as fallback. A missing ID is 400 Invitation ID is required. Used by createInvitationRoute.