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

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/usage.ts
• Phase-by-Phase: examples/phase1-*.ts, examples/phase2-*.ts, examples/phase3-*.ts
• Advanced Scenarios: examples/advanced-usage.ts
• Enterprise Features: examples/enterprise-usage.ts