aivi.gnome.notifications

Types for GNOME desktop notifications.

These are operating-system notifications: the kind that appear in the desktop shell. They are separate from AppNotification in the optional application-types package, which describes messages shown inside your own app window.

This module defines the payloads, handle annotation, task alias, and response types used by the built-in desktop notification capability:

use aivi.gnome.notifications (NotificationSource)

@source notifications "io.mailfox"
signal notifications : NotificationSource

Import

use aivi.gnome.notifications (
    NotificationAction
    Notification
    NotificationSource
    NotificationTask
    NotificationError
    NotificationResponse
    NotificationEvent
)

Overview

Type	Description
NotificationAction	One clickable action button in a notification
Notification	Full desktop notification payload
NotificationSource	Nominal handle annotation for @source notifications ...
NotificationTask A	Generic desktop-notification task alias
NotificationError	Failure case when notification delivery fails
NotificationResponse	What the user did with the notification
NotificationEvent	Response paired with notification id

Types

NotificationAction

type NotificationAction = {
    label: Text,
    id: Text
}

One action button attached to a notification.

• label — text shown to the user
• id — stable identifier you can match on later if the action is triggered

use aivi.gnome.notifications (NotificationAction)

value archiveAction : NotificationAction = {
    label: "Archive",
    id: "archive"
}

Notification

use aivi.gnome.notifications (NotificationAction)

type Notification = {
    summary: Text,
    body: Option Text,
    icon: Option Text,
    actions: List NotificationAction
}

Full notification payload.

• summary — short headline
• body — optional longer message
• icon — optional icon name or other backend-specific text identifier
• actions — zero or more clickable actions

NotificationSource

type NotificationSource = Unit

Nominal handle annotation used with @source notifications "app.name".

NotificationTask

use aivi.gnome.notifications (NotificationError)

type NotificationTask A = (Task NotificationError A)

Alias used by notifications.send and notifications.close.

use aivi.gnome.notifications (
    Notification
    NotificationAction
)

value archiveAction : NotificationAction = {
    label: "Archive",
    id: "archive"
}

value newMail : Notification = {
    summary: "New mail",
    body: Some "You have 3 new messages",
    icon: Some "mail-unread",
    actions: [archiveAction]
}

NotificationError

type NotificationError =
  NotificationFailed Text

Notification delivery failed, with a backend-provided message.

NotificationResponse

type NotificationResponse =
  | ActionTriggered Text
  | Dismissed

Result from the desktop after a notification is shown.

• ActionTriggered id — the user clicked an action with the given id
• Dismissed — the notification was closed without an action

use aivi.gnome.notifications (
    NotificationResponse
    ActionTriggered
    Dismissed
)

type NotificationResponse -> Text
func responseLabel =
 ||> ActionTriggered actionId -> "Clicked: {actionId}"
 ||> Dismissed                -> "Dismissed"

NotificationEvent

use aivi.gnome.notifications (NotificationResponse)

type NotificationEvent = {
    id: Int,
    response: NotificationResponse
}

Published by notifications.events so apps can correlate responses with previously shown desktop notifications.

Capability surface

use aivi.gnome.notifications (
    Notification
    NotificationError
    NotificationEvent
    NotificationSource
)

@source notifications "io.mailfox" with {
    bus: "session"
}
signal notifications : NotificationSource

signal events : Signal NotificationEvent = notifications.events

value mailNotification : Notification = {
    summary: "New mail",
    body: Some "You have 3 new messages",
    icon: Some "mail-unread",
    actions: []
}

value showMail : Task NotificationError Int = notifications.send mailNotification
value closeMail : Task NotificationError Unit = notifications.close 42

Additional constructors and task alias

NotificationTask A is Task NotificationError A. NotificationFailed message reports provider failure, and ActionTriggered id reports the identifier of the action selected by the user.