Push Notifications

import UserNotifications

/// Notification categories define the actions available for each notification type.
///
/// Register on app launch:
/// ```swift
/// NotificationCategories.registerAll()
/// ```
///
/// Server should include `category` in APNs payload:
/// ```json
/// {
///   "aps": {
///     "alert": { "title": "New Message", "body": "Hello!" },
///     "category": "MESSAGE_CATEGORY"
///   }
/// }
/// ```
enum NotificationCategories {

    // MARK: - Category Identifiers

    enum Identifier: String, CaseIterable {
        case message = "MESSAGE_CATEGORY"
        case reminder = "REMINDER_CATEGORY"
        case update = "UPDATE_CATEGORY"
        case social = "SOCIAL_CATEGORY"
    }

    // MARK: - Action Identifiers

    enum Action: String {
        // Message actions
        case reply = "REPLY_ACTION"
        case markRead = "MARK_READ_ACTION"

        // Reminder actions
        case complete = "COMPLETE_ACTION"
        case snooze = "SNOOZE_ACTION"

        // Update actions
        case view = "VIEW_ACTION"
        case later = "LATER_ACTION"

        // Social actions
        case like = "LIKE_ACTION"
        case comment = "COMMENT_ACTION"
    }

    // MARK: - Registration

    /// Register all notification categories.
    /// Call this on app launch in didFinishLaunchingWithOptions.
    static func registerAll() {
        let categories: Set<UNNotificationCategory> = [
            messageCategory,
            reminderCategory,
            updateCategory,
            socialCategory
        ]

        UNUserNotificationCenter.current().setNotificationCategories(categories)

        #if DEBUG
        print("📋 [Notifications] Registered \(categories.count) categories")
        #endif
    }

    // MARK: - Category Definitions

    /// Message category with reply and mark read actions.
    private static var messageCategory: UNNotificationCategory {
        // Text input action for replies
        let replyAction = UNTextInputNotificationAction(
            identifier: Action.reply.rawValue,
            title: "Reply",
            options: [],
            textInputButtonTitle: "Send",
            textInputPlaceholder: "Type your reply..."
        )

        let markReadAction = UNNotificationAction(
            identifier: Action.markRead.rawValue,
            title: "Mark as Read",
            options: []
        )

        return UNNotificationCategory(
            identifier: Identifier.message.rawValue,
            actions: [replyAction, markReadAction],
            intentIdentifiers: [],
            hiddenPreviewsBodyPlaceholder: "New message",
            categorySummaryFormat: "%u new messages",
            options: [.customDismissAction, .allowInCarPlay]
        )
    }

    /// Reminder category with complete and snooze actions.
    private static var reminderCategory: UNNotificationCategory {
        let completeAction = UNNotificationAction(
            identifier: Action.complete.rawValue,
            title: "Complete",
            options: [.foreground]  // Opens app
        )

        let snoozeAction = UNNotificationAction(
            identifier: Action.snooze.rawValue,
            title: "Snooze 15 min",
            options: []
        )

        return UNNotificationCategory(
            identifier: Identifier.reminder.rawValue,
            actions: [completeAction, snoozeAction],
            intentIdentifiers: [],
            hiddenPreviewsBodyPlaceholder: "Reminder",
            options: []
        )
    }

    /// Update category with view and later actions.
    private static var updateCategory: UNNotificationCategory {
        let viewAction = UNNotificationAction(
            identifier: Action.view.rawValue,
            title: "View",
            options: [.foreground]
        )

        let laterAction = UNNotificationAction(
            identifier: Action.later.rawValue,
            title: "Later",
            options: []
        )

        return UNNotificationCategory(
            identifier: Identifier.update.rawValue,
            actions: [viewAction, laterAction],
            intentIdentifiers: [],
            options: []
        )
    }

    /// Social category with like and comment actions.
    private static var socialCategory: UNNotificationCategory {
        let likeAction = UNNotificationAction(
            identifier: Action.like.rawValue,
            title: "❤️ Like",
            options: []
        )

        let commentAction = UNTextInputNotificationAction(
            identifier: Action.comment.rawValue,
            title: "Comment",
            options: [.foreground],
            textInputButtonTitle: "Post",
            textInputPlaceholder: "Write a comment..."
        )

        return UNNotificationCategory(
            identifier: Identifier.social.rawValue,
            actions: [likeAction, commentAction],
            intentIdentifiers: [],
            hiddenPreviewsBodyPlaceholder: "New activity",
            categorySummaryFormat: "%u new notifications",
            options: [.customDismissAction]
        )
    }
}

