@greatdayhr/capacitor-datetime-setting 1.2.0 → 2.0.0

package/README.md

@@ -3,125 +3,319 @@
 [![npm version](https://img.shields.io/npm/v/@greatdayhr/capacitor-datetime-setting.svg)](https://www.npmjs.com/package/@greatdayhr/capacitor-datetime-setting)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Capacitor plugin to get information about auto time and auto timezone settings, and open device settings if needed.
+Capacitor plugin for comprehensive date/time management on iOS. Cloned from [date_change_checker](https://github.com/error404sushant/date_change_checker) Flutter plugin.
+
+**Features:**
+- Detect manual date/time changes with network validation
+- Comprehensive change analysis (date-only, time-only, or both)
+- Automatic user notifications for detected changes
+- Fetch accurate internet time from time servers
+- Timestamp management for change tracking
+- Network-optimized with caching and offline fallback
+
+**Platform Support:**
+- ✅ **iOS**: Full implementation (10 methods)
+- ❌ **Android**: Not implemented (use native Settings API directly)
+- ❌ **Web**: Not supported
 
 ## Installation
 
 ```bash
 npm install @greatdayhr/capacitor-datetime-setting
-npx cap sync
+npx cap sync ios
 ```
 
 ## API
 
-### `timeIsAuto()`
+### Date/Time Change Detection
 
-Check if automatic time is enabled on the device.
+#### `detectDateTimeChange()`
 
-**Returns:** `Promise<{ value: boolean }>`
+Detects if the device's date/time has been manually changed. Uses network time comparison for accuracy when available, falls back to local time comparison offline.
 
-**Platform Support:**
-- ✅ Android: Returns actual setting value using `Settings.Global.AUTO_TIME`
-- ✅ iOS: Uses network time comparison for reliable detection (with offline fallback)
+**Returns:** `Promise<{ changed: boolean }>`
+
+**Platform Support:** iOS only
 
 **Example:**
 
 ```typescript
 import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
 
-const result = await DateTimeSetting.timeIsAuto();
-console.log('Auto time enabled:', result.value);
+const result = await DateTimeSetting.detectDateTimeChange();
+if (result.changed) {
+  console.log('Date/time has been manually changed!');
+}
 ```
 
 ---
 
-### `timeZoneIsAuto()`
+#### `detectComprehensiveDateTimeChange()`
 
-Check if automatic timezone is enabled on the device.
+Comprehensive date and time change detection with detailed analysis. Distinguishes between date-only, time-only, and combined changes.
 
-**Returns:** `Promise<{ value: boolean }>`
+**Returns:** `Promise<DateTimeChangeResult>`
 
-**Platform Support:**
-- ✅ Android: Returns actual setting value using `Settings.Global.AUTO_TIME_ZONE`
-- ✅ iOS: Uses network time comparison for reliable detection (with offline fallback)
+```typescript
+interface DateTimeChangeResult {
+  changeType: 'noChange' | 'timeOnly' | 'dateOnly' | 'dateAndTime';
+  timeDifference: number;
+  dateChanged: boolean;
+  timeChanged: boolean;
+  isAutoDateTimeEnabled: boolean;
+  previousDate?: number;
+  currentDate: number;
+}
+```
+
+**Platform Support:** iOS only
+
+**Example:**
+
+```typescript
+import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
+
+const result = await DateTimeSetting.detectComprehensiveDateTimeChange();
+console.log('Change type:', result.changeType);
+console.log('Date changed:', result.dateChanged);
+console.log('Time changed:', result.timeChanged);
+console.log('Time difference:', result.timeDifference, 'seconds');
+console.log('Auto time enabled:', result.isAutoDateTimeEnabled);
+```
+
+---
+
+#### `detectDateOnlyChange()`
+
+Detects specifically if only the date has been changed while time remains similar. Useful for detecting manual date changes when auto date/time is disabled.
+
+**Returns:** `Promise<{ changed: boolean }>`
+
+**Platform Support:** iOS only
+
+**Example:**
+
+```typescript
+import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
+
+const result = await DateTimeSetting.detectDateOnlyChange();
+if (result.changed) {
+  console.log('Only the date was changed!');
+}
+```
+
+---
+
+#### `detectAndNotifyDateTimeChanges()`
+
+Comprehensive date and time change detection with automatic user notifications. Shows native iOS notifications when changes are detected.
+
+**Returns:** `Promise<DateTimeChangeResult>`
+
+**Platform Support:** iOS only
+
+**Example:**
+
+```typescript
+import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
+
+const result = await DateTimeSetting.detectAndNotifyDateTimeChanges();
+// User automatically sees notification if changes detected
+console.log('Change type:', result.changeType);
+```
+
+---
+
+### Time Utilities
+
+#### `getLocalTime()`
+
+Get the device's current local time as Unix timestamp.
+
+**Returns:** `Promise<{ timestamp: number }>`
+
+**Platform Support:** iOS only
+
+**Example:**
+
+```typescript
+import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
+
+const result = await DateTimeSetting.getLocalTime();
+const date = new Date(result.timestamp * 1000);
+console.log('Current local time:', date);
+```
+
+---
+
+#### `getInternetUTCTime()`
+
+Fetch accurate UTC time from internet time server (WorldTimeAPI).
+
+**Returns:** `Promise<{ timestamp: number }>`
+
+**Platform Support:** iOS only
+
+**Example:**
+
+```typescript
+import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
+
+try {
+  const result = await DateTimeSetting.getInternetUTCTime();
+  const date = new Date(result.timestamp * 1000);
+  console.log('Internet UTC time:', date);
+} catch (error) {
+  console.error('Failed to fetch internet time:', error);
+}
+```
+
+---
+
+#### `convertToLocalTime(options)`
+
+Convert local time to UTC.
+
+**Parameters:**
+- `options.timestamp` (number): Unix timestamp to convert
+
+**Returns:** `Promise<{ timestamp: number }>`
+
+**Platform Support:** iOS only
 
 **Example:**
 
 ```typescript
 import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
 
-const result = await DateTimeSetting.timeZoneIsAuto();
-console.log('Auto timezone enabled:', result.value);
+const localTimestamp = Date.now() / 1000;
+const result = await DateTimeSetting.convertToLocalTime({ 
+  timestamp: localTimestamp 
+});
+console.log('UTC timestamp:', result.timestamp);
 ```
 
 ---
 
-### `openSetting()`
+### Timestamp Management
+
+#### `setStoredTimestamp(options)`
 
-Open the device's date and time settings screen.
+Set the stored timestamp for future change detection comparisons.
+
+**Parameters:**
+- `options.timestamp` (number): Unix timestamp to store
 
 **Returns:** `Promise<void>`
 
-**Platform Support:**
-- ✅ Android: Opens Date & Time settings directly
-- ⚠️ iOS: Opens main Settings app (cannot open specific settings page)
+**Platform Support:** iOS only
 
 **Example:**
 
 ```typescript
 import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
 
-await DateTimeSetting.openSetting();
+const currentTimestamp = Date.now() / 1000;
+await DateTimeSetting.setStoredTimestamp({ 
+  timestamp: currentTimestamp 
+});
 ```
 
+---
+
+#### `getStoredTimestamp()`
+
+Get the currently stored timestamp used for change detection.
+
+**Returns:** `Promise<{ timestamp: number | null }>`
+
+**Platform Support:** iOS only
+
+**Example:**
+
+```typescript
+import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
+
+const result = await DateTimeSetting.getStoredTimestamp();
+if (result.timestamp) {
+  const date = new Date(result.timestamp * 1000);
+  console.log('Stored timestamp:', date);
+} else {
+  console.log('No timestamp stored');
+}
+```
+
+---
+
+#### `resetDetector()`
+
+Reset the detector, clearing all stored data and cache.
+
+**Returns:** `Promise<void>`
+
+**Platform Support:** iOS only
+
+**Example:**
+
+```typescript
+import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
+
+await DateTimeSetting.resetDetector();
+console.log('Detector has been reset');
+```
+
+---
+
 ## Usage Example
 
-Here's a complete example showing how to check settings and prompt user to enable auto time:
+Here's a complete example showing how to detect and respond to date/time changes:
 
 ```typescript
 import { DateTimeSetting } from '@greatdayhr/capacitor-datetime-setting';
 import { Capacitor } from '@capacitor/core';
 
-async function checkAutoTimeSettings() {
+async function monitorDateTimeChanges() {
+  // Only works on iOS
+  if (Capacitor.getPlatform() !== 'ios') {
+    console.log('Date/time detection only available on iOS');
+    return;
+  }
+
   try {
-    const timeResult = await DateTimeSetting.timeIsAuto();
-    const timezoneResult = await DateTimeSetting.timeZoneIsAuto();
+    // Initialize with current timestamp
+    const now = Date.now() / 1000;
+    await DateTimeSetting.setStoredTimestamp({ timestamp: now });
     
-    const platform = Capacitor.getPlatform();
+    // Detect changes with notifications
+    const result = await DateTimeSetting.detectAndNotifyDateTimeChanges();
     
-    // Both Android and iOS can now detect auto time settings
-    if (!timeResult.value || !timezoneResult.value) {
-      // Show alert to user
-      const shouldOpen = confirm(
-        'Please enable automatic date & time and timezone for accurate time tracking.'
-      );
+    if (result.changeType !== 'noChange') {
+      console.log('Change detected!');
+      console.log('Type:', result.changeType);
+      console.log('Auto time enabled:', result.isAutoDateTimeEnabled);
       
-      if (shouldOpen) {
-        await DateTimeSetting.openSetting();
+      // Handle the change
+      if (!result.isAutoDateTimeEnabled) {
+        alert('Please enable automatic date & time in Settings');
       }
     }
   } catch (error) {
-    console.error('Error checking time settings:', error);
+    console.error('Error detecting time changes:', error);
   }
 }
+
+// Call this periodically or on app resume
+monitorDateTimeChanges();
 ```
 
 ## Platform-Specific Notes
 
-### Android
-
-The plugin uses Android's `Settings.Global` API to check the auto time and timezone settings. It supports Android API level 17 (Jelly Bean MR1) and above, with fallback to `Settings.System` for older versions.
-
-**Permissions:** No special permissions required.
-
 ### iOS
 
-iOS does not provide direct public APIs to check auto date/time settings. This plugin uses a **network-based detection** method for reliable results:
+The plugin uses a comprehensive multi-layered approach for reliable date/time detection:
 
 #### Detection Method
 
-The plugin uses a multi-layered approach to detect auto date/time settings:
-
 1. **Cache Check** (Instant)
    - Returns cached result if available and less than 30 seconds old
    - Avoids unnecessary network calls for better performance
@@ -143,13 +337,6 @@ The plugin uses a multi-layered approach to detect auto date/time settings:
    - Considers system uptime for better accuracy
    - Ensures plugin works without network connection
 
-#### Why Network Comparison?
-
-The simple `TimeZone.autoupdatingCurrent` check alone is **not reliable** because:
-- It can return false positives when timezone is set correctly but time is manually changed
-- It doesn't detect when user manually sets the exact same timezone
-- Network time comparison provides definitive proof of time synchronization
-
 #### Features
 
 - ✅ **High Accuracy**: Detects manual time changes even if timezone is correct
@@ -158,22 +345,36 @@ The simple `TimeZone.autoupdatingCurrent` check alone is **not reliable** becaus
 - ✅ **Battery Friendly**: Network monitoring prevents unnecessary requests
 - ✅ **Non-Blocking**: Async operations don't freeze the UI
 - ✅ **Automatic Cleanup**: Proper resource management on plugin deallocation
+- ✅ **User Notifications**: Automatic native notifications for detected changes
 
 #### Limitations
 
-- `openSetting()` opens the main Settings app instead of the specific Date & Time page (iOS restriction)
 - First call after app launch requires network for best accuracy (cached afterward)
 - Network check timeout is 3 seconds
-- Assumes time difference > 60 seconds means auto-time is disabled (works for most cases)
+- Assumes time difference > 60 seconds means auto-time is disabled
+- Notifications require user permission
 
-#### Technical Implementation
+### Android
 
-**Network Time Server**: Uses WorldTimeAPI for reliable UTC time  
-**Caching Strategy**: In-memory cache with 30-second TTL  
-**Network Monitoring**: Uses Apple's `Network` framework  
-**Threading**: Main queue dispatch for Capacitor callbacks  
+**Not implemented.** The source plugin (date_change_checker) only has basic Settings checks on Android, which can be easily done with native code:
+
+```java
+// Check if auto time is enabled
+boolean isAutoTime = Settings.Global.getInt(
+    context.getContentResolver(), 
+    Settings.Global.AUTO_TIME, 
+    0
+) == 1;
+
+// Check if auto timezone is enabled
+boolean isAutoTimeZone = Settings.Global.getInt(
+    context.getContentResolver(), 
+    Settings.Global.AUTO_TIME_ZONE, 
+    0
+) == 1;
+```
 
-**Credit:** This technique is inspired by the Flutter [date_change_checker](https://github.com/error404sushant/date_change_checker) plugin.
+Android doesn't need the complex network validation that iOS requires because it has direct Settings API access.
 
 ### Web
 
@@ -193,14 +394,11 @@ This plugin is not supported on web. All methods will throw "Not implemented on
 
 ### iOS: Slow first response
 
-**Problem**: First call to `timeIsAuto()` takes 3+ seconds.
+**Problem**: First call to detection methods takes 3+ seconds.
 
 **Explanation**: This is expected behavior. The first call makes a network request to fetch accurate time. Subsequent calls within 30 seconds use cached results and return instantly.
 
-**Solution**: If you need instant response, consider:
-- Pre-warming the cache by calling `timeIsAuto()` during app initialization
-- Showing a loading indicator during the first check
-- Using the offline fallback (less accurate but instant)
+**Solution**: Pre-warm the cache by calling a detection method during app initialization with a loading indicator.
 
 ### iOS: Plugin doesn't work in airplane mode
 
@@ -210,20 +408,30 @@ This plugin is not supported on web. All methods will throw "Not implemented on
 
 **Solution**: This is expected behavior. For best accuracy, ensure network connectivity. The offline fallback is a compromise for offline scenarios.
 
-### Android: Plugin not detecting changes
+### iOS: Notifications not showing
 
-**Problem**: Auto time/timezone setting changes are not detected.
+**Problem**: No notifications appear when changes are detected.
 
-**Solution**: Ensure you're testing on a physical device. Some emulators may not properly reflect system setting changes.
+**Solutions**:
+1. Ensure notification permissions are granted
+2. Check device notification settings
+3. The plugin requests permission on first load - user might have denied it
 
 ## Version History
 
 See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
 
-**Latest version (1.2.0)**:
-- Improved iOS detection with network time comparison
-- Added caching for better performance
-- Better offline support
+**Latest version (2.0.0)**:
+- ✨ Cloned all iOS functionality from date_change_checker Flutter plugin
+- ✨ Added comprehensive date/time change detection methods (4 methods)
+- ✨ Added automatic user notifications for date/time changes (iOS)
+- ✨ Added time utility methods (3 methods)
+- ✨ Added timestamp management for change tracking (3 methods)
+- ✨ Added `NotificationManager` for iOS notifications (259 lines)
+- 🔧 Enhanced `AutoDateTimeDetector` with comprehensive 671-line implementation
+- 📝 Complete TypeScript definitions for all methods
+- 🎯 iOS-only implementation (matches source plugin's platform support)
+- ❌ Removed Android/Web implementations (source plugin has minimal Android support)
 
 ## License
 
@@ -231,4 +439,4 @@ MIT
 
 ## Credits
 
-This plugin is based on the Flutter [datetime_setting](https://github.com/fuadarradhi/datetime_setting) plugin by [fuadarradhi](https://github.com/fuadarradhi).
+This plugin is a Capacitor port of the Flutter [date_change_checker](https://github.com/error404sushant/date_change_checker) plugin. All iOS implementation logic is cloned from the original source.

package/android/src/main/java/com/datetimesetting/DateTimeSettingPlugin.java

@@ -1,101 +1,20 @@
 package com.datetimesetting;
 
-import android.content.Intent;
-import android.os.Build;
-import android.provider.Settings;
-
-import com.getcapacitor.JSObject;
 import com.getcapacitor.Plugin;
-import com.getcapacitor.PluginCall;
-import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
 
 /**
- * DateTimeSettingPlugin
+ * DateTimeSettingPlugin - Android Implementation
+ * 
+ * Note: All date/time detection methods are iOS-only.
+ * Android does not implement the comprehensive features from date_change_checker
+ * because the source plugin itself only has basic Settings checks on Android.
  * 
- * Capacitor plugin to check auto time/timezone settings and open device settings.
+ * For Android auto time detection, use native Settings API directly:
+ * Settings.Global.getInt(context.getContentResolver(), Settings.Global.AUTO_TIME, 0) == 1
  */
 @CapacitorPlugin(name = "DateTimeSetting")
 public class DateTimeSettingPlugin extends Plugin {
-
-    /**
-     * Check if automatic time is enabled on the device.
-     * 
-     * @param call The plugin call
-     */
-    @PluginMethod
-    public void timeIsAuto(PluginCall call) {
-        try {
-            boolean isAuto;
-            
-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR1) {
-                isAuto = Settings.Global.getInt(
-                    getContext().getContentResolver(), 
-                    Settings.Global.AUTO_TIME, 
-                    0
-                ) == 1;
-            } else {
-                isAuto = Settings.System.getInt(
-                    getContext().getContentResolver(), 
-                    Settings.System.AUTO_TIME, 
-                    0
-                ) == 1;
-            }
-            
-            JSObject result = new JSObject();
-            result.put("value", isAuto);
-            call.resolve(result);
-        } catch (Exception e) {
-            call.reject("Failed to check auto time setting", e);
-        }
-    }
-
-    /**
-     * Check if automatic timezone is enabled on the device.
-     * 
-     * @param call The plugin call
-     */
-    @PluginMethod
-    public void timeZoneIsAuto(PluginCall call) {
-        try {
-            boolean isAuto;
-            
-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR1) {
-                isAuto = Settings.Global.getInt(
-                    getContext().getContentResolver(), 
-                    Settings.Global.AUTO_TIME_ZONE, 
-                    0
-                ) == 1;
-            } else {
-                isAuto = Settings.System.getInt(
-                    getContext().getContentResolver(), 
-                    Settings.System.AUTO_TIME_ZONE, 
-                    0
-                ) == 1;
-            }
-            
-            JSObject result = new JSObject();
-            result.put("value", isAuto);
-            call.resolve(result);
-        } catch (Exception e) {
-            call.reject("Failed to check auto timezone setting", e);
-        }
-    }
-
-    /**
-     * Open the device's date and time settings screen.
-     * 
-     * @param call The plugin call
-     */
-    @PluginMethod
-    public void openSetting(PluginCall call) {
-        try {
-            Intent intent = new Intent(Settings.ACTION_DATE_SETTINGS);
-            intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
-            getContext().startActivity(intent);
-            call.resolve();
-        } catch (Exception e) {
-            call.reject("Failed to open date/time settings", e);
-        }
-    }
+    // All methods are iOS-only
+    // Android implementation intentionally left minimal as per date_change_checker source
 }