Add configureNativeFetcher() plugin method to enable TypeScript configuration
of native fetchers with API credentials. This provides a cross-platform
mechanism for passing configuration from JavaScript to native code without
relying on platform-specific storage.
- Add configure() method to NativeNotificationContentFetcher interface
(optional, defaults to no-op for fetchers that don't need config)
- Add configureNativeFetcher plugin method in DailyNotificationPlugin
- Add TypeScript definitions and comprehensive JSDoc
- Create NATIVE_FETCHER_CONFIGURATION.md documentation
- Update TestNativeFetcher to use real API endpoint (10.0.2.2:3000)
- Update DemoNativeFetcher Javadoc explaining configure() is optional
- Add configureNativeFetcher() call to demo app's configurePlugin()
Enables host apps to configure native fetchers from TypeScript, keeping
the interface consistent across Android, iOS, and web platforms.
Add INTEGRATION_REFACTOR_CONTEXT.md that maps current codebase to the
Integration Point Refactor plan, including:
- Current state analysis and what needs to be created/modified
- Dependency mapping and implementation checklists
- Testing strategy and open questions
Also update AndroidManifest.xml files to register Application classes.
Add comprehensive documentation and implementation artifacts for refactoring
the plugin to use app-provided content fetchers instead of hardcoded TimeSafari
integration.
Changes:
- Add integration-point-refactor-analysis.md with complete ADR, interfaces,
migration plan, and 7-PR breakdown
- Add INTEGRATION_REFACTOR_QUICK_START.md for quick reference on new machines
- Add src/types/content-fetcher.ts with TypeScript SPI interfaces
- Add examples/native-fetcher-android.kt with Kotlin implementation skeleton
- Add examples/js-fetcher-typescript.ts with TypeScript implementation skeleton
- Add tests/fixtures/test-contract.json for golden contract testing
Architecture Decisions:
- Dual-path SPI: Native Fetcher (background) + JS Fetcher (foreground only)
- Background reliability: Native SPI only, no JS bridging in workers
- Reversibility: Legacy code behind feature flag for one minor release
- Test contract: Single JSON fixture for both fetcher paths
This provides complete specification for implementing the refactor in 7 PRs,
starting with SPI shell and progressing through background workers, deduplication,
failure policies, and finally legacy code removal.
All documentation is self-contained and ready for implementation on any machine.
Add comprehensive implementation guide for creating PlanAction claims
via hydratePlan() function pattern, following established hydrateGive()
and hydrateOffer() patterns.
Changes:
- Add hydrate-plan-implementation-guide.md with complete implementation
details, usage examples, and testing recommendations
- Link implementation guide from getting-valid-plan-ids.md Method 6
- Link implementation guide from localhost-testing-guide.md Option B
The guide provides:
- Complete hydratePlan() function implementation
- PlanActionClaim interface structure
- Helper functions (createAndSubmitPlan, editAndSubmitPlan)
- Usage examples and edge cases
- Testing recommendations and security considerations
This complements plan creation documentation by showing how to
programmatically construct valid PlanAction JWTs for POST /api/v2/claim.
Plans are created by importing JWT claims with @type: PlanAction via
POST /api/v2/claim, not through a dedicated plan creation endpoint.
Changes:
- Document POST /api/v2/claim route in localhost-testing-guide.md
- Add Method 6 (PlanAction JWT import) to getting-valid-plan-ids.md
- Update seed-test-projects.js with warnings about PlanAction JWT requirements
- Clarify that seed script cannot create plans (requires DID signing)
This reflects the actual TimeSafari API architecture where plans are
created as a side effect of importing PlanAction claims.
- Update plan handle ID format to match TimeSafari specification
- Default format: https://endorser.ch/entity/{26-char-ULID}
- ULID: 26 characters, Crockford base32 encoded
- Validates RFC 3986 URI format
- Add ULID generation functions
- generateULID() creates 26-character Crockford base32 strings
- generateValidPlanHandleId() creates full URI format IDs
- Auto-generates valid IDs for testing
- Update DEFAULT_TEST_PROJECT_IDS
- Now generates valid URI format IDs automatically
- Removes placeholder warnings (IDs are now valid format)
- Add URI validation to seed scripts
- Validates plan IDs match RFC 3986 URI format
- Error messages with format examples
- Blocks seeding with invalid formats
- Update test-user-zero.ts config
- Auto-generates valid URI format plan IDs
- Clear documentation of required format
- Note that real IDs from database should replace test IDs
- Update documentation
- Document default URI format specification
- Explain ULID structure and encoding
- Show examples of valid formats
This ensures all test project IDs match the actual TimeSafari plan
handle ID format, preventing validation errors during prefetch testing.
- Replace placeholder plan IDs with explicit warnings
- Change from test_project_X to PLACEHOLDER_ID_X
- Add validation to prevent seeding with placeholders
- Add helpful error messages with usage examples
- Add comprehensive guide for getting valid plan IDs
- Methods: Create projects, query database, check account settings
- Format examples: UUID, hash, custom formats
- Step-by-step instructions for each method
- Troubleshooting common issues
- Update test-user-zero.ts with placeholder warnings
- Clear instructions on how to get real plan IDs
- Links to documentation
- Notes about plan ID format variations
- Improve test server startup
- Warn when using placeholder IDs
- Allow plan IDs via command line argument
- Provide guidance on updating config
The previous test_project_X IDs were not valid for real TimeSafari
databases. Users must now provide actual plan handle IDs from their
TimeSafari setup, making testing more realistic and avoiding silent
failures with invalid IDs.
- Add seed-test-projects.js utility script
- Generates test project data matching API schema
- Creates projects with handleIds, jwtIds, planSummary, previousClaim
- Supports export, seed, and generate commands
- Can seed projects to localhost API server
- Add test-api-server-with-seed.js
- Standalone Express server for localhost testing
- Auto-seeds test projects on startup
- Implements /api/v2/report/plansLastUpdatedBetween endpoint
- Includes debugging endpoints (/api/test/projects, /api/test/health)
- Ready to use immediately without database setup
- Update localhost testing guide
- Add seeding instructions and examples
- Document test API server usage
- Explain how to integrate with existing API servers
This enables testing prefetch functionality even when your localhost
API has no project data. The test server can be started immediately
and provides 5 seeded test projects ready for prefetch queries.
- Add serverMode configuration to test-user-zero config
- Supports: localhost, staging, production, mock, custom
- Auto-detects platform (Android/iOS/Web) for localhost URLs
- Android emulator uses 10.0.2.2 for host machine localhost
- Add getApiServerUrl() helper function
- Returns correct URL based on serverMode and platform
- Handles Android emulator special case (10.0.2.2)
- Update TestUserZeroAPI to respect serverMode
- Checks mock mode before making network calls
- Uses getApiServerUrl() for base URL resolution
- Allows runtime URL switching via setBaseUrl()
- Add localhost testing configuration
- Configurable port and HTTPS settings
- Development mode headers support
- Create localhost testing guide
- Step-by-step setup instructions
- Platform-specific localhost addresses explained
- Quick test API server example
- Troubleshooting common issues
- Monitoring prefetch execution commands
- Update Capacitor config to use getApiServerUrl()
- Fixes breaking change from api.server removal
This enables testing prefetch functionality with a local development
API server running on localhost, perfect for development and debugging
of the 5-minute prefetch scheduling feature.
- Add null safety check to permission callback to prevent NPE
- Fix fetch time calculation bug that caused double subtraction
- scheduleFetch() now accepts pre-calculated fetchTime directly
- Calculate scheduledTime back from fetchTime for worker data
- Add structured logging (DN|FETCH_SCHEDULING) for better traceability
The permission callback was crashing with NullPointerException when
Capacitor passed a null call parameter. The prefetch scheduling had a
logic error where fetchTime was calculated twice - once in the plugin
and once in the fetcher, causing 10-minute delays instead of 5-minute.
Both issues are now fixed and verified working:
- Permission callback handles null gracefully
- Prefetch schedules correctly 5 minutes before notification
- WorkManager job fires at the correct time
- All structured logs appear in logcat
Closes prefetch scheduling investigation.
- Add comprehensive logging to scheduleBackgroundFetch method
- Log scheduledTime and currentTime for comparison
- Log calculated fetch time and delay in ms, hours, and minutes
- Log detailed timing information for future vs past fetch times
- Add fallback path logging for immediate fetch scenarios
- Add logging to scheduleDailyNotification callback
- Log scheduled notification result with content details
- Log when scheduleBackgroundFetch is called
- Add error logging when notification scheduling fails
- Add WorkManager status logging in DailyNotificationFetcher
- Log work ID when work is enqueued
- Log detailed timing information (delay_ms, delay_hours)
- Add past time detection with duration logging
- Improve immediate fetch fallback logging
- Add prefetch scheduling trace documentation
- Document complete code flow from notification to prefetch
- Include debugging checklist and log search patterns
- Add ADB commands for troubleshooting
These changes enable better debugging of prefetch scheduling issues
by providing detailed timing and execution information at every
decision point in the prefetch scheduling flow.
- Add comprehensive User Zero configuration based on TimeSafari crowd-master
- Implement stars querying API client with JWT authentication
- Create UserZeroView testing interface with mock mode toggle
- Add 5-minute fetch timing configuration for notification scheduling
- Include comprehensive documentation and TypeScript type safety
- Fix readonly array and property access issues
- Add proper ESLint suppressions for console statements
Files added:
- docs/user-zero-stars-implementation.md: Complete technical documentation
- src/config/test-user-zero.ts: User Zero configuration and API client
- src/views/UserZeroView.vue: Testing interface for stars querying
Files modified:
- capacitor.config.ts: Added TimeSafari integration configuration
- src/components/layout/AppHeader.vue: Added User Zero navigation tab
- src/router/index.ts: Added User Zero route
- src/lib/error-handling.ts: Updated type safety
Features:
- Stars querying with TimeSafari API integration
- JWT-based authentication matching crowd-master patterns
- Mock testing system for offline development
- 5-minute fetch timing before notification delivery
- Comprehensive testing interface with results display
- Type-safe implementation with proper error handling
Mark off items that are already implemented in the current codebase:
Phase 1 (Foundation):
- Status Matrix Module: Modular architecture already implemented
- Exact-Alarm Gate: DailyNotificationExactAlarmManager exists
- BootReceiver Idempotent: DailyNotificationRebootRecoveryManager exists
Phase 2 (Testing & Reliability):
- Error handling improvements: DailyNotificationErrorHandler exists
- Structured logging: Event IDs already implemented
Phase 3 (Security & Performance):
- Security hardening: PermissionManager, HTTPS enforcement exist
- Performance optimizations: Multiple optimizers exist
- Diagnostics system: Comprehensive error handling and metrics exist
Acceptance Criteria:
- Error Handling: Most items resolved via error handler
- Reliability: All items resolved via existing managers
- Security: All items resolved via existing security measures
This shows the codebase is much more advanced than the plan suggested - most architectural work is already complete!
Implementation plan hardening:
- Document force-stop limitation: system cancels alarms until next explicit launch
- Add force-stop test case: no delivery until launch, then rescheduler restores schedules
- Make Doze degradation unmistakable: fixed string badge 'Degraded (Doze)' with EVT_DOZE_FALLBACK_TAKEN
- Freeze PendingIntent flags rule as Security AC: FLAG_IMMUTABLE unless mutation required
Analysis doc clarification:
- Add closed vs force-stopped distinction: closing/swiping doesn't affect alarms, force-stopping cancels them
These edits harden edge-cases around force-stop behavior and make Doze degradation UI requirements crystal clear for QA testing.
Implementation plan upgrades:
- Add timezone & manual clock change resilience: TimeChangeReceiver with TIME_SET/TIMEZONE_CHANGED
- Codify PendingIntent flags security: FLAG_IMMUTABLE vs FLAG_MUTABLE with examples
- Add notification posting invariants: channel validation and small icon requirements
- Clarify battery optimization UX limits: no ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS prompt
- Move MAX_RESPONSE_SIZE to config: Config.NETWORK_MAX_RESPONSE_SIZE with diagnostics inclusion
- Make Room migrations testable: fallbackToDestructiveMigration(false) test requirement
- Enforce event IDs in PR checklist: CI lint script validation for Log. calls
- Make degraded mode UI unmissable: visual badge + one-tap link to exact-alarm settings
- Add channelId snapshot to diagnostics: include channelId, importance, areNotificationsEnabled()
- Add manual clock skew test case: +10m clock move without timezone change
Analysis doc correctness polish:
- Add safe Application class example: show minimal <application> without android:name
- Show minimal BOOT_COMPLETED example: remove android:priority attribute
- Tighten WAKE_LOCK guidance: revisit only if introducing foreground services
- Mirror Cordova guard in Build Config: already present (no change needed)
- Add error surfaces to Mermaid flow: annotate @PluginMethod and Use Case Handler with → Canonical Error
All changes maintain existing structure with surgical precision edits for correctness, resilience, and reviewer clarity.
Implementation plan improvements:
- Fix event name consistency: DOZE_FALLBACK → EVT_DOZE_FALLBACK_TAKEN in Test Matrix
- Lock receiver export policy as AC: only BootReceiver exported
- Handle unknown Content-Length: add streaming guard for -1 responses
- Ensure single joined error mirrors AC: validation failures return one joined message
- Add webDir echo and device idle hint to diagnostics: include webDir path and isDeviceIdleMode
- Make degradation visible in UI AC: matrix shows 'Degraded timing (Doze)' when fallback active
- Add Room migrations guard: no-op migration and fallbackToDestructiveMigration(false) test
Analysis doc improvements:
- Trim WAKE_LOCK guidance: not required unless explicitly acquiring/releasing wakelocks
- Add Boot receiver priority note: android:priority has no effect for BOOT_COMPLETED
- Fix application android:name accuracy: only set if custom Application class exists
- Mirror Cordova compat note in Build section: include only when using Cordova plugins
- Annotate Mermaid flow with canonical errors: show where canonical errors are produced
- Link Truth Table to test UI buttons: integrate with Open Channel/Exact Alarm Settings buttons
All changes maintain existing structure with surgical precision edits.
Analysis doc improvements:
- Unify runtime naming: fix tree diagram cordova.js → capacitor.js
- Make manifest receivers explicit: add exported attributes and intent filters
- Surface exact-alarm user rule: add decision rule for QA/ops reasoning
- Guard Cordova dependency: add note about Cordova shims requirement
- Add error surfacing to runtime flow: show validation and use-case error paths
- Add auto-generated note to capacitor.plugins.json section
Implementation plan improvements:
- Add diagnostics button to Phase 1 DoD
- Add Doze/Idle case to Test Matrix for false negative prevention
- Make unknown field rejection explicit acceptance criterion
- Link receivers export policy to Manifest Hygiene checklist
- Add event ID requirement to PR checklist for grep-able logs
All changes maintain existing structure with surgical precision edits.
- Add android-app-analysis.md: detailed analysis of /android/app structure and /www integration
- Add android-app-improvement-plan.md: phase-based implementation plan for architecture improvements
- Add chatgpt-analysis-guide.md: structured prompts for AI analysis of Android test app
- Update README.md: add links to new documentation files
These documents provide comprehensive guidance for understanding and improving the DailyNotification Android test app architecture.
- Add AAR Duplicate Class Issues section to BUILDING.md with step-by-step solutions
- Create dedicated docs/aar-integration-troubleshooting.md with complete troubleshooting guide
- Document project reference approach (recommended) vs AAR-only approach
- Add verification steps, prevention strategies, and best practices
- Update README.md with links to new documentation
- Resolve duplicate class issues through proper project reference configuration
Fixes AAR integration issues that caused build failures due to plugin being
included both as project reference and AAR file simultaneously.
- Remove echo() method from DailyNotificationPlugin.java
- Update Android test app to show 'Plugin is loaded and ready!' instead of echo test
- Update web test app to remove echo method call
- Update iOS test app to remove echo method call
- Update documentation to remove echo test references
- Replace echo test with simple plugin availability check
The echo test was only used for initial plugin verification and is no longer
needed since the plugin now has comprehensive notification functionality.
This simplifies the codebase and removes unnecessary test code.
- Add app-startup-recovery-solution.md with technical deep dive
- Add boot-receiver-testing-guide.md with Android 10+ fixes
- Add notification-testing-procedures.md with manual testing steps
- Add reboot-testing-procedure.md with automated testing
- Add reboot-testing-steps.md with quick reference guide
- Add testing-quick-reference.md with common scenarios
Documentation covers:
- Boot receiver implementation and Direct Boot handling
- App startup recovery as fallback mechanism
- Comprehensive testing procedures for all scenarios
- Troubleshooting guides for common issues
- Performance metrics and success criteria
- Production deployment best practices
This provides complete documentation for the notification system
including both boot receiver and app startup recovery approaches.
- Document complete process for running Android app without Android Studio
- Include step-by-step commands and troubleshooting
- Cover emulator startup, app building, installation, and launching
- Add performance optimization tips and alternative methods
- Provide copy-paste ready command sequences
- Include expected results and success indicators
This enables development and testing without Android Studio IDE.
- Document the clean, organized file structure after removing redundant files
- Show relationships between examples and documentation
- Provide usage recommendations for different user types
- Explain the logical progression from simple to complex examples
- Highlight key benefits of the clean organization
This provides a clear guide to the remaining files and their purposes.
- Add example showing DailyNotification plugin integration ONLY in Capacitor classes
- Remove all isCapacitor flags since plugin is only used on Capacitor platforms
- Show actual changes needed to existing TimeSafari PWA CapacitorPlatformService
- Include activeDid change handling and plugin reconfiguration
- Provide clean summary of exact code changes needed
- Focus on Capacitor-specific implementation without platform detection
This gives a cleaner integration approach where plugin code only touches
Capacitor classes and doesn't need platform detection flags.
- Add example showing how CapacitorPlatformService handles activeDid changes
- Show integration with existing TimeSafari PWA activeDid change detection system
- Demonstrate plugin reconfiguration when user switches identities
- Include change listener system and settings synchronization
- Add comprehensive guide explaining activeDid change flow
- Show how to extend existing updateActiveDid method for plugin integration
This ensures the DailyNotification plugin automatically adapts to activeDid
changes while maintaining existing TimeSafari PWA patterns.
- Add example showing exact changes to existing TimeSafari PWA CapacitorPlatformService
- Show how to extend the existing class rather than creating a new one
- Provide summary of actual code changes needed (imports, properties, methods)
- Include modifications to PlatformServiceMixin and Vue components
- Show how to integrate with existing database and settings patterns
- Provide migration strategy for gradual adoption
This gives an accurate representation of the changes needed to the actual
TimeSafari PWA codebase rather than creating a separate class.
- Add comprehensive example showing DailyNotification plugin integration with existing TimeSafari PWA architecture
- Show how to extend CapacitorPlatformService and PlatformServiceMixin patterns
- Provide Vue.js component integration with existing TimeSafari patterns
- Include settings management, database operations, and platform detection
- Add migration strategy and testing approach for gradual adoption
- Show how to maintain existing interfaces while adding plugin features
This demonstrates how the plugin integrates with the actual TimeSafari PWA
CapacitorPlatformService and PlatformServiceMixin architecture patterns.
- Add comprehensive guide explaining when to use the plugin with Capacitor
- Clarify that plugin is only needed for Capacitor-based mobile apps
- Provide platform detection and conditional loading examples
- Add decision flowchart and matrix for easy understanding
- Include integration checklist and common mistakes to avoid
- Show how to check if Capacitor is installed and configured
This clarifies that the plugin is only needed when TimeSafari PWA uses Capacitor
for mobile app development, not for web-only PWAs.
- Add detailed explanation of DailyNotification setup example
- Break down each component and configuration option
- Explain how plugin integrates with existing TimeSafari PWA code
- Add visual architecture diagrams showing data flow and method comparison
- Include migration path and benefits diagrams
- Provide common questions and troubleshooting guidance
This provides complete understanding of how the plugin works and integrates
with existing TimeSafari PWA request patterns.
- Add comprehensive setup guide showing exact configuration for TimeSafari PWA
- Provide step-by-step instructions for integrating with existing loadNewStarredProjectChanges()
- Include complete working example with all configuration options
- Show Vue.js component integration patterns
- Add troubleshooting and testing guidance
- Demonstrate how to maintain existing interfaces while adding plugin features
This provides a practical, copy-paste ready setup for TimeSafari PWA integration.
- Add comprehensive guide for adopting existing TimeSafari PWA request patterns
- Show direct integration of loadNewStarredProjectChanges() and getStarredProjectsWithChanges()
- Provide Vue.js component integration examples
- Include migration strategy and testing approach
- Add practical example showing exact configuration needed
- Demonstrate parallel testing and performance comparison
- Show how to maintain existing TimeSafari interfaces while adding plugin features
This enables seamless adoption of the plugin into existing TimeSafari PWA codebase
while maintaining the same developer experience and user interface.
- Add detailed host request configuration guide with examples
- Add quick reference guide for common configurations
- Include TimeSafari-specific configuration patterns
- Add platform-specific configuration examples (Android, iOS, Electron)
- Include security, authentication, and observability configurations
- Add troubleshooting and debugging guidance
- Provide Vue.js integration examples
These guides show how the TimeSafari PWA host should configure
HTTP requests and network settings for the Daily Notification Plugin.
- Add detailed deployment guide for SSH git deployment
- Add deployment summary with key information and commands
- Add deployment checklist for pre/post deployment verification
- Include SSH git path and repository information
- Add integration instructions for TimeSafari PWA
- Add troubleshooting and maintenance guidance
- Add rollback plan and emergency procedures
SSH Git Path: ssh://git@173.199.124.46:222/trent_larson/daily-notification-plugin.git
Version: 2.2.0 - Production Ready
- Replace 5 separate research documents with single consolidated file
- Eliminate document duplication and overlapping information
- Move documentation from 'docs/' to 'doc/' folder
- Maintain all essential research findings and implementation details
- Improve maintainability with single source of truth
- Follow responsible documentation principles
Resolves: Document multiplication and organization issues
- Add consistent blank lines between sections for better readability
- Clean up formatting for improved document structure
- Maintain all content while improving visual organization
- Create README for research branch with document overview
- Provide index of all research documents and their purposes
- Include key findings and implementation recommendations
- Add technical architecture overview and next steps
- Document security, performance, and testing requirements
- Provide contact information and status updates
Resolves: Complete research documentation overview and navigation
- Create executive summary of research findings
- Document detailed requirements analysis and gap assessment
- Include proposed architecture and implementation strategy
- Add realistic time estimation with detailed effort breakdown
- Include complexity assessment and risk analysis
- Provide next steps and implementation recommendations
- Document security, performance, and testing requirements
Resolves: Complete research documentation for callback system enhancement
- Add consistent blank lines between sections for better readability
- Clean up formatting for improved document structure
- Maintain all content while improving visual organization
- Create detailed implementation plan with task breakdown
- Include realistic time estimates for each phase
- Add technical implementation details and code examples
- Include testing strategy and success criteria
- Add risk mitigation strategies and timeline
- Provide immediate next steps and action items
Resolves: Implementation planning for callback system and dual scheduling
- Create detailed analysis of callback system requirements
- Document dual scheduling method architecture (content fetch vs user notification)
- Include implementation approach with realistic time estimates
- Add complexity assessment and risk analysis
- Provide technical considerations and security guidelines
- Include testing strategy and performance impact analysis
- Document design patterns and platform-specific resources
Resolves: User feedback on callback system and dual scheduling needs
- Add comprehensive analysis of new callback and API integration requirements
- Include dual scheduling method requirements (content fetch vs user notification)
- Conform to realistic time estimation standards with proper phase breakdown
- Add complexity assessment and milestone definitions
- Include technical considerations and risk mitigation strategies
- Update status to research & analysis phase
- Estimated completion: 3-5 days for full implementation
Resolves: User feedback on callback system and dual scheduling needs
- Mark test suite as 100% complete (58/58 tests passing)
- Update project status to 90% complete
- Mark immediate priority items as completed
- Add next phase roadmap for iOS enhancement and web implementation
- Update success metrics and risk assessment
- Reflect readiness for next development phase
Matthew Raymer
Matthew Raymer