Basic D-Bus API (#866)

* feat: basic D-Bus API

Expose muted state and the number of unread message over D-Bus when
running on Linux. This is useful for, e.g., displaying notifications on
a window manager status bar.

Signed-off-by: Kristóf Marussy <kristof@marussy.com>

* docs: create docs directory

Move the documentation to a separate directory so that new documentation
can be added into one place.

We keep the following files still in the repository root by convention:

* CHANGELOG.md
* CODE_OF_CONDUCT.md
* CONTRIBUTING.md
* LICENSE.md
* README.md
* SECURITY.md

Signed-off-by: Kristóf Marussy <kristof@marussy.com>

* docs: D-Bus usage example

Signed-off-by: Kristóf Marussy <kristof@marussy.com>

* fix: remove unneeded D-Bus signals

Only notify clients that the message counts or the mute status has
changed if there actually was a change.

Signed-off-by: Kristóf Marussy <kristof@marussy.com>

* docs: rewrite sample bar client

* docs: better unread --services help

* docs: update dbus docs

* docs: use ferdium-dbus in dbus bar example

* docs: make command argument required in bar example

---------

Signed-off-by: Kristóf Marussy <kristof@marussy.com>
Co-authored-by: Victor Bonnelle <victor.bonnelle@protonmail.com>

3 files changed, 183 insertions, 0 deletions

diff --git a/docs/dbus/ferdium_bar.py b/docs/dbus/ferdium_bar.py
new file mode 100644
index 000000000..6fd5d8c30
--- /dev/null
+++ b/docs/dbus/ferdium_bar.py
@@ -0,0 +1,102 @@
+import asyncio
+import argparse
+import html
+
+from ferdium_dbus import Client
+
+
+async def toggle_window(client, args):
+    """Toggle window visibility"""
+
+    await client.toggle_window()
+
+
+async def toggle_mute(client, args):
+    """Toggle mute status"""
+
+    await client.toggle_mute()
+
+
+async def unread(client, args):
+    """Get unread messages count"""
+
+    def callback():
+        """Print unread count(s)"""
+
+        # For each service
+        counts = {}
+        for service in client.unread_services:
+            name, direct, indirect = service
+            safe_name = html.escape(name)
+
+            # If it's exactly the service we're looking for, just return the count
+            if safe_name == args.services:
+                count = direct
+                if not args.direct:
+                    count += indirect
+                print(count)
+                return
+
+            # If the service in included in the services we're looking for
+            if args.services in ("total", "all") or safe_name in args.services:
+                counts[safe_name] = direct
+                if not args.direct:
+                    counts[safe_name] += indirect
+
+        # Get total notifications
+        if args.services == "total":
+            print(sum(counts.values()))
+            return
+
+        # Finally, print each service notifications on a different line
+        print(
+            "\n".join(
+                f"{name}: {count}"
+                for name, count in counts.items()
+            )
+        )
+
+    # Do print counts and keep running if tail mode enabled
+    callback()
+    if args.tail:
+        client.on_change(callback)
+        await asyncio.get_running_loop().create_future()
+
+
+async def main():
+    """Main cli interface"""
+
+    # Define commands
+    commands = {
+        "unread": unread,
+        "toggle-mute": toggle_mute,
+        "toggle-window": toggle_window,
+    }
+
+    # Arguments parser
+    argparser = argparse.ArgumentParser(description="Script to interact with Ferdium on your bar")
+    subparsers = argparser.add_subparsers(dest="command", required=True)
+    # Unread command
+    argparser_unread = subparsers.add_parser("unread", help=unread.__doc__)
+    argparser_unread.add_argument("-s", "--services", default="total", help="Which services to get notifications from {total, all, <name>} (the name can be a comma-separated list)")
+    argparser_unread.add_argument("-d", "--direct", action="store_true", default=False, help="Get only direct (mentions or DM) messages")
+    argparser_unread.add_argument("-t", "--tail", action="store_true", default=False, help="Keep running and print on change")
+    # Toggle mute and toggle window commands
+    argparser_toggle_mute = subparsers.add_parser("toggle-mute", help=toggle_mute.__doc__)
+    argparser_toggle_window = subparsers.add_parser("toggle-window", help=toggle_window.__doc__)
+    # Get args
+    args = argparser.parse_args()
+
+    # Initialise ferdium client
+    client = Client()
+    await client.connect()
+    if not client.running:
+        print("not running")
+        return
+
+    # Execute command
+    await commands[args.command](client, args)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/docs/dbus/org.ferdium.Ferdium.xml b/docs/dbus/org.ferdium.Ferdium.xml
new file mode 100644
index 000000000..8c66a9e21
--- /dev/null
+++ b/docs/dbus/org.ferdium.Ferdium.xml
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+  <!--
+    org.ferdium.Ferdium:
+    @short_description: Control Ferdium from the desktop
+
+    Interface for accessing Ferdium notification state, allowing notification
+    counts to be displayed in the desktop (e.g., on a status bar) and updating
+    the muted state of notifications.
+
+    The #org.ferdium.UnreadDirectMessageCount,
+    #org.ferdium.UnreadIndirectMessageCount, and #org.ferdium.UnreadServices
+    are affected by notification muting and hiding settings of Ferdium.
+    In particular, they are not updated if #org.ferdium.Muted is #TRUE.
+    Moreover, services with muted notifications or hidden indirect message
+    counts will not appear in the respective counts.
+    This behavior is consistent with the behavior of the Ferdium tray icon.
+  -->
+  <interface name="org.ferdium.Ferdium">
+    <!--
+      ToggleMute:
+
+      Toggles the muted state of notifcations.
+
+      Use the #org.ferdium.Ferdium.Muted property to get or set the current
+      muted state.
+    -->
+    <method name="ToggleMute" />
+    <!--
+      ToggleWindow:
+
+      Brings the Ferdium window into the foreground if it is not currently
+      focused. Hides the Ferdium window if is is currently focused.
+
+      Calling this method is equivalent to clicking on the Ferdium tray icon.
+    -->
+    <method name="ToggleWindow" />
+    <!--
+      Muted:
+
+      Gets or sets the current muted state of notifications.
+
+      #TRUE if notifications are currently muted, #FALSE otherwise.
+    -->
+    <property name="Muted" type="b" access="readwrite" />
+    <!--
+      UnreadDirectMessageCount:
+
+      The number of unread direct messages.
+    -->
+    <property name="UnreadDirectMessageCount" type="u" access="read" />
+    <!--
+      UnreadIndirectMessageCount:
+
+      The number of unread indirect messages.
+    -->
+    <property name="UnreadIndirectMessageCount" type="u" access="read" />
+    <!--
+      UnreadServices:
+
+      The list of services with unread messages.
+
+      The value of this property is an array of structs corresponding to each
+      service with unread messages.
+      The elements of a struct are the following:
+
+      1. The name of the service.
+
+      2. The number of unread direct messages of the service.
+
+      3. The number of unread indirect messages of the service.
+
+      Services with no unread direct or indirect messages (i.e., structs with
+      the second and third element set to 0) are omitted from the array.
+    -->
+    <property name="UnreadServices" type="a(suu)" access="read" />
+  </interface>
+</node>
diff --git a/docs/dbus/requirements.txt b/docs/dbus/requirements.txt
new file mode 100644
index 000000000..d08a849d9
--- /dev/null
+++ b/docs/dbus/requirements.txt
@@ -0,0 +1 @@
+git+https://github.com/victorbnl/ferdium-dbus-py