react-native-alarms 0.0.6 → 0.0.7

package/ios/alarm/AlarmRingPresenter.swift

@@ -8,12 +8,15 @@ import UIKit
 /// so this shows when the alarm fires while the app is in the foreground, or when the
 /// user opens the app by tapping the alarm notification.
 final class AlarmRingPresenter {
-  static let componentName = "AlarmRing"
-
+  private static let defaultComponentName = "AlarmRing"
+  
   private static weak var controller: UIViewController?
   private static var alarmId: String?
-
-  static func present(_ alarm: AlarmData, bridge: RCTBridge?, attempt: Int = 0) {
+  
+  static func present(_ alarm: AlarmData, bridge: RCTBridge?,
+                      componentName: String = defaultComponentName,
+                      componentProps: [String: Any] = [:],
+                      attempt: Int = 0) {
     DispatchQueue.main.async {
       if controller != nil, alarmId == alarm.id {
         // Already showing (e.g. presented while backgrounded, now foregrounded):
@@ -23,7 +26,9 @@ final class AlarmRingPresenter {
       }
       // Cold start from a notification tap or the AlarmKit "Open" button: the root
       // surface or window may not be ready yet, so retry for up to ~15 s.
-      guard let surface = makeSurface(bridge, props: alarm.toDictionary()),
+      guard let surface = makeSurface(bridge,
+                                      componentName: componentName,
+                                      props: alarm.toDictionary()),
             let top = topViewController() else {
         if attempt < 60 {
           DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {
@@ -34,7 +39,7 @@ final class AlarmRingPresenter {
         }
         return
       }
-
+      
       let vc = UIViewController()
       let root = RCTSurfaceHostingProxyRootView(surface: surface)
       root.backgroundColor = .systemBackground
@@ -42,7 +47,7 @@ final class AlarmRingPresenter {
       surface.start()
       vc.modalPresentationStyle = .fullScreen
       vc.isModalInPresentation = true
-
+      
       let show = {
         top.present(vc, animated: true)
         controller = vc
@@ -56,7 +61,7 @@ final class AlarmRingPresenter {
       }
     }
   }
-
+  
   /// The ring screen speaks the task via TTS, and iOS won't play it over the
   /// notification / AlarmKit sound, so stop that sound once the screen is up.
   /// Only while the app is frontmost: in the background the system alert is the
@@ -64,11 +69,11 @@ final class AlarmRingPresenter {
   private static func silenceIfActive(_ id: String) {
     guard UIApplication.shared.applicationState == .active else { return }
     NotificationBackend.shared.silence(id)
-    #if canImport(AlarmKit)
+#if canImport(AlarmKit)
     if #available(iOS 26.0, *) { AlarmKitBackend.shared.silence(id) }
-    #endif
+#endif
   }
-
+  
   /// Called when ringing ends for any reason (stop, snooze, cancel).
   static func dismiss(_ id: String? = nil) {
     DispatchQueue.main.async {
@@ -78,18 +83,20 @@ final class AlarmRingPresenter {
       vc.dismiss(animated: true)
     }
   }
-
+  
   private static let createSurface = NSSelectorFromString("createFabricSurfaceForModuleName:initialProperties:")
-
+  
   /// `RCTSurfacePresenter` implements `createFabricSurfaceForModuleName:initialProperties:`
   /// without formally adopting `RCTSurfacePresenterStub`, and its header is ObjC++ (not
   /// importable from Swift), so call it by selector.
-  private static func makeSurface(_ bridge: RCTBridge?, props: [String: Any]) -> RCTSurfaceProtocol? {
+  private static func makeSurface(_ bridge: RCTBridge?,
+                                  componentName: String,
+                                  props: [String: Any]) -> RCTSurfaceProtocol? {
     guard let presenter = surfacePresenter(bridge), presenter.responds(to: createSurface) else { return nil }
     return presenter.perform(createSurface, with: componentName, with: props)?
       .takeUnretainedValue() as? RCTSurfaceProtocol
   }
-
+  
   /// Bridgeless mode skips `bridge.surfacePresenter` (and injection) for modules
   /// registered with `RCT_EXTERN_MODULE`, so fall back to the presenter of the app's
   /// root React surface, which `RCTFabricSurface` keeps in a weak `_surfacePresenter` ivar.
@@ -99,10 +106,10 @@ final class AlarmRingPresenter {
           let hosting = findHostingView(in: root),
           let surface = hosting.surface as AnyObject?,
           let ivar = class_getInstanceVariable(type(of: surface), "_surfacePresenter")
-    else { return nil }
+            else { return nil }
     return object_getIvar(surface, ivar) as? NSObject
   }
-
+  
   private static func findHostingView(in view: UIView) -> RCTSurfaceHostingView? {
     if let hosting = view as? RCTSurfaceHostingView { return hosting }
     for sub in view.subviews {
@@ -110,14 +117,14 @@ final class AlarmRingPresenter {
     }
     return nil
   }
-
+  
   private static func keyWindow() -> UIWindow? {
     UIApplication.shared.connectedScenes
       .compactMap { $0 as? UIWindowScene }
       .flatMap { $0.windows }
       .first { $0.isKeyWindow }
   }
-
+  
   private static func topViewController() -> UIViewController? {
     var top = keyWindow()?.rootViewController
     while let presented = top?.presentedViewController { top = presented }

package/ios/alarm/AlarmStore.swift

@@ -4,45 +4,45 @@ import Foundation
 enum AlarmStore {
   private static let key = "RNAlarm.alarms"
   private static let lock = NSLock()
-
+  
   static func all() -> [AlarmData] {
     lock.lock(); defer { lock.unlock() }
     return Array(load().values)
   }
-
+  
   static func get(_ id: String) -> AlarmData? {
     lock.lock(); defer { lock.unlock() }
     return load()[id]
   }
-
+  
   static func save(_ alarm: AlarmData) {
     lock.lock(); defer { lock.unlock() }
     var map = load()
     map[alarm.id] = alarm
     persist(map)
   }
-
+  
   static func remove(_ id: String) {
     lock.lock(); defer { lock.unlock() }
     var map = load()
     map.removeValue(forKey: id)
     persist(map)
   }
-
+  
   static func clear() {
     lock.lock(); defer { lock.unlock() }
     persist([:])
   }
-
+  
   // MARK: - Private
-
+  
   private static func load() -> [String: AlarmData] {
     guard let data = UserDefaults.standard.data(forKey: key),
           let map = try? JSONDecoder().decode([String: AlarmData].self, from: data)
-    else { return [:] }
+            else { return [:] }
     return map
   }
-
+  
   private static func persist(_ map: [String: AlarmData]) {
     if let data = try? JSONEncoder().encode(map) {
       UserDefaults.standard.set(data, forKey: key)

package/ios/alarm/NotificationBackend.swift

@@ -10,25 +10,25 @@ import UserNotifications
 @objc(RNAlarmNotificationBackend)
 final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
   static let shared = NotificationBackend()
-
+  
   static let category = "RN_ALARM"
   static let actionSnooze = "RN_ALARM_SNOOZE"
   static let actionStop = "RN_ALARM_STOP"
   private static let prefix = "rnalarm:"
   /// How many `interval` occurrences to pre-schedule (iOS caps pending requests at 64).
   private static let intervalOccurrences = 12
-
+  
   private let center = UNUserNotificationCenter.current()
-
+  
   /// The alarm whose notification is currently being shown (foreground) or was tapped.
   private(set) var ringing: AlarmData?
   /// Wired by `AlarmModule` so native events reach JS.
   var onEvent: ((String, AlarmData) -> Void)?
-
+  
   /// Delegate that was installed before us (e.g. Notifee); non-alarm notifications go to it.
   private weak var previousDelegate: UNUserNotificationCenterDelegate?
   private static var installed = false
-
+  
   /// Installs the delegate and actions. Call once at launch so a tap on a
   /// notification that starts the app is delivered to the module.
   @objc static func install() {
@@ -51,9 +51,9 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
       ),
     ])
   }
-
+  
   // MARK: - Permission
-
+  
   /// 'granted' | 'denied' | 'notDetermined', same vocabulary as Android.
   func status(_ completion: @escaping (String) -> Void) {
     center.getNotificationSettings { settings in
@@ -64,20 +64,20 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
       }
     }
   }
-
+  
   func request(_ completion: @escaping (Bool) -> Void) {
     center.requestAuthorization(options: [.alert, .sound, .badge]) { ok, _ in completion(ok) }
   }
-
+  
   // MARK: - Scheduling
-
+  
   private func ids(for alarmId: String) -> [String] {
     let base = Self.prefix + alarmId
     return [base, base + ":snooze"]
-      + (1...7).map { base + ":wd\($0)" }
-      + (0..<Self.intervalOccurrences).map { base + ":i\($0)" }
+    + (1...7).map { base + ":wd\($0)" }
+    + (0..<Self.intervalOccurrences).map { base + ":i\($0)" }
   }
-
+  
   private func content(for a: AlarmData) -> UNMutableNotificationContent {
     let c = UNMutableNotificationContent()
     c.title = a.title.isEmpty ? "Alarm" : a.title
@@ -85,32 +85,32 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     c.categoryIdentifier = Self.category
     c.userInfo = ["alarmId": a.id]
     c.sound = (a.sound.isEmpty || a.sound == "default")
-      ? .default
-      : UNNotificationSound(named: UNNotificationSoundName(rawValue: a.sound))
+    ? .default
+    : UNNotificationSound(named: UNNotificationSoundName(rawValue: a.sound))
     // Breaks through Focus when the Time Sensitive Notifications capability is enabled;
     // silently downgraded to a normal notification otherwise.
     c.interruptionLevel = .timeSensitive
     return c
   }
-
+  
   private func request(_ id: String, _ a: AlarmData, _ trigger: UNNotificationTrigger) -> UNNotificationRequest {
     UNNotificationRequest(identifier: id, content: content(for: a), trigger: trigger)
   }
-
+  
   func schedule(_ a: AlarmData, completion: @escaping (Error?) -> Void) {
     cancel(a.id)
     let cal = Calendar.current
     let base = Self.prefix + a.id
     let hm = cal.dateComponents([.hour, .minute], from: a.date)
     var requests: [UNNotificationRequest] = []
-
+    
     switch a.repeatType {
     case "daily":
       var dc = DateComponents()
       dc.hour = hm.hour
       dc.minute = hm.minute
       requests.append(request(base, a, UNCalendarNotificationTrigger(dateMatching: dc, repeats: true)))
-
+      
     case "weekly":
       let days = a.weekdays.isEmpty ? Array(1...7) : a.weekdays.filter { (1...7).contains($0) }
       for d in days {
@@ -120,7 +120,7 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
         dc.minute = hm.minute
         requests.append(request(base + ":wd\(d)", a, UNCalendarNotificationTrigger(dateMatching: dc, repeats: true)))
       }
-
+      
     case "interval":
       // iOS repeating interval triggers count from "now", not from `timestamp`, so
       // pre-schedule the next N exact occurrences instead.
@@ -130,16 +130,16 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
         requests.append(request(base + ":i\(k)", a, exactTrigger(ms: t)))
         t += a.intervalMs
       }
-
+      
     default:
       let next = a.nextTrigger()
       guard next > 0 else { return completion(nil) } // nothing in the future, same as Android
       requests.append(request(base, a, exactTrigger(ms: next)))
     }
-
+    
     add(requests, completion: completion)
   }
-
+  
   private func exactTrigger(ms: Double) -> UNCalendarNotificationTrigger {
     let dc = Calendar.current.dateComponents(
       [.year, .month, .day, .hour, .minute, .second],
@@ -147,7 +147,7 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     )
     return UNCalendarNotificationTrigger(dateMatching: dc, repeats: false)
   }
-
+  
   private func add(_ requests: [UNNotificationRequest], completion: @escaping (Error?) -> Void) {
     let group = DispatchGroup()
     var firstError: Error?
@@ -160,7 +160,7 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     }
     group.notify(queue: .main) { completion(firstError) }
   }
-
+  
   /// 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))
@@ -168,19 +168,19 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     center.add(request(Self.prefix + a.id + ":snooze", a, trigger))
     if ringing?.id == a.id { ringing = nil }
   }
-
+  
   /// Stops the notification's sound (by clearing the delivered notification) while the
   /// in-app ring screen takes over; `ringing` stays set so the session is still live.
   func silence(_ id: String) {
     center.removeDeliveredNotifications(withIdentifiers: ids(for: id))
   }
-
+  
   func cancel(_ id: String) {
     center.removePendingNotificationRequests(withIdentifiers: ids(for: id))
     center.removeDeliveredNotifications(withIdentifiers: ids(for: id))
     if ringing?.id == id { ringing = nil }
   }
-
+  
   func cancelAll() {
     center.getPendingNotificationRequests { (requests: [UNNotificationRequest]) in
       let ours = requests.map { $0.identifier }.filter { $0.hasPrefix(Self.prefix) }
@@ -192,7 +192,7 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     }
     ringing = nil
   }
-
+  
   /// Dismiss: clear the shown notification and, like Android, drop a pending snooze.
   func stop(_ id: String) {
     center.removeDeliveredNotifications(withIdentifiers: ids(for: id))
@@ -202,14 +202,14 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
       onEvent?(AlarmModule.eventDismissed, a)
     }
   }
-
+  
   // MARK: - UNUserNotificationCenterDelegate
-
+  
   private func alarm(from notification: UNNotification) -> AlarmData? {
     guard let id = notification.request.content.userInfo["alarmId"] as? String else { return nil }
     return AlarmStore.get(id)
   }
-
+  
   func userNotificationCenter(
     _ center: UNUserNotificationCenter,
     willPresent notification: UNNotification,
@@ -229,7 +229,7 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     // The ring screen takes over; keep the sound but skip the banner when it can show.
     completionHandler(onEvent == nil ? [.banner, .list, .sound] : [.list, .sound])
   }
-
+  
   func userNotificationCenter(
     _ center: UNUserNotificationCenter,
     didReceive response: UNNotificationResponse,

package/package.json

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

package/specs/NativeAlarm.ts

@@ -1,97 +1,130 @@
 import type { TurboModule } from 'react-native';
 import { NativeModules, Platform, TurboModuleRegistry } from 'react-native';
+import { AlarmPermission, AlarmConfig, AlarmProp } from '../src/types';
 
 /**
- * Shared contract of the native `Alarm` module.
- *
- * Both platforms register a legacy-style module named `Alarm` with these exact
- * method names (Android: AlarmModule.kt, iOS: ios/alarm/AlarmModule.swift) and
- * emit the same events through `NativeEventEmitter`:
- *   onAlarmFired | onAlarmDismissed | onAlarmSnoozed  -> AlarmEvent
+ * Native Alarm module interface.
  */
-
-/** type: 'none' | 'daily' | 'weekly' | 'interval' */
-export type AlarmRepeat = {
-  type: string;
-  weekdays?: number[]; // 1 = Sunday ... 7 = Saturday (weekly)
-  intervalMs?: number; // interval
-};
-
-export type AlarmConfig = {
-  alarmId?: string;
-  timestamp: number; // ms since epoch
-  title: string;
-  body?: string;
-  sound?: string; // 'default' or a bundled sound file name
-  vibrate?: boolean; // Android only (iOS alarms always vibrate per system settings)
-  snoozeEnabled?: boolean;
-  snoozeMinutes?: number;
-  repeat?: AlarmRepeat;
-  data?: string; // JSON string payload
-};
-
-export type Alarm = {
-  alarmId: string;
-  timestamp: number;
-  title: string;
-  body: string;
-  sound: string;
-  vibrate: boolean;
-  snoozeEnabled: boolean;
-  snoozeMinutes: number;
-  repeat: AlarmRepeat;
-  data: string;
-  enabled: boolean;
-  nextTriggerAt: number; // 0 if none
-};
-
-/** status: 'granted' | 'denied' | 'notDetermined' */
-export type AlarmPermission = {
-  status: string;
-  notifications: boolean;
-  canScheduleExact: boolean;
-  canDrawOverlays: boolean; // Android only; always true on iOS
-  canUseFullScreenIntent: boolean; // Android only; always true on iOS
-  backend?: string; // iOS only: 'alarmkit' (iOS 26+) | 'notifications'
-};
-
-export type AlarmEvent = {
-  alarmId: string;
-  timestamp: number;
-  title: string;
-  body: string;
-  data: string;
-};
-
 export interface Spec extends TurboModule {
-  // ---------- Permissions ----------
+  // ---------------------------------------------------------------------------
+  // Permissions
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns the current permission status.
+   */
   checkPermission(): Promise<AlarmPermission>;
+
+  /**
+   * Requests any required permissions.
+   */
   requestPermission(): Promise<AlarmPermission>;
+
+  /**
+   * Checks whether exact alarms can be scheduled.
+   *
+   * Android only.
+   */
   canScheduleExactAlarms(): Promise<boolean>;
-  /** Opens the vendor Autostart screen on Android; resolves false on iOS. */
+
+  /**
+   * Opens the device's Autostart settings screen.
+   *
+   * Android:
+   * Opens the vendor-specific Autostart page when available.
+   *
+   * iOS:
+   * Resolves `false`.
+   */
   openAutoStartSettings(): Promise<boolean>;
 
-  // ---------- Scheduling ----------
+  // ---------------------------------------------------------------------------
+  // Scheduling
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Schedules a new alarm.
+   *
+   * Returns the generated or provided alarm ID.
+   */
   scheduleAlarm(config: AlarmConfig): Promise<string>;
+
+  /**
+   * Updates an existing alarm.
+   *
+   * Returns `true` if the update succeeds.
+   */
   updateAlarm(alarmId: string, config: AlarmConfig): Promise<boolean>;
+
+  /**
+   * Cancels a specific alarm.
+   */
   cancelAlarm(alarmId: string): Promise<boolean>;
+
+  /**
+   * Cancels every scheduled alarm.
+   */
   cancelAllAlarms(): Promise<void>;
 
-  // ---------- Control (while ringing) ----------
+  // ---------------------------------------------------------------------------
+  // Ringing Controls
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Stops the currently ringing alarm.
+   */
   stopAlarm(alarmId: string): Promise<void>;
+
+  /**
+   * Snoozes the currently ringing alarm.
+   *
+   * @param alarmId Alarm identifier.
+   * @param minutes Snooze duration in minutes.
+   */
   snoozeAlarm(alarmId: string, minutes: number): Promise<void>;
-  getRingingAlarm(): Promise<Alarm | null>;
 
-  // ---------- Queries ----------
-  getAlarm(alarmId: string): Promise<Alarm | null>;
-  getAllAlarms(): Promise<Alarm[]>;
+  /**
+   * Returns the currently ringing alarm, if one exists.
+   */
+  getRingingAlarm(): Promise<AlarmProp | null>;
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns a scheduled alarm by ID.
+   */
+  getAlarm(alarmId: string): Promise<AlarmProp | null>;
+
+  /**
+   * Returns every scheduled alarm.
+   */
+  getAllAlarms(): Promise<AlarmProp[]>;
+
+  /**
+   * Checks whether an alarm is scheduled.
+   */
   isScheduled(alarmId: string): Promise<boolean>;
 
-  // ---------- Events (used by NativeEventEmitter) ----------
+  // ---------------------------------------------------------------------------
+  // NativeEventEmitter Support
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Internal listener registration.
+   */
   addListener(eventName: string): void;
+
+  /**
+   * Internal listener cleanup.
+   */
   removeListeners(count: number): void;
 }
 
+/**
+ * Error shown when the native module is unavailable.
+ */
 const LINKING_ERROR =
   "react-native-alarms: the native 'Alarm' module is not linked. " +
   Platform.select({
@@ -99,8 +132,24 @@ const LINKING_ERROR =
     default: 'Rebuild the app after installing the package.',
   });
 
-// Both platforms register a legacy module, reachable through either registry
-// depending on the architecture. Throw on first use, not on import.
+/**
+ * Cross-platform native Alarm module.
+ *
+ * Supports both the legacy Native Module system and the New Architecture
+ * (TurboModules). The module is resolved lazily so importing it does not
+ * immediately throw if native linking is missing.
+ *
+ * @example
+ * ```ts
+ * import Alarm from 'react-native-alarms';
+ *
+ * const id = await Alarm.scheduleAlarm({
+ *   timestamp: Date.now() + 60000,
+ *   title: 'Meeting',
+ *   body: 'Standup starts now',
+ * });
+ * ```
+ */
 const Alarm: Spec =
   TurboModuleRegistry.get<Spec>('Alarm') ??
   NativeModules.Alarm ??