バージョン: 0.9.0 (最新)

💬 チャットサービス

Chat Serviceは、チャネル、サブスクリプション、メッセージング機能を含むリアルタイム通信機能を管理するための包括的なソリューションを提供します。この統合サービスは、チャネル管理とサブスクリプション処理を単一の一貫したAPIに統合しています。

🚀 クイックスタート

import express from 'express';
import { middlewares, services, drivers } from '@nodeblocks/backend-sdk';

const { nodeBlocksErrorMiddleware } = middlewares;
const { chatService } = services;
const { withMongo, createFileStorageDriver } = drivers;

const connectToDatabase = withMongo('mongodb://localhost:27017', 'dev', 'user', 'password');
const fileStorageDriver = createFileStorageDriver('your-project-id', 'your-bucket-name');

express()
  .use(
    chatService(
      {
        ...(await connectToDatabase('identities')),
        ...(await connectToDatabase('chatChannels')),
        ...(await connectToDatabase('chatMessages')),
        ...(await connectToDatabase('chatChannelReadStates')),
        ...(await connectToDatabase('subscriptions')),
        ...(await connectToDatabase('organizations')), // オプション
        ...(await connectToDatabase('chatMessageTemplates')), // オプション
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        identity: {
          typeIds: {
            admin: '100',
            guest: '000',
            regular: '001',
          },
        },
        organization: {
          roles: {
            admin: 'admin',
            member: 'member',
            owner: 'owner',
          },
        },
      },
      {
        fileStorageDriver, // メッセージ添付ファイルのアップロードURLに必要
      }
    )
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

📋 エンドポイント概要

チャネル操作

Method	Path	説明
`POST`	`/channels`	新しいチャネルを作成
`GET`	`/channels`	すべてのチャネルを一覧表示
`GET`	`/channels/:channelId`	特定のチャネルを取得
`GET`	`/channels/:channelId/icon-upload-url`	チャネルアイコンのアップロード用署名付きURLを生成
`PATCH`	`/channels/:channelId`	チャネルを更新
`DELETE`	`/channels/:channelId`	チャネルを削除

サブスクリプション操作

Method	Path	説明
`POST`	`/subscriptions`	新しいサブスクリプションを作成
`GET`	`/subscriptions`	すべてのサブスクリプションを一覧表示
`GET`	`/subscriptions/:subscriptionId`	特定のサブスクリプションを取得
`DELETE`	`/subscriptions/:subscriptionId`	サブスクリプションを削除

メッセージ操作

Method	Path	説明
`POST`	`/messages`	新しいメッセージを作成
`GET`	`/messages?channelId=:channelId`	チャネル内のメッセージを一覧表示
`GET`	`/channels/:channelId/messages`	特定のチャネルのすべてのメッセージを取得
`GET`	`/messages/:messageId`	特定のメッセージを取得
`GET`	`/messages/:messageId/attachment-upload-url`	メッセージ添付ファイルのアップロード用署名付きURLを生成
`POST`	`/messages/:messageId/attachments`	既存のメッセージに新しい添付ファイルを作成
`DELETE`	`/messages/:messageId/attachments/:attachmentId`	メッセージから添付ファイルを削除
`PATCH`	`/messages/:messageId`	メッセージを更新
`DELETE`	`/messages/:messageId`	メッセージを削除

メッセージテンプレート操作

Method	Path	説明
`POST`	`/message-templates`	新しいメッセージテンプレートを作成
`GET`	`/message-templates`	すべてのメッセージテンプレートを一覧表示（管理者のみ）
`GET`	`/organizations/:organizationId/message-templates`	組織のメッセージテンプレートを一覧表示（組織メンバー）
`GET`	`/message-templates/:templateId`	特定のメッセージテンプレートを取得
`PATCH`	`/message-templates/:templateId`	既存のメッセージテンプレートを更新
`DELETE`	`/message-templates/:templateId`	既存のメッセージテンプレートを削除

チャネル既読状態操作

Method	Path	説明
`PUT`	`/channels/:channelId/read-state`	チャネルの既読状態をアップサート（作成または更新）

🗄️ エンティティスキーマ

チャネルエンティティ

{
  "name": "string",
  "ownerId": "string",
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細:

Field	Type	自動生成	必須	説明
`name`	string	❌	✅	チャネル名/タイトル
`ownerId`	string	❌	✅	このチャネルを所有するアイデンティティのID
`createdAt`	datetime	✅	✅	作成タイムスタンプ
`id`	string	✅	✅	一意の識別子（UUID）
`updatedAt`	datetime	✅	✅	最終更新タイムスタンプ

サブスクリプションエンティティ

{
  "approved": "boolean",
  "channelId": "string",
  "permissions": ["string"],
  "subscribedAt": "string (datetime)",
  "subscribedId": "string",
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細:

Field	Type	自動生成	必須	説明
`approved`	boolean	❌	❌	サブスクリプションが承認されているかどうか
`channelId`	string	❌	✅	サブスクライブするチャネルのID
`permissions`	array	❌	❌	権限文字列の配列（例：["read", "write"]）
`subscribedAt`	datetime	❌	❌	サブスクリプションが作成されたタイムスタンプ
`subscribedId`	string	❌	❌	サブスクライブするアイデンティティのID
`createdAt`	datetime	✅	✅	作成タイムスタンプ
`id`	string	✅	✅	一意の識別子（UUID）
`updatedAt`	datetime	✅	✅	最終更新タイムスタンプ

メッセージエンティティ

{
  "channelId": "string",
  "content": "string",
  "senderId": "string",
  "title": "string",
  "attachments": [
    {
      "objectId": "string (UUID)",
      "type": "string",
      "id": "string (UUID)",
      "createdAt": "string (datetime)",
      "updatedAt": "string (datetime)"
    }
  ],
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"

フィールド詳細:

Field	Type	自動生成	必須	説明
`channelId`	string	❌	✅	メッセージが送信されるチャネルのID
`content`	string	❌	✅	メッセージの内容/テキスト
`senderId`	string	❌	✅	メッセージを送信するアイデンティティのID
`title`	string	❌	❌	オプションのメッセージタイトル
`attachments`	array	❌	✅	ファイル添付の配列（空の`[]`も可）
`attachments[].objectId`	string (UUID)	❌	✅	ストレージ内のアップロードされたファイルへのUUID参照
`attachments[].type`	string	❌	✅	MIMEタイプまたはファイルカテゴリ
`attachments[].id`	string (UUID)	✅	✅	添付ファイルエンティティの一意の識別子
`attachments[].createdAt`	datetime	✅	✅	添付ファイルの作成タイムスタンプ
`attachments[].updatedAt`	datetime	✅	✅	添付ファイルの最終更新タイムスタンプ
`createdAt`	datetime	✅	✅	メッセージの作成タイムスタンプ
`id`	string	✅	✅	一意の識別子（UUID）
`updatedAt`	datetime	✅	✅	メッセージの最終更新タイムスタンプ

📝 Note: 自動生成フィールドはサービスによって設定され、作成/更新リクエストに含めるべきではありません。attachments配列内の各添付ファイルは、メッセージ作成時に自動的に基本エンティティフィールド（id、createdAt、updatedAt）を受け取ります。スキーマはadditionalProperties: falseを強制します - 定義されたフィールドのみが許可されます。

チャネル既読状態エンティティ

{
  "channelId": "string",
  "identityId": "string",
  "lastReadMessageId": "string",
  "lastReadMessageCreatedAt": "string (datetime)",
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細:

Field	Type	自動生成	必須	説明
`channelId`	string	❌	✅	追跡されるチャネルのID
`identityId`	string	❌	✅	既読状態が追跡されるアイデンティティのID
`lastReadMessageId`	string	❌	✅	アイデンティティが最後に読んだメッセージのID
`lastReadMessageCreatedAt`	datetime	❌	✅	最後に読んだメッセージが作成されたタイムスタンプ
`createdAt`	datetime	✅	✅	作成タイムスタンプ
`id`	string	✅	✅	一意の識別子（UUID）
`updatedAt`	datetime	✅	✅	最終更新タイムスタンプ

📝 Note: 自動生成フィールドはサービスによって設定され、アップサートリクエストに含めるべきではありません。スキーマはadditionalProperties: falseを強制します - 定義されたフィールドのみが許可されます。

🔐 認証ヘッダー

保護されたエンドポイントでは、以下のヘッダーを含めてください：

Authorization: Bearer <access_token>
x-nb-fingerprint: <device_fingerprint>

⚠️ Important: x-nb-fingerprintヘッダーは、認証時にフィンガープリントが指定された場合、すべての認証済みリクエストで必須です。これがない場合、リクエストは401 Unauthorizedを返します。

🔧 APIエンドポイント

📺 チャネル操作

1. チャネルの作成

提供された情報で新しいチャットチャネルを作成します。

リクエスト:

Method: POST
Path: /channels
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: 自動的に強制されます（nameとownerIdが必要、追加プロパティなし）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたは自己（ownerIdが認証済みユーザーと一致）

リクエストボディ:

Field	Type	必須	説明
`name`	string	✅	チャネル名/タイトル
`ownerId`	string	✅	このチャネルを所有するユーザーのID
`icon`	object \| null	❌	`objectId`（UUID）と`type`（string）を含むチャネルアイコンオブジェクト、またはnull

レスポンスボディ:

Field	Type	説明
`name`	string	チャネル名/タイトル
`ownerId`	string	このチャネルを所有するユーザーのID
`icon`	object \| null	`type`（string）と`url`（string）を含むチャネルアイコンオブジェクト、またはnull
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のチャネル識別子
`updatedAt`	string	最終更新タイムスタンプ

リクエスト例:

curl -X POST http://localhost:8089/channels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Updates",
    "ownerId": "user-456"
  }'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "name": "Project Updates",
  "ownerId": "user-456",
  "icon": null,
  "createdAt": "2025-06-24T08:33:40.146Z",
  "id": "af62eac3-06aa-481a-8c44-a029e96de2ed",
  "updatedAt": "2025-06-24T08:33:40.146Z"
}

バリデーションエラー例:

必須フィールドの欠如:

{
  "error": {
    "message": "must have ownerId when creating a new channel"
  }
}

スキーマバリデーションエラー:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'ownerId'"
    ]
  }
}

