zafiaonline.api_client package

Subpackages

Submodules

zafiaonline.api_client.api_decorators module

Utility decorators for user validation and message handling in MafiaOnline.

This module contains decorators used to simplify validation logic when handling user messages and checking room participation in the MafiaOnline API client.

Typical usage example:

@extract_message async def handle_text(self, content: str):

print(f”User said: {content}”)

@room_participation_required async def send_to_room(self, room_id: str):

pass

class zafiaonline.api_client.api_decorators.ApiDecorators[source]

Bases: object

A collection of static decorator methods for API request handling and validation.

This class provides reusable decorators to be applied to asynchronous methods in API client classes. These decorators add functionality such as user authentication, player ID resolution, room validation, and packet message extraction. They help enforce consistency and reduce boilerplate across API interactions.

staticmethod fetch_player_id(func)[source]

Decorator that ensures a valid player_id is passed to the decorated async method.

If player_id is None, attempts to resolve it using player_nickname via an API call to the Players service. Raises an error if both values are missing or the nickname cannot be resolved.

Parameters:

func (Callable) – The asynchronous function to decorate. Must accept the following arguments in order: cls, player_id, player_nickname, auth, *args, **kwargs.

Returns:

The decorated asynchronous function with resolved player_id.

Return type:

Callable

Raises:

  • AttributeError – If both player_id and player_nickname are None.

  • ValueError – If no user is found for the given player_nickname.

staticmethod login_required(func)[source]

Decorator that ensures sufficient login credentials are provided.

This decorator checks that required authentication details (email, password, token, user_id) are present in keyword arguments. If essential login information is missing, it raises a LoginError.

Parameters:

func (Callable) – The function requiring login validation.

Returns:

Wrapped function that raises LoginError if login credentials are incomplete, or otherwise proceeds with the original function call.

Return type:

Callable

Raises:

  • LoginError – If neither a valid (email + password) nor (token + user_id)

  • pair is provided. –

staticmethod requires_room_check(auth)[source]

Decorator to ensure the user is in the specified room before executing the function.

This decorator checks the user’s current room via the API. If the user is not in any room, or is in a different room than the one passed to the function, it raises a ValueError.

Parameters:

  • func (Callable) – The asynchronous function to wrap.

  • auth (Auth) – The authentication object used to retrieve user information.

Returns:

The wrapped asynchronous function that performs a room consistency check.

Return type:

Callable

Raises:

ValueError – If the user is not in a room, or if the room does not match the given room_id.

staticmethod extract_message(func)[source]

Processes an incoming packet and passes the message text to the function if it is a main text message.

Extracts the message content and user information from the packet structure if the packet type is MESSAGE and the message type is MAIN_TEXT. Stores the user ID, username, and sex in self.

Parameters:

func (Callable) – An asynchronous function expecting arguments (self, content, *args, **kwargs), where content is the extracted message text.

Returns:

The wrapped function, or None if the packet is not a main text message.

Return type:

Callable

zafiaonline.api_client.global_chat_methods module

Handles interaction with the global chat system for authenticated clients.

This module defines the GlobalChatMethods class, which allows clients to join and leave the global chat, send messages, and perform basic anti-spam handling. It is designed to be used as part of a WebSocket-based client for MafiaOnline or similar real-time systems.

Typical usage example:

auth = Auth(…) chat = GlobalChatMethods(auth) await chat.join_global_chat() await chat.send_message_global(“Hello everyone!”) await chat.leave_from_global_chat()

class zafiaonline.api_client.global_chat_methods.GlobalChatMethods(auth_client)[source]

Bases: object

Handles global chat interactions for an authenticated user.

This class manages the global chat functionality using an authenticated client session. It initializes user-related state and tracks messages sent during the session.

Parameters:

auth_client (AuthService)

auth_client

An authenticated API client instance used for user operations.

sent_messages

A SentMessages instance used to track sent messages.

await send_server(data, remove_token_from_object=False)[source]

Sends data to the server through the authenticated client.

This method forwards the given data to the server using the client’s send_server method. Optionally removes token-related information from the data before sending.

Parameters:

  • data (dict) – The dict data object to be sent to the server. Can be of any type supported by the underlying client method.

  • remove_token_from_object (bool) – If True, removes authentication token fields from the data before sending. Defaults to False.

Returns:

None

Raises:

Any exception raised by self.client.send_server. –

Return type:

None

await get_data(data)[source]

Fetches structured data from the server based on the given key.

Delegates the retrieval logic to the authenticated client.

Parameters:

data (str) – The key or identifier for the data to fetch.

Returns:

The retrieved data as a dictionary if available; otherwise, None.

Return type:

dict | None

await join_global_chat()[source]

Joins the global chat by sending a join request to the server.

This method constructs a packet with the appropriate type identifier and sends it to the server to add the client to the global chat session.

Once joined, the client can receive and send messages within the global chat room.

Returns:

None

Raises:

Any exception raised by send_server. –

Return type:

dict

await leave_from_global_chat()[source]

Leaves the global chat and returns the client to the dashboard.

Sends a request to the server to remove the client from the global chat and add them to the dashboard, typically representing a lobby or non-chat state.

Returns:

None

Raises:

Any exception raised by send_server. –

Return type:

dict

await send_message_global(content, message_style=MessageStyles.NO_COLOR)[source]

Sends a message to the global chat with optional styling.

Validates and cleans the message before sending. Implements basic spam prevention and risk mitigation by skipping unsafe or repeated messages.

Parameters:

  • content (str) – The text content of the message to send.

  • message_style (int, optional) – The display style of the message. Defaults to MessageStyles.NO_COLOR.

Returns:

None

Return type:

None

zafiaonline.api_client.player_methods module

Client-side interface for sending and receiving data via server packets.

This module provides a high-level asynchronous interface for interacting with a game or application server. It includes methods for sending requests (e.g., friend management, messaging, complaints, room actions), receiving responses, and parsing returned data into model objects.

Typical usage example:

client = Client(…) await client.players.remove_friend(“user_id”) messages = await client.get_private_messages(“friend_id”)

class zafiaonline.api_client.player_methods.PlayersMethods(auth_client)[source]

Bases: object

Handles all player-related interactions in the system.

This class provides a high-level interface to interact with the player’s data, including friends, messages, complaints, ratings, and profile information. It communicates with the backend server via the provided authenticated client.

Parameters:

auth_client (AuthService)

auth_client

An authenticated client used to communicate with the backend.

Type:

Auth

sent_messages

A message tracker used for spam prevention and content validation.

Type:

SentMessages

await send_server(data, remove_token_from_object=False)[source]

Sends data to the server using the authenticated client.

This method delegates the sending operation to the internal client. Optionally removes the token from the data object before sending.

Parameters:

  • data (dict) – The dict data object to be sent to the server.

  • remove_token_from_object (bool) – If True, removes the token field from the object before sending. Defaults to False.

Returns:

None

Return type:

None

await get_data(data)[source]

Sends a request and waits for a specific response from the server.

Delegates the operation to the internal client to retrieve data that matches the given identifier or request type.

Parameters:

data (str) – The string key or identifier used to filter or retrieve the expected response.

Returns:

The response data as a dictionary if available, otherwise None.

Return type:

dict | None

await friend_list()[source]

Fetches the user’s friend list from the server.

Sends a request with packet type ADD_CLIENT_TO_FRIENDSHIP_LIST, then awaits and decodes the server response into a list of ModelFriend objects.

Returns:

A list of ModelFriend instances representing the user’s friends.

Raises:

AttributeError – If the friendship list is missing in the server response.

Return type:

list[ModelFriend]

await get_friend_invite_list()[source]

Fetches the list of friends in the invite list from the server.

Sends a request to retrieve users currently in the invite list and awaits the server’s response.

Returns:

The parsed server response associated with FRIENDS_IN_INVITE_LIST, typically a dict or None if the data was not received.

Return type:

dict