// MARK: - Category Summary Formats

/*
 Category Summary Format Specifiers:

 %u - Number of notifications in the group
 %@ - The summary argument from the notification content

 Example:
 - categorySummaryFormat: "%u new messages from %@"
 - With 3 notifications from "John"
 - Shows: "3 new messages from John"

 To set the summary argument:
 content.summaryArgument = "John"
 content.summaryArgumentCount = 3  // Optional, defaults to 1
 */

// MARK: - Action Options Reference

/*
 UNNotificationActionOptions:

 .authenticationRequired - Requires device unlock
 .destructive           - Red text, indicates destructive action
 .foreground           - Opens the app when selected

 UNNotificationCategoryOptions:

 .customDismissAction     - Calls delegate when dismissed
 .allowInCarPlay          - Shows in CarPlay
 .hiddenPreviewsShowTitle - Shows title even when previews hidden
 .hiddenPreviewsShowSubtitle - Shows subtitle even when previews hidden
 .allowAnnouncement       - Siri can announce
 */

import Foundation
import UserNotifications

/// Handles notification presentation and user responses.
///
/// Setup in AppDelegate:
/// ```swift
/// func application(_ application: UIApplication, didFinishLaunchingWithOptions...) -> Bool {
///     UNUserNotificationCenter.current().delegate = NotificationDelegate.shared
///     NotificationCategories.registerAll()
///     return true
/// }
/// ```
final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate, @unchecked Sendable {

    // MARK: - Singleton

    static let shared = NotificationDelegate()

    // MARK: - Handlers

    /// Custom handler for notification tap. Set this to handle navigation.
    var onNotificationTap: ((NotificationPayload) async -> Void)?

    /// Custom handler for notification actions. Set this to handle action buttons.
    var onNotificationAction: ((String, NotificationPayload) async -> Void)?

    // MARK: - Initialization

    private override init() {
        super.init()
    }

    // MARK: - UNUserNotificationCenterDelegate

    /// Called when a notification arrives while app is in foreground.
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification
    ) async -> UNNotificationPresentationOptions {

        let userInfo = notification.request.content.userInfo

        #if DEBUG
        print("📬 [Notifications] Received in foreground")
        print("   Title: \(notification.request.content.title)")
        print("   Body: \(notification.request.content.body)")
        #endif

        // Parse and optionally handle
        if let payload = NotificationPayload(userInfo: userInfo) {
            // You can choose to handle silently or show banner
            // For example, don't show banner if user is already viewing related content
            // return []
            _ = payload  // Suppress unused warning
        }

        // Show notification banner, sound, and badge
        return [.banner, .sound, .badge, .list]
    }

    /// Called when user interacts with a notification.
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse
    ) async {

        let userInfo = response.notification.request.content.userInfo
        let actionIdentifier = response.actionIdentifier

        #if DEBUG
        print("📬 [Notifications] User responded")
        print("   Action: \(actionIdentifier)")
        #endif

        guard let payload = NotificationPayload(userInfo: userInfo) else {
            return
        }

        switch actionIdentifier {
        case UNNotificationDefaultActionIdentifier:
            // User tapped the notification
            await handleNotificationTap(payload)

        case UNNotificationDismissActionIdentifier:
            // User dismissed (only if category has .customDismissAction)
            #if DEBUG
            print("   User dismissed notification")
            #endif

        default:
            // Custom action button
            await handleCustomAction(actionIdentifier, payload: payload, response: response)
        }
    }

    /// Called when user opens notification settings from notification.
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        openSettingsFor notification: UNNotification?
    ) {
        // Post notification for app to handle
        NotificationCenter.default.post(
            name: .openNotificationSettings,
            object: nil
        )
    }

    // MARK: - Handlers

    private func handleNotificationTap(_ payload: NotificationPayload) async {
        // Use custom handler if set
        if let handler = onNotificationTap {
            await handler(payload)
            return
        }

        // Default handling based on type
        await MainActor.run {
            switch payload.type {
            case .message:
                if let resourceId = payload.resourceId {
                    NotificationCenter.default.post(
                        name: .navigateToMessage,
                        object: nil,
                        userInfo: ["messageId": resourceId]
                    )
                }

            case .reminder:
                if let resourceId = payload.resourceId {
                    NotificationCenter.default.post(
                        name: .navigateToReminder,
                        object: nil,
                        userInfo: ["reminderId": resourceId]
                    )
                }

            case .update:
                NotificationCenter.default.post(
                    name: .showUpdateDetails,
                    object: nil,
                    userInfo: payload.extra
                )

            case .unknown:
                // Handle deep link if available
                if let deepLink = payload.deepLink {
                    NotificationCenter.default.post(
                        name: .handleDeepLink,
                        object: nil,
                        userInfo: ["url": deepLink]
                    )
                }
            }
        }
    }

    private func handleCustomAction(
        _ identifier: String,
        payload: NotificationPayload,
        response: UNNotificationResponse
    ) async {
        // Use custom handler if set
        if let handler = onNotificationAction {
            await handler(identifier, payload)
            return
        }

        // Default action handling
        switch identifier {
        case NotificationCategories.Action.reply.rawValue:
            // Handle text input reply
            if let textResponse = response as? UNTextInputNotificationResponse {
                await handleReply(text: textResponse.userText, payload: payload)
            }

        case NotificationCategories.Action.markRead.rawValue:
            await markAsRead(payload: payload)

        case NotificationCategories.Action.complete.rawValue:
            await completeTask(payload: payload)

        case NotificationCategories.Action.snooze.rawValue:
            await snoozeReminder(payload: payload)

        default:
            #if DEBUG
            print("⚠️ [Notifications] Unknown action: \(identifier)")
            #endif
        }
    }

    // MARK: - Action Implementations

    private func handleReply(text: String, payload: NotificationPayload) async {
        #if DEBUG
        print("💬 [Notifications] Reply: \(text)")
        #endif

        // TODO: Send reply to server
        // await APIClient.shared.sendReply(to: payload.resourceId, text: text)
    }

    private func markAsRead(payload: NotificationPayload) async {
        #if DEBUG
        print("✓ [Notifications] Mark as read: \(payload.resourceId ?? "unknown")")
        #endif

        // TODO: Mark as read on server
        // await APIClient.shared.markAsRead(payload.resourceId)
    }

    private func completeTask(payload: NotificationPayload) async {
        #if DEBUG
        print("✓ [Notifications] Complete task: \(payload.resourceId ?? "unknown")")
        #endif

        // TODO: Complete task on server
        // await APIClient.shared.completeTask(payload.resourceId)
    }

    private func snoozeReminder(payload: NotificationPayload) async {
        #if DEBUG
        print("⏰ [Notifications] Snooze: \(payload.resourceId ?? "unknown")")
        #endif

        // Reschedule notification for 15 minutes later
        do {
            try await NotificationManager.shared.scheduleLocalNotification(
                title: payload.title ?? "Reminder",
                body: payload.body ?? "",
                in: 15 * 60,  // 15 minutes
                category: NotificationCategories.Identifier.reminder.rawValue,
                userInfo: payload.extra
            )
        } catch {
            #if DEBUG
            print("⚠️ [Notifications] Failed to snooze: \(error)")
            #endif
        }
    }
}

