@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/push-notifications/references/notification-patterns.md

@@ -1,218 +1,173 @@
 # Notification Patterns
 
-Detailed implementation patterns for push notifications in iOS apps. Covers the complete lifecycle from AppDelegate wiring through debugging delivery issues.
+Working code for the app side of notifications: wiring at launch, the center
+delegate, routing a tap to a screen, silent pushes, a small scheduler, the
+token lifecycle, category setup, testing, badges and moving a provisional user
+to full permission.
 
 ## Contents
 
-- [Complete AppDelegate Adaptor Setup](#complete-appdelegate-adaptor-setup)
-- [Full UNUserNotificationCenterDelegate](#full-unusernotificationcenterdelegate)
-- [Deep Link Router](#deep-link-router)
-- [Silent Push Handler](#silent-push-handler)
-- [Notification Scheduling Manager](#notification-scheduling-manager)
-- [Token Refresh and Update Flow](#token-refresh-and-update-flow)
-- [Category Registration](#category-registration)
-- [Testing Notifications](#testing-notifications)
-- [Badge Management](#badge-management)
-- [Provisional to Full Authorization Upgrade](#provisional-to-full-authorization-upgrade)
+- [App and AppDelegate Wiring](#app-and-appdelegate-wiring)
+- [The Center Delegate](#the-center-delegate)
+- [Routing a Tap to a Screen](#routing-a-tap-to-a-screen)
+- [Handling a Silent Push](#handling-a-silent-push)
+- [A Local Scheduler](#a-local-scheduler)
+- [Token Lifecycle](#token-lifecycle)
+- [Registering Categories](#registering-categories)
+- [Testing and Debugging Delivery](#testing-and-debugging-delivery)
+- [Badges](#badges)
+- [From Provisional to Full Permission](#from-provisional-to-full-permission)
 
-## Complete AppDelegate Adaptor Setup
+## App and AppDelegate Wiring
 
-The full AppDelegate wiring for a SwiftUI app that handles both remote and local notifications.
+SwiftUI calls the app's `init` ahead of the delegate's launch callback
+(`application(_:didFinishLaunchingWithOptions:)`), so the center delegate is
+installed there, as early as it can be.
 
 ```swift
-import SwiftUI
-import UserNotifications
-
 @main
-struct MyApp: App {
-    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
-    @State private var router = DeepLinkRouter.shared
+struct GardenApp: App {
+    @UIApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate
+    @State private var router = NotificationRouter()
 
     init() {
-        // Set delegate as early as possible so no notifications are missed.
-        // App.init runs before application(_:didFinishLaunchingWithOptions:).
-        UNUserNotificationCenter.current().delegate = NotificationDelegate.shared
+        UNUserNotificationCenter.current().delegate = GardenNotificationDelegate.shared
     }
 
     var body: some Scene {
         WindowGroup {
-            ContentView()
+            RootView()
                 .environment(router)
-                .task { await setupNotifications() }
+                .task { await startNotifications() }
         }
     }
 
-    private func setupNotifications() async {
-        registerNotificationCategories()
-
+    @MainActor
+    private func startNotifications() async {
+        GardenNotificationDelegate.shared.router = router
+        NotificationCategories.registerAll()
         let center = UNUserNotificationCenter.current()
-        let settings = await center.notificationSettings()
-
-        if settings.authorizationStatus == .notDetermined {
-            _ = try? await center.requestAuthorization(
-                options: [.alert, .sound, .badge]
-            )
-        }
-
-        // APNs registration is independent from alert authorization. If the
-        // user denies alerts, remote notifications can still arrive silently.
-        await MainActor.run {
-            UIApplication.shared.registerForRemoteNotifications()
+        if await center.notificationSettings().authorizationStatus == .notDetermined {
+            _ = try? await center.requestAuthorization(options: [.badge, .alert, .sound])
         }
+        // Register whatever the answer was: a user who declined alerts
+        // still receives remote notifications, only silently.
+        UIApplication.shared.registerForRemoteNotifications()
     }
 }
 ```
 
-### AppDelegate Class
+### The AppDelegate
 
 ```swift
-class AppDelegate: NSObject, UIApplicationDelegate {
-    func application(
-        _ application: UIApplication,
-        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
-    ) -> Bool {
-        // Delegate may also be set here if not set in App.init.
-        // Setting in App.init is preferred because it runs earlier.
-        return true
-    }
-
-    func application(
-        _ application: UIApplication,
-        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
-    ) {
-        let token = deviceToken.map { String(format: "%02x", $0) }.joined()
-        print("APNs device token: \(token)")
-
-        // Always send token to server -- tokens can change between launches.
+final class AppDelegate: NSObject, UIApplicationDelegate {
+    func application(_ application: UIApplication,
+                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+        let hex = deviceToken.reduce(into: "") { $0 += String(format: "%02x", $1) }
+        // Upload on every call: the token may differ from the last launch.
         Task { @MainActor in
-            await TokenService.shared.upload(token: token)
+            await PushTokenService.shared.upload(hex)
         }
     }
 
-    func application(
-        _ application: UIApplication,
-        didFailToRegisterForRemoteNotificationsWithError error: Error
-    ) {
+    func application(_ application: UIApplication,
+                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
         #if targetEnvironment(simulator)
-        // Simulator can simulate pushes with .apns files or simctl, but it
-        // does not register with APNs for a real device token.
-        print("Simulator: APNs device-token registration is unavailable.")
+        // Always happens here; use .apns files or simctl push to test.
         #else
-        print("APNs registration failed: \(error.localizedDescription)")
-        // Log to your analytics/crash reporting service
+        Diagnostics.record("apns_registration_failed", error: error)
         #endif
     }
 
-    // Silent push / background notification handler
-    func application(
-        _ application: UIApplication,
-        didReceiveRemoteNotification userInfo: [AnyHashable: Any]
-    ) async -> UIBackgroundFetchResult {
-        await BackgroundNotificationHandler.shared.handle(userInfo: userInfo)
+    func application(_ application: UIApplication,
+                     didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async
+        -> UIBackgroundFetchResult {
+        await SilentPushHandler().handle(job: userInfo["job"] as? String)
     }
 }
 ```
 
-## Full UNUserNotificationCenterDelegate
+## The Center Delegate
+
+The protocol methods are `nonisolated`: the system may call them off the main
+thread and the notification objects are not `Sendable`. Each one copies the
+plain values it needs, then hands them to main-actor code.
 
 ```swift
+struct TapSummary: Sendable {
+    let category: String
+    let action: String
+    let threadID: String?
+    let plantID: String?
+    let typed: String?
+
+    init(_ response: UNNotificationResponse) {
+        let content = response.notification.request.content
+        category = content.categoryIdentifier
+        action = response.actionIdentifier
+        threadID = content.userInfo["threadID"] as? String
+        plantID = content.userInfo["plantID"] as? String
+        typed = (response as? UNTextInputNotificationResponse)?.userText
+    }
+}
+
 @MainActor
-final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
-    static let shared = NotificationDelegate()
+final class GardenNotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
+    static let shared = GardenNotificationDelegate()
+    weak var router: NotificationRouter?
+    var visibleThreadID: String?
 
     private override init() { super.init() }
 
-    /// Called when a notification arrives while the app is in the foreground.
-    /// Return which presentation options to use. Without this method,
-    /// foreground notifications are silently suppressed.
-    func userNotificationCenter(
-        _ center: UNUserNotificationCenter,
-        willPresent notification: UNNotification
-    ) async -> UNNotificationPresentationOptions {
-        let userInfo = notification.request.content.userInfo
-
-        // Example: suppress banner for the chat screen the user is already viewing
-        if let chatId = userInfo["chatId"] as? String,
-           NavigationState.shared.currentChatId == chatId {
-            // Still update badge/list but do not show a banner
+    nonisolated func userNotificationCenter(_ center: UNUserNotificationCenter,
+                                            willPresent notification: UNNotification) async
+        -> UNNotificationPresentationOptions {
+        let thread = notification.request.content.userInfo["threadID"] as? String
+        let onScreen = await visibleThreadID
+        if let thread, thread == onScreen {
+            // The user is already looking at this conversation: skip the banner.
             return [.badge, .list, .sound]
         }
-
         return [.banner, .sound, .badge, .list]
     }
 
-    /// Called when the user taps the notification or a notification action button.
-    func userNotificationCenter(
-        _ center: UNUserNotificationCenter,
-        didReceive response: UNNotificationResponse
-    ) async {
-        let userInfo = response.notification.request.content.userInfo
-        let categoryIdentifier = response.notification.request.content.categoryIdentifier
+    nonisolated func userNotificationCenter(_ center: UNUserNotificationCenter,
+                                            didReceive response: UNNotificationResponse) async {
+        await handle(TapSummary(response))
+    }
 
-        switch response.actionIdentifier {
+    private func handle(_ tap: TapSummary) async {
+        switch tap.action {
         case UNNotificationDefaultActionIdentifier:
-            await routeNotificationTap(category: categoryIdentifier, userInfo: userInfo)
-
+            openScreen(for: tap)
         case UNNotificationDismissActionIdentifier:
-            // User swiped away the notification. Only fires if the category
-            // was created with .customDismissAction option.
-            break
-
+            // Only delivered when the category has .customDismissAction.
+            await ChatService.shared.markSeen(tap.threadID)
         default:
-            // Custom action button
-            await handleAction(
-                response.actionIdentifier,
-                category: categoryIdentifier,
-                response: response,
-                userInfo: userInfo
-            )
+            await perform(tap)
         }
     }
 
-    // MARK: - Routing
-
-    private func routeNotificationTap(
-        category: String,
-        userInfo: [AnyHashable: Any]
-    ) async {
-        switch category {
-        case "MESSAGE_CATEGORY":
-            guard let chatId = userInfo["chatId"] as? String else { return }
-            DeepLinkRouter.shared.navigate(to: .chat(id: chatId))
-
-        case "WORKOUT_CATEGORY":
-            guard let workoutId = userInfo["workoutId"] as? String else { return }
-            DeepLinkRouter.shared.navigate(to: .workout(id: workoutId))
-
+    private func openScreen(for tap: TapSummary) {
+        switch tap.category {
+        case "CHAT":
+            if let id = tap.threadID { router?.navigate(to: .thread(id: id)) }
+        case "WATERING":
+            if let id = tap.plantID { router?.navigate(to: .plant(id: id)) }
         default:
-            // Unknown category -- open the app to its default state
-            break
+            break   // unknown category: the app simply opens where it was
         }
     }
 
-    private func handleAction(
-        _ actionIdentifier: String,
-        category: String,
-        response: UNNotificationResponse,
-        userInfo: [AnyHashable: Any]
-    ) async {
-        switch (category, actionIdentifier) {
-        case ("MESSAGE_CATEGORY", "REPLY_ACTION"):
-            guard let textResponse = response as? UNTextInputNotificationResponse,
-                  let chatId = userInfo["chatId"] as? String else { return }
-            await MessageService.shared.sendReply(
-                text: textResponse.userText,
-                chatId: chatId
-            )
-
-        case ("MESSAGE_CATEGORY", "LIKE_ACTION"):
-            guard let messageId = userInfo["messageId"] as? String else { return }
-            await MessageService.shared.likeMessage(id: messageId)
-
-        case ("MESSAGE_CATEGORY", "MARK_READ_ACTION"):
-            guard let chatId = userInfo["chatId"] as? String else { return }
-            await MessageService.shared.markAsRead(chatId: chatId)
-
+    private func perform(_ tap: TapSummary) async {
+        switch (tap.category, tap.action) {
+        case ("CHAT", "REPLY"):
+            guard let text = tap.typed, let id = tap.threadID else { return }
+            await ChatService.shared.send(text, to: id)
+        case ("CHAT", "MARK_READ"):
+            await ChatService.shared.markSeen(tap.threadID)
+        case ("WATERING", "DONE"):
+            if let id = tap.plantID { await PlantStore.shared.logWatering(id) }
         default:
             break
         }
@@ -220,16 +175,16 @@ final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
 }
 ```
 
-## Deep Link Router
-
-An `@Observable` router that bridges notification taps to SwiftUI navigation. The router holds a pending destination that the view layer observes and consumes.
+## Routing a Tap to a Screen
 
 ```swift
-@Observable
-@MainActor
-final class DeepLinkRouter {
-    static let shared = DeepLinkRouter()
+enum AppDestination: Hashable {
+    case thread(id: String)
+    case plant(id: String)
+}
 
+@Observable @MainActor
+final class NotificationRouter {
     var pendingDestination: AppDestination?
 
     func navigate(to destination: AppDestination) {
@@ -237,200 +192,134 @@ final class DeepLinkRouter {
     }
 }
 
-enum AppDestination: Hashable {
-    case chat(id: String)
-    case workout(id: String)
-    case profile(userId: String)
-    case settings
-}
+enum AppTab: Hashable { case chats, garden }
 
-// In the root view:
 struct RootView: View {
-    @Environment(DeepLinkRouter.self) private var router
-    @State private var selectedTab: Tab = .home
-    @State private var homePath = NavigationPath()
-    @State private var chatPath = NavigationPath()
+    @Environment(NotificationRouter.self) private var router
+    @State private var tab: AppTab = .chats
+    @State private var chatsPath = NavigationPath()
+    @State private var gardenPath = NavigationPath()
 
     var body: some View {
-        TabView(selection: $selectedTab) {
-            Tab("Home", systemImage: "house", value: .home) {
-                NavigationStack(path: $homePath) {
-                    HomeView()
-                        .navigationDestination(for: AppDestination.self) { dest in
-                            destinationView(for: dest)
-                        }
+        TabView(selection: $tab) {
+            Tab("Chats", systemImage: "bubble.left.and.bubble.right", value: AppTab.chats) {
+                NavigationStack(path: $chatsPath) {
+                    ChatListView()
+                        .navigationDestination(for: AppDestination.self) { DestinationView($0) }
                 }
             }
-            Tab("Chat", systemImage: "message", value: .chat) {
-                NavigationStack(path: $chatPath) {
-                    ChatListView()
-                        .navigationDestination(for: AppDestination.self) { dest in
-                            destinationView(for: dest)
-                        }
+            Tab("Garden", systemImage: "leaf", value: AppTab.garden) {
+                NavigationStack(path: $gardenPath) {
+                    GardenView()
+                        .navigationDestination(for: AppDestination.self) { DestinationView($0) }
                 }
             }
         }
-        .onChange(of: router.pendingDestination) { _, destination in
-            guard let destination else { return }
-            handleDeepLink(destination)
+        .onChange(of: router.pendingDestination) { _, target in
+            guard let target else { return }
+            switch target {
+            case .thread:
+                tab = .chats
+                chatsPath = NavigationPath()
+                chatsPath.append(target)
+            case .plant:
+                tab = .garden
+                gardenPath = NavigationPath()
+                gardenPath.append(target)
+            }
             router.pendingDestination = nil
         }
     }
-
-    private func handleDeepLink(_ destination: AppDestination) {
-        switch destination {
-        case .chat:
-            selectedTab = .chat
-            chatPath = NavigationPath()
-            chatPath.append(destination)
-        case .workout:
-            selectedTab = .home
-            homePath = NavigationPath()
-            homePath.append(destination)
-        case .profile, .settings:
-            selectedTab = .home
-            homePath = NavigationPath()
-            homePath.append(destination)
-        }
-    }
-
-    @ViewBuilder
-    private func destinationView(for destination: AppDestination) -> some View {
-        switch destination {
-        case .chat(let id): ChatDetailView(chatId: id)
-        case .workout(let id): WorkoutDetailView(workoutId: id)
-        case .profile(let userId): ProfileView(userId: userId)
-        case .settings: SettingsView()
-        }
-    }
 }
 ```
 
-## Silent Push Handler
+`Tab(_:systemImage:value:)` needs iOS 18; on older targets use `.tabItem` and
+`.tag`.
 
-Silent pushes wake the app in the background to fetch new content. The system gives approximately 30 seconds of background execution time. Return the correct `UIBackgroundFetchResult` so the system can learn the app's data patterns and schedule future wakes efficiently.
+## Handling a Silent Push
 
-```swift
-@MainActor
-final class BackgroundNotificationHandler {
-    static let shared = BackgroundNotificationHandler()
-
-    func handle(userInfo: [AnyHashable: Any]) async -> UIBackgroundFetchResult {
-        guard let action = userInfo["action"] as? String else {
-            return .noData
-        }
-
-        do {
-            switch action {
-            case "sync":
-                let hasNewData = try await DataSyncService.shared.performSync()
-                return hasNewData ? .newData : .noData
-
-            case "refresh-config":
-                try await ConfigService.shared.refreshRemoteConfig()
-                return .newData
-
-            case "clear-cache":
-                await CacheManager.shared.clearExpired()
-                return .newData
+The app gets roughly 30 seconds of background time. Report the real outcome:
+the system uses the results to learn when your data changes and to plan later
+wake-ups. The delegate reads the `job` string out of `userInfo` before calling
+the handler: the dictionary is not `Sendable`, so Swift 6 rejects handing it
+from the main-actor delegate to a nonisolated async method.
 
-            default:
-                return .noData
+```swift
+struct SilentPushHandler {
+    func handle(job: String?) async -> UIBackgroundFetchResult {
+        switch job {
+        case "refreshInbox":
+            do {
+                let changed = try await MailboxSync.shared.refresh()
+                return changed ? .newData : .noData
+            } catch {
+                return .failed
             }
-        } catch {
-            print("Background notification handling failed: \(error)")
-            return .failed
+        case "purgeCache":
+            await ImageCache.shared.purgeExpired()
+            return .noData
+        default:
+            return .noData
         }
     }
 }
 ```
 
-**Important:** The Background Modes capability with "Remote notifications" must be enabled in the Xcode project for silent push to work. Send background pushes with `aps.content-available = 1`, no alert/sound/badge keys, `apns-push-type: background`, and `apns-priority: 5`. Delivery is low priority, throttled, and not guaranteed; Apple cautions against more than two or three per hour, so do not use silent pushes for every-few-minutes polling or user-visible notification behavior. Keep `didReceiveRemoteNotification` work bounded and return the correct `UIBackgroundFetchResult` within the background execution window.
+Apple's guidance caps background pushes at roughly two or three per hour. Do not use them to poll a server, and never make something the user can
+see depend on one arriving.
 
-When reviewing a background-push proposal, explicitly call out these contracts: background pushes are not immediate freshness signals; APNs may throttle or drop them; the app needs Background Modes > Remote notifications; the app delegate handler must finish promptly and return `.newData`, `.noData`, or `.failed` based on the actual result.
+When reviewing a silent-push design, flag each of these if missing:
+- It does not deliver instant freshness.
+- APNs can throttle or drop the push.
+- The Remote notifications background mode is on.
+- The handler finishes quickly and its result matches what happened.
 
-## Notification Scheduling Manager
+## A Local Scheduler
 
-A service that encapsulates local notification scheduling, making it testable and reusable.
+Wrapping the center in one type keeps call sites small and gives tests a seam.
 
 ```swift
 @MainActor
 final class NotificationScheduler {
-    private let center = UNUserNotificationCenter.current()
-
-    // MARK: - Schedule
-
-    func scheduleReminder(
-        id: String,
-        title: String,
-        body: String,
-        at date: Date,
-        repeats: Bool = false,
-        categoryIdentifier: String? = nil,
-        userInfo: [String: String] = [:]
-    ) async throws {
-        let content = UNMutableNotificationContent()
-        content.title = title
-        content.body = body
-        content.sound = .default
-        content.userInfo = userInfo
-        if let category = categoryIdentifier {
-            content.categoryIdentifier = category
-        }
-
-        let components = Calendar.current.dateComponents(
-            [.year, .month, .day, .hour, .minute],
-            from: date
-        )
-        let trigger = UNCalendarNotificationTrigger(
-            dateMatching: components,
-            repeats: repeats
-        )
+    private let center: UNUserNotificationCenter
 
-        let request = UNNotificationRequest(
-            identifier: id,
-            content: content,
-            trigger: trigger
-        )
-
-        try await center.add(request)
+    init(center: UNUserNotificationCenter = .current()) {
+        self.center = center
     }
 
-    func scheduleDailyReminder(
-        id: String,
-        title: String,
-        body: String,
-        hour: Int,
-        minute: Int
-    ) async throws {
-        let content = UNMutableNotificationContent()
-        content.title = title
-        content.body = body
-        content.sound = .default
-
-        var components = DateComponents()
-        components.hour = hour
-        components.minute = minute
-
-        let trigger = UNCalendarNotificationTrigger(
-            dateMatching: components,
-            repeats: true
-        )
+    func remind(_ key: String, headline: String, text: String, on moment: Date,
+                categoryID: String? = nil) async throws {
+        let payload = makeContent(headline, text)
+        if let categoryID { payload.categoryIdentifier = categoryID }
+        let when = Calendar.current.dateComponents([.year, .month, .day, .hour, .minute], from: moment)
+        try await enqueue(key, payload, UNCalendarNotificationTrigger(dateMatching: when, repeats: false))
+    }
 
-        let request = UNNotificationRequest(
-            identifier: id,
-            content: content,
-            trigger: trigger
-        )
+    func remindEveryDay(_ key: String, headline: String, text: String,
+                        atHour hour: Int, minute: Int) async throws {
+        var when = DateComponents()
+        when.hour = hour
+        when.minute = minute
+        let payload = makeContent(headline, text)
+        try await enqueue(key, payload, UNCalendarNotificationTrigger(dateMatching: when, repeats: true))
+    }
 
-        try await center.add(request)
+    private func makeContent(_ headline: String, _ text: String) -> UNMutableNotificationContent {
+        let payload = UNMutableNotificationContent()
+        payload.title = headline
+        payload.body = text
+        payload.sound = .default
+        return payload
     }
 
-    // MARK: - Manage
+    private func enqueue(_ key: String, _ payload: UNNotificationContent,
+                         _ trigger: UNNotificationTrigger) async throws {
+        try await center.add(UNNotificationRequest(identifier: key, content: payload, trigger: trigger))
+    }
 
-    func cancelNotification(id: String) {
-        center.removePendingNotificationRequests(withIdentifiers: [id])
-        center.removeDeliveredNotifications(withIdentifiers: [id])
+    func cancel(_ key: String) {
+        center.removePendingNotificationRequests(withIdentifiers: [key])
+        center.removeDeliveredNotifications(withIdentifiers: [key])
     }
 
     func cancelAll() {
@@ -438,229 +327,183 @@ final class NotificationScheduler {
         center.removeAllDeliveredNotifications()
     }
 
-    func pendingNotifications() async -> [UNNotificationRequest] {
-        await center.pendingNotificationRequests()
-    }
-
-    func isScheduled(id: String) async -> Bool {
-        let pending = await center.pendingNotificationRequests()
-        return pending.contains { $0.identifier == id }
+    func hasPending(_ key: String) async -> Bool {
+        let queued = await center.pendingNotificationRequests()
+        return queued.contains { $0.identifier == key }
     }
 }
 ```
 
-## Token Refresh and Update Flow
+## Token Lifecycle
 
-Device tokens can change between app launches. Treat the token as ephemeral and always send the latest to your server from every `didRegisterForRemoteNotificationsWithDeviceToken` callback. Do not use `UserDefaults` as the source of truth for skipping upload, and do not assume a fixed token length.
+The token is short-lived data. Send whatever the latest callback delivered;
+never check a value in `UserDefaults` to decide an upload can be skipped.
 
 ```swift
-@MainActor
-@Observable
-final class TokenService {
-    static let shared = TokenService()
-
+@MainActor @Observable
+final class PushTokenService {
+    static let shared = PushTokenService()
     private(set) var currentToken: String?
 
-    func upload(token: String) async {
+    func upload(_ hexToken: String) async {
         do {
-            try await APIClient.shared.registerDeviceToken(token)
-            currentToken = token
+            try await DeviceAPI.register(pushToken: hexToken)
+            currentToken = hexToken
         } catch {
-            print("Failed to upload APNs token: \(error)")
-            // Retry on next launch -- didRegisterForRemoteNotifications fires again
+            // Nothing to retry by hand: the next launch delivers the token again.
         }
     }
 
-    /// Call when the user logs out to disassociate the token from their account.
     func invalidate() async {
-        guard let token = currentToken else { return }
-        try? await APIClient.shared.unregisterDeviceToken(token)
+        if let active = currentToken {
+            try? await DeviceAPI.unregister(pushToken: active)
+        }
         currentToken = nil
     }
 }
 ```
 
-**Logout flow:** When a user logs out, unregister the device token from your server. Otherwise the old user's account continues receiving pushes on this device.
+Call `invalidate()` at sign-out. Without it the server keeps the token bound to
+the old account and that account's pushes keep landing on this device.
 
-## Category Registration
+## Registering Categories
 
-Register categories at app launch, before any notification arrives. Calling `setNotificationCategories` replaces the entire set, so register all categories in one call.
+Register at launch, before the first notification can arrive.
+`setNotificationCategories` replaces the whole set, so pass every category in
+one call.
 
 ```swift
-func registerNotificationCategories() {
-    // Message category
-    let replyAction = UNTextInputNotificationAction(
-        identifier: "REPLY_ACTION",
-        title: "Reply",
-        options: [],
-        textInputButtonTitle: "Send",
-        textInputPlaceholder: "Type a reply..."
-    )
-    let markReadAction = UNNotificationAction(
-        identifier: "MARK_READ_ACTION",
-        title: "Mark as Read",
-        options: []
-    )
-    let messageCategory = UNNotificationCategory(
-        identifier: "MESSAGE_CATEGORY",
-        actions: [replyAction, markReadAction],
-        intentIdentifiers: [],
-        categorySummaryFormat: "%u more messages from %@",
-        options: [.customDismissAction]
-    )
-
-    // Workout category
-    let startAction = UNNotificationAction(
-        identifier: "START_WORKOUT_ACTION",
-        title: "Start",
-        options: [.foreground]
-    )
-    let skipAction = UNNotificationAction(
-        identifier: "SKIP_WORKOUT_ACTION",
-        title: "Skip",
-        options: [.destructive]
-    )
-    let workoutCategory = UNNotificationCategory(
-        identifier: "WORKOUT_CATEGORY",
-        actions: [startAction, skipAction],
-        intentIdentifiers: [],
-        options: []
-    )
-
-    UNUserNotificationCenter.current().setNotificationCategories([
-        messageCategory,
-        workoutCategory,
-    ])
+enum NotificationCategories {
+    static func registerAll() {
+        let reply = UNTextInputNotificationAction(
+            identifier: "REPLY", title: "Reply", options: [],
+            textInputButtonTitle: "Send", textInputPlaceholder: "Write a reply"
+        )
+        let markRead = UNNotificationAction(identifier: "MARK_READ", title: "Mark as Read", options: [])
+        let chat = UNNotificationCategory(
+            identifier: "CHAT",
+            actions: [reply, markRead],
+            intentIdentifiers: [],
+            hiddenPreviewsBodyPlaceholder: nil,
+            categorySummaryFormat: "%u more from %@",
+            options: [.customDismissAction]
+        )
+
+        let done = UNNotificationAction(identifier: "DONE", title: "Watered", options: [.foreground])
+        let skip = UNNotificationAction(identifier: "SKIP", title: "Skip Today", options: [.destructive])
+        let watering = UNNotificationCategory(
+            identifier: "WATERING", actions: [done, skip], intentIdentifiers: []
+        )
+
+        UNUserNotificationCenter.current().setNotificationCategories([chat, watering])
+    }
 }
 ```
 
-## Testing Notifications
+## Testing and Debugging Delivery
 
-### Simulator Limitations
+### What Simulator can and cannot do
 
-- **Remote notifications cannot be received** via APNs on the simulator.
-- **Drag-and-drop `.apns` files** onto the simulator to simulate remote notifications.
-- **Local notifications** work normally on the simulator.
-- `didFailToRegisterForRemoteNotificationsWithError` always fires on the simulator.
+- It never receives pushes from APNs, and
+  `didFailToRegisterForRemoteNotificationsWithError` fires every time.
+- Local notifications behave normally.
+- A `.apns` file dropped onto the Simulator window is shown as a remote
+  notification.
 
-### Simulating Remote Notifications
+### Simulating a remote notification
 
-Create a `.apns` file and drag it onto the running simulator:
+The file needs a top-level `Simulator Target Bundle` key alongside `aps` and
+any custom keys:
 
 ```json
 {
-    "Simulator Target Bundle": "com.example.myapp",
-    "aps": {
-        "alert": {
-            "title": "Test Notification",
-            "body": "This is a simulated push notification."
-        },
-        "badge": 1,
-        "sound": "default",
-        "category": "MESSAGE_CATEGORY"
-    },
-    "messageId": "test-123",
-    "chatId": "chat-abc"
+  "Simulator Target Bundle": "org.sample.garden",
+  "aps": { "alert": { "title": "Basil", "body": "Time to water." }, "sound": "default" },
+  "plantID": "basil-01"
 }
 ```
 
-Or use the `xcrun simctl push` command:
-
 ```bash
-xcrun simctl push booted com.example.myapp payload.apns
+xcrun simctl push booted org.sample.garden watering.apns
 ```
 
-### Testing on Device
-
-Use the APNs sandbox environment during development. The device token from a development build uses the sandbox; production builds use the production APNs endpoint.
-
-For quick testing without a server, use tools like:
-- **Apple Push Notification Console** to send development-environment test payloads and inspect delivery logs
-- Command-line APNs requests generated by the console or your own provider scripts
-
-### Debugging Delivery
-
-1. **Check entitlements:** Ensure the push notification entitlement is in the app's provisioning profile. The `aps-environment` key must be present.
-
-2. **Verify token format:** The token you send to your provider should be the hexadecimal bytes from `deviceToken`. Do not hard-code a token length; APNs says not to make assumptions about device token size.
-
-3. **Check APNs response codes:**
-
-| Status | Meaning | Action |
-|--------|---------|--------|
-| 200 | Success | Notification accepted by APNs |
-| 400 | Bad request | Check payload format (max 4096 bytes) |
-| 403 | Forbidden | Certificate/key mismatch or expired |
-| 405 | Method not allowed | Must use POST with HTTP/2 |
-| 410 | Gone | Device token is no longer valid; remove from server |
-| 413 | Payload too large | Reduce payload size (max 4096 bytes) |
-| 429 | Too many requests | APNs is throttling; back off |
-| 500 | Internal server error | APNs issue; retry later |
-
-4. **Console.app:** Connect the device, open Console.app on Mac, filter by `dasd` or `apsd` or your app's bundle identifier. Look for delivery confirmations or rejection reasons.
-
-5. **Common reasons notifications do not arrive:**
-   - App is in Low Power Mode and the system defers delivery
-   - Focus / Do Not Disturb is active and the app is not in the allowed list
-   - The device has no internet connection
-   - The device token has changed and the server is using a stale token (status 410)
-   - Silent pushes are rate-limited by the system (typically a few per hour)
-   - The notification payload exceeds 4096 bytes
-   - The APNs certificate or key has expired
-
-6. **Background push debugging:** Silent pushes are heavily throttled. The system decides when and whether to wake the app. During development, the system is more generous. In production, expect delays. Use `BGTaskScheduler` for more reliable background processing.
-
-## Badge Management
-
-Reset the badge count when the user opens the app so stale badge numbers do not persist.
+### On a device
+
+Debug builds receive sandbox tokens; release and TestFlight builds talk to the
+production APNs endpoint. The Push Notifications Console in the developer
+account sends test pushes to development tokens and shows delivery logs; a
+request generated there, or your own script, can also be replayed.
+
+### When nothing arrives
+
+- The provisioning profile includes the push entitlement and the app carries
+  the `aps-environment` key.
+- The provider sends the token as hex, with no assumption about its size.
+
+| APNs status | Meaning |
+|-------------|---------|
+| 200 | Accepted |
+| 400 | Bad request; check the payload format (4096 bytes at most) |
+| 403 | Certificate or signing key is wrong or has expired |
+| 405 | Wrong method; requests must be POST over HTTP/2 |
+| 410 | Token is no longer valid; delete it on the server |
+| 413 | Payload over 4096 bytes |
+| 429 | Too many requests; back off |
+| 500 | APNs internal error; retry later |
+
+On a Mac with the device attached, Console.app filtered to `apsd`, `dasd` or
+the app's bundle ID shows the system's side of delivery.
+
+Frequent causes of missing notifications:
+- Low Power Mode is deferring work.
+- A Focus or Do Not Disturb mode does not allow the app.
+- No network.
+- A stale token (410).
+- Silent pushes above the few-per-hour budget.
+- A payload over 4096 bytes.
+- An expired APNs certificate or key.
+
+Silent pushes are handled more generously while debugging than in production,
+where delays are normal. For background work that must run, use
+`BGTaskScheduler` (see `background-processing`).
+
+## Badges
+
+Clear the badge when the app becomes active so an old count does not stay on
+the icon. `setBadgeCount(_:)` is async and throws, available from iOS 16; add
+an availability check when the deployment target is older. The two-parameter
+`onChange(of:)` closure below is iOS 17; on iOS 16 use the single-value form.
 
 ```swift
-// In AppDelegate or SceneDelegate
-func sceneDidBecomeActive(_ scene: UIScene) {
-    UNUserNotificationCenter.current().setBadgeCount(0)
-}
-
-// Or in SwiftUI with the scene phase
-struct ContentView: View {
-    @Environment(\.scenePhase) private var scenePhase
-
-    var body: some View {
-        MainView()
-            .onChange(of: scenePhase) { _, phase in
-                if phase == .active {
-                    Task {
-                        try? await UNUserNotificationCenter.current().setBadgeCount(0)
-                    }
-                }
+struct BadgeResetModifier: ViewModifier {
+    @Environment(\.scenePhase) private var phase
+
+    func body(content wrapped: Content) -> some View {
+        wrapped.onChange(of: phase) { _, newPhase in
+            guard newPhase == .active else { return }
+            Task {
+                let center = UNUserNotificationCenter.current()
+                try? await center.setBadgeCount(0)
             }
+        }
     }
 }
 ```
 
-`setBadgeCount(_:)` (iOS 16+) is the modern `UserNotifications` API for updating the badge count. Use availability checks if you still support older deployment targets.
+A UIKit scene can do the same in `sceneDidBecomeActive(_:)`.
 
-## Provisional to Full Authorization Upgrade
+## From Provisional to Full Permission
 
-If you started with provisional notifications, you can later ask for full authorization. The system shows the permission prompt again.
+A provisional user can be asked again: requesting `[.alert, .sound, .badge]`
+now shows the real system prompt.
 
 ```swift
 @MainActor
-func upgradeToFullAuthorization() async -> Bool {
+func upgradeFromProvisional() async -> Bool {
     let center = UNUserNotificationCenter.current()
-    let settings = await center.notificationSettings()
-
-    guard settings.authorizationStatus == .provisional else {
-        return settings.authorizationStatus == .authorized
-    }
-
-    do {
-        // This presents the system prompt to the user
-        let granted = try await center.requestAuthorization(
-            options: [.alert, .sound, .badge]
-        )
-        return granted
-    } catch {
-        return false
-    }
+    let status = await center.notificationSettings().authorizationStatus
+    guard status == .provisional else { return status == .authorized }
+    let granted = try? await center.requestAuthorization(options: [.sound, .badge, .alert])
+    return granted ?? false
 }
 ```