🛣️ Invitation routes

Invitation routes are SDK composers, not Express middleware. Each route invokes isAuthenticated() and checkIdentityType(['admin']).

Inventory

Route	Method / protocol	Path	Schema	Validators	Success status
createInvitationRoute	POST / HTTP	/invitations	createInvitationSchema	isAuthenticated(), checkIdentityType(['admin'])	201
findInvitationsRoute	GET / HTTP	/invitations	findInvitationsSchema	isAuthenticated(), checkIdentityType(['admin'])	200
getInvitationByIdRoute	GET / HTTP	/invitations/:invitationId	getInvitationSchema	isAuthenticated(), checkIdentityType(['admin'])	200
deleteInvitationRoute	DELETE / HTTP	/invitations/:invitationId	deleteInvitationSchema	isAuthenticated(), checkIdentityType(['admin'])	204

Details

createInvitationRoute

Implementation

Endpoint: POST /invitations

Creates an invitation, generates its one-time token, and sends its email for an authenticated administrator.

Access: Authenticated administrator. The factories execute in source order: isAuthenticated(), then checkIdentityType(['admin']). The selected context.authenticate adapter reads a Bearer token by default; authService selects cookie authentication only for authMode: 'cookie'.

Request: createInvitationSchema requires an application/json body with email-formatted email and string fromIdentityId; optional orgId and role are the only additional fields because the body schema is strict. Access needs the selected Bearer header or accessToken cookie. mailService and enabled, complete invitation mail configuration are runtime requirements.

Pipeline: createInvitation → getInvitationById → buildInvitationOnetimeTokenPayload → generateOnetimeToken → sendInvitationEmail → createInvitationTerminator, all logged.

Success: 201 { invitationId }.

Failure: Source-defined failures include 400 missing body, failed invitation insertion, missing invitation ID/token, or missing invitation/token for delivery; 404 when the just-created invitation cannot be retrieved; and 500 database, token, mail-configuration, delivery, or creation-terminator failures. The shared validator contracts also determine authentication/authorization failures.

View complete source

export const createInvitationRoute = withRoute({
  handler: compose(
    withLogging(createInvitation),
    flatMapAsync(withLogging(getInvitationById)),
    flatMapAsync(withLogging(buildInvitationOnetimeTokenPayload)),
    flatMapAsync(withLogging(generateOnetimeToken)),
    flatMapAsync(withLogging(sendInvitationEmail)),
    lift(withLogging(createInvitationTerminator)),
  ),
  method: 'POST',
  path: '/invitations',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});

findInvitationsRoute

Implementation

Endpoint: GET /invitations

Lists invitations for an authenticated administrator and removes the database-only _id field from every returned item.

Access: Authenticated administrator. The factories execute in source order: isAuthenticated(), then checkIdentityType(['admin']); the selected adapter accepts Bearer by default or the cookie transport selected by authService.

Request: findInvitationsSchema accepts optional query email, fromIdentityId, orgId, role, page (1–1000), and limit (1–50), plus the selected access-token transport. It defines no request body or path parameters.

Pipeline: findInvitations with pagination → normalizeInvitationsListTerminator.

Success: 200 by the service’s ordinary res.json(result) path: either a normalized array or { data, metadata: { pagination } }, with _id removed. withPagination supplies the paginated result consumed by the terminator.

Failure: 500 Failed to find invitations plus shared validation failures.

View complete source

export const findInvitationsRoute = withRoute({
  handler: compose(withPagination(withLogging(findInvitations)), lift(withLogging(normalizeInvitationsListTerminator))),
  method: 'GET',
  path: '/invitations',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});

getInvitationByIdRoute

Implementation

Endpoint: GET /invitations/:invitationId

Retrieves one invitation for an authenticated administrator and returns its public shape without _id.

Access: Authenticated administrator. The factories execute in source order: isAuthenticated(), then checkIdentityType(['admin']); the selected adapter accepts Bearer by default or the cookie transport selected by authService.

Request: getInvitationSchema requires the string path parameter invitationId and the selected access-token transport. It defines no request body or query parameters.

Pipeline: getInvitationById → normalizeInvitationTerminator.

Success: 200 by the service’s ordinary res.json(result) path, with the invitation’s _id removed.

Failure: 400 Invitation ID is required, 404 Invitation not found from retrieval or normalization, and 500 Failed to get invitation by id, plus shared validator failures.

View complete source

export const getInvitationByIdRoute = withRoute({
  handler: compose(withLogging(getInvitationById), lift(withLogging(normalizeInvitationTerminator))),
  method: 'GET',
  path: '/invitations/:invitationId',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});

deleteInvitationRoute

Implementation

Endpoint: DELETE /invitations/:invitationId

Deletes one invitation for an authenticated administrator and returns the explicit empty 204 response descriptor.

Access: Authenticated administrator. The factories execute in source order: isAuthenticated(), then checkIdentityType(['admin']); the selected adapter accepts Bearer by default or the cookie transport selected by authService.

Request: deleteInvitationSchema requires the string path parameter invitationId and the selected access-token transport. It defines no request body or query parameters.

Pipeline: deleteInvitation → deleteInvitationTerminator.

Success: 204 with no body.

Failure: 400 Invitation ID is required, 404 Invitation not found, 500 Failed to delete invitation, or 500 Unknown error deleting invitation from the terminator, plus shared validator failures.

View complete source

export const deleteInvitationRoute = withRoute({
  handler: compose(withLogging(deleteInvitation), lift(withLogging(deleteInvitationTerminator))),
  method: 'DELETE',
  path: '/invitations/:invitationId',
  validators: [isAuthenticated(), checkIdentityType(['admin'])],
});