// MARK: - Notification Names

extension Notification.Name {
    /// Posted when user wants to open notification settings.
    static let openNotificationSettings = Notification.Name("openNotificationSettings")

    /// Posted when navigating to a message from notification.
    static let navigateToMessage = Notification.Name("navigateToMessage")

    /// Posted when navigating to a reminder from notification.
    static let navigateToReminder = Notification.Name("navigateToReminder")

    /// Posted when showing update details from notification.
    static let showUpdateDetails = Notification.Name("showUpdateDetails")

    /// Posted when handling a deep link from notification.
    static let handleDeepLink = Notification.Name("handleDeepLink")
}

import Foundation
import UserNotifications
#if canImport(UIKit)
import UIKit
#endif

/// Central manager for push notification registration and handling.
///
/// Usage:
/// ```swift
/// // Request permission
/// let granted = try await NotificationManager.shared.requestAuthorization()
///
/// // Register for remote notifications
/// if granted {
///     NotificationManager.shared.registerForRemoteNotifications()
/// }
///
/// // Schedule local notification
/// try await NotificationManager.shared.scheduleLocalNotification(
///     title: "Reminder",
///     body: "Don't forget!",
///     at: Date().addingTimeInterval(3600)
/// )
/// ```
@MainActor
@Observable
final class NotificationManager {

    // MARK: - Singleton

    static let shared = NotificationManager()

    // MARK: - Properties

    /// Current authorization status.
    private(set) var authorizationStatus: UNAuthorizationStatus = .notDetermined

