# Daily Notification Plugin **Author**: Matthew Raymer **Version**: 2.0.0 **Created**: 2025-09-22 09:22:32 UTC **Last Updated**: 2025-09-22 09:22:32 UTC ## Overview The Daily Notification Plugin is a comprehensive Capacitor plugin that provides enterprise-grade daily notification functionality across Android, iOS, and Web platforms. It features dual scheduling, callback support, TTL-at-fire logic, and comprehensive observability. ## Features ### 🚀 **Core Features** - **Dual Scheduling**: Separate content fetch and user notification scheduling - **TTL-at-Fire Logic**: Content validity checking at notification time - **Callback System**: HTTP, local, and queue callback support - **Circuit Breaker Pattern**: Automatic failure detection and recovery - **Cross-Platform**: Android, iOS, and Web implementations ### 📱 **Platform Support** - **Android**: WorkManager + AlarmManager + SQLite (Room) - **iOS**: BGTaskScheduler + UNUserNotificationCenter + Core Data - **Web**: Service Worker + IndexedDB + Push Notifications ### 🔧 **Enterprise Features** - **Observability**: Structured logging with event codes - **Health Monitoring**: Comprehensive status and performance metrics - **Error Handling**: Exponential backoff and retry logic - **Security**: Encrypted storage and secure callback handling ## Installation ```bash npm install @timesafari/daily-notification-plugin ``` ## Quick Start ### Basic Usage ```typescript import { DailyNotification } from '@timesafari/daily-notification-plugin'; // Schedule a daily notification await DailyNotification.scheduleDailyNotification({ title: 'Daily Update', body: 'Your daily content is ready', schedule: '0 9 * * *' // 9 AM daily }); ``` ### Enhanced Usage (Recommended) ```typescript import { DailyNotification, DualScheduleConfiguration } from '@timesafari/daily-notification-plugin'; // Configure dual scheduling const config: DualScheduleConfiguration = { contentFetch: { schedule: '0 8 * * *', // Fetch at 8 AM ttlSeconds: 3600, // 1 hour TTL source: 'api', url: 'https://api.example.com/daily-content' }, userNotification: { schedule: '0 9 * * *', // Notify at 9 AM title: 'Daily Update', body: 'Your daily content is ready', actions: [ { id: 'view', title: 'View' }, { id: 'dismiss', title: 'Dismiss' } ] } }; await DailyNotification.scheduleDualNotification(config); ``` ### Callback Integration ```typescript // Register analytics callback await DailyNotification.registerCallback('analytics', { kind: 'http', target: 'https://analytics.example.com/events', headers: { 'Authorization': 'Bearer your-token', 'Content-Type': 'application/json' } }); // Register local callback await DailyNotification.registerCallback('database', { kind: 'local', target: 'saveToDatabase' }); function saveToDatabase(event: CallbackEvent) { console.log('Saving to database:', event); // Your database save logic here } ``` ## API Reference ### Core Methods #### `scheduleDailyNotification(options)` Schedule a basic daily notification (backward compatible). ```typescript await DailyNotification.scheduleDailyNotification({ title: string; body: string; schedule: string; // Cron expression actions?: NotificationAction[]; }); ``` #### `scheduleContentFetch(config)` Schedule content fetching separately. ```typescript await DailyNotification.scheduleContentFetch({ schedule: string; // Cron expression ttlSeconds: number; // Time-to-live in seconds source: string; // Content source identifier url?: string; // API endpoint URL headers?: Record; }); ``` #### `scheduleUserNotification(config)` Schedule user notifications separately. ```typescript await DailyNotification.scheduleUserNotification({ schedule: string; // Cron expression title: string; // Notification title body: string; // Notification body actions?: NotificationAction[]; }); ``` #### `scheduleDualNotification(config)` Schedule both content fetch and user notification. ```typescript await DailyNotification.scheduleDualNotification({ contentFetch: ContentFetchConfig; userNotification: UserNotificationConfig; }); ``` ### Callback Methods #### `registerCallback(name, config)` Register a callback function. ```typescript await DailyNotification.registerCallback('callback-name', { kind: 'http' | 'local' | 'queue'; target: string; // URL or function name headers?: Record; }); ``` #### `unregisterCallback(name)` Remove a registered callback. ```typescript await DailyNotification.unregisterCallback('callback-name'); ``` #### `getRegisteredCallbacks()` Get list of registered callbacks. ```typescript const callbacks = await DailyNotification.getRegisteredCallbacks(); // Returns: string[] ``` ### Status Methods #### `getDualScheduleStatus()` Get comprehensive status information. ```typescript const status = await DailyNotification.getDualScheduleStatus(); // Returns: { // nextRuns: number[]; // lastOutcomes: string[]; // cacheAgeMs: number | null; // staleArmed: boolean; // queueDepth: number; // circuitBreakers: CircuitBreakerStatus; // performance: PerformanceMetrics; // } ``` ## Platform Requirements ### Android - **Minimum SDK**: API 21 (Android 5.0) - **Target SDK**: API 34 (Android 14) - **Permissions**: `POST_NOTIFICATIONS`, `SCHEDULE_EXACT_ALARM`, `USE_EXACT_ALARM` - **Dependencies**: Room 2.6.1+, WorkManager 2.9.0+ ### iOS - **Minimum Version**: iOS 13.0 - **Background Modes**: Background App Refresh, Background Processing - **Permissions**: Notification permissions required - **Dependencies**: Core Data, BGTaskScheduler ### Web - **Service Worker**: Required for background functionality - **HTTPS**: Required for Service Worker and push notifications - **Browser Support**: Chrome 40+, Firefox 44+, Safari 11.1+ ## Configuration ### Android Configuration #### AndroidManifest.xml ```xml ``` #### build.gradle ```gradle dependencies { implementation "androidx.room:room-runtime:2.6.1" implementation "androidx.work:work-runtime-ktx:2.9.0" implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3" annotationProcessor "androidx.room:room-compiler:2.6.1" } ``` ### iOS Configuration #### Info.plist ```xml UIBackgroundModes background-app-refresh background-processing BGTaskSchedulerPermittedIdentifiers com.timesafari.dailynotification.content-fetch com.timesafari.dailynotification.notification-delivery ``` #### Capabilities 1. Enable "Background Modes" capability 2. Enable "Background App Refresh" 3. Enable "Background Processing" ### Web Configuration #### Service Worker Registration ```typescript if ('serviceWorker' in navigator) { navigator.serviceWorker.register('/sw.js') .then(registration => { console.log('Service Worker registered:', registration); }) .catch(error => { console.error('Service Worker registration failed:', error); }); } ``` #### Push Notification Setup ```typescript const permission = await Notification.requestPermission(); if (permission === 'granted') { const subscription = await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: 'your-vapid-public-key' }); await fetch('/api/push-subscription', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(subscription) }); } ``` ## Testing ### Unit Tests ```bash npm test ``` ### Integration Tests ```typescript import { DailyNotification } from '@timesafari/daily-notification-plugin'; describe('Integration Tests', () => { test('dual scheduling workflow', async () => { const config = { contentFetch: { schedule: '0 8 * * *', ttlSeconds: 3600 }, userNotification: { schedule: '0 9 * * *', title: 'Test' } }; await DailyNotification.scheduleDualNotification(config); const status = await DailyNotification.getDualScheduleStatus(); expect(status.nextRuns.length).toBe(2); }); }); ``` ## Enterprise Integration ### Analytics Integration ```typescript // Google Analytics 4 const ga4Callback = new GoogleAnalyticsCallback('G-XXXXXXXXXX', 'your-api-secret'); await ga4Callback.register(); // Mixpanel const mixpanelCallback = new MixpanelCallback('your-project-token'); await mixpanelCallback.register(); ``` ### CRM Integration ```typescript // Salesforce const salesforceCallback = new SalesforceCallback('your-access-token', 'your-instance-url'); await salesforceCallback.register(); // HubSpot const hubspotCallback = new HubSpotCallback('your-api-key'); await hubspotCallback.register(); ``` ### Monitoring Integration ```typescript // Datadog const datadogCallback = new DatadogCallback('your-api-key', 'your-app-key'); await datadogCallback.register(); // New Relic const newrelicCallback = new NewRelicCallback('your-license-key'); await newrelicCallback.register(); ``` ## Troubleshooting ### Common Issues #### Android - **Permission Denied**: Ensure all required permissions are declared - **WorkManager Not Running**: Check battery optimization settings - **Database Errors**: Verify Room database schema migration #### iOS - **Background Tasks Not Running**: Check Background App Refresh settings - **Core Data Errors**: Verify Core Data model compatibility - **Notification Permissions**: Request notification permissions #### Web - **Service Worker Not Registering**: Ensure HTTPS and proper file paths - **Push Notifications Not Working**: Verify VAPID keys and server setup - **IndexedDB Errors**: Check browser compatibility and storage quotas ### Debug Commands ```typescript // Get comprehensive status const status = await DailyNotification.getDualScheduleStatus(); console.log('Status:', status); // Check registered callbacks const callbacks = await DailyNotification.getRegisteredCallbacks(); console.log('Callbacks:', callbacks); ``` ## Performance Considerations ### Memory Usage - **Android**: Room database with connection pooling - **iOS**: Core Data with lightweight contexts - **Web**: IndexedDB with efficient indexing ### Battery Optimization - **Android**: WorkManager with battery-aware constraints - **iOS**: BGTaskScheduler with system-managed execution - **Web**: Service Worker with efficient background sync ### Network Usage - **Circuit Breaker**: Prevents excessive retry attempts - **TTL-at-Fire**: Reduces unnecessary network calls - **Exponential Backoff**: Intelligent retry scheduling ## Security Considerations ### Permissions - **Minimal Permissions**: Only request necessary permissions - **Runtime Checks**: Verify permissions before operations - **Graceful Degradation**: Handle permission denials gracefully ### Data Protection - **Local Storage**: Encrypted local storage on all platforms - **Network Security**: HTTPS-only for all network operations - **Callback Security**: Validate callback URLs and headers ### Privacy - **No Personal Data**: Plugin doesn't collect personal information - **Local Processing**: All processing happens locally - **User Control**: Users can disable notifications and callbacks ## Contributing ### Development Setup ```bash git clone https://github.com/timesafari/daily-notification-plugin.git cd daily-notification-plugin npm install npm run build npm test ``` ### Code Standards - **TypeScript**: Strict type checking enabled - **ESLint**: Code quality and consistency - **Prettier**: Code formatting - **Jest**: Comprehensive testing ### Pull Request Process 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests for new functionality 5. Ensure all tests pass 6. Submit a pull request ## License MIT License - see [LICENSE](LICENSE) file for details. ## Support ### Documentation - **API Reference**: Complete TypeScript definitions - **Migration Guide**: [doc/migration-guide.md](doc/migration-guide.md) - **Enterprise Examples**: [doc/enterprise-callback-examples.md](doc/enterprise-callback-examples.md) ### Community - **GitHub Issues**: Report bugs and request features - **Discussions**: Ask questions and share solutions - **Contributing**: Submit pull requests and improvements ### Enterprise Support - **Custom Implementations**: Tailored solutions for enterprise needs - **Integration Support**: Help with complex integrations - **Performance Optimization**: Custom performance tuning --- **Version**: 2.0.0 **Last Updated**: 2025-09-22 09:22:32 UTC **Author**: Matthew Raymer