バージョン: 0.9.0 (最新)

🛣️ チャットルート

チャットルートは、Nodeblocksアプリケーションでチャット管理操作の事前設定されたHTTPエンドポイントを提供します。これらのルートは、ハンドラー、バリデーター、ミドルウェアを組み合わせて、適切な認証、認可、エラーハンドリングを備えた完全なAPIエンドポイントを作成します。

🎯 概要

チャットルートは以下の目的で設計されています：

完全なAPIエンドポイントの提供 - チャット管理操作用
セキュアな操作のためのハンドラーとバリデーターの組み合わせ - セキュリティ
認証と認可チェックの含まれる - アクセス制御
関数型合成パターンのサポート - 構成可能性
ログとエラー管理の自動処理 - 運用性

📋 ルート構造

各チャットルートは一貫したパターンに従います：

HTTP Method: 操作タイプを定義（GET、POST、PATCH、DELETE）
Path: パラメータ付きエンドポイントURLを指定
ハンドラー: ビジネスロジック用の構成された関数チェーン
バリデーター: 認証と認可チェック

🔧 利用可能なチャットルート

チャネルルート

`createChatChannelRoute`

新しいチャネルを作成し、作成されたリソースを返します。

目的: 完全なリソース取得を含むチャネル作成を処理

ルート詳細:

Method: POST
Path: /channels
認証: Required (Bearer token)

ハンドラー: createChatChannel, getChatChannelById, createChatChannelTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestBody', 'ownerId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.createChatChannelRoute);

`findChatChannelsRoute`

正規化されたリスト形式ですべてのチャネルを取得します。

目的: ページネーション付きでチャネルをリスト

ルート詳細:

Method: GET
Path: /channels
認証: Required (Bearer token)

ハンドラー: findChatChannels, normalizeChatChannelsListTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestQuery', 'ownerId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.findChatChannelsRoute);

`getChatChannelRoute`

IDで特定のチャネルを取得します。

目的: チャネルデータを取得

ルート詳細:

Method: GET
Path: /channels/:channelId
認証: Required (Bearer token)

