react-native-alarms 0.0.7 → 0.0.8

package/AlarmService.ts

@@ -25,36 +25,60 @@
  * });
  * ```
  */
-import { NativeEventEmitter, NativeModules } from 'react-native';
+import { NativeEventEmitter, type EmitterSubscription } from 'react-native';
 import type {
   AlarmConfig,
   AlarmProp,
   AlarmPermission,
   AlarmEvent,
+  AlarmEventMap,
+  AlarmEventName,
 } from './src/types';
 import { AlarmRegistry } from './src/utils';
-
-const { Alarm: NativeAlarm } = NativeModules;
+import Alarm, { getNativeAlarmModule } from './specs/NativeAlarm';
 
 /**
- * Resolves the native alarm module when it is linked.
- *
- * The module is loaded conditionally so importing the service does not
- * immediately fail when the native module is unavailable.
+ * Resolves the native module when available and keeps the lazy proxy as a
+ * fallback so missing native linking is reported when an operation is called.
  */
-const alarm = NativeAlarm ? require('./specs/NativeAlarm').default : null;
+const nativeAlarm = getNativeAlarmModule();
+const alarm = nativeAlarm ?? Alarm;
 
 /**
  * Native event emitter used to subscribe to alarm lifecycle events.
  */
-const alarmEmitter = NativeAlarm ? new NativeEventEmitter(NativeAlarm) : null;
+const alarmEmitter = nativeAlarm ? new NativeEventEmitter(nativeAlarm) : null;
 
 /**
  * Callback invoked when a native alarm event is received.
  *
  * @param alarm Event data emitted by the native alarm module.
  */
-type AlarmEventListener = (alarm: AlarmEvent) => void;
+type AlarmEventListener<K extends AlarmEventName = AlarmEventName> = (
+  alarm: AlarmEventMap[K],
+) => void;
+
+const ALARM_EVENT_NAMES = [
+  'onAlarmFired',
+  'onAlarmDismissed',
+  'onAlarmSnoozed',
+] as const satisfies readonly AlarmEventName[];
+
+function isAlarmEvent(value: Object): value is AlarmEvent {
+  return (
+    'alarmId' in value &&
+    typeof value.alarmId === 'string' &&
+    'timestamp' in value &&
+    typeof value.timestamp === 'number' &&
+    'title' in value &&
+    typeof value.title === 'string' &&
+    'body' in value &&
+    typeof value.body === 'string' &&
+    'data' in value &&
+    typeof value.data === 'string' &&
+    (!('image' in value) || typeof value.image === 'string')
+  );
+}
 
 /**
  * High-level service for scheduling and managing native alarms.
@@ -83,19 +107,17 @@ export class AlarmService {
    * more than once for the same event.
    */
   private static listeners: {
-    fired: Set<AlarmEventListener>;
-    dismissed: Set<AlarmEventListener>;
-    snoozed: Set<AlarmEventListener>;
+    [K in AlarmEventName]: Set<AlarmEventListener<K>>;
   } = {
-    fired: new Set(),
-    dismissed: new Set(),
-    snoozed: new Set(),
+    onAlarmFired: new Set(),
+    onAlarmDismissed: new Set(),
+    onAlarmSnoozed: new Set(),
   };
 
   /**
    * Native event subscriptions created by {@link initialize}.
    */
-  private static subscriptions: any[] = [];
+  private static subscriptions: EmitterSubscription[] = [];
 
   /**
    * Initializes native event forwarding.
@@ -107,25 +129,18 @@ export class AlarmService {
    * This method is called automatically by the event subscription helpers.
    */
   static initialize(): void {
-    if (!alarmEmitter || !this.subscriptions.length) {
-      this.subscriptions = [
-        alarmEmitter?.addListener('onAlarmFired', (data: any) => {
-          this.listeners.fired.forEach(listener =>
-            listener(data as AlarmEvent),
+    if (!alarmEmitter || this.subscriptions.length) return;
+    this.subscriptions = ALARM_EVENT_NAMES.map(eventName =>
+      alarmEmitter.addListener(eventName, (event: Object) => {
+        if (!isAlarmEvent(event)) {
+          console.error(
+            `[react-native-alarms] Ignoring invalid ${eventName} event payload`,
           );
-        }),
-        alarmEmitter?.addListener('onAlarmDismissed', (data: any) => {
-          this.listeners.dismissed.forEach(listener =>
-            listener(data as AlarmEvent),
-          );
-        }),
-        alarmEmitter?.addListener('onAlarmSnoozed', (data: any) => {
-          this.listeners.snoozed.forEach(listener =>
-            listener(data as AlarmEvent),
-          );
-        }),
-      ].filter(Boolean);
-    }
+          return;
+        }
+        this.listeners[eventName].forEach(listener => listener(event));
+      }),
+    );
   }
 
   /**
@@ -139,7 +154,7 @@ export class AlarmService {
    * remove individual callbacks.
    */
   static cleanup(): void {
-    this.subscriptions.forEach(sub => sub?.remove());
+    this.subscriptions.forEach(sub => sub.remove());
     this.subscriptions = [];
   }
 
@@ -161,11 +176,10 @@ export class AlarmService {
    * unsubscribe();
    * ```
    */
