Version: 0.6.0 (Latest)

💬 Chat Service

The Chat Service provides a comprehensive solution for managing real-time communication features including channels, subscriptions, and messaging capabilities. This unified service combines channel management and subscription handling into a single, cohesive API.

🚀 Quickstart

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

const { nodeBlocksErrorMiddleware } = middlewares;
const { chatService } = services;
const { getMongoClient } = drivers;

const client = getMongoClient('mongodb://localhost:27017', 'dev');

express()
  .use(
    chatService(
      {
        identities: client.collection('identities'),
        chatChannels: client.collection('chatChannels'),
        chatMessages: client.collection('chatMessages'),
        subscriptions: client.collection('subscriptions'), // optional
        organizations: client.collection('organizations'), // optional
        chatMessageTemplates: client.collection('chatMessageTemplates'), // optional
      },
      {
        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',
          },
        },
      }
    )
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

📋 Endpoint Summary

Channel Operations

Method	Path	Description
`POST`	`/channels`	Create a new channel
`GET`	`/channels`	List all channels
`GET`	`/channels/:channelId`	Get a specific channel
`PATCH`	`/channels/:channelId`	Update a channel
`DELETE`	`/channels/:channelId`	Delete a channel

Subscription Operations

Method	Path	Description
`POST`	`/subscriptions`	Create a new subscription
`GET`	`/subscriptions`	List all subscriptions
`GET`	`/subscriptions/:subscriptionId`	Get a specific subscription
`DELETE`	`/subscriptions/:subscriptionId`	Delete a subscription

Message Operations

Method	Path	Description
`POST`	`/messages`	Create a new message
`GET`	`/messages?channelId=:channelId`	List messages in a channel
`GET`	`/messages/:messageId`	Get a specific message

Message Template Operations

Method	Path	Description
`POST`	`/message-templates`	Create a new message template
`GET`	`/message-templates/:templateId`	Get a specific message template

🗄️ Entity Schemas

Channel Entity

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

Field Details:

Field	Type	Auto-Generated	Required	Description
`name`	string	❌	✅	Channel name/title
`ownerId`	string	❌	✅	ID of the identity who owns this channel
`createdAt`	datetime	✅	✅	Creation timestamp
`id`	string	✅	✅	Unique identifier (UUID)
`updatedAt`	datetime	✅	✅	Last modification timestamp

Subscription Entity

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

Field Details:

Field	Type	Auto-Generated	Required	Description
`approved`	boolean	❌	❌	Whether the subscription is approved
`channelId`	string	❌	✅	ID of the channel being subscribed to
`permissions`	array	❌	❌	Array of permission strings (e.g., ["read", "write"])
`subscribedAt`	datetime	❌	❌	Timestamp when subscription was created
`subscribedId`	string	❌	❌	ID of the identity subscribing
`createdAt`	datetime	✅	✅	Creation timestamp
`id`	string	✅	✅	Unique identifier (UUID)
`updatedAt`	datetime	✅	✅	Last modification timestamp

Message Entity

