react-native-alarms 0.0.6 → 0.0.8

package/ios/alarm/NotificationBackend.swift

@@ -1,5 +1,6 @@
 import Foundation
 import UserNotifications
+import UniformTypeIdentifiers
 
 /// Fallback backend for devices without AlarmKit (iOS < 26, or AlarmKit denied):
 /// local notifications with Stop / Snooze actions.
@@ -10,25 +11,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 +52,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,82 +65,128 @@ 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 {
+  
+  private func content(for a: AlarmData, attachment: UNNotificationAttachment? = nil) -> UNMutableNotificationContent {
     let c = UNMutableNotificationContent()
     c.title = a.title.isEmpty ? "Alarm" : a.title
     c.body = a.body.isEmpty ? "Alarm is ringing" : a.body
     c.categoryIdentifier = Self.category
-    c.userInfo = ["alarmId": a.id]
+    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))
+    ? .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)
+  
+  private func request(_ id: String, _ a: AlarmData, _ trigger: UNNotificationTrigger,
+                       _ attachment: UNNotificationAttachment? = nil) -> UNNotificationRequest {
+    UNNotificationRequest(identifier: id, content: content(for: a, attachment: attachment), 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] = []
+    prepareAttachment(for: a.image) { attachment in
+      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 {
+      switch a.repeatType {
+      case "daily":
         var dc = DateComponents()
-        dc.weekday = d
         dc.hour = hm.hour
         dc.minute = hm.minute
-        requests.append(request(base + ":wd\(d)", a, UNCalendarNotificationTrigger(dateMatching: dc, repeats: true)))
-      }
+        requests.append(self.request(base, a, UNCalendarNotificationTrigger(dateMatching: dc, repeats: true), attachment))
 
-    case "interval":
-      // iOS repeating interval triggers count from "now", not from `timestamp`, so
-      // pre-schedule the next N exact occurrences instead.
-      var t = a.nextTrigger()
-      guard t > 0 else { return completion(nil) }
-      for k in 0..<Self.intervalOccurrences {
-        requests.append(request(base + ":i\(k)", a, exactTrigger(ms: t)))
-        t += a.intervalMs
+      case "weekly":
+        let days = a.weekdays.isEmpty ? Array(1...7) : a.weekdays.filter { (1...7).contains($0) }
+        for d in days {
+          var dc = DateComponents()
+          dc.weekday = d
+          dc.hour = hm.hour
+          dc.minute = hm.minute
+          requests.append(self.request(base + ":wd\(d)", a, UNCalendarNotificationTrigger(dateMatching: dc, repeats: true), attachment))
+        }
+
+      case "interval":
+        // iOS repeating interval triggers count from "now", not from `timestamp`, so
+        // pre-schedule the next N exact occurrences instead.
+        var t = a.nextTrigger()
+        guard t > 0 else { return completion(nil) }
+        for k in 0..<Self.intervalOccurrences {
+          requests.append(self.request(base + ":i\(k)", a, self.exactTrigger(ms: t), attachment))
+          t += a.intervalMs
+        }
+
+      default:
+        let next = a.nextTrigger()
+        guard next > 0 else { return completion(nil) } // nothing in the future, same as Android
+        requests.append(self.request(base, a, self.exactTrigger(ms: next), attachment))
       }
 
-    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)))
+      self.add(requests, completion: completion)
     }
-
-    add(requests, completion: completion)
   }
 
+  private func prepareAttachment(for image: String?, completion: @escaping (UNNotificationAttachment?) -> Void) {
+    guard let image, !image.isEmpty else { return completion(nil) }
+    guard let url = URL(string: image) else {
+      NSLog("[react-native-alarms] Invalid image URI: %@", image)
+      return completion(nil)
+    }
+    if url.isFileURL {
+      do {
+        completion(try UNNotificationAttachment(identifier: "alarm-image", url: url, options: nil))
+      } catch {
+        NSLog("[react-native-alarms] Could not attach alarm image: %@", error.localizedDescription)
+        completion(nil)
+      }
+      return
+    }
+    guard url.scheme?.lowercased() == "https" else {
+      NSLog("[react-native-alarms] Alarm image URI must use file:// or https://: %@", image)
+      return completion(nil)
+    }
+
+    URLSession.shared.downloadTask(with: url) { 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)
+      }
+      let mimeType = response?.mimeType
+      let ext = url.pathExtension.isEmpty
+        ? (mimeType.flatMap { UTType(mimeType: $0)?.preferredFilenameExtension } ?? "jpg")
+        : url.pathExtension
+      let destination = FileManager.default.temporaryDirectory
+        .appendingPathComponent(UUID().uuidString)
+        .appendingPathExtension(ext)
+      do {
+        try FileManager.default.moveItem(at: temporaryURL, to: destination)
+        completion(try UNNotificationAttachment(identifier: "alarm-image", url: destination, options: nil))
+      } catch {
+        NSLog("[react-native-alarms] Could not attach downloaded alarm image: %@", error.localizedDescription)
+        completion(nil)
+      }
+    }.resume()
+  }
+  
   private func exactTrigger(ms: Double) -> UNCalendarNotificationTrigger {
     let dc = Calendar.current.dateComponents(
       [.year, .month, .day, .hour, .minute, .second],
@@ -147,7 +194,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,27 +207,29 @@ 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))
     let trigger = UNTimeIntervalNotificationTrigger(timeInterval: Double(max(1, minutes)) * 60, repeats: false)
-    center.add(request(Self.prefix + a.id + ":snooze", a, trigger))
-    if ringing?.id == a.id { ringing = nil }
+    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 }
+    }
   }
-
+  
   /// 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 +241,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 +251,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 +278,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,17 +1,17 @@
 {
   "name": "react-native-alarms",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "A powerful, cross-platform alarm management library for React Native",
   "private": false,
   "main": "index.ts",
-  "types": "index.d.ts",
+  "types": "index.ts",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
+      "types": "./index.ts",
       "default": "./index.ts"
     },
     "./service": {
-      "types": "./AlarmService.d.ts",
+      "types": "./AlarmService.ts",
       "default": "./AlarmService.ts"
     },
     "./package.json": "./package.json"

package/specs/NativeAlarm.ts

@@ -1,109 +1,162 @@
 import type { TurboModule } from 'react-native';
 import { NativeModules, Platform, TurboModuleRegistry } from 'react-native';
+import type { 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({
     ios: "Run 'pod install' in the ios folder, then rebuild the app.",
-    default: 'Rebuild the app after installing the package.',
+    default:
+      'Rebuild the app after installing the package. Expo Go is unsupported; use a development build.',
   });
 
-// Both platforms register a legacy module, reachable through either registry
-// depending on the architecture. Throw on first use, not on import.
+export function getNativeAlarmModule(): Spec | null {
+  return TurboModuleRegistry.get<Spec>('Alarm') ?? NativeModules.Alarm ?? null;
+}
+
+/**
+ * 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 ??
+  getNativeAlarmModule() ??
   new Proxy({} as Spec, {
     get() {
       throw new Error(LINKING_ERROR);