diff --git a/doc/directives/0003-iOS-Android-Parity-Directive.md b/doc/directives/0003-iOS-Android-Parity-Directive.md new file mode 100644 index 0000000..2f5a48d --- /dev/null +++ b/doc/directives/0003-iOS-Android-Parity-Directive.md @@ -0,0 +1,1193 @@ +# iOS Android Parity Directive — iOS Implementation Upgrade + +**Status:** 🎯 **PLANNING** - Directive for iOS-2 branch +**Date:** 2025-11-13 +**Author:** Matthew Raymer +**Branch:** `ios-2` +**Objective:** Upgrade iOS implementation to match Android functionality while preserving Android code and TypeScript interface + +--- + +## Executive Summary + +This directive outlines the plan to upgrade the iOS implementation of the Daily Notification Plugin to achieve feature parity with the functioning Android implementation. The Android codebase and TypeScript interface definitions will remain **completely untouched** during this work. + +### Key Constraints + +- ✅ **Android code must remain unchanged** - No modifications to `src/android/` directory +- ✅ **TypeScript interface must remain unchanged** - No modifications to `src/definitions.ts` +- ✅ **iOS implementation must match Android functionality** - All Android `@PluginMethod` methods must have iOS equivalents +- ✅ **Platform-specific adaptations allowed** - iOS can use Swift/iOS APIs but must provide same functionality + +### Testing & Scope + +- ✅ **Primary Testing Target:** iOS Simulator +- ✅ **Initial Scope:** One scheduled prefetch + one scheduled notification per day + - **Prefetch Timing:** 5 minutes before notification time + - **Notification Timing:** User-specified daily time +- ✅ **Test App:** `ios-test-app` (equivalent to `android-test-app`) with same HTML/JS UI +- ✅ **Rolling Window:** Deferred to Phase 2 (initial implementation supports single daily schedule) + +### Readiness Milestones + +- **Phase 1:** Test app ready for basic testing (one prefetch + one notification per day) +- **Phase 3:** Library ready for TimeSafari integration +- **Phase 4:** Full library ready for production TimeSafari integration + +--- + +## Current State Assessment + +### Android Implementation (Reference) + +**Location:** `src/android/DailyNotificationPlugin.java` + +**Key Components:** +- ✅ `DailyNotificationPlugin.java` - Main plugin class (1936 lines) +- ✅ `DailyNotificationStorage.java` - Storage abstraction +- ✅ `DailyNotificationScheduler.java` - AlarmManager-based scheduling +- ✅ `DailyNotificationFetcher.java` - Background content fetching +- ✅ `DailyNotificationDatabase.java` - SQLite database management +- ✅ `DailyNotificationRollingWindow.java` - Rolling window safety +- ✅ `DailyNotificationExactAlarmManager.java` - Exact alarm management +- ✅ `DailyNotificationRebootRecoveryManager.java` - Reboot recovery +- ✅ `DailyNotificationTTLEnforcer.java` - TTL enforcement +- ✅ `DailyNotificationETagManager.java` - ETag caching +- ✅ `DailyNotificationJWTManager.java` - JWT authentication +- ✅ `EnhancedDailyNotificationFetcher.java` - TimeSafari API integration +- ✅ `DailyNotificationFetchWorker.java` - WorkManager background worker +- ✅ `DailyNotificationReceiver.java` - Broadcast receiver for alarms + +**Implemented Methods (from Android):** +1. `configure()` - Plugin configuration with database/storage options +2. `scheduleDailyNotification()` - Schedule daily notification +3. `getLastNotification()` - Get last delivered notification +4. `cancelAllNotifications()` - Cancel all scheduled notifications +5. `getNotificationStatus()` - Get current notification status +6. `updateSettings()` - Update notification settings +7. `getBatteryStatus()` - Get battery status information +8. `requestBatteryOptimizationExemption()` - Request battery optimization exemption +9. `setAdaptiveScheduling()` - Enable/disable adaptive scheduling +10. `getPowerState()` - Get current power state +11. `maintainRollingWindow()` - Manual rolling window maintenance +12. `getRollingWindowStats()` - Get rolling window statistics +13. `getExactAlarmStatus()` - Get exact alarm status +14. `requestExactAlarmPermission()` - Request exact alarm permission +15. `openExactAlarmSettings()` - Open exact alarm settings +16. `getRebootRecoveryStatus()` - Get reboot recovery status +17. `setActiveDidFromHost()` - Set activeDid from host (Phase 1) +18. `refreshAuthenticationForNewIdentity()` - Refresh authentication (Phase 1) +19. `clearCacheForNewIdentity()` - Clear cache for new identity (Phase 1) +20. `updateBackgroundTaskIdentity()` - Update background task identity (Phase 1) +21. `testJWTGeneration()` - Test JWT generation (Phase 1) +22. `testEndorserAPI()` - Test Endorser.ch API (Phase 1) +23. `coordinateBackgroundTasks()` - Coordinate background tasks (Phase 3) +24. `handleAppLifecycleEvent()` - Handle app lifecycle events (Phase 3) +25. `getCoordinationStatus()` - Get coordination status (Phase 3) +26. `scheduleDailyReminder()` - Schedule static daily reminder +27. `cancelDailyReminder()` - Cancel daily reminder +28. `getScheduledReminders()` - Get all scheduled reminders +29. `updateDailyReminder()` - Update existing daily reminder + +### iOS Implementation (Current) + +**Location:** `ios/Plugin/DailyNotificationPlugin.swift` + +**Current Components:** +- ✅ `DailyNotificationPlugin.swift` - Main plugin class (480 lines, partial) +- ✅ `DailyNotificationDatabase.swift` - CoreData database (exists) +- ✅ `DailyNotificationRollingWindow.swift` - Rolling window (exists) +- ✅ `DailyNotificationTTLEnforcer.swift` - TTL enforcer (exists) +- ✅ `DailyNotificationETagManager.swift` - ETag manager (exists) +- ✅ `DailyNotificationBackgroundTaskManager.swift` - Background task manager (exists) +- ✅ `DailyNotificationConstants.swift` - Constants (exists) +- ✅ `DailyNotificationErrorHandler.swift` - Error handling (exists) +- ✅ `DailyNotificationLogger.swift` - Logging (exists) +- ✅ `DailyNotificationPowerManager.swift` - Power management (exists) +- ✅ `DailyNotificationPerformanceOptimizer.swift` - Performance (exists) +- ✅ `DailyNotificationCallbacks.swift` - Callbacks (exists) +- ✅ `DailyNotificationConfig.swift` - Configuration (exists) +- ✅ `DailyNotificationModel.swift` - Data models (exists) +- ✅ `DailyNotificationMaintenanceWorker.swift` - Maintenance (exists) + +**Currently Implemented Methods:** +1. ✅ `configure()` - Basic configuration (needs enhancement) +2. ✅ `scheduleContentFetch()` - Basic BGTaskScheduler (needs enhancement) +3. ✅ `scheduleUserNotification()` - Basic UNUserNotificationCenter (needs enhancement) +4. ✅ `scheduleDualNotification()` - Dual scheduling (needs enhancement) +5. ✅ `getDualScheduleStatus()` - Status retrieval (needs enhancement) +6. ✅ `scheduleDailyReminder()` - Static reminders (implemented) +7. ✅ `cancelDailyReminder()` - Cancel reminders (implemented) +8. ✅ `getScheduledReminders()` - Get reminders (implemented) +9. ✅ `updateDailyReminder()` - Update reminders (implemented) + +**Missing Methods (Need Implementation):** +1. ❌ `scheduleDailyNotification()` - Main scheduling method +2. ❌ `getLastNotification()` - Last notification retrieval +3. ❌ `cancelAllNotifications()` - Cancel all notifications +4. ❌ `getNotificationStatus()` - Status retrieval +5. ❌ `updateSettings()` - Settings update +6. ❌ `getBatteryStatus()` - Battery status +7. ❌ `requestBatteryOptimizationExemption()` - Battery optimization +8. ❌ `setAdaptiveScheduling()` - Adaptive scheduling +9. ❌ `getPowerState()` - Power state +10. ❌ `maintainRollingWindow()` - Rolling window maintenance +11. ❌ `getRollingWindowStats()` - Rolling window stats +12. ❌ `getExactAlarmStatus()` - Exact alarm status (iOS equivalent) +13. ❌ `requestExactAlarmPermission()` - Alarm permission (iOS equivalent) +14. ❌ `openExactAlarmSettings()` - Alarm settings (iOS equivalent) +15. ❌ `getRebootRecoveryStatus()` - Reboot recovery status +16. ❌ `setActiveDidFromHost()` - ActiveDid management (Phase 1) +17. ❌ `refreshAuthenticationForNewIdentity()` - Auth refresh (Phase 1) +18. ❌ `clearCacheForNewIdentity()` - Cache clearing (Phase 1) +19. ❌ `updateBackgroundTaskIdentity()` - Background task identity (Phase 1) +20. ❌ `testJWTGeneration()` - JWT testing (Phase 1) +21. ❌ `testEndorserAPI()` - API testing (Phase 1) +22. ❌ `coordinateBackgroundTasks()` - Background coordination (Phase 3) +23. ❌ `handleAppLifecycleEvent()` - Lifecycle events (Phase 3) +24. ❌ `getCoordinationStatus()` - Coordination status (Phase 3) + +--- + +## Implementation Strategy + +**Testing Environment:** iOS Simulator (primary testing target) + +**Initial Scope:** Simplified daily schedule +- **One scheduled prefetch per day** (via BGTaskScheduler) + - **Timing:** 5 minutes before notification time +- **One scheduled notification per day** (via UNUserNotificationCenter) + - **Timing:** User-specified daily time +- Full rolling window and advanced features deferred to later phases + +### Phase 1: Core Infrastructure Parity + +**Objective:** Implement core notification scheduling and management methods with simplified daily schedule + +**Tasks:** +1. **Storage Layer Enhancement** + - Enhance `DailyNotificationStorage` (Swift equivalent) to match Android `DailyNotificationStorage.java` + - Support both UserDefaults and SQLite (CoreData) storage modes + - Implement content caching and retrieval + +2. **Scheduler Implementation** + - Create `DailyNotificationScheduler.swift` equivalent to `DailyNotificationScheduler.java` + - Use `UNUserNotificationCenter` for notification scheduling + - **Initial:** Support single daily notification (one prefetch + one notification per day) + - Rolling window logic deferred to Phase 2 + +3. **Background Fetching** + - Enhance `DailyNotificationBackgroundTaskManager.swift` to match Android `DailyNotificationFetcher.java` + - Implement `BGTaskScheduler` registration and execution + - **Initial:** Support single daily prefetch task (scheduled 5 minutes before notification) + - Add content fetching with ETag support + +4. **Core Methods Implementation** + - `scheduleDailyNotification()` - Main scheduling method (single daily schedule) + - `getLastNotification()` - Last notification retrieval + - `cancelAllNotifications()` - Cancel all + - `getNotificationStatus()` - Status retrieval + - `updateSettings()` - Settings update + +**Platform Adaptations:** +- Android `AlarmManager` → iOS `UNUserNotificationCenter` with `UNCalendarNotificationTrigger` +- Android `WorkManager` → iOS `BGTaskScheduler` with `BGAppRefreshTaskRequest` +- Android `SharedPreferences` → iOS `UserDefaults` (with SQLite option via CoreData) + +**Test App Readiness:** Phase 1 test app should be ready for testing on iOS Simulator after core methods are implemented + +### Phase 2: Advanced Features Parity + +**Objective:** Implement advanced features matching Android capabilities + +**Tasks:** +1. **Rolling Window Management** + - Enhance `DailyNotificationRollingWindow.swift` to match Android implementation + - Implement iOS-specific limits (64 pending notifications) + - Add maintenance scheduling + - **Note:** Expands beyond single daily schedule to support rolling window + +2. **TTL Enforcement** + - Enhance `DailyNotificationTTLEnforcer.swift` to match Android implementation + - Implement TTL checking at notification fire time + - Add stale content handling + +3. **Exact Alarm Equivalent** + - Implement iOS equivalent of Android exact alarm management + - Use `UNTimeIntervalNotificationTrigger` for precise timing + - Handle iOS notification delivery guarantees + +4. **Reboot Recovery** + - Create `DailyNotificationRebootRecoveryManager.swift` equivalent + - Use iOS app launch detection to reschedule notifications + - Implement recovery status tracking + +5. **Power Management** + - Enhance `DailyNotificationPowerManager.swift` to match Android capabilities + - Implement battery status checking + - Add background refresh status checking + +**Platform Adaptations:** +- Android exact alarms → iOS notification delivery with time-based triggers +- Android battery optimization → iOS Background App Refresh settings +- Android reboot recovery → iOS app launch detection and rescheduling + +**Test App Readiness:** Phase 2 test app should be ready for testing rolling window and advanced features on iOS Simulator + +### Phase 3: TimeSafari Integration Parity + +**Objective:** Implement TimeSafari-specific integration features + +**Tasks:** +1. **JWT Management** + - Create `DailyNotificationJWTManager.swift` equivalent + - Implement JWT token generation and caching + - Add token refresh logic + +2. **ETag Management** + - Enhance `DailyNotificationETagManager.swift` to match Android + - Implement ETag caching and conditional requests + - Add ETag invalidation logic + +3. **Enhanced Fetcher** + - Create `EnhancedDailyNotificationFetcher.swift` equivalent + - Implement TimeSafari API integration + - Add activeDid support + +4. **Phase 1 Methods** + - `setActiveDidFromHost()` - ActiveDid management + - `refreshAuthenticationForNewIdentity()` - Auth refresh + - `clearCacheForNewIdentity()` - Cache clearing + - `updateBackgroundTaskIdentity()` - Background task identity + - `testJWTGeneration()` - JWT testing + - `testEndorserAPI()` - API testing + +**Platform Adaptations:** +- Android WorkManager background tasks → iOS BGTaskScheduler background tasks +- Android SharedPreferences for config → iOS UserDefaults for config +- Android JWT signing → iOS JWT signing (same algorithm, different implementation) + +**TimeSafari Integration Readiness:** Library ready for TimeSafari integration after Phase 3 completion +**Test App Readiness:** Phase 3 test app should be ready for testing TimeSafari integration features on iOS Simulator + +### Phase 4: Background Coordination Parity + +**Objective:** Implement background task coordination features + +**Tasks:** +1. **Background Coordination** + - Implement `coordinateBackgroundTasks()` method + - Add TimeSafari PlatformServiceMixin integration + - Coordinate BGTaskScheduler with app lifecycle + +2. **Lifecycle Management** + - Implement `handleAppLifecycleEvent()` method + - Handle app background/foreground events + - Sync state with app lifecycle + +3. **Coordination Status** + - Implement `getCoordinationStatus()` method + - Track coordination state + - Provide debugging information + +**Platform Adaptations:** +- Android app lifecycle callbacks → iOS app lifecycle notifications +- Android WorkManager coordination → iOS BGTaskScheduler coordination + +**TimeSafari Integration Readiness:** Full library ready for production TimeSafari integration after Phase 4 completion +**Test App Readiness:** Phase 4 test app should be ready for testing full background coordination on iOS Simulator + +--- + +## Component Mapping: Android → iOS + +### Core Components + +| Android Component | iOS Equivalent | Status | Notes | +|------------------|----------------|--------|-------| +| `DailyNotificationPlugin.java` | `DailyNotificationPlugin.swift` | ✅ Partial | Needs method additions | +| `DailyNotificationStorage.java` | `DailyNotificationStorage.swift` | ❌ Missing | Create new file | +| `DailyNotificationScheduler.java` | `DailyNotificationScheduler.swift` | ❌ Missing | Create new file | +| `DailyNotificationFetcher.java` | `DailyNotificationBackgroundTaskManager.swift` | ✅ Exists | Needs enhancement | +| `DailyNotificationDatabase.java` | `DailyNotificationDatabase.swift` | ✅ Exists | CoreData-based | +| `DailyNotificationRollingWindow.java` | `DailyNotificationRollingWindow.swift` | ✅ Exists | Needs enhancement | +| `DailyNotificationExactAlarmManager.java` | iOS equivalent needed | ❌ Missing | Use UNUserNotificationCenter | +| `DailyNotificationRebootRecoveryManager.java` | iOS equivalent needed | ❌ Missing | Use app launch detection | +| `DailyNotificationTTLEnforcer.java` | `DailyNotificationTTLEnforcer.swift` | ✅ Exists | Needs enhancement | +| `DailyNotificationETagManager.java` | `DailyNotificationETagManager.swift` | ✅ Exists | Needs enhancement | +| `DailyNotificationJWTManager.java` | iOS equivalent needed | ❌ Missing | Create new file | +| `EnhancedDailyNotificationFetcher.java` | iOS equivalent needed | ❌ Missing | Create new file | +| `DailyNotificationFetchWorker.java` | BGTaskScheduler handler | ❌ Missing | Implement in plugin | +| `DailyNotificationReceiver.java` | Notification delegate | ❌ Missing | Implement in plugin | + +### Platform API Mapping + +| Android API | iOS Equivalent | Implementation Notes | +|-------------|----------------|---------------------| +| `AlarmManager.setExact()` | `UNUserNotificationCenter.add()` with `UNCalendarNotificationTrigger` | Use calendar-based triggers for daily scheduling | +| `WorkManager.enqueue()` | `BGTaskScheduler.submit()` | Use BGAppRefreshTaskRequest for background fetching | +| `SharedPreferences` | `UserDefaults` | For simple key-value storage | +| `SQLiteDatabase` | `CoreData` / `SQLite.swift` | For complex data storage | +| `NotificationManager` | `UNUserNotificationCenter` | For notification delivery | +| `PowerManager` | `UIDevice.batteryState` | For battery status | +| `BroadcastReceiver` | App lifecycle notifications | For reboot recovery | +| `PendingIntent` | `UNNotificationRequest` | For scheduled notifications | + +--- + +## Method Implementation Checklist + +### Core Methods (Phase 1) + +- [ ] `configure(options: ConfigureOptions)` - Enhanced configuration +- [ ] `scheduleDailyNotification(options: NotificationOptions)` - Main scheduling +- [ ] `getLastNotification()` - Last notification retrieval +- [ ] `cancelAllNotifications()` - Cancel all notifications +- [ ] `getNotificationStatus()` - Status retrieval +- [ ] `updateSettings(settings: NotificationSettings)` - Settings update +- [ ] `getBatteryStatus()` - Battery status +- [ ] `requestBatteryOptimizationExemption()` - Battery optimization (iOS: Background App Refresh) +- [ ] `setAdaptiveScheduling(options: { enabled: boolean })` - Adaptive scheduling +- [ ] `getPowerState()` - Power state + +### Rolling Window Methods (Phase 2) + +- [ ] `maintainRollingWindow()` - Manual maintenance +- [ ] `getRollingWindowStats()` - Statistics retrieval + +### Exact Alarm Methods (Phase 2) - iOS Equivalents + +- [ ] `getExactAlarmStatus()` - Notification delivery status +- [ ] `requestExactAlarmPermission()` - Notification permissions +- [ ] `openExactAlarmSettings()` - Open notification settings + +### Reboot Recovery Methods (Phase 2) + +- [ ] `getRebootRecoveryStatus()` - Recovery status + +### TimeSafari Integration Methods (Phase 3) + +- [ ] `setActiveDidFromHost(options: { activeDid: string })` - ActiveDid management +- [ ] `refreshAuthenticationForNewIdentity(options: { activeDid: string })` - Auth refresh +- [ ] `clearCacheForNewIdentity()` - Cache clearing +- [ ] `updateBackgroundTaskIdentity(options: { activeDid: string })` - Background task identity +- [ ] `testJWTGeneration(options?: { activeDid?: string })` - JWT testing +- [ ] `testEndorserAPI(options?: { activeDid?: string, apiServer?: string })` - API testing + +### Background Coordination Methods (Phase 4) + +- [ ] `coordinateBackgroundTasks()` - Background coordination +- [ ] `handleAppLifecycleEvent(options: { lifecycleEvent: string })` - Lifecycle events +- [ ] `getCoordinationStatus()` - Coordination status + +### Enhanced Dual Scheduling Methods (Already Partially Implemented) + +- [x] `scheduleContentFetch(config: ContentFetchConfig)` - Needs enhancement +- [x] `scheduleUserNotification(config: UserNotificationConfig)` - Needs enhancement +- [x] `scheduleDualNotification(config: DualScheduleConfiguration)` - Needs enhancement +- [x] `getDualScheduleStatus()` - Needs enhancement + +### Reminder Methods (Already Implemented) + +- [x] `scheduleDailyReminder(options: ReminderOptions)` - ✅ Complete +- [x] `cancelDailyReminder(options: { reminderId: string })` - ✅ Complete +- [x] `getScheduledReminders()` - ✅ Complete +- [x] `updateDailyReminder(options: ReminderOptions)` - ✅ Complete + +--- + +## Platform-Specific Considerations + +### Testing Environment + +- **Primary Testing Target:** iOS Simulator +- **Simulator Testing:** All features should be testable on iOS Simulator +- **Physical Device Testing:** Optional for final validation + +### iOS Notification Limits + +- **Maximum Pending Notifications:** 64 (system limit) +- **Maximum Daily Notifications:** ~20 (recommended) +- **Initial Scope:** One prefetch + one notification per day +- **Rolling Window Strategy:** Always arm today's notifications, arm tomorrow's if within limits (Phase 2+) + +### iOS Background Execution + +- **BGTaskScheduler Limits:** + - Background refresh tasks: ~30 seconds execution time + - Processing tasks: Variable, depends on system resources +- **Strategy:** Efficient processing, immediate next-schedule after completion + +### iOS Storage Options + +- **UserDefaults:** For simple configuration and preferences +- **CoreData:** For complex relational data (schedules, content cache) +- **File System:** For large content (images, media) + +### iOS Permission Model + +- **Notification Permissions:** Required for all notification delivery +- **Background App Refresh:** Required for background fetching +- **Strategy:** Request permissions early, provide clear explanations + +--- + +## Testing Strategy + +### Unit Tests + +- [ ] Test all new methods match Android behavior +- [ ] Test storage layer (UserDefaults and CoreData) +- [ ] Test scheduler with iOS notification limits +- [ ] Test background task execution +- [ ] Test TTL enforcement +- [ ] Test rolling window maintenance + +### Integration Tests + +- [ ] Test full notification pipeline (fetch → cache → schedule → display) +- [ ] Test offline scenarios +- [ ] Test background execution reliability +- [ ] Test reboot recovery +- [ ] Test activeDid integration + +### Manual Testing + +- [ ] Test on physical iOS devices +- [ ] Test Background App Refresh settings +- [ ] Test notification permissions +- [ ] Test battery optimization scenarios +- [ ] Test app lifecycle events + +--- + +## iOS Test App Requirements + +### UI Parity with Android + +**Objective:** Create iOS test app with identical UI/UX to Android test app, using iOS plugin implementation + +**Reference App:** `test-apps/android-test-app/` (Standalone Android with HTML/JS UI) + +**Requirements:** +1. **Same UI as Android Test App** + - Reuse exact HTML/JavaScript from `android-test-app/app/src/main/assets/public/index.html` + - Same button layout and functionality + - Same status display area + - Same visual design and styling + - Platform detection to use iOS plugin methods instead of Android + +2. **Platform Detection** + - Detect iOS platform and use iOS plugin methods + - Show iOS-specific status indicators + - Display iOS-specific permission states + - Adapt Android-specific methods to iOS equivalents (e.g., `openExactAlarmSettings` → `openNotificationSettings`) + +3. **iOS Plugin Integration** + - Use iOS `DailyNotificationPlugin` instead of Android version + - All method calls route to iOS native implementation + - Error handling adapted for iOS-specific errors + +**File Structure:** +``` +test-apps/ios-test-app/ +├── App/ +│ ├── AppDelegate.swift # App delegate with plugin setup +│ ├── Info.plist # iOS permissions and config +│ ├── SceneDelegate.swift # Scene management (if needed) +│ └── Main.storyboard # Main storyboard (if needed) +├── App.xcodeproj/ # Xcode project +├── App.xcworkspace/ # Xcode workspace (if using CocoaPods) +├── Podfile # CocoaPods dependencies +└── www/ # Web assets (HTML/JS/CSS) + ├── index.html # Same UI as android-test-app + ├── capacitor.config.json # Capacitor config + └── capacitor.plugins.json # Plugin registration +``` + +### iOS Permissions and Requirements + +**Required Permissions (Info.plist):** + +1. **Notification Permissions** + ```xml + UIBackgroundModes + + remote-notification + fetch + processing + + ``` + +2. **Background Task Identifiers** + ```xml + BGTaskSchedulerPermittedIdentifiers + + com.timesafari.dailynotification.fetch + com.timesafari.dailynotification.notify + + ``` + +3. **Usage Descriptions** + ```xml + NSUserNotificationsUsageDescription + TimeSafari needs notification permissions to deliver daily updates + ``` + +**Runtime Permission Handling:** + +1. **Notification Permissions** + - Request via `UNUserNotificationCenter.requestAuthorization()` + - Check status via `UNUserNotificationCenter.getNotificationSettings()` + - Display permission status in test app UI + - Provide "Open Settings" button if denied + +2. **Background App Refresh** + - Check status via `UIApplication.shared.backgroundRefreshStatus` + - Display status in test app UI + - Provide guidance for enabling in Settings + +3. **Permission Status Display** + - Show notification permission state (authorized/denied/not determined) + - Show background refresh state (available/restricted/denied) + - Show battery optimization status (iOS equivalent) + - Provide actionable buttons to request/enable permissions + +**iOS-Specific Requirements:** + +1. **Background Task Registration** + - Register BGTaskScheduler tasks in `AppDelegate.application(_:didFinishLaunchingWithOptions:)` + - Register handlers before app finishes launching + - Handle task expiration gracefully + +2. **Notification Categories** + - Define notification categories for actions + - Register categories with UNUserNotificationCenter + - Handle notification actions in delegate + +3. **App Lifecycle Integration** + - Handle app background/foreground events + - Reschedule notifications on app launch + - Sync state on app resume + +### Build Options + +**Objective:** Support both Xcode GUI and command-line builds with straightforward setup + +#### Xcode Build (GUI) + +**Setup:** +1. Open `test-apps/ios-test-app/App.xcworkspace` (if using CocoaPods) or `App.xcodeproj` in Xcode +2. Select target device (simulator or physical device) +3. Build and run via Xcode interface + +**Xcode Configuration:** +- **Scheme:** ios-test-app (or similar) +- **Configuration:** Debug (development) / Release (production) +- **Signing:** Automatic signing with development team +- **Capabilities:** + - Push Notifications + - Background Modes (Remote notifications, Background fetch, Background processing) + +**Xcode Build Steps:** +1. Clean build folder (Cmd+Shift+K) +2. Build project (Cmd+B) +3. Run on device/simulator (Cmd+R) +4. Attach debugger for debugging + +#### Console Build (Command Line) + +**Objective:** Enable straightforward command-line builds matching Android test app pattern + +**Build Script Pattern:** +- Follow pattern from `scripts/build-native.sh` +- Create `scripts/build-ios-test-app.sh` for iOS test app +- Support both simulator and device builds +- Include dependency installation (CocoaPods) +- Include code signing configuration + +**Build Commands (via Script):** + +1. **Build iOS Test App (Debug - Simulator)** + ```bash + ./scripts/build-ios-test-app.sh --simulator + ``` + +2. **Build iOS Test App (Debug - Device)** + ```bash + ./scripts/build-ios-test-app.sh --device + ``` + +3. **Build iOS Test App (Release)** + ```bash + ./scripts/build-ios-test-app.sh --release + ``` + +**Direct xcodebuild Commands (if needed):** + +1. **Install Dependencies** + ```bash + cd test-apps/ios-test-app + pod install # If using CocoaPods + ``` + +2. **Build iOS App (Debug - Simulator)** + ```bash + xcodebuild -workspace App.xcworkspace \ + -scheme ios-test-app \ + -configuration Debug \ + -sdk iphonesimulator \ + -destination 'platform=iOS Simulator,name=iPhone 15' \ + build + ``` + +3. **Build iOS App (Debug - Device)** + ```bash + xcodebuild -workspace App.xcworkspace \ + -scheme ios-test-app \ + -configuration Debug \ + -sdk iphoneos \ + -destination 'generic/platform=iOS' \ + build + ``` + +4. **Build iOS App (Release)** + ```bash + xcodebuild -workspace App.xcworkspace \ + -scheme ios-test-app \ + -configuration Release \ + -sdk iphoneos \ + -archivePath build/ios-test-app.xcarchive \ + archive + ``` + +**Build Script Requirements:** +- Check for required tools (xcodebuild, pod if using CocoaPods) +- Install dependencies automatically +- Support both simulator and device builds +- Provide clear error messages +- Follow same pattern as `scripts/build-native.sh` (colors, logging, error handling) + +### Debugging Strategy + +**Objective:** Make debugging easily accessible and comprehensive + +#### Console Logging + +**Structured Logging:** +1. **Log Levels** + - `DEBUG`: Detailed diagnostic information + - `INFO`: General informational messages + - `WARN`: Warning messages for potential issues + - `ERROR`: Error messages for failures + +2. **Log Format** + ``` + [DNP-PLUGIN] [LEVEL] [TIMESTAMP] [METHOD] Message + ``` + Example: + ``` + [DNP-PLUGIN] [INFO] [2025-11-13 10:30:45 UTC] [scheduleDailyNotification] Scheduling notification for 09:00 + ``` + +3. **Log Categories** + - `DNP-PLUGIN`: Main plugin operations + - `DNP-SCHEDULER`: Scheduling operations + - `DNP-FETCHER`: Background fetching + - `DNP-STORAGE`: Storage operations + - `DNP-TTL`: TTL enforcement + - `DNP-ROLLING-WINDOW`: Rolling window maintenance + +**Logging Implementation:** +- Use `os_log` for system-level logging (visible in Console.app) +- Use `print()` for Xcode console output +- Include file/line information in debug builds +- Support log level filtering + +#### Xcode Debugging + +**Breakpoints:** +1. **Strategic Breakpoints** + - Plugin method entry points + - Background task handlers + - Notification scheduling logic + - Error handling paths + +2. **Conditional Breakpoints** + - Break on specific notification IDs + - Break on error conditions + - Break on specific activeDid values + +3. **Logging Breakpoints** + - Log method entry/exit without stopping + - Log variable values + - Log call stack + +**Debugging Tools:** +1. **LLDB Commands** + - Inspect Swift objects + - Print variable values + - Execute Swift expressions + - View call stack + +2. **View Hierarchy Debugger** + - Inspect UI components + - Debug layout issues + - Verify UI state + +3. **Network Debugging** + - Monitor API calls + - Inspect request/response + - Debug authentication issues + +#### Test App Debugging UI + +**Debug Panel in Test App:** +1. **Log Viewer** + - Real-time log display + - Filter by log level + - Filter by category + - Search functionality + - Export logs to file + +2. **Status Dashboard** + - Plugin initialization status + - Permission status + - Background task status + - Notification schedule status + - Storage status + +3. **Diagnostic Tools** + - Test individual plugin methods + - View stored data (UserDefaults, CoreData) + - Trigger manual background tasks + - Force notification delivery + - Clear caches + +4. **Error Display** + - Show recent errors + - Error details and stack traces + - Error reporting functionality + +**Debug View Implementation:** +```vue + + +``` + +#### Console.app Integration + +**System Logs:** +- Use `os_log` for system-level logging +- View logs in Console.app on macOS +- Filter by subsystem: `com.timesafari.dailynotification` +- Export logs for analysis + +**Log Export:** +- Export logs from test app UI +- Export via Xcode Organizer +- Export via Console.app +- Include timestamps and log levels + +#### Background Task Debugging + +**BGTaskScheduler Debugging:** +1. **Task Registration Verification** + - Log task registration in AppDelegate + - Verify task identifiers match Info.plist + - Check task handler registration + +2. **Task Execution Monitoring** + - Log task start/completion + - Log task expiration + - Monitor task execution time + - Track task success/failure + +3. **Task Scheduling Debugging** + - Log scheduled task times + - Verify earliestBeginDate + - Check task submission success + - Monitor task cancellation + +**Debug Commands:** +```swift +// In test app or debug build +func debugBackgroundTasks() { + // List registered tasks + // Show scheduled tasks + // Trigger test tasks + // View task history +} +``` + +#### Notification Debugging + +**Notification Delivery Debugging:** +1. **Scheduled Notifications** + - List all pending notifications + - Show notification content + - Display trigger times + - Verify notification limits + +2. **Notification Delivery** + - Log notification delivery + - Track delivery success/failure + - Monitor notification actions + - Debug notification display + +3. **Permission Debugging** + - Check permission status + - Log permission requests + - Track permission changes + - Debug permission denials + +**Debug Methods:** +```swift +// Debug notification state +func debugNotifications() { + // Get pending notifications + // Get delivered notifications + // Check notification settings + // Verify notification categories +} +``` + +### Test App Implementation Checklist + +- [ ] Create `ios-test-app` directory structure (equivalent to `android-test-app`) +- [ ] Copy HTML/JS UI from `android-test-app/app/src/main/assets/public/index.html` +- [ ] Adapt JavaScript to use iOS plugin methods +- [ ] Configure Info.plist with required permissions +- [ ] Implement AppDelegate with plugin setup +- [ ] Set up Xcode project/workspace +- [ ] Configure CocoaPods (if needed) or direct dependencies +- [ ] Create build script `scripts/build-ios-test-app.sh` +- [ ] Test Xcode GUI builds +- [ ] Test command-line builds via script +- [ ] Implement comprehensive logging +- [ ] Add Console.app integration +- [ ] Create debugging documentation + +--- + +## File Organization + +### New Files to Create + +``` +ios/Plugin/ +├── DailyNotificationStorage.swift # Storage abstraction (new) +├── DailyNotificationScheduler.swift # Scheduler implementation (new) +├── DailyNotificationJWTManager.swift # JWT management (new) +├── EnhancedDailyNotificationFetcher.swift # Enhanced fetcher (new) +└── DailyNotificationRebootRecoveryManager.swift # Reboot recovery (new) +``` + +### Files to Enhance + +``` +ios/Plugin/ +├── DailyNotificationPlugin.swift # Add missing methods +├── DailyNotificationBackgroundTaskManager.swift # Enhance background tasks +├── DailyNotificationRollingWindow.swift # Enhance rolling window +├── DailyNotificationTTLEnforcer.swift # Enhance TTL enforcement +└── DailyNotificationETagManager.swift # Enhance ETag management +``` + +### Test App Files to Create + +``` +test-apps/ios-test-app/ # New iOS test app (equivalent to android-test-app) +├── App/ +│ ├── AppDelegate.swift # App delegate with plugin setup +│ ├── Info.plist # iOS permissions and config +│ ├── SceneDelegate.swift # Scene management (if needed) +│ └── Main.storyboard # Main storyboard (if needed) +├── App.xcodeproj/ # Xcode project +├── App.xcworkspace/ # Xcode workspace (if using CocoaPods) +├── Podfile # CocoaPods dependencies +└── www/ # Web assets (same as android-test-app) + ├── index.html # Same UI as android-test-app + ├── capacitor.config.json # Capacitor config + └── capacitor.plugins.json # Plugin registration +``` + +### Build Scripts to Create + +``` +scripts/ +└── build-ios-test-app.sh # iOS test app build script (new) + # Pattern: Similar to scripts/build-native.sh + # Features: + # - Check environment (xcodebuild, pod) + # - Install dependencies (pod install) + # - Build for simulator or device + # - Clear error messages and logging +``` + +--- + +## Success Criteria + +### Functional Parity + +- [ ] All Android `@PluginMethod` methods have iOS equivalents +- [ ] All methods return same data structures as Android +- [ ] All methods handle errors consistently with Android +- [ ] All methods log consistently with Android + +### Platform Adaptations + +- [ ] iOS uses appropriate iOS APIs (UNUserNotificationCenter, BGTaskScheduler) +- [ ] iOS respects iOS limits (64 notification limit, background execution limits) +- [ ] iOS provides iOS-specific features where appropriate (Background App Refresh) + +### Code Quality + +- [ ] All code follows Swift best practices +- [ ] All code is documented with file-level and method-level comments +- [ ] All code includes error handling and logging +- [ ] All code is type-safe + +### Testing + +- [ ] Unit tests cover all new methods +- [ ] Integration tests verify full pipeline +- [ ] Manual testing confirms real-world behavior + +### Test App + +- [ ] `ios-test-app` created with same UI as `android-test-app` +- [ ] Test app uses iOS plugin implementation +- [ ] All permissions properly configured in Info.plist +- [ ] Build script `build-ios-test-app.sh` created and working +- [ ] Build works via both Xcode GUI and command line +- [ ] Comprehensive logging accessible via Console.app +- [ ] Background task debugging tools available + +--- + +## Risks & Mitigations + +### Risk 1: iOS Background Execution Limitations + +**Risk:** iOS background execution is more limited than Android +**Mitigation:** +- Use efficient processing algorithms +- Schedule next task immediately after completion +- Provide clear user guidance on Background App Refresh + +### Risk 2: iOS Notification Limits + +**Risk:** iOS 64 notification limit may conflict with rolling window strategy +**Mitigation:** +- Implement smart rolling window that respects limits +- Prioritize today's notifications over tomorrow's +- Provide clear error messages when limits are reached + +### Risk 3: TypeScript Interface Compatibility + +**Risk:** iOS implementation may not match TypeScript interface exactly +**Mitigation:** +- Test all methods against TypeScript interface +- Ensure return types match exactly +- Ensure error handling matches Android behavior + +### Risk 4: Platform-Specific Behavior Differences + +**Risk:** iOS and Android may behave differently for same operations +**Mitigation:** +- Document all platform differences +- Provide platform-specific error messages where appropriate +- Test cross-platform compatibility + +--- + +## Timeline Estimate + +### Phase 1: Core Infrastructure +- Storage layer implementation +- Scheduler implementation (single daily schedule: one prefetch + one notification) + - Prefetch scheduled 5 minutes before notification time +- Background fetching enhancement (single daily prefetch, 5 minutes before notification) +- Core methods implementation +- iOS test app creation (ios-test-app) +- Build script creation (build-ios-test-app.sh) +- Testing on iOS Simulator + +**Test App Readiness:** ✅ Ready for testing after Phase 1 completion +- Basic scheduling (one prefetch 5 minutes before + one notification per day) +- Core plugin methods functional +- Testable on iOS Simulator + +### Phase 2: Advanced Features +- Rolling window enhancement (expands beyond single daily schedule) +- TTL enforcement enhancement +- Exact alarm equivalent implementation +- Reboot recovery implementation +- Power management enhancement +- Testing on iOS Simulator + +**Test App Readiness:** ✅ Ready for testing after Phase 2 completion +- Rolling window and advanced features functional +- Testable on iOS Simulator + +### Phase 3: TimeSafari Integration +- JWT management implementation +- ETag management enhancement +- Enhanced fetcher implementation +- Phase 1 methods implementation +- Testing on iOS Simulator + +**TimeSafari Integration Readiness:** ✅ Library ready for TimeSafari integration after Phase 3 completion +**Test App Readiness:** ✅ Ready for testing after Phase 3 completion +- TimeSafari integration features functional +- Testable on iOS Simulator + +### Phase 4: Background Coordination +- Background coordination implementation +- Lifecycle management implementation +- Coordination status implementation +- Testing on iOS Simulator + +**TimeSafari Integration Readiness:** ✅ Full library ready for production TimeSafari integration after Phase 4 completion +**Test App Readiness:** ✅ Ready for testing after Phase 4 completion +- Full background coordination functional +- Testable on iOS Simulator + +--- + +## Dependencies + +### External Dependencies + +- **Capacitor:** iOS plugin framework +- **UserNotifications:** iOS notification framework +- **BackgroundTasks:** iOS background execution framework +- **CoreData:** iOS data persistence framework + +### Internal Dependencies + +- **TypeScript Interface:** Must remain unchanged (`src/definitions.ts`) +- **Android Implementation:** Reference implementation (read-only) +- **Existing iOS Components:** Build upon existing Swift files + +--- + +## References + +### Android Implementation Files + +- `src/android/DailyNotificationPlugin.java` - Main plugin class +- `src/android/DailyNotificationStorage.java` - Storage layer +- `src/android/DailyNotificationScheduler.java` - Scheduler +- `src/android/DailyNotificationFetcher.java` - Background fetching +- `src/android/DailyNotificationDatabase.java` - Database management +- `src/android/DailyNotificationRollingWindow.java` - Rolling window +- `src/android/DailyNotificationExactAlarmManager.java` - Exact alarms +- `src/android/DailyNotificationRebootRecoveryManager.java` - Reboot recovery +- `src/android/DailyNotificationTTLEnforcer.java` - TTL enforcement +- `src/android/DailyNotificationETagManager.java` - ETag management +- `src/android/DailyNotificationJWTManager.java` - JWT management +- `src/android/EnhancedDailyNotificationFetcher.java` - Enhanced fetcher + +### iOS Implementation Files + +- `ios/Plugin/DailyNotificationPlugin.swift` - Main plugin class +- `ios/Plugin/DailyNotificationDatabase.swift` - Database (CoreData) +- `ios/Plugin/DailyNotificationRollingWindow.swift` - Rolling window +- `ios/Plugin/DailyNotificationTTLEnforcer.swift` - TTL enforcement +- `ios/Plugin/DailyNotificationETagManager.swift` - ETag management +- `ios/Plugin/DailyNotificationBackgroundTaskManager.swift` - Background tasks + +### TypeScript Interface + +- `src/definitions.ts` - Complete TypeScript interface definition + +### Documentation + +- `doc/implementation-roadmap.md` - Implementation roadmap +- `doc/INTEGRATION_CHECKLIST.md` - Integration checklist +- `README.md` - Project documentation + +--- + +## Competence Hooks + +### Why This Works + +- **Platform Parity:** Matching Android functionality ensures consistent user experience across platforms +- **Incremental Approach:** Phased implementation reduces risk and allows for iterative testing +- **Platform Adaptations:** Using iOS-native APIs ensures optimal performance and reliability + +### Common Pitfalls + +- **Background Execution Limits:** iOS background execution is more limited than Android - must design for efficiency +- **Notification Limits:** iOS 64 notification limit requires careful rolling window management +- **Permission Model:** iOS requires explicit permission requests - must handle gracefully + +### Next Skill Unlock + +- **iOS Background Execution:** Understanding BGTaskScheduler and background execution patterns +- **iOS Notification System:** Deep dive into UNUserNotificationCenter and notification delivery guarantees + +### Teach-Back + +**Question:** "How does iOS background execution differ from Android, and how does this affect the notification scheduling strategy?" + +**Expected Answer:** iOS background execution is more limited (30 seconds for refresh tasks) and less reliable than Android WorkManager. This requires efficient processing, immediate next-schedule after completion, and fallback strategies for when background execution fails. + +--- + +## Collaboration Hooks + +### Discussion Points + +1. **Platform Differences:** How should we handle platform-specific behavior differences in error messages and user guidance? +2. **Testing Strategy:** What level of cross-platform testing is needed to ensure parity? +3. **Performance:** How do we ensure iOS implementation performs as well as Android? + +### Review Points + +- **Code Review:** All new iOS code should be reviewed against Android implementation for functional parity +- **Architecture Review:** iOS component architecture should be reviewed for maintainability +- **Testing Review:** Test coverage should be reviewed for completeness + +### Stakeholders + +- **iOS Developer:** Primary implementer +- **Android Developer:** Reference implementation owner (consultation) +- **TypeScript Developer:** Interface maintainer (consultation) +- **QA:** Testing and validation + +--- + +## Decision Log + +### 2025-11-13: Directive Created + +**Decision:** Create comprehensive directive for iOS Android parity implementation +**Rationale:** Need clear plan for upgrading iOS while preserving Android and TypeScript interface +**Status:** ✅ Approved for implementation + +--- + +**Status:** 🎯 **READY FOR IMPLEMENTATION** +**Next Steps:** Begin Phase 1 implementation after directive approval +