react-native-alarms 0.0.0-stage → 0.0.2

package/.bundle/config

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

package/AlarmService.d.ts

@@ -0,0 +1,112 @@
+/**
+ * AlarmService - High-level alarm management API
+ * Provides convenient wrapper methods for the native alarm module
+ */
+
+import type {
+  AlarmConfig,
+  Alarm,
+  AlarmPermission,
+  AlarmEvent,
+} from './specs/NativeAlarm';
+
+type AlarmEventListener = (alarm: AlarmEvent) => void;
+
+/**
+ * High-level alarm service for managing alarms
+ */
+export class AlarmService {
+  /**
+   * Initialize the alarm service and set up event listeners
+   */
+  static initialize(): void;
+
+  /**
+   * Cleanup event listeners
+   */
+  static cleanup(): void;
+
+  /**
+   * Register a listener for when alarms fire
+   * @returns unsubscribe function
+   */
+  static onAlarmFired(listener: AlarmEventListener): () => void;
+
+  /**
+   * Register a listener for when alarms are dismissed
+   * @returns unsubscribe function
+   */
+  static onAlarmDismissed(listener: AlarmEventListener): () => void;
+
+  /**
+   * Register a listener for when alarms are snoozed
+   * @returns unsubscribe function
+   */
+  static onAlarmSnoozed(listener: AlarmEventListener): () => void;
+
+  /**
+   * Check the current alarm permissions
+   */
+  static checkPermission(): Promise<AlarmPermission>;
+
+  /**
+   * Request alarm permissions
+   */
+  static requestPermission(): Promise<AlarmPermission>;
+
+  /**
+   * Schedule a new alarm
+   * @returns alarm ID
+   */
+  static scheduleAlarm(config: AlarmConfig): Promise<string>;
+
+  /**
+   * Update an existing alarm
+   * @returns boolean indicating success
+   */
+  static updateAlarm(alarmId: string, config: AlarmConfig): Promise<boolean>;
+
+  /**
+   * Cancel an alarm
+   * @returns boolean if alarm existed
+   */
+  static cancelAlarm(alarmId: string): Promise<boolean>;
+
+  /**
+   * Cancel all alarms
+   */
+  static cancelAllAlarms(): Promise<void>;
+
+  /**
+   * Stop the currently ringing alarm
+   */
+  static stopAlarm(alarmId: string): Promise<void>;
+
+  /**
+   * Snooze the currently ringing alarm
+   * @param minutes - snooze duration (defaults to alarm's snoozeMinutes)
+   */
+  static snoozeAlarm(alarmId: string, minutes?: number): Promise<void>;
+
+  /**
+   * Get the currently ringing alarm (if any)
+   */
+  static getRingingAlarm(): Promise<Alarm | null>;
+
+  /**
+   * Get a specific alarm by ID
+   */
+  static getAlarm(alarmId: string): Promise<Alarm | null>;
+
+  /**
+   * Get all scheduled alarms
+   */
+  static getAllAlarms(): Promise<Alarm[]>;
+
+  /**
+   * Check if an alarm is scheduled
+   */
+  static isScheduled(alarmId: string): Promise<boolean>;
+}
+
+export default AlarmService;

package/AlarmService.ts