追加プロパティエラー:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must NOT have additional properties"
    ]
  }
}

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must NOT have additional properties",
      "request body must NOT have additional properties"
    ]
  }
}

2. チャネルの一覧取得

オプションのフィルタリングとページネーションを使用してすべてのチャネルを取得します。

リクエスト:

Method: GET
Path: /channels
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: name、ownerId、ページネーション（page、limit）のクエリパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたは自己（自分のチャネルをリクエストする場合）

クエリパラメータ:

Parameter	Type	必須	説明
`name`	string	❌	チャネル名でフィルタ
`ownerId`	string	❌	所有者IDでフィルタ
`page`	number	❌	ページネーションのページ番号（1-1000）
`limit`	number	❌	1ページあたりのアイテム数（1-50）

レスポンスボディ: チャネル配列とメタデータを含むページネーション付きレスポンス。

レスポンス構造:

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "ownerId": "string",
      "icon": {
        "type": "string",
        "url": "string"
      } | null,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": number,
      "limit": number,
      "total": number,
      "totalPages": number,
      "hasNext": boolean,
      "hasPrev": boolean
    }
  }
}

リクエスト例:

curl "http://localhost:8089/channels?page=1&limit=10" \
  -H "Authorization: Bearer <access_token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "name": "Project Updates",
      "ownerId": "user-456",
      "icon": null,
      "createdAt": "2025-06-24T08:33:40.146Z",
      "id": "af62eac3-06aa-481a-8c44-a029e96de2ed",
      "updatedAt": "2025-06-24T08:33:40.146Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

3. チャネルの取得

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

リクエスト:

Method: GET
Path: /channels/:channelId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: チャネルIDのパスパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロール、チャネル所有者、またはチャネルへのアクティブなサブスクリプションが必要

