react-native-alarms 0.0.9 → 0.0.10

package/README.md

@@ -193,6 +193,20 @@ unsubscribeDismissed();
 unsubscribeSnoozed();
 ```
 
+Alarm events are delivered to JavaScript only while the native module and JS
+runtime are active; they are not a durable event queue. On app startup, query
+`getRingingAlarm()` to recover an alarm that started while the app was closed:
+
+```typescript
+const ringingAlarm = await AlarmService.getRingingAlarm();
+if (ringingAlarm) {
+  // Restore any app-level state needed for the currently ringing alarm.
+}
+```
+
+Register event listeners as part of app initialization to receive subsequent
+transitions. Native ring-screen presentation is independent of JS event delivery.
+
 ### Managing Alarms
 
 ```typescript
@@ -240,7 +254,7 @@ type AlarmConfig = {
   title: string;              // Alarm title/label
   body?: string;              // Alarm description
   image?: string;             // file:// or https:// image URI for ring screen/notifications
-  sound?: string;             // 'default' or custom sound file name
+  sound?: string;             // 'default' or a bundled sound filename, e.g. 'bell.wav'
   vibrate?: boolean;          // Enable vibration (Android only)
   snoozeEnabled?: boolean;    // Allow snoozing
   snoozeMinutes?: number;     // Snooze duration in minutes
@@ -278,6 +292,28 @@ AlarmKit system alert itself does not display custom images, but the image URI i
 available to the React Native ring screen when it opens. Render it in that screen
 with React Native's `Image` component and `source={{ uri: image }}`.
 
+#### Custom alarm sound
+
+Set `sound` to the same bundled filename on both platforms. For example, with
+`sound: 'bell.wav'`, include `bell.wav` in the iOS app target's Copy Bundle
+Resources and add it to Android at
+`android/app/src/main/res/raw/bell.wav` (create the `raw` directory if needed).
+Android raw resource filenames must be lowercase and use only letters, numbers,
+and underscores. iOS notification sounds must use a supported audio format and
+meet Apple's notification sound duration and size limits.
+
+```ts
+await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 60_000,
+  title: 'Wake up',
+  sound: 'bell.wav',
+});
+```
+
+The alarm uses the custom sound when the file is bundled for that platform.
+Otherwise, including when `sound` is omitted or set to `'default'`, it uses the
+platform's default alarm sound.
+
 > **How the native layer stores these:** `AlarmConfig.presentation` is resolved by `AlarmService` before being handed off to the native module. The resulting fields stored in the native `AlarmData` model are:
 >
 > | Field | Type | Default | Description |

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

@@ -138,9 +138,7 @@ class AlarmModule(private val ctx: ReactApplicationContext) : ReactContextBaseJa
       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)
+      scheduleReplacing(alarm)
       promise.resolve(id)
     } catch (e: Exception) {
       promise.reject("E_SCHEDULE", e.message, e)
@@ -152,15 +150,39 @@ class AlarmModule(private val ctx: ReactApplicationContext) : ReactContextBaseJa
     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)
+      scheduleReplacing(alarm)
       promise.resolve(true)
     } catch (e: Exception) {
       promise.reject("E_UPDATE", e.message, e)
     }
   }
 
