diff --git a/doc/BACKGROUND_DATA_FETCHING_PLAN.md b/doc/BACKGROUND_DATA_FETCHING_PLAN.md index 758301f..3ca15aa 100644 --- a/doc/BACKGROUND_DATA_FETCHING_PLAN.md +++ b/doc/BACKGROUND_DATA_FETCHING_PLAN.md @@ -3,7 +3,7 @@ **Author**: Matthew Raymer **Version**: 1.0.0 **Created**: 2025-10-02 07:47:04 UTC -**Last Updated**: 2025-10-02 10:45:00 UTC +**Last Updated**: 2025-10-02 11:30:00 UTC ## Overview @@ -258,64 +258,81 @@ Based on TimeSafari's optimization patterns: #### **Database Integration Patterns** -**Android/Electron: Plugin-Managed SQLite** +**Android/Electron: Hybrid activeDid Approach** ```typescript -// Plugin handles database operations directly -await plugin.configure({ - dbPath: 'daily_notifications.db', - storage: 'shared' +// TimeSafari integration with hybrid activeDid management +await plugin.configureDatabase({ + platform: 'android', + storageType: 'hybrid', + hostDbPath: 'timesafari.sqlite' // Access TimeSafari's active_identity }); -// Plugin provides database access methods -const results = await plugin.executeContentFetch(config); -await plugin.cacheContentData(results); +// Host provides current activeDid +const activeIdentity = await this.$getActiveIdentity(); +await plugin.setActiveDidFromHost(activeIdentity.activeDid); + +// Enable automatic background lookup +await plugin.enableAutoActiveDidMode(); -// Host application accesses cached data via plugin -const cachedData = await plugin.getContentCache(); +// Plugin can fetch content and cache independently +const results = await plugin.executeContentFetch(config); ``` -**Web: Host-Managed Database** +**Web: Host-Managed Database with Hybrid activeDid** ```typescript // Host application manages absurd-sql database -import { openDatabase } from 'absurd-sql'; - -const db = await openDatabase('daily_notifications.db'); +await plugin.configureDatabase({ + platform: 'web', + storageType: 'hybrid' +}); -// Plugin provides SQL queries, host executes them -const query = await plugin.getContentFetchQuery(apiEndpoint, credentials); -const results = await db.exec(query); +// Host provides activeDid (plugin doesn't access web database) +const activeIdentity = await this.$getActiveIdentity(); +await plugin.setActiveDidFromHost(activeIdentity.activeDid); -// Plugin receives results for processing -await plugin.processContentData(results); +// Plugin delegates SQL operations to host +const query = await plugin.getContentFetchQuery(apiEndpoint, activeDid); +const results = await hostDatabase.exec(query); ``` -**iOS: Hybrid Approach** +**iOS: Hybrid Approach with Active Identity Access** ```typescript -// Plugin manages Core Data operations on background thread -await plugin.scheduleContentFetch(config); +// Plugin manages Core Data + reads TimeSafari's active_identity +await plugin.configureDatabase({ + platform: 'ios', + storageType: 'hybrid', + hostDbPath: 'timesafari.sqlite' +}); + +// Host provides activeDid initially +const activeIdentity = await this.$getActiveIdentity(); +await plugin.setActiveDidFromHost(activeIdentity.activeDid); -// Host application accesses stored data via plugin APIs -const notificationData = await plugin.getLastNotification(); -const cachedContent = await plugin.getContentHistory(); +// Plugin can refresh activeDid in background tasks +await plugin.enableAutoActiveDidMode(); ``` #### **New Plugin Methods Required** ```typescript interface EnhancedDailyNotificationPlugin { - // Database configuration + // Database configuration - Platform-aware based on TimeSafari integration configureDatabase(options: { - storageType: 'plugin-managed' | 'host-managed'; + platform: 'android' | 'ios' | 'web' | 'electron'; + storageType: 'plugin-managed' | 'host-managed' | 'hybrid'; dbPath?: string; encryption?: boolean; + hostDbPath?: string; // Path to TimeSafari's active_identity database }): Promise; + // Hybrid activeDid Management (Option 3 Implementation) + setActiveDidFromHost(activeDid: string): Promise; + refreshActiveDidFromDatabase(): Promise; + enableAutoActiveDidMode(): Promise; + // Content fetch with database integration fetchAndStoreContent(config: ContentFetchConfig): Promise; - // Credential management - simplified to activeDid only - setActiveDid(activeDid: string): Promise; - // Data access for host application getStoredContent(query: string, params?: any[]): Promise; clearStoredContent(options?: { olderThan?: number }): Promise; @@ -324,14 +341,22 @@ interface EnhancedDailyNotificationPlugin { getBackgroundTaskStatus(): Promise; pauseBackgroundTasks(): Promise; resumeBackgroundTasks(): Promise; + + // TimeSafari Integration Methods + initializeFromTimeSafari(): Promise; + listenForActiveDidChanges(): Promise; } ``` -### Background Scheduling +### Background Scheduling with Hybrid activeDid Management - **Integrate** with existing WorkManager/BGTaskScheduler - **Coordinate** API fetch timing with notification schedules - **Handle** app lifecycle events (background/foreground) +- **Implement** dual-mode activeDid access: + - **Foreground**: Host provides activeDid via `setActiveDidFromHost()` + - **Background**: Plugin looks up activeDid via `refreshActiveDidFromDatabase()` +- **Coordinate** with TimeSafari's PlatformServiceMixin for identity changes ## Migration & Testing Strategy @@ -342,12 +367,17 @@ interface EnhancedDailyNotificationPlugin { 3. **Phase 3**: Integrate with notification scheduling 4. **Phase 4**: Add passkey authentication support -### Testing Approach +### Testing Approach with Hybrid activeDid Management -- **Unit tests** for JWT generation and HTTP clients -- **Integration tests** for API endpoint interactions +- **Unit tests** for JWT generation and HTTP clients with activeDid +- **Integration tests** for API endpoint interactions using TimeSafari active_identity patterns +- **Hybrid activeDid testing**: + - Test `setActiveDidFromHost()` with TimeSafari PlatformServiceMixin + - Test `refreshActiveDidFromDatabase()` with background tasks + - Test `enableAutoActiveDidMode()` for automatic synchronization - **Background testing** on real devices (doze mode, app backgrounding) -- **Authentication testing** with actual DID credentials +- **Authentication testing** with actual DID credentials from TimeSafari active_identity table +- **Cross-platform testing** for Android/Electron (SQLite access) vs Web (host delegation) patterns ## API Endpoints to Support @@ -448,16 +478,18 @@ GET {apiServer}/api/v2/report/offersToPlansOwnedByMe?afterId={jwtId}&beforeId={j - Create plugin configuration interfaces - Set up basic error handling -### Phase 2: Authentication & API Integration (Weeks 3-4) +### Phase 2: Hybrid activeDid Integration & API Access (Weeks 3-4) -- Implement DID-based authentication -- Integrate API endpoint calls +- Implement hybrid activeDid management (Option 3 approach) +- Add `setActiveDidFromHost()` and `refreshActiveDidFromDatabase()` methods +- Implement TimeSafari active_identity table access +- Integrate API endpoint calls with activeDid-based authentication - Add response parsing and validation - Implement platform-specific database integration: - - **Android/Electron**: Direct @capacitor-community/sqlite integration - - **Web**: Plugin delegation pattern with absurd-sql coordination - - **iOS**: Core Data background thread integration -- Implement simplified activeDid-based authentication and API calls + - **Android/Electron**: Direct @capacitor-community/sqlite integration with active_identity access + - **Web**: Plugin delegation pattern with host-provided activeDid + - **iOS**: Core Data background thread integration with TimeSafari database access +- Add `enableAutoActiveDidMode()` for automatic identity synchronization ### Phase 3: Background Integration (Weeks 5-6) @@ -502,7 +534,12 @@ GET {apiServer}/api/v2/report/offersToPlansOwnedByMe?afterId={jwtId}&beforeId={j --- -**Status**: Enhanced planning document - Ready for implementation +**Status**: Hybrid activeDid implementation plan - Ready for implementation **Next Steps**: Begin Phase 1 implementation with Android HTTP client setup -**Dependencies**: Android Studio, Xcode, Capacitor CLI, existing plugin infrastructure, @capacitor-community/sqlite, @simplewebauthn packages -**Enhanced Features**: DID authentication, batch processing, structured logging, cross-platform storage optimization +**Dependencies**: Android Studio, Xcode, Capacitor CLI, existing plugin infrastructure, @capacitor-community/sqlite, TimeSafari active_identity table access +**Hybrid Features**: +- **Option 3 Implementation**: Dual-mode activeDid access (host-provided + background lookup) +- **TimeSafari Integration**: PlatformServiceMixin coordination and active_identity table access +- **Cross-Platform**: Android/Electron SQLite access, Web host delegation, iOS Core Data hybrid +- **Authentication**: DID-based JWT with activeDid from TimeSafari's identity system +- **Background Tasks**: Automatic activeDid synchronization across app lifecycle states