await invite_friend(player_id)[source]

Sends a friend invite to a player by their ID.

Sends a request to invite the specified player to the current room and awaits a confirmation response from the server.

Parameters:

player_id (str) – The unique identifier of the player to invite.

Returns:

The server’s response associated with the FRIEND_IS_INVITED key, or None if no response was received.

Return type:

dict

await search_player(nickname)[source]

Searches for a player by their nickname.

Sends a search request to the server to look up a player using the provided nickname.

Parameters:

nickname (str) – The nickname of the player to search for.

Returns:

A dictionary containing the search result data, or None if no data was received.

Return type:

dict

await remove_friend(friend_id)[source]

Removes a friend from the user’s friend list.

Sends a request to the server to remove the specified friend.

Parameters:

friend_id (str) – The unique identifier of the friend to remove.

Returns:

None.

Return type:

dict

await get_friend_requests()[source]
Return type:

dict

await kick_user_vote(room_id, value=True)[source]

Sends a vote request to kick a user from a room.

Parameters:

  • room_id (str) – The unique identifier of the room.

  • value (bool) – The vote decision. Defaults to True (vote to kick).

Return type:

None

await kick_user(user_id, room_id)[source]

Sends a request to kick a user from the specified room.

Parameters:

  • user_id (str) – The unique identifier of the user to be kicked.

  • room_id (str) – The unique identifier of the room.

Return type:

dict

await message_complaint(reason, screenshot_id, user_id)[source]

Submits a complaint about a user’s message.

Allows users to report inappropriate messages by specifying a reason and attaching a screenshot.

Parameters:

  • reason (str) – The reason for the complaint.

  • screenshot_id (int) – The ID of the uploaded screenshot. Obtained from update_photo_server().

  • user_id (str) – The ID of the user being reported.

Returns:

The server response to the complaint request.

Return type:

dict

await get_private_messages(friend_id)[source]

Retrieves private messages exchanged with a specific friend.

Parameters:

friend_id (str) – The unique identifier of the friend.

Returns:

A list of private messages as ModelMessage objects.

Raises:

AttributeError – If no data was received from the server.

Return type:

list[ModelMessage]

await get_rating(rating_type=RatingType.AUTHORITY, rating_mode=RatingMode.ALL_TIME)[source]

Retrieves the player rating based on the specified type and mode.

Parameters:

  • rating_type (RatingType) – The type of rating to retrieve. Defaults to RatingType.AUTHORITY.

  • rating_mode (RatingMode) – The time period for the rating. Defaults to RatingMode.ALL_TIME.

Returns:

A dictionary containing the rating data if successful, otherwise None.

Return type:

dict

await send_message_friend(friend_id, content)[source]

Sends a private message to a friend.

Parameters:

  • friend_id (str) – The unique identifier of the friend.

  • content (str) – The message text to be sent.

Returns:

None. The message is sent if it passes validation checks.

Return type:

dict | None

await get_user(user_id)[source]

Retrieves the profile data of a specific user.

Parameters:

user_id (str) – The unique identifier of the user.

Returns:

The user’s profile data if successfully retrieved, otherwise None.

Raises:

Exception – If an unexpected error occurs while fetching the data.

Return type:

dict | None

await add_friend(user_id)[source]
Parameters:

user_id (str)

Return type:

int

zafiaonline.api_client.room_methods module

This module provides matchmaking and room-related functionalities for a multiplayer game client.

It defines asynchronous methods for joining and leaving rooms, creating players, performing role-based actions, sending messages, and interacting with the matchmaking queue. The module relies on communication with a game server using structured packet data.

Typical usage example:

auth = Auth(…) matchmaking = MatchMakingMethods(auth) await matchmaking.match_making_add_user(players_size = 12)

class zafiaonline.api_client.room_methods.RoomMethods(auth_client)[source]

Bases: object

Handles multiplayer room logic over WebSocket for an authenticated client.

The Room class provides high-level operations for creating, joining, managing, and interacting within game rooms via WebSocket. It builds structured payloads, handles message dispatch, and manages room-level interactions like chat, voting, and forfeiting.

Parameters:

auth_client (AuthService)

auth_client

Authenticated WebSocket client used for communication.

Type:

Auth

sent_messages

Tracker for detecting repeated messages or spam.

Type:

SentMessages

md5hash

Utility for hashing passwords with salt before transmission.

Type:

Md5

await send_server(data, remove_token_from_object=False)[source]

Sends a structured payload to the game server via WebSocket.

Delegates the actual sending logic to the authenticated client.

Parameters:

  • data (dict) – The payload to be sent to the server.

  • remove_token_from_object (bool, optional) – Whether to remove the authentication token from the payload object before sending. Defaults to False.

Returns:

None

Return type:

None

await get_data(data)[source]

Fetches structured data from the server based on the given key.

Delegates the retrieval logic to the authenticated client.

Parameters:

data (str) – The key or identifier for the data to fetch.

Returns:

The retrieved data as a dictionary if available; otherwise, None.

Return type:

dict | None

await listen()[source]

Waits for and returns the next incoming message from the server.

This method listens for a single message from the WebSocket connection and returns it as a dictionary.

Returns:

The parsed message if received successfully; otherwise, None.

Return type:

dict | None

await create_room(selected_roles=[], title='', max_players=8, min_players=5, password=None, min_level=1, vip_enabled=False)[source]

Creates a new game room with the specified parameters.

Sends a room creation request to the server with the configured settings such as player limits, role selection, room title, and access restrictions.

Parameters:

  • selected_roles (List[Roles | int], optional) – List of roles or role IDs selected for the room. Defaults to [0].

  • title (str, optional) – Title of the room. Defaults to “”.

  • max_players (int, optional) – Maximum number of players allowed. Defaults to 8.

  • min_players (int, optional) – Minimum number of players to start the game. Defaults to 5.

  • password (str | None, optional) – Optional password for the room. Defaults to None.

  • min_level (int, optional) – Minimum player level required to join. Defaults to 1.

  • vip_enabled (bool, optional) – Whether VIP features are enabled. Defaults to False.

Returns:

A ModelRoom instance if room creation succeeds, otherwise None.

Return type:

ModelRoom | None

Raises:

AttributeError – If no response data is received after sending the request.

await remove_player(room_id)[source]

Sends a request to remove the player from a specific room.

Constructs and sends a request to leave or be removed from the room with the given identifier.

Parameters:

room_id (str) – The unique identifier of the room.

Returns:

None

Return type:

None

await leave_room(room_id)[source]

Leaves the specified room by sending a removal request.

Delegates to remove_player to handle the actual request to leave the room.

Parameters:

room_id (str) – The unique identifier of the room.

Returns:

None

Return type:

None

await send_invate_to_room(user_id)[source]
Parameters:

user_id (str)

Return type:

dict | None

await get_invite_list()[source]
Return type:

dict | None

await get_players(room_id)[source]
Parameters:

room_id (str)

Return type:

dict | None

await create_player(room_id, room_model_type=RoomModelType.NOT_MATCHMAKING_MODE)[source]

Creates a player in the specified room and retrieves room statistics.

Should be called after join_room() if the user is not the host.

Sends a request to create a player in the given room, waits for room statistics to be received, and retries up to 3 times if necessary.

Parameters:

  • room_id (str) – The unique identifier of the room.

  • room_model_type (RoomModelType, optional) – The type of room model. Defaults to RoomModelType.NOT_MATCHMAKING_MODE.

Returns:

A dictionary containing “player_list” and “room_messages” if successful, otherwise None.

Return type:

dict | None

Raises:

AttributeError – If the room statistics cannot be retrieved.

await join_room(room_id, password='')[source]

Joins a specified room using the given room ID and optional password.

Sends a request to the server to join the specified room. If a password is provided, it is hashed before being included in the request.

Parameters:

  • room_id (str) – The unique identifier of the room to join.

  • password (str, optional) – The password for the room, if required. Defaults to an empty string.