{
  "channelId": "string",
  "content": "string",
  "senderId": "string",
  "title": "string",
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

Field Details:

Field	Type	Auto-Generated	Required	Description
`channelId`	string	❌	✅	ID of the channel where message is sent
`content`	string	❌	✅	Message content/text
`senderId`	string	❌	✅	ID of the identity sending the message
`title`	string	❌	❌	Optional message title
`createdAt`	datetime	✅	✅	Creation timestamp
`id`	string	✅	✅	Unique identifier (UUID)
`updatedAt`	datetime	✅	✅	Last modification timestamp

📝 Note: Auto-generated fields are set by the service and should not be included in create/update requests. Schema enforces additionalProperties: false - only defined fields are allowed.

🔐 Authentication Headers

For protected endpoints, include the following headers:

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

⚠️ Important: The x-nb-fingerprint header is required for all authenticated requests if fingerprint was specified during authorization. Without it, requests will return 401 Unauthorized.

🔧 API Endpoints

📺 Channel Operations

1. Create Channel

Creates a new chat channel with the provided information.

Request:

Method: POST
Path: /channels
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Enforced automatically (name and ownerId required; no additional properties)
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or self (ownerId matches authenticated user)

Request Body:

Field	Type	Required	Description
`name`	string	✅	Channel name/title
`ownerId`	string	✅	ID of the user who owns this channel

Response Body:

Field	Type	Description
`name`	string	Channel name/title
`ownerId`	string	ID of the user who owns this channel
`createdAt`	string	Creation timestamp
`id`	string	Unique channel identifier
`updatedAt`	string	Last update timestamp

Example Request:

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

Success Response:

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

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

Validation Error Examples:

Missing Required Field:

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

Schema Validation Error:

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

Additional Properties Error:

{
  "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. List Channels

Retrieves all channels with optional filtering and pagination.

Request:

Method: GET
Path: /channels
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Query parameter validation for name, ownerId, and pagination (page, limit)
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or self (when requesting own channels)

Query Parameters:

Parameter	Type	Required	Description
`name`	string	❌	Filter by channel name
`ownerId`	string	❌	Filter by owner ID
`page`	number	❌	Page number for pagination
`limit`	number	❌	Number of items per page

Response Body:

Field	Type	Description
`name`	string	Channel name/title
`ownerId`	string	ID of the user who owns this channel
`createdAt`	string	Creation timestamp
`id`	string	Unique channel identifier
`updatedAt`	string	Last update timestamp

Example Request:

curl http://localhost:8089/channels

Success Response:

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

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

3. Get Channel

Retrieves a specific channel by ID.

Request:

Method: GET
Path: /channels/:channelId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Path parameter validation for channel ID
Route Validators:
- Require authenticated request (bearer token)
- Require admin role, channel owner, or active subscription to the channel

Example Request:

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

4. Update Channel

Updates an existing channel's properties.

Request:

Method: PATCH
Path: /channels/:channelId
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Partial update schema (all fields optional; no additional properties)
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or channel owner

Request Body:

Field	Type	Required	Description
`name`	string	❌	New channel name/title
`ownerId`	string	❌	New owner ID

Response Body:

Field	Type	Description
`name`	string	Updated channel name/title
`ownerId`	string	Updated owner ID
`createdAt`	string	Creation timestamp
`id`	string	Unique channel identifier
`updatedAt`	string	Last update timestamp

Example Request:

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

5. Delete Channel

Removes a channel and all associated data.

Request:

Method: DELETE
Path: /channels/:channelId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Path parameter validation for channel ID
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or channel owner

Response Body:

Field	Type	Description
No response body	-	Delete endpoint returns no response body on success

Example Request:

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

Success Response:

Status: 204 No Content
Body: (empty)

Not Found Error Example:

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

📋 Subscription Operations

6. Create Subscription

Creates a new subscription to a channel.

Request:

Method: POST
Path: /subscriptions
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Enforced automatically (channelId and subscribedId required; no additional properties)
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or self (subscriber is the authenticated user)

Request Body:

Field	Type	Required	Description
`channelId`	string	✅	ID of the channel to subscribe to
`approved`	boolean	❌	Whether the subscription is approved
`permissions`	array	❌	Array of permission strings
`subscribedAt`	string	❌	Timestamp when subscription was created
`subscribedId`	string	❌	ID of the user subscribing

Response Body:

Field	Type	Description
`channelId`	string	ID of the channel being subscribed to
`subscribedId`	string	ID of the user subscribing
`approved`	boolean	Whether the subscription is approved
`permissions`	array	Array of permission strings
`subscribedAt`	string	Timestamp when subscription was created
`createdAt`	string	Creation timestamp
`id`	string	Unique subscription identifier
`updatedAt`	string	Last update timestamp

Example Request:

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"]
  }'

Success Response:

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"
}

Validation Error Example:

{
  "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",
    ]
  }
}

7. List Subscriptions

Retrieves all subscriptions with optional filtering and pagination.

Request:

Method: GET
Path: /subscriptions
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Query parameter validation for approved, channelId, subscribedAt, subscribedId, and pagination (page, limit)
Route Validators:
- Require authenticated request (bearer token)
- Require admin role, active subscription to the channel, channel owner, or self (subscriber)

Query Parameters:

Parameter	Type	Required	Description
`approved`	boolean	❌	Filter by approval status
`channelId`	string	❌	Filter by channel ID
`subscribedId`	string	❌	Filter by subscriber ID
`subscribedAt`	string	❌	Filter by subscription date
`page`	number	❌	Page number for pagination
`limit`	number	❌	Number of items per page

Response Body:

Field	Type	Description
`channelId`	string	ID of the channel being subscribed to
`subscribedId`	string	ID of the user subscribing
`approved`	boolean	Whether the subscription is approved
`permissions`	array	Array of permission strings
`subscribedAt`	string	Timestamp when subscription was created
`createdAt`	string	Creation timestamp
`id`	string	Unique subscription identifier
`updatedAt`	string	Last update timestamp

Example Request:

curl http://localhost:8089/subscriptions

