cordova-notify-plugin 1.0.1

package/README.md

@@ -0,0 +1,131 @@
+# cordova-notify-plugin
+
+A Cordova plugin to schedule and cancel local alarm notifications on Android.  
+Alarms fire even when the app is closed and survive device reboots.
+
+## Supported Platforms
+
+- Android (API 19+)
+
+## Installation
+
+```bash
+cordova plugin add cordova-notify-plugin
+```
+
+Or from a local path:
+
+```bash
+cordova plugin add ../cordova-plugin-alarm-notify
+```
+
+## Permissions
+
+The plugin automatically adds the following permissions to `AndroidManifest.xml`:
+
+| Permission | Purpose |
+|---|---|
+| `POST_NOTIFICATIONS` | Show notification when alarm fires (Android 13+) |
+| `SCHEDULE_EXACT_ALARM` | Schedule exact-time alarms (Android 12+) |
+| `RECEIVE_BOOT_COMPLETED` | Re-schedule alarms after device reboot |
+| `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` | Prevent Doze mode from blocking alarms |
+
+## Usage
+
+### Schedule an Alarm
+
+**Modern API (Promise):**
+
+```javascript
+cordova.plugins.alarmNotify.schedule({
+  id: 1,
+  title: 'Meeting',
+  text: 'Team standup starts now',
+  at: new Date('2026-04-17T09:00:00')
+})
+.then(msg => console.log('Scheduled:', msg))
+.catch(err => console.error('Error:', err));
+```
+
+`at` also accepts a Unix millisecond timestamp:
+
+```javascript
+cordova.plugins.alarmNotify.schedule({
+  id: 2,
+  title: 'Reminder',
+  text: 'Check emails',
+  at: Date.now() + 5 * 60 * 1000   // 5 minutes from now
+});
+```
+
+**Legacy API (Callbacks):**
+
+```javascript
+cordova.plugins.alarmNotify.schedule(
+  1,                      // id
+  'Meeting',              // title
+  'Team standup',         // text
+  Date.now() + 60000,     // trigger time (ms)
+  msg => console.log(msg),
+  err => console.error(err)
+);
+```
+
+### Cancel an Alarm
+
+**Modern API (Promise):**
+
+```javascript
+cordova.plugins.alarmNotify.cancel(1)
+  .then(msg => console.log('Cancelled:', msg))
+  .catch(err => console.error('Error:', err));
+```
+
+**Legacy API (Callbacks):**
+
+```javascript
+cordova.plugins.alarmNotify.cancel(
+  1,
+  msg => console.log('Cancelled:', msg),
+  err => console.error('Error:', err)
+);
+```
+
+## Runtime Permission Handling
+
+On first use, the plugin may trigger the following system dialogs automatically:
+
+- **Android 13+** — "Allow notifications" permission dialog.
+- **Android 12+** — Redirects to the *Alarms & Reminders* settings screen if exact alarm permission is not granted.
+- **All versions** — Requests battery optimization exemption so alarms work reliably in the background.
+
+## TypeScript
+
+Type definitions are included:
+
+```typescript
+import { AlarmNotifyPlugin, AlarmOptions } from 'cordova-notify-plugin';
+
+declare const cordova: {
+  plugins: { alarmNotify: AlarmNotifyPlugin }
+};
+
+const options: AlarmOptions = {
+  id: 1,
+  title: 'Alarm',
+  text: 'Wake up!',
+  at: new Date()
+};
+
+await cordova.plugins.alarmNotify.schedule(options);
+```
+
+## Notes
+
+- Reusing the same `id` overwrites the existing alarm with that id.
+- Alarms with a trigger time in the past are silently ignored on reboot recovery.
+- The plugin stores scheduled alarms in `SharedPreferences` so they can be restored after a reboot.
+
+## License
+
+Apache-2.0

package/index.d.ts