-  static onAlarmFired(listener: AlarmEventListener): () => boolean {
-    this.initialize();
-    this.listeners.fired.add(listener);
-
-    return () => this.listeners.fired.delete(listener);
+  static onAlarmFired(
+    listener: AlarmEventListener<'onAlarmFired'>,
+  ): () => void {
+    return this.subscribe('onAlarmFired', listener);
   }
 
   /**
@@ -174,11 +188,10 @@ export class AlarmService {
    * @param listener Callback invoked with the dismissed alarm's event data.
    * @returns A function that unregisters this callback.
    */
-  static onAlarmDismissed(listener: AlarmEventListener): () => boolean {
-    this.initialize();
-    this.listeners.dismissed.add(listener);
-
-    return () => this.listeners.dismissed.delete(listener);
+  static onAlarmDismissed(
+    listener: AlarmEventListener<'onAlarmDismissed'>,
+  ): () => void {
+    return this.subscribe('onAlarmDismissed', listener);
   }
 
   /**
@@ -187,11 +200,21 @@ export class AlarmService {
    * @param listener Callback invoked with the snoozed alarm's event data.
    * @returns A function that unregisters this callback.
    */
-  static onAlarmSnoozed(listener: AlarmEventListener): () => boolean {
-    this.initialize();
-    this.listeners.snoozed.add(listener);
+  static onAlarmSnoozed(
+    listener: AlarmEventListener<'onAlarmSnoozed'>,
+  ): () => void {
+    return this.subscribe('onAlarmSnoozed', listener);
+  }
 
-    return () => this.listeners.snoozed.delete(listener);
+  private static subscribe<K extends AlarmEventName>(
+    eventName: K,
+    listener: AlarmEventListener<K>,
+  ): () => void {
+    this.initialize();
+    this.listeners[eventName].add(listener);
+    return () => {
+      this.listeners[eventName].delete(listener);
+    };
   }
 
   /**
@@ -201,7 +224,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async checkPermission(): Promise<AlarmPermission> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.checkPermission();
   }
 
@@ -214,7 +236,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async requestPermission(): Promise<AlarmPermission> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.requestPermission();
   }
 
@@ -237,15 +258,7 @@ export class AlarmService {
    * ```
    */
   static async scheduleAlarm(config: AlarmConfig): Promise<string> {
-    if (!alarm) {
-      throw new Error('Alarm module not linked');
-    }
-    const componentName = AlarmRegistry.resolve(config.presentation?.type);
-    return alarm.scheduleAlarm({
-      ...config,
-      componentName,
-      componentProps: config.presentation?.props ?? {},
-    });
+    return alarm.scheduleAlarm(this.toNativeConfig(config));
   }
 
   /**
@@ -260,8 +273,17 @@ export class AlarmService {
     alarmId: string,
     config: AlarmConfig,
   ): Promise<boolean> {
-    if (!alarm) throw new Error('Alarm module not linked');
-    return alarm.updateAlarm(alarmId, config);
+    return alarm.updateAlarm(alarmId, this.toNativeConfig(config));
+  }
+
+  private static toNativeConfig<T extends AlarmConfig>(
+    config: T,
+  ): T & { componentName: string; componentProps: Record<string, unknown> } {
+    return {
+      ...config,
+      componentName: AlarmRegistry.resolve(config.presentation?.type),
+      componentProps: config.presentation?.props ?? {},
+    };
   }
 
   /**
@@ -272,7 +294,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async cancelAlarm(alarmId: string): Promise<boolean> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.cancelAlarm(alarmId);
   }
 
@@ -283,7 +304,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async cancelAllAlarms(): Promise<void> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.cancelAllAlarms();
   }
 
@@ -295,7 +315,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async stopAlarm(alarmId: string): Promise<void> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.stopAlarm(alarmId);
   }
 
@@ -313,7 +332,6 @@ export class AlarmService {
    * ```
    */
   static async snoozeAlarm(alarmId: string, minutes?: number): Promise<void> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.snoozeAlarm(alarmId, minutes ?? 5);
   }
 
@@ -325,7 +343,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async getRingingAlarm(): Promise<AlarmProp | null> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.getRingingAlarm();
   }
 
@@ -337,7 +354,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async getAlarm(alarmId: string): Promise<AlarmProp | null> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.getAlarm(alarmId);
   }
 