8. Get Subscription

Retrieves a specific subscription by ID.

Request:

Method: GET
Path: /subscriptions/:subscriptionId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Path parameter validation for subscription ID
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or subscription owner

Example Request:

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

9. Delete Subscription

Removes a subscription (unsubscribe from channel).

Request:

Method: DELETE
Path: /subscriptions/:subscriptionId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Path parameter validation for subscription ID
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or subscription owner

Response Body:

Field	Type	Description
No response body	-	Delete endpoint returns no response body on success

Example Request:

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

Success Response:

Status: 204 No Content
Body: (empty)

Not Found Error Example:

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

💬 Message Operations

10. Create Message

Sends a new message to a channel.

Request:

Method: POST
Path: /messages
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Enforced automatically (content, senderId, and channelId required; no additional properties)
Route Validators:
- Require authenticated request (bearer token)
- Require self as sender
- Require active subscription to the channel

Request Body:

Field	Type	Required	Description
`channelId`	string	✅	ID of the channel where message is sent
`content`	string	✅	Message content/text
`senderId`	string	✅	ID of the user sending the message
`title`	string	❌	Optional message title

Response Body:

Field	Type	Description
`channelId`	string	ID of the channel where message is sent
`content`	string	Message content/text
`senderId`	string	ID of the user sending the message
`title`	string	Optional message title
`createdAt`	string	Creation timestamp
`id`	string	Unique message identifier
`updatedAt`	string	Last update timestamp

Example Request:

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

Success Response:

{
  "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"
}

Validation Error Example:

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

11. List Messages

Retrieves messages in a specific channel.

Request:

Method: GET
Path: /messages?channelId=:channelId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Query parameter validation for channelId (required), optional content, senderId, title, and pagination (page, limit)
Route Validators:
- Require authenticated request (bearer token)
- Require admin role, active subscription to the channel, or self as sender

Query Parameters:

Parameter	Type	Required	Description
`channelId`	string	✅	ID of the channel to get messages from
`content`	string	❌	Filter by message content
`senderId`	string	❌	Filter by sender ID
`title`	string	❌	Filter by message title
`page`	number	❌	Page number for pagination
`limit`	number	❌	Number of items per page

Response Body:

Field	Type	Description
`channelId`	string	ID of the channel where message is sent
`content`	string	Message content/text
`senderId`	string	ID of the user sending the message
`title`	string	Optional message title
`createdAt`	string	Creation timestamp
`id`	string	Unique message identifier
`updatedAt`	string	Last update timestamp

Example Request:

curl "http://localhost:8089/messages?channelId=test-channel-123"

Success Response:

[
  {
    "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"
  }
]

Validation Error Example:

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

12. Get Message by ID

Retrieves a specific message by ID.

Request:

Method: GET
Path: /messages/:messageId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Path parameter validation for message ID
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or message owner

Example Request:

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

Success Response:

{
  "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"
}

Not Found Error Example:

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

13. Update Message

Updates an existing message's content.

Request:

Method: PATCH
Path: /messages/:messageId
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Partial update schema (all fields optional; path parameter validation for message ID; no additional properties)
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or message owner

Request Body:

Field	Type	Required	Description
`content`	string	❌	Updated message content
`title`	string	❌	Updated message title

Response Body:

Field	Type	Description
`channelId`	string	ID of the channel where message is sent
`content`	string	Updated message content
`senderId`	string	ID of the user sending the message
`title`	string	Updated message title
`createdAt`	string	Creation timestamp
`id`	string	Unique message identifier
`updatedAt`	string	Last update timestamp

Example Request:

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

Success Response:

{
  "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"
}

Not Found Error Example:

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

14. Delete Message

Removes a message from a channel.

Request:

Method: DELETE
Path: /messages/:messageId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Validation:

Schema Validation: Path parameter validation for message ID
Route Validators:
- Require authenticated request (bearer token)
- Require admin role or message owner

Response Body:

Field	Type	Description
No response body	-	Delete endpoint returns no response body on success

Example Request:

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

Success Response:

Status: 204 No Content
Body: (empty)

Not Found Error Example:

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

📝 Message Template Operations

16. Create Message Template

Creates a new chat message template for reusable messaging content with proper validation and error handling.

Request:

Method: POST
Path: /message-templates
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Request Body:

Field	Type	Required	Description
`content`	string	✅	Template message content
`title`	string	✅	Template title/description
`organizationId`	string	❌	Organization identifier for template scope
`permissions`	string[]	❌	Array of permission strings for access control

Validation:

Schema Validation: Enforced automatically (content and title required)
Route Validators: Require authenticated request (bearer token)

Example Request:

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",
    "permissions": ["read", "write"]
  }'

Success Response:

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

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

Validation Error Example:

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

17. Get Message Template by ID

Retrieves a specific chat message template by its unique identifier for reuse in messaging applications.

Request:

Method: GET
Path: /message-templates/:templateId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearer token required

Path Parameters:

templateId: string (required) - Unique identifier of the message template

Request Body:

Field	Type	Required	Description
No request body	-	No body required

Validation:

Schema Validation: Path parameter validation for template ID
Route Validators: Require authenticated request (bearer token)

Example Request:

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

Success Response:

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",
  "permissions": ["read", "write"],
  "title": "Welcome Message",
  "updatedAt": "2025-01-20T10:30:00.000Z"
}

Not Found Error Example:

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

⚙️ Configuration Options

Service Data Store

interface ChatServiceDataStore {
  identities: Collection;              // Required - User identities collection
  chatChannels: Collection;            // Required - Chat channels collection
  organizations?: Collection;          // Optional - Organizations collection
  subscriptions?: Collection;          // Optional - Channel subscriptions collection
  chatMessages: Collection;            // Required - Chat messages collection
  chatMessageTemplates?: Collection;   // Optional - Message templates collection
}

Service Configuration

interface ChatServiceConfiguration {
  authSecrets: {
    authEncSecret: string;    // JWT encryption secret
    authSignSecret: string;   // JWT signing secret
  };
  identity?: {
    typeIds?: {
      admin: string;          // Admin user type identifier
      guest: string;          // Guest user type identifier
      regular: string;        // Regular user type identifier
    };
  };
  organization?: {
    roles?: {
      admin: string;          // Admin organization role identifier
      member: string;         // Member organization role identifier
      owner: string;          // Owner organization role identifier
    };
  };
}

Configuration Details

The chat service configuration is organized into logical groups for security and user type management.

🔐 Security Settings

authSecrets - JWT token security secrets

Type: { authEncSecret: string; authSignSecret: string }
Description: Secret keys for JWT encryption and signing (used for token validation)
Required: Yes (for production)
Child Properties:
- authEncSecret: Secret key for JWT payload encryption
- authSignSecret: Secret key for JWT signature verification

👥 User Type Settings

identity.typeIds - User type identifier configuration

Type: { admin?: string; guest?: string; regular?: string }
Description: Custom user type identifiers for role-based access control
Default: undefined (uses default type validation)
Child Properties:
- admin: Admin user type identifier
  - Type: string
  - Description: Custom identifier for admin users
  - Use Case: Role-based access control for administrative operations
  - Example: "admin", "administrator", "superuser"
- guest: Guest user type identifier
  - Type: string
  - Description: Custom identifier for guest users
  - Use Case: Limited access for unauthenticated or temporary users
  - Example: "guest", "visitor", "anonymous"
- regular: Regular user type identifier
  - Type: string
  - Description: Custom identifier for regular users
  - Use Case: Standard user access permissions
  - Example: "user", "member", "customer"

🏢 Organization Settings

organization.roles - Organization role identifier configuration

Type: { admin?: string; member?: string; owner?: string }
Description: Custom organization role identifiers for role-based access control
Default: undefined (uses default role validation)
Child Properties:
- admin: Admin organization role identifier
  - Type: string
  - Description: Custom identifier for organization admin role
  - Use Case: Organization-level administrative operations
  - Example: "admin", "administrator", "org-admin"
- member: Member organization role identifier
  - Type: string
  - Description: Custom identifier for organization member role
  - Use Case: Standard organization membership permissions
  - Example: "member", "user", "participant"
- owner: Owner organization role identifier
  - Type: string
  - Description: Custom identifier for organization owner role
  - Use Case: Full organization ownership permissions
  - Example: "owner", "founder", "org-owner"

Example Configuration

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'
    }
  }
};

🚨 Error Handling

All chat service errors return JSON format with appropriate HTTP status codes:

Common Error Codes