レスポンスボディ:

Field	Type	説明
`name`	string	チャネル名/タイトル
`ownerId`	string	このチャネルを所有するユーザーのID
`icon`	object \| null	`type`（string）と`url`（string）を含むチャネルアイコンオブジェクト、またはnull
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のチャネル識別子
`updatedAt`	string	最終更新タイムスタンプ

リクエスト例:

curl http://localhost:8089/channels/af62eac3-06aa-481a-8c44-a029e96de2ed \
  -H "Authorization: Bearer <access_token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Project Updates",
  "ownerId": "user-456",
  "icon": null,
  "createdAt": "2025-06-24T08:33:40.146Z",
  "id": "af62eac3-06aa-481a-8c44-a029e96de2ed",
  "updatedAt": "2025-06-24T08:33:40.146Z"
}

4. チャネルアイコンアップロードURLの取得

チャネルアイコン画像を安全にアップロードするための事前署名付きURLを生成します。オブジェクトIDと一時的な署名付きURLを返します。

リクエスト:

Method: GET
Path: /channels/:channelId/icon-upload-url
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

URLパラメータ:

Parameter	Type	必須	説明
`channelId`	string	✅	対象チャネルID

クエリパラメータ:

Parameter	Type	必須	説明
`contentType`	string	✅	画像MIMEタイプ（例：`image/png`、`image/jpeg`）
`contentLength`	number	✅	ファイルサイズ（バイト単位、最大10MB）

レスポンスボディ:

Field	Type	説明
`objectId`	string	アイコンの生成されたストレージオブジェクトID
`url`	string	ファイルをアップロードするための事前署名付きURL

バリデーション:

スキーマバリデーション: 画像アップロードスキーマを使用（コンテンツタイプとサイズ制約）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはチャネル所有者が必要

リクエスト例:

curl "http://localhost:8089/channels/af62eac3-06aa-481a-8c44-a029e96de2ed/icon-upload-url?contentType=image/jpeg&contentLength=524288" \
  -H "Authorization: Bearer <token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "objectId": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "url": "https://storage.googleapis.com/bucket/channels/icons/...&X-Goog-Expires=900&X-Goog-Signature=..."
}

使用方法:

contentTypeとcontentLengthクエリパラメータを使用してこのエンドポイントを呼び出し、署名付きアップロードURLを取得します
返されたurlを使用して、アイコンファイルをクラウドストレージに直接アップロードします（ファイルバイナリを含むPUTリクエスト）
返されたobjectIdを保存して、アップロードされたアイコンを参照します

エラーレスポンス:

クエリパラメータの欠如:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "contentType is required",
      "contentLength is required"
    ]
  }
}

無効なコンテンツタイプ:

{
  "error": {
    "message": "Invalid content type - must be an image"
  }
}

ファイルサイズが大きすぎる:

{
  "error": {
    "message": "File size exceeds maximum allowed (10MB)"
  }
}

チャネルが見つからない:

{
  "error": {
    "message": "Channel not found"
  }
}

認証されていない:

{
  "error": {
    "message": "Unauthorized - must be channel owner or admin"
  }
}

5. チャネルの更新

既存のチャネルのプロパティを更新します。

リクエスト:

Method: PATCH
Path: /channels/:channelId
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: 部分更新スキーマ（すべてのフィールドがオプション、追加プロパティなし）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはチャネル所有者が必要

リクエストボディ:

Field	Type	必須	説明
`name`	string	❌	新しいチャネル名/タイトル
`icon`	object \| null	❌	`objectId`（UUID）と`type`（string）を含むチャネルアイコンオブジェクト、またはnullでアイコンを削除

レスポンスボディ:

Field	Type	説明
`name`	string	更新されたチャネル名/タイトル
`ownerId`	string	このチャネルを所有するユーザーのID
`icon`	object \| null	チャネルアイコンオブジェクトまたはnull
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のチャネル識別子
`updatedAt`	string	最終更新タイムスタンプ

リクエスト例:

curl -X PATCH http://localhost:8089/channels/af62eac3-06aa-481a-8c44-a029e96de2ed \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "name": "Updated Project Updates"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Updated Project Updates",
  "ownerId": "user-456",
  "icon": null,
  "createdAt": "2025-06-24T08:33:40.146Z",
  "id": "af62eac3-06aa-481a-8c44-a029e96de2ed",
  "updatedAt": "2025-06-24T09:15:22.123Z"
}

6. チャネルの削除

チャネルと関連するすべてのデータを削除します。

リクエスト:

Method: DELETE
Path: /channels/:channelId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: チャネルIDのパスパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはチャネル所有者が必要

レスポンスボディ:

Field	Type	説明
No response body	-	削除エンドポイントは成功時にレスポンスボディを返しません

リクエスト例:

curl -X DELETE http://localhost:8089/channels/af62eac3-06aa-481a-8c44-a029e96de2ed

成功レスポンス:

Status: 204 No Content
Body: (empty)

見つからないエラー例:

{
  "error": {
    "message": "Channel not found"
  }
}

📋 サブスクリプション操作

7. サブスクリプションの作成

チャネルへの新しいサブスクリプションを作成します。

リクエスト:

Method: POST
Path: /subscriptions
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: 自動的に強制されます（channelIdとsubscribedIdが必要、追加プロパティなし）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたは自己（サブスクライバーが認証済みユーザー）

リクエストボディ:

Field	Type	必須	説明
`channelId`	string	✅	サブスクライブするチャネルのID
`subscribedId`	string	✅	サブスクライブするユーザーのID
`approved`	boolean	❌	サブスクリプションが承認されているかどうか
`permissions`	string[]	❌	権限文字列の配列
`subscribedAt`	string (date-time)	❌	サブスクリプションが作成されたタイムスタンプ

レスポンスボディ:

