feat(android): implement Phase 1.2 TTL-at-fire enforcement

- Add DailyNotificationTTLEnforcer with freshness validation logic - Add TTL validation to scheduling path before arming notifications - Implement skip rule: if (T - fetchedAt) > ttlSeconds → skip arming - Add TTL violation logging with TTL_VIOLATION code - Add comprehensive unit tests for TTL enforcement - Add TTL enforcer integration to DailyNotificationPlugin - Add phase1-2-ttl-enforcement.ts usage examples This implements the critical Phase 1.2 gate for content freshness: - Notifications with stale content are automatically skipped - TTL violations are logged and tracked for analytics - Freshness validation prevents delivery of outdated content - Configurable TTL settings support different use cases - Integration with existing scheduling infrastructure Files: 5 changed, 878 insertions(+)
2025-09-08 09:58:15 +00:00
parent 489dd4ac28
commit de6331aabd
5 changed files with 878 additions and 0 deletions
--- a/examples/phase1-2-ttl-enforcement.ts
+++ b/examples/phase1-2-ttl-enforcement.ts
@@ -0,0 +1,173 @@
+/**
+ * Phase 1.2 TTL-at-Fire Enforcement Usage Example
+ * 
+ * Demonstrates TTL enforcement functionality
+ * Shows how stale notifications are automatically skipped
+ * 
+ * @author Matthew Raymer
+ * @version 1.0.0
+ */
+
+import { DailyNotification } from '@timesafari/daily-notification-plugin';
+
+/**
+ * Example: Configure TTL enforcement
+ */
+async function configureTTLEnforcement() {
+  try {
+    console.log('Configuring TTL enforcement...');
+    
+    // Configure with TTL settings
+    await DailyNotification.configure({
+      storage: 'shared',
+      ttlSeconds: 1800, // 30 minutes TTL
+      prefetchLeadMinutes: 15
+    });
+    
+    console.log('✅ TTL enforcement configured (30 minutes)');
+    
+    // Now the plugin will automatically skip notifications with stale content
+    // Content older than 30 minutes at fire time will not be armed
+    
+  } catch (error) {
+    console.error('❌ TTL configuration failed:', error);
+  }
+}
+
+/**
+ * Example: Schedule notification with TTL enforcement
+ */
+async function scheduleWithTTLEnforcement() {
+  try {
+    // Configure TTL enforcement first
+    await configureTTLEnforcement();
+    
+    // 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 TTL enforcement');
+    
+    // The plugin will now:
+    // 1. Check content freshness before arming
+    // 2. Skip notifications with stale content
+    // 3. Log TTL violations for debugging
+    // 4. Store violation statistics
+    
+  } catch (error) {
+    console.error('❌ Scheduling with TTL enforcement failed:', error);
+  }
+}
+
+/**
+ * Example: Demonstrate TTL violation scenario
+ */
+async function demonstrateTTLViolation() {
+  try {
+    console.log('Demonstrating TTL violation scenario...');
+    
+    // Configure with short TTL for demonstration
+    await DailyNotification.configure({
+      storage: 'shared',
+      ttlSeconds: 300, // 5 minutes TTL (very short for demo)
+      prefetchLeadMinutes: 2
+    });
+    
+    // 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 5-minute TTL');
+    
+    // If content is fetched more than 5 minutes before 09:00,
+    // the notification will be skipped due to TTL violation
+    
+    console.log('ℹ️  If content is older than 5 minutes at 09:00, notification will be skipped');
+    
+  } catch (error) {
+    console.error('❌ TTL violation demonstration failed:', error);
+  }
+}
+
+/**
+ * Example: Check TTL violation statistics
+ */
+async function checkTTLStats() {
+  try {
+    console.log('Checking TTL violation statistics...');
+    
+    // Configure TTL enforcement
+    await DailyNotification.configure({
+      storage: 'shared',
+      ttlSeconds: 1800, // 30 minutes
+      prefetchLeadMinutes: 15
+    });
+    
+    // The plugin automatically tracks TTL violations
+    // You can check the logs for TTL_VIOLATION entries
+    // or implement a method to retrieve violation statistics
+    
+    console.log('✅ TTL enforcement active - violations will be logged');
+    console.log('ℹ️  Check logs for "TTL_VIOLATION" entries');
+    
+  } catch (error) {
+    console.error('❌ TTL stats check failed:', error);
+  }
+}
+
+/**
+ * Example: Different TTL configurations for different use cases
+ */
+async function configureDifferentTTLScenarios() {
+  try {
+    console.log('Configuring different TTL scenarios...');
+    
+    // Scenario 1: Real-time notifications (short TTL)
+    await DailyNotification.configure({
+      storage: 'shared',
+      ttlSeconds: 300, // 5 minutes
+      prefetchLeadMinutes: 2
+    });
+    
+    console.log('✅ Real-time notifications: 5-minute TTL');
+    
+    // Scenario 2: Daily digest (longer TTL)
+    await DailyNotification.configure({
+      storage: 'shared',
+      ttlSeconds: 7200, // 2 hours
+      prefetchLeadMinutes: 30
+    });
+    
+    console.log('✅ Daily digest: 2-hour TTL');
+    
+    // Scenario 3: Weekly summary (very long TTL)
+    await DailyNotification.configure({
+      storage: 'shared',
+      ttlSeconds: 86400, // 24 hours
+      prefetchLeadMinutes: 60
+    });
+    
+    console.log('✅ Weekly summary: 24-hour TTL');
+    
+  } catch (error) {
+    console.error('❌ TTL scenario configuration failed:', error);
+  }
+}
+
+// Export examples for use
+export {
+  configureTTLEnforcement,
+  scheduleWithTTLEnforcement,
+  demonstrateTTLViolation,
+  checkTTLStats,
+  configureDifferentTTLScenarios
+};