react-native-alarms 0.0.0-stage → 0.0.2

package/android/app/build.gradle

@@ -0,0 +1,119 @@
+apply plugin: "com.android.application"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "com.facebook.react"
+
+/**
+ * This is the configuration block to customize your React Native Android app.
+ * By default you don't need to apply any configuration, just uncomment the lines you need.
+ */
+react {
+    /* Folders */
+    //   The root of your project, i.e. where "package.json" lives. Default is '../..'
+    // root = file("../../")
+    //   The folder where the react-native NPM package is. Default is ../../node_modules/react-native
+    // reactNativeDir = file("../../node_modules/react-native")
+    //   The folder where the react-native Codegen package is. Default is ../../node_modules/@react-native/codegen
+    // codegenDir = file("../../node_modules/@react-native/codegen")
+    //   The cli.js file which is the React Native CLI entrypoint. Default is ../../node_modules/react-native/cli.js
+    // cliFile = file("../../node_modules/react-native/cli.js")
+
+    /* Variants */
+    //   The list of variants to that are debuggable. For those we're going to
+    //   skip the bundling of the JS bundle and the assets. Default is "debug", "debugOptimized".
+    //   If you add flavors like lite, prod, etc. you'll have to list your debuggableVariants.
+    // debuggableVariants = ["liteDebug", "liteDebugOptimized", "prodDebug", "prodDebugOptimized"]
+
+    /* Bundling */
+    //   A list containing the node command and its flags. Default is just 'node'.
+    // nodeExecutableAndArgs = ["node"]
+    //
+    //   The command to run when bundling. By default is 'bundle'
+    // bundleCommand = "ram-bundle"
+    //
+    //   The path to the CLI configuration file. Default is empty.
+    // bundleConfig = file(../rn-cli.config.js)
+    //
+    //   The name of the generated asset file containing your JS bundle
+    // bundleAssetName = "MyApplication.android.bundle"
+    //
+    //   The entry file for bundle generation. Default is 'index.android.js' or 'index.js'
+    // entryFile = file("../js/MyApplication.android.js")
+    //
+    //   A list of extra flags to pass to the 'bundle' commands.
+    //   See https://github.com/react-native-community/cli/blob/main/docs/commands.md#bundle
+    // extraPackagerArgs = []
+
+    /* Hermes Commands */
+    //   The hermes compiler command to run. By default it is 'hermesc'
+    // hermesCommand = "$rootDir/my-custom-hermesc/bin/hermesc"
+    //
+    //   The list of flags to pass to the Hermes compiler. By default is "-O", "-output-source-map"
+    // hermesFlags = ["-O", "-output-source-map"]
+
+    /* Autolinking */
+    autolinkLibrariesWithApp()
+}
+
+/**
+ * Set this to true to Run Proguard on Release builds to minify the Java bytecode.
+ */
+def enableProguardInReleaseBuilds = false
+
+/**
+ * The preferred build flavor of JavaScriptCore (JSC)
+ *
+ * For example, to use the international variant, you can use:
+ * `def jscFlavor = io.github.react-native-community:jsc-android-intl:2026004.+`
+ *
+ * The international variant includes ICU i18n library and necessary data
+ * allowing to use e.g. `Date.toLocaleString` and `String.localeCompare` that
+ * give correct results when using with locales other than en-US. Note that
+ * this variant is about 6MiB larger per architecture than default.
+ */
+def jscFlavor = 'io.github.react-native-community:jsc-android:2026004.+'
+
+android {
+    ndkVersion rootProject.ext.ndkVersion
+    buildToolsVersion rootProject.ext.buildToolsVersion
+    compileSdk rootProject.ext.compileSdkVersion
+
+    namespace "com.reactnativealarm"
+    defaultConfig {
+        applicationId "com.reactnativealarm"
+        minSdkVersion rootProject.ext.minSdkVersion
+        targetSdkVersion rootProject.ext.targetSdkVersion
+        versionCode 1
+        versionName "1.0"
+    }
+    signingConfigs {
+        debug {
+            storeFile file('debug.keystore')
+            storePassword 'android'
+            keyAlias 'androiddebugkey'
+            keyPassword 'android'
+        }
+    }
+    buildTypes {
+        debug {
+            signingConfig signingConfigs.debug
+        }
+        release {
+            // Caution! In production, you need to generate your own keystore file.
+            // see https://reactnative.dev/docs/signed-apk-android.
+            signingConfig signingConfigs.debug
+            minifyEnabled enableProguardInReleaseBuilds
+            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro"
+        }
+    }
+}
+
+dependencies {
+    // The version of react-native is set by the React Native Gradle Plugin
+    implementation("com.facebook.react:react-android")
+
+    if (hermesEnabled.toBoolean()) {
+        implementation("com.facebook.react:hermes-android")
+    } else {
+        implementation jscFlavor
+    }
+}

