asyncapi: "2.6.0"
info:
  title: Realtog User Chat WebSocket API
  version: "1.0.0"
  description: |
    WebSocket API for Realtog User-Admin Chat System.
    
    ## Overview
    This API enables real-time messaging between users and admins/support staff.
    Users can send messages to admins and receive responses in real-time.
    
    ## Authentication
    - Connect with JWT token: `{ auth: { token: 'your-jwt-token' } }`
    - Token obtained from `/auth/login` or `/auth/register` endpoints
    
    ## User Flow
    1. Connect to WebSocket with JWT token
    2. Automatically joins `user:{userId}` room
    3. Join specific chat with `user-admin:join` event
    4. Send/receive messages in real-time
    5. Receive chat updates (unread count, new messages)
    
servers:
  production:
    url: https://your-production-url.com
    protocol: socket.io
    description: Production server
  development:
    url: http://localhost:3000
    protocol: socket.io
    description: Development server
channels:
  /:
    publish:
      description: |
        Events that the client (user app) sends to the server.
        All events require WebSocket authentication.
      message:
        oneOf:
          - $ref: "#/components/messages/UserAdminJoin"
          - $ref: "#/components/messages/UserAdminLeave"
    subscribe:
      description: |
        Events that the server sends to the client (user app).
        These are received automatically when subscribed to the relevant rooms.
      message:
        oneOf:
          - $ref: "#/components/messages/Error"
          - $ref: "#/components/messages/UserAdminNewMessage"
          - $ref: "#/components/messages/UserAdminChatUpdated"

components:
  messages:
    UserAdminJoin:
      name: user-admin:join
      title: Join User-Admin Chat Room
      summary: |
        Join a specific chat room to receive real-time messages.
        Call this after opening a chat conversation.
      payload:
        type: string
        description: |
          The chatId to join. Get this from GET /messages/user-admin/chat endpoint.
      examples:
        - name: JoinUserChat
          summary: User joins their chat with admin
          payload: "507f1f77bcf86cd799439011"

    UserAdminLeave:
      name: user-admin:leave
      title: Leave User-Admin Chat Room
      summary: |
        Leave a chat room when navigating away from the conversation.
        This stops receiving real-time updates for that specific chat.
      payload:
        type: string
        description: The chatId to leave.
      examples:
        - name: LeaveUserChat
          summary: User leaves their chat
          payload: "507f1f77bcf86cd799439011"

    Error:
      name: error
      title: Error Message
      summary: Server sends an error message to the client.
      payload:
        type: object
        properties:
          message:
            type: string
            description: Error description.

    UserAdminNewMessage:
      name: user-admin:new-message
      title: New Message Received
      summary: |
        Emitted when a new message is sent in the chat.
        You receive this if you're joined to the chat room (user-admin:join).
        
        **Important:** When user receives this while viewing the chat,
        call POST /messages/user-admin/chat/:chatId/read to mark as read.
      payload:
        type: object
        required:
          - id
          - chatId
          - senderId
          - senderName
          - senderType
          - content
          - timestamp
          - read
        properties:
          id:
            type: string
            description: Unique message ID
          chatId:
            type: string
            description: Chat room ID this message belongs to
          senderId:
            type: string
            description: ID of the user who sent the message
          senderName:
            type: string
            description: Name of the sender
          senderType:
            type: string
            enum: [user, admin]
            description: Type of sender (user or admin/support)
          content:
            type: string
            description: Text content of the message
          timestamp:
            type: string
            format: date-time
            description: When the message was sent
          read:
            type: boolean
            description: Whether current user has read this message
          images:
            type: array
            items:
              type: string
              format: uri
            description: Array of image URLs attached to the message
      examples:
        - name: AdminReply
          summary: Admin sends a reply to user
          payload:
            id: "60d5ec49f1b2c72b8c8e4f2a"
            chatId: "507f1f77bcf86cd799439011"
            senderId: "admin123"
            senderName: "Support Team"
            senderType: "admin"
            content: "Hello! How can I help you today?"
            timestamp: "2024-01-29T10:30:00Z"
            read: false
            images: []

    UserAdminChatUpdated:
      name: user-admin:chat-updated
      title: Chat Summary Updated
      summary: |
        Emitted when chat metadata changes (new message, unread count, etc.).
        Use this to update your chat list UI in real-time.
        
        **Triggers:**
        - New message sent/received
        - Messages marked as read
        - User/admin comes online/offline
      payload:
        type: object
        required:
          - id
          - userId
          - userName
          - userEmail
          - initials
          - unreadCount
          - online
        properties:
          id:
            type: string
            description: Chat ID
          userId:
            type: string
            description: User ID in this chat (for users, this is their own ID)
          userName:
            type: string
            description: Name of the user
          userEmail:
            type: string
            description: Email of the user
          initials:
            type: string
            description: User initials for avatar display
          lastMessage:
            type: string
            description: Preview of the last message in chat
          lastMessageTime:
            type: string
            format: date-time
            description: Timestamp of last message
          unreadCount:
            type: integer
            description: Number of unread messages for current user
          online:
            type: boolean
            description: Whether the other party (admin) is online
      examples:
        - name: NewMessageUpdate
          summary: Chat updated after new message
          payload:
            id: "507f1f77bcf86cd799439011"
            userId: "user123"
            userName: "John Doe"
            userEmail: "john@example.com"
            initials: "JD"
            lastMessage: "Thank you for your help!"
            lastMessageTime: "2024-01-29T10:35:00Z"
            unreadCount: 0
            online: true
        - name: UnreadCountUpdate
          summary: Chat updated with new unread count
          payload:
            id: "507f1f77bcf86cd799439011"
            userId: "user123"
            userName: "John Doe"
            userEmail: "john@example.com"
            initials: "JD"
            lastMessage: "Your order has been processed"
            lastMessageTime: "2024-01-29T10:40:00Z"
            unreadCount: 1
            online: true