ハンドラー: getChatChannelById, normalizeChatChannelTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), ownsChannel(['params', 'requestParams', 'channelId']), hasSubscription(['params', 'requestParams', 'channelId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.getChatChannelRoute);

`updateChatChannelRoute`

既存のチャネルを更新し、更新されたリソースを返します。

目的: アクセス制御付きでチャネルデータを変更

ルート詳細:

Method: PATCH
Path: /channels/:channelId
認証: Required (Bearer token)

ハンドラー: updateChatChannel, getChatChannelById, normalizeChatChannelTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), ownsChannel(['params', 'requestParams', 'channelId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.updateChatChannelRoute);

`deleteChatChannelRoute`

IDでチャネルを削除します。

目的: アクセス制御付きでチャネルを削除

ルート詳細:

Method: DELETE
Path: /channels/:channelId
認証: Required (Bearer token)

ハンドラー: deleteChatChannel, deleteChatChannelTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), ownsChannel(['params', 'requestParams', 'channelId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.deleteChatChannelRoute);

`getChannelMessagesRoute`

GET /channels/:channelId/messages経由で特定チャネルのすべてのチャットメッセージを取得します。

目的: ページネーションサポート付きで特定チャネルに属するすべてのメッセージを取得

ルート詳細:

Method: GET
Path: /channels/:channelId/messages
認証: Required (Bearer token)

ブロック: getChannelMessagesByChannelId

ターミネーター: orThrowによる組み込み成功/エラーマッピング（200ステータスコード）

バリデーター:

isAuthenticated - ユーザーが認証されていることを確保
channelExists - channelIdによるチャネルの存在をチェック
hasSubscription - ユーザーのチャネルへのサブスクリプションをチェック

レスポンス (200 OK): メッセージオブジェクトの配列

エラーレスポンス:

401: ユーザーが認証されていません
403: ユーザーがチャネルにサブスクライブされていません
404: チャネルが存在しません
500: データベース操作が失敗しました

ハンドラープロセス:

ユーザー認証とチャネルサブスクリプションをバリデーション
指定されたチャネルのすべてのメッセージを取得
クエリパラメータが提供されている場合はページネーションを適用
200ステータスでメッセージ配列を返す

使用例:

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

// Register route with Express app
app.use('/api', routes.getChannelMessagesRoute);

// Client usage:
const response = await fetch('/api/channels/channel-123/messages', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

if (response.ok) {
  const messages = await response.json();
  console.log('Channel messages:', messages);
}

`getChatChannelIconUploadUrlRoute`

GET /channels/:channelId/icon-upload-url経由でチャットチャネルアイコン用の署名付きアップロードURLを生成します。

目的: 適切な認証と認可を備えたチャットチャネルアイコン画像のアップロード用の事前署名付きURLを提供します。

ルート詳細:

Method: GET
Path: /channels/:channelId/icon-upload-url
認証: Required (Bearer token)

ブロック: generateChatChannelIconUploadUrl ターミネーター: orThrowによる組み込み成功/エラーマッピング（200ステータスコード）

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), ownsChannel(['params', 'requestParams', 'channelId']))

レスポンス (200 OK):

{
  "objectId": "string",
  "url": "string"
}

クエリパラメータ:

contentType: string - アップロードするファイルのMIMEタイプ（例: 'image/png'）
contentLength: number - バイト単位のファイルサイズ（最大10MB）

エラーレスポンス:

400 Bad Request: 無効なクエリパラメータ（ファイルサイズが大きすぎる、無効なコンテンツタイプ）
401 Unauthorized: 認証失敗
403 Forbidden: ユーザーに管理者権限がなく、チャネルを所有していない
500 Internal Server Error: ファイルストレージサービスエラー

ハンドラープロセス:

認証と認可をバリデーション（管理者またはチャネル所有者）
クエリパラメータをバリデーション（contentType、contentLength）
ファイル拡張子付きUUID objectIdを生成
ファイルストレージドライバーを使用して署名付きアップロードURLを作成
アップロード用のobjectIdと署名付きURLを返す

認可に関する注意事項:

認証が必要
管理者またはチャネル所有者がアクセス可能
someバリデーターを使用して管理者アクセスまたはチャネル所有権のいずれかを許可

使用例:

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

// Register route with Express app
app.use('/api', routes.getChatChannelIconUploadUrlRoute);

// Client usage:
const response = await fetch('/api/channels/channel-123/icon-upload-url?contentType=image/png&contentLength=1024000', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

if (response.ok) {
  const { objectId, url } = await response.json();
  // Use url to upload the file
  // Store objectId for later reference
}

サブスクリプションルート

`createChatSubscriptionRoute`

新しいサブスクリプションを作成し、作成されたリソースを返します。

目的: 完全なリソース取得を含むサブスクリプション作成を処理

ルート詳細:

Method: POST
Path: /subscriptions
認証: Required (Bearer token)

ハンドラー: createChatSubscription, getChatSubscriptionById, createChatSubscriptionTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestBody', 'subscribedId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.createChatSubscriptionRoute);

`findChatSubscriptionsRoute`

正規化されたリスト形式ですべてのサブスクリプションを取得します。

目的: ページネーション付きでサブスクリプションをリスト

ルート詳細:

Method: GET
Path: /subscriptions
認証: Required (Bearer token)

ハンドラー: findChatSubscriptions, normalizeChatSubscriptionsListTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), hasSubscription(['params', 'requestQuery', 'channelId']), ownsChannel(['params', 'requestQuery', 'channelId']), isSelf(['params', 'requestQuery', 'subscribedId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.findChatSubscriptionsRoute);

`getChatSubscriptionRoute`

IDで特定のサブスクリプションを取得します。

目的: サブスクリプションデータを取得

ルート詳細:

Method: GET
Path: /subscriptions/:subscriptionId
認証: Required (Bearer token)

ハンドラー: getChatSubscriptionById, normalizeChatSubscriptionTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), ownsSubscription(['params', 'requestParams', 'subscriptionId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.getChatSubscriptionRoute);

`deleteChatSubscriptionRoute`

IDでサブスクリプションを削除します。

目的: サブスクリプションを削除

ルート詳細:

Method: DELETE
Path: /subscriptions/:subscriptionId
認証: Required (Bearer token)

ハンドラー: deleteChatSubscription, deleteChatSubscriptionTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), ownsSubscription(['params', 'requestParams', 'subscriptionId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.deleteChatSubscriptionRoute);

メッセージルート

`createChatMessageRoute`

新しいメッセージを作成し、作成されたリソースを返します。

目的: 完全なリソース取得を含むメッセージ作成を処理

ルート詳細:

Method: POST
Path: /messages
認証: Required (Bearer token)

ハンドラー: createChatMessage, getChatMessageById, createChatMessageTerminator

バリデーター: isAuthenticated, isSelf(['params', 'requestBody', 'senderId']), hasSubscription(['params', 'requestBody', 'channelId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.createChatMessageRoute);

`findChatMessagesRoute`

正規化されたリスト形式ですべてのメッセージを取得します。

目的: ページネーション付きでメッセージをリスト

ルート詳細:

Method: GET
Path: /messages
認証: Required (Bearer token)

ハンドラー: findChatMessages, normalizeChatMessagesListTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), hasSubscription(['params', 'requestQuery', 'channelId']), isSelf(['params', 'requestQuery', 'senderId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.findChatMessagesRoute);

`getChatMessageRoute`

IDで特定のメッセージを取得します。

目的: メッセージデータを取得

ルート詳細:

Method: GET
Path: /messages/:messageId
認証: Required (Bearer token)

ハンドラー: getChatMessageById, normalizeChatMessageTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), ownsMessage(['params', 'requestParams', 'messageId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.getChatMessageRoute);

`updateChatMessageRoute`

既存のメッセージを更新し、更新されたリソースを返します。

目的: 所有者のみのアクセス制御付きでメッセージデータを変更

ルート詳細:

Method: PATCH
Path: /messages/:messageId
認証: Required (Bearer token)

ハンドラー: updateChatMessage, getChatMessageById, normalizeChatMessageTerminator

バリデーター: isAuthenticated, ownsMessage(['params', 'requestParams', 'messageId'])

使用例:

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

// Register route with Express app
app.use('/api', routes.updateChatMessageRoute);

`deleteChatMessageRoute`

IDでメッセージを削除します。

目的: アクセス制御付きでメッセージを削除

ルート詳細:

Method: DELETE
Path: /messages/:messageId
認証: Required (Bearer token)

ハンドラー: deleteChatMessage, deleteChatMessageTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), ownsMessage(['params', 'requestParams', 'messageId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.deleteChatMessageRoute);

`getChatMessageAttachmentUploadUrlRoute`

GET /messages/:messageId/attachment-upload-url経由でチャットメッセージ添付用のファイルアップロードURLを生成します。

目的: チャットメッセージへの添付ファイルのアップロード用のセキュアで時間制限付きURLを提供

ルート詳細:

Method: GET
Path: /messages/:messageId/attachment-upload-url
認証: Required (Bearer token)

ブロック: generateChatMessageAttachmentUploadUrl

ターミネーター: orThrow

バリデーター: isAuthenticated, ownsMessage

クエリパラメータ:

contentType: string (required) - アップロードするファイルのMIMEタイプ（安全なタイプに対してバリデーション）
contentLength: integer (required) - バイト単位のファイルサイズ（最大10MB）

レスポンス: objectIdと署名付きアップロードURLを持つオブジェクト

レスポンス構造:

{
  objectId: string;  // Unique identifier for the uploaded file
  url: string;       // Pre-signed URL for uploading the file
}

エラーレスポンス:

400 - 無効なコンテンツタイプまたはファイルサイズが制限を超えています
401 - 認証されていません
403 - このメッセージにアップロードする権限がありません
500 - FileStorageServiceErrorまたはChatMessageBlockError

ハンドラープロセス:

認証とメッセージ所有権をバリデーション
スキーマ経由でコンテンツタイプとサイズをバリデーション
一意のobject IDを生成
適切なファイル拡張子付きで署名付きアップロードURLを作成
クライアントにobjectIdとURLを返す

使用例:

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

// Register route with Express app
app.use('/api', routes.getChatMessageAttachmentUploadUrlRoute);

// Client-side request:
const messageId = 'message123';
const response = await fetch(
  `/api/messages/${messageId}/attachment-upload-url?contentType=image/png&contentLength=1000000`,
  {
    headers: {
      'Authorization': 'Bearer <token>'
    }
  }
);

const { objectId, url } = await response.json();

// Upload file to signed URL
await fetch(url, {
  method: 'PUT',
  headers: {
    'Content-Type': 'image/png'
  },
  body: fileData
});

// Store objectId with message for later retrieval

セキュリティ機能:

危険なMIMEタイプを除外（実行可能ファイル、スクリプト、アーカイブ）
ファイルサイズ制限を強制（最大10MB）
メッセージ所有権バリデーションが必要
時間制限付き署名付きURL

`createChatMessageAttachmentRoute`

POST /messages/:messageId/attachments経由で新しいチャットメッセージ添付を作成します。

目的: バリデーションと自動エンティティ生成を含む既存メッセージへのファイル添付の追加

ルート詳細:

Method: POST
Path: /messages/:messageId/attachments
認証: Required (Bearer token)

ブロック: createChatMessageAttachment, getChatMessageAttachmentById

ターミネーター: orThrow

バリデーター: isAuthenticated, ownsMessage

リクエストボディ:

{
  "objectId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "image/png"
}

レスポンス: ベースエンティティフィールド付きで作成された添付（ステータス201）

レスポンス構造:

{
  objectId: string;  // UUID reference to uploaded file
  type: string;      // MIME type
  id: string;        // Generated attachment ID
  createdAt: string; // ISO datetime
  updatedAt: string; // ISO datetime
}

エラーレスポンス:

400 - 無効なリクエストボディ（objectIdまたはtypeが欠落）
401 - 認証されていません
403 - このメッセージを変更する権限がありません
404 - メッセージが見つからないか、添付が見つかりません
500 - ChatMessageUnexpectedDBErrorまたはChatMessageBlockError

ハンドラープロセス:

認証とメッセージ所有権をバリデーション
スキーマ経由でobjectId（UUID）とtypeをバリデーション
ベースエンティティフィールド付きで添付を作成
メッセージのattachments配列に添付をプッシュ
作成された添付を取得して返す

使用例:

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

// Register route with Express app
app.use('/api', routes.createChatMessageAttachmentRoute);

// Client-side request:
const response = await fetch(`/api/messages/${messageId}/attachments`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    objectId: '550e8400-e29b-41d4-a716-446655440000',
    type: 'image/png'
  })
});

const attachment = await response.json();
// attachment has id, createdAt, updatedAt fields

主な機能:

添付用の自動ベースエンティティフィールド生成
メッセージ所有権バリデーション
アトミックMongoDB $push操作
生成されたフィールド付きで完全な添付を返す
すべての失敗シナリオに対する完全なエラーハンドリング

`deleteChatMessageAttachmentRoute`

DELETE /messages/:messageId/attachments/:attachmentId経由でチャットメッセージ添付を削除します。

目的: 既存メッセージからファイル添付を削除し、ストレージからも削除

ルート詳細:

Method: DELETE
Path: /messages/:messageId/attachments/:attachmentId
認証: Required (Bearer token)

ブロック: deleteChatMessageAttachment

ターミネーター: orThrow

バリデーター: isAuthenticated, some (checks checkIdentityType for admin OR ownsMessage)

レスポンス: 成功時にコンテンツなし（ステータス204）

エラーレスポンス:

401 - 認証されていません
403 - このメッセージを変更する権限がありません（管理者または所有者ではない）
404 - メッセージが見つからないか、添付が見つかりません
500 - ChatMessageUnexpectedDBError、ChatMessageBlockError、またはFileStorageServiceError

ハンドラープロセス:

認証と認可をバリデーション（管理者またはメッセージ所有者）
スキーマ経由でmessageIdとattachmentIdをバリデーション
$pullを使用してメッセージのattachments配列から添付を削除
メッセージのupdatedAtタイムスタンプを更新
ストレージから物理ファイルを削除
成功時に204 No Contentを返す

使用例:

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

// Register route with Express app
app.use('/api', routes.deleteChatMessageAttachmentRoute);

// Client-side request:
const response = await fetch(`/api/messages/${messageId}/attachments/${attachmentId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer <token>'
  }
});

// response.status === 204 on success

主な機能:

アトミックMongoDB $pull操作
更新前にドキュメントを返して添付の詳細を取得
objectIdとtypeを使用してストレージから物理ファイルを削除
自動メッセージタイムスタンプ更新
管理者または所有者の認可チェック
すべての失敗シナリオに対する完全なエラーハンドリング

`streamChatMessagesRoute`

WebSocketで/messages/listen経由でリアルタイムでチャットメッセージをストリーミングします。

目的: WebSocketとMongoDB変更ストリームを使用してクライアントへのリアルタイムメッセージストリーミングを有効化

ルート詳細:

Method: WebSocket (implicit)
Path: /messages/listen
Protocol: ws
認証: 現在無効（TODO: WebSocket IPアドレス形式が修正されたら有効化）

ハンドラー: streamChatMessages, normalizeChatMessageStream

バリデーター: WebSocket IPアドレス形式の問題により現在コメントアウトされています：

isAuthenticated() - Bearerトークン認証をバリデーションします
hasSubscription(['params', 'requestQuery', 'channelId']) - ユーザーがチャネルにサブスクライブされていることを確認します

クエリパラメータ:

channelId: string (required) - メッセージをストリーミングするチャネルID

レスポンス: 作成されるときに正規化されたチャットメッセージのストリーム

使用例:

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

// Register route with Express app
app.use('/api', routes.streamChatMessagesRoute);

// Client-side WebSocket connection:
const ws = new WebSocket('ws://localhost:3000/api/messages/listen?channelId=channel123');

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('New message:', message);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('WebSocket connection closed');
};

WebSocketフロー:

クライアントがchannelIdクエリパラメータ付きでWebSocket接続を確立
サーバーがchannelIdの存在をバリデーション（スキーマバリデーション）
サーバーが指定されたチャネル用のMongoDB変更ストリームを作成
サーバーが各新しいメッセージを正規化（_idフィールドを削除）
サーバーがリアルタイムで正規化されたメッセージをクライアントにストリーミング
クライアントが切断するかエラーが発生するまで接続が開いたまま

エラーハンドリング:

400: channelIdパラメータが欠落または無効
500: MongoDB変更ストリームの作成に失敗

注意事項:

新しいメッセージのみをストリーミング（挿入操作）
メッセージは送信前に正規化される（MongoDB _idフィールドが削除される）
WebSocket IP形式の修正待ちで認証バリデーターが現在無効化されている

メッセージテンプレートルート

`createChatMessageTemplateRoute`

新しいチャットメッセージテンプレートを作成し、作成されたリソースを返します。

目的: 完全なリソース取得を含むメッセージテンプレート作成を処理

ルート詳細:

Method: POST
Path: /message-templates
認証: Required (Bearer token)

ハンドラー: createChatMessageTemplate, getChatMessageTemplateById, orThrow

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), hasOrgRole(['owner','admin'], ['params','requestBody','organizationId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.createChatMessageTemplateRoute);

`getChatMessageTemplateRoute`

IDでチャットメッセージテンプレートを取得します。

目的: 組織アクセス制御付きでテンプレートデータを取得

ルート詳細:

Method: GET
Path: /message-templates/:messageTemplateId
認証: Required (Bearer token)

ハンドラー: getChatMessageTemplateById, orThrow

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), hasOrganizationAccessToMessageTemplate(['owner','admin'], ['params','requestParams','messageTemplateId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.getChatMessageTemplateRoute);

`updateChatMessageTemplateRoute`

PATCH /message-templates/:messageTemplateId経由で既存のチャットメッセージテンプレートを更新します。

目的: 組織アクセス制御とバリデーションを含む既存メッセージテンプレートの変更

ルート詳細:

Method: PATCH
Path: /message-templates/:messageTemplateId
認証: Required (Bearer token)

ハンドラー: updateChatMessageTemplate, getChatMessageTemplateById, orThrow

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), hasOrganizationAccessToMessageTemplate(['owner','admin'], ['params','requestParams','messageTemplateId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.updateChatMessageTemplateRoute);

`deleteChatMessageTemplateRoute`

DELETE /message-templates/:messageTemplateId経由でチャットメッセージテンプレートを削除します。

目的: 組織アクセス制御とバリデーションを含む既存メッセージテンプレートの削除。

ルート詳細:

Method: DELETE
Path: /message-templates/:messageTemplateId
認証: Required (Bearer token)

ハンドラー: deleteChatMessageTemplate, orThrow

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), hasOrganizationAccessToMessageTemplate(['owner','admin'], ['params','requestParams','messageTemplateId']))

使用例:

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

// Register route with Express app
app.use('/api', routes.deleteChatMessageTemplateRoute);

レスポンス (204 No Content):

{}

エラーレスポンス:

401: Unauthorized - 無効または欠落している認証トークン
403: Forbidden - ユーザーにこのメッセージテンプレートを削除する権限がありません
404: Not Found - メッセージテンプレートが存在しません
500: Internal Server Error - データベース操作が失敗しました

主な機能:

Authorization Control: テンプレート所有者、組織管理者、またはシステム管理者へのアクセスを制限
Safe Deletion: 削除前にテンプレートの存在をバリデーション
Atomic Operations: MongoDBアトミック削除操作を使用
Comprehensive Error Handling: 異なる失敗シナリオに対する特定のエラーレスポンス

`findChatMessageTemplatesRoute`

GET /message-templates経由でチャットメッセージテンプレートをリストします。

目的: データ正規化と管理者専用アクセス制御を含むページネーション付きチャットメッセージテンプレートの取得

ルート詳細:

Method: GET
Path: /message-templates
認証: Required (Bearer token)
認可: Admin only (checkIdentityType(['admin']))

ハンドラー: findChatMessageTemplates, normalizeDocuments, orThrow

バリデーター: isAuthenticated, checkIdentityType(['admin'])

クエリパラメータ:

Parameter	Type	Required	Default	Description
`page`	number	❌	1	Page number for pagination
`limit`	number	❌	10	Number of templates per page

使用例:

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

// Register route with Express app
app.use('/api', routes.findChatMessageTemplatesRoute);

レスポンス (200 - 成功):

{
  "data": [
    {
      "id": "template-123",
      "title": "Welcome Message",
      "content": "Hello, welcome to our chat!",
      "organizationId": "org-456",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "metadata": {
    "pagination": {
      "hasNext": false,
      "hasPrev": false,
      "limit": 10,
      "page": 1,
      "total": 1,
      "totalPages": 1
    }
  }
}

エラーレスポンス:

401: Unauthorized - 無効または欠落している認証トークン
403: Forbidden - ユーザーが管理者ではありません
404: Not Found - テンプレートが見つかりません（空の配列を返す）
500: Internal Server Error - データベースまたは正規化エラー

主な機能:

Pagination Support: メタデータ付きの完全なページネーション
Data Normalization: normalizeDocuments経由の自動ドキュメント正規化
Admin Access Control: 管理者ユーザーのみに制限
Flexible Filtering: MongoDBスタイルのクエリフィルターをサポート
Comprehensive Error Handling: 異なるシナリオに対する特定のエラーレスポンス

`findChatMessageTemplatesForOrganizationRoute`

GET /organizations/:organizationId/message-templates経由で特定組織のチャットメッセージテンプレートを取得します。

目的: 適切な認可制御とデータ正規化を含むメッセージテンプレートへの組織スコープ付きアクセスの提供

ルート詳細:

Method: GET
Path: /organizations/:organizationId/message-templates
認証: Required (Bearer token)
認可: Organization role-based (hasOrgRole(['owner', 'admin']))

ハンドラー: buildFilterToGetChatMessageTemplatesByOrganizationId, findChatMessageTemplates, normalizeDocuments, orThrow

バリデーター: isAuthenticated, hasOrgRole(['owner', 'admin'], ['params', 'requestParams', 'organizationId'])

クエリパラメータ:

Parameter	Type	Required	Default	Description
`page`	number	❌	1	Page number for pagination
`limit`	number	❌	10	Number of templates per page

使用例:

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

// Register route with Express app
app.use('/api', routes.findChatMessageTemplatesForOrganizationRoute);

レスポンス (200 - 成功):

{
  "data": [
    {
      "id": "template-123",
      "title": "Welcome Message",
      "content": "Hello, welcome to our organization!",
      "organizationId": "org-456",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "metadata": {
    "pagination": {
      "hasNext": false,
      "hasPrev": false,
      "limit": 10,
      "page": 1,
      "total": 1,
      "totalPages": 1
    }
  }
}

エラーレスポンス:

401: Unauthorized - 無効または欠落している認証トークン
403: Forbidden - ユーザーに組織アクセスがないか、ロール権限が不足しています
404: Not Found - 組織が見つからないか、テンプレートが利用できません
500: Internal Server Error - データベースまたは正規化エラー

主な機能:

Organization Scoping: テンプレートは組織IDで自動的にフィルタリングされる
Role-Based Authorization: 組織所有者と管理者へのアクセスを制限
Pagination Support: 大きなテンプレートコレクション用のメタデータ付き完全なページネーション
Data Normalization: クリーンなAPIレスポンス用の自動ドキュメント正規化
Secure Access Control: 適切な権限を確保する多層バリデーション

`upsertChatChannelReadStateRoute`

PUT /channels/:channelId/read-state経由でチャットチャネル読み取り状態をアップサートまたは作成します。

目的: ユーザーがチャネルで最後に読み取ったメッセージを追跡する読み取り状態レコードの作成または更新

ルート詳細:

Method: PUT
Path: /channels/:channelId/read-state
認証: Required (Bearer token)

ブロック:

buildChatChannelReadStateQuery - 既存の読み取り状態を見つけるためのクエリを構築
findChatChannelReadStates - 既存の読み取り状態レコードを見つける
buildLastReadMessageQuery - 最後に読み取ったメッセージを見つけるためのクエリを構築
findChatMessages - 最後に読み取ったメッセージを見つける
buildCreateChatChannelReadStatePayload - 作成用のペイロードを構築
buildUpdateChatChannelReadStatePayload - 更新用のペイロードを構築
createChatChannelReadState - 新しい読み取り状態を作成
updateChatChannelReadState - 既存の読み取り状態を更新

ターミネーター: orThrowによる組み込み成功/エラーマッピング（204ステータスコード）

バリデーター:

isAuthenticated - ユーザーが認証されていることを確保
channelExists - channelIdによるチャネルの存在をチェック
hasSubscription - ユーザーのチャネルへのサブスクリプションをチェック

リクエストボディ:

{
  identityId: string;          // required - user identity ID
  lastReadMessageId: string;   // required - last read message ID
}

レスポンス (204 No Content): 成功時に空のレスポンスボディ

エラーレスポンス:

401: ユーザーが認証されていません
403: ユーザーがチャネルにサブスクライブされていないか、identityIdが認証されたユーザーと一致しません
404: チャネルが存在しないか、最後に読み取ったメッセージが見つかりません
500: データベース操作が失敗しました

ハンドラープロセス:

チャネルとアイデンティティの既存の読み取り状態を見つける
IDで最後に読み取ったメッセージを見つける
読み取り状態が存在する場合、新しいメッセージ情報で更新
読み取り状態が存在しない場合、新しいものを作成
成功時に204 No Contentを返す

使用例:

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

// Register route with Express app
app.use('/api', routes.upsertChatChannelReadStateRoute);

// Client usage:
const response = await fetch('/api/channels/channel-123/read-state', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    identityId: 'user-456',
    lastReadMessageId: 'message-789'
  })
});

if (response.status === 204) {
  console.log('Read state upserted successfully');
}

🔗 関連ドキュメント

チャットドメイン概要 - チャットドメイン概要
チャットスキーマ - チャットバリデーションスキーマ
チャットハンドラー - チャットビジネスロジック関数

🎯 概要​

📋 ルート構造​

🔧 利用可能なチャットルート​

チャネルルート​

createChatChannelRoute​

findChatChannelsRoute​

getChatChannelRoute​

updateChatChannelRoute​

deleteChatChannelRoute​

getChannelMessagesRoute​

getChatChannelIconUploadUrlRoute​

サブスクリプションルート​

createChatSubscriptionRoute​

findChatSubscriptionsRoute​

getChatSubscriptionRoute​

deleteChatSubscriptionRoute​

メッセージルート​

createChatMessageRoute​

findChatMessagesRoute​

getChatMessageRoute​

updateChatMessageRoute​

deleteChatMessageRoute​

getChatMessageAttachmentUploadUrlRoute​

createChatMessageAttachmentRoute​

deleteChatMessageAttachmentRoute​

streamChatMessagesRoute​

メッセージテンプレートルート​

createChatMessageTemplateRoute​

getChatMessageTemplateRoute​

updateChatMessageTemplateRoute​

deleteChatMessageTemplateRoute​

findChatMessageTemplatesRoute​

findChatMessageTemplatesForOrganizationRoute​

upsertChatChannelReadStateRoute​

🔗 関連ドキュメント​

🎯 概要

📋 ルート構造

🔧 利用可能なチャットルート

チャネルルート

`createChatChannelRoute`

`findChatChannelsRoute`

`getChatChannelRoute`

`updateChatChannelRoute`

`deleteChatChannelRoute`

`getChannelMessagesRoute`

`getChatChannelIconUploadUrlRoute`

サブスクリプションルート

`createChatSubscriptionRoute`

`findChatSubscriptionsRoute`

`getChatSubscriptionRoute`

`deleteChatSubscriptionRoute`

メッセージルート

`createChatMessageRoute`

`findChatMessagesRoute`

`getChatMessageRoute`

`updateChatMessageRoute`

`deleteChatMessageRoute`

`getChatMessageAttachmentUploadUrlRoute`

`createChatMessageAttachmentRoute`

`deleteChatMessageAttachmentRoute`

`streamChatMessagesRoute`

メッセージテンプレートルート

`createChatMessageTemplateRoute`

`getChatMessageTemplateRoute`

`updateChatMessageTemplateRoute`

`deleteChatMessageTemplateRoute`

`findChatMessageTemplatesRoute`

`findChatMessageTemplatesForOrganizationRoute`

`upsertChatChannelReadStateRoute`

🔗 関連ドキュメント