    /// Device token for remote notifications (hex string).
    private(set) var deviceToken: String?

    /// Whether notifications are enabled.
    var isAuthorized: Bool {
        authorizationStatus == .authorized
    }

    /// Whether notifications are provisionally authorized.
    var isProvisional: Bool {
        authorizationStatus == .provisional
    }

    // MARK: - Initialization

    private init() {
        Task {
            await refreshAuthorizationStatus()
        }
    }

    // MARK: - Authorization

    /// Request notification authorization from the user.
    ///
    /// - Parameter options: Authorization options (defaults to alert, badge, sound).
    /// - Returns: Whether authorization was granted.
    @discardableResult
    func requestAuthorization(
        options: UNAuthorizationOptions = [.alert, .badge, .sound]
    ) async throws -> Bool {
        let center = UNUserNotificationCenter.current()
        let granted = try await center.requestAuthorization(options: options)

        await refreshAuthorizationStatus()

        return granted
    }

    /// Request provisional authorization (iOS 12+).
    /// Notifications are delivered quietly without prompting the user.
    @discardableResult
    func requestProvisionalAuthorization() async throws -> Bool {
        let options: UNAuthorizationOptions = [.alert, .badge, .sound, .provisional]
        return try await requestAuthorization(options: options)
    }

    /// Refresh the current authorization status.
    func refreshAuthorizationStatus() async {
        let settings = await UNUserNotificationCenter.current().notificationSettings()
        authorizationStatus = settings.authorizationStatus
    }

    /// Check if a specific notification setting is enabled.
    func isSettingEnabled(_ keyPath: KeyPath<UNNotificationSettings, UNNotificationSetting>) async -> Bool {
        let settings = await UNUserNotificationCenter.current().notificationSettings()
        return settings[keyPath: keyPath] == .enabled
    }

    // MARK: - Remote Notification Registration

    /// Register for remote notifications.
    func registerForRemoteNotifications() {
        #if canImport(UIKit) && !os(watchOS)
        UIApplication.shared.registerForRemoteNotifications()
        #endif
    }

    /// Unregister from remote notifications.
    func unregisterForRemoteNotifications() {
        #if canImport(UIKit) && !os(watchOS)
        UIApplication.shared.unregisterForRemoteNotifications()
        #endif
        deviceToken = nil
    }

    /// Called by AppDelegate when registration succeeds.
    func didRegisterForRemoteNotifications(with deviceToken: Data) {
        let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
        self.deviceToken = token

        #if DEBUG
        print("📱 [Notifications] Device token: \(token)")
        #endif

        // Send token to server
        Task {
            await sendTokenToServer(token)
        }
    }

    /// Called by AppDelegate when registration fails.
    func didFailToRegisterForRemoteNotifications(with error: Error) {
        #if DEBUG
        print("❌ [Notifications] Registration failed: \(error.localizedDescription)")
        #endif
    }

    // MARK: - Server Communication

    private func sendTokenToServer(_ token: String) async {
        // TODO: Implement your server token registration
        // Example:
        // do {
        //     try await APIClient.shared.registerDeviceToken(token)
        // } catch {
        //     print("Failed to register token with server: \(error)")
        // }
    }

    // MARK: - Badge Management

    /// Clear the app badge.
    func clearBadge() async {
        do {
            try await UNUserNotificationCenter.current().setBadgeCount(0)
        } catch {
            #if DEBUG
            print("⚠️ [Notifications] Failed to clear badge: \(error)")
            #endif
        }
    }

    /// Set the app badge count.
    func setBadge(_ count: Int) async {
        do {
            try await UNUserNotificationCenter.current().setBadgeCount(count)
        } catch {
            #if DEBUG
            print("⚠️ [Notifications] Failed to set badge: \(error)")
            #endif
        }
    }

    // MARK: - Local Notifications

    /// Schedule a local notification.
    ///
    /// - Parameters:
    ///   - title: Notification title.
    ///   - body: Notification body.
    ///   - date: When to deliver the notification.
    ///   - category: Optional category identifier for actions.
    ///   - userInfo: Additional data to include.
    /// - Returns: The notification identifier (for cancellation).
    @discardableResult
    func scheduleLocalNotification(
        title: String,
        body: String,
        at date: Date,
        category: String? = nil,
        userInfo: [String: Any] = [:]
    ) async throws -> String {
        let content = UNMutableNotificationContent()
        content.title = title
        content.body = body
        content.sound = .default
        content.userInfo = userInfo

        if let category {
            content.categoryIdentifier = category
        }

        let components = Calendar.current.dateComponents(
            [.year, .month, .day, .hour, .minute, .second],
            from: date
        )

        let trigger = UNCalendarNotificationTrigger(
            dateMatching: components,
            repeats: false
        )

        let identifier = UUID().uuidString
        let request = UNNotificationRequest(
            identifier: identifier,
            content: content,
            trigger: trigger
        )

        try await UNUserNotificationCenter.current().add(request)

        #if DEBUG
        print("📅 [Notifications] Scheduled: \(identifier) for \(date)")
        #endif

        return identifier
    }

