📧 Invitation ハンドラーブロック

Invitation handler ブロックは、NodeBlocks アプリケーションにおける招待管理操作のためのコアビジネスロジック関数を提供します。これらのハンドラーは、招待データベース操作、データ変換、レスポンスフォーマットの共通パターンをカプセル化します。

---

🎯 概要

Invitation ハンドラーブロックは次のことを目的として設計されています:

• 再利用可能な関数で招待ビジネスロジックをカプセル化する
• 適切なエラー管理を使用して招待データベース操作を処理する
• 招待データを異なるフォーマット間で変換する
• TypeScript 統合によるタイプセーフティを確保する
• 他の招待ブロックとの合成をサポートする

---

📋 Invitation ハンドラータイプ

Invitation アシンクハンドラー

非同期の招待操作を実行する関数（データベース呼び出し、API リクエストなど）。

Invitation シンクハンドラー

同期の招待操作を実行する関数（データ変換、検証など）。

Invitation ターミネーターハンドラー

最終的な招待レスポンスをフォーマットして返す関数。

---

🔧 利用可能な Invitation ハンドラー

createInvitation

データベースに新しい招待を作成します。

目的: エンティティ管理を使用して招待の作成を処理する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • params.requestBody: 招待作成データ
  • context.db: データベース接続
  • context.configuration.invitation.status.pending: 保留ステータス設定

戻り値: Result<RouteHandlerPayload, Error> - invitationId を含む成功またはエラー

ペイロード要件:

• params.requestBody は招待データを含む必要があります
• context.db はデータベース操作のために利用可能である必要があります
• context.configuration.invitation.status.pending は設定されているべき

主要機能:

• リクエストボディが存在し、空でないことを検証
• 保留ステータスの設定を使用するか、デフォルトで 'pending' を使用
• タイムスタンプと ID を使用してベースエンティティを作成
• データベースに招待を挿入
• 成功時に invitationId を返す
• データベースエラーを適切に処理

使用例:

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

const { createInvitation } = handlers;

// 合成で使用
const invitationPipeline = compose(createInvitation, generateToken, sendEmail);

---

sendInvitationEmail

ワンタイムトークンを使用して招待メールを送信します。

目的: 招待通知のメール配信を処理する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • context.data.invitation: 前のハンドラーからの招待オブジェクト
  • context.data.token: 前のハンドラーからのワンタイムトークン
  • context.mailService: メール送信のためのメールサービス
  • context.configuration.invitation.emailConfig: メール設定
  • context.configuration.invitation.enabled: 招待が有効かどうか

戻り値: Result<RouteHandlerPayload, Error> - invitationEmailSent フラグまたはエラーでの成功

ペイロード要件:

• context.data.invitation と token は前のハンドラーから利用可能でなければならない
• context.mailService はメール送信のために利用可能である必要があります
• context.configuration.invitation は有効で適切に設定されている必要があります

主要機能:

• 招待とトークンが提供されていることを検証
• 招待メール設定が完全で有効であることを確認
• メールサービスが利用可能であることを検証
• テンプレートとトークンを使用してメール HTML を生成
• メールサービスを使用して招待メールを送信
• 成功時にメール送信結果を返す
• 設定とメール送信エラーを処理

使用例:

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

const { sendInvitationEmail } = handlers;

// 合成で使用
const invitationPipeline = compose(generateToken, sendInvitationEmail, terminator);

---

findInvitations

オプションのフィルタリングを使用して複数の招待を検索します。

目的: フィルターサポートを使用して招待のクエリを処理する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • params.requestQuery: 招待のオプションのフィルター基準
  • context.db: データベース接続

戻り値: Result<RouteHandlerPayload, Error> - 招待配列またはエラーでの成功

ペイロード要件:

• params.requestQuery はオプション - 提供された場合、MongoDB フィルターとして使用される
• context.db はデータベース操作のために利用可能である必要があります

主要機能:

• リクエストクエリからオプションのフィルターを受け入れる
• フィルターが提供されていない場合、すべての招待を返す
• 招待の配列を返す
• データベースエラーを適切に処理

使用例:

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

const { findInvitations } = handlers;

// 合成で使用
const invitationPipeline = compose(findInvitations, listTerminator);

---

buildCheckInvitationTokenPayload

ターゲット指定を使用して招待トークン検証のためのペイロードを構築します。

目的: 招待ワークフローのトークン検証を設定する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む

戻り値: Result<RouteHandlerPayload, Error> - checkToken 設定での成功

ペイロード要件:

• 特定の要件なし - このハンドラーは常に成功します

主要機能:

• checkToken 設定を招待ターゲットとマージ
• ターゲットを INVITATION_TARGET 定数に設定
• 常に成功（エラー条件なし）
• checkToken 設定で更新されたペイロードを返す
• 招待トークン検証の準備ステップとして使用

使用例:

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

const { buildCheckInvitationTokenPayload } = handlers;

// 合成で使用
const invitationPipeline = compose(buildCheckInvitationTokenPayload, checkToken);

---

buildInvitationOnetimeTokenPayload

招待ワンタイムトークン生成のためのペイロードを構築します。

目的: generateOnetimeToken ハンドラーのための招待固有のデータとリクエスト情報を準備する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • context.data.invitationId: 前のハンドラーからの招待 ID
  • context.configuration.invitation.target: 招待ターゲット設定

戻り値: Result<RouteHandlerPayload, Error> - トークンペイロードデータまたはエラーでの成功

ペイロード要件:

• context.data.invitationId は前のハンドラーから利用可能でなければならない
• context.configuration.invitation.target は設定されているべき

使用例:

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

const { buildInvitationOnetimeTokenPayload } = handlers;

// 合成で使用
const invitationPipeline = compose(createInvitation, buildInvitationOnetimeTokenPayload, generateOnetimeToken, sendEmail);

---

getInvitationIdFromTokenInfo

リクエストコンテキストのトークン情報から招待 ID を抽出します。

目的: 招待処理のためにトークンデータから invitationId を抽出する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • context.data.tokenInfo.invitationId: トークンからの招待 ID

戻り値: Result<RouteHandlerPayload, Error> - invitationId またはエラーでの成功

ペイロード要件:

• context.data.tokenInfo.invitationId は前のハンドラーから利用可能でなければならない

主要機能:

• コンテキストのトークン情報から invitationId を抽出
• invitationId が提供されていることを検証
• 成功時に invitationId を返す
• invitationId が不足している場合、400 エラーを返す
• 招待処理の準備ステップとして使用

使用例:

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

const { getInvitationIdFromTokenInfo } = handlers;

// 合成で使用
const invitationPipeline = compose(getInvitationIdFromTokenInfo, getInvitationById, isPendingInvitation);

---

getInvitationById

一意の識別子によって単一の招待を取得します。

目的: 招待 ID を使用してデータベースから招待詳細を取得する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • params.requestParams.invitationId または context.data.invitationId: 取得する招待 ID
  • context.db: データベース接続

戻り値: Result<RouteHandlerPayload, Error> - 招待オブジェクトまたはエラーでの成功

ペイロード要件:

• 招待 ID は params.requestParams.invitationId または context.data.invitationId で提供されなければならない
• context.db はデータベース操作のために利用可能である必要があります

主要機能:

• invitationId が提供されていることを検証
• データベースで ID によって招待を検索
• 見つからない場合、404 を返す
• 成功時に招待データを返す
• データベースエラーを適切に処理

使用例:

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

const { getInvitationById } = handlers;

// 合成で使用
const invitationPipeline = compose(getInvitationById, isPendingInvitation, updateInvitation);

---

verifyInvitationPayload

トークン情報を使用して招待の真正性を検証します。

目的: セキュリティのためにトークン情報に対して招待 ID を検証する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • params.requestParams.invitationId または context.data.invitationId: 検証する招待 ID
  • context.data.tokenInfo.invitationId: トークンからの招待 ID