Field	Type	説明
`channelId`	string	サブスクライブするチャネルのID
`subscribedId`	string	サブスクライブするユーザーのID
`approved`	boolean	サブスクリプションが承認されているかどうか
`permissions`	array	権限文字列の配列
`subscribedAt`	string	サブスクリプションが作成されたタイムスタンプ
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のサブスクリプション識別子
`updatedAt`	string	最終更新タイムスタンプ

リクエスト例:

curl -X POST http://localhost:8089/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "af62eac3-06aa-481a-8c44-a029e96de2ed",
    "subscribedId": "user-456",
    "approved": true,
    "permissions": ["read", "write"]
  }'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "channelId": "af62eac3-06aa-481a-8c44-a029e96de2ed",
  "subscribedId": "user-456",
  "approved": true,
  "permissions": ["read", "write"],
  "createdAt": "2025-06-27T02:16:07.916Z",
  "id": "b17501d6-2576-4a18-86f5-3545da75e678",
  "updatedAt": "2025-06-27T02:16:07.916Z"
}

バリデーションエラー例:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'channelId'",
      "request body must have required property 'subscribedId'",
    ]
  }
}

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must NOT have additional properties",
    ]
  }
}

8. サブスクリプションの一覧取得

オプションのフィルタリングとページネーションを使用してすべてのサブスクリプションを取得します。

リクエスト:

Method: GET
Path: /subscriptions
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: approved、channelId、subscribedAt、subscribedId、ページネーション（page、limit）のクエリパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロール、チャネルへのアクティブなサブスクリプション、チャネル所有者、または自己（サブスクライバー）が必要

クエリパラメータ:

Parameter	Type	必須	説明
`approved`	boolean	❌	承認ステータスでフィルタ
`channelId`	string	❌	チャネルIDでフィルタ
`subscribedId`	string	❌	サブスクライバーIDでフィルタ
`subscribedAt`	string (date-time)	❌	サブスクリプション日でフィルタ
`page`	number	❌	ページネーションのページ番号（1-1000）
`limit`	number	❌	1ページあたりのアイテム数（1-50）

レスポンスボディ: サブスクリプション配列とメタデータを含むページネーション付きレスポンス。

レスポンス構造:

{
  "data": [
    {
      "id": "string",
      "channelId": "string",
      "subscribedId": "string",
      "approved": boolean,
      "permissions": ["string"],
      "subscribedAt": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": number,
      "limit": number,
      "total": number,
      "totalPages": number,
      "hasNext": boolean,
      "hasPrev": boolean
    }
  }
}

リクエスト例:

curl "http://localhost:8089/subscriptions?page=1&limit=10" \
  -H "Authorization: Bearer <access_token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "channelId": "channel-123",
      "subscribedId": "user-456",
      "approved": true,
      "permissions": ["read", "write"],
      "subscribedAt": "2025-06-24T08:33:40.146Z",
      "createdAt": "2025-06-24T08:33:40.146Z",
      "id": "sub-789",
      "updatedAt": "2025-06-24T08:33:40.146Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

9. サブスクリプションの取得

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

リクエスト:

Method: GET
Path: /subscriptions/:subscriptionId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: サブスクリプションIDのパスパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはサブスクリプション所有者が必要

リクエスト例:

curl http://localhost:8089/subscriptions/b17501d6-2576-4a18-86f5-3545da75e678

10. サブスクリプションの削除

サブスクリプションを削除します（チャネルからサブスクライブ解除）。

リクエスト:

Method: DELETE
Path: /subscriptions/:subscriptionId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: サブスクリプションIDのパスパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはサブスクリプション所有者が必要

レスポンスボディ:

Field	Type	説明
No response body	-	削除エンドポイントは成功時にレスポンスボディを返しません

リクエスト例:

curl -X DELETE http://localhost:8089/subscriptions/b17501d6-2576-4a18-86f5-3545da75e678

成功レスポンス:

Status: 204 No Content
Body: (empty)

見つからないエラー例:

{
  "error": {
    "message": "Subscription not found"
  }
}

💬 メッセージ操作

11. メッセージの作成

チャネルに新しいメッセージを送信します。

リクエスト:

Method: POST
Path: /messages
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: 自動的に強制されます（content、senderId、channelIdが必要、追加プロパティなし）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 送信者として自己が必要
- チャネルへのアクティブなサブスクリプションが必要

リクエストボディ:

Field	Type	必須	説明
`channelId`	string	✅	メッセージが送信されるチャネルのID
`content`	string	✅	メッセージの内容/テキスト
`senderId`	string	✅	メッセージを送信するユーザーのID
`title`	string	❌	オプションのメッセージタイトル

レスポンスボディ:

Field	Type	説明
`channelId`	string	メッセージが送信されるチャネルのID
`content`	string	メッセージの内容/テキスト
`senderId`	string	メッセージを送信するユーザーのID
`title`	string	オプションのメッセージタイトル
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のメッセージ識別子
`updatedAt`	string	最終更新タイムスタンプ

リクエスト例:

curl -X POST http://localhost:8089/messages \
  -H "Content-Type: application/json" \
  -d '{"channelId": "test-channel-123", "content": "Hello world!", "senderId": "user-456"}'

成功レスポンス:

{
  "channelId": "test-channel-123",
  "content": "Hello world!",
  "senderId": "user-456",
  "createdAt": "2025-07-01T03:22:06.178Z",
  "id": "2b43d66c-9cab-434b-9cb7-18de8d3ec9c9",
  "updatedAt": "2025-07-01T03:22:06.178Z"
}

バリデーションエラー例:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'senderId'",
      "request body must have required property 'channelId'"
    ]
  }
}

12. メッセージの一覧取得

特定のチャネル内のメッセージを取得します。

リクエスト:

Method: GET
Path: /messages?channelId=:channelId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: channelId（必須）、オプションのcontent、senderId、title、ページネーション（page、limit）のクエリパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロール、チャネルへのアクティブなサブスクリプション、または送信者として自己が必要

クエリパラメータ:

Parameter	Type	必須	説明
`channelId`	string	✅	メッセージを取得するチャネルのID
`content`	string	❌	メッセージ内容でフィルタ
`senderId`	string	❌	送信者IDでフィルタ
`title`	string	❌	メッセージタイトルでフィルタ
`page`	number	❌	ページネーションのページ番号（1-1000）
`limit`	number	❌	1ページあたりのアイテム数（1-50）

レスポンスボディ: メッセージ配列とメタデータを含むページネーション付きレスポンス。

レスポンス構造:

{
  "data": [
    {
      "id": "string",
      "channelId": "string",
      "content": "string",
      "senderId": "string",
      "title": "string",
      "attachments": [
        {
          "id": "string",
          "objectId": "string",
          "type": "string",
          "url": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": number,
      "limit": number,
      "total": number,
      "totalPages": number,
      "hasNext": boolean,
      "hasPrev": boolean
    }
  }
}

リクエスト例:

curl "http://localhost:8089/messages?channelId=test-channel-123&page=1&limit=10" \
  -H "Authorization: Bearer <access_token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "channelId": "test-channel-123",
      "content": "Updated message content",
      "senderId": "user-456",
      "createdAt": "2025-07-01T03:22:06.178Z",
      "id": "2b43d66c-9cab-434b-9cb7-18de8d3ec9c9",
      "updatedAt": "2025-07-01T03:22:34.413Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

バリデーションエラー例:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "query parameter 'channelId' is required"
    ]
  }
}

13. IDでメッセージを取得

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

リクエスト:

Method: GET
Path: /messages/:messageId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: メッセージIDのパスパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはメッセージ所有者が必要

リクエスト例:

curl http://localhost:8089/messages/2b43d66c-9cab-434b-9cb7-18de8d3ec9c9

成功レスポンス:

{
  "channelId": "test-channel-123",
  "content": "Updated message content",
  "senderId": "user-456",
  "createdAt": "2025-07-01T03:22:06.178Z",
  "id": "2b43d66c-9cab-434b-9cb7-18de8d3ec9c9",
  "updatedAt": "2025-07-01T03:22:34.413Z"
}

見つからないエラー例:

{
  "error": {
    "message": "Message not found"
  }
}

14. メッセージの更新

既存のメッセージの内容を更新します。

リクエスト:

Method: PATCH
Path: /messages/:messageId
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: 部分更新スキーマ（すべてのフィールドがオプション、メッセージIDのパスパラメータ検証、追加プロパティなし）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはメッセージ所有者が必要

リクエストボディ:

Field	Type	必須	説明
`content`	string	❌	更新されたメッセージ内容
`senderId`	string	❌	更新された送信者ID（通常は変更されません）
`title`	string	❌	更新されたメッセージタイトル

レスポンスボディ:

Field	Type	説明
`channelId`	string	メッセージが送信されるチャネルのID
`content`	string	更新されたメッセージ内容
`senderId`	string	メッセージを送信するユーザーのID
`title`	string	更新されたメッセージタイトル
`createdAt`	string	作成タイムスタンプ
`id`	string	一意のメッセージ識別子
`updatedAt`	string	最終更新タイムスタンプ

リクエスト例:

curl -X PATCH http://localhost:8089/messages/2b43d66c-9cab-434b-9cb7-18de8d3ec9c9 \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated message content"}'

成功レスポンス:

{
  "channelId": "test-channel-123",
  "content": "Updated message content",
  "senderId": "user-456",
  "createdAt": "2025-07-01T03:22:06.178Z",
  "id": "2b43d66c-9cab-434b-9cb7-18de8d3ec9c9",
  "updatedAt": "2025-07-01T03:22:34.413Z"
}

見つからないエラー例:

{
  "error": {
    "message": "Chat message not found"
  }
}

15. メッセージの削除

チャネルからメッセージを削除します。

リクエスト:

Method: DELETE
Path: /messages/:messageId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

バリデーション:

スキーマバリデーション: メッセージIDのパスパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはメッセージ所有者が必要

レスポンスボディ:

Field	Type	説明
No response body	-	削除エンドポイントは成功時にレスポンスボディを返しません

リクエスト例:

curl -X DELETE http://localhost:8089/messages/81950444-5223-47c8-8a8c-0604c2955f15

成功レスポンス:

Status: 204 No Content
Body: (empty)

見つからないエラー例:

{
  "error": {
    "message": "Chat message not found"
  }
}

📝 メッセージテンプレート操作

16. メッセージテンプレートの作成

適切な検証とエラーハンドリングを使用して、再利用可能なメッセージングコンテンツ用の新しいチャットメッセージテンプレートを作成します。

リクエスト:

Method: POST
Path: /message-templates
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

リクエストボディ:

Field	Type	必須	説明
`content`	string	✅	テンプレートメッセージの内容
`title`	string	✅	テンプレートのタイトル/説明
`organizationId`	string	❌	テンプレートスコープの組織識別子

バリデーション:

スキーマバリデーション: 自動的に強制されます（contentとtitleが必要）
ルートバリデーター: 認証済みリクエストが必要（bearerトークン）

リクエスト例:

curl -X POST {{host}}/message-templates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>" \
  -d '{
    "content": "Welcome to our community! Please follow our guidelines.",
    "title": "Welcome Message",
    "organizationId": "org-123"
  }'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "template-uuid-here"
}

バリデーションエラー例:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'content'"
    ]
  }
}

17. IDでメッセージテンプレートを取得

一意の識別子で特定のチャットメッセージテンプレートを取得し、メッセージングアプリケーションで再利用します。

リクエスト:

Method: GET
Path: /message-templates/:templateId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要

URLパラメータ:

templateId: string (必須) - メッセージテンプレートの一意の識別子

リクエストボディ:

Field	Type	必須	説明
No request body	-	ボディは不要です

バリデーション:

スキーマバリデーション: テンプレートIDのパスパラメータ検証
ルートバリデーター: 認証済みリクエストが必要（bearerトークン）

リクエスト例:

curl -X GET {{host}}/message-templates/template-123 \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": "Welcome to our community! Please follow our guidelines.",
  "createdAt": "2025-01-20T10:30:00.000Z",
  "id": "template-123",
  "organizationId": "org-123",
  "title": "Welcome Message",
  "updatedAt": "2025-01-20T10:30:00.000Z"
}

