Initial commit: nick docs

03 - API Reference/Chat API.md

@@ -0,0 +1,144 @@
+---
+title: Chat API
+tags: [api, chat, reference]
+---
+
+# Chat API
+
+All chat endpoints live under `/api/chat/*`. The router is [`backend/src/services/chat/chatRoutes.ts`](../../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:**
+```ts
+{
+  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:**
+```ts
+{
+  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]].
+
+## Related
+
+- [[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)