nick/nick-doc

Fork 0

Files

moojttaba 0da235ae27 Initial commit: nick docs

2026-05-23 20:35:34 +03:30

5.3 KiB

Raw Blame History

title, tags

title

Chat API

All chat endpoints live under /api/chat/*. The router is backend/src/services/chat/chatRoutes.ts, controller is chatController, service is ChatService. Every endpoint requires Bearer JWT — the router applies authenticateToken globally.

Model: Chat. Real-time delivery happens over Socket.IO rooms named chat-<chatId>. Clients must call join-chat-room after connecting. See Socket Events for new-message, messages-read, message-edited, message-deleted, participants-added, participant-removed, and user-typing payloads.

Conversations

POST /api/chat

Description: Create a generic chat between two or more participants. Auth required: Bearer JWT Request body:

{
  participantIds: string[];     // 2+ user ids (caller is added automatically)
  type?: "direct" | "group";    // default "direct"
  title?: string;               // group only
  metadata?: Record<string, unknown>;
}

Response 201: { success: true, data: { chat: { _id, participants, type, ... } } } Errors: 400 need 2+ participants, 404 participant not found.

POST /api/chat/purchase-request

Description: Create (or fetch the existing) chat tied to a specific PurchaseRequest between buyer and seller. Idempotent. Auth required: Bearer JWT Request body: { purchaseRequestId: string; sellerId: string } Response 200/201: { success: true, data: { chat } }

POST /api/chat/support

Description: Open a support chat. Adds the caller and the support/admin pool. Used by the in-app help widget. Auth required: Bearer JWT Request body: { subject?: string; initialMessage?: string } Response 201: { success: true, data: { chat } }

GET /api/chat

Description: List the caller's chats, ordered by latest message. Includes unread counts. Auth required: Bearer JWT Query params: page, limit, type (direct | group | support) Response 200: { success, data: { chats: [...], pagination } }

GET /api/chat/stats

Description: Aggregate counts (total chats, total messages, total unread). Auth required: Bearer JWT

GET /api/chat/:id/info

Description: Full chat metadata: participants (populated), title, type, created-at, last message, unread per user. Auth required: Bearer JWT (participant) Errors: 403 not a participant, 404 not found.

PATCH /api/chat/:id/archive

Description: Toggle archived state for the caller (per-user flag). Auth required: Bearer JWT (participant)

POST /api/chat/:id/participants

Description: Add a participant to a group chat. Auth required: Bearer JWT (creator/admin) Request body: { userId: string } Side effects: Emits participants-added on chat-<id>.

DELETE /api/chat/:id/participants/:participantId

Description: Remove a participant from a group chat. Auth required: Bearer JWT (creator/admin) Side effects: Emits participant-removed on chat-<id>.

Messages

GET /api/chat/:id/messages

Description: Paginated message history (newest first by default). Auth required: Bearer JWT (participant) Query params: page, limit, before (cursor by createdAt)

POST /api/chat/:id/messages

Description: Send a text message. Auth required: Bearer JWT (participant) Request body:

{
  content: string;
  type?: "text" | "system";       // default "text"
  replyToMessageId?: string;
  metadata?: Record<string, unknown>;
}

Response 201: { success, data: { message } } Side effects: Emits new-message on chat-<chatId>; increments unread for other participants.

POST /api/chat/:id/messages/file

Description: Send a message with a binary attachment. Multipart form (file field). Maxes follow the File API limits. Auth required: Bearer JWT (participant) Form fields:

file - the file blob
content? - optional caption
replyToMessageId? - optional

Response 201: { success, data: { message: { attachments: [{ url, filename, mimeType, size }] } } }

PATCH /api/chat/:id/messages/read

Description: Mark all unread messages up to the latest as read for the caller. Auth required: Bearer JWT (participant) Response 200: { success, data: { modifiedCount } } Side effects: Emits messages-read on chat-<id>.

PUT /api/chat/:id/messages/:messageId

Description: Edit an existing message (author only, within edit window). Auth required: Bearer JWT (message author) Request body: { content: string } Side effects: Emits message-edited on chat-<id>.

DELETE /api/chat/:id/messages/:messageId

Description: Soft-delete a message (author or admin). The record stays but deletedAt is set and content is cleared. Auth required: Bearer JWT (author or admin) Side effects: Emits message-deleted on chat-<id>.

Typing indicator

Typing indicators are not REST endpoints — clients emit typing-start and typing-stop over Socket.IO. The server broadcasts user-typing to the chat room. Full details in Socket Events.

Chat
Chat Flow
File API (for attachment uploads)
Notification API (for out-of-band notifications when a chat message is received and the user is offline)

5.3 KiB Raw Blame History