@tokamakdev/plugin-notifications 0.1.0-beta.50

package/apple/NotificationsPlugin.swift

@@ -0,0 +1,381 @@
+import Foundation
+import UserNotifications
+
+#if os(iOS)
+  import UIKit
+#else
+  import AppKit
+#endif
+
+private let subscriptionKey = "tokamak.notifications.subscription"
+private let showInForegroundKey = "tokamak.notifications.show-in-foreground"
+/// The system keeps only the soonest 64 pending requests.
+private let pendingLimit = 64
+/// The system allows about 30 seconds for a background remote notification.
+private let pushTimeout: TimeInterval = 25
+private let shown: UNNotificationPresentationOptions = [.banner, .list, .sound]
+
+#if os(iOS)
+  private let pushEntitlement = "aps-environment"
+#else
+  private let pushEntitlement = "com.apple.developer.aps-environment"
+#endif
+
+final class TokamakNotificationsPlugin: NSObject, TokamakPlugin,
+  UNUserNotificationCenterDelegate
+{
+  let id = "notifications"
+
+  private let host: TokamakHost
+  private let center = UNUserNotificationCenter.current()
+  private let defaults = UserDefaults.standard
+  private var listeners: [String: [UUID: TokamakPluginReply]] = [:]
+  /// Notifications opened while no page listened for them.
+  private var heldOpened: [[String: Any]] = []
+  private var registering: [TokamakPluginReply] = []
+
+  /// Becomes the notification centre's delegate before launch finishes, which
+  /// the system requires to deliver the notification that launched the app.
+  init(host: TokamakHost) {
+    self.host = host
+    super.init()
+    center.delegate = self
+    if defaults.dictionary(forKey: subscriptionKey) != nil {
+      registerForRemoteNotifications()
+    }
+  }
+
+  func call(
+    method: String,
+    arguments: Any,
+    reply: @escaping TokamakPluginReply
+  ) {
+    do throws(TokamakPluginError) {
+      switch method {
+      case "permission":
+        permission(reply)
+      case "requestPermission":
+        center.requestAuthorization(options: [.alert, .sound, .badge]) { _, _ in
+          self.permission(reply)
+        }
+      case "show":
+        add(try TokamakNotificationRequest(arguments, scheduled: false), reply: reply)
+      case "schedule":
+        schedule(try TokamakNotificationRequest(arguments, scheduled: true), reply: reply)
+      case "getScheduled":
+        center.getPendingNotificationRequests { reply(.success($0.map(\.scheduled))) }
+      case "getDelivered":
+        center.getDeliveredNotifications {
+          reply(.success($0.map { TokamakNotificationFields($0).content }))
+        }
+      case "remove":
+        let id = try identifier(arguments)
+        center.removePendingNotificationRequests(withIdentifiers: [id])
+        center.removeDeliveredNotifications(withIdentifiers: [id])
+        reply(.success(nil))
+      case "subscribe":
+        try subscribeToPush(arguments, reply: reply)
+      case "getSubscription":
+        reply(.success(defaults.dictionary(forKey: subscriptionKey)))
+      case "unsubscribe":
+        unsubscribe()
+        reply(.success(nil))
+      default:
+        throw .notSupported("\(id).\(method) is not supported")
+      }
+    } catch {
+      reply(.failure(error))
+    }
+  }
+
+  func subscribe(
+    method: String,
+    arguments: Any,
+    reply: @escaping TokamakPluginReply
+  ) -> (() -> Void) {
+    guard ["onMessage", "onNotificationOpened", "onSubscriptionChange"].contains(method) else {
+      reply(.failure(.notSupported("\(id).\(method) is not supported")))
+      return {}
+    }
+    let key = UUID()
+    listeners[method, default: [:]][key] = reply
+    if method == "onNotificationOpened" {
+      let held = heldOpened
+      heldOpened.removeAll()
+      for opened in held {
+        reply(.success(opened))
+      }
+    }
+    return { [weak self] in
+      self?.listeners[method]?.removeValue(forKey: key)
+    }
+  }
+
+  func didRegisterForRemoteNotifications(deviceToken: Data) {
+    let previous = defaults.dictionary(forKey: subscriptionKey)
+    guard previous != nil || !registering.isEmpty else { return }
+    let subscription: [String: Any] = [
+      "service": "apns",
+      "token": deviceToken.map { String(format: "%02x", $0) }.joined(),
+      "environment": Self.apsEnvironment ?? "development",
+    ]
+    defaults.set(subscription, forKey: subscriptionKey)
+    let replies = registering
+    registering.removeAll()
+    for reply in replies {
+      reply(.success(subscription))
+    }
+    if let previous, previous["token"] as? String != subscription["token"] as? String {
+      emit("onSubscriptionChange", subscription)
+    }
+  }
+
+  func didFailToRegisterForRemoteNotifications(error: Error) {
+    let replies = registering
+    registering.removeAll()
+    for reply in replies {
+      reply(.failure(Self.registrationError(error)))
+    }
+  }
+
+  /// Runs the Worker's `push` handler for a data-only message, showing the
+  /// notification it returns.
+  func didReceiveRemoteNotification(
+    _ userInfo: [AnyHashable: Any],
+    completion: @escaping (TokamakBackgroundResult) -> Void
+  ) {
+    let fields = TokamakNotificationFields(remoteNotification: userInfo)
+    guard fields.title == nil, fields.body == nil else {
+      completion(.noData)
+      return
+    }
+    emit("onMessage", fields.message)
+    host.dispatch(event: "push", payload: fields.message, timeout: pushTimeout) { result in
+      switch result {
+      case .success(.handled(let returned)):
+        self.show(returned) { completion(.newData) }
+      case .success(.unhandled):
+        completion(.noData)
+      case .failure(let error):
+        print("tokamak push handler failed: \(error)")
+        completion(.failed)
+      }
+    }
+  }
+
+  func userNotificationCenter(
+    _ center: UNUserNotificationCenter,
+    willPresent notification: UNNotification,
+    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
+  ) {
+    let fields = TokamakNotificationFields(notification)
+    DispatchQueue.main.async {
+      guard fields.isPush else {
+        completionHandler(shown)
+        return
+      }
+      self.emit("onMessage", fields.message)
+      completionHandler(self.defaults.bool(forKey: showInForegroundKey) ? shown : [])
+    }
+  }
+
+  func userNotificationCenter(
+    _ center: UNUserNotificationCenter,
+    didReceive response: UNNotificationResponse,
+    withCompletionHandler completionHandler: @escaping () -> Void
+  ) {
+    let opened = TokamakNotificationFields(response.notification).opened
+    DispatchQueue.main.async {
+      self.emit("onNotificationOpened", opened)
+      completionHandler()
+    }
+  }
+
+  private func emit(_ method: String, _ value: [String: Any]) {
+    let current = listeners[method] ?? [:]
+    if method == "onNotificationOpened" && current.isEmpty {
+      heldOpened.append(value)
+    }
+    for reply in current.values {
+      reply(.success(value))
+    }
+  }
+
+  private func permission(_ reply: @escaping TokamakPluginReply) {
+    center.getNotificationSettings { settings in
+      reply(.success(Self.permission(settings.authorizationStatus)))
+    }
+  }
+
+  private static func permission(_ status: UNAuthorizationStatus) -> String {
+    switch status {
+    case .denied: return "denied"
+    case .notDetermined: return "prompt"
+    default: return "granted"
+    }
+  }
+
+  private func schedule(_ request: TokamakNotificationRequest, reply: @escaping TokamakPluginReply)
+  {
+    center.getPendingNotificationRequests { pending in
+      let replaces = pending.contains { $0.identifier == request.id }
+      guard replaces || pending.count < pendingLimit else {
+        reply(
+          .failure(
+            TokamakPluginError(
+              name: "QuotaExceededError",
+              message: "The app has \(pendingLimit) scheduled notifications, the most allowed"
+            )))
+        return
+      }
+      self.add(request, reply: reply)
+    }
+  }
+
+  private func add(_ request: TokamakNotificationRequest, reply: @escaping TokamakPluginReply) {
+    let notification: UNNotificationRequest
+    do {
+      notification = try request.request()
+    } catch {
+      reply(.failure(error))
+      return
+    }
+    center.getNotificationSettings { settings in
+      guard Self.permission(settings.authorizationStatus) == "granted" else {
+        reply(
+          .failure(
+            TokamakPluginError(
+              name: "NotAllowedError",
+              message: "Notification permission has not been granted"
+            )))
+        return
+      }
+      self.center.add(notification) { error in
+        reply(error.map { .failure(Self.operationError($0)) } ?? .success(nil))
+      }
+    }
+  }
+
+  /// Shows a notification a Worker handler returned, then calls `completion`.
+  private func show(_ returned: Any, completion: @escaping () -> Void) {
+    guard !(returned is NSNull) else {
+      completion()
+      return
+    }
+    guard let request = try? TokamakNotificationRequest(returned, scheduled: false) else {
+      print("tokamak push handler returned an invalid notification")
+      completion()
+      return
+    }
+    add(request) { _ in completion() }
+  }
+
+  private func subscribeToPush(
+    _ arguments: Any,
+    reply: @escaping TokamakPluginReply
+  ) throws(TokamakPluginError) {
+    #if os(macOS)
+      guard Self.entitlement("com.apple.application-identifier") != nil else {
+        throw .notSupported("Push requires a team-signed build")
+      }
+    #endif
+    #if !targetEnvironment(simulator)
+      guard Self.apsEnvironment != nil else {
+        throw TokamakPluginError(
+          name: "InvalidStateError",
+          message: "Push requires the app to declare the \(pushEntitlement) entitlement"
+        )
+      }
+    #endif
+    let options = arguments as? [String: Any] ?? [:]
+    defaults.set(options["showInForeground"] as? Bool ?? false, forKey: showInForegroundKey)
+    registering.append(reply)
+    registerForRemoteNotifications()
+  }
+
+  /// Stops push delivery, failing a `subscribe` still waiting for its token.
+  private func unsubscribe() {
+    unregisterForRemoteNotifications()
+    defaults.removeObject(forKey: subscriptionKey)
+    defaults.removeObject(forKey: showInForegroundKey)
+    let replies = registering
+    registering.removeAll()
+    for reply in replies {
+      reply(.failure(TokamakPluginError(name: "AbortError", message: "unsubscribe was called")))
+    }
+  }
+
+  private func registerForRemoteNotifications() {
+    #if os(iOS)
+      UIApplication.shared.registerForRemoteNotifications()
+    #else
+      NSApplication.shared.registerForRemoteNotifications()
+    #endif
+  }
+
+  private func unregisterForRemoteNotifications() {
+    #if os(iOS)
+      UIApplication.shared.unregisterForRemoteNotifications()
+    #else
+      NSApplication.shared.unregisterForRemoteNotifications()
+    #endif
+  }
+
+  private func identifier(_ arguments: Any) throws(TokamakPluginError) -> String {
+    guard let id = (arguments as? [String: Any])?["id"] as? String, !id.isEmpty else {
+      throw TokamakPluginError(name: "TypeError", message: "id must be a non-empty string")
+    }
+    return id
+  }
+
+  /// The APNs environment the app is signed for, or nil without the push entitlement.
+  private static let apsEnvironment: String? = {
+    #if targetEnvironment(simulator)
+      return "development"
+    #elseif os(iOS)
+      return profileEntitlement(pushEntitlement)
+    #else
+      return entitlement(pushEntitlement) as? String
+    #endif
+  }()
+
+  #if os(macOS)
+    private static func entitlement(_ key: String) -> Any? {
+      guard let task = SecTaskCreateFromSelf(nil) else { return nil }
+      return SecTaskCopyValueForEntitlement(task, key as CFString, nil)
+    }
+  #endif
+
+  #if os(iOS) && !targetEnvironment(simulator)
+    /// An entitlement in the embedded provisioning profile, which signing takes
+    /// the push environment from.
+    private static func profileEntitlement(_ key: String) -> String? {
+      guard
+        let url = Bundle.main.url(forResource: "embedded", withExtension: "mobileprovision"),
+        let profile = try? Data(contentsOf: url),
+        let start = profile.range(of: Data("<?xml".utf8)),
+        let end = profile.range(of: Data("</plist>".utf8), in: start.lowerBound..<profile.endIndex),
+        let plist = try? PropertyListSerialization.propertyList(
+          from: profile[start.lowerBound..<end.upperBound],
+          format: nil
+        ) as? [String: Any]
+      else {
+        return nil
+      }
+      return (plist["Entitlements"] as? [String: Any])?[key] as? String
+    }
+  #endif
+
+  private static func registrationError(_ error: Error) -> TokamakPluginError {
+    // Cocoa reports a missing aps-environment entitlement as error 3000.
+    let error = error as NSError
+    if error.domain == NSCocoaErrorDomain && error.code == 3000 {
+      return TokamakPluginError(name: "InvalidStateError", message: error.localizedDescription)
+    }
+    return operationError(error)
+  }
+
+  private static func operationError(_ error: Error) -> TokamakPluginError {
+    TokamakPluginError(name: "OperationError", message: error.localizedDescription)
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@tokamakdev/plugin-notifications",
+  "version": "0.1.0-beta.50",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mantty/tokamak.git",
+    "directory": "plugins/notifications"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./service-worker": "./service-worker/index.ts"
+  },
+  "dependencies": {
+    "@tokamakdev/plugin": "0.1.0-beta.50"
+  },
+  "files": [
+    "android",
+    "apple",
+    "service-worker",
+    "src",
+    "web",
+    "tokamak-plugin.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/service-worker/index.ts

@@ -0,0 +1,142 @@
+import type { Message, OpenedNotification } from "../src/index.js";
+import {
+  MESSAGE,
+  OPENED,
+  OPENED_CACHE,
+  SUBSCRIPTION,
+  type ServiceWorkerMessage,
+  notificationData,
+  pluginData,
+  webPushSubscription,
+} from "../web/protocol.js";
+
+/** The parts of the service worker events and global scope the helpers use. */
+interface ExtendableEvent {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+interface PushEvent extends ExtendableEvent {
+  readonly data: { text(): string } | null;
+}
+
+interface NotificationEvent extends ExtendableEvent {
+  readonly notification: Notification;
+}
+
+interface PushSubscriptionChangeEvent extends ExtendableEvent {
+  readonly newSubscription?: PushSubscription | null;
+  readonly oldSubscription?: PushSubscription | null;
+}
+
+interface WindowClient {
+  readonly url: string;
+  focus(): Promise<WindowClient>;
+  postMessage(message: ServiceWorkerMessage): void;
+}
+
+interface ServiceWorkerScope {
+  readonly registration: ServiceWorkerRegistration;
+  readonly clients: {
+    matchAll(options: { type: "window"; includeUncontrolled: boolean }): Promise<WindowClient[]>;
+    openWindow(url: string): Promise<WindowClient | null>;
+  };
+}
+
+const scope = globalThis as unknown as ServiceWorkerScope;
+
+/**
+ * Shows the notification in a push message's `{ id, title, body, data }` JSON payload and
+ * forwards the message to open pages.
+ */
+export function handlePush(event: PushEvent): void {
+  event.waitUntil(showAndForward(message(payload(event.data?.text()))));
+}
+
+/**
+ * Handles a click on a notification the plugin showed: holds it for the page's
+ * `onNotificationOpened`, then focuses an open page or opens `data.url` (default `/`).
+ * Returns false for other notifications.
+ */
+export function handleNotificationClick(event: NotificationEvent): boolean {
+  const data = pluginData(event.notification.data);
+  if (!data) return false;
+  event.notification.close();
+  const opened: OpenedNotification = {
+    id: event.notification.tag,
+    title: event.notification.title,
+    body: event.notification.body || null,
+    data: data.data,
+    source: data.source,
+  };
+  event.waitUntil(open(opened));
+  return true;
+}
+
+/** Forwards the replacement subscription to open pages when the push service changes it. */
+export function handleSubscriptionChange(event: PushSubscriptionChangeEvent): void {
+  event.waitUntil(forwardSubscription(event));
+}
+
+async function showAndForward(pushed: Message): Promise<void> {
+  await scope.registration.showNotification(pushed.title ?? "", {
+    body: pushed.body ?? undefined,
+    tag: pushed.id,
+    data: notificationData("push", pushed.data),
+  });
+  await post({ type: MESSAGE, message: pushed });
+}
+
+async function open(opened: OpenedNotification): Promise<void> {
+  const cache = await caches.open(OPENED_CACHE);
+  await cache.put(`/__tokamak/notifications/opened/${crypto.randomUUID()}`, Response.json(opened));
+  const client = (await windows()).at(0);
+  if (client) {
+    await client.focus();
+  } else {
+    await scope.clients.openWindow(typeof opened.data.url === "string" ? opened.data.url : "/");
+  }
+  await post({ type: OPENED });
+}
+
+async function forwardSubscription(event: PushSubscriptionChangeEvent): Promise<void> {
+  const options = event.oldSubscription?.options;
+  const subscription =
+    event.newSubscription ??
+    (options ? await scope.registration.pushManager.subscribe(options) : null);
+  if (subscription) {
+    await post({ type: SUBSCRIPTION, subscription: webPushSubscription(subscription) });
+  }
+}
+
+async function post(message: ServiceWorkerMessage): Promise<void> {
+  for (const client of await windows()) client.postMessage(message);
+}
+
+function windows(): Promise<WindowClient[]> {
+  return scope.clients.matchAll({ type: "window", includeUncontrolled: true });
+}
+
+/** A push payload's JSON, or its text as the body when it is not JSON. */
+function payload(text: string | undefined): unknown {
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { body: text };
+  }
+}
+
+/** The message in a push payload; every field is optional. */
+function message(payload: unknown): Message {
+  const fields = (payload ?? {}) as Partial<Record<keyof Message, unknown>>;
+  return {
+    id: typeof fields.id === "string" ? fields.id : crypto.randomUUID(),
+    title: typeof fields.title === "string" ? fields.title : null,
+    body: typeof fields.body === "string" ? fields.body : null,
+    data: isRecord(fields.data) ? fields.data : {},
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/index.ts

@@ -0,0 +1,145 @@
+import { FrontendPlugin } from "@tokamakdev/plugin";
+import * as web from "../web/index.js";
+
+/** Whether the app may show notifications. */
+export type Permission = "granted" | "denied" | "prompt";
+
+export interface NotificationContent {
+  /** Showing or scheduling another notification with the same id replaces this one. */
+  readonly id: string;
+  readonly title: string;
+  readonly body?: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface ScheduledNotification extends NotificationContent {
+  /** Milliseconds since the epoch; the earliest time the notification is shown. */
+  readonly at: number;
+}
+
+/** A received push message. A data-only message has no title or body. */
+export interface Message {
+  readonly id: string;
+  readonly title: string | null;
+  readonly body: string | null;
+  readonly data: Record<string, unknown>;
+}
+
+export interface OpenedNotification extends Message {
+  readonly source: "local" | "push";
+}
+
+/** Where the app's server sends push messages for this installation. */
+export type Subscription =
+  | {
+      readonly service: "apns";
+      readonly token: string;
+      readonly environment: "development" | "production";
+    }
+  | { readonly service: "fcm"; readonly token: string }
+  | {
+      readonly service: "webpush";
+      readonly endpoint: string;
+      readonly keys: { readonly p256dh: string; readonly auth: string };
+    };
+
+export interface SubscribeOptions {
+  /** Web Push only: the app's VAPID public key, base64url-encoded. */
+  readonly applicationServerKey?: string;
+  /** Also show push notifications that arrive while the page is visible. Defaults to false. */
+  readonly showInForeground?: boolean;
+}
+
+export type Listener<T> = (value: T) => void;
+export type ErrorListener = (error: DOMException) => void;
+
+class Notifications extends FrontendPlugin {
+  constructor() {
+    super("notifications");
+  }
+
+  permission(): Promise<Permission> {
+    return this.hasNativeTransport ? this.call("permission") : web.permission();
+  }
+
+  /** Asks the user for permission to show notifications. */
+  requestPermission(): Promise<Permission> {
+    return this.hasNativeTransport ? this.call("requestPermission") : web.requestPermission();
+  }
+
+  /** Shows a notification now, even while the page is visible. */
+  show(notification: NotificationContent): Promise<void> {
+    return this.hasNativeTransport ? this.call("show", notification) : web.show(notification);
+  }
+
+  /** Shows a notification at `at`, or now when `at` has passed. Not supported on the web. */
+  schedule(notification: ScheduledNotification): Promise<void> {
+    return this.hasNativeTransport ? this.call("schedule", notification) : web.schedule();
+  }
+
+  /** Scheduled notifications not yet shown. */
+  getScheduled(): Promise<ScheduledNotification[]> {
+    return this.hasNativeTransport ? this.call("getScheduled") : Promise.resolve([]);
+  }
+
+  /** Shown notifications still in the notification centre. */
+  getDelivered(): Promise<NotificationContent[]> {
+    return this.hasNativeTransport ? this.call("getDelivered") : web.getDelivered();
+  }
+
+  /** Removes a scheduled or shown notification. */
+  remove(id: string): Promise<void> {
+    return this.hasNativeTransport ? this.call("remove", { id }) : web.remove(id);
+  }
+
+  /** Subscribes to push messages, returning the existing subscription when there is one. */
+  subscribe(options: SubscribeOptions = {}): Promise<Subscription> {
+    if (!this.hasNativeTransport) return web.subscribe(options);
+    return this.call("subscribe", { showInForeground: options.showInForeground ?? false });
+  }
+
+  /** The current push subscription, or null. */
+  getSubscription(): Promise<Subscription | null> {
+    return this.hasNativeTransport ? this.call("getSubscription") : web.getSubscription();
+  }
+
+  unsubscribe(): Promise<void> {
+    return this.hasNativeTransport ? this.call("unsubscribe") : web.unsubscribe();
+  }
+
+  /** Receives push messages that arrive while the page is loaded. */
+  onMessage(listener: Listener<Message>, error: ErrorListener = report): () => void {
+    if (!this.hasNativeTransport) return web.onMessage(listener);
+    return this.listen("onMessage", (value) => {
+      listener(value as Message);
+    }, error);
+  }
+
+  /** Receives opened notifications, local or push, including the one that opened the app. */
+  onNotificationOpened(
+    listener: Listener<OpenedNotification>,
+    error: ErrorListener = report,
+  ): () => void {
+    if (!this.hasNativeTransport) return web.onNotificationOpened(listener);
+    return this.listen("onNotificationOpened", (value) => {
+      listener(value as OpenedNotification);
+    }, error);
+  }
+
+  /** Receives the replacement when the push service changes the subscription. */
+  onSubscriptionChange(
+    listener: Listener<Subscription>,
+    error: ErrorListener = report,
+  ): () => void {
+    if (!this.hasNativeTransport) return web.onSubscriptionChange(listener);
+    return this.listen("onSubscriptionChange", (value) => {
+      listener(value as Subscription);
+    }, error);
+  }
+}
+
+function report(error: DOMException): void {
+  console.error(error);
+}
+
+export const notifications = new Notifications();