📧 招待ハンドラーブロック

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

---

🎯 概要

招待ハンドラーブロックは以下を目的として設計されています：

• 再利用可能な機能での招待ビジネスロジックのカプセル化
• 適切なエラー管理による招待データベース操作の処理
• 異なるフォーマット間での招待データの変換
• TypeScript統合による型安全性の確保
• 他の招待ブロックとのコンポジションのサポート

---

📋 招待ハンドラー種類

招待非同期ハンドラー

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

招待同期ハンドラー

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

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

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

---

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

createInvitation

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

目的: エンティティ管理による招待の作成を処理

使用方法:

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

const { createInvitation } = handlers;

// コンポジションで使用
const invitationPipeline = compose(createInvitation, generateToken, sendEmail);

---

sendInvitationEmail

ワンタイムトークン付き招待メールを送信します。

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

使用方法:

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

const { sendInvitationEmail } = handlers;

// コンポジションで使用
const invitationPipeline = compose(generateToken, sendInvitationEmail, terminator);

---

findInvitations

オプションのフィルタリング付きで複数の招待を検索します。

目的: フィルタサポート付き招待のクエリを処理

使用方法:

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);

---

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;

// コンポジションで使用
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);

---

getInvitationById

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

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

使用方法:

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

const { getInvitationById } = handlers;

// コンポジションで使用
const invitationPipeline = compose(getInvitationById, isPendingInvitation, updateInvitation);

---

updateInvitation

検証とエラー処理によるデータベース内の招待データを更新します。

目的: 適切な検証による招待レコードの更新

使用方法:

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

const { updateInvitation } = handlers;

// コンポジションで使用
const invitationPipeline = compose(getInvitationById, isPendingInvitation, buildAcceptInvitationPayload, updateInvitation);

---

deleteInvitation

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

目的: 検証による招待レコードの永続的削除

使用方法:

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

const { deleteInvitation } = handlers;

// コンポジションで使用
const invitationPipeline = compose(getInvitationById, deleteInvitation, deleteTerminator);

---

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

createInvitationTerminator

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

目的: 201ステータスによる招待作成成功レスポンスのフォーマット

使用方法:

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

const { createInvitationTerminator } = handlers;

// コンポジションで使用
const invitationPipeline = compose(createInvitation, createInvitationTerminator);

---

normalizeInvitationTerminator

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

目的: APIレスポンス用招待データのクリーニング

使用方法:

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

const { normalizeInvitationTerminator } = handlers;

// コンポジションで使用
const invitationPipeline = compose(getInvitationById, normalizeInvitationTerminator);

---

normalizeInvitationsListTerminator

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

目的: APIレスポンス用招待配列データのクリーニング

使用方法:

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

const { normalizeInvitationsListTerminator } = handlers;

// コンポジションで使用
const invitationPipeline = compose(findInvitations, normalizeInvitationsListTerminator);

---

deleteInvitationTerminator

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

目的: 204ステータスによる削除成功レスポンスのフォーマット

使用方法:

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

const { deleteInvitationTerminator } = handlers;

// コンポジションで使用
const invitationPipeline = compose(deleteInvitation, deleteInvitationTerminator);

---

🔗 関連ドキュメント

• 招待スキーマブロック - 招待データ検証と契約
• 招待ルートブロック - 招待HTTPエンドポイント定義
• 招待フィーチャーブロック - 招待コンポーズド機能