@tokamakdev/plugin-notifications 0.1.0-beta.50

package/README.md

@@ -0,0 +1,206 @@
+# @tokamakdev/plugin-notifications
+
+Local and push notifications for tokamak applications and the web.
+
+```sh
+npm install @tokamakdev/plugin-notifications
+```
+
+```ts
+import { notifications } from "@tokamakdev/plugin-notifications";
+
+await notifications.requestPermission(); // "granted" | "denied" | "prompt"
+
+await notifications.show({ id: "download-42", title: "Download finished", body: "report.pdf" });
+await notifications.schedule({ id: "reminder-7", title: "Check in", at: Date.parse("2026-10-01T09:00:00Z") });
+
+const subscription = await notifications.subscribe({ applicationServerKey: VAPID_PUBLIC_KEY });
+await fetch("/api/subscriptions", { method: "POST", body: JSON.stringify(subscription) });
+
+notifications.onMessage((message) => console.log(message.data));
+notifications.onNotificationOpened((opened) => console.log(opened.id, opened.source));
+notifications.onSubscriptionChange((subscription) => {
+  void fetch("/api/subscriptions", { method: "POST", body: JSON.stringify(subscription) });
+});
+```
+
+## Permission
+
+`permission()` reports whether the app may show notifications and
+`requestPermission()` asks the user. No other method asks. On Android before
+13, notifications are allowed unless the user turns them off.
+
+## Local notifications
+
+- `show(notification)` shows a notification now, even while the page is
+  visible.
+- `schedule(notification)` shows it at `at`, in milliseconds since the epoch,
+  or now when `at` has passed. Scheduled notifications survive app and device
+  restarts. Android may delay them by several minutes while the device is idle.
+  iOS and macOS keep at most 64; scheduling more rejects with
+  `QuotaExceededError`. The web does not support scheduling.
+- `getScheduled()` lists scheduled notifications not yet shown, and
+  `getDelivered()` lists shown notifications still in the notification centre.
+- `remove(id)` removes a scheduled or shown notification. On Android, the id
+  of a push notification FCM showed is its `tag`.
+
+Showing or scheduling a notification with the `id` of another replaces it.
+
+## Push notifications
+
+`subscribe()` subscribes to push messages and returns where the app's server
+sends them. It returns the existing subscription when there is one.
+
+| Platform | Subscription | Push service |
+|---|---|---|
+| iOS, macOS | `{ service: "apns", token, environment }` | APNs, in `environment` (`development` or `production`) |
+| Android | `{ service: "fcm", token }` | Firebase Cloud Messaging HTTP v1 |
+| Web | `{ service: "webpush", endpoint, keys }` | Web Push, with the app's VAPID key pair |
+
+Push notifications that arrive while the page is visible reach `onMessage`.
+They are also shown when `subscribe` was given `showInForeground: true`, on
+iOS, macOS and Android. The web shows every push notification.
+`onSubscriptionChange` reports a replacement subscription, for example when FCM
+rotates a token.
+
+### Declarations
+
+Local notifications need no declarations. Push needs these:
+
+| Platform | Declaration |
+|---|---|
+| iOS | `aps-environment` in the app's entitlements file, set with `ios.entitlements`. The value may be `development`: signing uses the provisioning profile's value. Push requires a paid Apple Developer Program team. |
+| macOS | `com.apple.developer.aps-environment` in the `macos.entitlements` file, and a team-signed build (`macos.team-id`). |
+| Android | The app's Firebase project values as `<meta-data>` in its `android.manifest` file, from the Firebase console's project settings. |
+| Web | A service worker that uses the helper below, and the app's VAPID public key as `applicationServerKey`. |
+
+```xml
+<!-- iOS entitlements file -->
+<plist version="1.0">
+<dict>
+  <key>aps-environment</key>
+  <string>development</string>
+</dict>
+</plist>
+```
+
+```xml
+<!-- Android manifest file -->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <application>
+    <meta-data android:name="com.tokamak.notifications.fcm.application-id" android:value="1:1234567890:android:0123456789abcdef" />
+    <meta-data android:name="com.tokamak.notifications.fcm.project-id" android:value="my-project" />
+    <meta-data android:name="com.tokamak.notifications.fcm.api-key" android:value="AIza..." />
+  </application>
+</manifest>
+```
+
+Without its declaration, `subscribe` rejects with `InvalidStateError`, and in
+a macOS build without a team with `NotSupportedError`. The Firebase values
+identify the project and are not secret.
+
+The iOS build declares the `remote-notification` background mode. An
+`ios.plist` file that sets `UIBackgroundModes` replaces the plugin's value, so
+it must include `remote-notification`.
+
+### Messages
+
+The server sends each service's payload, and the plugin reports it as a
+`Message`:
+
+| Service | `id` | `title`, `body` | `data` |
+|---|---|---|---|
+| APNs | The notification's identifier | `aps.alert.title`, `aps.alert.body` | Every top-level key except `aps` |
+| FCM | The message ID | `notification.title`, `notification.body` | The `data` map |
+| Web Push | `id` in the JSON payload | `title`, `body` in the payload | `data` in the payload |
+
+A Web Push payload is JSON: `{ "id": "...", "title": "...", "body": "...", "data": {} }`.
+Every field is optional.
+
+### Data-only messages
+
+A message without a title or body runs the Worker's `push` handler in native
+builds, whether the app is in the foreground, in the background, or started by
+the message:
+
+```js
+export default {
+  async fetch(request, env, ctx) {
+    // ...
+  },
+
+  async push(message, env, ctx) {
+    const item = await fetch(`https://api.example.com/items/${message.data.id}`);
+    // Return a notification to show it, or return nothing.
+    return { id: `item-${message.data.id}`, title: "New item", body: (await item.json()).summary };
+  },
+};
+```
+
+`message` is the `Message`; `env` and `ctx` are the Worker's usual arguments.
+A returned notification is shown as `show` shows one. The page also receives
+the message through `onMessage` while it is loaded. Cloudflare never calls
+`push`, and `tok dev` does not run it.
+
+The platforms limit background delivery:
+
+| Platform | The server sends | Limits |
+|---|---|---|
+| iOS | `content-available: 1` with `apns-push-type: background` and `apns-priority: 5` | The system throttles delivery and may drop messages, and delivers nothing after the user force-quits the app until they open it. The plugin stops the handler after 25 seconds, within the system's 30. |
+| macOS | As iOS | Delivered while the app is running. |
+| Android | A `data` message with `priority: high` | Nothing is delivered after the app is force-stopped. The plugin stops the handler after 8 seconds, within FCM's 10, which include starting the app. |
+
+The web does not support data-only messages: browsers require every push
+message to show a notification.
+
+## Opened notifications
+
+`onNotificationOpened` receives each notification the user opens, local or
+push. The plugin holds notifications opened before a page listens, including
+the one that launched the app, and delivers them to the first listener.
+Android does not pass the title or body of an FCM notification the system
+showed, so those are null.
+
+## Web
+
+The web implementation needs a service worker for everything but `show`. Add
+the helpers to the app's own service worker:
+
+```js
+import {
+  handleNotificationClick,
+  handlePush,
+  handleSubscriptionChange,
+} from "@tokamakdev/plugin-notifications/service-worker";
+
+self.addEventListener("push", (event) => handlePush(event));
+self.addEventListener("notificationclick", (event) => handleNotificationClick(event));
+self.addEventListener("pushsubscriptionchange", (event) => handleSubscriptionChange(event));
+```
+
+- `handlePush` shows the payload's notification and forwards the message to
+  open pages.
+- `handleNotificationClick` focuses an open page, or opens `data.url` (default
+  `/`), and holds the notification for `onNotificationOpened`. It returns false
+  for notifications the plugin did not show.
+- `handleSubscriptionChange` forwards a replacement subscription to open pages.
+
+Safari supports Web Push on macOS 13 and later, and on iOS and iPadOS 16.4 and
+later only for web apps added to the Home Screen.
+
+## Android icon
+
+Android shows notifications with a monochrome icon. Add one as
+`drawable/tokamak_notification` in the app's Android resource directory, set
+with `android.icon`. Without it, the plugin uses the launcher icon, which
+Android draws as a solid shape.
+
+## Errors
+
+- `NotAllowedError`: permission has not been granted.
+- `NotSupportedError`: the platform or build cannot perform the call.
+- `InvalidStateError`: the app has not made a declaration push requires.
+- `QuotaExceededError`: the platform's limit on scheduled notifications is
+  reached.
+- `OperationError`: a platform or push service failure.
+- `TypeError`: an invalid argument.

package/android/AndroidManifest.xml

@@ -0,0 +1,30 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <application>
+    <provider
+        android:name="com.tokamak.plugins.notifications.TokamakFirebaseInitializer"
+        android:authorities="${applicationId}.tokamak-firebase"
+        android:exported="false" />
+    <service
+        android:name="com.tokamak.plugins.notifications.TokamakPushService"
+        android:exported="false">
+      <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+      </intent-filter>
+    </service>
+    <receiver
+        android:name="com.tokamak.plugins.notifications.TokamakAlarmReceiver"
+        android:exported="false" />
+    <receiver
+        android:name="com.tokamak.plugins.notifications.TokamakBootReceiver"
+        android:exported="false">
+      <intent-filter>
+        <action android:name="android.intent.action.BOOT_COMPLETED" />
+        <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
+      </intent-filter>
+    </receiver>
+    <meta-data android:name="firebase_messaging_auto_init_enabled" android:value="false" />
+    <meta-data
+        android:name="com.google.firebase.messaging.default_notification_channel_id"
+        android:value="tokamak.notifications" />
+  </application>
+</manifest>

package/android/Content.kt

@@ -0,0 +1,47 @@
+package com.tokamak.plugins.notifications
+
+import com.tokamak.runtime.TokamakPluginError
+import org.json.JSONObject
+
+/** A notification the page asked to show or schedule. */
+internal class Content(
+    val id: String,
+    val title: String,
+    val body: String?,
+    val data: JSONObject,
+    /** Milliseconds since the epoch; null to show now. */
+    val at: Long?,
+) {
+    fun toJson(): JSONObject =
+        JSONObject()
+            .put("id", id)
+            .put("title", title)
+            .put("data", data)
+            .apply {
+                body?.let { put("body", it) }
+                at?.let { put("at", it) }
+            }
+
+    companion object {
+        fun parse(arguments: Any?, scheduled: Boolean): Content {
+            val json = arguments as? JSONObject ?: JSONObject()
+            val id = json.opt("id") as? String
+            if (id.isNullOrEmpty()) throw typeError("id must be a non-empty string")
+            val title = json.opt("title") as? String ?: throw typeError("title must be a string")
+            val at = if (scheduled) scheduledTime(json) else null
+            return Content(id, title, json.opt("body") as? String, json.optJSONObject("data") ?: JSONObject(), at)
+        }
+
+        fun fromJson(json: JSONObject): Content = parse(json, json.has("at"))
+
+        private fun scheduledTime(json: JSONObject): Long {
+            val at = (json.opt("at") as? Number)?.toDouble()
+            if (at == null || !at.isFinite()) {
+                throw typeError("at must be a number of milliseconds since the epoch")
+            }
+            return at.toLong()
+        }
+
+        private fun typeError(message: String) = TokamakPluginError("TypeError", message)
+    }
+}

package/android/NotificationsPlugin.kt

@@ -0,0 +1,287 @@
+package com.tokamak.plugins.notifications
+
+import android.Manifest
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
+import android.util.Log
+import com.google.firebase.FirebaseApp
+import com.google.firebase.messaging.FirebaseMessaging
+import com.tokamak.runtime.TokamakHost
+import com.tokamak.runtime.TokamakPlugin
+import com.tokamak.runtime.TokamakPluginError
+import com.tokamak.runtime.TokamakPluginReply
+import org.json.JSONArray
+import org.json.JSONObject
+import org.json.JSONTokener
+
+private const val PREFERENCES = "tokamak.notifications"
+private const val ASKED = "asked"
+private const val SUBSCRIBED = "subscribed"
+private const val TOKEN = "token"
+private const val SHOW_IN_FOREGROUND = "show-in-foreground"
+private const val PERMISSION_REQUEST = 0x4E07
+
+/** FCM allows about 10 seconds for a message, including starting the app. */
+private const val PUSH_TIMEOUT_MILLIS = 8_000L
+private const val FCM_MESSAGE_ID_EXTRA = "google.message_id"
+private val LISTENERS = setOf("onMessage", "onNotificationOpened", "onSubscriptionChange")
+
+class TokamakNotificationsPlugin(
+    private val host: TokamakHost,
+) : TokamakPlugin {
+    override val id = "notifications"
+
+    private val context = host.context
+    private val preferences = context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
+    private val notifier = Notifier(context)
+    private val schedule = Schedule(context)
+    private val listeners = mutableMapOf<String, MutableMap<Int, TokamakPluginReply>>()
+    private var nextListener = 0
+
+    /** Notifications opened while no page listened for them. */
+    private val heldOpened = mutableListOf<JSONObject>()
+    private val permissionReplies = mutableListOf<TokamakPluginReply>()
+
+    init {
+        notifier.createChannel()
+    }
+
+    override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
+        runCatching {
+            when (method) {
+                "permission" -> reply(Result.success(permission()))
+                "requestPermission" -> requestPermission(reply)
+                "show" -> show(Content.parse(arguments, scheduled = false), reply)
+                "schedule" -> schedule(Content.parse(arguments, scheduled = true), reply)
+                "getScheduled" -> reply(Result.success(JSONArray(schedule.all().map(Content::toJson))))
+                "getDelivered" -> reply(Result.success(JSONArray(notifier.delivered())))
+                "remove" -> remove(identifier(arguments), reply)
+                "subscribe" -> subscribe(arguments, reply)
+                "getSubscription" -> reply(Result.success(subscription()))
+                "unsubscribe" -> unsubscribe(reply)
+                else -> super.call(method, arguments, reply)
+            }
+        }.onFailure { reply(Result.failure(pluginError(it))) }
+    }
+
+    override fun subscribe(
+        method: String,
+        arguments: Any?,
+        reply: TokamakPluginReply,
+    ): () -> Unit {
+        if (method !in LISTENERS) return super.subscribe(method, arguments, reply)
+        val key = nextListener++
+        listeners.getOrPut(method, ::mutableMapOf)[key] = reply
+        if (method == "onNotificationOpened") {
+            heldOpened.forEach { reply(Result.success(it)) }
+            heldOpened.clear()
+        }
+        return { listeners[method]?.remove(key) }
+    }
+
+    override fun onRequestPermissionsResult(
+        requestCode: Int,
+        permissions: Array<out String>,
+        grantResults: IntArray,
+    ) {
+        if (requestCode != PERMISSION_REQUEST) return
+        val permission = permission()
+        permissionReplies.forEach { it(Result.success(permission)) }
+        permissionReplies.clear()
+    }
+
+    /** Delivers a notification the user opened, local or from FCM, that started the activity. */
+    override fun onIntent(intent: Intent) {
+        val opened =
+            intent.getStringExtra(OPENED_EXTRA)?.let(::JSONObject)
+                ?: intent.getStringExtra(FCM_MESSAGE_ID_EXTRA)?.let { openedPush(intent, it) }
+                ?: return
+        intent.removeExtra(OPENED_EXTRA)
+        intent.removeExtra(FCM_MESSAGE_ID_EXTRA)
+        emit("onNotificationOpened", opened)
+    }
+
+    /** Reports a replaced token; `subscribe` reports the first. */
+    internal fun onNewToken(token: String) {
+        val previous = preferences.getString(TOKEN, null) ?: return
+        if (!preferences.getBoolean(SUBSCRIBED, false) || token == previous) return
+        preferences.edit().putString(TOKEN, token).apply()
+        context.mainExecutor.execute { emit("onSubscriptionChange", fcmSubscription(token)) }
+    }
+
+    /**
+     * Delivers an FCM message to the page. Runs the Worker's `push` handler for a data-only
+     * message and shows the notification it returns. FCM calls this off the main thread.
+     */
+    internal fun onMessageReceived(message: JSONObject, visible: Boolean) {
+        context.mainExecutor.execute { emit("onMessage", message) }
+        if (visible) {
+            if (preferences.getBoolean(SHOW_IN_FOREGROUND, false)) notifier.post(content(message), "push")
+            return
+        }
+        runCatching { host.dispatch("push", message.toString(), PUSH_TIMEOUT_MILLIS) }
+            .onSuccess { result -> result?.let(::showReturned) }
+            .onFailure { Log.w("tokamak", "the Worker's push handler failed", it) }
+    }
+
+    private fun showReturned(result: String) {
+        val returned = JSONTokener(result).nextValue() as? JSONObject ?: return
+        runCatching { notifier.post(Content.parse(returned, scheduled = false), "local") }
+            .onFailure { Log.w("tokamak", "the Worker's push handler returned an invalid notification", it) }
+    }
+
+    private fun emit(method: String, value: JSONObject) {
+        val current = listeners[method].orEmpty().values.toList()
+        if (method == "onNotificationOpened" && current.isEmpty()) heldOpened += value
+        current.forEach { it(Result.success(value)) }
+    }
+
+    private fun permission(): String =
+        when {
+            notifier.enabled -> "granted"
+            canPrompt() -> "prompt"
+            else -> "denied"
+        }
+
+    /** Whether asking shows the system prompt, which Android 13 and later show until the user refuses twice. */
+    private fun canPrompt(): Boolean {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) return false
+        val permission = Manifest.permission.POST_NOTIFICATIONS
+        if (context.checkSelfPermission(permission) == PackageManager.PERMISSION_GRANTED) return false
+        return !preferences.getBoolean(ASKED, false) ||
+            host.activity?.shouldShowRequestPermissionRationale(permission) == true
+    }
+
+    private fun requestPermission(reply: TokamakPluginReply) {
+        val activity = host.activity
+        if (
+            Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU ||
+            activity == null ||
+            permission() != "prompt"
+        ) {
+            reply(Result.success(permission()))
+            return
+        }
+        preferences.edit().putBoolean(ASKED, true).apply()
+        permissionReplies += reply
+        if (permissionReplies.size == 1) {
+            activity.requestPermissions(arrayOf(Manifest.permission.POST_NOTIFICATIONS), PERMISSION_REQUEST)
+        }
+    }
+
+    private fun show(content: Content, reply: TokamakPluginReply) {
+        requireEnabled()
+        notifier.post(content, "local")
+        reply(Result.success(null))
+    }
+
+    private fun schedule(content: Content, reply: TokamakPluginReply) {
+        requireEnabled()
+        if ((content.at ?: 0) <= System.currentTimeMillis()) {
+            notifier.post(content, "local")
+        } else {
+            schedule.add(content)
+        }
+        reply(Result.success(null))
+    }
+
+    private fun remove(id: String, reply: TokamakPluginReply) {
+        schedule.remove(id)
+        notifier.remove(id)
+        reply(Result.success(null))
+    }
+
+    private fun subscribe(arguments: Any?, reply: TokamakPluginReply) {
+        val messaging = messaging() ?: throw invalidState(
+            "Push requires the app's Firebase project values in its Android manifest",
+        )
+        val showInForeground = (arguments as? JSONObject)?.optBoolean("showInForeground") ?: false
+        preferences.edit()
+            .putBoolean(SUBSCRIBED, true)
+            .putBoolean(SHOW_IN_FOREGROUND, showInForeground)
+            .apply()
+        messaging.isAutoInitEnabled = true
+        messaging.token.addOnCompleteListener { task ->
+            when {
+                !preferences.getBoolean(SUBSCRIBED, false) ->
+                    reply(Result.failure(TokamakPluginError("AbortError", "unsubscribe was called")))
+                task.isSuccessful -> {
+                    preferences.edit().putString(TOKEN, task.result).apply()
+                    reply(Result.success(fcmSubscription(task.result)))
+                }
+                else -> reply(Result.failure(operationError(task.exception)))
+            }
+        }
+    }
+
+    private fun subscription(): JSONObject? {
+        if (!preferences.getBoolean(SUBSCRIBED, false)) return null
+        return preferences.getString(TOKEN, null)?.let(::fcmSubscription)
+    }
+
+    private fun unsubscribe(reply: TokamakPluginReply) {
+        preferences.edit().remove(SUBSCRIBED).remove(TOKEN).remove(SHOW_IN_FOREGROUND).apply()
+        val messaging = messaging() ?: return reply(Result.success(null))
+        messaging.isAutoInitEnabled = false
+        messaging.deleteToken().addOnCompleteListener { task ->
+            reply(if (task.isSuccessful) Result.success(null) else Result.failure(operationError(task.exception)))
+        }
+    }
+
+    private fun messaging(): FirebaseMessaging? =
+        if (FirebaseApp.getApps(context).isEmpty()) null else FirebaseMessaging.getInstance()
+
+    /** A received push message's notification, shown as FCM would show it. */
+    private fun content(message: JSONObject): Content =
+        Content(
+            message.getString("id"),
+            message.opt("title") as? String ?: "",
+            message.opt("body") as? String,
+            message.getJSONObject("data"),
+            null,
+        )
+
+    private fun fcmSubscription(token: String): JSONObject =
+        JSONObject().put("service", "fcm").put("token", token)
+
+    /** An opened FCM notification: FCM passes its data map, but not its title or body. */
+    private fun openedPush(intent: Intent, messageId: String): JSONObject {
+        val data = JSONObject()
+        intent.extras?.keySet().orEmpty()
+            .filterNot { it.startsWith("google.") || it.startsWith("gcm.") || it in FCM_KEYS }
+            .forEach { key -> intent.getStringExtra(key)?.let { data.put(key, it) } }
+        return JSONObject()
+            .put("id", messageId)
+            .put("title", JSONObject.NULL)
+            .put("body", JSONObject.NULL)
+            .put("data", data)
+            .put("source", "push")
+    }
+
+    private fun requireEnabled() {
+        if (!notifier.enabled) {
+            throw TokamakPluginError("NotAllowedError", "Notification permission has not been granted")
+        }
+    }
+
+    private fun identifier(arguments: Any?): String {
+        val id = (arguments as? JSONObject)?.opt("id") as? String
+        if (id.isNullOrEmpty()) throw TokamakPluginError("TypeError", "id must be a non-empty string")
+        return id
+    }
+
+    private companion object {
+        /** Extras FCM adds to the launch intent of an opened notification. */
+        val FCM_KEYS = setOf("from", "collapse_key")
+
+        fun invalidState(message: String) = TokamakPluginError("InvalidStateError", message)
+
+        fun operationError(error: Throwable?) =
+            TokamakPluginError("OperationError", error?.message ?: "The push service failed")
+
+        fun pluginError(error: Throwable): TokamakPluginError =
+            error as? TokamakPluginError ?: operationError(error)
+    }
+}

package/android/Notifier.kt

@@ -0,0 +1,91 @@
+package com.tokamak.plugins.notifications
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.os.Bundle
+import org.json.JSONObject
+
+internal const val CHANNEL = "tokamak.notifications"
+internal const val OPENED_EXTRA = "com.tokamak.notifications.opened"
+private const val DATA_EXTRA = "com.tokamak.notifications.data"
+
+/** The plugin and FCM post every notification with this ID, telling them apart by tag. */
+private const val NOTIFICATION_ID = 0
+
+/** Posts, lists and removes the app's notifications on the default channel. */
+internal class Notifier(private val context: Context) {
+    private val manager = context.getSystemService(NotificationManager::class.java)
+
+    val enabled: Boolean
+        get() = manager.areNotificationsEnabled()
+
+    fun createChannel() {
+        manager.createNotificationChannel(
+            NotificationChannel(CHANNEL, "Notifications", NotificationManager.IMPORTANCE_DEFAULT),
+        )
+    }
+
+    /** Shows [content], replacing a notification with the same ID; opening it launches the app. */
+    fun post(content: Content, source: String) {
+        createChannel()
+        val opened = opened(content, source)
+        val notification =
+            Notification.Builder(context, CHANNEL)
+                .setSmallIcon(icon())
+                .setContentTitle(content.title)
+                .setContentText(content.body)
+                .setAutoCancel(true)
+                .setContentIntent(launch(content.id, opened))
+                .addExtras(Bundle().apply { putString(DATA_EXTRA, content.data.toString()) })
+                .build()
+        manager.notify(content.id, NOTIFICATION_ID, notification)
+    }
+
+    /** The app's shown notifications, identified by tag, as the page sees them. */
+    fun delivered(): List<JSONObject> =
+        manager.activeNotifications.mapNotNull { shown ->
+            val id = shown.tag?.takeIf { shown.id == NOTIFICATION_ID } ?: return@mapNotNull null
+            val extras = shown.notification.extras
+            JSONObject()
+                .put("id", id)
+                .put("title", extras.getCharSequence(Notification.EXTRA_TITLE)?.toString() ?: "")
+                .put("data", JSONObject(extras.getString(DATA_EXTRA) ?: "{}"))
+                .apply {
+                    extras.getCharSequence(Notification.EXTRA_TEXT)?.let { put("body", it.toString()) }
+                }
+        }
+
+    fun remove(id: String) = manager.cancel(id, NOTIFICATION_ID)
+
+    /** The app's monochrome `drawable/tokamak_notification`, or its launcher icon. */
+    private fun icon(): Int =
+        context.resources
+            .getIdentifier("tokamak_notification", "drawable", context.packageName)
+            .takeIf { it != 0 }
+            ?: context.applicationInfo.icon.takeIf { it != 0 }
+            ?: android.R.drawable.sym_def_app_icon
+
+    private fun launch(id: String, opened: JSONObject): PendingIntent {
+        val intent =
+            requireNotNull(context.packageManager.getLaunchIntentForPackage(context.packageName))
+                .setIdentifier(id)
+                .putExtra(OPENED_EXTRA, opened.toString())
+        return PendingIntent.getActivity(
+            context,
+            0,
+            intent,
+            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+        )
+    }
+
+    private fun opened(content: Content, source: String): JSONObject =
+        JSONObject()
+            .put("id", content.id)
+            .put("title", content.title)
+            .put("body", content.body ?: JSONObject.NULL)
+            .put("data", content.data)
+            .put("source", source)
+}