戻り値: Result<RouteHandlerPayload, Error> - 検証された invitationId またはエラーでの成功

ペイロード要件:

• 招待 ID は params またはコンテキストデータで提供されなければならない
• context.data.tokenInfo.invitationId は前のハンドラーから利用可能でなければならない
• 両方の ID が一致しないと検証が成功しない

主要機能:

• 複数のソースから invitationId を抽出
• tokenInfo が invitationId を含んでいることを検証
• セキュリティのために invitationId をトークン invitationId と比較
• 成功時に検証フラグを返す
• ID が一致しない場合、400 エラーを返す
• 招待の真正性を確保

使用例:

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

const { verifyInvitationPayload } = handlers;

// 合成で使用
const invitationPipeline = compose(verifyInvitationPayload, getInvitationById, isPendingInvitation);

---

isPendingInvitation

招待が保留ステータスであることを検証します。

目的: ステータスをチェックすることで招待が処理可能であることを確保する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • context.data.invitation: 前のハンドラーからの招待オブジェクト
  • context.configuration.invitation.status.pending: 保留ステータス設定

戻り値: Result<RouteHandlerPayload, Error> - isPendingInvitation フラグまたはエラーでの成功

ペイロード要件:

• context.data.invitation は前のハンドラーから利用可能でなければならない
• context.configuration.invitation.status.pending は設定されているべき

主要機能:

• 招待がコンテキストで提供されていることを検証
• 保留ステータスの設定を使用するか、デフォルトで 'pending' を使用
• 招待ステータスが保留ステータスと一致することを確認
• 成功時に保留フラグを返す
• 招待が保留されていない場合、400 エラーを返す
• 招待が処理可能であることを確保

使用例:

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

const { isPendingInvitation } = handlers;

// 合成で使用
const invitationPipeline = compose(getInvitationById, isPendingInvitation, buildAcceptInvitationPayload);

---

buildAcceptInvitationPayload

更新されたステータスとタイムスタンプで招待受け入れのためのペイロードを構築します。

目的: 受け入れステータスと受け入れタイムスタンプで招待データを準備する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • context.configuration.invitation.status.accepted: 受け入れステータス設定

戻り値: Result<RouteHandlerPayload, Error> - 更新された招待データまたはエラーでの成功

ペイロード要件:

• context.configuration.invitation.status.accepted は設定されているべき

主要機能:

• 受け入れステータスの設定を使用するか、デフォルトで 'accepted' を使用
• タイムスタンプでベースエンティティを更新
• acceptedAt タイムスタンプを現在の日付に設定
• ステータスを受け入れに設定
• 成功時に更新された招待データを返す
• 受け入れワークフローのための招待を準備

使用例:

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

const { buildAcceptInvitationPayload } = handlers;

// 合成で使用
const invitationPipeline = compose(getInvitationById, isPendingInvitation, buildAcceptInvitationPayload, updateInvitation);

---

updateInvitation

検証とエラー処理を使用してデータベース内の招待データを更新します。

目的: 適切な検証を使用して招待レコードを更新する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • params.requestParams.invitationId または context.data.invitationId: 更新する招待 ID
  • params.requestBody または context.data.invitation: 更新する招待データ
  • context.db: データベース接続

戻り値: Result<RouteHandlerPayload, Error> - invitationId またはエラーでの成功

ペイロード要件:

• 招待 ID は params またはコンテキストデータで提供されなければならない
• 招待データはリクエストボディまたはコンテキストデータで提供されなければならない
• context.db はデータベース操作のために利用可能である必要があります

主要機能:

• invitationId が提供されていることを検証
• 招待データが存在し、空でないことを検証
• タイムスタンプでベースエンティティを更新
• 更新前に招待が存在することを確認
• 成功時に invitationId を返す
• 見つからない場合と更新失敗を処理
• データベースエラーを適切に処理

