daily-notification-plugin/docs/plugin-usage-decision-guide.md

DailyNotification Plugin - Usage Decision Guide

Author: Matthew Raymer
Version: 1.0.0
Created: 2025-10-08 06:24:57 UTC

Quick Decision Flow

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           TimeSafari PWA Project                               │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  ┌─────────────────┐                                                           │
│  │   Does your     │                                                           │
│  │   TimeSafari    │                                                           │
│  │   PWA use       │                                                           │
│  │   Capacitor?    │                                                           │
│  └─────────────────┘                                                           │
│           │                                                                     │
│           ▼                                                                     │
│  ┌─────────────────┐                    ┌─────────────────┐                    │
│  │       YES       │                    │       NO        │                    │
│  │                 │                    │                 │                    │
│  │  ┌─────────────┐│                    │  ┌─────────────┐│                    │
│  │  │   Use       ││                    │  │   Don't     ││                    │
│  │  │   Plugin    ││                    │  │   Use       ││                    │
│  │  │             ││                    │  │   Plugin    ││                    │
│  │  │ ✅ Native   ││                    │  │             ││                    │
│  │  │    mobile   ││                    │  │ ❌ Web-only ││                    │
│  │  │    features ││                    │  │    PWA      ││                    │
│  │  │ ✅ Background││                    │  │ ❌ No native││                    │
│  │  │    notifications││                    │  │    features ││                    │
│  │  │ ✅ Platform ││                    │  │ ❌ Use      ││                    │
│  │  │    specific ││                    │  │    existing ││                    │
│  │  │    optimizations││                    │  │    code    ││                    │
│  │  └─────────────┘│                    │  └─────────────┘│                    │
│  └─────────────────┘                    └─────────────────┘                    │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

Detailed Decision Matrix

Scenario	Use Plugin?	Why?	What to Do
Web-only PWA	❌ NO	Plugin requires Capacitor for native mobile features	Continue using your existing loadNewStarredProjectChanges() code
Capacitor + Android	✅ YES	Plugin provides WorkManager, AlarmManager, notification channels	Integrate plugin with platform detection
Capacitor + iOS	✅ YES	Plugin provides BGTaskScheduler, UNUserNotificationCenter	Integrate plugin with platform detection
Capacitor + Electron	✅ YES	Plugin provides desktop notifications and background tasks	Integrate plugin with Electron-specific configuration
Capacitor + Web	❌ NO	Web browser doesn't support native mobile features	Use existing web code, plugin won't work

Code Examples

Scenario 1: Web-Only PWA (No Plugin)

// Your existing TimeSafari PWA code - NO CHANGES NEEDED
class TimeSafariHomeView {
  private async loadNewStarredProjectChanges() {
    if (this.activeDid && this.starredPlanHandleIds.length > 0) {
      try {
        const starredProjectChanges = await getStarredProjectsWithChanges(
          this.axios,
          this.apiServer,
          this.activeDid,
          this.starredPlanHandleIds,
          this.lastAckedStarredPlanChangesJwtId,
        );
        this.numNewStarredProjectChanges = starredProjectChanges.data.length;
        this.newStarredProjectChangesHitLimit = starredProjectChanges.hitLimit;
      } catch (error) {
        console.warn("[HomeView] Failed to load starred project changes:", error);
        this.numNewStarredProjectChanges = 0;
        this.newStarredProjectChangesHitLimit = false;
      }
    }
  }
}

What happens:

• Your existing code works perfectly in web browsers
• No plugin integration needed
• No native mobile features (background notifications, etc.)
• Limited to web browser capabilities

Scenario 2: Capacitor-Based PWA (Use Plugin)

// Your TimeSafari PWA with Capacitor - USE PLUGIN
import { Capacitor } from '@capacitor/core';
import { DailyNotification } from '@timesafari/daily-notification-plugin';

