# redbear-notifications — D-Bus Interface

**Bus:** session
**Well-known name:** `org.freedesktop.Notifications`
**Object paths:**
- `/org/freedesktop/Notifications` — Notifications server

## Interface: `org.freedesktop.Notifications`

### Methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `Notify` | `(app_name: s, replaces_id: u, app_icon: s, summary: s, body: s, actions: as, hints: a{sv}, expire_timeout: i) → (u)` | Create or replace a notification. Returns notification ID. If `replaces_id` is non-zero and matches an existing notification owned by the same sender, the record is updated in-place. Maximum 1024 active notifications. |
| `CloseNotification` | `(id: u) → ()` | Close a notification by ID. Emits `NotificationClosed` signal with reason 3 (closed). |
| `GetCapabilities` | `() → (as)` | Returns `["body", "body-markup"]` |
| `GetServerInformation` | `() → (ssss)` | Returns `("Red Bear Notifications", "redbear", "0.3.1", "1.2")` |
| `InvokeAction` | `(id: u, action_key: s) → ()` | Invoke an action on a notification. Validates: (1) caller is the notification owner, (2) the action key was declared at notify time. Emits `ActionInvoked` signal, then removes the notification. |

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `Idle` | `b` | Always `false` (idle tracking not implemented) |

### Signals

| Signal | Signature | Description |
|--------|-----------|-------------|
| `NotificationClosed` | `(id: u, reason: u)` | A notification was closed. Reason: 1=expired, 2=dismissed, 3=closed. |
| `ActionInvoked` | `(id: u, action_key: s)` | An action was invoked on a notification. |

## Notification Lifecycle

1. **Creation** (`Notify`): A notification record is stored with owner (sender bus name), action keys, expire timeout, and issue timestamp. Monotonically increasing IDs starting from 1. If `replaces_id` matches an existing record, that record is updated; otherwise a new record is created.

2. **Expiry** (background sweeper, 500 ms interval): Notifications with `expire_timeout > 0` are checked against `issued_at + expire_timeout`. Expired notifications are removed and `NotificationClosed(1)` is emitted. Notifications with `expire_timeout <= 0` never expire.

3. **Action invocation** (`InvokeAction`): Validates sender ownership and action key. Emits `ActionInvoked`, then removes the notification and emits `NotificationClosed(2)`.

4. **Close** (`CloseNotification`): Removes the notification and emits `NotificationClosed(3)`.

5. **Sender vanishing** (background reaper, 2 s interval): Every 2 seconds, the daemon queries `org.freedesktop.DBus.NameHasOwner` for each tracked sender. If a sender has vanished from the bus, all its notifications are removed and `NotificationClosed(2)` is emitted for each.

6. **Bound enforcement**: When the active notification count exceeds 1024, the oldest notification (by insertion order) is evicted and `NotificationClosed(2)` is emitted.

## Action Format

The `actions` parameter is a flat string array of alternating key-label pairs:
```
["default", "Open", "reply", "Reply"]
```
The daemon extracts keys (every even-indexed element) and validates `InvokeAction` against them.

## Connection

- Session bus (`ConnectionBuilder::session()`)
- Registers well-known name `org.freedesktop.Notifications` on the session bus

## References
- [Desktop Notifications Specification](https://specifications.freedesktop.org/notification-spec/notification-spec-latest.html) v1.2
- Conformance: Full Notify/CloseNotification/GetCapabilities/GetServerInformation. Action invocation with ownership validation. Expiry sweeper. Sender reaper for vanished bus names. Bounded notification store (1024 max). No persistence across restarts. No sound/image/hint processing beyond storage. No idle tracking.