react-native-alarmageddon 1.0.0

package/src/index.ts

@@ -0,0 +1,317 @@
+import {
+  NativeModules,
+  NativeEventEmitter,
+  PermissionsAndroid,
+  Platform,
+  EmitterSubscription,
+} from 'react-native';
+
+/**
+ * Parameters for scheduling an alarm
+ */
+export type AlarmParams = {
+  /** Unique identifier for the alarm */
+  id: string;
+  /** ISO 8601 datetime string for when the alarm should trigger */
+  datetimeISO: string;
+  /** Title shown in the notification */
+  title?: string;
+  /** Body text shown in the notification */
+  body?: string;
+  /** URI of the sound to play (uses default alarm sound if not provided) */
+  soundUri?: string;
+  /** Whether to vibrate when alarm triggers (default: true) */
+  vibrate?: boolean;
+  /** Number of minutes for snooze (default: 5) */
+  snoozeMinutes?: number;
+  /** Number of seconds before alarm auto-stops (default: 60) */
+  autoStopSeconds?: number;
+};
+
+/**
+ * Stored alarm data returned from listAlarms
+ */
+export type StoredAlarm = {
+  id: string;
+  datetimeISO: string;
+  title: string;
+  body: string;
+  vibrate: boolean;
+  snoozeMinutes: number;
+  autoStopSeconds: number;
+};
+
+/**
+ * Permission request result
+ */
+export type PermissionResult = {
+  granted: boolean;
+  exactAlarmGranted?: boolean;
+};
+
+/**
+ * Active alarm info
+ */
+export type ActiveAlarmInfo = {
+  activeAlarmId: string;
+} | null;
+
+/**
+ * Native module interface
+ */
+interface AlarmModuleInterface {
+  scheduleAlarm(alarm: AlarmParams): Promise<void>;
+  cancelAlarm(id: string): Promise<void>;
+  listAlarms(): Promise<StoredAlarm[]>;
+  requestPermissions(): Promise<PermissionResult>;
+  checkExactAlarmPermission(): Promise<boolean>;
+  openExactAlarmSettings(): Promise<void>;
+  snoozeAlarm(id: string, minutes: number): Promise<void>;
+  stopCurrentAlarm(id: string): Promise<void>;
+  snoozeCurrentAlarm(id: string, minutes: number): Promise<void>;
+  getCurrentAlarmPlaying(): Promise<ActiveAlarmInfo>;
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+const { AlarmModule } = NativeModules as { AlarmModule: AlarmModuleInterface };
+
+// Validate module exists
+if (!AlarmModule) {
+  throw new Error(
+    'react-native-alarmageddon: NativeModule is null. ' +
+      'Ensure you have linked the native module correctly. ' +
+      'On Android, run `npx react-native run-android` to rebuild.'
+  );
+}
+
+const eventEmitter = new NativeEventEmitter(NativeModules.AlarmModule);
+
+/**
+ * Request notification permission (required on Android 13+)
+ * @returns Promise resolving to true if permission granted
+ */
+async function requestNotificationPermission(): Promise<boolean> {
+  if (Platform.OS !== 'android') {
+    return true;
+  }
+
+  try {
+    if (Platform.Version >= 33) {
+      const status = await PermissionsAndroid.request(
+        'android.permission.POST_NOTIFICATIONS' as any
+      );
+      return status === PermissionsAndroid.RESULTS.GRANTED;
+    }
+    return true;
+  } catch (error) {
+    console.warn('Failed to request notification permission:', error);
+    return false;
+  }
+}
+
+/**
+ * Request exact alarm permission (required on Android 12+)
+ * Opens system settings if not granted
+ * @returns Promise resolving to permission result
+ */
+async function requestExactAlarmPermission(): Promise<PermissionResult> {
+  if (Platform.OS !== 'android') {
+    return { granted: true, exactAlarmGranted: true };
+  }
+
+  return AlarmModule.requestPermissions();
+}
+
+/**
+ * Check if exact alarm permission is granted
+ * @returns Promise resolving to true if permission granted
+ */
+async function checkExactAlarmPermission(): Promise<boolean> {
+  if (Platform.OS !== 'android') {
+    return true;
+  }
+
+  return AlarmModule.checkExactAlarmPermission();
+}
+
+/**
+ * Open system settings for exact alarm permission
+ */
+async function openExactAlarmSettings(): Promise<void> {
+  if (Platform.OS === 'android') {
+    return AlarmModule.openExactAlarmSettings();
+  }
+}
+
+/**
+ * Ensure all required permissions are granted
+ * Requests both notification and exact alarm permissions
+ * @returns Promise resolving to true if all permissions granted
+ */
+async function ensurePermissions(): Promise<boolean> {
+  if (Platform.OS !== 'android') {
+    return true;
+  }
+
+  const [notificationGranted, exactAlarmResult] = await Promise.all([
+    requestNotificationPermission(),
+    requestExactAlarmPermission(),
+  ]);
+
+  return notificationGranted && exactAlarmResult.granted;
+}
+
+/**
+ * Schedule an alarm
+ * @param alarm - Alarm parameters
+ */
+async function scheduleAlarm(alarm: AlarmParams): Promise<void> {
+  if (!alarm.id) {
+    throw new Error('Alarm ID is required');
+  }
+  if (!alarm.datetimeISO) {
+    throw new Error('datetimeISO is required');
+  }
+
+  return AlarmModule.scheduleAlarm(alarm);
+}
+
+/**
+ * Cancel a scheduled alarm
+ * @param id - Alarm ID to cancel
+ */
+async function cancelAlarm(id: string): Promise<void> {
+  if (!id) {
+    throw new Error('Alarm ID is required');
+  }
+  return AlarmModule.cancelAlarm(id);
+}
+
+/**
+ * List all scheduled alarms
+ * @returns Promise resolving to array of stored alarms
+ */
+async function listAlarms(): Promise<StoredAlarm[]> {
+  return AlarmModule.listAlarms();
+}
+
+/**
+ * Snooze an alarm for a specified number of minutes
+ * @param id - Alarm ID to snooze
+ * @param minutes - Number of minutes to snooze (default: 5)
+ */
+async function snoozeAlarm(id: string, minutes: number = 5): Promise<void> {
+  if (!id) {
+    throw new Error('Alarm ID is required');
+  }
+  return AlarmModule.snoozeAlarm(id, minutes);
+}
+
+/**
+ * Stop the currently playing alarm
+ * @param id - Alarm ID to stop
+ */
+async function stopCurrentAlarm(id: string): Promise<void> {
+  if (!id) {
+    throw new Error('Alarm ID is required');
+  }
+  return AlarmModule.stopCurrentAlarm(id);
+}
+
+/**
+ * Snooze the currently playing alarm
+ * @param id - Alarm ID to snooze
+ * @param minutes - Number of minutes to snooze (default: 5)
+ */
+async function snoozeCurrentAlarm(id: string, minutes: number = 5): Promise<void> {
+  if (!id) {
+    throw new Error('Alarm ID is required');
+  }
+  return AlarmModule.snoozeCurrentAlarm(id, minutes);
+}
+
+/**
+ * Get the currently playing alarm (if any)
+ * @returns Promise resolving to active alarm info or null
+ */
+async function getCurrentAlarmPlaying(): Promise<ActiveAlarmInfo> {
+  return AlarmModule.getCurrentAlarmPlaying();
+}
+
+/**
+ * Subscribe to alarm state changes
+ * Callback receives the alarm ID when an alarm starts, or null when stopped
+ * @param callback - Function called when alarm state changes
+ * @returns Cleanup function to remove the subscription
+ */
+function onAlarmStateChange(
+  callback: (alarmId: string | null) => void
+): () => void {
+  const subscription: EmitterSubscription = eventEmitter.addListener(
+    'activeAlarmId',
+    callback
+  );
+  return () => subscription.remove();
+}
+
+/**
+ * Add event listener for alarm state changes
+ * @param event - Event name ('activeAlarmId')
+ * @param callback - Callback function
+ * @returns EmitterSubscription for removal
+ */
+function addEventListener(
+  event: 'activeAlarmId',
+  callback: (alarmId: string | null) => void
+): EmitterSubscription {
+  return eventEmitter.addListener(event, callback);
+}
+
+/**
+ * Main module export with all alarm functions
+ */
+const RNAlarmModule = {
+  // Permissions
+  ensurePermissions,
+  requestNotificationPermission,
+  requestExactAlarmPermission,
+  checkExactAlarmPermission,
+  openExactAlarmSettings,
+
+  // Alarm management
+  scheduleAlarm,
+  cancelAlarm,
+  listAlarms,
+  snoozeAlarm,
+
+  // Active alarm control
+  stopCurrentAlarm,
+  snoozeCurrentAlarm,
+  getCurrentAlarmPlaying,
+
+  // Event handling
+  onAlarmStateChange,
+  addEventListener,
+};
+
+export default RNAlarmModule;
+export { RNAlarmModule };
+
+// Export individual functions for tree-shaking
+export {
+  ensurePermissions,
+  requestNotificationPermission,
+  requestExactAlarmPermission,
+  checkExactAlarmPermission,
+  openExactAlarmSettings,
+  scheduleAlarm,
+  cancelAlarm,
+  listAlarms,
+  snoozeAlarm,
+  stopCurrentAlarm,
+  snoozeCurrentAlarm,
+  getCurrentAlarmPlaying,
+  onAlarmStateChange,
+  addEventListener,
+};