class TimeSafariHomeView {
  async initialize() {
    // Check if running in Capacitor
    if (Capacitor.isNativePlatform()) {
      // Initialize plugin for native mobile features
      await this.setupDailyNotification();
    } else {
      // Use existing web-only code
      console.log('Running in web browser - using existing code');
    }
  }
  
  async setupDailyNotification() {
    // Only runs on native platforms (Android, iOS)
    await DailyNotification.configure({
      timesafariConfig: {
        activeDid: this.activeDid,
        endpoints: {
          projectsLastUpdated: `${this.apiServer}/api/v2/report/plansLastUpdatedBetween`
        },
        starredProjectsConfig: {
          enabled: true,
          starredPlanHandleIds: this.starredPlanHandleIds,
          lastAckedJwtId: this.lastAckedStarredPlanChangesJwtId,
          fetchInterval: '0 8 * * *'
        }
      },
      networkConfig: {
        httpClient: this.axios,
        baseURL: this.apiServer,
        timeout: 30000
      }
    });
  }
  
  async loadNewStarredProjectChanges() {
    if (Capacitor.isNativePlatform()) {
      // Use plugin-enhanced method on native platforms
      await this.loadNewStarredProjectChangesNative();
    } else {
      // Use existing web method in browser
      await this.loadNewStarredProjectChangesWeb();
    }
  }
}

What happens:

• Plugin provides native mobile features (background notifications, etc.)
• Enhanced error handling and performance optimization
• Platform-specific optimizations (Android WorkManager, iOS BGTaskScheduler)
• Graceful fallback to web code when not on native platform

How to Check if You Need the Plugin

1. Check if Capacitor is Installed

# Check if Capacitor is in your package.json
npm list @capacitor/core

# Or check your package.json file
cat package.json | grep capacitor

2. Check if Capacitor is Configured

# Check if capacitor.config.ts exists
ls capacitor.config.ts

# Or check if capacitor.config.js exists
ls capacitor.config.js

3. Check if Native Platforms are Added

# Check if Android platform is added
ls android/

# Check if iOS platform is added
ls ios/

4. Check in Your Code

// Add this to your TimeSafari PWA to check
import { Capacitor } from '@capacitor/core';

console.log('Platform:', Capacitor.getPlatform());
console.log('Is Native:', Capacitor.isNativePlatform());
console.log('Is Web:', Capacitor.getPlatform() === 'web');

Integration Checklist

✅ If You Have Capacitor:

• Install the DailyNotification plugin
• Add platform detection to your code
• Configure the plugin for your TimeSafari data
• Test on Android device/emulator
• Test on iOS device/simulator
• Test web fallback in browser
• Implement graceful degradation

❌ If You Don't Have Capacitor:

• Continue using your existing code
• No plugin integration needed
• No changes required
• Your existing loadNewStarredProjectChanges() works perfectly

Common Mistakes

❌ Mistake 1: Installing Plugin Without Capacitor

// DON'T DO THIS - Plugin won't work in web browsers
import { DailyNotification } from '@timesafari/daily-notification-plugin';

// This will fail in web browsers
await DailyNotification.configure({...});

❌ Mistake 2: Not Using Platform Detection

// DON'T DO THIS - Always tries to use plugin
await DailyNotification.configure({...}); // Fails in web browsers

✅ Correct Approach: Platform Detection

// DO THIS - Only use plugin on native platforms
import { Capacitor } from '@capacitor/core';

if (Capacitor.isNativePlatform()) {
  await DailyNotification.configure({...});
} else {
  // Use existing web code
}

Summary

The DailyNotification plugin is ONLY needed when your TimeSafari PWA uses Capacitor for mobile app development.

• Web-only PWA: Continue using your existing code, no plugin needed
• Capacitor-based PWA: Use the plugin with platform detection for native mobile features
• Always implement graceful degradation to fall back to web code when needed

---

Quick Answer: If your TimeSafari PWA doesn't use Capacitor, you don't need the DailyNotification plugin. Your existing loadNewStarredProjectChanges() code works perfectly for web-only PWAs.