daily-notification-plugin/USAGE.md

Daily Notification Plugin - Usage Guide

Quick Start

import { DailyNotification } from '@timesafari/daily-notification-plugin';

// 1. Configure the plugin
await DailyNotification.configure({
  storage: 'shared',           // Use shared SQLite database
  ttlSeconds: 1800,           // 30 minutes TTL
  prefetchLeadMinutes: 15     // Prefetch 15 minutes before delivery
});

// 2. Schedule a notification
await DailyNotification.scheduleDailyNotification({
  url: 'https://api.example.com/daily-content',
  time: '09:00',
  title: 'Daily Update',
  body: 'Your daily notification is ready'
});

Configuration Options

Storage Mode

• 'shared' (Recommended): Uses shared SQLite database with WAL mode
• 'tiered' (Legacy): Uses SharedPreferences/UserDefaults + in-memory cache

TTL Settings

• ttlSeconds: Maximum age of content at delivery time (default: 1800 = 30 minutes)
• prefetchLeadMinutes: How early to prefetch content (default: 15 minutes)

Performance Optimization

• enableETagSupport: Use conditional requests for bandwidth savings
• enableErrorHandling: Advanced retry logic with exponential backoff
• enablePerformanceOptimization: Database indexes, memory management, object pooling

Static Daily Reminders

For simple daily reminders that don't require network content or content caching:

Basic Usage

// Schedule a simple daily reminder
await DailyNotification.scheduleDailyReminder({
  id: 'morning_checkin',
  title: 'Good Morning!',
  body: 'Time to check your TimeSafari community updates',
  time: '09:00'  // HH:mm format
});

Advanced Configuration

// Schedule a customized reminder
await DailyNotification.scheduleDailyReminder({
  id: 'evening_reflection',
  title: 'Evening Reflection',
  body: 'Take a moment to reflect on your day',
  time: '20:00',
  sound: true,
  vibration: true,
  priority: 'high',
  repeatDaily: true,
  timezone: 'America/New_York'
});

Reminder Management

// Get all scheduled reminders
const result = await DailyNotification.getScheduledReminders();
console.log('Scheduled reminders:', result.reminders);

// Update an existing reminder
await DailyNotification.updateDailyReminder('morning_checkin', {
  title: 'Updated Morning Check-in',
  time: '08:30',
  priority: 'high'
});

// Cancel a specific reminder
await DailyNotification.cancelDailyReminder('evening_reflection');

Key Benefits

• ✅ No Network Required: Works completely offline
• ✅ No Content Cache: Direct notification display without caching
• ✅ Simple API: Easy-to-use methods for basic reminder functionality
• ✅ Persistent: Survives app restarts and device reboots
• ✅ Cross-Platform: Consistent behavior across Android, iOS, and Web

Time Format

Use 24-hour format with leading zeros:

• ✅ Valid: "09:00", "12:30", "23:59"
• ❌ Invalid: "9:00", "24:00", "12:60"

Platform-Specific Features

Android

// Check exact alarm status
const alarmStatus = await DailyNotification.getExactAlarmStatus();
if (!alarmStatus.canSchedule) {
  // Request permission or use windowed fallback
  await DailyNotification.requestExactAlarmPermission();
}

// Check reboot recovery status
const recoveryStatus = await DailyNotification.getRebootRecoveryStatus();
if (recoveryStatus.recoveryNeeded) {
  console.log('System may have rebooted - notifications restored');
}

iOS

// Background tasks are automatically handled
// The plugin uses BGTaskScheduler for T–lead prefetch
// No additional configuration needed

Advanced Usage

Error Handling

// Configure retry behavior
await DailyNotification.configure({
  maxRetries: 3,
  baseRetryDelay: 1000,      // 1 second
  maxRetryDelay: 30000,      // 30 seconds
  backoffMultiplier: 2.0
});

// Monitor error metrics
const errorMetrics = await DailyNotification.getErrorMetrics();
console.log(`Network errors: ${errorMetrics.networkErrors}`);
console.log(`Cache hit ratio: ${errorMetrics.cacheHitRatio}`);

Performance Monitoring

// Get performance metrics
const metrics = await DailyNotification.getPerformanceMetrics();
console.log(`Performance score: ${metrics.overallScore}/100`);
console.log(`Memory usage: ${metrics.averageMemoryUsage}MB`);

// Optimize if needed
if (metrics.overallScore < 70) {
  await DailyNotification.optimizeMemory();
  await DailyNotification.optimizeDatabase();
}

Rolling Window Management

// Manual maintenance
await DailyNotification.maintainRollingWindow();

// Check status
const windowStats = await DailyNotification.getRollingWindowStats();
console.log(`Maintenance needed: ${windowStats.maintenanceNeeded}`);
console.log(`Time until next: ${windowStats.timeUntilNextMaintenance}ms`);

Production Configuration

// Recommended production settings
await DailyNotification.configure({
  storage: 'shared',
  ttlSeconds: 1800,
  prefetchLeadMinutes: 15,
  enableETagSupport: true,
  enableErrorHandling: true,
  enablePerformanceOptimization: true,
  memoryWarningThreshold: 50,    // MB
  memoryCriticalThreshold: 100,  // MB
  objectPoolSize: 20,
  maxObjectPoolSize: 100
});

Troubleshooting

Common Issues

1. Notifications not firing

   • Check exact alarm permissions on Android
   • Verify TTL settings aren't too restrictive
   • Ensure rolling window is maintained

2. High memory usage

   • Enable performance optimization
   • Check memory thresholds
   • Monitor object pool efficiency

3. Network efficiency

   • Enable ETag support
   • Monitor cache hit ratios
   • Check error retry patterns

Debug Information

// Get comprehensive debug info
const debugInfo = await DailyNotification.getDebugInfo();
console.log('Plugin Status:', debugInfo.status);
console.log('Configuration:', debugInfo.configuration);
console.log('Recent Errors:', debugInfo.recentErrors);

Migration from Legacy Storage

// The plugin automatically migrates from tiered to shared storage
// No manual migration needed - just configure with storage: 'shared'
await DailyNotification.configure({
  storage: 'shared'  // Triggers automatic migration
});

Best Practices

1. Always configure before scheduling - Set up storage, TTL, and optimization features
2. Monitor performance metrics - Use built-in monitoring to optimize settings
3. Handle errors gracefully - Implement retry logic and fallback mechanisms
4. Test on both platforms - Android and iOS have different capabilities and limitations
5. Use production settings - Enable all optimization features for production use

API Reference

See src/definitions.ts for complete TypeScript interface definitions.

Examples

• Basic Usage: examples/hello-poll.ts
• Stale Data UX: examples/stale-data-ux.ts
• Enterprise Features: See INTEGRATION_GUIDE.md for enterprise integration patterns