react-native-alarms 0.0.6 → 0.0.7

package/AlarmService.d.ts

@@ -1,115 +1,219 @@
 /**
- * AlarmService - High-level alarm management API
- * Provides convenient wrapper methods for the native alarm module
+ * 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,
-  Alarm,
+  AlarmProp,
   AlarmPermission,
   AlarmEvent,
-} from './specs/NativeAlarm';
+} 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;
 
 /**
- * High-level alarm service for managing alarms
+ * Static service for managing native alarms.
+ *
+ * All methods can be called directly without creating an instance.
  */
 export class AlarmService {
   /**
-   * Initialize the alarm service and set up event listeners
+   * 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;
 
   /**
-   * Cleanup event listeners
+   * 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;
 
   /**
-   * Register a listener for when alarms fire
-   * @returns unsubscribe function
+   * 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;
 
   /**
-   * Register a listener for when alarms are dismissed
-   * @returns unsubscribe function
+   * 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;
 
   /**
-   * Register a listener for when alarms are snoozed
-   * @returns unsubscribe function
+   * 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;
 
   /**
-   * Check the current alarm permissions
+   * 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>;
 
   /**
-   * Request alarm permissions
+   * 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>;
 
   /**
-   * Schedule a new alarm
-   * @returns alarm ID
+   * 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>;
 
   /**
-   * Update an existing alarm
-   * @returns boolean indicating success
+   * 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>;
 
   /**
-   * Cancel an alarm
-   * @returns boolean if alarm existed
+   * 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>;
 
   /**
-   * Cancel all alarms
+   * 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>;
 
   /**
-   * Stop the currently ringing alarm
+   * 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>;
 
   /**
-   * Snooze the currently ringing alarm
-   * @param minutes - snooze duration (defaults to alarm's snoozeMinutes)
+   * 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>;
 
   /**
-   * Get the currently ringing alarm (if any)
+   * 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<Alarm | null>;
+  static getRingingAlarm(): Promise<AlarmProp | null>;
 
   /**
-   * Get a specific alarm by ID
+   * 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<Alarm | null>;
+  static getAlarm(alarmId: string): Promise<AlarmProp | null>;
 
   /**
-   * Get all scheduled alarms
+   * 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<Alarm[]>;
+  static getAllAlarms(): Promise<AlarmProp[]>;
 
   /**
-   * Check if an alarm is scheduled
+   * 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 vendor Autostart screen on Android; resolves false on iOS.
+   * 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>;
 }

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,12 +92,21 @@ 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) => {
@@ -64,42 +129,76 @@ export class AlarmService {
   }
 
   /**
-   * 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');
@@ -107,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');
@@ -115,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,
@@ -134,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');
@@ -142,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');
@@ -150,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');
@@ -158,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');
@@ -166,43 +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 vendor Autostart screen on Android; resolves false on iOS. */
+  /**
+   * 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;