Returns:

None

Return type:

dict | None

await role_action(user_id, room_id, room_model_type=RoomModelType.NOT_MATCHMAKING_MODE)[source]

Performs a role-specific action on a user within a room.

Used to execute a role-based action (e.g., vote, attack, investigate) during an ongoing game.

Parameters:

  • user_id (str) – The unique identifier of the targeted user.

  • room_id (str) – The unique identifier of the room where the action occurs.

  • room_model_type (RoomModelType, optional) – The type of room model to use. Defaults to RoomModelType.NOT_MATCHMAKING_MODE.

Returns:

None

Return type:

dict | None

await give_up(room_id, room_model_type=RoomModelType.NOT_MATCHMAKING_MODE)[source]

Sends a request to forfeit the game.

Allows a player to surrender during an ongoing game.

Parameters:

  • room_id (str) – The unique identifier of the room where the surrender occurs.

  • room_model_type (RoomModelType, optional) – The type of room model. Defaults to RoomModelType.NOT_MATCHMAKING_MODE.

Returns:

None

Return type:

dict | None

await send_message_room(content, room_id, message_style=MessageStyles.NO_COLOR)[source]

Sends a message to the specified room.

Prevents sending if the message content is empty or potentially risky to avoid spam or bans.

Parameters:

  • content (str) – The message text to be sent.

  • room_id (str) – The unique identifier of the room.

  • message_style (int, optional) – The style of the message. Defaults to MessageStyles.NO_COLOR.

Returns:

None

Return type:

None

await add_client_to_room_list()[source]

Adds the client to the list of available rooms.

Sends a request so the client can receive updates about available rooms in the game lobby.

Returns:

Room list data if available, otherwise None.

Return type:

Optional[dict]

class zafiaonline.api_client.room_methods.MatchMakingMethods(auth_client)[source]

Bases: object

Handles matchmaking operations for the client.

This class provides methods for interacting with the matchmaking system, including adding and removing the user from the matchmaking queue, checking queue status, and retrieving user count.

Parameters:

auth_client (AuthService)

auth_client

The authenticated client instance used to send and receive data from the server.

Type:

Auth

await send_server(data, remove_token_from_object=False)[source]

Sends a packet to the server through the authenticated client.

Parameters:

  • data (dict) – The data to be sent to the server.

  • remove_token_from_object (bool, optional) – Whether to remove the token from the object before sending. Defaults to False.

Returns:

None

Return type:

None

await get_data(data)[source]

Retrieves data from the server through the authenticated client.

Parameters:

data (str) – The key or identifier for the data to retrieve.

Returns:

The data received from the server, or None if no data is available.

Return type:

dict | None

await match_making_get_status()[source]

Retrieves the current status of matchmaking.

Sends a request to the server to get the current matchmaking status and waits briefly for a response.

Returns:

The matchmaking status data received from the server, or None if no data is returned.

Return type:

dict | None

await users_waiting_count(players_size=8)[source]

Retrieves the number of users currently waiting for a matchmaking game.

Sends a request to the server to get the number of players currently waiting in the matchmaking queue.

Parameters:

players_size (int, optional) – The desired number of players in the game. Defaults to 8.

Returns:

The response data containing the count of waiting users, or None if no data is returned.

Return type:

dict | None

await match_making_add_user(players_size=8)[source]

Adds the user to the matchmaking queue.

Sends a request to the server to add the user to matchmaking. No response is expected.

Parameters:

players_size (int, optional) – The desired number of players in the game. Defaults to 8.

Returns:

None

Return type:

int | None

await match_making_remove_user()[source]

Removes the user from the matchmaking queue.

Sends a request to the server to remove the user from matchmaking. No response is expected.

Returns:

None

Return type:

None

await match_making_add_game()[source]

Sends a matchmaking add game request and retrieves the server response.

Constructs a request with the type MATCH_MAKING_ADD_GAME, sends it to the server, and then returns the data about the added game.

Returns:

A dictionary with information about the added game if available, otherwise None.

Return type:

dict | None

await match_making_ban_role()[source]

Sends a matchmaking role selection request and retrieves selected role data.

Constructs a request with the type MATCH_MAKING_USER_SELECT_ROLE, sends it to the server, and then returns the data about how many users have selected roles.

Returns:

A dictionary with information about selected roles if available, otherwise None.

Return type:

dict | None

zafiaonline.api_client.user_methods module

User-related operations for the Mafia client-server application.

Provides the User class which wraps several high-level user actions by sending requests to the server through the authenticated client connection.

These include nickname updates, language settings, VIP purchases, profile photo uploads, gender updates, and dashboard management.

Typical usage example:

auth = Auth(…) user = UserMethods(auth) await user.username_set(“CoolPlayer123”) await user.select_language(Languages.ENGLISH) await user.buy_vip()

class zafiaonline.api_client.user_methods.AuthService(client, proxy=None)[source]

Bases: Websocket

Handles user authentication and session-related metadata for WebSocket communication.

Parameters:

  • client (Client)

  • proxy (str | None)

client

The main client instance used for communication.

Type:

Client

proxy

Proxy address used for network requests.

Type:

Optional[str]

token

Authentication token for the current session.

Type:

Optional[str]

user_id

Unique identifier of the authenticated user.

Type:

Optional[str]

device_id

Identifier of the device used in this session.

Type:

str

md5hash

Utility for generating MD5 hashes.

Type:

Md5

user

Model representing the authenticated user.

Type:

ModelUser

server_configi

Model for server configuration.

Type:

ModelServerConfig

await sign_in(email='', password='', token='', user_id='')[source]

Signs in a user using email/password or token-based authentication.

Parameters:

  • email (str) – User’s email address. Defaults to “”.

  • password (str) – User’s password (in plaintext). Defaults to “”.

  • token (str) – Authentication token, used instead of password if provided. Defaults to “”.

  • user_id (str) – ID of the user to associate with the session. Defaults to “”.

Returns:

User object on successful authentication. bool: False if authentication fails.

Return type:

ModelUser

class zafiaonline.api_client.user_methods.UserMethods(auth_client)[source]

Bases: object

Handles user-related actions within the Mafia client.

This class provides functionality for interacting with user-specific endpoints of the Mafia API. It allows operations such as setting the username, selecting a preferred language, purchasing VIP status, and updating profile photos. It relies on an authenticated Auth client to send these requests to the server.

Parameters:

auth_client (AuthService)

auth_client

An instance of the authenticated client used to communicate with the Mafia API for user-specific actions.

Type:

Auth

await send_server(data, remove_token_from_object=False)[source]

Sends a data payload to the server through the authenticated client.

This method delegates the actual sending of data to the underlying Auth client, allowing the User class to abstract communication with the Mafia server. It can optionally remove the token from the payload before sending.

Parameters:

  • data (dict[str, Any]) – The dictionary payload to be sent to the server.

  • remove_token_from_object (bool) – If True, removes the token from the payload before sending. Defaults to False.

Returns:

None

Return type:

None

await get_data(data)[source]

Fetches structured data from the server based on the given key.

Delegates the retrieval logic to the authenticated client.

Parameters:

data (str) – The key or identifier for the data to fetch.

Returns:

The retrieved data as a dictionary if available; otherwise, None.

Return type:

dict | None

await listen()[source]

Listens for incoming messages from the server.

This method delegates the listening functionality to the underlying authenticated client. It waits asynchronously for a message from the server and returns the received payload.

Returns:

The message or data received from the server. The exact type and structure of the response depends on the server’s protocol.

Return type:

dict | None

await username_set(nickname)[source]

Sends a request to the server to update the user’s username.

This method constructs and dispatches a packet to set a new nickname for the currently authenticated user. The server is expected to process the request and update the user’s profile accordingly.

Parameters:

nickname (str) – The desired username to assign to the user’s account.

Returns:

None

Return type:

str

await backpack_get()[source]
Return type:

dict

