profanity/apidocs/python/src/plugin.py

"""
The plugin module defines optional callback functions that CProof plugins can
implement to handle events such as startup, shutdown, message processing, and
presence updates.

All functions are optional and are called by CProof when the corresponding event
occurs. You need to define them in your module and they will automatically be used
for callback events.

To utilize full functionality, such as the ``prof.cons_show`` function, see ``prof``
documentation and use::

    import prof
"""

# Initialization and Lifecycle
# ---------------------------

def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None:
    """Initializes the plugin when loaded by CProof.

    Called when CProof starts or when the plugin is loaded via the ``/plugins load``
    or ``/plugins install`` commands.

    :param version: The version of CProof (e.g., ``"1.0.0"``).
    :param status: The package status of CProof (``"development"`` or ``"release"``).
    :param account_name: The account name of the logged-in user, or None if not logged in.
    :param fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in.
    :return: None

    Example::

            def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None:
                prof.cons_show(f"MyPlugin for CProof {version} ({status}) has been loaded, account: {account_name}")
    """
    pass

def prof_on_start() -> None:
    """Called when CProof starts.

    Use this to perform setup tasks that should occur at application startup.

    :return: None

    Example::

            def prof_on_start() -> None:
                prof.cons_show("CProof has started...")
    """
    pass

def prof_on_shutdown() -> None:
    """Called when CProof is shutting down.

    Use this to perform cleanup tasks before the application exits.

    :return: None

    Example::

            def prof_on_shutdown() -> None:
                prof.cons_show("CProof is shutting down...")
    """
    pass

def prof_on_unload() -> None:
    """Called when the plugin is unloaded via the ``/plugins unload`` command.

    Use this to clean up plugin-specific resources.

    :return: None

    Example::

            def prof_on_unload() -> None:
                prof.cons_show("Plugin unloaded")
    """
    pass

def prof_on_connect(account_name: str, fulljid: str) -> None:
    """Called when a user connects to CProof with an account.

    :param account_name: The account name used for login.
    :param fulljid: The full Jabber ID (barejid/resource) of the connected account.
    :return: None

    Example::

            def prof_on_connect(account_name: str, fulljid: str) -> None:
                prof.cons_show(f"Connected as {account_name} ({fulljid})")
    """
    pass

def prof_on_disconnect(account_name: str, fulljid: str) -> None:
    """Called when a user disconnects an account from CProof.

    :param account_name: The account name being disconnected.
    :param fulljid: The full Jabber ID (barejid/resource) of the disconnected account.
    :return: None

    Example::

            def prof_on_disconnect(account_name: str, fulljid: str) -> None:
                prof.cons_show(f"Disconnected {account_name} ({fulljid})")
    """
    pass

# Chat Message Handlers
# ---------------------

def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None:
    """Called before a chat message is displayed in a chat window.

    Allows the plugin to modify or cancel the message display.

    :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
    :param resource: The sender's resource (e.g., ``laptop``).
    :param message: The received message.
    :return: The modified message to display, or None to preserve the original.

    Example::

            def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None:
                new_message = f"{message} (from {barejid})"
                return new_message
    """
    pass

def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None:
    """Called after a chat message is displayed in a chat window.

    Use this to perform actions after the message is shown.

    :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
    :param resource: The sender's resource (e.g., ``laptop``).
    :param message: The displayed message.
    :return: None

    Example::

            def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None:
                prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}")
    """
    pass

def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
    """Called before a chat message is sent from CProof.

    Allows the plugin to modify or cancel the message.

    :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
    :param message: The message to be sent.
    :return: The modified message to send, or None to cancel sending.

    Example::

            def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
                return f"{message} (sent by plugin)"
    """
    pass

def prof_post_chat_message_send(barejid: str, message: str) -> None:
    """Called after a chat message is sent from CProof.

    Use this to log or react to sent messages.

    :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
    :param message: The sent message.
    :return: None

    Example::

            def prof_post_chat_message_send(barejid: str, message: str) -> None:
                prof.cons_show(f"Sent to {barejid}: {message}")
    """
    pass

# Room Message Handlers
# ---------------------

def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None:
    """Called before a chat room message is displayed.

    Allows the plugin to modify or cancel the message display.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param nick: The nickname of the message sender.
    :param message: The received message.
    :return: The modified message to display, or None to preserve the original.

    Example::

            def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None:
                return f"{message} (from {nick})"
    """
    pass

def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None:
    """Called after a chat room message is displayed.

    Use this to perform actions after the message is shown.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param nick: The nickname of the message sender.
    :param message: The displayed message.
    :return: None

    Example::

            def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None:
                prof.cons_show(f"Displayed in {barejid} from {nick}: {message}")
    """
    pass

def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
    """Called before a chat room message is sent.

    Allows the plugin to modify or cancel the message.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param message: The message to be sent.
    :return: The modified message to send, or None to cancel sending.

    Example::

            def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
                return f"{message} (sent by plugin)"
    """
    pass

def prof_post_room_message_send(barejid: str, message: str) -> None:
    """Called after a chat room message is sent.

    Use this to log or react to sent messages.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param message: The sent message.
    :return: None

    Example::

            def prof_post_room_message_send(barejid: str, message: str) -> None:
                prof.cons_show(f"Sent to {barejid}: {message}")
    """
    pass

def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None:
    """Called when a chat room history message is received from the server.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param nick: The nickname of the message sender.
    :param message: The received message.
    :param timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``).
    :return: None

    Example::

            def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None:
                prof.cons_show(f"History in {barejid} from {nick} at {timestamp}: {message}")
    """
    pass