@@ -0,0 +1,66 @@
+export interface AlarmOptions {
+  /** Unique alarm identifier. Reusing the same id overwrites the previous alarm. */
+  id: number;
+  /** Notification title shown in the status bar. */
+  title: string;
+  /** Notification body text. */
+  text: string;
+  /** Trigger time as a Date object or Unix millisecond timestamp. */
+  at: Date | number;
+}
+
+export interface AlarmNotifyPlugin {
+  /**
+   * Schedule a local alarm notification.
+   *
+   * @example
+   * // Promise
+   * await cordova.plugins.alarmNotify.schedule({
+   *   id: 1,
+   *   title: 'Meeting',
+   *   text: 'Team standup',
+   *   at: new Date('2026-04-17T09:00:00'),
+   * });
+   *
+   * // Callback (legacy)
+   * cordova.plugins.alarmNotify.schedule(1, 'Meeting', 'Standup', Date.now() + 60000,
+   *   msg => console.log(msg),
+   *   err => console.error(err)
+   * );
+   */
+  schedule(options: AlarmOptions): Promise<string>;
+  schedule(
+    id: number,
+    title: string,
+    text: string,
+    atMillis: number,
+    success: (msg: string) => void,
+    error: (err: string) => void
+  ): void;
+
+  /**
+   * Cancel a previously scheduled alarm.
+   *
+   * @example
+   * // Promise
+   * await cordova.plugins.alarmNotify.cancel(1);
+   *
+   * // Callback (legacy)
+   * cordova.plugins.alarmNotify.cancel(1,
+   *   msg => console.log(msg),
+   *   err => console.error(err)
+   * );
+   */
+  cancel(id: number): Promise<string>;
+  cancel(
+    id: number,
+    success: (msg: string) => void,
+    error: (err: string) => void
+  ): void;
+}
+
+declare global {
+  interface CordovaPlugins {
+    alarmNotify: AlarmNotifyPlugin;
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "cordova-notify-plugin",
+  "version": "1.0.1",
+  "description": "Cordova plugin to schedule and cancel local alarm notifications on Android. Survives device reboot and works while the app is closed.",
+  "main": "www/alarmNotify.js",
+  "types": "index.d.ts",
+  "cordova": {
+    "id": "com.solocode.alarmnotify",
+    "platforms": [
+      "android"
+    ]
+  },
+  "keywords": [
+    "ecosystem:cordova",
+    "cordova-android",
+    "alarm",
+    "notification",
+    "local-notification",
+    "schedule",
+    "background"
+  ],
+  "files": [
+    "plugin.xml",
+    "package.json",
+    "index.d.ts",
+    "www/",
+    "src/"
+  ],
+  "engines": {
+    "cordovaDependencies": {
+      "1.0.0": {
+        "cordova-android": ">=12.0.0",
+        "cordova": ">=12.0.0"
+      }
+    }
+  },
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "bugs": {
+    "url": ""
+  },
+  "homepage": ""
+}

package/plugin.xml

@@ -0,0 +1,52 @@
+<?xml version='1.0' encoding='utf-8'?>
+<plugin id="com.solocode.alarmnotify" version="1.0.0" xmlns="http://apache.org/cordova/ns/plugins/1.0" xmlns:android="http://schemas.android.com/apk/res/android">
+    <name>alarmNotify</name>
+    
+    <js-module name="alarmNotify" src="www/alarmNotify.js">
+        <clobbers target="cordova.plugins.alarmNotify" />
+    </js-module>
+
+<platform name="android">
+    <config-file target="res/xml/config.xml" parent="/*">
+      <feature name="AlarmNotify">
+        <param name="android-package" value="com.solocode.alarmnotify.AlarmNotify" />
+      </feature>
+    </config-file>
+
+    <source-file src="src/android/AlarmNotify.java" target-dir="src/com/solocode/alarmnotify" />
+    <source-file src="src/android/AlarmReceiver.java" target-dir="src/com/solocode/alarmnotify" />
+    <source-file src="src/android/BootReceiver.java" target-dir="src/com/solocode/alarmnotify" />
+
+    <framework src="androidx.core:core:1.12.0" />
+
+    <config-file target="AndroidManifest.xml" parent="/manifest">
+      <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+      <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+      <!-- Tam zamanlı alarm için (Android 12+ bazı durumlarda gerekebilir) -->
+      <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
+
+      <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+    </config-file>
+
+    <config-file target="AndroidManifest.xml" parent="/manifest/application">
+
+      <!-- Alarm tetikleyici receiver -->
+      <receiver
+        android:name="com.solocode.alarmnotify.AlarmReceiver"
+        android:exported="false" />
+
+      <!-- Reboot sonrası tekrar kuran receiver -->
+      <receiver
+        android:name="com.solocode.alarmnotify.BootReceiver"
+        android:exported="true">
+        <intent-filter>
+          <action android:name="android.intent.action.BOOT_COMPLETED" />
+        </intent-filter>
+      </receiver>
+
+    </config-file>
+  </platform>
+
+
+
+</plugin>

package/src/android/AlarmNotify.java

@@ -0,0 +1,208 @@
+package com.solocode.alarmnotify;
+
+import android.Manifest;
+import android.app.AlarmManager;
+import android.app.PendingIntent;
+import android.content.Context;
+import android.content.Intent;
+import android.content.SharedPreferences;
+import android.content.pm.PackageManager;
+import android.net.Uri;
+import android.os.Build;
+import android.os.PowerManager;
+import android.provider.Settings;
+
+import org.apache.cordova.CallbackContext;
+import org.apache.cordova.CordovaPlugin;
+import org.apache.cordova.PermissionHelper;
+
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.util.HashSet;
+import java.util.Set;
+
+public class AlarmNotify extends CordovaPlugin {
+
+  private static final int REQ_POST_NOTIF = 7001;
+
+  private static final String PREFS = "AlarmNotifyPrefs";
+  private static final String KEY_IDS = "alarm_ids";
+  private static final String KEY_ALARM_PREFIX = "alarm_";
+
+  private CallbackContext pendingCallback;
+  private JSONArray pendingArgs;
+
+  @Override
+  public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
+
+    if ("schedule".equals(action)) {
+      // Android 13+ bildirim izni
+      if (Build.VERSION.SDK_INT >= 33) {
+        if (!hasPostNotificationsPermission()) {
+          pendingCallback = callbackContext;
+          pendingArgs = args;
+          PermissionHelper.requestPermission(this, REQ_POST_NOTIF, Manifest.permission.POST_NOTIFICATIONS);
+          return true;
+        }
+      }
+      // Android 12'de exact alarm izni kontrolü
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+        AlarmManager am = (AlarmManager) cordova.getActivity().getSystemService(Context.ALARM_SERVICE);
+        if (!am.canScheduleExactAlarms()) {
+          // Kullanıcıyı exact alarm ayarları ekranına yönlendir
+          Intent intent = new Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM,
+              Uri.parse("package:" + cordova.getActivity().getPackageName()));
+          cordova.getActivity().startActivity(intent);
+          callbackContext.error("EXACT_ALARM_PERMISSION_REQUIRED");
+          return true;
+        }
+      }
+      // Pil optimizasyon muafiyeti iste (Doze / agresif üretici optimizasyonlarına karşı)
+      requestBatteryExemptionIfNeeded();
+      scheduleInternal(args, callbackContext);
+      return true;
+    }
+
+    if ("cancel".equals(action)) {
+      int id = args.optInt(0, 1);
+      cancelAlarm(cordova.getActivity().getApplicationContext(), id);
+      removeAlarm(cordova.getActivity().getApplicationContext(), id);
+      callbackContext.success("cancelled " + id);
+      return true;
+    }
+
+    return false;
+  }
+
+  private boolean hasPostNotificationsPermission() {
+    return cordova.getActivity().checkSelfPermission(Manifest.permission.POST_NOTIFICATIONS)
+        == PackageManager.PERMISSION_GRANTED;
+  }
+
+  private void requestBatteryExemptionIfNeeded() {
+    try {
+      PowerManager pm = (PowerManager) cordova.getActivity().getSystemService(Context.POWER_SERVICE);
+      String pkg = cordova.getActivity().getPackageName();
+      if (!pm.isIgnoringBatteryOptimizations(pkg)) {
+        Intent intent = new Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS,
+            Uri.parse("package:" + pkg));
+        cordova.getActivity().startActivity(intent);
+      }
+    } catch (Exception ignored) {
+      // İzin yoksa veya cihaz desteklemiyorsa sessizce geç
+    }
+  }
+
+  @Override
+  public void onRequestPermissionResult(int requestCode, String[] permissions, int[] grantResults) throws JSONException {
+    if (requestCode == REQ_POST_NOTIF) {
+      if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
+        // Android 12 exact alarm kontrolü de burada tekrarla
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+          AlarmManager am = (AlarmManager) cordova.getActivity().getSystemService(Context.ALARM_SERVICE);
+          if (!am.canScheduleExactAlarms()) {
+            Intent intent = new Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM,
+                Uri.parse("package:" + cordova.getActivity().getPackageName()));
+            cordova.getActivity().startActivity(intent);
+            if (pendingCallback != null) pendingCallback.error("EXACT_ALARM_PERMISSION_REQUIRED");
+            pendingCallback = null;
+            pendingArgs = null;
+            return;
+          }
+        }
+        requestBatteryExemptionIfNeeded();
+        scheduleInternal(pendingArgs, pendingCallback);
+      } else {
+        if (pendingCallback != null) pendingCallback.error("POST_NOTIFICATIONS denied");
+      }
+      pendingCallback = null;
+      pendingArgs = null;
+    }
+  }
+
+  private void scheduleInternal(JSONArray args, CallbackContext cb) {
+    try {
+      int id = args.optInt(0, 1);
+      String title = args.optString(1, "Alarm");
+      String text = args.optString(2, "Time!");
+      long atMillis = args.optLong(3, System.currentTimeMillis() + 5000);
+
+      Context ctx = cordova.getActivity().getApplicationContext();
+      scheduleAlarm(ctx, id, title, text, atMillis);
+      saveAlarm(ctx, id, title, text, atMillis);
+      cb.success("scheduled " + id + " at " + atMillis);
+    } catch (Exception e) {
+      cb.error(e.getMessage());
+    }
+  }
+
+  // --------- STATIC HELPERS (BootReceiver da kullanacak) ---------
+
+  public static void scheduleAlarm(Context ctx, int id, String title, String text, long atMillis) {
+    Intent intent = new Intent(ctx, AlarmReceiver.class);
+    intent.putExtra("id", id);
+    intent.putExtra("title", title);
+    intent.putExtra("text", text);
+
+    PendingIntent pi = PendingIntent.getBroadcast(
+        ctx, id, intent,
+        PendingIntent.FLAG_UPDATE_CURRENT | (Build.VERSION.SDK_INT >= 23 ? PendingIntent.FLAG_IMMUTABLE : 0)
+    );
+
+    AlarmManager am = (AlarmManager) ctx.getSystemService(Context.ALARM_SERVICE);
+
+    try {
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S && am.canScheduleExactAlarms()) {
+        am.setExactAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, atMillis, pi);
+      } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+        am.setExactAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, atMillis, pi);
+      } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
+        am.setExact(AlarmManager.RTC_WAKEUP, atMillis, pi);
+      } else {
+        am.set(AlarmManager.RTC_WAKEUP, atMillis, pi);
+      }
+    } catch (SecurityException se) {
+      am.set(AlarmManager.RTC_WAKEUP, atMillis, pi);
+    }
+  }
+
+  public static void cancelAlarm(Context ctx, int id) {
+    Intent intent = new Intent(ctx, AlarmReceiver.class);
+    PendingIntent pi = PendingIntent.getBroadcast(
+        ctx, id, intent,
+        PendingIntent.FLAG_UPDATE_CURRENT | (Build.VERSION.SDK_INT >= 23 ? PendingIntent.FLAG_IMMUTABLE : 0)
+    );
+    AlarmManager am = (AlarmManager) ctx.getSystemService(Context.ALARM_SERVICE);
+    am.cancel(pi);
+  }
+
+  private static void saveAlarm(Context ctx, int id, String title, String text, long atMillis) throws JSONException {
+    SharedPreferences sp = ctx.getSharedPreferences(PREFS, Context.MODE_PRIVATE);
+    Set<String> ids = new HashSet<>(sp.getStringSet(KEY_IDS, new HashSet<>()));
+    ids.add(String.valueOf(id));
+    JSONObject o = new JSONObject();
+    o.put("id", id); o.put("title", title); o.put("text", text); o.put("atMillis", atMillis);
+    sp.edit().putStringSet(KEY_IDS, ids).putString(KEY_ALARM_PREFIX + id, o.toString()).apply();
+  }
+
+  private static void removeAlarm(Context ctx, int id) {
+    SharedPreferences sp = ctx.getSharedPreferences(PREFS, Context.MODE_PRIVATE);
+    Set<String> ids = new HashSet<>(sp.getStringSet(KEY_IDS, new HashSet<>()));
+    ids.remove(String.valueOf(id));
+    sp.edit().putStringSet(KEY_IDS, ids).remove(KEY_ALARM_PREFIX + id).apply();
+  }
+
+  public static Set<String> getSavedAlarmIds(Context ctx) {
+    SharedPreferences sp = ctx.getSharedPreferences(PREFS, Context.MODE_PRIVATE);
+    return new HashSet<>(sp.getStringSet(KEY_IDS, new HashSet<>()));
+  }
+
+  public static JSONObject getSavedAlarm(Context ctx, String idStr) {
+    SharedPreferences sp = ctx.getSharedPreferences(PREFS, Context.MODE_PRIVATE);
+    String raw = sp.getString(KEY_ALARM_PREFIX + idStr, null);
+    if (raw == null) return null;
+    try { return new JSONObject(raw); } catch (Exception e) { return null; }
+  }
+}

