⚙️ 招待ハンドラー

招待ハンドラーは、Nodeblocksアプリケーションで招待管理操作のためのコアビジネスロジック関数を提供します。これらのハンドラーは、招待データベース操作、データ変換、レスポンスフォーマットの一般的なパターンをカプセル化します。

---

🎯 概要

招待ハンドラーは以下の目的で設計されています：

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

---

📋 招待ハンドラータイプ

招待非同期ハンドラー

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

招待同期ハンドラー

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

招待ターミネーターハンドラー

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

---

🔧 利用可能な招待ハンドラー

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;

// Use in composition
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;

// Use in composition
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;

// Use in composition
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;

// Use in composition
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;

// Use in composition
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;

// Use in composition
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;

// Use in composition
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がパラメータまたはコンテキストデータで提供されている必要があります
• context.data.tokenInfo.invitationIdが前のハンドラーから利用可能である必要があります
• 検証が成功するには両方のIDが一致する必要があります

主な機能:

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

使用例:

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

const { verifyInvitationPayload } = handlers;

// Use in composition
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;

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

---

buildAcceptInvitationPayload

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

目的: 承認ステータスと承認タイムスタンプ付きで招待データを準備

パラメータ:

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

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

ペイロード要件:

• context.configuration.invitation.status.acceptedが設定されている必要があります

主な機能:

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

使用例:

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

const { buildAcceptInvitationPayload } = handlers;

// Use in composition
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がパラメータまたはコンテキストデータで提供されている必要があります
• 招待データがリクエストボディまたはコンテキストデータで提供されている必要があります
• context.dbがデータベース操作で利用可能である必要があります

主な機能:

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

使用例:

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

const { updateInvitation } = handlers;

// Use in composition
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;

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

---

🎯 招待ターミネーターハンドラー

createInvitationTerminator

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

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

パラメータ:

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

戻り値: 201 statusCode付きのレスポンスオブジェクト

ペイロード要件:

• context.data.createInvitationが前のハンドラーから利用可能である必要があります

使用例:

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

const { createInvitationTerminator } = handlers;

// Use in composition
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;

// Use in composition
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;

// Use in composition
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;

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