"/admin/account/{bigscreenAccountId}/message":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    post:
        tags: [Accounts]
        operationId: adminMessageUser
        summary: Send an admin message to a user
        description: |
            Sends a message that surfaces in the user's VR client (or
            website connection) — used for warnings, system notifications,
            or moderator-to-user contact. **Returns plain text `OK`** —
            not JSON.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [message]
                        properties:
                            message: { type: string }
                            severity:
                                type: string
                                enum: [info, warning, urgent]
                            persist:
                                type: boolean
                                description: When true, the message is also queued for delivery if the user is offline.
        responses:
            "200":
                description: Message dispatched. Body is the literal string `OK`.
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Account has no live connections (and `persist` is false).
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]

"/admin/account/{bigscreenAccountId}/connections":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Accounts]
        operationId: getAccountConnections
        summary: Live connections for an account
        description: |
            Lists active VR / website / cloud connections currently attributed to the
            account. For each connection, includes the room id the user is in
            (rooms with private visibility are surfaced as the literal `"hidden"`).
        responses:
            "200":
                description: Active connections.
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                type: object
                                required: [userSessionId, data]
                                properties:
                                    userSessionId: { type: string }
                                    currentRoomId:
                                        type: [string, "null"]
                                        description: The room id the user is currently in, or `"hidden"` for private rooms, or null.
                                    data:
                                        type: object
                                        description: Public projection of the user session (`BigscreenUser.toPublicObject()`).
                                        additionalProperties: true
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]

"/admin/account/{bigscreenAccountId}/rooms":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Accounts]
        operationId: getRoomsForAccount
        summary: Rooms an account is in or owns (stub — always empty)
        description: |
            **Stub** — `getRoomsForAccount` in
            `cloud/src/CloudAdminApi.ts` returns `[]` unconditionally.
            Endpoint is registered for parity with the rest of the room
            CRUD; expect this to come back online later.
        deprecated: true
        responses:
            "200":
                description: Always returns an empty array.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/LiveRoom.yaml" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]

"/admin/account/{bigscreenAccountId}/disconnect":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Accounts]
        operationId: disconnectAccount
        summary: Force-disconnect all of an account's sessions
        description: |
            Severs every active VR / website connection on the account. Used as
            part of banning flows. Returns the literal text `"OK"` on success.
        responses:
            "200":
                description: '"OK".'
                content:
                    text/plain:
                        schema: { type: string, example: "OK" }
            "401": { $ref: "../cloud-admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../cloud-admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: User has no live connections.
                content:
                    application/json:
                        schema: { $ref: "../cloud-admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]