# Private Message Handlers
# ------------------------

def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None:
    """Called before a private chat room message is displayed.

    Allows the plugin to modify or cancel the message display.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param nick: The nickname of the message sender.
    :param message: The received message.
    :return: The modified message to display, or None to preserve the original.

    Example::

            def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None:
                return f"{message} (private from {nick})"
    """
    pass

def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None:
    """Called after a private chat room message is displayed.

    Use this to perform actions after the message is shown.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param nick: The nickname of the message sender.
    :param message: The displayed message.
    :return: None

    Example::

            def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None:
                prof.cons_show(f"Displayed private in {barejid} from {nick}: {message}")
    """
    pass

def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None:
    """Called before a private chat room message is sent.

    Allows the plugin to modify or cancel the message.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param nick: The nickname of the message recipient.
    :param message: The message to be sent.
    :return: The modified message to send, or None to cancel sending.

    Example::

            def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None:
                return f"{message} (private to {nick})"
    """
    pass

def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
    """Called after a private chat room message is sent.

    Use this to log or react to sent messages.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :param nick: The nickname of the message recipient.
    :param message: The sent message.
    :return: None

    Example::

            def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
                prof.cons_show(f"Sent private to {nick} in {barejid}: {message}")
    """
    pass

# Stanza Handlers
# ---------------

def prof_on_message_stanza_send(stanza: str) -> str | None:
    """Called before an XMPP message stanza is sent.

    Allows the plugin to modify or cancel the stanza.

    :param stanza: The XMPP message stanza to send.
    :return: The modified stanza to send, or None to preserve the original.

    Example::

            def prof_on_message_stanza_send(stanza: str) -> str | None:
                prof.cons_show(f"Sending message stanza: {stanza}")
                return stanza
    """
    pass

def prof_on_message_stanza_receive(stanza: str) -> bool:
    """Called when an XMPP message stanza is received.

    Allows the plugin to control whether CProof processes the stanza.

    :param stanza: The received XMPP message stanza.
    :return: True to allow CProof to process the stanza, False to block processing.

    Example::

            def prof_on_message_stanza_receive(stanza: str) -> bool:
                prof.cons_show(f"Received message stanza: {stanza}")
                return True
    """
    pass

def prof_on_presence_stanza_send(stanza: str) -> str | None:
    """Called before an XMPP presence stanza is sent.

    Allows the plugin to modify or cancel the stanza.

    :param stanza: The XMPP presence stanza to send.
    :return: The modified stanza to send, or None to preserve the original.

    Example::

            def prof_on_presence_stanza_send(stanza: str) -> str | None:
                prof.cons_show(f"Sending presence stanza: {stanza}")
                return stanza
    """
    pass

def prof_on_presence_stanza_receive(stanza: str) -> bool:
    """Called when an XMPP presence stanza is received.

    Allows the plugin to control whether CProof processes the stanza.

    :param stanza: The received XMPP presence stanza.
    :return: True to allow CProof to process the stanza, False to block processing.

    Example::

            def prof_on_presence_stanza_receive(stanza: str) -> bool:
                prof.cons_show(f"Received presence stanza: {stanza}")
                return True
    """
    pass

def prof_on_iq_stanza_send(stanza: str) -> str | None:
    """Called before an XMPP IQ stanza is sent.

    Allows the plugin to modify or cancel the stanza.

    :param stanza: The XMPP IQ stanza to send.
    :return: The modified stanza to send, or None to preserve the original.

    Example::

            def prof_on_iq_stanza_send(stanza: str) -> str | None:
                prof.cons_show(f"Sending IQ stanza: {stanza}")
                return stanza
    """
    pass

def prof_on_iq_stanza_receive(stanza: str) -> bool:
    """Called when an XMPP IQ stanza is received.

    Allows the plugin to control whether CProof processes the stanza.

    :param stanza: The received XMPP IQ stanza.
    :return: True to allow CProof to process the stanza, False to block processing.

    Example::

            def prof_on_iq_stanza_receive(stanza: str) -> bool:
                prof.cons_show(f"Received IQ stanza: {stanza}")
                return True
    """
    pass

# Contact Presence Handlers
# -------------------------

def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None:
    """Called when a contact goes offline.

    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
    :param resource: The resource being disconnected (e.g., ``laptop``).
    :param status: The status message received with the offline presence, or None.
    :return: None

    Example::

            def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None:
                prof.cons_show(f"{barejid}/{resource} went offline: {status or 'No status'}")
    """
    pass

def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None:
    """Called when a presence notification is received from a contact.

    :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
    :param resource: The resource of the contact (e.g., ``laptop``).
    :param presence: The contact's presence (``"chat"``, ``"online"``, ``"away"``, ``"xa"``, or ``"dnd"``).
    :param status: The status message received with the presence, or None.
    :param priority: The priority associated with the resource.
    :return: None

    Example::

            def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None:
                prof.notify(f"{barejid} is {presence}", 5000, "Presence")
    """
    pass

# Window Focus Handlers
# ---------------------

def prof_on_chat_win_focus(barejid: str) -> None:
    """Called when a chat window is focused.

    :param barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``).
    :return: None

    Example::

            def prof_on_chat_win_focus(barejid: str) -> None:
                prof.cons_show(f"Focused chat window for {barejid}")
    """
    pass

def prof_on_room_win_focus(barejid: str) -> None:
    """Called when a chat room window is focused.

    :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
    :return: None

    Example::

            def prof_on_room_win_focus(barejid: str) -> None:
                prof.cons_show(f"Focused room window for {barejid}")
    """
    pass