Files

Siavash Sameni 7a616744f4 docs: complete code-reality alignment for remaining docs + reconcile issue set

Remaining docs updated to match code (the docs that the first pass had not covered):
- Flows: Chat, Referral, Rating, Registration, Google OAuth, Negotiation, Payout,
  Trezor Safekeeping — corrected endpoints, socket events, status enums, auth gaps
- API Reference: User API, Trezor API — admin route prefix/verb/status corrections,
  added undocumented endpoints (ton-proof challenge, profile email verify,
  GET /trezor/account, POST /trezor/verify-operation)
- Data Models: Chat, Notification, Payment, PointTransaction, User — corrected
  enums (PaymentProvider, escrowState, PointTransaction.type, User.status),
  90-day notification TTL, soft-delete semantics, wallet fields

Trezor "zero frontend" finding (audit C31/C32) corrected as STALE:
- Verified current code HAS a full frontend Trezor implementation (admin/trezor
  page, TrezorSettingsView, trezorConnector via @trezor/connect-web,
  TrezorSignDialog, actions/trezor.ts building the {message,signature} object)
- Fixed Trezor Safekeeping Flow doc (removed false "no frontend" warnings)
- Reclassified ISSUE-012 as invalid/superseded with explanation

Issue set reconciled to a single canonical numbering (ISSUE-001..054):
- Adopted the comprehensive 51-issue set (long-slug, fully indexed)
- Removed 35 superseded short-slug duplicates from the first pass
- Removed a duplicate ISSUE-046 file
- Added 3 issues the 51-set lacked: ISSUE-052 (completed-not-counted-in-stats),
  ISSUE-053 (axios 401-only interceptor), ISSUE-054 (rate limiter counts all attempts)
- Regenerated Issues Index: 53 open (14 critical, 39 major) + 1 invalid

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-05-29 15:15:02 +04:00

6.1 KiB

Raw Blame History

title, tags

title

Chat API

Last updated: 2026-05-29 — aligned with code (see Doc vs Code Audit Report)

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.

Rate limits and constraints

Rule	Value
Messages per user per minute	20
Edit window	15 minutes after send
Maximum message length	5 000 characters

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.

PUT /api/chat/:id/archive

Description: Toggle archived state for the caller (per-user flag). Calling this endpoint on an already-archived chat unarchives it (toggle semantics). 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 }] } } }

⚠️ KNOWN BUG — The frontend sendFileMessage function incorrectly posts to POST /api/chat/:id/messages (the plain-text endpoint) instead of POST /api/chat/:id/messages/file. File uploads are currently broken as a result; the attachment is silently dropped or the request is rejected.

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

Description: Mark messages as read for the caller. Passing an empty messageIds array (or omitting it) marks all messages in the chat as read. 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 the 15-minute 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)

6.1 KiB Raw Blame History