@@ -0,0 +1,196 @@
+/**
+ * AlarmService - 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.
+ */
+
+import { NativeEventEmitter, NativeModules } from 'react-native';
+import type {
+  AlarmConfig,
+  Alarm,
+  AlarmPermission,
+  AlarmEvent,
+} from './specs/NativeAlarm';
+
+const { Alarm: NativeAlarm } = NativeModules;
+
+// Guard against module not being linked
+const alarm = NativeAlarm ? require('./specs/NativeAlarm').default : null;
+
+const alarmEmitter = NativeAlarm ? new NativeEventEmitter(NativeAlarm) : null;
+
+type AlarmEventListener = (alarm: AlarmEvent) => void;
+
+/**
+ * High-level alarm service for managing alarms
+ */
+export class AlarmService {
+  private static listeners: {
+    fired: Set<AlarmEventListener>;
+    dismissed: Set<AlarmEventListener>;
+    snoozed: Set<AlarmEventListener>;
+  } = {
+    fired: new Set(),
+    dismissed: new Set(),
+    snoozed: new Set(),
+  };
+
+  private static subscriptions: any[] = [];
+
+  /**
+   * Initialize the alarm service and set up event listeners
+   */
+  static initialize() {
+    if (!alarmEmitter || !this.subscriptions.length) {
+      this.subscriptions = [
+        alarmEmitter?.addListener('onAlarmFired', (data: any) => {
+          this.listeners.fired.forEach(listener => listener(data as AlarmEvent));
+        }),
+        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);
+    }
+  }
+
+  /**
+   * Cleanup event listeners
+   */
+  static cleanup() {
+    this.subscriptions.forEach(sub => sub?.remove());
+    this.subscriptions = [];
+  }
+
+  /**
+   * Register a listener for when alarms fire
+   */
+  static onAlarmFired(listener: AlarmEventListener) {
+    this.initialize();
+    this.listeners.fired.add(listener);
+    return () => this.listeners.fired.delete(listener);
+  }
+
+  /**
+   * Register a listener for when alarms are dismissed
+   */
+  static onAlarmDismissed(listener: AlarmEventListener) {
+    this.initialize();
+    this.listeners.dismissed.add(listener);
+    return () => this.listeners.dismissed.delete(listener);
+  }
+
+  /**
+   * Register a listener for when alarms are snoozed
+   */
+  static onAlarmSnoozed(listener: AlarmEventListener) {
+    this.initialize();
+    this.listeners.snoozed.add(listener);
+    return () => this.listeners.snoozed.delete(listener);
+  }
+
+  /**
+   * Check the current alarm permissions
+   */
+  static async checkPermission(): Promise<AlarmPermission> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.checkPermission();
+  }
+
+  /**
+   * Request alarm permissions
+   */
+  static async requestPermission(): Promise<AlarmPermission> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.requestPermission();
+  }
+
+  /**
+   * Schedule a new alarm
+   */
+  static async scheduleAlarm(config: AlarmConfig): Promise<string> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.scheduleAlarm(config);
+  }
+
+  /**
+   * Update an existing alarm
+   */
+  static async updateAlarm(
+    alarmId: string,
+    config: AlarmConfig,
+  ): Promise<boolean> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.updateAlarm(alarmId, config);
+  }
+
+  /**
+   * Cancel an alarm
+   */
+  static async cancelAlarm(alarmId: string): Promise<boolean> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.cancelAlarm(alarmId);
+  }
+
+  /**
+   * Cancel all alarms
+   */
+  static async cancelAllAlarms(): Promise<void> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.cancelAllAlarms();
+  }
+
+  /**
+   * Stop the currently ringing alarm
+   */
+  static async stopAlarm(alarmId: string): Promise<void> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.stopAlarm(alarmId);
+  }
+
+  /**
+   * Snooze the currently ringing alarm
+   */
+  static async snoozeAlarm(alarmId: string, minutes?: number): Promise<void> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.snoozeAlarm(alarmId, minutes ?? 5);
+  }
+
+  /**
+   * Get the currently ringing alarm (if any)
+   */
+  static async getRingingAlarm(): Promise<Alarm | null> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.getRingingAlarm();
+  }
+
+  /**
+   * Get a specific alarm by ID
+   */
+  static async getAlarm(alarmId: string): Promise<Alarm | null> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.getAlarm(alarmId);
+  }
+
+  /**
+   * Get all scheduled alarms
+   */
+  static async getAllAlarms(): Promise<Alarm[]> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.getAllAlarms();
+  }
+
+  /**
+   * Check if an alarm is scheduled
+   */
+  static async isScheduled(alarmId: string): Promise<boolean> {
+    if (!alarm) throw new Error('Alarm module not linked');
+    return alarm.isScheduled(alarmId);
+  }
+}
+
+// Export a singleton instance
+export default AlarmService;

package/README.md