package/src/android/AlarmReceiver.java

@@ -0,0 +1,44 @@
+package com.solocode.alarmnotify;
+
+import android.app.NotificationChannel;
+import android.app.NotificationManager;
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.os.Build;
+
+import androidx.core.app.NotificationCompat;
+
+public class AlarmReceiver extends BroadcastReceiver {
+
+  private static final String CHANNEL_ID = "alarm_notify_channel";
+
+  @Override
+  public void onReceive(Context context, Intent intent) {
+    int id = intent.getIntExtra("id", 1);
+    String title = intent.getStringExtra("title");
+    String text = intent.getStringExtra("text");
+
+    NotificationManager nm = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);
+
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      NotificationChannel ch = new NotificationChannel(
+          CHANNEL_ID,
+          "Alarm Notifications",
+          NotificationManager.IMPORTANCE_HIGH
+      );
+      nm.createNotificationChannel(ch);
+    }
+
+    int iconRes = context.getApplicationInfo().icon;
+
+    NotificationCompat.Builder b = new NotificationCompat.Builder(context, CHANNEL_ID)
+        .setSmallIcon(iconRes)
+        .setContentTitle(title != null ? title : "Alarm")
+        .setContentText(text != null ? text : "Time!")
+        .setAutoCancel(true)
+        .setPriority(NotificationCompat.PRIORITY_HIGH);
+
+    nm.notify(id, b.build());
+  }
+}

