react-native-alarms 0.0.5 → 0.0.7

package/AlarmService.ts

@@ -1,31 +1,87 @@
 /**
- * AlarmService - High-level alarm management API
+ * High-level alarm management API.
  *
- * This module provides a convenient wrapper around the native alarm module
- * with additional features like event listeners and state management.
+ * Provides a convenient wrapper around the native `Alarm` module for
+ * scheduling and managing alarms, handling permissions, querying alarm
+ * state, and subscribing to native alarm events.
+ *
+ * This API can also be used for time-sensitive reminders and custom
+ * scheduled experiences supported by the native alarm presentation flow.
+ *
+ * @example
+ * ```typescript
+ * import { AlarmService } from 'react-native-alarms/service';
+ *
+ * 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 event is ready.',
+ * });
+ * ```
  */
-
 import { NativeEventEmitter, NativeModules } from 'react-native';
 import type {
   AlarmConfig,
-  Alarm,
+  AlarmProp,
   AlarmPermission,
   AlarmEvent,
-} from './specs/NativeAlarm';
+} from './src/types';
+import { AlarmRegistry } from './src/utils';
 
 const { Alarm: NativeAlarm } = NativeModules;
 
-// Guard against module not being linked
+/**
+ * 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.
+ */
 const alarm = NativeAlarm ? require('./specs/NativeAlarm').default : null;
 