@@ -1,3 +1,386 @@
-# Temporary Holding Version
+# React Native Alarms 🔔
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A powerful, cross-platform alarm management library for React Native. Schedule, manage, and control alarms on both Android and iOS with a unified API.
+
+[![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)
+
+## Features
+
+✨ **Cross-Platform Support**
+- Seamless support for both Android and iOS
+- Native alarm implementation for reliable delivery
+- Background execution support
+
+🎯 **Comprehensive Alarm Management**
+- Schedule one-time and recurring alarms (daily, weekly, interval-based)
+- Update and cancel alarms
+- Snooze and stop currently ringing alarms
+- Query alarm status
+
+🔔 **Event-Driven Architecture**
+- Real-time events for alarm firing, dismissal, and snoozing
+- Easy event listener registration and cleanup
+- Full-screen alarm display on iOS 26+ with AlarmKit
+- Fallback to notifications on older devices
+
+🔐 **Permission Handling**
+- Automatic permission checking and requesting
+- Platform-specific permission management
+- Detailed permission status reporting
+
+## Installation
+
+```bash
+npm install react-native-alarms
+# or
+yarn add react-native-alarms
+```
+
+### Native Module Linking
+
+Since this is a native module, you'll need to link it:
+
+```bash
+cd ios && pod install && cd ..
+```
+
+For Android, the native code should auto-link.
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { AlarmService } from 'react-native-alarms/service';
+
+// Check permissions
+const permission = await AlarmService.checkPermission();
+
+// Request permissions if needed
+if (permission.status !== 'granted') {
+  await AlarmService.requestPermission();
+}
+
+// Schedule an alarm for 10 minutes from now
+const alarmId = await AlarmService.scheduleAlarm({
+  timestamp: Date.now() + 10 * 60 * 1000,
+  title: 'Wake up!',
+  body: 'Time to start your day',
+  vibrate: true,
+  snoozeEnabled: true,
+  snoozeMinutes: 5,
+});
+
+console.log('Alarm scheduled:', alarmId);
+```
+
+### Listening to Alarm Events
+
+```typescript
+import { AlarmService } from 'react-native-alarms/service';
+
+// Listen for when alarm fires
+const unsubscribeFired = AlarmService.onAlarmFired((alarm) => {
+  console.log('Alarm fired:', alarm.title);
+});
+
+// Listen for when alarm is dismissed
+const unsubscribeDismissed = AlarmService.onAlarmDismissed((alarm) => {
+  console.log('Alarm dismissed:', alarm.alarmId);
+});
+
+// Listen for when alarm is snoozed
+const unsubscribeSnoozed = AlarmService.onAlarmSnoozed((alarm) => {
+  console.log('Alarm snoozed:', alarm.alarmId);
+});
+
+// Cleanup listeners when done
+unsubscribeFired();
+unsubscribeDismissed();
+unsubscribeSnoozed();
+```
+
+### Managing Alarms
+
+```typescript
+import { AlarmService } from 'react-native-alarms/service';
+
+// Get all scheduled alarms
+const alarms = await AlarmService.getAllAlarms();
+
+// Get a specific alarm
+const alarm = await AlarmService.getAlarm(alarmId);
+
+// Check if alarm is scheduled
+const isScheduled = await AlarmService.isScheduled(alarmId);
+
+// Update an alarm
+await AlarmService.updateAlarm(alarmId, {
+  timestamp: Date.now() + 20 * 60 * 1000,
+  title: 'Updated alarm',
+});
+
+// Snooze the currently ringing alarm
+await AlarmService.snoozeAlarm(alarmId, 10); // Snooze for 10 minutes
+
+// Stop the currently ringing alarm
+await AlarmService.stopAlarm(alarmId);
+
+// Cancel a specific alarm
+await AlarmService.cancelAlarm(alarmId);
+
+// Cancel all alarms
+await AlarmService.cancelAllAlarms();
+```
+
+## API Reference
+
+### Types
+
+#### `AlarmConfig`
+Configuration object for scheduling alarms.
+
+```typescript
+type AlarmConfig = {
+  alarmId?: string;           // Unique identifier (auto-generated if omitted)
+  timestamp: number;          // Time in milliseconds (Date.now() format)
+  title: string;              // Alarm title/label
+  body?: string;              // Alarm description
+  sound?: string;             // 'default' or custom sound file name
+  vibrate?: boolean;          // Enable vibration (Android only)
+  snoozeEnabled?: boolean;    // Allow snoozing
+  snoozeMinutes?: number;     // Snooze duration in minutes
+  repeat?: AlarmRepeat;       // Repeat configuration
+  data?: string;              // Custom JSON string payload
+};
+```
+
+#### `AlarmRepeat`
+Repeat configuration for recurring alarms.
+
+```typescript
+type AlarmRepeat = {
+  type: 'none' | 'daily' | 'weekly' | 'interval';
+  weekdays?: number[];        // 1 = Sunday, 7 = Saturday (for weekly)
+  intervalMs?: number;        // Interval in milliseconds (for interval type)
+};
+```
+
+#### `Alarm`
+Alarm object returned from queries.
+
+```typescript
+type Alarm = {
+  alarmId: string;
+  timestamp: number;
+  title: string;
+  body: string;
+  sound: string;
+  vibrate: boolean;
+  snoozeEnabled: boolean;
+  snoozeMinutes: number;
+  repeat: AlarmRepeat;
+  data: string;
+  enabled: boolean;
+  nextTriggerAt: number;      // 0 if no future trigger
+};
+```
+
+#### `AlarmPermission`
+Permission status object.
+
+```typescript
+type AlarmPermission = {
+  status: 'granted' | 'denied' | 'notDetermined';
+  notifications: boolean;
+  canScheduleExact: boolean;
+  canDrawOverlays: boolean;   // Android only
+  canUseFullScreenIntent: boolean; // Android only
+  backend?: string;           // iOS only: 'alarmkit' or 'notifications'
+};
+```
+
+## Platform-Specific Behavior
+
+### iOS
+- **iOS 26+**: Uses native AlarmKit for real alarms that bypass silent mode
+- **iOS < 26**: Falls back to local notifications
+- Always handles vibration through system settings
+- Full-screen alarm display with system Stop/Snooze buttons
+
+### Android
+- Requires `SCHEDULE_EXACT_ALARM` permission for exact timing
+- Uses full-screen notifications on lock screen
+- Respects silent mode (can be overridden with system settings)
+- Supports custom sounds from app bundle or file system
+
+## Repeat Types
+
+### None (One-time)
+```typescript
+{ type: 'none' }
+```
+
+### Daily
+Rings at the same time every day.
+```typescript
+{ type: 'daily' }
+```
+
+### Weekly
+Rings at the same time on specified days.
+```typescript
+{
+  type: 'weekly',
+  weekdays: [1, 3, 5] // Sunday, Wednesday, Friday
+}
+```
+
+### Interval
+Rings at regular intervals. Note: intervals reset if the app is killed.
+```typescript
+{
+  type: 'interval',
+  intervalMs: 3600000 // Every hour
+}
+```
+
+## Complete Example
+
+```typescript
+import React, { useEffect, useState } from 'react';
+import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
+import { AlarmService } from 'react-native-alarms/service';
+
+export function AlarmScreen() {
+  const [alarms, setAlarms] = useState([]);
+  const [permissions, setPermissions] = useState(null);
+
+  useEffect(() => {
+    initializeAlarms();
+  }, []);
+
+  const initializeAlarms = async () => {
+    const perms = await AlarmService.checkPermission();
+    setPermissions(perms);
+
+    if (perms.status !== 'granted') {
+      await AlarmService.requestPermission();
+    }
+
+    const allAlarms = await AlarmService.getAllAlarms();
+    setAlarms(allAlarms);
+
+    const unsubFired = AlarmService.onAlarmFired((alarm) => {
+      console.log('🔔 Alarm fired:', alarm.title);
+    });
+
+    const unsubSnoozed = AlarmService.onAlarmSnoozed((alarm) => {
+      console.log('😴 Alarm snoozed:', alarm.title);
+    });
+
+    return () => {
+      unsubFired();
+      unsubSnoozed();
+    };
+  };
+
+  const scheduleAlarm = async () => {
+    const alarmId = await AlarmService.scheduleAlarm({
+      timestamp: Date.now() + 5 * 60 * 1000,
+      title: 'Time for a break!',
+      body: 'Take a moment to rest',
+      vibrate: true,
+      snoozeEnabled: true,
+      snoozeMinutes: 5,
+    });
+
+    const updated = await AlarmService.getAllAlarms();
+    setAlarms(updated);
+  };
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Alarm Manager</Text>
+      
+      <TouchableOpacity
+        style={styles.button}
+        onPress={scheduleAlarm}
+      >
+        <Text style={styles.buttonText}>Schedule Alarm</Text>
+      </TouchableOpacity>
+
+      <View style={styles.list}>
+        {alarms.map((alarm) => (
+          <View key={alarm.alarmId} style={styles.alarmItem}>
+            <Text>{alarm.title}</Text>
+            <Text>{new Date(alarm.timestamp).toLocaleTimeString()}</Text>
+          </View>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, padding: 20 },
+  title: { fontSize: 24, fontWeight: 'bold', marginBottom: 20 },
+  button: { backgroundColor: '#007AFF', padding: 12, borderRadius: 8 },
+  buttonText: { color: '#fff', fontWeight: 'bold', textAlign: 'center' },
+  list: { marginTop: 20 },
+  alarmItem: { padding: 12, borderBottomWidth: 1, borderBottomColor: '#eee' },
+});
+```
+
+## Troubleshooting
+
+### "Alarm Native module is not linked"
+Ensure the native module is properly linked:
+```bash
+cd ios && pod install && cd ..
+```
+
+### Alarms not triggering
+1. Check permissions: `await AlarmService.checkPermission()`
+2. Ensure app has necessary permissions:
+   - Android: `SCHEDULE_EXACT_ALARM`, `POST_NOTIFICATIONS`
+   - iOS: Allow notifications in Settings
+
+### iOS-specific: Notifications instead of full-screen alarm
+- Full-screen alarms (AlarmKit) require iOS 26+
+- Older devices use local notifications
+- Check `permission.backend` to see which is active
+
+### Android-specific: Alarm doesn't ring when app is killed
+- Enable Autostart permissions on device
+- Check device's battery optimization settings
+- Some OEMs require manual approval in their app management screens
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © 2024 Suraj Prasad
+
+## Support
+
+For issues and questions, please visit:
+- GitHub Issues: https://github.com/surajprasad13/react-native-alarms/issues
+- Email: surajvishwakarma830@gmail.com
+
+## Changelog
+
+### v0.1.0
+- Improved TypeScript support with proper type exports
+- Added AlarmService convenience class
+- Comprehensive documentation
+- Fixed module linking issues
+
+### v0.0.1
+- Initial release
+- Cross-platform alarm scheduling
+- Event-driven architecture
+- Permission management