package/android/app/proguard-rules.pro

@@ -0,0 +1,10 @@
+# Add project specific ProGuard rules here.
+# By default, the flags in this file are appended to flags specified
+# in /usr/local/Cellar/android-sdk/24.3.3/tools/proguard/proguard-android.txt
+# You can edit the include path and order by changing the proguardFiles
+# directive in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# Add any project specific keep options here:

package/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,81 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <!-- Exact alarms: USE_EXACT_ALARM is granted automatically to alarm-clock apps on
+         Android 13+; SCHEDULE_EXACT_ALARM covers Android 12 (user-grantable). -->
+    <uses-permission android:name="android.permission.USE_EXACT_ALARM" />
+    <uses-permission
+        android:name="android.permission.SCHEDULE_EXACT_ALARM"
+        android:maxSdkVersion="32" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.VIBRATE" />
+    <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
+    <!-- Lets the ringing service pop the alarm screen instantly from the background;
+         the full-screen notification alone is unreliable on many devices. -->
+    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+
+    <application
+      android:name=".MainApplication"
+      android:label="@string/app_name"
+      android:icon="@mipmap/ic_launcher"
+      android:roundIcon="@mipmap/ic_launcher_round"
+      android:allowBackup="false"
+      android:theme="@style/AppTheme"
+      android:usesCleartextTraffic="${usesCleartextTraffic}"
+      android:supportsRtl="true">
+      <activity
+        android:name=".MainActivity"
+        android:label="@string/app_name"
+        android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
+        android:launchMode="singleTask"
+        android:windowSoftInputMode="adjustResize"
+        android:exported="true">
+        <intent-filter>
+            <action android:name="android.intent.action.MAIN" />
+            <category android:name="android.intent.category.LAUNCHER" />
+        </intent-filter>
+      </activity>
+
+       <!-- Shown over the lock screen while the alarm rings. excludeFromRecents +
+           taskAffinity keep it out of the user's app history / back stack. -->
+      <activity
+        android:name="com.alarm.AlarmRingActivity"
+        android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
+        android:excludeFromRecents="true"
+        android:exported="false"
+        android:launchMode="singleInstance"
+        android:showWhenLocked="true"
+        android:taskAffinity=""
+        android:theme="@style/AppTheme"
+        android:turnScreenOn="true" />
+
+      <!-- Foreground service that plays the alarm: keeps the process alive and the
+           sound looping no matter what happens to the UI. -->
+      <service
+        android:name="com.alarm.AlarmService"
+        android:exported="false"
+        android:foregroundServiceType="mediaPlayback" />
+
+      <!-- AlarmManager fires here at the exact trigger time. -->
+      <receiver
+        android:name="com.alarm.AlarmReceiver"
+        android:exported="false" />
+
+      <!-- Reschedules every enabled alarm after a reboot, an app update or a clock change. -->
+      <receiver
+        android:name="com.alarm.BootReceiver"
+        android:enabled="true"
+        android:exported="true">
+        <intent-filter>
+          <action android:name="android.intent.action.BOOT_COMPLETED" />
+          <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
+          <action android:name="android.intent.action.TIME_SET" />
+          <action android:name="android.intent.action.TIMEZONE_CHANGED" />
+        </intent-filter>
+      </receiver>
+    </application>
+</manifest>

package/android/app/src/main/java/com/reactnativealarm/MainActivity.kt

@@ -0,0 +1,29 @@
+package com.reactnativealarm
+
+import com.facebook.react.ReactActivity
+import com.facebook.react.ReactActivityDelegate
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
+import com.facebook.react.defaults.DefaultReactActivityDelegate
+import com.alarm.AlarmRingActivity
+
+class MainActivity : ReactActivity() {
+
+  /**
+   * Returns the name of the main component registered from JavaScript. This is used to schedule
+   * rendering of the component.
+   */
+  override fun getMainComponentName(): String = "ReactNativeAlarm"
+
+  /**
+   * Returns the instance of the [ReactActivityDelegate]. We use [DefaultReactActivityDelegate]
+   * which allows you to enable New Architecture with a single boolean flags [fabricEnabled]
+   */
+  override fun createReactActivityDelegate(): ReactActivityDelegate =
+      DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
+
+  override fun onResume() {
+    super.onResume()
+    // An alarm is ringing and the user opened the app: show the ring screen on top.
+    AlarmRingActivity.openIfRinging(this)
+  }
+}

