daily-notification-plugin/src/definitions.ts

/**
 * Daily Notification Plugin Definitions
 * 
 * TypeScript definitions for the Daily Notification Plugin
 * Aligned with Android implementation and test requirements
 * 
 * @author Matthew Raymer
 * @version 2.0.0
 */

export interface NotificationResponse {
  id: string;
  title: string;
  body: string;
  timestamp: number;
  url?: string;
}

export interface NotificationOptions {
  url?: string;
  time?: string;
  title?: string;
  body?: string;
  sound?: boolean;
  priority?: 'high' | 'default' | 'low' | 'min' | 'max' | 'normal';
  timezone?: string;
  retryCount?: number;
  retryInterval?: number;
  offlineFallback?: boolean;
  contentHandler?: ContentHandler;
  headers?: Record<string, string>;
}

export interface ContentHandler {
  (response?: any): Promise<{ title: string; body: string; data?: any }>;
}



export interface ScheduleOptions {
  url?: string;
  time?: string;
  sound?: boolean;
  priority?: 'high' | 'default' | 'low' | 'min' | 'max' | 'normal';
  timezone?: string;
  retryCount?: number;
  retryInterval?: number;
  offlineFallback?: boolean;
  contentHandler?: ContentHandler;
  headers?: Record<string, string>;
}

export interface NotificationSettings {
  url?: string;
  time?: string;
  sound?: boolean;
  priority?: string;
  timezone?: string;
  retryCount?: number;
  retryInterval?: number;
  offlineFallback?: boolean;
}

export interface NotificationStatus {
  isEnabled?: boolean;
  isScheduled?: boolean;
  lastNotificationTime: number | Promise<number>;
  nextNotificationTime: number | Promise<number>;
  pending?: number;
  settings: NotificationSettings;
  error?: string;
}

export interface BatteryStatus {
  level: number;
  isCharging: boolean;
  powerState: number;
  isOptimizationExempt: boolean;
}

export interface PowerState {
  powerState: number;
  isOptimizationExempt: boolean;
}

export interface NotificationEvent extends Event {
  detail: {
    id: string;
    action: string;
    data?: any;
  };
}

export interface PermissionStatus {
  status?: string;
  granted?: boolean;
  notifications: PermissionState;
  backgroundRefresh?: PermissionState; // iOS only
  alert?: boolean;
  badge?: boolean;
  sound?: boolean;
  lockScreen?: boolean;
  carPlay?: boolean;
}

export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied' | 'provisional' | 'ephemeral' | 'unknown';

// Additional interfaces for enhanced functionality
export interface NotificationMetrics {
  scheduledTime: number;
  actualDeliveryTime?: number;
  contentAge: number;
  engagement?: 'TAPPED' | 'DISMISSED' | 'IGNORED';
  failureReason?: string;
  platformInfo: PlatformInfo;
}

export interface PlatformInfo {
  oem?: string;
  osVersion: string;
  appState: string;
}

export interface FallbackContent {
  title: string;
  body: string;
  isEmergency: boolean;
  age?: string;
}

export interface CachePolicy {
  maxSize: number;
  evictionPolicy: 'LRU' | 'FIFO' | 'TTL';
  ttl?: number;
  cleanupInterval: number;
}

export interface NetworkConfig {
  timeout: number;
  retryAttempts: number;
  retryDelay: number;
  offlineFallback: boolean;
}

export interface SchedulingConfig {
  exactAlarms: boolean;
  adaptiveScheduling: boolean;
  quietHours?: {
    start: string;
    end: string;
    enabled: boolean;
  };
  timezone: string;
}

export interface ConfigureOptions {
  dbPath?: string;
  storage?: 'shared' | 'tiered';
  ttlSeconds?: number;
  prefetchLeadMinutes?: number;
  maxNotificationsPerDay?: number;
  retentionDays?: number;
}

// Dual Scheduling System Interfaces
export interface ContentFetchConfig {
  enabled: boolean;
  schedule: string; // Cron expression
  url?: string;
  headers?: Record<string, string>;
  timeout?: number;
  retryAttempts?: number;
  retryDelay?: number;
  callbacks: {
    apiService?: string;
    database?: string;
    reporting?: string;
    onSuccess?: (data: any) => Promise<void>;
    onError?: (error: Error) => Promise<void>;
    onComplete?: (result: ContentFetchResult) => Promise<void>;
  };
  contentHandler?: ContentHandler;
  cachePolicy?: CachePolicy;
  networkConfig?: NetworkConfig;
}

