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>

6 files changed, 269 insertions, 0 deletions

diff --git a/docs/DBUS.md b/docs/DBUS.md
new file mode 100644
index 000000000..ffbd61f4b
--- /dev/null
+++ b/docs/DBUS.md
@@ -0,0 +1,20 @@
+# D-Bus interface
+
+Ferdium exposes an inter-process communication on Linux systems via [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/).
+This allows integrating Ferdium with your desktop environment by displaying the number of unread notifications in a status area and muting or unmuting notations.
+
+## Desktop integration
+
+As an example integration, the [`docs/dbus`](dbus) folder contains a module for status bars written in Python.
+To run the example, you'll need Python 3.11 and the [`dbus-next`](https://pypi.org/project/dbus-next/) PyPI package.
+
+The integration uses the [`FerdiumClient`](dbus/ferdium_client.py) client library, which is an asynchronous wrapper over the D-Bus interface.
+It illustrates multiple advanced concepts, such as asynchronous communication with Ferdium via `asyncio` and polling the session D-Bus to see if Ferdium is running.
+
+The [`ferdium_bar.py`](dbus/ferdium_bar.py) implements a bar module to use with status bars such as waybar or polybar. See `ferdium_bar.py --help` and `ferdium_bar.py unread --help` for further indications on how to use it.
+
+## Low-level API
+
+The low-level API exposed over D-Bus is documented in [`org.ferdium.Ferdium.xml](docs/org.ferdium.Ferdium.xml) with standard D-Bus introspection syntax.
+
+Ferdium will take ownership of the bus name `org.ferdium.Ferdium` and expose and object implementing the `org.ferdium.Ferdium` interface at the object path `/org/ferdium`.
diff --git a/docs/INTERNAL_SERVER.md b/docs/INTERNAL_SERVER.md
new file mode 100644
index 000000000..9e94f9bdf
--- /dev/null
+++ b/docs/INTERNAL_SERVER.md
@@ -0,0 +1,28 @@
+<p align="center">
+    <img src="../src/internal-server/public/images/logo.png" alt="" width="300"/>
+</p>
+
+# ferdium-internal-server
+Internal Ferdium Server used for storing settings/preferences without logging into an external server.
+
+## Differences to ferdium-server
+- Doesn't contain user management (only one user)
+- Doesn't require logging in
+- No recipe creation
+- Contains `start.js` script to allow starting the server via script
+- Uses `env.ini` instead of `.env` to stay compatible with Ferdium's build script
+- Only allows Ferdium clients to connect to the API
+
+## Configuration
+`ferdium-internal-server's` configuration is saved inside the `env.ini` file. Besides AdonisJS's settings, `ferdium-internal-server` has the following custom settings:
+- `CONNECT_WITH_FRANZ` (`true` or `false`, default: `true`): Whether to enable connections to the Franz server. By enabling this option, `ferdium-internal-server` can:
+  - Show the full Franz/Ferdi recipe library instead of only custom recipes
+  - Import Franz/Ferdi accounts
+
+## Exporting backups
+Since the `ferdium-internal-server` runs a local server, there's no automatic syncing of settings possible. You can backup your settings, by clicking on `Help > Import/Export Configuration Data` which will open the running server page in your browser. Choose the option to export and save the generated file.
+
+## Importing your Franz/Ferdi account
+`ferdium-internal-server` allows you to import your full Franz account, including all its settings.
+
+To import your Franz/Ferdi account, within Ferdium, click on `Help > Import/Export Configuration Data` which will open the running server page in your browser. You can then login using your Franz account details. `ferdium-internal-server` will create a new user with the same credentials and copy your Franz settings, services and workspaces.
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
new file mode 100644
index 000000000..bb1ca315d
--- /dev/null
+++ b/docs/MIGRATION.md
@@ -0,0 +1,38 @@
+# Migrating account data
+
+This guide is here to show you how to export your current Ferdi setup from the online server or from an accountless session for safe-keeping, backup or transferring to a new instance using only a browser.
+
+Before getting into the details of using an online account vs accountless, let's quickly review what the differences are between the two of them:
+
+## Using Ferdi with an Account
+
+The main advantage of using Ferdi with an account is that you have your configuration data stored on a cloud - and thus, when moving to a different machine, once you login, all these configurations are applied to the Ferdi instance on your new machine.
+
+**But**, if you use a Ferdi account, you need to reach their servers. If the servers are not accessible, you sadly have no other options for getting your data as there are no local copies. So it is advised to do this as soon as there's a chance - just to be safe.
+
+## Using Ferdi without an account i.e. Accountless
+
+Accountless instances have all the same functionality as account-based ones with the exception of multi-machine syncronization. If you don't intend to use this app on multiple machines with regularly changing settings and lists of services, there's no benefit to having an online account. Having a backup of your `export.ferdi-data` whenever you make changes to your setup, provides a similarly secure (albeit slower and manual alternative) to automatic syncing that doesn't rely on a server's constant availability.
+
+## Exporting
+
+Depending on where you have your account, you have to visit separate sites to retrieve it. This has no impact on your current instances. You can follow the next steps to access and export that data irrespective of which online server holds your data.
+
+1. Have Ferdi running on your system. (Even if you are on the initial "Get started" page, these instructions will work.)
+2. Go to `Help > Import/Export Configuration Data` which should open the corresponding url in your default browser.
+3. Click on `export your data to a ".ferdi-data" file`.
+4. Save the `export.ferdi-data` file to anywhere you'd like for safe-keeping/backup.
+
+## Importing
+
+1. Have Ferdium running on your system.
+2. When you get to the screen that says "Get Started", go to `Help > Import/Export Configuration Data` which should open a local url in your default browser.
+3. Click on `import your data from a ".ferdium-data" or ".ferdi-data" file`.
+4. Using the File browser button, find the previously saved `export.ferdi-data` file on your system and click the "Import data" button.
+5. Restart your application.
+
+_Note:_
+
+1. Setting up new instances or migrating to an accountless setup will require all services to be logged-in by hand again. This is because the session information only stays on your local machine - ever.
+2. Importing data does not override the list of local services if you have any, but adds them to the current list. This is normal behavior. If you do not want to deal with duplicate instances of services, you can delete your pre-existing services prior to importing from the previously exported data file.
+3. Due to current risks of losing access to Ferdi's services, it is ill-advised to use their servers in the future. You should setup your own server while you wait for official Ferdium solutions (if automatic syncing is important to you).
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