@@ -348,7 +364,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async getAllAlarms(): Promise<AlarmProp[]> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.getAllAlarms();
   }
 
@@ -360,7 +375,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async isScheduled(alarmId: string): Promise<boolean> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.isScheduled(alarmId);
   }
 
@@ -377,7 +391,6 @@ export class AlarmService {
    * @throws Error if the native alarm module is not linked.
    */
   static async openAutoStartSettings(): Promise<boolean> {
-    if (!alarm) throw new Error('Alarm module not linked');
     return alarm.openAutoStartSettings();
   }
 }

package/README.md

@@ -44,7 +44,7 @@ yarn add react-native-alarms
 
 ### Native Module Linking
 
-Since this is a native module, you'll need to link it:
+For a bare React Native app, install the iOS pods and rebuild:
 
 ```bash
 cd ios && pod install && cd ..
@@ -54,11 +54,32 @@ For Android, the native code auto-links, including the permissions, ring activit
 service and receivers in its manifest. No `MainApplication` or `AndroidManifest.xml`
 changes are needed. Rebuild the app after installing.
 
+### Expo
+
+The library works with Expo projects that generate and build native projects
+(prebuild, EAS Build, or a development build). It uses React Native autolinking and
+does not require an Expo config plugin:
+
+```bash
+npm install react-native-alarms
+npx expo prebuild
+npx expo run:android
+# or
+npx expo run:ios
+```
+
+Rebuild the native app after installing or upgrading the library. **Expo Go is not
+supported** because it cannot load this library's native alarm module. Existing bare
+React Native installation and setup remain unchanged.
+Register the `AlarmRing` component in your app's JavaScript entry point as described
+below; Expo Router apps should do this from a custom entry point before loading
+`expo-router/entry`.
+
 ### Register the ring screen
 
 When an alarm rings, both platforms show a full-screen React component registered as
 `AlarmRing`, with the alarm (`alarmId`, `title`, `body`, `snoozeEnabled`,
-`snoozeMinutes`, `data`) as props. Register your own component in `index.js`:
+`snoozeMinutes`, `data`, and optional `image`) as props. Register your own component in `index.js`:
 
 ```js
 import { AppRegistry } from 'react-native';
@@ -216,6 +237,7 @@ type AlarmConfig = {
   timestamp: number;          // Time in milliseconds (Date.now() format)
   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
   vibrate?: boolean;          // Enable vibration (Android only)
   snoozeEnabled?: boolean;    // Allow snoozing
@@ -236,6 +258,24 @@ type AlarmPresentation = {
 };
 ```
 
+Pass a URI string for `image`; for example:
+
+```ts
+await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 60_000,
+  title: 'Appointment',
+  image: 'https://example.com/appointment.jpg',
+});
+```
+
+When provided, `image` is returned with queried alarms and alarm events, passed to
+the registered ring screen as an initial prop, and used for the native notification
+image where supported. Android accepts `https://`, `file://`, and `content://` URIs.
+iOS notification attachments accept `https://` and `file://` URIs; the iOS 26+
+AlarmKit system alert itself does not display custom images, but the image URI is
+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 }}`.
+
 > **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 |
@@ -264,6 +304,7 @@ type Alarm = {
   timestamp: number;
   title: string;
   body: string;
+  image?: string;
   sound: string;
   vibrate: boolean;
   snoozeEnabled: boolean;
@@ -602,4 +643,3 @@ await AlarmService.scheduleAlarm({
 ```
 
 **Full Guide:** See [CUSTOM_UI_GUIDE.md](./CUSTOM_UI_GUIDE.md) for complete examples and best practices.
-

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