+  private fun scheduleReplacing(alarm: AlarmData) {
+    val previous = AlarmStore.get(ctx, alarm.id)
+    AlarmScheduler.cancel(ctx, alarm.id)
+    try {
+      AlarmStore.save(ctx, alarm)
+      AlarmScheduler.schedule(ctx, alarm)
+    } catch (error: Exception) {
+      AlarmScheduler.cancel(ctx, alarm.id)
+      if (previous == null) {
+        AlarmStore.remove(ctx, alarm.id)
+      } else {
+        AlarmStore.save(ctx, previous)
+        try {
+          AlarmScheduler.schedule(ctx, previous)
+        } catch (restoreError: Exception) {
+          android.util.Log.e(
+            "AlarmModule",
+            "Could not restore alarm ${alarm.id} after scheduling failed",
+            restoreError
+          )
+        }
+      }
+      throw error
+    }
+  }
+
   @ReactMethod
   fun cancelAlarm(alarmId: String, promise: Promise) {
     val existed = AlarmStore.get(ctx, alarmId) != null
@@ -182,14 +204,14 @@ class AlarmModule(private val ctx: ReactApplicationContext) : ReactContextBaseJa
 
   @ReactMethod
   fun stopAlarm(alarmId: String, promise: Promise) {
-    AlarmService.dismiss(ctx)
+    if (AlarmService.current?.id == alarmId) AlarmService.dismiss(ctx)
     promise.resolve(null)
   }
 
   @ReactMethod
   fun snoozeAlarm(alarmId: String, minutes: Double, promise: Promise) {
     val ringing = AlarmService.current
-    if (ringing != null) {
+    if (ringing?.id == alarmId) {
       AlarmService.snooze(ctx, minutes.toInt())
       return promise.resolve(null)
     }

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

@@ -153,13 +153,55 @@ class AlarmService : Service() {
   // ---- Sound ----
 
   private fun startSound(alarm: AlarmData) {
-    val uri = alarm.sound.takeIf { it.isNotBlank() && it != "default" }?.let { Uri.parse(it) }
-      ?: RingtoneManager.getDefaultUri(RingtoneManager.TYPE_ALARM)
+    val customUri = customSoundUri(alarm.sound)
+    if (customUri != null) {
+      try {
+        playSound(customUri)
+        return
+      } catch (e: Exception) {
+        Log.w(TAG, "Could not play custom alarm sound $customUri; using the default sound", e)
+      }
+    }
+
+    val defaultUri = RingtoneManager.getDefaultUri(RingtoneManager.TYPE_ALARM)
       ?: RingtoneManager.getDefaultUri(RingtoneManager.TYPE_RINGTONE)
+    if (defaultUri == null) {
+      Log.e(TAG, "No default alarm or ringtone sound is available")
+      startVibration()
+      return
+    }
+    try {
+      playSound(defaultUri)
+    } catch (e: Exception) {
+      Log.e(TAG, "Could not play default alarm sound $defaultUri", e)
+      startVibration() // last resort: at least wake the user somehow
+    }
+  }
 
+  private fun customSoundUri(sound: String): Uri? {
+    if (sound.isBlank() || sound == "default") return null
+
+    val parsed = Uri.parse(sound)
+    if (parsed.scheme != null) return parsed
+
+    val filename = sound.substringAfterLast('/')
+    val resourceName = filename.substringBeforeLast('.', filename)
+    if (filename != sound || !resourceName.matches(Regex("[a-z][a-z0-9_]*"))) {
+      Log.w(TAG, "Invalid custom alarm sound name '$sound'; using the default sound")
+      return null
+    }
+
+    val resourceId = resources.getIdentifier(resourceName, "raw", packageName)
+    if (resourceId == 0) {
+      Log.w(TAG, "Custom alarm sound '$sound' was not found; using the default sound")
+      return null
+    }
+    return Uri.parse("android.resource://$packageName/$resourceId")
+  }
+
+  private fun playSound(uri: Uri) {
+    val mp = MediaPlayer()
     try {
-      val mp = MediaPlayer()
-      player = mp
       mp.apply {
         setAudioAttributes(
           AudioAttributes.Builder()
@@ -172,11 +214,10 @@ class AlarmService : Service() {
         prepare()
         start()
       }
-    } catch (e: Exception) {
-      Log.e(TAG, "Could not play $uri, vibrating only", e)
-      runCatching { player?.release() }
-      player = null
-      startVibration() // last resort: at least wake the user somehow
+      player = mp
+    } catch (error: Exception) {
+      mp.release()
+      throw error
     }
   }
 

package/ios/alarm/AlarmData.swift

@@ -35,6 +35,23 @@ struct AlarmData: Codable {
 
         return props
     }
+
+  var bundledSoundName: String? {
+    guard !sound.isEmpty, sound != "default",
+          URL(fileURLWithPath: sound).lastPathComponent == sound else {
+      return nil
+    }
+
+    let filename = URL(fileURLWithPath: sound)
+    let name = filename.deletingPathExtension().lastPathComponent
+    let fileExtension = filename.pathExtension
+    guard !name.isEmpty, !fileExtension.isEmpty,
+          Bundle.main.url(forResource: name, withExtension: fileExtension) != nil else {
+      return nil
+    }
+
+    return sound
+  }
   
   /// Next time this alarm should ring, in ms since epoch, or 0 if never.
   func nextTrigger(from: Double = AlarmData.now()) -> Double {

package/ios/alarm/AlarmKitBackend.swift

@@ -138,8 +138,12 @@ final class AlarmKitBackend {
       metadata: RNAlarmMetadata(),
       tintColor: .blue
     )
-    let sound: AlertConfiguration.AlertSound =
-    (a.sound.isEmpty || a.sound == "default") ? .default : .named(a.sound)
+    let sound: AlertConfiguration.AlertSound
+    if let soundName = a.bundledSoundName {
+      sound = .named(soundName)
+    } else {
+      sound = .default
+    }
     
     return AlarmManager.AlarmConfiguration(
       schedule: schedule,

package/ios/alarm/AlarmModule.swift

@@ -17,6 +17,11 @@ final class AlarmModule: RCTEventEmitter {
   
   private var hasListeners = false
   private var activeObserver: NSObjectProtocol?
+  private struct ScheduleTransaction {
+    let token: UUID
+    let original: AlarmData?
+  }
+  private var scheduleTransactions: [String: ScheduleTransaction] = [:]
   
   override init() {
     super.init()
@@ -95,7 +100,10 @@ final class AlarmModule: RCTEventEmitter {
     return false
   }
   
-  private func cancelNative(_ id: String) {
+  private func cancelNative(_ id: String, preserveScheduleTransaction: Bool = false) {
+    if !preserveScheduleTransaction {
+      scheduleTransactions.removeValue(forKey: id)
+    }
     AlarmRingPresenter.dismiss(id)
     NotificationBackend.shared.cancel(id)
 #if canImport(AlarmKit)
@@ -203,19 +211,51 @@ final class AlarmModule: RCTEventEmitter {
     arm(AlarmData.from(config: dict, id: alarmId), code: "E_UPDATE", reject: reject) { resolve(true) }
   }
   
-  /// Cancel → persist → schedule, the same sequence as Android.
+  /// Replaces the persisted alarm only after the platform scheduler accepts it.
   private func arm(_ alarm: AlarmData, code: String, reject: @escaping RCTPromiseRejectBlock, done: @escaping () -> Void) {
-    cancelNative(alarm.id)
+    let original = scheduleTransactions[alarm.id].map { $0.original } ?? AlarmStore.get(alarm.id)
+    let token = UUID()
+    cancelNative(alarm.id, preserveScheduleTransaction: true)
+    scheduleTransactions[alarm.id] = ScheduleTransaction(token: token, original: original)
     AlarmStore.save(alarm)
-    
+
+    scheduleNative(alarm) { error in
+      guard self.scheduleTransactions[alarm.id]?.token == token else {
+        reject("E_CANCELLED", "Alarm scheduling was superseded or cancelled", nil)
+        return
+      }
+      guard let error else {
+        self.scheduleTransactions.removeValue(forKey: alarm.id)
+        done()
+        return
+      }
+
+      self.cancelNative(alarm.id, preserveScheduleTransaction: true)
+      if let original {
+        AlarmStore.save(original)
+        self.scheduleNative(original) { restoreError in
+          if let restoreError {
+            NSLog("[react-native-alarms] Could not restore alarm %@ after scheduling failed: %@",
+                  alarm.id, restoreError.localizedDescription)
+          }
+        }
+      } else {
+        AlarmStore.remove(alarm.id)
+      }
+      self.scheduleTransactions.removeValue(forKey: alarm.id)
+      reject(code, error.localizedDescription, error)
+    }
+  }
+
+  private func scheduleNative(_ alarm: AlarmData, completion: @escaping (Error?) -> Void) {
 #if canImport(AlarmKit)
     if #available(iOS 26.0, *), useAlarmKit {
       Task {
         do {
           try await AlarmKitBackend.shared.schedule(alarm)
-          done()
+          completion(nil)
         } catch {
-          reject(code, error.localizedDescription, error)
+          completion(error)
         }
       }
       return
@@ -224,11 +264,15 @@ final class AlarmModule: RCTEventEmitter {
     
     NotificationBackend.shared.status { status in
       guard status == "granted" else {
-        // Mirrors Android's SecurityException when the exact-alarm permission is missing.
-        return reject(code, "Alarm permission not granted; call requestPermission() first", nil)
+        let error = NSError(
+          domain: "ReactNativeAlarms",
+          code: 1,
+          userInfo: [NSLocalizedDescriptionKey: "Alarm permission not granted; call requestPermission() first"]
+        )
+        return completion(error)
       }
       NotificationBackend.shared.schedule(alarm) { error in
-        if let error { reject(code, error.localizedDescription, error) } else { done() }
+        completion(error)
       }
     }
   }

package/ios/alarm/NotificationBackend.swift

@@ -23,6 +23,8 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
   
   /// The alarm whose notification is currently being shown (foreground) or was tapped.
   private(set) var ringing: AlarmData?
+  private var imageScheduleTokens: [String: UUID] = [:]
+  private let imageScheduleTokensLock = NSLock()
   /// Wired by `AlarmModule` so native events reach JS.
   var onEvent: ((String, AlarmData) -> Void)?
   
@@ -86,9 +88,9 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     c.categoryIdentifier = Self.category
     c.userInfo = ["alarmId": a.id, "image": a.image ?? ""]
     if let attachment { c.attachments = [attachment] }
-    c.sound = (a.sound.isEmpty || a.sound == "default")
-    ? .default
-    : UNNotificationSound(named: UNNotificationSoundName(rawValue: a.sound))
+    c.sound = a.bundledSoundName.map {
+      UNNotificationSound(named: UNNotificationSoundName(rawValue: $0))
+    } ?? .default
     // Breaks through Focus when the Time Sensitive Notifications capability is enabled;
     // silently downgraded to a normal notification otherwise.
     c.interruptionLevel = .timeSensitive
@@ -102,7 +104,12 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
   
   func schedule(_ a: AlarmData, completion: @escaping (Error?) -> Void) {
     cancel(a.id)
+    let token = UUID()
+    setImageScheduleToken(token, for: a.id)
     prepareAttachment(for: a.image) { attachment in
+      guard self.hasImageScheduleToken(token, for: a.id) else {
+        return completion(CancellationError())
+      }
       let cal = Calendar.current
       let base = Self.prefix + a.id
       let hm = cal.dateComponents([.hour, .minute], from: a.date)
@@ -141,7 +148,7 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
         requests.append(self.request(base, a, self.exactTrigger(ms: next), attachment))
       }
 
-      self.add(requests, completion: completion)
+      self.add(requests, alarmId: a.id, token: token, completion: completion)
     }
   }
 
@@ -165,7 +172,9 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
       return completion(nil)
     }
 
-    URLSession.shared.downloadTask(with: url) { temporaryURL, response, error in
+    var request = URLRequest(url: url)
+    request.timeoutInterval = 15
+    URLSession.shared.downloadTask(with: request) { temporaryURL, response, error in
       guard let temporaryURL, error == nil else {
         NSLog("[react-native-alarms] Could not download alarm image: %@", error?.localizedDescription ?? "empty response")
         return completion(nil)
@@ -195,26 +204,69 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     return UNCalendarNotificationTrigger(dateMatching: dc, repeats: false)
   }
   
-  private func add(_ requests: [UNNotificationRequest], completion: @escaping (Error?) -> Void) {
+  private func add(
+    _ requests: [UNNotificationRequest],
+    alarmId: String,
+    token: UUID,
+    completion: @escaping (Error?) -> Void
+  ) {
     let group = DispatchGroup()
+    let errorLock = NSLock()
     var firstError: Error?
     for r in requests {
       group.enter()
       center.add(r) { error in
+        errorLock.lock()
         if firstError == nil { firstError = error }
+        errorLock.unlock()
         group.leave()
       }
     }
-    group.notify(queue: .main) { completion(firstError) }
+    group.notify(queue: .main) {
+      guard self.hasImageScheduleToken(token, for: alarmId) else {
+        self.center.removePendingNotificationRequests(withIdentifiers: requests.map(\.identifier))
+        return completion(CancellationError())
+      }
+      errorLock.lock()
+      let error = firstError
+      errorLock.unlock()
+      completion(error)
+    }
+  }
+
+  private func setImageScheduleToken(_ token: UUID, for alarmId: String) {
+    imageScheduleTokensLock.lock()
+    imageScheduleTokens[alarmId] = token
+    imageScheduleTokensLock.unlock()
+  }
+
+  private func hasImageScheduleToken(_ token: UUID, for alarmId: String) -> Bool {
+    imageScheduleTokensLock.lock()
+    defer { imageScheduleTokensLock.unlock() }
+    return imageScheduleTokens[alarmId] == token
   }
   
   /// One-off re-ring in `minutes`, equivalent to Android's `AlarmScheduler.scheduleSnooze`.
   func snooze(_ a: AlarmData, minutes: Int) {
     center.removeDeliveredNotifications(withIdentifiers: ids(for: a.id))
     let trigger = UNTimeIntervalNotificationTrigger(timeInterval: Double(max(1, minutes)) * 60, repeats: false)
+    let token = UUID()
+    setImageScheduleToken(token, for: a.id)
     prepareAttachment(for: a.image) { attachment in
-      self.center.add(self.request(Self.prefix + a.id + ":snooze", a, trigger, attachment))
-      if self.ringing?.id == a.id { self.ringing = nil }
+      guard self.hasImageScheduleToken(token, for: a.id) else { return }
+      let request = self.request(Self.prefix + a.id + ":snooze", a, trigger, attachment)
+      self.center.add(request) { error in
+        guard self.hasImageScheduleToken(token, for: a.id) else {
+          self.center.removePendingNotificationRequests(withIdentifiers: [request.identifier])
+          return
+        }
+        if let error {
+          NSLog("[react-native-alarms] Could not schedule snooze for %@: %@",
+                a.id, error.localizedDescription)
+        } else if self.ringing?.id == a.id {
+          self.ringing = nil
+        }
+      }
     }
   }
   
@@ -225,12 +277,16 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
   }
   
   func cancel(_ id: String) {
+    setImageScheduleToken(UUID(), for: id)
     center.removePendingNotificationRequests(withIdentifiers: ids(for: id))
     center.removeDeliveredNotifications(withIdentifiers: ids(for: id))
     if ringing?.id == id { ringing = nil }
   }
   
   func cancelAll() {
+    imageScheduleTokensLock.lock()
+    imageScheduleTokens.removeAll()
+    imageScheduleTokensLock.unlock()
     center.getPendingNotificationRequests { (requests: [UNNotificationRequest]) in
       let ours = requests.map { $0.identifier }.filter { $0.hasPrefix(Self.prefix) }
       self.center.removePendingNotificationRequests(withIdentifiers: ours)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-alarms",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "A powerful, cross-platform alarm management library for React Native",
   "private": false,
   "main": "index.ts",

package/src/types/index.ts

@@ -98,9 +98,11 @@ export type AlarmConfig = {
   image?: string;
 
   /**
-   * Alarm sound.
+   * Alarm sound file name, such as `"bell.wav"`.
    *
-   * Use `"default"` or a bundled sound file name.
+   * Bundle the same filename with the iOS app and place it in Android's
+   * `android/app/src/main/res/raw` directory. Uses the system default if
+   * omitted, set to `"default"`, or the file is unavailable.
    */
   sound?: string;