package/android/app/src/main/java/com/reactnativealarm/MainApplication.kt

@@ -0,0 +1,29 @@
+package com.reactnativealarm
+
+import android.app.Application
+import com.facebook.react.PackageList
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactHost
+import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
+import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
+import com.alarm.AlarmPackage
+
+class MainApplication : Application(), ReactApplication {
+
+  override val reactHost: ReactHost by lazy {
+    getDefaultReactHost(
+      context = applicationContext,
+      packageList =
+        PackageList(this).packages.apply {
+          // Packages that cannot be autolinked yet can be added manually here, for example:
+          // add(MyReactNativePackage())
+          add(AlarmPackage())
+        },
+    )
+  }
+
+  override fun onCreate() {
+    super.onCreate()
+    loadReactNative(this)
+  }
+}

package/android/app/src/main/java/com/reactnativealarm/alarm/AlarmData.kt

@@ -0,0 +1,134 @@
+package com.alarm
+
+import android.os.Bundle
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableMap
+import org.json.JSONArray
+import org.json.JSONObject
+import java.util.Calendar
+
+data class AlarmData(
+  val id: String,
+  val timestamp: Long,
+  val title: String,
+  val body: String,
+  val sound: String,
+  val vibrate: Boolean,
+  val snoozeEnabled: Boolean,
+  val snoozeMinutes: Int,
+  val repeatType: String,
+  val weekdays: List<Int>,
+  val intervalMs: Long,
+  val data: String,
+  var enabled: Boolean = true
+) {
+  fun nextTrigger(from: Long = System.currentTimeMillis()): Long {
+    if (!enabled) return 0
+    return when (repeatType) {
+      "daily" -> nextMatching(from) { true }
+      "weekly" -> nextMatching(from) { weekdays.isEmpty() || it in weekdays }
+      "interval" -> when {
+        intervalMs <= 0 -> 0
+        timestamp > from -> timestamp
+        else -> timestamp + ((from - timestamp) / intervalMs + 1) * intervalMs
+      }
+      else -> if (timestamp > from) timestamp else 0
+    }
+  }
+
+  private fun nextMatching(from: Long, ok: (Int) -> Boolean): Long {
+    val base = Calendar.getInstance().apply { timeInMillis = timestamp }
+    val c = Calendar.getInstance().apply {
+      timeInMillis = from
+      set(Calendar.HOUR_OF_DAY, base.get(Calendar.HOUR_OF_DAY))
+      set(Calendar.MINUTE, base.get(Calendar.MINUTE))
+      set(Calendar.SECOND, 0)
+      set(Calendar.MILLISECOND, 0)
+    }
+    repeat(8) {
+      if (c.timeInMillis > from && ok(c.get(Calendar.DAY_OF_WEEK))) return c.timeInMillis
+      c.add(Calendar.DAY_OF_YEAR, 1)
+    }
+    return 0
+  }
+
+  fun toJson(): String = JSONObject().apply {
+    put("id", id); put("timestamp", timestamp); put("title", title); put("body", body)
+    put("sound", sound); put("vibrate", vibrate); put("snoozeEnabled", snoozeEnabled)
+    put("snoozeMinutes", snoozeMinutes); put("repeatType", repeatType)
+    put("weekdays", JSONArray(weekdays)); put("intervalMs", intervalMs)
+    put("data", data); put("enabled", enabled)
+  }.toString()
+
+  fun toWritableMap(): WritableMap = Arguments.createMap().apply {
+    putString("alarmId", id)
+    putDouble("timestamp", timestamp.toDouble())
+    putString("title", title)
+    putString("body", body)
+    putString("sound", sound)
+    putBoolean("vibrate", vibrate)
+    putBoolean("snoozeEnabled", snoozeEnabled)
+    putDouble("snoozeMinutes", snoozeMinutes.toDouble())
+    putMap("repeat", Arguments.createMap().apply {
+      putString("type", repeatType)
+      putArray("weekdays", Arguments.createArray().apply { weekdays.forEach { pushInt(it) } })
+      putDouble("intervalMs", intervalMs.toDouble())
+    })
+    putString("data", data)
+    putBoolean("enabled", enabled)
+    putDouble("nextTriggerAt", nextTrigger().toDouble())
+  }
+
+  /** Initial props for the React ring screen hosted by [AlarmRingActivity]. */
+  fun toBundle(): Bundle = Bundle().apply {
+    putString("alarmId", id)
+    putDouble("timestamp", timestamp.toDouble())
+    putString("title", title)
+    putString("body", body)
+    putBoolean("snoozeEnabled", snoozeEnabled)
+    putInt("snoozeMinutes", snoozeMinutes)
+    putString("data", data)
+  }
+
+  companion object {
+    fun fromJson(s: String): AlarmData {
+      val o = JSONObject(s)
+      val wd = o.optJSONArray("weekdays")
+      return AlarmData(
+        o.getString("id"), o.getLong("timestamp"), o.optString("title"), o.optString("body"),
+        o.optString("sound", "default"), o.optBoolean("vibrate", true),
+        o.optBoolean("snoozeEnabled", true), o.optInt("snoozeMinutes", 5),
+        o.optString("repeatType", "none"),
+        if (wd == null) emptyList() else (0 until wd.length()).map { wd.getInt(it) },
+        o.optLong("intervalMs", 0), o.optString("data"), o.optBoolean("enabled", true)
+      )
+    }
+
+    fun fromMap(m: ReadableMap, id: String): AlarmData {
+      val r = if (m.hasKey("repeat") && !m.isNull("repeat")) m.getMap("repeat") else null
+      val wd = r?.takeIf { it.hasKey("weekdays") }?.getArray("weekdays")
+        ?.let { a -> (0 until a.size()).map { a.getInt(it) } } ?: emptyList()
+      return AlarmData(
+        id = id,
+        timestamp = m.getDouble("timestamp").toLong(),
+        title = m.str("title"),
+        body = m.str("body"),
+        sound = m.str("sound", "default"),
+        vibrate = m.bool("vibrate", true),
+        snoozeEnabled = m.bool("snoozeEnabled", true),
+        snoozeMinutes = if (m.hasKey("snoozeMinutes")) m.getDouble("snoozeMinutes").toInt() else 5,
+        repeatType = r?.str("type", "none") ?: "none",
+        weekdays = wd,
+        intervalMs = if (r != null && r.hasKey("intervalMs")) r.getDouble("intervalMs").toLong() else 0,
+        data = m.str("data")
+      )
+    }
+
+    private fun ReadableMap.str(k: String, d: String = "") =
+      if (hasKey(k) && !isNull(k)) getString(k) ?: d else d
+
+    private fun ReadableMap.bool(k: String, d: Boolean) =
+      if (hasKey(k) && !isNull(k)) getBoolean(k) else d
+  }
+}