使用例:

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

const { updateInvitation } = handlers;

// 合成で使用
const invitationPipeline = compose(getInvitationById, isPendingInvitation, buildAcceptInvitationPayload, updateInvitation);

---

deleteInvitation

一意の識別子によってデータベースから招待を削除します。

目的: 検証を使用して招待レコードを完全に削除する

パラメーター:

• payload: RouteHandlerPayload - リクエストコンテキストとデータを含む
  • params.requestParams.invitationId または context.data.invitationId: 削除する招待 ID
  • context.db: データベース接続

戻り値: Result<RouteHandlerPayload, Error> - invitationId またはエラーでの成功

ペイロード要件:

• 招待 ID は params.requestParams.invitationId または context.data.invitationId で提供されなければならない
• context.db はデータベース操作のために利用可能である必要があります

主要機能:

• invitationId が提供されていることを検証
• データベースから ID によって招待を削除
• 見つからない場合、404 を返す
• 成功時に削除結果を返す
• データベースエラーを適切に処理

使用例:

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

const { deleteInvitation } = handlers;

// 合成で使用
const invitationPipeline = compose(getInvitationById, deleteInvitation, deleteTerminator);

---

🎯 Invitation ターミネーターハンドラー

createInvitationTerminator

適切なステータスコードで招待作成を終了します。

目的: 201 ステータスで成功した招待作成レスポンスをフォーマットする

パラメーター:

• result: Result<RouteHandlerPayload, Error> - ペイロードまたはエラーを含む結果
  • context.data.createInvitation: 前のハンドラーからの作成結果

戻り値: 201 statusCode を含むレスポンスオブジェクト

ペイロード要件:

• context.data.createInvitation は前のハンドラーから利用可能でなければならない

使用例:

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

const { createInvitationTerminator } = handlers;

// 合成で使用
const invitationPipeline = compose(createInvitation, createInvitationTerminator);

---

normalizeInvitationTerminator

データベース固有のフィールドを削除して招待データを正規化します。

目的: API レスポンスのための招待データをクリーンアップする

パラメーター:

• result: Result<RouteHandlerPayload, Error> - ペイロードまたはエラーを含む結果
  • context.data.invitation: 前のハンドラーからの招待オブジェクト

戻り値: 正規化された招待オブジェクト

ペイロード要件:

• context.data.invitation は前のハンドラーから利用可能でなければならない

使用例:

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

const { normalizeInvitationTerminator } = handlers;

// 合成で使用
const invitationPipeline = compose(getInvitationById, normalizeInvitationTerminator);

---

normalizeInvitationsListTerminator

各アイテムからデータベース固有のフィールドを削除して招待リストを正規化します。

目的: API レスポンスのための招待配列データをクリーンアップする

パラメーター:

• result: Result<RouteHandlerPayload, Error> - ペイロードまたはエラーを含む結果
  • context.data.invitations: 前のハンドラーからの招待オブジェクトの配列

戻り値: 正規化された招待オブジェクトの配列

ペイロード要件:

• context.data.invitations は前のハンドラーから利用可能でなければならない

使用方法:

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

const { normalizeInvitationsListTerminator } = handlers;

// 合成で使用
const invitationPipeline = compose(findInvitations, normalizeInvitationsListTerminator);

---

deleteInvitationTerminator

適切なステータスコードで招待削除を終了します。

目的: 204 ステータスで成功した削除レスポンスをフォーマットする

パラメーター:

• result: Result<RouteHandlerPayload, Error> - ペイロードまたはエラーを含む結果
  • context.data.deleteInvitation: 前のハンドラーからの削除結果

戻り値: 204 statusCode を含むレスポンスオブジェクト

ペイロード要件:

• context.data.deleteInvitation は前のハンドラーから利用可能でなければならない

使用方法:

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

const { deleteInvitationTerminator } = handlers;

// 合成で使用
const invitationPipeline = compose(deleteInvitation, deleteInvitationTerminator);