await get_market(market_type=0, app_language=MafiaLanguages.English)[source]
Parameters:
Return type:

dict

await select_language(language=Languages.RUSSIAN)[source]

Sends a request to the server to update the user’s preferred language.

This method changes the language setting associated with the user’s profile on the server. The selected language will affect future server responses (such as system messages, UI text, etc.), depending on server-side support.

Parameters:

language (Languages) – The target language to set for the user. Defaults to Languages.RUSSIAN.

Returns:

None

Return type:

dict

await buy_vip(market_product_id=BuyVipMethodsIds.BuyWithSilverCoins, app_language=MafiaLanguages.English)[source]
Parameters:
Return type:

dict

await buy_silver_coins(market_product_id=BuySilverCoinsMethodsIds.BuyFiveThousandCoins)[source]
Parameters:

market_product_id (BuySilverCoinsMethodsIds)

Return type:

dict

await buy_decorations(market_product_id=BuyDecorationsMethodIds.BuySixHundredSilver, decoration_id=7, decoration_parameter=10, second_parameter=None)[source]
Parameters:

  • market_product_id (BuyDecorationsMethodIds)

  • decoration_id (int)

  • decoration_parameter (int)

  • second_parameter (int | None)

Return type:

dict

await buy_vip_old(app_language=MafiaLanguages.Russian)[source]

Sends a request to purchase a VIP account for the user.

This method initiates the purchase of a VIP account via the in-game market system. It includes the selected application language in the request payload, which may affect localization of the server response or purchase dialog (depending on server behavior).

Parameters:

app_language (MafiaLanguages, optional) – The language used for the request context. Defaults to MafiaLanguages.Russian.

Returns:

None

Return type:

dict

await get_default_photos()[source]
Return type:

dict

await update_photo(file)[source]

Uploads and sets a new profile photo for the user.

This method sends a request to the server to update the user’s profile picture. The provided image file is expected to be in raw byte format, which will be base64-encoded before transmission.

Parameters:

file (bytes) – The image file in bytes. Typically a PNG or JPEG.

Returns:

None

Return type:

None

await update_sex(sex)[source]

Sends a request to update the user’s gender on the server.

This method updates the user’s gender information by sending the appropriate payload to the backend. The gender is typically selected from a predefined enumeration (Sex), and the change is immediately reflected on the server after confirmation.

Parameters:

sex (Sex) – The new gender to assign to the user. Must be a value from the Sex enum (e.g., MALE, FEMALE).

Returns:

The server response indicating the success or failure of the operation. Usually a confirmation packet with updated user data or status.

Return type:

dict | None

await update_photo_server(file)[source]

Uploads and updates a screenshot on the server.

This method encodes the provided screenshot file (in bytes) into a base64 string and sends it to the server as part of a request to update or store the screenshot. It is typically used for sending game screenshots, user reports, or debugging information.

Parameters:

file (bytes) – The raw image data of the screenshot to be uploaded. Must be a valid byte sequence representing an image.

Returns:

None

Return type:

str

await dashboard()[source]

Sends a request to add the client to the dashboard.

This method communicates with the server to add the current client session to the dashboard context. It is often used to initialize the user’s presence in the main interface or lobby of the application, allowing access to account details, menus, or multiplayer features.

Typically, this is called after successful authentication and before interacting with dashboard-level features.

Returns:

None

Return type:

dict

zafiaonline.api_client.zafia_api module

Client module for interacting with the Zafia API.

This module provides an asynchronous wrapper around several HTTP-based endpoints used to interact with Zafia user profiles, such as modifying favorites, retrieving rankings, checking verification data, and more.

Typical usage example:

api = ZafiaApiMethods() top = await api.get_top(user_id=”user_xxxx”)

The ZafiaApi class extends HttpWrapper and handles endpoint-specific requests with automatic parameter formatting and error logging.

class zafiaonline.api_client.zafia_api.ZafiaApiMethods[source]

Bases: object

Asynchronous API client for interacting with Zafia user data and profile features.

This class provides high-level methods to access various Zafia endpoints, including actions like managing favorites, checking profile data, fetching leaderboard statistics, and verifying user accounts.

staticmethod with_user_id(func)[source]

Decorator that injects the ‘user_id’ into the request parameters.

This decorator modifies the ‘params’ dictionary passed to the wrapped function by adding the ‘user_id’ key.

Parameters:

func (Callable) – The asynchronous function to wrap.

Returns:

The wrapped asynchronous function with ‘user_id’ injected into the parameters.

Return type:

Callable

await change_favorite_status(user_id, favorite_id)[source]

Toggle the favorite status for a specific item by the user.

Sends a request to mark or unmark an item (identified by favorite_id) as a favorite for the specified user.

Parameters:

  • user_id (str) – The ID of the user performing the action.

  • favorite_id (str) – The ID of the item to be marked or unmarked as favorite.

Returns:

The server response indicating whether the update was successful.

Return type:

Dict[str, bool]

await change_visible_top(user_id, show=True)[source]

Changes the visibility status of the user on the top list.

Sends a request to the server to update whether the specified user should appear in the visible top list or not.

Parameters:

  • user_id (str) – The unique identifier of the user.

  • show (bool, optional) – Indicates whether the user should be shown in the top list. Defaults to True.

Returns:

A dictionary indicating whether the visibility status was successfully changed.

Return type:

Dict[str, bool]

await get_favorites_list(user_id, from_type=MethodGetFavourites.InviteMethod)[source]

Retrieves the list of favorite users for the specified user.

This method fetches the user’s favorites based on the specified method type, such as favorites added through invites or friend list means.

Parameters:

  • user_id (str) – The unique identifier of the user.

  • from_type (MethodGetFavourites, optional) – The method by which the favorites were added. Defaults to MethodGetFavourites.InviteMethod.

Returns:

A dictionary containing the list of favorite users.

Return type:

Dict[str, Any]

await check_profile(user_id, check_id, user_nickname, check_nickname)[source]

Compares the specified user’s profile with another user’s profile.

This method checks whether the provided nicknames and user IDs match or meet some criteria defined by the backend for profile comparison.

Parameters:

  • user_id (str) – The unique identifier of the current user.

  • check_id (str) – The unique identifier of the user to check against.

  • user_nickname (str) – The nickname of the current user.

  • check_nickname (str) – The nickname of the user being checked.

Returns:

A dictionary indicating whether the profile comparison passed.

Return type:

Dict[str, bool]

await get_top(user_id, top_type=RatingType.EXPERIENCE)[source]

Retrieves the leaderboard data for a given rating type.

This method fetches the top users from the specified leaderboard, such as by experience or other rating metrics.

Parameters:

  • user_id (str) – The ID of the user making the request.

  • top_type (RatingType, optional) – The type of leaderboard to retrieve. Defaults to RatingType.EXPERIENCE.

Returns:

A dictionary containing leaderboard data.

Return type:

Dict[str, Any]

await get_verifications(user_id, version=15, device_id='')[source]

Retrieves the list of verifications required for the client.

Sends a request to fetch current verification depending on the client version and device identifier.

Parameters:

  • user_id (str) – The ID of the user making the request.

  • version (int, optional) – The client version. Defaults to 15.

  • device_id (str, optional) – The device identifier. If not provided, a random one will be generated.

Returns:

A dictionary containing verification data.

Return type:

Dict[str, Any]

Module contents

class zafiaonline.api_client.ApiDecorators[source]

Bases: object

A collection of static decorator methods for API request handling and validation.

This class provides reusable decorators to be applied to asynchronous methods in API client classes. These decorators add functionality such as user authentication, player ID resolution, room validation, and packet message extraction. They help enforce consistency and reduce boilerplate across API interactions.

staticmethod extract_message(func)[source]

Processes an incoming packet and passes the message text to the function if it is a main text message.

Extracts the message content and user information from the packet structure if the packet type is MESSAGE and the message type is MAIN_TEXT. Stores the user ID, username, and sex in self.