見つからないエラー例:

{
  "error": {
    "message": "Chat message template not found"
  }
}

18. メッセージテンプレートの更新

部分データサポートを使用して既存のチャットメッセージテンプレートを更新し、管理者または組織所有者がテンプレートの内容とタイトルを変更できるようにします。

リクエスト:

Method: PATCH
Path: /message-templates/:templateId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（管理者または組織所有者/管理者）

URLパラメータ:

templateId: string (必須) - 更新するメッセージテンプレートの一意の識別子

リクエストボディ:

Field	Type	必須	説明
`content`	string	❌	更新されたメッセージテンプレートの内容
`title`	string	❌	更新されたメッセージテンプレートのタイトル

バリデーション:

スキーマバリデーション: パスパラメータと部分ボディ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはテンプレートへの組織所有者/管理者アクセスが必要

リクエスト例:

curl -X PATCH {{host}}/message-templates/template-123 \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated welcome message content",
    "title": "Updated Welcome Message"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": "Updated welcome message content",
  "createdAt": "2025-01-20T10:30:00.000Z",
  "id": "template-123",
  "organizationId": "org-123",
  "title": "Updated Welcome Message",
  "updatedAt": "2025-01-25T14:20:00.000Z"
}

エラーレスポンス:

見つからない（404）:

{
  "error": {
    "message": "Chat message template not found"
  }
}

認証されていない（401）:

{
  "error": {
    "message": "token could not be verified"
  }
}

禁止（403）:

{
  "error": {
    "message": "Access denied: insufficient permissions"
  }
}

使用例:

組織変更のためのウェルカムメッセージの更新
テンプレートの内容やタイトルの修正
時間の経過に伴うテンプレートの関連性の維持
管理テンプレート管理

19. メッセージテンプレートの削除

適切な認証チェックを使用して既存のチャットメッセージテンプレートを削除し、管理者または組織所有者がデータベースからテンプレートを削除できるようにします。

リクエスト:

Method: DELETE
Path: /message-templates/:templateId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（管理者または組織所有者/管理者）

URLパラメータ:

templateId: string (必須) - 削除するメッセージテンプレートの一意の識別子

バリデーション:

スキーマバリデーション: パスパラメータ検証
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールまたはテンプレートへの組織所有者/管理者アクセスが必要

リクエスト例:

curl -X DELETE {{host}}/message-templates/template-123 \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

成功レスポンス:

HTTP/1.1 204 No Content

エラーレスポンス:

見つからない（404）:

{
  "error": {
    "message": "Chat message template not found"
  }
}

認証されていない（401）:

{
  "error": {
    "message": "token could not be verified"
  }
}

禁止（403）:

{
  "error": {
    "message": "Access denied: insufficient permissions"
  }
}

内部サーバーエラー（500）:

{
  "error": {
    "message": "Failed to delete message template"
  }
}

使用例:

古いまたは未使用のテンプレートの削除
組織テンプレートのクリーンアップ
テンプレートライフサイクル管理
管理テンプレート削除

20. メッセージテンプレートの一覧取得

データ正規化と管理者専用アクセス制御を使用して、すべてのチャットメッセージテンプレートのページネーション付きリストを取得します。

リクエスト:

Method: GET
Path: /message-templates
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（管理者のみ）

クエリパラメータ:

Parameter	Type	必須	説明
`page`	number	❌	ページネーションのページ番号（1-1000）
`limit`	number	❌	1ページあたりのアイテム数（1-50）

レスポンスボディ: メッセージテンプレート配列とメタデータを含むページネーション付きレスポンス。

レスポンス構造:

{
  "data": [
    {
      "id": "string",
      "title": "string",
      "content": "string",
      "organizationId": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": number,
      "limit": number,
      "total": number,
      "totalPages": number,
      "hasNext": boolean,
      "hasPrev": boolean
    }
  }
}

バリデーション:

スキーマバリデーション: ページネーションクエリパラメータ
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールが必要（checkIdentityType(['admin'])）

リクエスト例:

curl "http://localhost:8089/message-templates?page=1&limit=10" \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "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"
    },
    {
      "id": "template-789",
      "title": "Support Response",
      "content": "Thank you for contacting support. We'll get back to you soon.",
      "organizationId": "org-456",
      "createdAt": "2024-01-02T00:00:00.000Z",
      "updatedAt": "2024-01-02T00:00:00.000Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

エラーレスポンス:

認証されていない（401）:

{
  "error": {
    "message": "token could not be verified"
  }
}

禁止（403）:

{
  "error": {
    "message": "Identity is not authorized to access this resource"
  }
}

内部サーバーエラー（500）:

{
  "error": {
    "message": "Failed to find message templates"
  }
}

使用例:

管理テンプレート管理
テンプレートインベントリと監視
一括テンプレート操作
テンプレート分析とレポート
システム管理インターフェース

21. 組織のメッセージテンプレート一覧取得

組織メンバーシップとロール権限に基づく自動アクセス制御を使用して、特定の組織にスコープされたチャットメッセージテンプレートのページネーション付きリストを取得します。

リクエスト:

Method: GET
Path: /organizations/:organizationId/message-templates
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（所有者/管理者ロールを持つ組織メンバー）

URLパラメータ:

organizationId: string (必須) - テンプレートを取得する組織の一意の識別子

クエリパラメータ:

page: number (オプション、デフォルト: 1) - ページネーションのページ番号
limit: number (オプション、デフォルト: 10) - 1ページあたりのテンプレート数

バリデーション:

スキーマバリデーション: 組織IDパスパラメータとページネーションクエリパラメータ
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 所有者または管理者ロールを持つ組織メンバーシップが必要

リクエスト例:

curl "http://localhost:8089/organizations/org-123/message-templates?page=1&limit=10" \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "template-456",
      "title": "Organization Welcome",
      "content": "Welcome to our organization chat!",
      "organizationId": "org-123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    },
    {
      "id": "template-789",
      "title": "Project Update",
      "content": "Here's the latest update on our project.",
      "organizationId": "org-123",
      "createdAt": "2024-01-02T00:00:00.000Z",
      "updatedAt": "2024-01-02T00:00:00.000Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 2,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

エラーレスポンス:

認証されていない（401）:

{
  "error": {
    "message": "token could not be verified"
  }
}

禁止（403）:

{
  "error": {
    "message": "Identity is not a member of the organization"
  }
}

内部サーバーエラー（500）:

{
  "error": {
    "message": "Failed to find message templates"
  }
}

使用例:

組織固有のテンプレート管理
チームコラボレーションツール
部門固有のメッセージングテンプレート
組織全体のコミュニケーション標準
ロールベースのテンプレートアクセス制御

⚙️ 設定オプション

サービスデータストア

interface ChatServiceDataStore {
  identities: Collection;              // 必須 - ユーザーアイデンティティコレクション
  chatChannels: Collection;            // 必須 - チャットチャネルコレクション
  organizations?: Collection;          // オプション - 組織コレクション
  subscriptions?: Collection;          // オプション - チャネルサブスクリプションコレクション
  chatMessages: Collection;            // 必須 - チャットメッセージコレクション
  chatMessageTemplates?: Collection;   // オプション - メッセージテンプレートコレクション
}

サービス設定

interface ChatServiceConfiguration {
  authSecrets: {
    authEncSecret: string;    // JWT暗号化シークレット
    authSignSecret: string;   // JWT署名シークレット
  };
  identity?: {
    typeIds?: {
      admin: string;          // 管理者ユーザータイプ識別子
      guest: string;          // ゲストユーザータイプ識別子
      regular: string;        // 通常ユーザータイプ識別子
    };
  };
  organization?: {
    roles?: {
      admin: string;          // 管理者組織ロール識別子
      member: string;         // メンバー組織ロール識別子
      owner: string;          // 所有者組織ロール識別子
    };
  };
}

設定詳細

チャットサービスの設定は、セキュリティとユーザータイプ管理のための論理的なグループに整理されています。

🔐 セキュリティ設定

authSecrets - JWTトークンセキュリティシークレット

Type: { authEncSecret: string; authSignSecret: string }
Description: JWT暗号化と署名用のシークレットキー（トークン検証に使用）
Required: Yes (for production)
Child Properties:
- authEncSecret: JWTペイロード暗号化用のシークレットキー
- authSignSecret: JWT署名検証用のシークレットキー

👥 ユーザータイプ設定

identity.typeIds - ユーザータイプ識別子設定

Type: { admin?: string; guest?: string; regular?: string }
Description: ロールベースアクセス制御用のカスタムユーザータイプ識別子
Default: undefined (uses default type validation)
Child Properties:
- admin: 管理者ユーザータイプ識別子
  - Type: string
  - Description: 管理者ユーザー用のカスタム識別子
  - Use Case: 管理操作のためのロールベースアクセス制御
  - Example: "admin", "administrator", "superuser"
- guest: ゲストユーザータイプ識別子
  - Type: string
  - Description: ゲストユーザー用のカスタム識別子
  - Use Case: 未認証または一時的なユーザーのための限定アクセス
  - Example: "guest", "visitor", "anonymous"
- regular: 通常ユーザータイプ識別子
  - Type: string
  - Description: 通常ユーザー用のカスタム識別子
  - Use Case: 標準ユーザーアクセス権限
  - Example: "user", "member", "customer"

🏢 組織設定

organization.roles - 組織ロール識別子設定

Type: { admin?: string; member?: string; owner?: string }
Description: ロールベースアクセス制御用のカスタム組織ロール識別子
Default: undefined (uses default role validation)
Child Properties:
- admin: 管理者組織ロール識別子
  - Type: string
  - Description: 組織管理者ロール用のカスタム識別子
  - Use Case: 組織レベルの管理操作
  - Example: "admin", "administrator", "org-admin"
- member: メンバー組織ロール識別子
  - Type: string
  - Description: 組織メンバーロール用のカスタム識別子
  - Use Case: 標準組織メンバーシップ権限
  - Example: "member", "user", "participant"
- owner: 所有者組織ロール識別子
  - Type: string
  - Description: 組織所有者ロール用のカスタム識別子
  - Use Case: 完全な組織所有権限
  - Example: "owner", "founder", "org-owner"

設定例

const chatConfig = {
  authSecrets: {
    authEncSecret: process.env.AUTH_ENC_SECRET || 'your-enc-secret',
    authSignSecret: process.env.AUTH_SIGN_SECRET || 'your-sign-secret'
  },
  identity: {
    typeIds: {
      admin: 'administrator',
      guest: 'visitor',
      regular: 'member'
    }
  },
  organization: {
    roles: {
      admin: 'admin',
      member: 'member',
      owner: 'owner'
    }
  }
};

🚨 エラーハンドリング

すべてのチャットサービスエラーは、適切なHTTPステータスコードとJSON形式で返されます：

一般的なエラーコード

Status	Error Message	説明
400	Validation Error	無効なリクエストボディ形式または必須フィールドの欠如
400	must have ownerId when creating a new channel	リクエストボディにownerIdフィールドが欠如
400	request body must have required property 'name'	リクエストボディにnameフィールドが欠如
400	request body must have required property 'ownerId'	リクエストボディにownerIdフィールドが欠如
400	request body must have required property 'channelId'	リクエストボディにchannelIdフィールドが欠如
400	request body must have required property 'subscribedId'	リクエストボディにsubscribedIdフィールドが欠如
400	request body must have required property 'content'	リクエストボディにcontentフィールドが欠如
400	request body must have required property 'senderId'	リクエストボディにsenderIdフィールドが欠如
400	request body must NOT have additional properties	リクエストにサポートされていないフィールドが含まれています
400	query parameter 'channelId' is required	必須のクエリパラメータが欠如
400	Failed to create channel	データベース挿入操作が挿入IDを返しませんでした
400	Failed to update channel	更新操作がデータを変更しませんでした（変更が検出されませんでした）
400	Failed to delete channel	データベース削除操作が失敗しました
400	Failed to create subscription	データベース挿入操作が挿入IDを返しませんでした
400	Failed to delete subscription	データベース削除操作が失敗しました
400	Failed to create message	データベース挿入操作が挿入IDを返しませんでした
400	Failed to update message	更新操作がデータを変更しませんでした（変更が検出されませんでした）
400	Failed to delete message	データベース削除操作が失敗しました
401	token could not be verified	認証トークンが欠如または無効
401	Authentication failed	認証トークンが欠如または無効
401	Token fails security check	トークンセキュリティ検証が失敗しました
403	User is not authorized to access this resource	ユーザーに必要な権限がありません（管理者アクセス）
404	Channel not found	リクエストされた操作に対してチャネルが存在しません
404	Subscription not found	リクエストされた操作に対してサブスクリプションが存在しません
404	Message not found	リクエストされた操作に対してメッセージが存在しません
404	Chat message not found	リクエストされた操作に対してチャットメッセージが存在しません
500	Failed to create channel	作成中のデータベース接続の問題または予期しない障害
500	Failed to get channel	取得中のデータベース接続の問題または予期しない障害
500	Failed to find channels	一覧表示中のデータベース接続の問題、無効なフィルター構文、または予期しない障害
500	Failed to update channel	更新中のデータベース接続の問題または予期しない障害
500	Failed to delete channel	削除中のデータベース接続の問題または予期しない障害
500	Failed to create subscription	作成中のデータベース接続の問題または予期しない障害
500	Failed to get subscription	取得中のデータベース接続の問題または予期しない障害
500	Failed to find subscriptions	一覧表示中のデータベース接続の問題、無効なフィルター構文、または予期しない障害
500	Failed to delete subscription	削除中のデータベース接続の問題または予期しない障害
500	Failed to create message	作成中のデータベース接続の問題または予期しない障害
500	Failed to get message	取得中のデータベース接続の問題または予期しない障害
500	Failed to find messages	一覧表示中のデータベース接続の問題、無効なフィルター構文、または予期しない障害
500	Failed to update message	更新中のデータベース接続の問題または予期しない障害
500	Failed to delete message	削除中のデータベース接続の問題または予期しない障害

エラーレスポンス形式

{
  "error": {
    "message": "Error message description",
    "data": ["Additional error details"]
  }
}

バリデーションエラーには追加の詳細が含まれます：

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'name'",
      "request body must have required property 'ownerId'"
    ]
  }
}