+/**
+ * Native event emitter used to subscribe to alarm lifecycle events.
+ */
 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;
 
 /**
- * High-level alarm service for managing alarms
+ * High-level service for scheduling and managing native alarms.
+ *
+ * All methods are static, so the service can be used directly without
+ * creating an instance.
+ *
+ * The service maintains JavaScript event listeners and forwards events
+ * received from the native module to registered callbacks.
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = AlarmService.onAlarmFired((alarm) => {
+ *   console.log('Alarm fired:', alarm.title);
+ * });
+ *
+ * // Remove this listener when it is no longer needed.
+ * unsubscribe();
+ * ```
  */
 export class AlarmService {
+  /**
+   * Registered JavaScript listeners grouped by event type.
+   *
+   * A `Set` prevents the same callback reference from being registered
+   * more than once for the same event.
+   */
   private static listeners: {
     fired: Set<AlarmEventListener>;
     dismissed: Set<AlarmEventListener>;
@@ -36,64 +92,113 @@ export class AlarmService {
     snoozed: new Set(),
   };
 
+  /**
+   * Native event subscriptions created by {@link initialize}.
+   */
   private static subscriptions: any[] = [];
 
   /**
-   * Initialize the alarm service and set up event listeners
+   * Initializes native event forwarding.
+   *
+   * Registers listeners for alarm firing, dismissal, and snoozing.
+   * Calling this method when subscriptions already exist does not
+   * register duplicate native subscriptions.
+   *
+   * This method is called automatically by the event subscription helpers.
    */
-  static initialize() {
+  static initialize(): void {
     if (!alarmEmitter || !this.subscriptions.length) {
       this.subscriptions = [
         alarmEmitter?.addListener('onAlarmFired', (data: any) => {
-          this.listeners.fired.forEach(listener => listener(data as AlarmEvent));
+          this.listeners.fired.forEach(listener =>
+            listener(data as AlarmEvent),
+          );
         }),
         alarmEmitter?.addListener('onAlarmDismissed', (data: any) => {
-          this.listeners.dismissed.forEach(listener => listener(data as AlarmEvent));
+          this.listeners.dismissed.forEach(listener =>
+            listener(data as AlarmEvent),
+          );
         }),
         alarmEmitter?.addListener('onAlarmSnoozed', (data: any) => {
-          this.listeners.snoozed.forEach(listener => listener(data as AlarmEvent));
+          this.listeners.snoozed.forEach(listener =>
+            listener(data as AlarmEvent),
+          );
         }),
       ].filter(Boolean);
     }
   }
 
   /**
-   * Cleanup event listeners
+   * Removes native event subscriptions created by the service.
+   *
+   * This stops forwarding native events to JavaScript listeners until
+   * {@link initialize} is called again.
+   *
+   * Registered JavaScript callbacks remain in their respective sets.
+   * Use the unsubscribe functions returned by the event helpers to
+   * remove individual callbacks.
    */
-  static cleanup() {
+  static cleanup(): void {
     this.subscriptions.forEach(sub => sub?.remove());
     this.subscriptions = [];
   }
 
   /**
-   * Register a listener for when alarms fire
+   * Subscribes to alarms when they fire.
+   *
+   * The service initializes native event forwarding automatically.
+   *
+   * @param listener Callback invoked with the fired alarm's event data.
+   * @returns A function that unregisters this callback.
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = AlarmService.onAlarmFired(alarm => {
+   *   console.log('Fired:', alarm.alarmId, alarm.title);
+   * });
+   *
+   * // Later:
+   * unsubscribe();
+   * ```
    */
-  static onAlarmFired(listener: AlarmEventListener) {
+  static onAlarmFired(listener: AlarmEventListener): () => boolean {
     this.initialize();
     this.listeners.fired.add(listener);
+
     return () => this.listeners.fired.delete(listener);
   }
 
   /**
-   * Register a listener for when alarms are dismissed
+   * Subscribes to alarms when they are dismissed.
+   *
+   * @param listener Callback invoked with the dismissed alarm's event data.
+   * @returns A function that unregisters this callback.
    */
-  static onAlarmDismissed(listener: AlarmEventListener) {
+  static onAlarmDismissed(listener: AlarmEventListener): () => boolean {
     this.initialize();
     this.listeners.dismissed.add(listener);
+
     return () => this.listeners.dismissed.delete(listener);
   }
 
   /**
-   * Register a listener for when alarms are snoozed
+   * Subscribes to alarms when they are snoozed.
+   *
+   * @param listener Callback invoked with the snoozed alarm's event data.
+   * @returns A function that unregisters this callback.
    */
-  static onAlarmSnoozed(listener: AlarmEventListener) {
+  static onAlarmSnoozed(listener: AlarmEventListener): () => boolean {
     this.initialize();
     this.listeners.snoozed.add(listener);
+
     return () => this.listeners.snoozed.delete(listener);
   }
 
   /**
-   * Check the current alarm permissions
+   * Retrieves the current alarm permission and capability status.
+   *
+   * @returns A promise resolving to the current permission status.
+   * @throws Error if the native alarm module is not linked.
    */
   static async checkPermission(): Promise<AlarmPermission> {
     if (!alarm) throw new Error('Alarm module not linked');
@@ -101,7 +206,12 @@ export class AlarmService {
   }
 
   /**
-   * Request alarm permissions
+   * Requests the permissions required for alarm scheduling.
+   *
+   * The permissions requested depend on the platform and its capabilities.
+   *
+   * @returns A promise resolving to the updated permission status.
+   * @throws Error if the native alarm module is not linked.
    */
   static async requestPermission(): Promise<AlarmPermission> {
     if (!alarm) throw new Error('Alarm module not linked');
@@ -109,15 +219,42 @@ export class AlarmService {
   }
 
   /**
-   * Schedule a new alarm
+   * Schedules a new alarm or time-based reminder.
+   *
+   * @param config Configuration containing the trigger timestamp,
+   * title, optional message, repeat settings, and custom data.
+   * @returns A promise resolving to the scheduled alarm ID.
+   * @throws Error if the native alarm module is not linked.
+   *
+   * @example
+   * ```typescript
+   * const alarmId = await AlarmService.scheduleAlarm({
+   *   timestamp: Date.now() + 5 * 60_000,
+   *   title: 'Take a break',
+   *   body: 'Your scheduled break starts now.',
+   *   data: JSON.stringify({ type: 'break-reminder' }),
+   * });
+   * ```
    */
   static async scheduleAlarm(config: AlarmConfig): Promise<string> {
-    if (!alarm) throw new Error('Alarm module not linked');
-    return alarm.scheduleAlarm(config);
+    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 ?? {},
+    });
   }
 
   /**
-   * Update an existing alarm
+   * Updates an existing scheduled alarm.
+   *
+   * @param alarmId Identifier of the alarm to update.
+   * @param config Updated alarm configuration.
+   * @returns A promise resolving to `true` if the update succeeds.
+   * @throws Error if the native alarm module is not linked.
    */
   static async updateAlarm(
     alarmId: string,
@@ -128,7 +265,11 @@ export class AlarmService {
   }
 
   /**
-   * Cancel an alarm
+   * Cancels a specific scheduled alarm.
+   *
+   * @param alarmId Identifier of the alarm to cancel.
+   * @returns A promise resolving to whether cancellation succeeded.
+   * @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');
@@ -136,7 +277,10 @@ export class AlarmService {
   }
 
   /**
-   * Cancel all alarms
+   * Cancels all scheduled alarms managed by the native module.
+   *
+   * @returns A promise that resolves when the operation completes.
+   * @throws Error if the native alarm module is not linked.
    */
   static async cancelAllAlarms(): Promise<void> {
     if (!alarm) throw new Error('Alarm module not linked');
@@ -144,7 +288,11 @@ export class AlarmService {
   }
 
   /**
-   * Stop the currently ringing alarm
+   * Stops a currently ringing alarm.
+   *
+   * @param alarmId Identifier of the ringing alarm.
+   * @returns A promise that resolves when the operation completes.
+   * @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');
@@ -152,7 +300,17 @@ export class AlarmService {
   }
 
   /**
-   * Snooze the currently ringing alarm
+   * Snoozes a currently ringing alarm.
+   *
+   * @param alarmId Identifier of the ringing alarm.
+   * @param minutes Snooze duration in minutes. Defaults to `5`.
+   * @returns A promise that resolves when the operation completes.
+   * @throws Error if the native alarm module is not linked.
+   *
+   * @example
+   * ```typescript
+   * await AlarmService.snoozeAlarm(alarmId, 10);
+   * ```
    */
   static async snoozeAlarm(alarmId: string, minutes?: number): Promise<void> {
     if (!alarm) throw new Error('Alarm module not linked');
@@ -160,37 +318,78 @@ export class AlarmService {
   }
 
   /**
-   * Get the currently ringing alarm (if any)
+   * Retrieves the alarm that is currently ringing.
+   *
+   * @returns A promise resolving to the ringing alarm, or `null`
+   * if no alarm is currently ringing.
+   * @throws Error if the native alarm module is not linked.
    */
-  static async getRingingAlarm(): Promise<Alarm | null> {
+  static async getRingingAlarm(): Promise<AlarmProp | null> {
     if (!alarm) throw new Error('Alarm module not linked');
     return alarm.getRingingAlarm();
   }
 
   /**
-   * Get a specific alarm by ID
+   * Retrieves a scheduled alarm by its identifier.
+   *
+   * @param alarmId Identifier of the alarm to retrieve.
+   * @returns A promise resolving to the alarm, or `null` if not found.
+   * @throws Error if the native alarm module is not linked.
    */
-  static async getAlarm(alarmId: string): Promise<Alarm | null> {
+  static async getAlarm(alarmId: string): Promise<AlarmProp | null> {
     if (!alarm) throw new Error('Alarm module not linked');
     return alarm.getAlarm(alarmId);
   }
 
   /**
-   * Get all scheduled alarms
+   * Retrieves all alarms managed by the native module.
+   *
+   * @returns A promise resolving to the list of scheduled alarms.
+   * @throws Error if the native alarm module is not linked.
    */
-  static async getAllAlarms(): Promise<Alarm[]> {
+  static async getAllAlarms(): Promise<AlarmProp[]> {
     if (!alarm) throw new Error('Alarm module not linked');
     return alarm.getAllAlarms();
   }
 
   /**
-   * Check if an alarm is scheduled
+   * Checks whether an alarm is currently scheduled.
+   *
+   * @param alarmId Identifier of the alarm to check.
+   * @returns A promise resolving to `true` if scheduled, otherwise `false`.
+   * @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);
   }
+
+  /**
+   * Opens the device manufacturer's Auto Start settings screen.
+   *
+   * This is primarily intended for Android devices whose manufacturers
+   * provide additional background-execution settings.
+   *
+   * On iOS, the native implementation resolves to `false`.
+   *
+   * @returns A promise resolving to `true` if the settings screen was
+   * opened, or `false` if unsupported or unavailable.
+   * @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();
+  }
 }
 
-// Export a singleton instance
+/**
+ * Default export for convenient service access.
+ *
+ * @example
+ * ```typescript
+ * import AlarmService from 'react-native-alarms/service';
+ *
+ * const alarms = await AlarmService.getAllAlarms();
+ * ```
+ */
 export default AlarmService;

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 react-native-alarm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,11 @@
 # React Native Alarms 🔔
 
-A powerful, cross-platform alarm management library for React Native. Schedule, manage, and control alarms on both Android and iOS with a unified API.
+A cross-platform native scheduling, reminder, and wake-up system for React Native. Schedule time-sensitive events on Android and iOS, deliver reminders, and present a registered custom React Native screen when a scheduled event fires—using one unified API.
+
+Although it can power a traditional alarm clock, react-native-alarms is also useful for exact-time reminders, scheduled check-ins, custom lock-screen experiences, and time-based app workflows. Build the experience around your own UI and event data instead of being limited to a standard alarm screen.
+
+> **Platform note:** The operating system controls background delivery and screen presentation. Exact timing, full-screen presentation, and behavior when an app is terminated depend on platform version, permissions, device settings, and the native scheduling mechanism. This library does not provide unrestricted background JavaScript execution.
+
 
 [![npm version](https://badge.fury.io/js/react-native-alarms.svg)](https://badge.fury.io/js/react-native-alarms)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -65,6 +70,44 @@ AppRegistry.registerComponent('AlarmRing', () => AlarmRingScreen);
 Call `Alarm.stopAlarm(alarmId)` or `Alarm.snoozeAlarm(alarmId, minutes)` from its
 buttons; the screen closes itself.
 
+#### Custom presentation component
+
+You can register **multiple** ring screens and choose which one fires per alarm using the `presentation` field in `AlarmConfig`:
+
+```js
+// index.js
+import { AppRegistry } from 'react-native';
+import { AlarmRingScreen } from './src/AlarmRingScreen';
+import { ReminderScreen } from './src/ReminderScreen';
+
+AppRegistry.registerComponent('AlarmRing', () => AlarmRingScreen);   // default
+AppRegistry.registerComponent('Reminder', () => ReminderScreen);     // custom
+```
+
+```ts
+import { AlarmRegistry, AlarmService } from 'react-native-alarms/service';
+
+// 1. Map your key to the registered component name
+AlarmRegistry.register('reminder', 'Reminder');
+
+// 2. Pass it when scheduling
+await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 60_000,
+  title: 'Standup',
+  presentation: {
+    type: 'reminder',           // resolves to the 'Reminder' component
+    props: { color: '#6200EE' } // forwarded to the screen as componentProps
+  },
+});
+```
+
+The native layer maps `presentation` to two internal fields:
+
+| Internal field | Type | Default | Description |
+|---|---|---|---|
+| `componentName` | `string` | `"AlarmRing"` | Registered `AppRegistry` component name shown when the alarm rings. |
+| `componentProps` / `componentPropsJSON` | `object` / `string` | `{}` | Key-value props forwarded to the ring screen on **both platforms**. On Android they arrive as top-level bundle extras and a nested `componentProps` map; on iOS as a parsed `[String: Any]` dictionary. |
+
 ### Direct module access
 
 ```ts
@@ -179,9 +222,28 @@ type AlarmConfig = {
   snoozeMinutes?: number;     // Snooze duration in minutes
   repeat?: AlarmRepeat;       // Repeat configuration
   data?: string;              // Custom JSON string payload
+  presentation?: AlarmPresentation; // Custom ring screen & props
+};
+
+type AlarmPresentation = {
+  /** Registered presentation type (key passed to AlarmRegistry.register). */
+  type?: string;
+  /**
+   * Props forwarded to the ring screen component.
+   * Available as `componentProps` on both Android and iOS.
+   */
+  props?: Record<string, unknown>;
 };
 ```
 
+> **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 |
+> |---|---|---|---|
+> | `componentName` | `string` | `"AlarmRing"` | The `AppRegistry` name of the component shown at ring time. Derived from `AlarmRegistry.resolve(presentation.type)`. |
+> | `componentProps` | `object` | `{}` | Parsed props object (from `presentation.props`). Available on both platforms at ring time as `componentProps`. |
+> | `componentPropsJSON` | `string` | `"{}"` | JSON-serialised representation of `componentProps`, persisted alongside the alarm so props survive a device reboot. |
+
 #### `AlarmRepeat`
 Repeat configuration for recurring alarms.
 
@@ -361,6 +423,22 @@ const styles = StyleSheet.create({
 });
 ```
 
+## 📸 Screenshots, Demos & Examples
+
+Explore how `react-native-alarms` works on Android and iOS.
+
+### 🖼️ Screenshots
+
+| Sample 1 | Sample 2 | Sample 3 |
+|---|---|---|
+| <img src="src/assets/sample-1.png" width="180" alt="Sample 1" /> | <img src="src/assets/sample-2.png" width="180" alt="Sample 2" /> | <img src="src/assets/sample-3.png" width="180" alt="Sample 3" /> |
+
+### 🎥 Demo Video
+
+Watch the library in action, including alarm scheduling, ringing, and Stop/Snooze interactions.
+
+[▶️ Watch the React Native Alarms Demo](src/assets/recording.mp4)
+
 ## Troubleshooting
 
 ### "Alarm Native module is not linked"
@@ -417,27 +495,99 @@ For issues and questions, please visit:
 
 The library supports completely custom alarm UI screens with custom data payloads.
 
-### Basic Custom Screen Example
+### Using `componentName` and `componentProps`
+
+The `presentation` field lets you choose **which registered component** is displayed and pass **arbitrary props** directly to it — without encoding everything inside a JSON `data` string.
+
+#### 1. Register your screens
+
+```js
+// index.js
+import { AppRegistry } from 'react-native';
+import { AlarmRingScreen }   from './src/AlarmRingScreen';
+import { MeetingAlarmScreen } from './src/MeetingAlarmScreen';
+
+AppRegistry.registerComponent('AlarmRing',    () => AlarmRingScreen);    // default fallback
+AppRegistry.registerComponent('MeetingAlarm', () => MeetingAlarmScreen); // custom
+```
+
+#### 2. Map a key to the component name
+
+```ts
+import { AlarmRegistry } from 'react-native-alarms';
+
+AlarmRegistry.register('meeting', 'MeetingAlarm');
+```
+
+#### 3. Schedule with `presentation`
 
 ```typescript
-import { NativeModules } from 'react-native';
 import { AlarmService } from 'react-native-alarms/service';
 
-export function MyCustomAlarmScreen({ alarmId, title, data }) {
-  const customData = JSON.parse(data || '{}');
+await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 5 * 60 * 1000,
+  title: 'Team standup',
+  presentation: {
+    type: 'meeting',                    // resolves to 'MeetingAlarm'
+    props: {
+      roomName: 'Zoom Room A',
+      meetingUrl: 'https://zoom.us/j/123',
+      accentColor: '#6200EE',
+    },
+  },
+});
+```
+
+#### 4. Receive `componentProps` in your screen
+
+The props passed via `presentation.props` are forwarded to the ring screen on both platforms:
+
+```typescript
+// MeetingAlarmScreen.tsx
+type Props = {
+  alarmId: string;
+  title: string;
+  snoozeEnabled: boolean;
+  snoozeMinutes: number;
+  data?: string;
+  // componentProps fields arrive as top-level props:
+  roomName?: string;
+  meetingUrl?: string;
+  accentColor?: string;
+};
 
+export function MeetingAlarmScreen({
+  alarmId,
+  title,
+  snoozeEnabled,
+  snoozeMinutes,
+  roomName,
+  meetingUrl,
+  accentColor = '#007AFF',
+}: Props) {
   return (
-    <View style={{ backgroundColor: customData.color }}>
-      <Text>{title}</Text>
+    <View style={{ flex: 1, backgroundColor: accentColor }}>
+      <Text style={{ fontSize: 28, color: '#fff' }}>{title}</Text>
+      <Text style={{ color: '#fff' }}>{roomName}</Text>
+
+      {snoozeEnabled && (
+        <TouchableOpacity onPress={() => AlarmService.snoozeAlarm(alarmId, snoozeMinutes)}>
+          <Text>Snooze {snoozeMinutes} min</Text>
+        </TouchableOpacity>
+      )}
       <TouchableOpacity onPress={() => AlarmService.stopAlarm(alarmId)}>
-        <Text>Stop</Text>
+        <Text>Dismiss</Text>
       </TouchableOpacity>
     </View>
   );
 }
 ```
 
-### Passing Custom Data
+> **Platform behaviour**
+> - **Android**: `componentProps` entries are flattened into the launch `Bundle` alongside standard fields (`alarmId`, `title`, etc.), and also available as a nested `componentProps` bundle. The `AlarmRingActivity` uses `componentName` to resolve which registered React root to display.
+> - **iOS**: `componentProps` (parsed from `componentPropsJSON`) is merged into the surface's initial properties passed to the React component.
+
+### Passing Custom Data (legacy approach)
 
 ```typescript
 await AlarmService.scheduleAlarm({