# Daily Notification Plugin - Usage Guide

## Quick Start

```typescript
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
```typescript
// 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
```typescript
// Background tasks are automatically handled
// The plugin uses BGTaskScheduler for T–lead prefetch
// No additional configuration needed
```

## Advanced Usage

### Error Handling
```typescript
// 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
```typescript
// 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
```typescript
// 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

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

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

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