🔗 関連ドキュメント

User Service - チャット参加者のユーザー管理
Organization Service - チームベースのチャット組織
Authentication Service - 認証と認可
Error Handling - エラーパターンの理解
Schema Component - データ検証の概念
Custom Service Tutorial - チャット機能の拡張

🚀 クイックスタート​

📋 エンドポイント概要​

チャネル操作​

サブスクリプション操作​

メッセージ操作​

メッセージテンプレート操作​

チャネル既読状態操作​

🗄️ エンティティスキーマ​

チャネルエンティティ​

サブスクリプションエンティティ​

メッセージエンティティ​

チャネル既読状態エンティティ​

🔐 認証ヘッダー​

🔧 APIエンドポイント​

📺 チャネル操作​

1. チャネルの作成​

2. チャネルの一覧取得​

3. チャネルの取得​

4. チャネルアイコンアップロードURLの取得​

5. チャネルの更新​

6. チャネルの削除​

📋 サブスクリプション操作​

7. サブスクリプションの作成​

8. サブスクリプションの一覧取得​

9. サブスクリプションの取得​

10. サブスクリプションの削除​

💬 メッセージ操作​

11. メッセージの作成​

12. メッセージの一覧取得​

13. IDでメッセージを取得​

14. メッセージの更新​

15. メッセージの削除​

📝 メッセージテンプレート操作​

16. メッセージテンプレートの作成​

17. IDでメッセージテンプレートを取得​

18. メッセージテンプレートの更新​

19. メッセージテンプレートの削除​

20. メッセージテンプレートの一覧取得​

21. 組織のメッセージテンプレート一覧取得​

⚙️ 設定オプション​

サービスデータストア​

サービス設定​

設定詳細​

🔐 セキュリティ設定​

👥 ユーザータイプ設定​

🏢 組織設定​

設定例​

🚨 エラーハンドリング​

一般的なエラーコード​

エラーレスポンス形式​

🔗 関連ドキュメント​

🚀 クイックスタート

📋 エンドポイント概要

チャネル操作

サブスクリプション操作

メッセージ操作

メッセージテンプレート操作

チャネル既読状態操作

🗄️ エンティティスキーマ

チャネルエンティティ

サブスクリプションエンティティ

メッセージエンティティ

チャネル既読状態エンティティ

🔐 認証ヘッダー

🔧 APIエンドポイント

📺 チャネル操作

1. チャネルの作成

2. チャネルの一覧取得

3. チャネルの取得

4. チャネルアイコンアップロードURLの取得

5. チャネルの更新

6. チャネルの削除

📋 サブスクリプション操作

7. サブスクリプションの作成

8. サブスクリプションの一覧取得

9. サブスクリプションの取得

10. サブスクリプションの削除

💬 メッセージ操作

11. メッセージの作成

12. メッセージの一覧取得

13. IDでメッセージを取得

14. メッセージの更新

15. メッセージの削除

📝 メッセージテンプレート操作

16. メッセージテンプレートの作成

17. IDでメッセージテンプレートを取得

18. メッセージテンプレートの更新

19. メッセージテンプレートの削除

20. メッセージテンプレートの一覧取得

21. 組織のメッセージテンプレート一覧取得

⚙️ 設定オプション

サービスデータストア

サービス設定

設定詳細

🔐 セキュリティ設定

👥 ユーザータイプ設定

🏢 組織設定

設定例

🚨 エラーハンドリング

一般的なエラーコード

エラーレスポンス形式

🔗 関連ドキュメント