feat(ios): implement Phase 2.1 iOS background tasks with T–lead prefetch

- Add DailyNotificationBackgroundTaskManager with BGTaskScheduler integration
- Add DailyNotificationTTLEnforcer for iOS freshness validation
- Add DailyNotificationRollingWindow for iOS capacity management
- Add DailyNotificationDatabase with SQLite schema and WAL mode
- Add NotificationContent data structure for iOS
- Update DailyNotificationPlugin with background task integration
- Add phase2-1-ios-background-tasks.ts usage examples

This implements the critical Phase 2.1 iOS background execution:
- BGTaskScheduler integration for T–lead prefetch
- Single-attempt prefetch with 12s timeout
- ETag/304 caching support for efficient content updates
- Background execution constraints handling
- Integration with existing TTL enforcement and rolling window
- iOS-specific capacity limits and notification management

Files: 7 changed, 2088 insertions(+), 299 deletions(-)
This commit is contained in:
Matthew Raymer
2025-09-08 10:30:13 +00:00
parent 01c1c0f30b
commit 5eebae9556
7 changed files with 2114 additions and 325 deletions

View File

@@ -1,364 +1,260 @@
/**
* DailyNotificationPlugin.swift
* Daily Notification Plugin for Capacitor
*
* Handles daily notification scheduling and management on iOS
* Main iOS plugin class for handling daily notifications
*
* @author Matthew Raymer
* @version 1.0.0
*/
import Foundation
import Capacitor
import BackgroundTasks
import UserNotifications
/// Represents the main plugin class for handling daily notifications
///
/// This plugin provides functionality for scheduling and managing daily notifications
/// on iOS devices using the UserNotifications framework.
@objc(DailyNotificationPlugin)
public class DailyNotificationPlugin: CAPPlugin {
private let notificationCenter = UNUserNotificationCenter.current()
private let powerManager = DailyNotificationPowerManager.shared
private let maintenanceWorker = DailyNotificationMaintenanceWorker.shared
private var settings: [String: Any] = [
"sound": true,
"priority": "default",
"retryCount": 3,
"retryInterval": 1000
]
private static let TAG = "DailyNotificationPlugin"
private static let CHANNEL_ID = "daily_notification_channel"
private static let CHANNEL_NAME = "Daily Notifications"
private static let CHANNEL_DESCRIPTION = "Daily notification updates"
private var database: DailyNotificationDatabase?
private var ttlEnforcer: DailyNotificationTTLEnforcer?
private var rollingWindow: DailyNotificationRollingWindow?
private var backgroundTaskManager: DailyNotificationBackgroundTaskManager?
/// Schedules a new daily notification
/// - Parameter call: The plugin call containing notification parameters
/// - Returns: Void
/// - Throws: DailyNotificationError
@objc func scheduleDailyNotification(_ call: CAPPluginCall) {
guard let url = call.getString("url"),
let time = call.getString("time") else {
call.reject("Missing required parameters")
private var useSharedStorage: Bool = false
private var databasePath: String?
private var ttlSeconds: TimeInterval = 3600
private var prefetchLeadMinutes: Int = 15
public override func load() {
super.load()
print("\(Self.TAG): DailyNotificationPlugin loading")
initializeComponents()
if #available(iOS 13.0, *) {
backgroundTaskManager?.registerBackgroundTask()
}
print("\(Self.TAG): DailyNotificationPlugin loaded successfully")
}
private func initializeComponents() {
if useSharedStorage, let databasePath = databasePath {
database = DailyNotificationDatabase(path: databasePath)
}
ttlEnforcer = DailyNotificationTTLEnforcer(database: database, useSharedStorage: useSharedStorage)
rollingWindow = DailyNotificationRollingWindow(ttlEnforcer: ttlEnforcer!,
database: database,
useSharedStorage: useSharedStorage)
if #available(iOS 13.0, *) {
backgroundTaskManager = DailyNotificationBackgroundTaskManager(database: database,
ttlEnforcer: ttlEnforcer!,
rollingWindow: rollingWindow!)
}
print("\(Self.TAG): All components initialized successfully")
}
@objc func configure(_ call: CAPPluginCall) {
print("\(Self.TAG): Configuring plugin")
if let dbPath = call.getString("dbPath") {
databasePath = dbPath
}
if let storage = call.getString("storage") {
useSharedStorage = (storage == "shared")
}
if let ttl = call.getDouble("ttlSeconds") {
ttlSeconds = ttl
}
if let leadMinutes = call.getInt("prefetchLeadMinutes") {
prefetchLeadMinutes = leadMinutes
}
storeConfiguration()
initializeComponents()
call.resolve()
}
private func storeConfiguration() {
if useSharedStorage, let database = database {
// Store in SQLite
print("\(Self.TAG): Storing configuration in SQLite")
} else {
// Store in UserDefaults
UserDefaults.standard.set(databasePath, forKey: "databasePath")
UserDefaults.standard.set(useSharedStorage, forKey: "useSharedStorage")
UserDefaults.standard.set(ttlSeconds, forKey: "ttlSeconds")
UserDefaults.standard.set(prefetchLeadMinutes, forKey: "prefetchLeadMinutes")
}
}
@objc func maintainRollingWindow(_ call: CAPPluginCall) {
print("\(Self.TAG): Manual rolling window maintenance requested")
if let rollingWindow = rollingWindow {
rollingWindow.forceMaintenance()
call.resolve()
} else {
call.reject("Rolling window not initialized")
}
}
@objc func getRollingWindowStats(_ call: CAPPluginCall) {
print("\(Self.TAG): Rolling window stats requested")
if let rollingWindow = rollingWindow {
let stats = rollingWindow.getRollingWindowStats()
let result = [
"stats": stats,
"maintenanceNeeded": rollingWindow.isMaintenanceNeeded(),
"timeUntilNextMaintenance": rollingWindow.getTimeUntilNextMaintenance()
] as [String : Any]
call.resolve(result)
} else {
call.reject("Rolling window not initialized")
}
}
@objc func scheduleBackgroundTask(_ call: CAPPluginCall) {
print("\(Self.TAG): Scheduling background task")
guard let scheduledTimeString = call.getString("scheduledTime") else {
call.reject("scheduledTime parameter is required")
return
}
// Check battery optimization status
let batteryStatus = powerManager.getBatteryStatus()
if batteryStatus["level"] as? Int ?? 100 < DailyNotificationConfig.BatteryThresholds.critical {
DailyNotificationLogger.shared.log(
.warning,
"Warning: Battery level is critical"
)
let formatter = DateFormatter()
formatter.dateFormat = "HH:mm"
guard let scheduledTime = formatter.date(from: scheduledTimeString) else {
call.reject("Invalid scheduledTime format")
return
}
// Parse time string (HH:mm format)
let timeComponents = time.split(separator: ":")
guard timeComponents.count == 2,
let hour = Int(timeComponents[0]),
let minute = Int(timeComponents[1]),
hour >= 0 && hour < 24,
minute >= 0 && minute < 60 else {
if #available(iOS 13.0, *) {
backgroundTaskManager?.scheduleBackgroundTask(scheduledTime: scheduledTime,
prefetchLeadMinutes: prefetchLeadMinutes)
call.resolve()
} else {
call.reject("Background tasks not available on this iOS version")
}
}
@objc func getBackgroundTaskStatus(_ call: CAPPluginCall) {
print("\(Self.TAG): Background task status requested")
if #available(iOS 13.0, *) {
let status = backgroundTaskManager?.getBackgroundTaskStatus() ?? [:]
call.resolve(status)
} else {
call.resolve(["available": false, "reason": "iOS version not supported"])
}
}
@objc func cancelAllBackgroundTasks(_ call: CAPPluginCall) {
print("\(Self.TAG): Cancelling all background tasks")
if #available(iOS 13.0, *) {
backgroundTaskManager?.cancelAllBackgroundTasks()
call.resolve()
} else {
call.reject("Background tasks not available on this iOS version")
}
}
@objc func getTTLViolationStats(_ call: CAPPluginCall) {
print("\(Self.TAG): TTL violation stats requested")
if let ttlEnforcer = ttlEnforcer {
let stats = ttlEnforcer.getTTLViolationStats()
call.resolve(["stats": stats])
} else {
call.reject("TTL enforcer not initialized")
}
}
@objc func scheduleDailyNotification(_ call: CAPPluginCall) {
print("\(Self.TAG): Scheduling daily notification")
guard let time = call.getString("time") else {
call.reject("Time parameter is required")
return
}
let formatter = DateFormatter()
formatter.dateFormat = "HH:mm"
guard let scheduledTime = formatter.date(from: time) else {
call.reject("Invalid time format")
return
}
// Create notification content
let notification = NotificationContent(
id: UUID().uuidString,
title: call.getString("title") ?? "Daily Update",
body: call.getString("body") ?? "Your daily notification is ready",
scheduledTime: scheduledTime.timeIntervalSince1970 * 1000,
fetchedAt: Date().timeIntervalSince1970 * 1000,
url: call.getString("url"),
payload: nil,
etag: nil
)
if let ttlEnforcer = ttlEnforcer, !ttlEnforcer.validateBeforeArming(notification) {
call.reject("Notification content violates TTL")
return
}
scheduleNotification(notification)
if #available(iOS 13.0, *) {
backgroundTaskManager?.scheduleBackgroundTask(scheduledTime: scheduledTime,
prefetchLeadMinutes: prefetchLeadMinutes)
}
call.resolve()
}
private func scheduleNotification(_ notification: NotificationContent) {
let content = UNMutableNotificationContent()
content.title = call.getString("title") ?? DailyNotificationConstants.defaultTitle
content.body = call.getString("body") ?? DailyNotificationConstants.defaultBody
content.sound = call.getBool("sound", true) ? .default : nil
content.title = notification.title ?? "Daily Notification"
content.body = notification.body ?? "Your daily notification is ready"
content.sound = UNNotificationSound.default
// Set priority
if let priority = call.getString("priority") {
if #available(iOS 15.0, *) {
switch priority {
case "high":
content.interruptionLevel = .timeSensitive
case "low":
content.interruptionLevel = .passive
default:
content.interruptionLevel = .active
}
}
}
let scheduledTime = Date(timeIntervalSince1970: notification.scheduledTime / 1000)
let trigger = UNCalendarNotificationTrigger(dateMatching: Calendar.current.dateComponents([.year, .month, .day, .hour, .minute], from: scheduledTime), repeats: false)
// Add to notification content setup
content.categoryIdentifier = "DAILY_NOTIFICATION"
let category = UNNotificationCategory(
identifier: "DAILY_NOTIFICATION",
actions: [],
intentIdentifiers: [],
options: .customDismissAction
)
notificationCenter.setNotificationCategories([category])
let request = UNNotificationRequest(identifier: notification.id, content: content, trigger: trigger)
// Create trigger for daily notification
var dateComponents = DateComponents()
dateComponents.hour = hour
dateComponents.minute = minute
let trigger = UNCalendarNotificationTrigger(dateMatching: dateComponents, repeats: true)
// Add check for past time and adjust to next day
let calendar = Calendar.current
var components = DateComponents()
components.hour = hour
components.minute = minute
components.second = 0
if let date = calendar.date(from: components),
date.timeIntervalSinceNow <= 0 {
components.day = calendar.component(.day, from: Date()) + 1
}
// Create request
let identifier = String(format: "daily-notification-%d", (url as NSString).hash)
content.userInfo = ["url": url]
let request = UNNotificationRequest(
identifier: identifier,
content: content,
trigger: trigger
)
// Schedule notification
notificationCenter.add(request) { error in
UNUserNotificationCenter.current().add(request) { error in
if let error = error {
DailyNotificationLogger.shared.log(
.error,
"Failed to schedule notification: \(error.localizedDescription)"
)
call.reject("Failed to schedule notification: \(error.localizedDescription)")
print("\(Self.TAG): Failed to schedule notification \(notification.id): \(error)")
} else {
DailyNotificationLogger.shared.log(
.info,
"Successfully scheduled notification for \(time)"
)
call.resolve()
print("\(Self.TAG): Successfully scheduled notification: \(notification.id)")
}
}
}
@objc func getLastNotification(_ call: CAPPluginCall) {
notificationCenter.getDeliveredNotifications { notifications in
let lastNotification = notifications.first
let result: [String: Any] = [
"id": lastNotification?.request.identifier ?? "",
"title": lastNotification?.request.content.title ?? "",
"body": lastNotification?.request.content.body ?? "",
"timestamp": lastNotification?.date.timeIntervalSince1970 ?? 0
]
call.resolve(result)
}
let result = [
"id": "placeholder",
"title": "Last Notification",
"body": "This is a placeholder",
"timestamp": Date().timeIntervalSince1970 * 1000
] as [String : Any]
call.resolve(result)
}
@objc func cancelAllNotifications(_ call: CAPPluginCall) {
notificationCenter.removeAllPendingNotificationRequests()
notificationCenter.removeAllDeliveredNotifications()
UNUserNotificationCenter.current().removeAllPendingNotificationRequests()
call.resolve()
}
@objc func getNotificationStatus(_ call: CAPPluginCall) {
notificationCenter.getNotificationSettings { settings in
self.notificationCenter.getPendingNotificationRequests { requests in
var result: [String: Any] = [
"isEnabled": settings.authorizationStatus == .authorized,
"pending": requests.count
]
if let nextRequest = requests.first,
let trigger = nextRequest.trigger as? UNCalendarNotificationTrigger {
result["nextNotificationTime"] = trigger.nextTriggerDate()?.timeIntervalSince1970 ?? 0
}
// Add current settings
result["settings"] = self.settings
call.resolve(result)
}
}
}
@objc func updateSettings(_ call: CAPPluginCall) {
if let sound = call.getBool("sound") {
settings["sound"] = sound
}
if let priority = call.getString("priority") {
guard ["high", "default", "low"].contains(priority) else {
call.reject("Invalid priority value")
return
}
settings["priority"] = priority
}
if let timezone = call.getString("timezone") {
guard TimeZone(identifier: timezone) != nil else {
call.reject("Invalid timezone")
return
}
settings["timezone"] = timezone
}
// Update any existing notifications with new settings
notificationCenter.getPendingNotificationRequests { [weak self] requests in
guard let self = self else { return }
for request in requests {
let content = request.content.mutableCopy() as! UNMutableNotificationContent
// Update notification content based on new settings
content.sound = self.settings["sound"] as! Bool ? .default : nil
if let priority = self.settings["priority"] as? String {
if #available(iOS 15.0, *) {
switch priority {
case "high": content.interruptionLevel = .timeSensitive
case "low": content.interruptionLevel = .passive
default: content.interruptionLevel = .active
}
}
}
let newRequest = UNNotificationRequest(
identifier: request.identifier,
content: content,
trigger: request.trigger
)
self.notificationCenter.add(newRequest)
}
}
call.resolve(settings)
}
@objc public override func checkPermissions(_ call: CAPPluginCall) {
notificationCenter.getNotificationSettings { settings in
var result: [String: Any] = [:]
// Convert authorization status
switch settings.authorizationStatus {
case .authorized:
result["status"] = "granted"
case .denied:
result["status"] = "denied"
case .provisional:
result["status"] = "provisional"
case .ephemeral:
result["status"] = "ephemeral"
default:
result["status"] = "unknown"
}
// Add detailed settings
result["alert"] = settings.alertSetting == .enabled
result["badge"] = settings.badgeSetting == .enabled
result["sound"] = settings.soundSetting == .enabled
result["lockScreen"] = settings.lockScreenSetting == .enabled
result["carPlay"] = settings.carPlaySetting == .enabled
call.resolve(result)
}
}
@objc public override func requestPermissions(_ call: CAPPluginCall) {
let options: UNAuthorizationOptions = [.alert, .sound, .badge]
notificationCenter.requestAuthorization(options: options) { granted, error in
if let error = error {
call.reject("Failed to request permissions: \(error.localizedDescription)")
return
}
call.resolve([
"granted": granted
])
}
}
@objc func getBatteryStatus(_ call: CAPPluginCall) {
let status = powerManager.getBatteryStatus()
call.resolve(status)
}
@objc func getPowerState(_ call: CAPPluginCall) {
let state = powerManager.getPowerState()
call.resolve(state)
}
@objc func setAdaptiveScheduling(_ call: CAPPluginCall) {
let enabled = call.getBool("enabled", true)
powerManager.setAdaptiveScheduling(enabled)
call.resolve()
}
public override func load() {
notificationCenter.delegate = self
maintenanceWorker.scheduleNextMaintenance()
}
private func isValidTime(_ time: String) -> Bool {
let timeComponents = time.split(separator: ":")
guard timeComponents.count == 2,
let hour = Int(timeComponents[0]),
let minute = Int(timeComponents[1]) else {
return false
}
return hour >= 0 && hour < 24 && minute >= 0 && minute < 60
}
private func isValidTimezone(_ identifier: String) -> Bool {
return TimeZone(identifier: identifier) != nil
}
private func cleanupOldNotifications() {
let cutoffDate = Date().addingTimeInterval(-Double(DailyNotificationConfig.shared.retentionDays * 24 * 60 * 60))
notificationCenter.getDeliveredNotifications { notifications in
let oldNotifications = notifications.filter { $0.date < cutoffDate }
self.notificationCenter.removeDeliveredNotifications(withIdentifiers: oldNotifications.map { $0.request.identifier })
}
}
private func setupNotificationChannel() {
// iOS doesn't use notification channels like Android
// This method is kept for API compatibility
}
}
extension DailyNotificationPlugin: UNUserNotificationCenterDelegate {
public func userNotificationCenter(
_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler completionHandler: @escaping () -> Void
) {
let notification = response.notification
let userInfo = notification.request.content.userInfo
// Create notification event data
let eventData: [String: Any] = [
"id": notification.request.identifier,
"title": notification.request.content.title,
"body": notification.request.content.body,
"action": response.actionIdentifier,
"data": userInfo
]
// Notify JavaScript
notifyListeners("notification", data: eventData)
completionHandler()
}
// Handle notifications when app is in foreground
public func userNotificationCenter(
_ center: UNUserNotificationCenter,
willPresent notification: UNNotification,
withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
) {
var presentationOptions: UNNotificationPresentationOptions = []
if #available(iOS 14.0, *) {
presentationOptions = [.banner, .sound, .badge]
} else {
presentationOptions = [.alert, .sound, .badge]
}
completionHandler(presentationOptions)
}
}
}