package/src/android/BootReceiver.java

@@ -0,0 +1,38 @@
+package com.solocode.alarmnotify;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+
+import org.json.JSONObject;
+
+import java.util.Set;
+
+public class BootReceiver extends BroadcastReceiver {
+
+  @Override
+  public void onReceive(Context context, Intent intent) {
+    if (intent == null) return;
+    if (!Intent.ACTION_BOOT_COMPLETED.equals(intent.getAction())) return;
+
+    Set<String> ids = AlarmNotify.getSavedAlarmIds(context);
+    long now = System.currentTimeMillis();
+
+    for (String idStr : ids) {
+      try {
+        JSONObject o = AlarmNotify.getSavedAlarm(context, idStr);
+        if (o == null) continue;
+
+        int id = o.optInt("id", 1);
+        String title = o.optString("title", "Alarm");
+        String text = o.optString("text", "Time!");
+        long atMillis = o.optLong("atMillis", now);
+
+        // geçmişte kaldıysa istersen hemen göster, ya da atla:
+        if (atMillis < now) continue;
+
+        AlarmNotify.scheduleAlarm(context, id, title, text, atMillis);
+      } catch (Exception ignored) {}
+    }
+  }
+}

package/www/alarmNotify.js

@@ -0,0 +1,66 @@
+var exec = require('cordova/exec');
+
+/**
+ * Schedule a local alarm notification.
+ *
+ * Modern usage (returns Promise):
+ *   alarmNotify.schedule({ id: 1, title: 'Meeting', text: 'Standup', at: new Date() })
+ *
+ * Legacy usage (callbacks):
+ *   alarmNotify.schedule(1, 'Meeting', 'Standup', Date.now() + 60000, onSuccess, onError)
+ *
+ * @param {Object|number} optionsOrId  Options object or alarm id (legacy).
+ * @param {string}        [title]      Notification title (legacy).
+ * @param {string}        [text]       Notification body (legacy).
+ * @param {number}        [atMillis]   Trigger time as Unix ms timestamp (legacy).
+ * @param {Function}      [success]    Success callback (legacy).
+ * @param {Function}      [error]      Error callback (legacy).
+ * @returns {Promise<string>|undefined}
+ */
+exports.schedule = function (optionsOrId, title, text, atMillis, success, error) {
+  var id, _title, _text, _at;
+
+  if (optionsOrId !== null && typeof optionsOrId === 'object') {
+    // Modern: options object
+    id     = optionsOrId.id     != null ? optionsOrId.id     : 1;
+    _title = optionsOrId.title  != null ? optionsOrId.title  : 'Alarm';
+    _text  = optionsOrId.text   != null ? optionsOrId.text   : '';
+    _at    = optionsOrId.at instanceof Date
+               ? optionsOrId.at.getTime()
+               : (optionsOrId.at != null ? optionsOrId.at : Date.now());
+
+    return new Promise(function (resolve, reject) {
+      exec(resolve, reject, 'AlarmNotify', 'schedule', [id, _title, _text, _at]);
+    });
+  }
+
+  // Legacy: positional args + callbacks
+  id     = optionsOrId;
+  _title = title;
+  _text  = text;
+  _at    = atMillis;
+  exec(success, error, 'AlarmNotify', 'schedule', [id, _title, _text, _at]);
+};
+
+/**
+ * Cancel a previously scheduled alarm.
+ *
+ * Modern usage (returns Promise):
+ *   alarmNotify.cancel(1)
+ *
+ * Legacy usage (callbacks):
+ *   alarmNotify.cancel(1, onSuccess, onError)
+ *
+ * @param {number}   id       Alarm id to cancel.
+ * @param {Function} [success] Success callback (legacy).
+ * @param {Function} [error]   Error callback (legacy).
+ * @returns {Promise<string>|undefined}
+ */
+exports.cancel = function (id, success, error) {
+  if (typeof success !== 'function' && typeof error !== 'function') {
+    return new Promise(function (resolve, reject) {
+      exec(resolve, reject, 'AlarmNotify', 'cancel', [id]);
+    });
+  }
+  exec(success, error, 'AlarmNotify', 'cancel', [id]);
+};