react-native-alarms 0.0.5 → 0.0.7

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.5",
+  "version": "0.0.7",
   "description": "A powerful, cross-platform alarm management library for React Native",
   "private": false,
   "main": "index.ts",
@@ -22,7 +22,7 @@
     "lint": "eslint .",
     "start": "react-native start",
     "test": "jest",
-    "prepare": "npm run build",
+    "prepare": "husky",
     "build": "tsc",
     "clean": "rm -rf dist types *.d.ts"
   },
@@ -56,6 +56,8 @@
     "@babel/core": "^7.25.2",
     "@babel/preset-env": "^7.25.3",
     "@babel/runtime": "^7.25.0",
+    "@commitlint/cli": "^21.2.4",
+    "@commitlint/config-conventional": "^21.2.4",
     "@react-native-community/cli": "20.2.0",
     "@react-native-community/cli-platform-android": "20.2.0",
     "@react-native-community/cli-platform-ios": "20.2.0",
@@ -68,6 +70,7 @@
     "@types/react": "^19.2.0",
     "@types/react-test-renderer": "^19.1.0",
     "eslint": "^8.19.0",
+    "husky": "^9.1.7",
     "jest": "^29.6.3",
     "prettier": "2.8.8",
     "react": "19.3.0",

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 ??