asyncapi: 2.5.0
info:
  title: RoomStream WebSocket API
  description: Real-time WebSocket events for chat room management using Socket.IO
  version: 1.1.0
  contact: {}
tags: []
servers:
  production:
    url: wss://your-domain.com/ws/rooms
    protocol: wss
    description: Production WebSocket server
  development:
    url: ws://localhost:3000/ws/rooms
    protocol: ws
    description: Development WebSocket server
components:
  schemas:
    SupabaseUserInfo:
      type: object
      properties:
        id:
          type: string
          description: Supabase user ID
          example: 550e8400-e29b-41d4-a716-446655440000
        email:
          type: object
          description: User email
          example: user@example.com
          nullable: true
        name:
          type: object
          description: User display name
          example: John Doe
          nullable: true
      required:
        - id
        - email
        - name
    ParticipantInfo:
      type: object
      properties:
        clientId:
          type: string
          description: Client socket ID or user ID
          example: xW3kJ9pL2mN8qR5t
        name:
          type: object
          description: Participant display name
          example: John Doe
          nullable: true
        supabaseUser:
          description: Supabase user data if authenticated
          allOf:
            - $ref: '#/components/schemas/SupabaseUserInfo'
      required:
        - clientId
        - name
    RecentMessage:
      type: object
      properties:
        id:
          type: string
          description: Message unique ID
          example: msg_1234567890_abc123
        clientId:
          type: string
          description: Sender client ID
          example: xyz789
        event:
          type: string
          description: Event type
          example: message
        message:
          type: string
          description: Message content
          example: Hello everyone!
        timestamp:
          format: date-time
          type: string
          description: Message timestamp
          example: '2024-01-15T10:30:00.000Z'
      required:
        - id
        - clientId
        - event
        - message
        - timestamp
    JoinedRoomEvent:
      type: object
      properties:
        roomId:
          type: string
          description: Room unique ID
          example: room_1234567890_abc123
        roomName:
          type: string
          description: Room display name
          example: General Chat
        participants:
          description: List of current participants
          type: array
          items:
            $ref: '#/components/schemas/ParticipantInfo'
        recentMessages:
          description: Last 10 messages in the room
          type: array
          items:
            $ref: '#/components/schemas/RecentMessage'
      required:
        - roomId
        - roomName
        - participants
        - recentMessages
    JoinRoomDto:
      type: object
      properties:
        roomId:
          type: string
          description: Room ID to join
          example: room_1737550000000_abc123def
        participantName:
          type: string
          description: Display name for the participant (optional for authenticated users)
          example: John Doe
      required:
        - roomId
    LeftRoomEvent:
      type: object
      properties:
        roomId:
          type: string
          description: Room unique ID
          example: room_1234567890_abc123
      required:
        - roomId
    LeaveRoomDto:
      type: object
      properties:
        roomId:
          type: string
          description: Room ID to leave
          example: room_1737550000000_abc123def
      required:
        - roomId
    ApplicationInfo:
      type: object
      properties:
        id:
          type: string
          description: Application ID
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Application name
          example: My Chat Bot
        createdBy:
          type: string
          description: User ID who created the application
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - id
        - name
        - createdBy
    NewMessageEvent:
      type: object
      properties:
        id:
          type: string
          description: Message unique ID
          example: msg_1737550000000_abc123def
        clientId:
          type: string
          description: Sender client ID
          example: xW3kJ9pL2mN8qR5t
        userId:
          type: string
          description: Sender user ID (if authenticated)
          example: 550e8400-e29b-41d4-a716-446655440000
        event:
          type: string
          description: Event type
          example: message
        message:
          type: string
          description: Message content
          example: Hello everyone!
        timestamp:
          format: date-time
          type: string
          description: Message timestamp
          example: '2024-01-15T10:30:00.000Z'
        roomId:
          type: string
          description: Room ID where message was sent
          example: room_1737550000000_abc123def
        supabaseUser:
          description: Supabase user data if authenticated
          allOf:
            - $ref: '#/components/schemas/SupabaseUserInfo'
        application:
          description: Application data if sent via app key
          allOf:
            - $ref: '#/components/schemas/ApplicationInfo'
        isApplication:
          type: boolean
          description: Whether the sender is an application
          example: false
      required:
        - id
        - clientId
        - event
        - message
        - timestamp
        - roomId
        - isApplication
    SendMessageDto:
      type: object
      properties:
        roomId:
          type: string
          description: Room ID to send the message to
          example: room_1737550000000_abc123def
        message:
          type: string
          description: Message content to send
          example: Hello everyone!
        event:
          type: string
          description: Custom event name (defaults to "message")
          example: message
          default: message
      required:
        - roomId
        - message
    RoomInfoEvent:
      type: object
      properties:
        id:
          type: string
          description: Room unique ID
          example: room_1234567890_abc123
        name:
          type: string
          description: Room display name
          example: General Chat
        participantCount:
          type: number
          description: Number of participants
          example: 5
        participants:
          description: List of current participants
          type: array
          items:
            $ref: '#/components/schemas/ParticipantInfo'
        messageCount:
          type: number
          description: Total number of messages
          example: 42
        createdAt:
          format: date-time
          type: string
          description: Room creation timestamp
          example: '2024-01-15T10:00:00.000Z'
      required:
        - id
        - name
        - participantCount
        - participants
        - messageCount
        - createdAt
    GetRoomInfoDto:
      type: object
      properties:
        roomId:
          type: string
          description: Room ID to get information about
          example: room_1737550000000_abc123def
      required:
        - roomId
    ParticipantNameUpdatedEvent:
      type: object
      properties:
        clientId:
          type: string
          description: Client socket ID
          example: abc123xyz
        participantName:
          type: string
          description: New participant name
          example: Jane Doe
        roomId:
          type: string
          description: Room unique ID
          example: room_1234567890_abc123
      required:
        - clientId
        - participantName
        - roomId
    UpdateParticipantNameDto:
      type: object
      properties:
        roomId:
          type: string
          description: Room ID where to update the name
          example: room_1737550000000_abc123def
        participantName:
          type: string
          description: New display name for the participant
          example: Jane Doe
          maxLength: 50
      required:
        - roomId
        - participantName
    RoomDeletedEvent:
      type: object
      properties:
        roomId:
          type: string
          description: Room unique ID
          example: room_1234567890_abc123
        roomName:
          type: string
          description: Room display name
          example: General Chat
        message:
          type: string
          description: Deletion message
          example: A sala "General Chat" foi deletada
      required:
        - roomId
        - roomName
        - message
    ErrorEvent:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Sala não encontrada
      required:
        - message
    TokenExpiredEvent:
      type: object
      properties:
        message:
          type: string
          description: Expiration message
          example: Your session has expired. Please log in again.
        userId:
          type: string
          description: User ID of the expired session
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - message
        - userId
