mud_server.admin_gradio.api.auth
================================

.. py:module:: mud_server.admin_gradio.api.auth

.. autoapi-nested-parse::

   Authentication API client for MUD Server.

   This module handles all authentication-related API operations:
   - User login with password authentication
   - New user registration
   - User logout and session cleanup

   All functions follow a consistent pattern:
       - Validate input using validators module
       - 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
           "data": dict | None,     # Additional data (session_id, role, etc.)
           "error": str | None,     # Error details if failed
       }



Attributes
----------

.. autoapisummary::

   mud_server.admin_gradio.api.auth.logger


Classes
-------

.. autoapisummary::

   mud_server.admin_gradio.api.auth.AuthAPIClient


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

.. py:data:: logger

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

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


   API client for authentication operations.

   This client handles login, registration, and logout operations,
   providing clean separation between API logic and UI concerns.

   .. admonition:: Example

      >>> client = AuthAPIClient()
      >>> result = client.login("alice", "password123")
      >>> if result["success"]:
      ...     print(f"Logged in: {result['data']['session_id']}")

   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:: login(username, password)

      Authenticate user and create session.

      Validates credentials, sends login request to backend, and returns
      session data on success.

      :param username: Username to login with
      :param password: Plain text password

      :returns:

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

      .. admonition:: Examples

         >>> client = AuthAPIClient()
         >>> result = client.login("alice", "password123")
         >>> result["success"]
         True
         >>> result["data"]["role"]
         'player'



   .. py:method:: register(username, password, password_confirm)

      Register a new user account.

      Validates input, sends registration request to backend API, and returns
      status message indicating success or failure.

      :param username: Desired username for new account
      :param password: Plain text password for new account
      :param password_confirm: Password confirmation (must match password)

      :returns:

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

      .. admonition:: Examples

         >>> client = AuthAPIClient()
         >>> result = client.register("bob", "password123", "password123")
         >>> result["success"]
         True
         >>> "You can now login" in result["message"]
         True



   .. py:method:: logout(session_id)

      Logout user and clean up session.

      Sends logout request to backend API and returns confirmation.

      :param session_id: Session ID to logout (can be None if not logged in)

      :returns:

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

      .. admonition:: Examples

         >>> client = AuthAPIClient()
         >>> result = client.logout("abc123")
         >>> result["success"]
         True
         >>> result["message"]
         'You have been logged out.'