wip

docs/behavior/notifications-behavior.mdx

@@ -0,0 +1,57 @@
+---
+id: notifications
+title: Notifications
+---
+
+Recyclarr integrates with [Apprise API][apprise], a versatile notification platform, to offer robust
+notification capabilities. This integration allows Recyclarr to send notifications to a wide array
+of services, including popular platforms like Discord and Email. For a comprehensive list of
+supported notification targets, please refer to the [Apprise documentation][urls].
+
+This page provides an overview of Recyclarr's notification system, explaining its behavior and the
+information it provides. Notifications in Recyclarr are designed to keep you informed about sync
+operations, providing real-time updates on the process and detailed information about the results.
+
+[apprise]: https://github.com/caronc/apprise-api
+[urls]: https://github.com/caronc/apprise/wiki#notification-services
+
+## Setting Up Notifications
+
+To configure notifications for Recyclarr, you'll need to modify your `settings.yml` file. For
+detailed instructions on how to set up notifications, including examples and all available options,
+please refer to the [notification settings reference][settings] page.
+
+[settings]: /yaml/settings-reference/notifications.mdx
+
+## Notification Behavior
+
+Currently, Recyclarr's notification system is focused on [sync operations][sync]. Notifications are
+designed to be comprehensive, providing a complete overview of the operation without overwhelming
+you with too many messages. Here are some key points to understand about the notification behavior:
+
+- **Single Notification per Sync**: Recyclarr sends one consolidated notification for each `sync`
+  command execution, regardless of the number of service instances configured in your YAML file.
+
+- **Multi-Service Support**: If you have multiple service instances configured (e.g., 2 Radarr and 1
+  Sonarr), the single notification will include information about the sync operation for all
+  services.
+
+- **Timing**: The notification is sent upon completion of the entire sync operation across all
+  configured services.
+
+[sync]: /cli/sync.mdx
+
+## Notification Content
+
+The notification sent after each sync operation includes the following information:
+
+- **Overall Status**: An indication of whether the sync operation was successful or if it failed.
+
+- **Service-Specific Statistics**: For each service instance synced (e.g., Radarr, Sonarr), you'll
+  receive high-level statistical information, such as:
+  - Number of custom formats synced
+  - How many quality profiles were updated
+  - Other relevant metrics specific to the service
+
+- **Error and Warning Reports**: Any errors or warnings that occurred during the sync operation are
+  included in the notification.

docs/yaml/settings-reference/notifications.mdx

@@ -0,0 +1,80 @@
+---
+id: notifications
+title: Notifications
+---
+
+This page covers two different ways to configure Apprise notifications in Recyclarr: Stateless Mode
+and Stateful Mode.
+
+:::caution
+
+Details regarding how to use and configure Apprise itself is outside of the scope of this wiki page
+and, in particular, Recyclarr support channels. Apprise-specific questions should be directed to the
+appropriate Apprise support channels.
+
+:::
+
+## Stateful Mode
+
+When using [stateful mode], the details of which specific URLs to publish notifications to is
+controlled by Apprise API configuration.
+
+[stateful mode]: https://github.com/caronc/apprise-api#persistent-stateful-storage-solution
+
+```yml
+notifications:
+  apprise:
+    mode: stateful
+    base_url: http://localhost:8000
+    key: recyclarr
+    tags: foo bar, baz
+```
+
+Reference for the `apprise` section is below. Note that most of these values are forwarded directly
+to Apprise API and you should rely on their documentation for more information.
+
+- `mode` *(Required)*<br/>
+  Set this to `stateful` to enable stateful mode.
+
+- `base_url` *(Required)*<br/>
+  This is the base URL of the Apprise API server that Recyclarr should send notifications to.
+
+- `key` *(Required)*<br/>
+  The key represents a configuration file on the Apprise API server that will be used to determine
+  where notifications are sent.
+
+- `tags` *(Optional)*<br/>
+  Optionally notify only those URLs tagged accordingly. Use a comma (`,`) to `OR` your tags and a
+  space (` `) to `AND` them.
+
+## Stateless Mode
+
+Use [stateless mode] when you want to sidecar the Apprise API without it having access to storage.
+This means that Recyclarr's notification settings will contain the list of URLs to publish
+notifications to.
+
+[stateless mode]: https://github.com/caronc/apprise-api#stateless-mode
+
+```yml
+notifications:
+  apprise:
+    mode: stateless
+    base_url: http://localhost:8000
+    urls:
+      - https://discord.com/api/webhooks/secret
+```
+
+Reference for the `apprise` section is below. Note that most of these values are forwarded directly
+to Apprise API and you should rely on their documentation for more information.
+
+- `mode` *(Required)*<br/>
+  Set this to `stateless` to enable stateless mode.
+
+- `base_url` *(Required)*<br/>
+  This is the base URL of the Apprise API server that Recyclarr should send notifications to.
+
+- `urls` *(Required)*<br/>
+  One or more URLs that apprise will forward notifications to. If you want to know what kind of URLs
+  to put here, please visit the [Apprise API documentation][urls].
+
+[urls]: https://github.com/caronc/apprise/wiki#notification-services