[WIP]

docs/source/conf.py

@@ -138,15 +138,12 @@ latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -156,8 +153,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'platypush.tex', 'platypush Documentation',
+    (master_doc, 'platypush.tex', 'platypush Documentation', 'BlackLight', 'manual'),
-     'BlackLight', 'manual'),
 ]
 
 
@@ -165,10 +161,7 @@ latex_documents = [
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
+man_pages = [(master_doc, 'platypush', 'platypush Documentation', [author], 1)]
-    (master_doc, 'platypush', 'platypush Documentation',
-     [author], 1)
-]
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -177,9 +170,15 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'platypush', 'platypush Documentation',
+    (
-     author, 'platypush', 'One line description of project.',
+        master_doc,
-     'Miscellaneous'),
+        'platypush',
+        'platypush Documentation',
+        author,
+        'platypush',
+        'One line description of project.',
+        'Miscellaneous',
+    ),
 ]
 
 
@@ -199,7 +198,8 @@ autodoc_default_options = {
     'inherited-members': True,
 }
 
-autodoc_mock_imports = ['googlesamples.assistant.grpc.audio_helpers',
+autodoc_mock_imports = [
+    'googlesamples.assistant.grpc.audio_helpers',
     'google.assistant.embedded',
     'google.assistant.library',
     'google.assistant.library.event',
@@ -291,6 +291,7 @@ autodoc_mock_imports = ['googlesamples.assistant.grpc.audio_helpers',
     'irc.connection',
     'irc.events',
     'defusedxml',
+    'nio',
 ]
 
 sys.path.insert(0, os.path.abspath('../..'))

platypush/message/event/matrix.py

@@ -67,6 +67,92 @@ class MatrixMessageEvent(MatrixEvent):
         super().__init__(*args, body=body, **kwargs)
 
 
+class MatrixMediaMessageEvent(MatrixMessageEvent):
+    """
+    Event triggered when a media message is received on a subscribed room.
+    """
+
+    def __init__(self, *args, url: str, **kwargs):
+        """
+        :param url: The URL of the media file.
+        """
+        super().__init__(*args, url=url, **kwargs)
+
+
+class MatrixStickerEvent(MatrixMediaMessageEvent):
+    """
+    Event triggered when a sticker is sent to a room.
+    """
+
+
+class MatrixReactionEvent(MatrixEvent):
+    """
+    Event triggered when a user submits a reaction to an event.
+    """
+
+    def __init__(self, *args, in_response_to_event_id: str, **kwargs):
+        """
+        :param in_response_to_event_id: The ID of the URL related to the reaction.
+        """
+        super().__init__(
+            *args, in_response_to_event_id=in_response_to_event_id, **kwargs
+        )
+
+
+class MatrixEncryptedMessageEvent(MatrixMessageEvent):
+    """
+    Event triggered when a message is received but the client doesn't
+    have the E2E keys to decrypt it, or encryption has not been enabled.
+    """
+
+
+class MatrixCallEvent(MatrixEvent):
+    """
+    Base class for Matrix call events.
+    """
+
+    def __init__(
+        self, *args, call_id: str, version: int, sdp: str | None = None, **kwargs
+    ):
+        """
+        :param call_id: The unique ID of the call.
+        :param version: An increasing integer representing the version of the call.
+        :param sdp: SDP text of the session description.
+        """
+        super().__init__(*args, call_id=call_id, version=version, sdp=sdp, **kwargs)
+
+
+class MatrixCallInviteEvent(MatrixCallEvent):
+    """
+    Event triggered when the user is invited to a call.
+    """
+
+    def __init__(self, *args, invite_validity: float | None = None, **kwargs):
+        """
+        :param invite_validity: For how long the invite will be valid, in seconds.
+        :param sdp: SDP text of the session description.
+        """
+        super().__init__(*args, invite_validity=invite_validity, **kwargs)
+
+
+class MatrixCallAnswerEvent(MatrixCallEvent):
+    """
+    Event triggered by the callee when they wish to answer the call.
+    """
+
+
+class MatrixCallHangupEvent(MatrixCallEvent):
+    """
+    Event triggered when a participant in the call exists.
+    """
+
+
+class MatrixRoomCreatedEvent(MatrixEvent):
+    """
+    Event triggered when a room is created.
+    """
+
+
 class MatrixRoomJoinEvent(MatrixEvent):
     """
     Event triggered when a user joins a room.
@@ -81,17 +167,11 @@ class MatrixRoomLeaveEvent(MatrixEvent):
 
 class MatrixRoomInviteEvent(MatrixEvent):
     """
-    Event triggered when a user is invited to a room.
+    Event triggered when the user is invited to a room.
     """
 
 
-class MatrixRoomInviteMeEvent(MatrixEvent):
+class MatrixRoomTopicChangedEvent(MatrixEvent):
-    """
-    Event triggered when the currently logged in user is invited to a room.
-    """
-
-
-class MatrixRoomTopicChangeEvent(MatrixEvent):
     """
     Event triggered when the topic/title of a room changes.
     """

platypush/plugins/matrix/manifest.yaml

@@ -1,10 +1,25 @@
 manifest:
   events:
     platypush.message.event.matrix.MatrixMessageEvent: when a message is received.
+    platypush.message.event.matrix.MatrixMediaMessageEvent: when a media message is received.
+    platypush.message.event.matrix.MatrixRoomCreatedEvent: when a room is created.
     platypush.message.event.matrix.MatrixRoomJoinEvent: when a user joins a room.
     platypush.message.event.matrix.MatrixRoomLeaveEvent: when a user leaves a room.
-    platypush.message.event.matrix.MatrixRoomInviteEvent: when a user (other than the currently logged one) is invited to a room.
+    platypush.message.event.matrix.MatrixRoomInviteEvent: when the user is invited to a room.
-    platypush.message.event.matrix.MatrixRoomMeInviteEvent: when the currently logged in user is invited to a room.
+    platypush.message.event.matrix.MatrixRoomTopicChangedEvent: when the topic/title of a room changes.
-    platypush.message.event.matrix.MatrixRoomTopicChangeEvent: when the topic/title of a room changes.
+    platypush.message.event.matrix.MatrixCallInviteEvent: when the user is invited to a call.
+    platypush.message.event.matrix.MatrixCallAnswerEvent: when a called user wishes to pick the call.
+    platypush.message.event.matrix.MatrixCallHangupEvent: when a called user exits the call.
+    platypush.message.event.matrix.MatrixStickerEvent: when a sticker is sent to a room.
+    platypush.message.event.matrix.MatrixEncryptedMessageEvent: |
+      when a message is received but the client doesn't
+      have the E2E keys to decrypt it, or encryption has not been enabled.
+  apt:
+    - libolm-devel
+  pacman:
+    - libolm
+  pip:
+    - matrix-nio[e2e]
+    - async_lru
   package: platypush.plugins.matrix
   type: plugin

platypush/schemas/matrix.py

@@ -0,0 +1,109 @@
+from marshmallow import fields
+from marshmallow.schema import Schema
+
+from platypush.schemas import DateTime
+
+
+class MatrixProfileSchema(Schema):
+    user_id = fields.String(
+        required=True,
+        metadata={
+            'description': 'User ID',
+            'example': '@myuser:matrix.example.org',
+        },
+    )
+
+    display_name = fields.String(
+        attribute='displayname',
+        metadata={
+            'description': 'User display name',
+            'example': 'Foo Bar',
+        },
+    )
+
+    avatar_url = fields.URL(
+        metadata={
+            'description': 'User avatar URL',
+            'example': 'mxc://matrix.platypush.tech/AbCdEfG0123456789',
+        }
+    )
+
+
+class MatrixRoomSchema(Schema):
+    room_id = fields.String(
+        required=True,
+        metadata={
+            'description': 'Room ID',
+            'example': '!aBcDeFgHiJkMnO:matrix.example.org',
+        },
+    )
+
+    name = fields.String(
+        metadata={
+            'description': 'Room name',
+            'example': 'My Room',
+        }
+    )
+
+    display_name = fields.String(
+        metadata={
+            'description': 'Room display name',
+            'example': 'My Room',
+        }
+    )
+
+    topic = fields.String(
+        metadata={
+            'description': 'Room topic',
+            'example': 'My Room Topic',
+        }
+    )
+
+    avatar_url = fields.URL(
+        attribute='room_avatar_url',
+        metadata={
+            'description': 'Room avatar URL',
+            'example': 'mxc://matrix.platypush.tech/AbCdEfG0123456789',
+        },
+    )
+
+    owner_id = fields.String(
+        attribute='own_user_id',
+        metadata={
+            'description': 'Owner user ID',
+            'example': '@myuser:matrix.example.org',
+        },
+    )
+
+    encrypted = fields.Bool()
+
+
+class MatrixDeviceSchema(Schema):
+    device_id = fields.String(
+        required=True,
+        attribute='id',
+        metadata={
+            'description': 'ABCDEFG',
+        },
+    )
+
+    display_name = fields.String(
+        metadata={
+            'description': 'Device display name',
+            'example': 'My Device',
+        }
+    )
+
+    last_seen_ip = fields.String(
+        metadata={
+            'description': 'Last IP associated to this device',
+            'example': '1.2.3.4',
+        }
+    )
+
+    last_seen_date = DateTime(
+        metadata={
+            'description': 'The last time that the device was reported online',
+            'example': '2022-07-23T17:20:01.254223',
+        }
+    )

setup.py

@@ -268,5 +268,7 @@ setup(
         'ngrok': ['pyngrok'],
         # Support for IRC integration
         'irc': ['irc'],
+        # Support for the Matrix integration
+        'matrix': ['matrix-nio'],
     },
 )