    /// Schedule a notification with a time interval.
    @discardableResult
    func scheduleLocalNotification(
        title: String,
        body: String,
        in timeInterval: TimeInterval,
        category: String? = nil,
        userInfo: [String: Any] = [:]
    ) async throws -> String {
        let content = UNMutableNotificationContent()
        content.title = title
        content.body = body
        content.sound = .default
        content.userInfo = userInfo

        if let category {
            content.categoryIdentifier = category
        }

        let trigger = UNTimeIntervalNotificationTrigger(
            timeInterval: timeInterval,
            repeats: false
        )

        let identifier = UUID().uuidString
        let request = UNNotificationRequest(
            identifier: identifier,
            content: content,
            trigger: trigger
        )

        try await UNUserNotificationCenter.current().add(request)

        return identifier
    }

    /// Cancel a scheduled notification.
    func cancelNotification(identifier: String) {
        UNUserNotificationCenter.current()
            .removePendingNotificationRequests(withIdentifiers: [identifier])
    }

    /// Cancel all pending notifications.
    func cancelAllNotifications() {
        UNUserNotificationCenter.current().removeAllPendingNotificationRequests()
    }

    /// Get all pending notification requests.
    func getPendingNotifications() async -> [UNNotificationRequest] {
        await UNUserNotificationCenter.current().pendingNotificationRequests()
    }

    /// Get all delivered notifications.
    func getDeliveredNotifications() async -> [UNNotification] {
        await UNUserNotificationCenter.current().deliveredNotifications()
    }

    /// Remove specific delivered notifications.
    func removeDeliveredNotifications(identifiers: [String]) {
        UNUserNotificationCenter.current()
            .removeDeliveredNotifications(withIdentifiers: identifiers)
    }

    /// Remove all delivered notifications.
    func removeAllDeliveredNotifications() {
        UNUserNotificationCenter.current().removeAllDeliveredNotifications()
    }
}

// MARK: - Settings URL Helper

extension NotificationManager {

    /// Open system notification settings for this app.
    func openNotificationSettings() {
        #if canImport(UIKit) && !os(watchOS)
        guard let url = URL(string: UIApplication.openNotificationSettingsURLString) else {
            return
        }

        Task { @MainActor in
            await UIApplication.shared.open(url)
        }
        #endif
    }
}

import Foundation

/// Type-safe representation of a push notification payload.
///
/// Expected server payload format:
/// ```json
/// {
///   "aps": {
///     "alert": {
///       "title": "Notification Title",
///       "body": "Notification body text"
///     },
///     "badge": 1,
///     "sound": "default",
///     "category": "MESSAGE_CATEGORY",
///     "mutable-content": 1
///   },
///   "type": "message",
///   "resource_id": "msg_12345",
///   "deep_link": "myapp://messages/msg_12345",
///   "image_url": "https://example.com/image.jpg",
///   "custom_field": "custom_value"
/// }
/// ```
struct NotificationPayload: Sendable {

    // MARK: - Types

    /// Notification type for routing.
    enum NotificationType: String, Sendable {
        case message
        case reminder
        case update
        case social
        case promo
        case unknown
    }

    // MARK: - Properties

    /// Type of notification for routing.
    let type: NotificationType

    /// Notification title from alert.
    let title: String?

    /// Notification body from alert.
    let body: String?

    /// Subtitle from alert.
    let subtitle: String?

    /// Resource identifier for deep linking.
    let resourceId: String?

    /// Deep link URL.
    let deepLink: URL?

    /// Image URL for rich notifications.
    let imageURL: URL?

    /// Badge count.
    let badge: Int?

    /// Category identifier.
    let category: String?

    /// Thread identifier for grouping.
    let threadId: String?

    /// Any extra custom fields.
    let extra: [String: Any]

    /// Original userInfo dictionary.
    let rawUserInfo: [AnyHashable: Any]