package/android/app/src/main/java/com/reactnativealarm/alarm/AlarmModule.kt

@@ -0,0 +1,263 @@
+package com.alarm
+
+import android.Manifest
+import android.app.NotificationManager
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.net.Uri
+import android.os.Build
+import android.provider.Settings
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.content.ContextCompat
+import com.facebook.react.bridge.*
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.facebook.react.modules.core.PermissionAwareActivity
+import java.lang.ref.WeakReference
+import java.util.UUID
+
+class AlarmModule(private val ctx: ReactApplicationContext) : ReactContextBaseJavaModule(ctx) {
+
+  init { instance = WeakReference(this) }
+
+  override fun getName() = NAME
+
+  override fun invalidate() {
+    if (instance?.get() === this) instance = null
+    super.invalidate()
+  }
+
+  // ---------- Permissions ----------
+
+  private fun notificationsGranted(): Boolean =
+    if (Build.VERSION.SDK_INT >= 33)
+      ContextCompat.checkSelfPermission(ctx, Manifest.permission.POST_NOTIFICATIONS) ==
+        PackageManager.PERMISSION_GRANTED
+    else NotificationManagerCompat.from(ctx).areNotificationsEnabled()
+
+  private fun canDrawOverlays(): Boolean = Settings.canDrawOverlays(ctx)
+
+  private fun canUseFullScreenIntent(): Boolean =
+    Build.VERSION.SDK_INT < 34 ||
+      ctx.getSystemService(NotificationManager::class.java).canUseFullScreenIntent()
+
+  private fun permissionMap(): WritableMap = Arguments.createMap().apply {
+    val ok = notificationsGranted()
+    putString("status", if (ok) "granted" else "denied")
+    putBoolean("notifications", ok)
+    putBoolean("canScheduleExact", AlarmScheduler.canScheduleExact(ctx))
+    putBoolean("canDrawOverlays", canDrawOverlays())
+    putBoolean("canUseFullScreenIntent", canUseFullScreenIntent())
+  }
+
+  private fun launchSettings(intent: Intent) {
+    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+    (ctx.currentActivity ?: ctx).startActivity(intent)
+  }
+
+  /**
+   * Opens the settings screen for the first missing special permission, in the order
+   * that matters most for a ringing alarm. Only one screen at a time; the caller
+   * re-checks and calls again if needed.
+   */
+  private fun openNextMissingSpecialPermission(): Boolean {
+    val pkg = Uri.parse("package:${ctx.packageName}")
+    return when {
+      // Android 12 only: on 13+ USE_EXACT_ALARM is granted automatically.
+      Build.VERSION.SDK_INT in 31..32 && !AlarmScheduler.canScheduleExact(ctx) -> {
+        launchSettings(Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM, pkg)); true
+      }
+      // "Display over other apps": lets the ringing service pop the alarm screen
+      // instantly, even from the background. The full-screen notification alone is
+      // unreliable on many devices (notably Xiaomi/MIUI).
+      !canDrawOverlays() -> {
+        launchSettings(Intent(Settings.ACTION_MANAGE_OVERLAY_PERMISSION, pkg)); true
+      }
+      // Android 14+: full-screen intents can be revoked per app.
+      !canUseFullScreenIntent() -> {
+        launchSettings(Intent(Settings.ACTION_MANAGE_APP_USE_FULL_SCREEN_INTENT).setData(pkg)); true
+      }
+      else -> false
+    }
+  }
+
+  /**
+   * OEM "Autostart" permission (Xiaomi/MIUI, Oppo, Vivo, Huawei...). Without it the
+   * system refuses to start the app's process to deliver the AlarmManager broadcast
+   * once the app has been killed, so the alarm silently never rings. There is no public
+   * API to query it; this opens the vendor settings screen when one exists.
+   * Resolves true if a screen was opened, false if this device has none.
+   */
+  @ReactMethod
+  fun openAutoStartSettings(promise: Promise) {
+    val candidates = listOf(
+      "com.miui.securitycenter" to "com.miui.permcenter.autostart.AutoStartManagementActivity",
+      "com.coloros.safecenter" to "com.coloros.safecenter.permission.startup.StartupAppListActivity",
+      "com.oppo.safe" to "com.oppo.safe.permission.startup.StartupAppListActivity",
+      "com.vivo.permissionmanager" to "com.vivo.permissionmanager.activity.BgStartUpManagerActivity",
+      "com.huawei.systemmanager" to "com.huawei.systemmanager.startupmgr.ui.StartupNormalAppListActivity",
+      "com.samsung.android.lool" to "com.samsung.android.sm.ui.battery.BatteryActivity",
+    )
+    for ((pkg, cls) in candidates) {
+      val intent = Intent().setComponent(android.content.ComponentName(pkg, cls))
+      if (ctx.packageManager.resolveActivity(intent, 0) == null) continue
+      try {
+        launchSettings(intent)
+        return promise.resolve(true)
+      } catch (_: Exception) { /* try the next one */ }
+    }
+    promise.resolve(false)
+  }
+
+  @ReactMethod
+  fun canScheduleExactAlarms(promise: Promise) =
+    promise.resolve(AlarmScheduler.canScheduleExact(ctx))
+
+  @ReactMethod
+  fun checkPermission(promise: Promise) = promise.resolve(permissionMap())
+
+  @ReactMethod
+  fun requestPermission(promise: Promise) {
+    val activity = ctx.currentActivity
+    if (Build.VERSION.SDK_INT >= 33 && !notificationsGranted() && activity is PermissionAwareActivity) {
+      activity.requestPermissions(arrayOf(Manifest.permission.POST_NOTIFICATIONS), 9871) { _, _, _ ->
+        openNextMissingSpecialPermission()
+        promise.resolve(permissionMap())
+        true
+      }
+      return
+    }
+    openNextMissingSpecialPermission()
+    promise.resolve(permissionMap())
+  }
+
+  // ---------- Scheduling ----------
+
+  @ReactMethod
+  fun scheduleAlarm(config: ReadableMap, promise: Promise) {
+    try {
+      val id = if (config.hasKey("alarmId") && !config.isNull("alarmId"))
+        config.getString("alarmId")!! else UUID.randomUUID().toString()
+      val alarm = AlarmData.fromMap(config, id)
+      AlarmScheduler.cancel(ctx, id)
+      AlarmStore.save(ctx, alarm)
+      AlarmScheduler.schedule(ctx, alarm)
+      promise.resolve(id)
+    } catch (e: Exception) {
+      promise.reject("E_SCHEDULE", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun updateAlarm(alarmId: String, config: ReadableMap, promise: Promise) {
+    try {
+      if (AlarmStore.get(ctx, alarmId) == null) return promise.resolve(false)
+      val alarm = AlarmData.fromMap(config, alarmId)
+      AlarmScheduler.cancel(ctx, alarmId)
+      AlarmStore.save(ctx, alarm)
+      AlarmScheduler.schedule(ctx, alarm)
+      promise.resolve(true)
+    } catch (e: Exception) {
+      promise.reject("E_UPDATE", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun cancelAlarm(alarmId: String, promise: Promise) {
+    val existed = AlarmStore.get(ctx, alarmId) != null
+    AlarmScheduler.cancel(ctx, alarmId)
+    if (AlarmService.current?.id == alarmId) AlarmService.dismiss(ctx)
+    AlarmStore.remove(ctx, alarmId)
+    promise.resolve(existed)
+  }
+
+  @ReactMethod
+  fun cancelAllAlarms(promise: Promise) {
+    AlarmStore.all(ctx).forEach { AlarmScheduler.cancel(ctx, it.id) }
+    AlarmService.dismiss(ctx)
+    AlarmStore.clear(ctx)
+    promise.resolve(null)
+  }
+
+  // ---------- Control (while ringing) ----------
+
+  @ReactMethod
+  fun stopAlarm(alarmId: String, promise: Promise) {
+    AlarmService.dismiss(ctx)
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  fun snoozeAlarm(alarmId: String, minutes: Double, promise: Promise) {
+    val ringing = AlarmService.current
+    if (ringing != null) {
+      AlarmService.snooze(ctx, minutes.toInt())
+      return promise.resolve(null)
+    }
+    // Not ringing: schedule a one-off snooze for a stored alarm.
+    val alarm = AlarmStore.get(ctx, alarmId)
+      ?: return promise.reject("E_NOT_FOUND", "Alarm $alarmId not found")
+    try {
+      AlarmScheduler.scheduleSnooze(ctx, alarm, minutes.toInt())
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("E_SNOOZE", e.message, e)
+    }
+  }
+
+  /** The alarm currently ringing (if any), so JS can show the ring UI on launch. */
+  @ReactMethod
+  fun getRingingAlarm(promise: Promise) =
+    promise.resolve(AlarmService.current?.toWritableMap())
+
+  // ---------- Queries ----------
+
+  @ReactMethod
+  fun getAlarm(alarmId: String, promise: Promise) =
+    promise.resolve(AlarmStore.get(ctx, alarmId)?.toWritableMap())
+
+  @ReactMethod
+  fun getAllAlarms(promise: Promise) {
+    val arr = Arguments.createArray()
+    AlarmStore.all(ctx).sortedBy { it.timestamp }.forEach { arr.pushMap(it.toWritableMap()) }
+    promise.resolve(arr)
+  }
+
+  @ReactMethod
+  fun isScheduled(alarmId: String, promise: Promise) {
+    val a = AlarmStore.get(ctx, alarmId)
+    promise.resolve(a != null && a.enabled && a.nextTrigger() > 0)
+  }
+
+  // ---------- Events ----------
+
+  // Required by NativeEventEmitter on the JS side.
+  @ReactMethod fun addListener(eventName: String) {}
+  @ReactMethod fun removeListeners(count: Double) {}
+
+  private fun send(eventName: String, a: AlarmData) {
+    if (!ctx.hasActiveReactInstance()) return
+    val map = Arguments.createMap().apply {
+      putString("alarmId", a.id)
+      putDouble("timestamp", System.currentTimeMillis().toDouble())
+      putString("title", a.title)
+      putString("body", a.body)
+      putString("data", a.data)
+    }
+    ctx.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java).emit(eventName, map)
+  }
+
+  companion object {
+    const val NAME = "Alarm"
+    const val EVENT_FIRED = "onAlarmFired"
+    const val EVENT_DISMISSED = "onAlarmDismissed"
+    const val EVENT_SNOOZED = "onAlarmSnoozed"
+
+    private var instance: WeakReference<AlarmModule>? = null
+
+    /** Called from native alarm code; no-op if the JS runtime isn't alive. */
+    fun emit(eventName: String, a: AlarmData) {
+      val module = instance?.get() ?: return
+      runCatching { module.send(eventName, a) }
+    }
+  }
+}