Parameters:

func (Callable) – An asynchronous function expecting arguments (self, content, *args, **kwargs), where content is the extracted message text.

Returns:

The wrapped function, or None if the packet is not a main text message.

Return type:

Callable

staticmethod fetch_player_id(func)[source]

Decorator that ensures a valid player_id is passed to the decorated async method.

If player_id is None, attempts to resolve it using player_nickname via an API call to the Players service. Raises an error if both values are missing or the nickname cannot be resolved.

Parameters:

func (Callable) – The asynchronous function to decorate. Must accept the following arguments in order: cls, player_id, player_nickname, auth, *args, **kwargs.

Returns:

The decorated asynchronous function with resolved player_id.

Return type:

Callable

Raises:

  • AttributeError – If both player_id and player_nickname are None.

  • ValueError – If no user is found for the given player_nickname.

staticmethod login_required(func)[source]

Decorator that ensures sufficient login credentials are provided.

This decorator checks that required authentication details (email, password, token, user_id) are present in keyword arguments. If essential login information is missing, it raises a LoginError.

Parameters:

func (Callable) – The function requiring login validation.

Returns:

Wrapped function that raises LoginError if login credentials are incomplete, or otherwise proceeds with the original function call.

Return type:

Callable

Raises:

  • LoginError – If neither a valid (email + password) nor (token + user_id)

  • pair is provided. –

staticmethod requires_room_check(auth)[source]

Decorator to ensure the user is in the specified room before executing the function.

This decorator checks the user’s current room via the API. If the user is not in any room, or is in a different room than the one passed to the function, it raises a ValueError.

Parameters:

  • func (Callable) – The asynchronous function to wrap.

  • auth (Auth) – The authentication object used to retrieve user information.

Returns:

The wrapped asynchronous function that performs a room consistency check.

Return type:

Callable

Raises:

ValueError – If the user is not in a room, or if the room does not match the given room_id.

class zafiaonline.api_client.GlobalChatMethods(auth_client)[source]

Bases: object

Handles global chat interactions for an authenticated user.

This class manages the global chat functionality using an authenticated client session. It initializes user-related state and tracks messages sent during the session.

Parameters:

auth_client (AuthService)

auth_client

An authenticated API client instance used for user operations.

sent_messages

A SentMessages instance used to track sent messages.

await get_data(data)[source]

Fetches structured data from the server based on the given key.

Delegates the retrieval logic to the authenticated client.

Parameters:

data (str) – The key or identifier for the data to fetch.

Returns:

The retrieved data as a dictionary if available; otherwise, None.

Return type:

dict | None

await join_global_chat()[source]

Joins the global chat by sending a join request to the server.

This method constructs a packet with the appropriate type identifier and sends it to the server to add the client to the global chat session.

Once joined, the client can receive and send messages within the global chat room.

Returns:

None

Raises:

Any exception raised by send_server. –

Return type:

dict

await leave_from_global_chat()[source]

Leaves the global chat and returns the client to the dashboard.

Sends a request to the server to remove the client from the global chat and add them to the dashboard, typically representing a lobby or non-chat state.

Returns:

None

Raises:

Any exception raised by send_server. –

Return type:

dict

await send_message_global(content, message_style=MessageStyles.NO_COLOR)[source]

Sends a message to the global chat with optional styling.

Validates and cleans the message before sending. Implements basic spam prevention and risk mitigation by skipping unsafe or repeated messages.

Parameters:

  • content (str) – The text content of the message to send.

  • message_style (int, optional) – The display style of the message. Defaults to MessageStyles.NO_COLOR.

Returns:

None

Return type:

None

await send_server(data, remove_token_from_object=False)[source]

Sends data to the server through the authenticated client.

This method forwards the given data to the server using the client’s send_server method. Optionally removes token-related information from the data before sending.

Parameters:

  • data (dict) – The dict data object to be sent to the server. Can be of any type supported by the underlying client method.

  • remove_token_from_object (bool) – If True, removes authentication token fields from the data before sending. Defaults to False.

Returns:

None

Raises:

Any exception raised by self.client.send_server. –

Return type:

None

class zafiaonline.api_client.PlayersMethods(auth_client)[source]

Bases: object

Handles all player-related interactions in the system.

This class provides a high-level interface to interact with the player’s data, including friends, messages, complaints, ratings, and profile information. It communicates with the backend server via the provided authenticated client.

Parameters:

auth_client (AuthService)

auth_client

An authenticated client used to communicate with the backend.

Type:

Auth

sent_messages

A message tracker used for spam prevention and content validation.

Type:

SentMessages

await add_friend(user_id)[source]
Parameters:

user_id (str)

Return type:

int

await friend_list()[source]

Fetches the user’s friend list from the server.

Sends a request with packet type ADD_CLIENT_TO_FRIENDSHIP_LIST, then awaits and decodes the server response into a list of ModelFriend objects.

Returns:

A list of ModelFriend instances representing the user’s friends.

Raises:

AttributeError – If the friendship list is missing in the server response.

Return type:

list[ModelFriend]

await get_data(data)[source]

Sends a request and waits for a specific response from the server.

Delegates the operation to the internal client to retrieve data that matches the given identifier or request type.

Parameters:

data (str) – The string key or identifier used to filter or retrieve the expected response.

Returns:

The response data as a dictionary if available, otherwise None.

Return type:

dict | None

await get_friend_invite_list()[source]

Fetches the list of friends in the invite list from the server.

Sends a request to retrieve users currently in the invite list and awaits the server’s response.

Returns:

The parsed server response associated with FRIENDS_IN_INVITE_LIST, typically a dict or None if the data was not received.

Return type:

dict

await get_friend_requests()[source]
Return type:

dict

await get_private_messages(friend_id)[source]

Retrieves private messages exchanged with a specific friend.

Parameters:

friend_id (str) – The unique identifier of the friend.

Returns:

A list of private messages as ModelMessage objects.

Raises:

AttributeError – If no data was received from the server.

Return type:

list[ModelMessage]

await get_rating(rating_type=RatingType.AUTHORITY, rating_mode=RatingMode.ALL_TIME)[source]

Retrieves the player rating based on the specified type and mode.

Parameters:

  • rating_type (RatingType) – The type of rating to retrieve. Defaults to RatingType.AUTHORITY.

  • rating_mode (RatingMode) – The time period for the rating. Defaults to RatingMode.ALL_TIME.

Returns:

A dictionary containing the rating data if successful, otherwise None.

Return type:

dict

await get_user(user_id)[source]

Retrieves the profile data of a specific user.

Parameters:

user_id (str) – The unique identifier of the user.

Returns:

The user’s profile data if successfully retrieved, otherwise None.

Raises:

Exception – If an unexpected error occurs while fetching the data.

Return type:

dict | None

await invite_friend(player_id)[source]

Sends a friend invite to a player by their ID.

Sends a request to invite the specified player to the current room and awaits a confirmation response from the server.

Parameters:

player_id (str) – The unique identifier of the player to invite.

Returns:

The server’s response associated with the FRIEND_IS_INVITED key, or None if no response was received.

Return type:

dict

await kick_user(user_id, room_id)[source]

Sends a request to kick a user from the specified room.

Parameters:

  • user_id (str) – The unique identifier of the user to be kicked.

  • room_id (str) – The unique identifier of the room.

Return type:

dict

await kick_user_vote(room_id, value=True)[source]

Sends a vote request to kick a user from a room.

Parameters:

  • room_id (str) – The unique identifier of the room.

  • value (bool) – The vote decision. Defaults to True (vote to kick).

Return type:

None

await message_complaint(reason, screenshot_id, user_id)[source]

Submits a complaint about a user’s message.

Allows users to report inappropriate messages by specifying a reason and attaching a screenshot.

Parameters:

  • reason (str) – The reason for the complaint.

  • screenshot_id (int) – The ID of the uploaded screenshot. Obtained from update_photo_server().

  • user_id (str) – The ID of the user being reported.