@@ -14,6 +14,7 @@ data class AlarmData(
   val timestamp: Long,
   val title: String,
   val body: String,
+  val image: String,
   val sound: String,
   val vibrate: Boolean,
   val snoozeEnabled: Boolean,
@@ -77,6 +78,7 @@ data class AlarmData(
 
   fun toJson(): String = JSONObject().apply {
     put("id", id); put("timestamp", timestamp); put("title", title); put("body", body)
+    put("image", image)
     put("sound", sound); put("vibrate", vibrate); put("snoozeEnabled", snoozeEnabled)
     put("snoozeMinutes", snoozeMinutes); put("repeatType", repeatType)
     put("weekdays", JSONArray(weekdays)); put("intervalMs", intervalMs)
@@ -90,6 +92,7 @@ data class AlarmData(
     putDouble("timestamp", timestamp.toDouble())
     putString("title", title)
     putString("body", body)
+    putString("image", image)
     putString("sound", sound)
     putBoolean("vibrate", vibrate)
     putBoolean("snoozeEnabled", snoozeEnabled)
@@ -117,6 +120,7 @@ data class AlarmData(
     putDouble("timestamp", timestamp.toDouble())
     putString("title", title)
     putString("body", body)
+    putString("image", image)
     putBoolean("snoozeEnabled", snoozeEnabled)
     putInt("snoozeMinutes", snoozeMinutes)
     putString("data", data)
@@ -173,6 +177,7 @@ data class AlarmData(
         timestamp = o.getLong("timestamp"),
         title = o.optString("title"),
         body = o.optString("body"),
+        image = o.optString("image"),
         sound = o.optString("sound", "default"),
         vibrate = o.optBoolean("vibrate", true),
         snoozeEnabled = o.optBoolean("snoozeEnabled", true),
@@ -214,6 +219,7 @@ data class AlarmData(
         timestamp = m.getDouble("timestamp").toLong(),
         title = m.str("title"),
         body = m.str("body"),
+        image = m.str("image"),
         sound = m.str("sound", "default"),
         vibrate = m.bool("vibrate", true),
         snoozeEnabled = m.bool("snoozeEnabled", true),

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

@@ -241,6 +241,7 @@ class AlarmModule(private val ctx: ReactApplicationContext) : ReactContextBaseJa
       putDouble("timestamp", System.currentTimeMillis().toDouble())
       putString("title", a.title)
       putString("body", a.body)
+      putString("image", a.image)
       putString("data", a.data)
     }
     ctx.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java).emit(eventName, map)

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

@@ -8,6 +8,8 @@ import android.app.Service
 import android.content.Context
 import android.content.Intent
 import android.content.pm.ServiceInfo
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
 import android.media.AudioAttributes
 import android.media.MediaPlayer
 import android.media.RingtoneManager
@@ -22,6 +24,9 @@ import android.os.Vibrator
 import android.util.Log
 import androidx.core.app.NotificationCompat
 import androidx.core.app.ServiceCompat
+import java.io.InputStream
+import java.net.URL
+import java.util.concurrent.Executors
 
 /**
  * Foreground service that actually rings: looping sound, vibration, a partial wake
@@ -39,6 +44,7 @@ class AlarmService : Service() {
   private var player: MediaPlayer? = null
   private var vibrator: Vibrator? = null
   private var wakeLock: PowerManager.WakeLock? = null
+  private val imageExecutor = Executors.newSingleThreadExecutor()
 
   override fun onBind(intent: Intent?): IBinder? = null
 
@@ -70,6 +76,7 @@ class AlarmService : Service() {
     Log.i(TAG, "Ringing alarm ${alarm.id}")
 
     startInForeground(buildNotification(alarm))
+    loadNotificationImage(alarm)
     acquireWakeLock()
     startSound(alarm)
     if (alarm.vibrate) startVibration()
@@ -139,6 +146,7 @@ class AlarmService : Service() {
 
   override fun onDestroy() {
     stopRinging()
+    imageExecutor.shutdownNow()
     super.onDestroy()
   }
 
@@ -217,7 +225,7 @@ class AlarmService : Service() {
       .build()
   }
 
-  private fun buildNotification(alarm: AlarmData): Notification {
+  private fun buildNotification(alarm: AlarmData, image: Bitmap? = null): Notification {
     ensureChannel()
     val ringIntent = Intent(this, AlarmRingActivity::class.java)
       .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
@@ -235,12 +243,58 @@ class AlarmService : Service() {
       .setFullScreenIntent(fullScreen, true)
       .setContentIntent(fullScreen)
       .addAction(0, "Stop", commandPI(ACTION_DISMISS, 2))
+    if (image != null) {
+      b.setStyle(
+        NotificationCompat.BigPictureStyle()
+          .bigPicture(image)
+          .setBigContentTitle(alarm.title.ifBlank { "Alarm" })
+          .setSummaryText(alarm.body.ifBlank { "Alarm is ringing" })
+      )
+    }
     if (alarm.snoozeEnabled) {
       b.addAction(0, "Snooze", commandPI(ACTION_SNOOZE, 3))
     }
     return b.build()
   }
 
+  private fun loadNotificationImage(alarm: AlarmData) {
+    if (alarm.image.isBlank()) return
+    imageExecutor.execute {
+      try {
+        val bitmap = decodeImage(Uri.parse(alarm.image)) ?: return@execute
+        handler.post {
+          if (current?.id == alarm.id) {
+            ensureChannel().notify(NOTIFICATION_ID, buildNotification(alarm, bitmap))
+          }
+        }
+      } catch (e: Exception) {
+        Log.w(TAG, "Could not load notification image for alarm ${alarm.id}", e)
+      }
+    }
+  }
+
+  private fun decodeImage(uri: Uri): Bitmap? {
+    fun openStream(): InputStream? = when (uri.scheme?.lowercase()) {
+      "https" -> URL(uri.toString()).openConnection().apply {
+        connectTimeout = 5_000
+        readTimeout = 5_000
+      }.getInputStream()
+      "file", "content", "android.resource" -> contentResolver.openInputStream(uri)
+      else -> throw IllegalArgumentException("Unsupported alarm image URI: $uri")
+    }
+
+    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    openStream()?.use { BitmapFactory.decodeStream(it, null, bounds) }
+    if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+
+    var sampleSize = 1
+    while (bounds.outWidth / sampleSize > 1024 || bounds.outHeight / sampleSize > 1024) {
+      sampleSize *= 2
+    }
+    val options = BitmapFactory.Options().apply { inSampleSize = sampleSize }
+    return openStream()?.use { BitmapFactory.decodeStream(it, null, options) }
+  }
+
   private fun commandPI(action: String, code: Int): PendingIntent =
     PendingIntent.getService(
       this, code, Intent(this, AlarmService::class.java).setAction(action),

package/android-lib/src/main/AndroidManifest.xml

@@ -1,5 +1,6 @@
 <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" />
     <uses-permission android:name="android.permission.USE_EXACT_ALARM" />
     <uses-permission

package/index.ts

@@ -11,6 +11,8 @@ export type {
   AlarmProp,
   AlarmPermission,
   AlarmEvent,
+  AlarmEventMap,
+  AlarmEventName,
 } from './src/types';
 
 export { AlarmService } from './AlarmService';

package/ios/.xcode.env.local

@@ -1 +1 @@
-export NODE_BINARY=/opt/homebrew/Cellar/node/26.10.0_1/bin/node
+export NODE_BINARY=/opt/homebrew/bin/node

package/ios/ReactNativeAlarm/Info.plist

@@ -26,6 +26,8 @@
 	<string>$(CURRENT_PROJECT_VERSION)</string>
 	<key>LSRequiresIPhoneOS</key>
 	<true/>
+	<key>NSAlarmKitUsageDescription</key>
+	<string>This app needs access to alarms to wake you up on time.</string>
 	<key>NSAppTransportSecurity</key>
 	<dict>
 		<key>NSAllowsArbitraryLoads</key>
@@ -73,7 +75,5 @@
 	</array>
 	<key>UIViewControllerBasedStatusBarAppearance</key>
 	<false/>
-	<key>NSAlarmKitUsageDescription</key>
-	<string>This app needs access to alarms to wake you up on time.</string>
 </dict>
 </plist>

package/ios/ReactNativeAlarm.xcodeproj/project.pbxproj

@@ -223,10 +223,14 @@
 			inputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-ReactNativeAlarm/Pods-ReactNativeAlarm-frameworks-${CONFIGURATION}-input-files.xcfilelist",
 			);
+			inputPaths = (
+			);
 			name = "[CP] Embed Pods Frameworks";
 			outputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-ReactNativeAlarm/Pods-ReactNativeAlarm-frameworks-${CONFIGURATION}-output-files.xcfilelist",
 			);
+			outputPaths = (
+			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
 			shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-ReactNativeAlarm/Pods-ReactNativeAlarm-frameworks.sh\"\n";
@@ -262,10 +266,14 @@
 			inputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-ReactNativeAlarm/Pods-ReactNativeAlarm-resources-${CONFIGURATION}-input-files.xcfilelist",
 			);
+			inputPaths = (
+			);
 			name = "[CP] Copy Pods Resources";
 			outputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-ReactNativeAlarm/Pods-ReactNativeAlarm-resources-${CONFIGURATION}-output-files.xcfilelist",
 			);
+			outputPaths = (
+			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
 			shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-ReactNativeAlarm/Pods-ReactNativeAlarm-resources.sh\"\n";

package/ios/alarm/AlarmData.swift

@@ -7,6 +7,7 @@ struct AlarmData: Codable {
   var timestamp: Double // ms since epoch
   var title: String
   var body: String
+  var image: String? = nil
   var sound: String
   var vibrate: Bool
   var snoozeEnabled: Bool
@@ -78,6 +79,7 @@ struct AlarmData: Codable {
       "timestamp": timestamp,
       "title": title,
       "body": body,
+      "image": image ?? "",
       "sound": sound,
       "vibrate": vibrate,
       "snoozeEnabled": snoozeEnabled,
@@ -97,6 +99,7 @@ struct AlarmData: Codable {
       timestamp: (m["timestamp"] as? NSNumber)?.doubleValue ?? 0,
       title: m["title"] as? String ?? "",
       body: m["body"] as? String ?? "",
+      image: m["image"] as? String,
       sound: m["sound"] as? String ?? "default",
       vibrate: (m["vibrate"] as? NSNumber)?.boolValue ?? true,
       snoozeEnabled: (m["snoozeEnabled"] as? NSNumber)?.boolValue ?? true,

package/ios/alarm/AlarmModule.swift

@@ -81,6 +81,7 @@ final class AlarmModule: RCTEventEmitter {
       "timestamp": AlarmData.now(),
       "title": a.title,
       "body": a.body,
+      "image": a.image ?? "",
       "data": a.data,
     ])
   }

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.
@@ -78,12 +79,13 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     + (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))
@@ -93,51 +95,96 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
     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] = []
-    
-    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 {
+    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.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 "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))
       }
-      
-    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
+
+      self.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)
       }
-      
-    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)))
+      return
     }
-    
-    add(requests, completion: completion)
+    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 {
@@ -165,8 +212,10 @@ final class NotificationBackend: NSObject, UNUserNotificationCenterDelegate {
   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

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "react-native-alarms",
-  "version": "0.0.7",
+  "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,6 +1,6 @@
 import type { TurboModule } from 'react-native';
 import { NativeModules, Platform, TurboModuleRegistry } from 'react-native';
-import { AlarmPermission, AlarmConfig, AlarmProp } from '../src/types';
+import type { AlarmPermission, AlarmConfig, AlarmProp } from '../src/types';
 
 /**
  * Native Alarm module interface.
@@ -129,9 +129,14 @@ 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.',
   });
 
+export function getNativeAlarmModule(): Spec | null {
+  return TurboModuleRegistry.get<Spec>('Alarm') ?? NativeModules.Alarm ?? null;
+}
+
 /**
  * Cross-platform native Alarm module.
  *
@@ -151,8 +156,7 @@ const LINKING_ERROR =
  * ```
  */
 const Alarm: Spec =
-  TurboModuleRegistry.get<Spec>('Alarm') ??
-  NativeModules.Alarm ??
+  getNativeAlarmModule() ??
   new Proxy({} as Spec, {
     get() {
       throw new Error(LINKING_ERROR);

package/src/types/index.ts

@@ -91,6 +91,12 @@ export type AlarmConfig = {
    */
   body?: string;
 
+  /**
+   * Optional image URI (for example, a `file://` path or an `https://` URL).
+   * Passed to the ringing screen and shown in native notifications when supported.
+   */
+  image?: string;
+
   /**
    * Alarm sound.
    *
@@ -152,6 +158,9 @@ export type AlarmProp = {
   /** Alarm body. */
   body: string;
 
+  /** Optional image URI. */
+  image?: string;
+
   /** Sound being used. */
   sound: string;
 
@@ -241,6 +250,17 @@ export type AlarmEvent = {
   /** Alarm body. */
   body: string;
 
+  /** Optional image URI. */
+  image?: string;
+
   /** Custom JSON payload. */
   data: string;
 };
+
+export type AlarmEventMap = {
+  onAlarmFired: AlarmEvent;
+  onAlarmDismissed: AlarmEvent;
+  onAlarmSnoozed: AlarmEvent;
+};
+
+export type AlarmEventName = keyof AlarmEventMap;

package/.bundle/config

@@ -1,2 +0,0 @@
-BUNDLE_PATH: "vendor/bundle"
-BUNDLE_FORCE_RUBY_PLATFORM: 1

package/.husky/commit-msg

@@ -1 +0,0 @@
-npx --no -- commitlint --edit $1

package/AlarmService.d.ts

@@ -1,221 +0,0 @@
-/**
- * High-level alarm management API.
- *
- * Provides convenient wrapper methods for managing native alarms,
- * including scheduling, updating, cancelling, snoozing, and monitoring
- * alarm lifecycle events.
- *
- * This service can be used for alarms, scheduled reminders, and other
- * time-sensitive experiences supported by the native alarm module.
- *
- * @example
- * ```typescript
- * import { AlarmService } from 'react-native-alarms';
- *
- * const permission = await AlarmService.checkPermission();
- *
- * if (permission.status !== 'granted') {
- *   await AlarmService.requestPermission();
- * }
- *
- * const alarmId = await AlarmService.scheduleAlarm({
- *   timestamp: Date.now() + 60_000,
- *   title: 'Reminder',
- *   body: 'Your scheduled reminder is ready.',
- * });
- * ```
- */
-
-import type {
-  AlarmConfig,
-  AlarmProp,
-  AlarmPermission,
-  AlarmEvent,
-} from './src/types';
-
-/**
- * Callback invoked when an alarm lifecycle event occurs.
- *
- * @param alarm - Information about the alarm associated with the event.
- */
-type AlarmEventListener = (alarm: AlarmEvent) => void;
-
-/**
- * Static service for managing native alarms.
- *
- * All methods can be called directly without creating an instance.
- */
-export class AlarmService {
-  /**
-   * Initializes the alarm service and registers native event listeners.
-   *
-   * Call this method to begin forwarding native alarm events to
-   * registered JavaScript listeners. Event registration methods may
-   * also initialize the service automatically.
-   */
-  static initialize(): void;
-
-  /**
-   * Removes native event subscriptions created by the service.
-   *
-   * Registered JavaScript callbacks may remain registered, depending
-   * on the implementation. Reinitialize the service before expecting
-   * to receive native events again.
-   */
-  static cleanup(): void;
-
-  /**
-   * Registers a listener for when an alarm fires.
-   *
-   * @param listener - Callback invoked with the fired alarm's event data.
-   * @returns A function that unregisters this listener.
-   *
-   * @example
-   * ```typescript
-   * const unsubscribe = AlarmService.onAlarmFired((alarm) => {
-   *   console.log('Alarm fired:', alarm);
-   * });
-   *
-   * // Unsubscribe when no longer needed.
-   * unsubscribe();
-   * ```
-   */
-  static onAlarmFired(listener: AlarmEventListener): () => void;
-
-  /**
-   * Registers a listener for when an alarm is dismissed.
-   *
-   * @param listener - Callback invoked with the dismissed alarm's event data.
-   * @returns A function that unregisters this listener.
-   */
-  static onAlarmDismissed(listener: AlarmEventListener): () => void;
-
-  /**
-   * Registers a listener for when an alarm is snoozed.
-   *
-   * @param listener - Callback invoked with the snoozed alarm's event data.
-   * @returns A function that unregisters this listener.
-   */
-  static onAlarmSnoozed(listener: AlarmEventListener): () => void;
-
-  /**
-   * Checks the current alarm permission status.
-   *
-   * @returns A promise resolving to the current permission information.
-   * @throws If the native alarm module is unavailable.
-   */
-  static checkPermission(): Promise<AlarmPermission>;
-
-  /**
-   * Requests the permissions required by the native alarm functionality.
-   *
-   * @returns A promise resolving to the resulting permission information.
-   * @throws If the native alarm module is unavailable.
-   */
-  static requestPermission(): Promise<AlarmPermission>;
-
-  /**
-   * Schedules a new alarm.
-   *
-   * @param config - Configuration describing the alarm to schedule.
-   * @returns A promise resolving to the ID assigned to the scheduled alarm.
-   * @throws If the native alarm module is unavailable or scheduling fails.
-   */
-  static scheduleAlarm(config: AlarmConfig): Promise<string>;
-
-  /**
-   * Updates an existing scheduled alarm.
-   *
-   * @param alarmId - ID of the alarm to update.
-   * @param config - Updated configuration for the alarm.
-   * @returns A promise resolving to `true` if the update succeeds.
-   * @throws If the native alarm module is unavailable or the update fails.
-   */
-  static updateAlarm(alarmId: string, config: AlarmConfig): Promise<boolean>;
-
-  /**
-   * Cancels a scheduled alarm.
-   *
-   * @param alarmId - ID of the alarm to cancel.
-   * @returns A promise resolving to `true` if the alarm was cancelled.
-   * @throws If the native alarm module is unavailable.
-   */
-  static cancelAlarm(alarmId: string): Promise<boolean>;
-
-  /**
-   * Cancels all scheduled alarms.
-   *
-   * @returns A promise that resolves when the cancellation operation completes.
-   * @throws If the native alarm module is unavailable.
-   */
-  static cancelAllAlarms(): Promise<void>;
-
-  /**
-   * Stops a currently ringing alarm.
-   *
-   * @param alarmId - ID of the ringing alarm to stop.
-   * @returns A promise that resolves when the stop operation completes.
-   * @throws If the native alarm module is unavailable.
-   */
-  static stopAlarm(alarmId: string): Promise<void>;
-
-  /**
-   * Snoozes a currently ringing alarm.
-   *
-   * @param alarmId - ID of the alarm to snooze.
-   * @param minutes - Optional snooze duration in minutes. If omitted,
-   * the native implementation or alarm configuration determines the default.
-   * @returns A promise that resolves when the snooze operation completes.
-   * @throws If the native alarm module is unavailable or snoozing fails.
-   */
-  static snoozeAlarm(alarmId: string, minutes?: number): Promise<void>;
-
-  /**
-   * Retrieves the currently ringing alarm, if one exists.
-   *
-   * @returns A promise resolving to the ringing alarm, or `null` if none exists.
-   * @throws If the native alarm module is unavailable.
-   */
-  static getRingingAlarm(): Promise<AlarmProp | null>;
-
-  /**
-   * Retrieves a specific alarm by its ID.
-   *
-   * @param alarmId - ID of the alarm to retrieve.
-   * @returns A promise resolving to the alarm, or `null` if it is not found.
-   * @throws If the native alarm module is unavailable.
-   */
-  static getAlarm(alarmId: string): Promise<AlarmProp | null>;
-
-  /**
-   * Retrieves all alarms known to the native alarm module.
-   *
-   * @returns A promise resolving to an array of alarm records.
-   * @throws If the native alarm module is unavailable.
-   */
-  static getAllAlarms(): Promise<AlarmProp[]>;
-
-  /**
-   * Checks whether an alarm is currently scheduled.
-   *
-   * @param alarmId - ID of the alarm to check.
-   * @returns A promise resolving to `true` if the alarm is scheduled;
-   * otherwise, `false`.
-   * @throws If the native alarm module is unavailable.
-   */
-  static isScheduled(alarmId: string): Promise<boolean>;
-
-  /**
-   * Opens the device manufacturer's Auto Start settings on Android,
-   * where supported, to help users configure background launch behavior.
-   *
-   * On iOS, this method resolves to `false`.
-   *
-   * @returns A promise resolving to `true` if the settings screen was opened;
-   * otherwise, `false`.
-   * @throws If the native alarm module is unavailable.
-   */
-  static openAutoStartSettings(): Promise<boolean>;
-}
-
-export default AlarmService;

package/commitlint.config.mjs

@@ -1 +0,0 @@
-export default { extends: ['@commitlint/config-conventional'] };

package/index.d.ts

@@ -1,20 +0,0 @@
-/**
- * React Native Alarms - Type definitions
- * Cross-platform alarm management for React Native
- */
-
-import type { Spec } from './specs/NativeAlarm';
-
-export type {
-  AlarmRepeat,
-  AlarmConfig,
-  AlarmProp,
-  AlarmPermission,
-  AlarmEvent,
-} from './src/types';
-
-export { AlarmService } from './AlarmService';
-
-declare const Alarm: Spec;
-
-export default Alarm;