export interface UserNotificationConfig {
  enabled: boolean;
  schedule: string; // Cron expression
  title?: string;
  body?: string;
  sound?: boolean;
  vibration?: boolean;
  priority?: 'low' | 'normal' | 'high';
  badge?: boolean;
  actions?: NotificationAction[];
  category?: string;
  userInfo?: Record<string, any>;
}

export interface NotificationAction {
  id: string;
  title: string;
  icon?: string;
  destructive?: boolean;
  authenticationRequired?: boolean;
}

export interface DualScheduleConfiguration {
  contentFetch: ContentFetchConfig;
  userNotification: UserNotificationConfig;
  relationship?: {
    autoLink: boolean;        // Automatically link content to notification
    contentTimeout: number;   // How long to wait for content before notification
    fallbackBehavior: 'skip' | 'show_default' | 'retry';
  };
}

export interface ContentFetchResult {
  success: boolean;
  data?: any;
  timestamp: number;
  contentAge: number;
  error?: string;
  retryCount: number;
  metadata?: Record<string, any>;
}

export interface DualScheduleStatus {
  contentFetch: {
    isEnabled: boolean;
    isScheduled: boolean;
    lastFetchTime?: number;
    nextFetchTime?: number;
    lastFetchResult?: ContentFetchResult;
    pendingFetches: number;
  };
  userNotification: {
    isEnabled: boolean;
    isScheduled: boolean;
    lastNotificationTime?: number;
    nextNotificationTime?: number;
    pendingNotifications: number;
  };
  relationship: {
    isLinked: boolean;
    contentAvailable: boolean;
    lastLinkTime?: number;
  };
  overall: {
    isActive: boolean;
    lastActivity: number;
    errorCount: number;
    successRate: number;
  };
}

// Enhanced DailyNotificationPlugin interface with dual scheduling
export interface DailyNotificationPlugin {
  // Configuration methods
  configure(options: ConfigureOptions): Promise<void>;
  
  // Rolling window management
  maintainRollingWindow(): Promise<void>;
  getRollingWindowStats(): Promise<{
    stats: string;
    maintenanceNeeded: boolean;
    timeUntilNextMaintenance: number;
  }>;
  
  // Exact alarm management
  getExactAlarmStatus(): Promise<{
    supported: boolean;
    enabled: boolean;
    canSchedule: boolean;
    fallbackWindow: string;
  }>;
  requestExactAlarmPermission(): Promise<void>;
  openExactAlarmSettings(): Promise<void>;
  
  // Reboot recovery management
  getRebootRecoveryStatus(): Promise<{
    inProgress: boolean;
    lastRecoveryTime: number;
    timeSinceLastRecovery: number;
    recoveryNeeded: boolean;
  }>;
  
  // Existing methods
  scheduleDailyNotification(options: NotificationOptions | ScheduleOptions): Promise<void>;
  getLastNotification(): Promise<NotificationResponse | null>;
  cancelAllNotifications(): Promise<void>;
  getNotificationStatus(): Promise<NotificationStatus>;
  updateSettings(settings: NotificationSettings): Promise<void>;
  getBatteryStatus(): Promise<BatteryStatus>;
  requestBatteryOptimizationExemption(): Promise<void>;
  setAdaptiveScheduling(options: { enabled: boolean }): Promise<void>;
  getPowerState(): Promise<PowerState>;
  checkPermissions(): Promise<PermissionStatus>;
  requestPermissions(): Promise<PermissionStatus>;
  
  // New dual scheduling methods
  scheduleContentFetch(config: ContentFetchConfig): Promise<void>;
  scheduleUserNotification(config: UserNotificationConfig): Promise<void>;
  scheduleDualNotification(config: DualScheduleConfiguration): Promise<void>;
  getDualScheduleStatus(): Promise<DualScheduleStatus>;
  updateDualScheduleConfig(config: DualScheduleConfiguration): Promise<void>;
  cancelDualSchedule(): Promise<void>;
  pauseDualSchedule(): Promise<void>;
  resumeDualSchedule(): Promise<void>;
  
  // Content management methods
  getContentCache(): Promise<Record<string, any>>;
  clearContentCache(): Promise<void>;
  getContentHistory(): Promise<ContentFetchResult[]>;
  
  // Callback management methods
  registerCallback(name: string, callback: Function): Promise<void>;
  unregisterCallback(name: string): Promise<void>;
  getRegisteredCallbacks(): Promise<string[]>;
}