mud_server.admin_gradio.api.admin
=================================

.. py:module:: mud_server.admin_gradio.api.admin

.. autoapi-nested-parse::

   Admin API client for MUD Server.

   This module handles all administrative operations:
   - Database viewing (players, sessions, chat messages)
   - User management (role changes, ban/unban)

   All functions require admin or superuser role and follow a consistent pattern:
       - Validate session state and admin permissions
       - Validate input
       - Make API request using BaseAPIClient
       - Return standardized response dictionaries

   Response Format:
       All functions return dictionaries with:
       {
           "success": bool,         # Whether operation succeeded
           "message": str,          # User-facing message or formatted data
           "data": None,
           "error": str | None,     # Error details if failed
       }



Classes
-------

.. autoapisummary::

   mud_server.admin_gradio.api.admin.AdminAPIClient


Module Contents
---------------

.. py:class:: AdminAPIClient(server_url = None)

   Bases: :py:obj:`mud_server.admin_gradio.api.base.BaseAPIClient`


   API client for administrative operations.

   This client handles database viewing and user management operations
   that require admin or superuser permissions.

   .. admonition:: Example

      >>> client = AdminAPIClient()
      >>> result = client.get_database_players(
      ...     session_id="admin123",
      ...     role="admin"
      ... )
      >>> if result["success"]:
      ...     print(result["message"])

   Initialize the base API client.

   :param server_url: Optional server URL override. If not provided,
                      uses MUD_SERVER_URL environment variable or defaults
                      to http://localhost:8000


   .. py:method:: get_database_players(session_id, role)

      Fetch and format all users from database (Admin/Superuser only).

      Returns detailed information about all accounts including:
      - ID, username, role, status
      - Character count and guest flags
      - Created date and last login
      - Password hash prefix

      :param session_id: User's session ID from login
      :param role: User's role (for permission checking)

      :returns:

                {
                    "success": bool,
                    "message": str,          # Formatted player table
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = AdminAPIClient()
         >>> result = client.get_database_players("admin123", "admin")
         >>> result["success"]
         True
         >>> "PLAYERS TABLE" in result["message"]
         True



   .. py:method:: get_database_sessions(session_id, role)

      Fetch and format all active sessions from database (Admin/Superuser only).

      Returns information about all active sessions including:
      - Session ID and username
      - Connection time and last activity

      :param session_id: User's session ID from login
      :param role: User's role (for permission checking)

      :returns:

                {
                    "success": bool,
                    "message": str,          # Formatted sessions table
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure



   .. py:method:: get_database_chat(session_id, role, limit = 50)

      Fetch and format recent chat messages from database (Admin/Superuser only).

      Returns recent chat messages from all rooms including:
      - Message ID, room, timestamp
      - Username and message content

      :param session_id: User's session ID from login
      :param role: User's role (for permission checking)
      :param limit: Maximum number of messages to retrieve (default: 50)

      :returns:

                {
                    "success": bool,
                    "message": str,          # Formatted chat messages
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure



   .. py:method:: manage_user(session_id, role, target_username, action, new_role = '')

      Perform user management actions (Admin/Superuser only).

      Supported actions:
      - change_role: Change user's role (requires new_role parameter)
      - ban: Ban/deactivate user account
      - unban: Unban/reactivate user account

      :param session_id: User's session ID from login
      :param role: User's role (for permission checking)
      :param target_username: Username of user to manage
      :param action: Action to perform (change_role, ban, unban)
      :param new_role: New role for change_role action (optional)

      :returns:

                {
                    "success": bool,
                    "message": str,
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = AdminAPIClient()
         >>> result = client.manage_user(
         ...     session_id="admin123",
         ...     role="admin",
         ...     target_username="alice",
         ...     action="change_role",
         ...     new_role="worldbuilder"
         ... )
         >>> result["success"]
         True