Returns:

The server response to the complaint request.

Return type:

dict

await remove_friend(friend_id)[source]

Removes a friend from the user’s friend list.

Sends a request to the server to remove the specified friend.

Parameters:

friend_id (str) – The unique identifier of the friend to remove.

Returns:

None.

Return type:

dict

await search_player(nickname)[source]

Searches for a player by their nickname.

Sends a search request to the server to look up a player using the provided nickname.

Parameters:

nickname (str) – The nickname of the player to search for.

Returns:

A dictionary containing the search result data, or None if no data was received.

Return type:

dict

await send_message_friend(friend_id, content)[source]

Sends a private message to a friend.

Parameters:

  • friend_id (str) – The unique identifier of the friend.

  • content (str) – The message text to be sent.

Returns:

None. The message is sent if it passes validation checks.

Return type:

dict | None

await send_server(data, remove_token_from_object=False)[source]

Sends data to the server using the authenticated client.

This method delegates the sending operation to the internal client. Optionally removes the token from the data object before sending.

Parameters:

  • data (dict) – The dict data object to be sent to the server.

  • remove_token_from_object (bool) – If True, removes the token field from the object before sending. Defaults to False.

Returns:

None

Return type:

None

class zafiaonline.api_client.AuthService(client, proxy=None)[source]

Bases: Websocket

Handles user authentication and session-related metadata for WebSocket communication.

Parameters:

  • client (Client)

  • proxy (str | None)

client

The main client instance used for communication.

Type:

Client

proxy

Proxy address used for network requests.

Type:

Optional[str]

token

Authentication token for the current session.

Type:

Optional[str]

user_id

Unique identifier of the authenticated user.

Type:

Optional[str]

device_id

Identifier of the device used in this session.

Type:

str

md5hash

Utility for generating MD5 hashes.

Type:

Md5

user

Model representing the authenticated user.

Type:

ModelUser

server_configi

Model for server configuration.

Type:

ModelServerConfig

await sign_in(email='', password='', token='', user_id='')[source]

Signs in a user using email/password or token-based authentication.

Parameters:

  • email (str) – User’s email address. Defaults to “”.

  • password (str) – User’s password (in plaintext). Defaults to “”.

  • token (str) – Authentication token, used instead of password if provided. Defaults to “”.

  • user_id (str) – ID of the user to associate with the session. Defaults to “”.

Returns:

User object on successful authentication. bool: False if authentication fails.

Return type:

ModelUser

class zafiaonline.api_client.UserMethods(auth_client)[source]

Bases: object

Handles user-related actions within the Mafia client.

This class provides functionality for interacting with user-specific endpoints of the Mafia API. It allows operations such as setting the username, selecting a preferred language, purchasing VIP status, and updating profile photos. It relies on an authenticated Auth client to send these requests to the server.

Parameters:

auth_client (AuthService)

auth_client

An instance of the authenticated client used to communicate with the Mafia API for user-specific actions.

Type:

Auth

await backpack_get()[source]
Return type:

dict

await buy_decorations(market_product_id=BuyDecorationsMethodIds.BuySixHundredSilver, decoration_id=7, decoration_parameter=10, second_parameter=None)[source]
Parameters:

  • market_product_id (BuyDecorationsMethodIds)

  • decoration_id (int)

  • decoration_parameter (int)

  • second_parameter (int | None)

Return type:

dict

await buy_silver_coins(market_product_id=BuySilverCoinsMethodsIds.BuyFiveThousandCoins)[source]
Parameters:

market_product_id (BuySilverCoinsMethodsIds)

Return type:

dict

await buy_vip(market_product_id=BuyVipMethodsIds.BuyWithSilverCoins, app_language=MafiaLanguages.English)[source]
Parameters:
Return type:

dict

await buy_vip_old(app_language=MafiaLanguages.Russian)[source]

Sends a request to purchase a VIP account for the user.

This method initiates the purchase of a VIP account via the in-game market system. It includes the selected application language in the request payload, which may affect localization of the server response or purchase dialog (depending on server behavior).

Parameters:

app_language (MafiaLanguages, optional) – The language used for the request context. Defaults to MafiaLanguages.Russian.

Returns:

None

Return type:

dict

await dashboard()[source]

Sends a request to add the client to the dashboard.

This method communicates with the server to add the current client session to the dashboard context. It is often used to initialize the user’s presence in the main interface or lobby of the application, allowing access to account details, menus, or multiplayer features.

Typically, this is called after successful authentication and before interacting with dashboard-level features.

Returns:

None

Return type:

dict

await get_data(data)[source]

Fetches structured data from the server based on the given key.

Delegates the retrieval logic to the authenticated client.

Parameters:

data (str) – The key or identifier for the data to fetch.

Returns:

The retrieved data as a dictionary if available; otherwise, None.

Return type:

dict | None

await get_default_photos()[source]
Return type:

dict

await get_market(market_type=0, app_language=MafiaLanguages.English)[source]
Parameters:
Return type:

dict

await listen()[source]

Listens for incoming messages from the server.

This method delegates the listening functionality to the underlying authenticated client. It waits asynchronously for a message from the server and returns the received payload.

Returns:

The message or data received from the server. The exact type and structure of the response depends on the server’s protocol.

Return type:

dict | None

await select_language(language=Languages.RUSSIAN)[source]

Sends a request to the server to update the user’s preferred language.

This method changes the language setting associated with the user’s profile on the server. The selected language will affect future server responses (such as system messages, UI text, etc.), depending on server-side support.

Parameters:

language (Languages) – The target language to set for the user. Defaults to Languages.RUSSIAN.

Returns:

None

Return type:

dict

await send_server(data, remove_token_from_object=False)[source]

Sends a data payload to the server through the authenticated client.

This method delegates the actual sending of data to the underlying Auth client, allowing the User class to abstract communication with the Mafia server. It can optionally remove the token from the payload before sending.

Parameters:

  • data (dict[str, Any]) – The dictionary payload to be sent to the server.

  • remove_token_from_object (bool) – If True, removes the token from the payload before sending. Defaults to False.

Returns:

None

Return type:

None

await update_photo(file)[source]

Uploads and sets a new profile photo for the user.

This method sends a request to the server to update the user’s profile picture. The provided image file is expected to be in raw byte format, which will be base64-encoded before transmission.

Parameters:

file (bytes) – The image file in bytes. Typically a PNG or JPEG.

Returns:

None

Return type:

None

await update_photo_server(file)[source]

Uploads and updates a screenshot on the server.

This method encodes the provided screenshot file (in bytes) into a base64 string and sends it to the server as part of a request to update or store the screenshot. It is typically used for sending game screenshots, user reports, or debugging information.

Parameters:

file (bytes) – The raw image data of the screenshot to be uploaded. Must be a valid byte sequence representing an image.

Returns:

None

Return type:

str

await update_sex(sex)[source]

Sends a request to update the user’s gender on the server.

This method updates the user’s gender information by sending the appropriate payload to the backend. The gender is typically selected from a predefined enumeration (Sex), and the change is immediately reflected on the server after confirmation.

Parameters:

sex (Sex) – The new gender to assign to the user. Must be a value from the Sex enum (e.g., MALE, FEMALE).

Returns:

The server response indicating the success or failure of the operation. Usually a confirmation packet with updated user data or status.

Return type:

dict | None

await username_set(nickname)[source]

Sends a request to the server to update the user’s username.

This method constructs and dispatches a packet to set a new nickname for the currently authenticated user. The server is expected to process the request and update the user’s profile accordingly.

Parameters:

nickname (str) – The desired username to assign to the user’s account.

Returns:

None

Return type:

str

class zafiaonline.api_client.RoomMethods(auth_client)[source]

Bases: object

Handles multiplayer room logic over WebSocket for an authenticated client.

The Room class provides high-level operations for creating, joining, managing, and interacting within game rooms via WebSocket. It builds structured payloads, handles message dispatch, and manages room-level interactions like chat, voting, and forfeiting.