Status	Error Message	Description
400	Validation Error	Invalid request body format or missing required fields
400	must have ownerId when creating a new channel	Missing ownerId field in request body
400	request body must have required property 'name'	Missing name field in request body
400	request body must have required property 'ownerId'	Missing ownerId field in request body
400	request body must have required property 'channelId'	Missing channelId field in request body
400	request body must have required property 'subscribedId'	Missing subscribedId field in request body
400	request body must have required property 'content'	Missing content field in request body
400	request body must have required property 'senderId'	Missing senderId field in request body
400	request body must NOT have additional properties	Request contains unsupported fields
400	query parameter 'channelId' is required	Missing required query parameter
400	Failed to create channel	Database insert operation failed to return an inserted ID
400	Failed to update channel	Update operation doesn't modify any data (no changes detected)
400	Failed to delete channel	Database deletion operation failed
400	Failed to create subscription	Database insert operation failed to return an inserted ID
400	Failed to delete subscription	Database deletion operation failed
400	Failed to create message	Database insert operation failed to return an inserted ID
400	Failed to update message	Update operation doesn't modify any data (no changes detected)
400	Failed to delete message	Database deletion operation failed
401	token could not be verified	Missing or invalid authorization token
401	Authentication failed	Missing or invalid authentication token
401	Token fails security check	Token security validation failed
403	User is not authorized to access this resource	User lacks required permissions (admin access)
404	Channel not found	Channel doesn't exist for the requested operation
404	Subscription not found	Subscription doesn't exist for the requested operation
404	Message not found	Message doesn't exist for the requested operation
404	Chat message not found	Chat message doesn't exist for the requested operation
500	Failed to create channel	Database connection issues or unexpected failures during creation
500	Failed to get channel	Database connection issues or unexpected failures during retrieval
500	Failed to find channels	Database connection issues, invalid filter syntax, or unexpected failures during listing
500	Failed to update channel	Database connection issues or unexpected failures during update
500	Failed to delete channel	Database connection issues or unexpected failures during deletion
500	Failed to create subscription	Database connection issues or unexpected failures during creation
500	Failed to get subscription	Database connection issues or unexpected failures during retrieval
500	Failed to find subscriptions	Database connection issues, invalid filter syntax, or unexpected failures during listing
500	Failed to delete subscription	Database connection issues or unexpected failures during deletion
500	Failed to create message	Database connection issues or unexpected failures during creation
500	Failed to get message	Database connection issues or unexpected failures during retrieval
500	Failed to find messages	Database connection issues, invalid filter syntax, or unexpected failures during listing
500	Failed to update message	Database connection issues or unexpected failures during update
500	Failed to delete message	Database connection issues or unexpected failures during deletion

Error Response Format

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

Validation Errors include additional details:

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

User Service - User management for chat participants
Organization Service - Team-based chat organization
Authentication Service - Authentication and authorization
Error Handling - Understanding error patterns
Schema Component - Data validation concepts
Custom Service Tutorial - Extend chat functionality

🚀 Quickstart​

📋 Endpoint Summary​

Channel Operations​

Subscription Operations​

Message Operations​

Message Template Operations​

🗄️ Entity Schemas​

Channel Entity​

Subscription Entity​

Message Entity​

🔐 Authentication Headers​

🔧 API Endpoints​

📺 Channel Operations​

1. Create Channel​

2. List Channels​

3. Get Channel​

4. Update Channel​

5. Delete Channel​

📋 Subscription Operations​

6. Create Subscription​

7. List Subscriptions​

8. Get Subscription​

9. Delete Subscription​

💬 Message Operations​

10. Create Message​

11. List Messages​

12. Get Message by ID​

13. Update Message​

14. Delete Message​

📝 Message Template Operations​

16. Create Message Template​

17. Get Message Template by ID​

⚙️ Configuration Options​

Service Data Store​

Service Configuration​

Configuration Details​

🔐 Security Settings​

👥 User Type Settings​

🏢 Organization Settings​

Example Configuration​

🚨 Error Handling​

Common Error Codes​

Error Response Format​

🔗 Related Documentation​

🚀 Quickstart

📋 Endpoint Summary

Channel Operations

Subscription Operations

Message Operations

Message Template Operations

🗄️ Entity Schemas

Channel Entity

Subscription Entity

Message Entity

🔐 Authentication Headers

🔧 API Endpoints

📺 Channel Operations

1. Create Channel

2. List Channels

3. Get Channel

4. Update Channel

5. Delete Channel

📋 Subscription Operations

6. Create Subscription

7. List Subscriptions

8. Get Subscription

9. Delete Subscription

💬 Message Operations

10. Create Message

11. List Messages

12. Get Message by ID

13. Update Message

14. Delete Message

📝 Message Template Operations

16. Create Message Template

17. Get Message Template by ID

⚙️ Configuration Options

Service Data Store

Service Configuration

Configuration Details

🔐 Security Settings

👥 User Type Settings

🏢 Organization Settings

Example Configuration

🚨 Error Handling

Common Error Codes

Error Response Format

🔗 Related Documentation