defaultContentType: application/json
channels:
  joinedRoom:
    subscribe:
      summary: Room joined confirmation
      description: >-
        Sent to client after successfully joining a room with room details and
        recent messages.
      message:
        name: joinedRoom
        payload:
          $ref: '#/components/schemas/JoinedRoomEvent'
  joinRoom:
    publish:
      summary: Join a chat room
      description: >-
        Client requests to join a specific room. Returns room info and recent
        messages.
      message:
        name: joinRoom
        payload:
          $ref: '#/components/schemas/JoinRoomDto'
  leftRoom:
    subscribe:
      summary: Room left confirmation
      description: Sent to client after successfully leaving a room.
      message:
        name: leftRoom
        payload:
          $ref: '#/components/schemas/LeftRoomEvent'
  leaveRoom:
    publish:
      summary: Leave a chat room
      description: Client requests to leave a specific room.
      message:
        name: leaveRoom
        payload:
          $ref: '#/components/schemas/LeaveRoomDto'
  '{eventName}':
    subscribe:
      summary: Custom event broadcast
      description: >-
        Dynamic event emitted to all room participants. Event name is defined by
        the "event" field in emit payload (default: "message").
      message:
        name: customEvent
        payload:
          $ref: '#/components/schemas/NewMessageEvent'
  emit:
    publish:
      summary: Emit custom event to room
      description: >-
        Send a custom event with any payload to all participants in a room. The
        event name is customizable.
      message:
        name: emit
        payload:
          $ref: '#/components/schemas/SendMessageDto'
  sendMessage:
    publish:
      summary: Send message to room (deprecated)
      description: >-
        Alias for "emit" event. Use "emit" instead. Sends a message with event
        type "message".
      message:
        name: sendMessage
        payload:
          $ref: '#/components/schemas/SendMessageDto'
  roomInfo:
    subscribe:
      summary: Room information response
      description: Response containing room details, participants list, and statistics.
      message:
        name: roomInfo
        payload:
          $ref: '#/components/schemas/RoomInfoEvent'
  getRoomInfo:
    publish:
      summary: Get room information
      description: >-
        Request detailed information about a specific room including
        participants and message count.
      message:
        name: getRoomInfo
        payload:
          $ref: '#/components/schemas/GetRoomInfoDto'
  participantNameUpdated:
    subscribe:
      summary: Participant name updated notification
      description: >-
        Broadcast to all room participants when someone updates their display
        name.
      message:
        name: participantNameUpdated
        payload:
          $ref: '#/components/schemas/ParticipantNameUpdatedEvent'
  updateParticipantName:
    publish:
      summary: Update participant name
      description: >-
        Update the display name of the current participant. Only available for
        anonymous users.
      message:
        name: updateParticipantName
        payload:
          $ref: '#/components/schemas/UpdateParticipantNameDto'
  roomDeleted:
    subscribe:
      summary: Room deleted notification
      description: Broadcast to all room participants when a room is deleted via REST API.
      message:
        name: roomDeleted
        payload:
          $ref: '#/components/schemas/RoomDeletedEvent'
  error:
    subscribe:
      summary: Error notification
      description: >-
        Sent to client when an operation fails (authentication, room not found,
        etc.).
      message:
        name: error
        payload:
          $ref: '#/components/schemas/ErrorEvent'
  tokenExpired:
    subscribe:
      summary: Token expired notification
      description: >-
        Sent to client when Supabase JWT token expires. Client will be
        disconnected.
      message:
        name: tokenExpired
        payload:
          $ref: '#/components/schemas/TokenExpiredEvent'