Parameters:

auth_client (AuthService)

auth_client

Authenticated WebSocket client used for communication.

Type:

Auth

sent_messages

Tracker for detecting repeated messages or spam.

Type:

SentMessages

md5hash

Utility for hashing passwords with salt before transmission.

Type:

Md5

await add_client_to_room_list()[source]

Adds the client to the list of available rooms.

Sends a request so the client can receive updates about available rooms in the game lobby.

Returns:

Room list data if available, otherwise None.

Return type:

Optional[dict]

await create_player(room_id, room_model_type=RoomModelType.NOT_MATCHMAKING_MODE)[source]

Creates a player in the specified room and retrieves room statistics.

Should be called after join_room() if the user is not the host.

Sends a request to create a player in the given room, waits for room statistics to be received, and retries up to 3 times if necessary.

Parameters:

  • room_id (str) – The unique identifier of the room.

  • room_model_type (RoomModelType, optional) – The type of room model. Defaults to RoomModelType.NOT_MATCHMAKING_MODE.

Returns:

A dictionary containing “player_list” and “room_messages” if successful, otherwise None.

Return type:

dict | None

Raises:

AttributeError – If the room statistics cannot be retrieved.

await create_room(selected_roles=[], title='', max_players=8, min_players=5, password=None, min_level=1, vip_enabled=False)[source]

Creates a new game room with the specified parameters.

Sends a room creation request to the server with the configured settings such as player limits, role selection, room title, and access restrictions.

Parameters:

  • selected_roles (List[Roles | int], optional) – List of roles or role IDs selected for the room. Defaults to [0].

  • title (str, optional) – Title of the room. Defaults to “”.

  • max_players (int, optional) – Maximum number of players allowed. Defaults to 8.

  • min_players (int, optional) – Minimum number of players to start the game. Defaults to 5.

  • password (str | None, optional) – Optional password for the room. Defaults to None.

  • min_level (int, optional) – Minimum player level required to join. Defaults to 1.

  • vip_enabled (bool, optional) – Whether VIP features are enabled. Defaults to False.

Returns:

A ModelRoom instance if room creation succeeds, otherwise None.

Return type:

ModelRoom | None

Raises:

AttributeError – If no response data is received after sending the request.

await get_data(data)[source]

Fetches structured data from the server based on the given key.

Delegates the retrieval logic to the authenticated client.

Parameters:

data (str) – The key or identifier for the data to fetch.

Returns:

The retrieved data as a dictionary if available; otherwise, None.

Return type:

dict | None

await get_invite_list()[source]
Return type:

dict | None

await get_players(room_id)[source]
Parameters:

room_id (str)

Return type:

dict | None

await give_up(room_id, room_model_type=RoomModelType.NOT_MATCHMAKING_MODE)[source]

Sends a request to forfeit the game.

Allows a player to surrender during an ongoing game.

Parameters:

  • room_id (str) – The unique identifier of the room where the surrender occurs.

  • room_model_type (RoomModelType, optional) – The type of room model. Defaults to RoomModelType.NOT_MATCHMAKING_MODE.

Returns:

None

Return type:

dict | None

await join_room(room_id, password='')[source]

Joins a specified room using the given room ID and optional password.

Sends a request to the server to join the specified room. If a password is provided, it is hashed before being included in the request.

Parameters:

  • room_id (str) – The unique identifier of the room to join.

  • password (str, optional) – The password for the room, if required. Defaults to an empty string.

Returns:

None

Return type:

dict | None

await leave_room(room_id)[source]

Leaves the specified room by sending a removal request.

Delegates to remove_player to handle the actual request to leave the room.

Parameters:

room_id (str) – The unique identifier of the room.

Returns:

None

Return type:

None

await listen()[source]

Waits for and returns the next incoming message from the server.

This method listens for a single message from the WebSocket connection and returns it as a dictionary.

Returns:

The parsed message if received successfully; otherwise, None.

Return type:

dict | None

await remove_player(room_id)[source]

Sends a request to remove the player from a specific room.

Constructs and sends a request to leave or be removed from the room with the given identifier.

Parameters:

room_id (str) – The unique identifier of the room.

Returns:

None

Return type:

None

await role_action(user_id, room_id, room_model_type=RoomModelType.NOT_MATCHMAKING_MODE)[source]

Performs a role-specific action on a user within a room.

Used to execute a role-based action (e.g., vote, attack, investigate) during an ongoing game.

Parameters:

  • user_id (str) – The unique identifier of the targeted user.

  • room_id (str) – The unique identifier of the room where the action occurs.

  • room_model_type (RoomModelType, optional) – The type of room model to use. Defaults to RoomModelType.NOT_MATCHMAKING_MODE.

Returns:

None

Return type:

dict | None

await send_invate_to_room(user_id)[source]
Parameters:

user_id (str)

Return type:

dict | None

await send_message_room(content, room_id, message_style=MessageStyles.NO_COLOR)[source]

Sends a message to the specified room.

Prevents sending if the message content is empty or potentially risky to avoid spam or bans.

Parameters:

  • content (str) – The message text to be sent.

  • room_id (str) – The unique identifier of the room.

  • message_style (int, optional) – The style of the message. Defaults to MessageStyles.NO_COLOR.

Returns:

None

Return type:

None

await send_server(data, remove_token_from_object=False)[source]

Sends a structured payload to the game server via WebSocket.

Delegates the actual sending logic to the authenticated client.

Parameters:

  • data (dict) – The payload to be sent to the server.

  • remove_token_from_object (bool, optional) – Whether to remove the authentication token from the payload object before sending. Defaults to False.

Returns:

None

Return type:

None

class zafiaonline.api_client.MatchMakingMethods(auth_client)[source]

Bases: object

Handles matchmaking operations for the client.

This class provides methods for interacting with the matchmaking system, including adding and removing the user from the matchmaking queue, checking queue status, and retrieving user count.

Parameters:

auth_client (AuthService)

auth_client

The authenticated client instance used to send and receive data from the server.

Type:

Auth

await get_data(data)[source]

Retrieves data from the server through the authenticated client.

Parameters:

data (str) – The key or identifier for the data to retrieve.

Returns:

The data received from the server, or None if no data is available.

Return type:

dict | None

await match_making_add_game()[source]

Sends a matchmaking add game request and retrieves the server response.

Constructs a request with the type MATCH_MAKING_ADD_GAME, sends it to the server, and then returns the data about the added game.

Returns:

A dictionary with information about the added game if available, otherwise None.

Return type:

dict | None

await match_making_add_user(players_size=8)[source]

Adds the user to the matchmaking queue.

Sends a request to the server to add the user to matchmaking. No response is expected.

Parameters:

players_size (int, optional) – The desired number of players in the game. Defaults to 8.

Returns:

None

Return type:

int | None

await match_making_ban_role()[source]

Sends a matchmaking role selection request and retrieves selected role data.

Constructs a request with the type MATCH_MAKING_USER_SELECT_ROLE, sends it to the server, and then returns the data about how many users have selected roles.

Returns:

A dictionary with information about selected roles if available, otherwise None.

Return type:

dict | None

await match_making_get_status()[source]

Retrieves the current status of matchmaking.

Sends a request to the server to get the current matchmaking status and waits briefly for a response.

Returns:

The matchmaking status data received from the server, or None if no data is returned.

Return type:

dict | None

await match_making_remove_user()[source]

Removes the user from the matchmaking queue.

Sends a request to the server to remove the user from matchmaking. No response is expected.

Returns:

None

Return type:

None

await send_server(data, remove_token_from_object=False)[source]

Sends a packet to the server through the authenticated client.

Parameters:

  • data (dict) – The data to be sent to the server.

  • remove_token_from_object (bool, optional) – Whether to remove the token from the object before sending. Defaults to False.

Returns:

None

Return type:

None

