daily-notification-plugin/examples/phase2-1-ios-background-tasks.ts

/**
 * Phase 2.1 iOS Background Tasks Usage Example
 * 
 * Demonstrates iOS background task functionality
 * Shows T–lead prefetch with BGTaskScheduler integration
 * 
 * @author Matthew Raymer
 * @version 1.0.0
 */

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

/**
 * Example: Configure iOS background tasks
 */
async function configureIOSBackgroundTasks() {
  try {
    console.log('Configuring iOS background tasks...');
    
    // Configure with background task settings
    await DailyNotification.configure({
      storage: 'shared',
      ttlSeconds: 1800, // 30 minutes TTL
      prefetchLeadMinutes: 15, // T–lead prefetch 15 minutes before
      maxNotificationsPerDay: 20 // iOS limit
    });
    
    console.log('✅ iOS background tasks configured');
    
    // The plugin will now:
    // - Register BGTaskScheduler tasks
    // - Schedule T–lead prefetch automatically
    // - Handle background execution constraints
    // - Respect ETag/304 caching
    
  } catch (error) {
    console.error('❌ iOS background task configuration failed:', error);
  }
}

/**
 * Example: Schedule notification with background prefetch
 */
async function scheduleWithBackgroundPrefetch() {
  try {
    // Configure background tasks first
    await configureIOSBackgroundTasks();
    
    // 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',
      sound: true
    });
    
    console.log('✅ Notification scheduled with background prefetch');
    
    // The plugin will now:
    // - Schedule notification for 09:00
    // - Schedule background task for 08:45 (T–lead)
    // - Perform single-attempt prefetch with 12s timeout
    // - Re-arm notification if content is fresh
    
  } catch (error) {
    console.error('❌ Scheduling with background prefetch failed:', error);
  }
}

/**
 * Example: Check background task status
 */
async function checkBackgroundTaskStatus() {
  try {
    console.log('Checking background task status...');
    
    // Get background task status
    const status = await DailyNotification.getBackgroundTaskStatus();
    
    console.log('📱 Background Task Status:');
    console.log(`   Available: ${status.available}`);
    console.log(`   Identifier: ${status.identifier}`);
    console.log(`   Timeout: ${status.timeout}s`);
    console.log(`   Expiration: ${status.expiration}s`);
    
    // Example output:
    // Available: true
    // Identifier: com.timesafari.dailynotification.prefetch
    // Timeout: 12s
    // Expiration: 30s
    
  } catch (error) {
    console.error('❌ Background task status check failed:', error);
  }
}

/**
 * Example: Manual background task scheduling
 */
async function manualBackgroundTaskScheduling() {
  try {
    console.log('Manually scheduling background task...');
    
    // Configure background tasks
    await configureIOSBackgroundTasks();
    
    // Manually schedule background task for specific time
    await DailyNotification.scheduleBackgroundTask({
      scheduledTime: '10:30' // Schedule for 10:30
    });
    
    console.log('✅ Background task manually scheduled for 10:30');
    
    // This will:
    // - Schedule background task for 10:15 (T–lead)
    // - Perform prefetch when iOS allows background execution
    // - Handle ETag/304 responses appropriately
    // - Update notification content if fresh
    
  } catch (error) {
    console.error('❌ Manual background task scheduling failed:', error);
  }
}

/**
 * Example: Demonstrate ETag caching
 */
async function demonstrateETagCaching() {
  try {
    console.log('Demonstrating ETag caching...');
    
    // Configure with short TTL for demonstration
    await DailyNotification.configure({
      storage: 'shared',
      ttlSeconds: 300, // 5 minutes TTL
      prefetchLeadMinutes: 2 // Very short lead time
    });
    
    // Schedule notification
    await DailyNotification.scheduleDailyNotification({
      url: 'https://api.example.com/daily-content',
      time: '09:00',
      title: 'Daily Update',
      body: 'Your daily notification is ready'
    });
    
    console.log('✅ Notification scheduled with ETag caching');
    
    // The background task will:
    // - Send If-None-Match header with stored ETag
    // - Receive 304 if content unchanged
    // - Receive 200 with new ETag if content updated
    // - Update stored content and ETag accordingly
    
  } catch (error) {
    console.error('❌ ETag caching demonstration failed:', error);
  }
}

/**
 * Example: Handle background task limitations
 */
async function handleBackgroundTaskLimitations() {
  try {
    console.log('Handling background task limitations...');
    
    // Configure background tasks
    await configureIOSBackgroundTasks();
    
    // Schedule multiple notifications to test limits
    const notifications = [
      { time: '08:00', title: 'Morning Update' },
      { time: '12:00', title: 'Lunch Reminder' },
      { time: '18:00', title: 'Evening Summary' },
      { time: '22:00', title: 'Good Night' }
    ];
    
    for (const notification of notifications) {
      await DailyNotification.scheduleDailyNotification({
        url: 'https://api.example.com/daily-content',
        time: notification.time,
        title: notification.title,
        body: 'Your daily notification is ready'
      });
    }
    
    console.log('✅ Multiple notifications scheduled');
    
    // iOS will:
    // - Limit background task execution time
    // - Provide 30-second expiration window
    // - Cancel tasks if they exceed limits
    // - Handle task failures gracefully
    
    // Check status to see current state
    const status = await DailyNotification.getBackgroundTaskStatus();
    console.log('📱 Current Status:', status);
    
  } catch (error) {
    console.error('❌ Background task limitations handling failed:', error);
  }
}

/**
 * Example: Monitor background task execution
 */
async function monitorBackgroundTaskExecution() {
  try {
    console.log('Monitoring background task execution...');
    
    // Configure background tasks
    await configureIOSBackgroundTasks();
    
    // Schedule notification
    await DailyNotification.scheduleDailyNotification({
      url: 'https://api.example.com/daily-content',
      time: '09:00',
      title: 'Daily Update',
      body: 'Your daily notification is ready'
    });
    
    // Monitor execution over time
    const monitorInterval = setInterval(async () => {
      try {
        const status = await DailyNotification.getBackgroundTaskStatus();
        console.log('📱 Background Task Status:', status);
        
        // Check if background task is available and active
        if (status.available) {
          console.log('✅ Background tasks are available');
        } else {
          console.log('⚠️  Background tasks not available:', status.reason);
        }
        
      } catch (error) {
        console.error('❌ Monitoring error:', error);
      }
    }, 60000); // Check every minute
    
    // Stop monitoring after 5 minutes
    setTimeout(() => {
      clearInterval(monitorInterval);
      console.log('✅ Background task monitoring completed');
    }, 300000);
    
  } catch (error) {
    console.error('❌ Background task monitoring failed:', error);
  }
}

/**
 * Example: Cancel background tasks
 */
async function cancelBackgroundTasks() {
  try {
    console.log('Cancelling background tasks...');
    
    // Cancel all background tasks
    await DailyNotification.cancelAllBackgroundTasks();
    
    console.log('✅ All background tasks cancelled');
    
    // This will:
    // - Cancel all pending BGTaskScheduler tasks
    // - Stop T–lead prefetch scheduling
    // - Clear background task queue
    // - Maintain existing notifications
    
  } catch (error) {
    console.error('❌ Background task cancellation failed:', error);
  }
}

// Export examples for use
export {
  configureIOSBackgroundTasks,
  scheduleWithBackgroundPrefetch,
  checkBackgroundTaskStatus,
  manualBackgroundTaskScheduling,
  demonstrateETagCaching,
  handleBackgroundTaskLimitations,
  monitorBackgroundTaskExecution,
  cancelBackgroundTasks
};