    // MARK: - Initialization

    init?(userInfo: [AnyHashable: Any]) {
        rawUserInfo = userInfo

        // Parse APS dictionary
        guard let aps = userInfo["aps"] as? [String: Any] else {
            return nil
        }

        // Parse alert
        if let alert = aps["alert"] as? [String: Any] {
            title = alert["title"] as? String
            body = alert["body"] as? String
            subtitle = alert["subtitle"] as? String
        } else if let alertString = aps["alert"] as? String {
            title = nil
            body = alertString
            subtitle = nil
        } else {
            title = nil
            body = nil
            subtitle = nil
        }

        // Parse badge
        badge = aps["badge"] as? Int

        // Parse category
        category = aps["category"] as? String

        // Parse thread ID
        threadId = aps["thread-id"] as? String

        // Parse custom fields
        let typeString = userInfo["type"] as? String ?? "unknown"
        type = NotificationType(rawValue: typeString) ?? .unknown

        resourceId = userInfo["resource_id"] as? String
            ?? userInfo["resourceId"] as? String
            ?? userInfo["id"] as? String

        if let deepLinkString = userInfo["deep_link"] as? String
            ?? userInfo["deepLink"] as? String
            ?? userInfo["url"] as? String {
            deepLink = URL(string: deepLinkString)
        } else {
            deepLink = nil
        }

        if let imageString = userInfo["image_url"] as? String
            ?? userInfo["imageUrl"] as? String
            ?? userInfo["image"] as? String {
            imageURL = URL(string: imageString)
        } else {
            imageURL = nil
        }

        // Collect extra fields
        let reservedKeys: Set<String> = [
            "aps", "type", "resource_id", "resourceId", "id",
            "deep_link", "deepLink", "url",
            "image_url", "imageUrl", "image"
        ]

        var extra: [String: Any] = [:]
        for (key, value) in userInfo {
            if let key = key as? String, !reservedKeys.contains(key) {
                extra[key] = value
            }
        }
        self.extra = extra
    }
}

// MARK: - Convenience Accessors

extension NotificationPayload {

    /// Check if this is a silent notification.
    var isSilent: Bool {
        guard let aps = rawUserInfo["aps"] as? [String: Any] else {
            return false
        }
        return aps["content-available"] as? Int == 1 && title == nil && body == nil
    }

    /// Check if this notification has rich content (image).
    var hasRichContent: Bool {
        imageURL != nil
    }

    /// Get a typed extra value.
    func extra<T>(_ key: String, as type: T.Type = T.self) -> T? {
        extra[key] as? T
    }
}

// MARK: - Debug Description

extension NotificationPayload: CustomDebugStringConvertible {

    var debugDescription: String {
        """
        NotificationPayload:
          type: \(type.rawValue)
          title: \(title ?? "nil")
          body: \(body ?? "nil")
          resourceId: \(resourceId ?? "nil")
          deepLink: \(deepLink?.absoluteString ?? "nil")
          imageURL: \(imageURL?.absoluteString ?? "nil")
          badge: \(badge.map { String($0) } ?? "nil")
          category: \(category ?? "nil")
          isSilent: \(isSilent)
          extra: \(extra.keys.joined(separator: ", "))
        """
    }
}

// MARK: - Example Payloads

/*
 Message notification:
 {
   "aps": {
     "alert": { "title": "John", "body": "Hey, how are you?" },
     "badge": 1,
     "sound": "default",
     "category": "MESSAGE_CATEGORY",
     "thread-id": "conversation_123"
   },
   "type": "message",
   "resource_id": "msg_456",
   "deep_link": "myapp://messages/msg_456"
 }

 Reminder notification:
 {
   "aps": {
     "alert": { "title": "Reminder", "body": "Meeting in 15 minutes" },
     "sound": "default",
     "category": "REMINDER_CATEGORY"
   },
   "type": "reminder",
   "resource_id": "reminder_789",
   "meeting_id": "meeting_123"
 }

 Silent notification (background update):
 {
   "aps": {
     "content-available": 1
   },
   "type": "sync",
   "sync_type": "messages",
   "timestamp": "2024-01-15T10:30:00Z"
 }

 Rich notification (with image):
 {
   "aps": {
     "alert": { "title": "New Photo", "body": "Alice shared a photo" },
     "sound": "default",
     "mutable-content": 1
   },
   "type": "social",
   "resource_id": "photo_123",
   "image_url": "https://example.com/photos/preview.jpg"
 }
 */