await users_waiting_count(players_size=8)[source]

Retrieves the number of users currently waiting for a matchmaking game.

Sends a request to the server to get the number of players currently waiting in the matchmaking queue.

Parameters:

players_size (int, optional) – The desired number of players in the game. Defaults to 8.

Returns:

The response data containing the count of waiting users, or None if no data is returned.

Return type:

dict | None

class zafiaonline.api_client.HttpsApiMethods[source]

Bases: object

Provides HTTPS API interaction.

This class extends HttpWrapper to provide additional functionality for secure API access over HTTPS, including hashing utilities.

md5hash

An instance of Md5 used for computing MD5 hashes.

await backpack_get()[source]

Fetches the contents of the user’s backpack.

Returns:

A dictionary containing the backpack items, or raw bytes if the response is not in JSON format.

Return type:

dict | bytes

await backpack_get_bonus_prices()[source]

Retrieves bonus price information for backpack items.

Returns:

A dictionary with bonus pricing details, or raw bytes if the response is not in JSON format.

Return type:

dict | bytes

await change_email(new_email, password, language=MafiaLanguages.English)[source]

Sends a request to change the user’s email address.

Parameters:

  • new_email (str) – The new email address to set for the user.

  • password (str) – The user’s current password (used for verification).

  • language (MafiaLanguages) – The preferred language for the response.

Returns:

A dictionary with the server response on success, or raw bytes if the response is not JSON.

Return type:

dict | bytes

await email_verification(verification_code)[source]

Submits the email verification code to complete verification.

Parameters:

verification_code (str) – The code sent to the user’s email for verification.

Returns:

A dictionary containing the server response, or raw bytes if the response is not in JSON format.

Return type:

dict | bytes

await get_client_config(version=55)[source]

Fetches the client configuration for a given version.

Sends a GET request to retrieve configuration settings used by the client, such as feature flags, limits, or layout settings.

Parameters:

version (int) – The version number of the client configuration to retrieve. Defaults to 55.

Returns:

The client configuration data returned by the server. Can be a parsed JSON dictionary or raw response bytes.

Return type:

dict | bytes

await get_client_feature_config()[source]

Fetches the client feature configuration.

Sends a GET request to retrieve a list of enabled or experimental features available to the client.

Returns:

The feature configuration returned by the server. May be a parsed JSON dictionary or raw response bytes.

Return type:

dict | bytes

await get_profile_photo_request(user_id)[source]

Retrieves the profile photo of a user by user ID.

Sends a GET request to the server to fetch the profile picture associated with the specified user.

Parameters:

user_id (str) – The unique identifier of the user whose profile photo should be retrieved.

Returns:

The server response containing the profile photo data. This can be a dictionary with metadata or raw image bytes.

Return type:

dict | bytes

await remove_user_account_request(language=MafiaLanguages.English)[source]

Sends a request to remove the user’s account.

This method sends a POST request to the server to initiate account removal, using the specified language for localization.

Parameters:

language (MafiaLanguages) – A MafiaLanguages enum value indicating the language to use in the request. Defaults to English.

Returns:

The server’s response to the account removal request, typically a dictionary or raw bytes depending on API implementation.

Return type:

dict | bytes

await sign_out()[source]

Signs the user out of the current session.

Sends a POST request to terminate the user’s active session on the server.

Returns:

The server’s response to the sign-out request, which may be a parsed JSON dictionary or raw response bytes.

Return type:

dict | bytes

await sign_up(email, password, username='', language=MafiaLanguages.English)[source]

Registers a new user account.

Sends a sign-up request to the server with email, password, and optional username.

Parameters:

  • email (str) – The user’s email address.

  • password (str) – The user’s password, which will be hashed before sending.

  • username (str, optional) – An optional display name for the user.

  • language (MafiaLanguages) – The preferred language for the account.

Returns:

The server’s response to the sign-up request, either as parsed JSON or raw bytes.

Return type:

dict | bytes

await user_get(user_id)[source]

Retrieves public information about a user by their ID.

Parameters:

user_id (str) – The unique identifier of the user.

Returns:

A dictionary with the user’s public profile data, or raw bytes if the response is not in JSON format.

Return type:

dict | bytes

await verify_email(language=MafiaLanguages.English)[source]

Sends a verification email to the user’s address.

Parameters:

language (MafiaLanguages) – The preferred language for the email content.

Returns:

The server’s response containing status or raw response bytes.

Return type:

dict[str, str] | bytes

class zafiaonline.api_client.ZafiaApiMethods[source]

Bases: object

Asynchronous API client for interacting with Zafia user data and profile features.

This class provides high-level methods to access various Zafia endpoints, including actions like managing favorites, checking profile data, fetching leaderboard statistics, and verifying user accounts.

await change_favorite_status(user_id, favorite_id)[source]

Toggle the favorite status for a specific item by the user.

Sends a request to mark or unmark an item (identified by favorite_id) as a favorite for the specified user.

Parameters:

  • user_id (str) – The ID of the user performing the action.

  • favorite_id (str) – The ID of the item to be marked or unmarked as favorite.

Returns:

The server response indicating whether the update was successful.

Return type:

Dict[str, bool]

await change_visible_top(user_id, show=True)[source]

Changes the visibility status of the user on the top list.

Sends a request to the server to update whether the specified user should appear in the visible top list or not.

Parameters:

  • user_id (str) – The unique identifier of the user.

  • show (bool, optional) – Indicates whether the user should be shown in the top list. Defaults to True.

Returns:

A dictionary indicating whether the visibility status was successfully changed.

Return type:

Dict[str, bool]

await check_profile(user_id, check_id, user_nickname, check_nickname)[source]

Compares the specified user’s profile with another user’s profile.

This method checks whether the provided nicknames and user IDs match or meet some criteria defined by the backend for profile comparison.

Parameters:

  • user_id (str) – The unique identifier of the current user.

  • check_id (str) – The unique identifier of the user to check against.

  • user_nickname (str) – The nickname of the current user.

  • check_nickname (str) – The nickname of the user being checked.

Returns:

A dictionary indicating whether the profile comparison passed.

Return type:

Dict[str, bool]

await get_favorites_list(user_id, from_type=MethodGetFavourites.InviteMethod)[source]

Retrieves the list of favorite users for the specified user.

This method fetches the user’s favorites based on the specified method type, such as favorites added through invites or friend list means.

Parameters:

  • user_id (str) – The unique identifier of the user.

  • from_type (MethodGetFavourites, optional) – The method by which the favorites were added. Defaults to MethodGetFavourites.InviteMethod.

Returns:

A dictionary containing the list of favorite users.

Return type:

Dict[str, Any]

await get_top(user_id, top_type=RatingType.EXPERIENCE)[source]

Retrieves the leaderboard data for a given rating type.

This method fetches the top users from the specified leaderboard, such as by experience or other rating metrics.

Parameters:

  • user_id (str) – The ID of the user making the request.

  • top_type (RatingType, optional) – The type of leaderboard to retrieve. Defaults to RatingType.EXPERIENCE.

Returns:

A dictionary containing leaderboard data.

Return type:

Dict[str, Any]

await get_verifications(user_id, version=15, device_id='')[source]

Retrieves the list of verifications required for the client.

Sends a request to fetch current verification depending on the client version and device identifier.

Parameters:

  • user_id (str) – The ID of the user making the request.

  • version (int, optional) – The client version. Defaults to 15.

  • device_id (str, optional) – The device identifier. If not provided, a random one will be generated.

Returns:

A dictionary containing verification data.

Return type:

Dict[str, Any]

staticmethod with_user_id(func)[source]

Decorator that injects the ‘user_id’ into the request parameters.

This decorator modifies the ‘params’ dictionary passed to the wrapped function by adding the ‘user_id’ key.

Parameters:

func (Callable) – The asynchronous function to wrap.

Returns:

The wrapped asynchronous function with ‘user_id’ injected into the parameters.

Return type:

Callable