# 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)

```typescript
// 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)

```typescript
// 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

```bash
# 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

```bash
# 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

```bash
# Check if Android platform is added
ls android/

# Check if iOS platform is added
ls ios/
```

### 4. Check in Your Code

```typescript
// 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

```typescript
// 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

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

### ✅ Correct Approach: Platform Detection

```typescript
// 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.