react-native-alarmageddon 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 react-native-alarmageddon
+
+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

@@ -0,0 +1,292 @@
+# react-native-alarmageddon
+
+🔔 **Native exact alarm scheduling for React Native with sound, snooze, and boot persistence.**
+
+A powerful React Native library for scheduling alarms that:
+- Use Android's `AlarmManager.setAlarmClock()` for exact timing
+- Play alarm sounds at full volume
+- Show full-screen notifications that wake the device
+- Support snooze functionality
+- Persist across device reboots
+- Work even when the app is killed
+
+## Features
+
+- ✅ **Exact Alarms**: Uses `setAlarmClock()` for precise alarm timing
+- ✅ **Full-Screen Intent**: Wakes device and shows alarm UI
+- ✅ **Sound & Vibration**: Plays alarm sound at max volume with vibration
+- ✅ **Snooze Support**: Built-in snooze functionality
+- ✅ **Boot Persistence**: Alarms automatically reschedule after reboot
+- ✅ **Background Support**: Works when app is killed
+- ✅ **Auto-Stop**: Configurable auto-stop timer
+- ✅ **Event Emitter**: Listen for alarm state changes in JavaScript
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Android  | ✅ Full support |
+| iOS      | ⚠️ Stub only (uses NOT_IMPLEMENTED errors) |
+
+> **Note**: iOS requires a different approach using `UNUserNotificationCenter`. Full iOS support is planned for a future release.
+
+## Installation
+
+```bash
+npm install react-native-alarmageddon
+# or
+yarn add react-native-alarmageddon
+```
+
+### Android Setup
+
+The library uses autolinking, so no manual linking is required for React Native 0.60+.
+
+#### Permissions
+
+The required permissions are automatically merged into your `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
+<uses-permission android:name="android.permission.USE_EXACT_ALARM" />
+<uses-permission android:name="android.permission.WAKE_LOCK" />
+<uses-permission android:name="android.permission.VIBRATE" />
+<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+```
+
+#### Android 12+ (API 31+) Requirements
+
+Starting with Android 12, apps must request the `SCHEDULE_EXACT_ALARM` permission at runtime. This library handles this automatically, but you should call `ensurePermissions()` before scheduling alarms.
+
+## Usage
+
+### Basic Example
+
+```typescript
+import RNAlarmModule from 'react-native-alarmageddon';
+
+// Request permissions first
+async function setupAlarms() {
+  const granted = await RNAlarmModule.ensurePermissions();
+  if (!granted) {
+    console.warn('Alarm permissions not granted');
+    return;
+  }
+
+  // Schedule an alarm for 5 minutes from now
+  const triggerTime = new Date(Date.now() + 5 * 60 * 1000);
+  
+  await RNAlarmModule.scheduleAlarm({
+    id: 'wake-up-alarm',
+    datetimeISO: triggerTime.toISOString(),
+    title: 'Wake Up!',
+    body: 'Time to start your day',
+    snoozeMinutes: 10,
+    autoStopSeconds: 120,
+    vibrate: true,
+  });
+}
+```
+
+### Listening for Alarm Events
+
+```typescript
+import { useEffect, useState } from 'react';
+import RNAlarmModule from 'react-native-alarmageddon';
+
+function AlarmScreen() {
+  const [activeAlarmId, setActiveAlarmId] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Check if an alarm is already playing when app opens
+    RNAlarmModule.getCurrentAlarmPlaying().then((info) => {
+      if (info) {
+        setActiveAlarmId(info.activeAlarmId);
+      }
+    });
+
+    // Subscribe to alarm state changes
+    const unsubscribe = RNAlarmModule.onAlarmStateChange((alarmId) => {
+      setActiveAlarmId(alarmId);
+    });
+
+    return unsubscribe;
+  }, []);
+
+  const handleStop = async () => {
+    if (activeAlarmId) {
+      await RNAlarmModule.stopCurrentAlarm(activeAlarmId);
+    }
+  };
+
+  const handleSnooze = async () => {
+    if (activeAlarmId) {
+      await RNAlarmModule.snoozeCurrentAlarm(activeAlarmId, 10);
+    }
+  };
+
+  if (!activeAlarmId) {
+    return null;
+  }
+
+  return (
+    <View>
+      <Text>Alarm is ringing!</Text>
+      <Button title="Stop" onPress={handleStop} />
+      <Button title="Snooze 10 min" onPress={handleSnooze} />
+    </View>
+  );
+}
+```
+
+### Managing Alarms
+
+```typescript
+import RNAlarmModule from 'react-native-alarmageddon';
+
+// List all scheduled alarms
+const alarms = await RNAlarmModule.listAlarms();
+console.log('Scheduled alarms:', alarms);
+
+// Cancel a specific alarm
+await RNAlarmModule.cancelAlarm('wake-up-alarm');
+
+// Snooze an alarm (reschedules it)
+await RNAlarmModule.snoozeAlarm('wake-up-alarm', 5);
+```
+
+## API Reference
+
+### Types
+
+```typescript
+type AlarmParams = {
+  id: string;              // Unique identifier
+  datetimeISO: string;     // ISO 8601 datetime string
+  title?: string;          // Notification title (default: "Alarm")
+  body?: string;           // Notification body (default: "")
+  soundUri?: string;       // Custom sound URI (uses system default if omitted)
+  vibrate?: boolean;       // Enable vibration (default: true)
+  snoozeMinutes?: number;  // Snooze duration (default: 5)
+  autoStopSeconds?: number; // Auto-stop after N seconds (default: 60)
+};
+
+type StoredAlarm = {
+  id: string;
+  datetimeISO: string;
+  title: string;
+  body: string;
+  vibrate: boolean;
+  snoozeMinutes: number;
+  autoStopSeconds: number;
+};
+
+type PermissionResult = {
+  granted: boolean;
+  exactAlarmGranted?: boolean;
+};
+
+type ActiveAlarmInfo = {
+  activeAlarmId: string;
+} | null;
+```
+
+### Methods
+
+#### Permissions
+
+| Method | Description |
+|--------|-------------|
+| `ensurePermissions()` | Request all required permissions. Returns `true` if granted. |
+| `requestNotificationPermission()` | Request notification permission (Android 13+). |
+| `requestExactAlarmPermission()` | Request exact alarm permission (Android 12+). Opens settings if needed. |
+| `checkExactAlarmPermission()` | Check if exact alarm permission is granted. |
+| `openExactAlarmSettings()` | Open system settings for exact alarm permission. |
+
+#### Alarm Management
+
+| Method | Description |
+|--------|-------------|
+| `scheduleAlarm(params)` | Schedule a new alarm. |
+| `cancelAlarm(id)` | Cancel a scheduled alarm. |
+| `listAlarms()` | Get all scheduled alarms. |
+| `snoozeAlarm(id, minutes)` | Reschedule an alarm for N minutes from now. |
+
+#### Active Alarm Control
+
+| Method | Description |
+|--------|-------------|
+| `stopCurrentAlarm(id)` | Stop the currently playing alarm. |
+| `snoozeCurrentAlarm(id, minutes)` | Stop and snooze the current alarm. |
+| `getCurrentAlarmPlaying()` | Get info about the currently playing alarm. |
+
+#### Events
+
+| Method | Description |
+|--------|-------------|
+| `onAlarmStateChange(callback)` | Subscribe to alarm state changes. Returns unsubscribe function. |
+| `addEventListener(event, callback)` | Add event listener. Returns subscription for removal. |
+
+## How It Works
+
+### Android Architecture
+
+1. **AlarmModule**: React Native bridge that schedules alarms via `AlarmManager`
+2. **AlarmReceiver**: `BroadcastReceiver` that triggers when alarm fires
+3. **AlarmService**: Foreground service that plays sound and shows notification
+4. **AlarmActivity**: Transparent activity that wakes the screen
+5. **BootReceiver**: Reschedules alarms after device reboot or time changes
+
+### Alarm Scheduling
+
+The library uses `AlarmManager.setAlarmClock()` which:
+- Is the most reliable way to schedule exact alarms on Android
+- Shows an alarm icon in the status bar
+- Can wake the device from Doze mode
+- Survives app kills
+
+### Boot Persistence
+
+The `BootReceiver` listens for:
+- `BOOT_COMPLETED`: Device finished booting
+- `LOCKED_BOOT_COMPLETED`: Direct boot completed
+- `TIME_SET`: User changed system time
+- `TIMEZONE_CHANGED`: Timezone changed
+- `MY_PACKAGE_REPLACED`: App was updated
+
+When any of these events occur, all future alarms are rescheduled.
+
+## Troubleshooting
+
+### Alarm not firing
+
+1. **Check permissions**: Ensure `SCHEDULE_EXACT_ALARM` is granted on Android 12+
+2. **Battery optimization**: Exclude your app from battery optimization
+3. **Verify time**: Ensure the scheduled time is in the future
+
+### Sound not playing
+
+1. **Check volume**: Ensure alarm volume is not muted
+2. **Custom sound**: Verify the sound URI is valid and accessible
+
+### Alarm not showing on lock screen
+
+1. **Notification permission**: Ensure `POST_NOTIFICATIONS` is granted on Android 13+
+2. **Lock screen settings**: Check device notification settings for lock screen visibility
+
+### After reboot, alarms are lost
+
+This shouldn't happen with the library, but verify:
+1. The `BootReceiver` is properly declared in the manifest
+2. Your app hasn't been force-stopped
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

package/android/build.gradle

@@ -0,0 +1,69 @@
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+buildscript {
+    def kotlin_version = safeExtGet('kotlinVersion', '1.9.22')
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace 'com.rnalarmmodule'
+    
+    compileSdkVersion safeExtGet('compileSdkVersion', 34)
+
+    defaultConfig {
+        minSdkVersion safeExtGet('minSdkVersion', 21)
+        targetSdkVersion safeExtGet('targetSdkVersion', 34)
+    }
+
+    sourceSets {
+        main {
+            java.srcDirs = ['src/main/java']
+            res.srcDirs = ['src/main/res']
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+
+    lintOptions {
+        abortOnError false
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    def kotlin_version = safeExtGet('kotlinVersion', '1.9.22')
+    
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    
+    // React Native dependency - works with both old and new architecture
+    if (rootProject.hasProperty('reactNativeVersion')) {
+        implementation "com.facebook.react:react-android:${rootProject.reactNativeVersion}"
+    } else {
+        implementation 'com.facebook.react:react-android:+'
+    }
+    
+    implementation 'androidx.core:core-ktx:1.12.0'
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+}

package/android/gradle.properties

@@ -0,0 +1,13 @@
+# React Native Alarmageddon Android Build Configuration
+
+# Version of Kotlin to use
+AlarmModule_kotlinVersion=1.9.22
+
+# Android SDK versions
+AlarmModule_compileSdkVersion=34
+AlarmModule_minSdkVersion=21
+AlarmModule_targetSdkVersion=34
+
+# Build configuration
+android.useAndroidX=true
+android.enableJetifier=true

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,55 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.rnalarmmodule">
+
+    <!-- Permissions that will merge with host app -->
+    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
+    <uses-permission android:name="android.permission.USE_EXACT_ALARM" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.VIBRATE" />
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+
+    <application>
+        <receiver 
+            android:name=".AlarmReceiver" 
+            android:exported="false">
+            <intent-filter>
+                <action android:name="com.rnalarmmodule.ALARM_TRIGGER" />
+                <action android:name="com.rnalarmmodule.ALARM_STOP" />
+                <action android:name="com.rnalarmmodule.ALARM_SNOOZE" />
+            </intent-filter>
+        </receiver>
+
+        <receiver 
+            android:name=".BootReceiver" 
+            android:exported="true"
+            android:directBootAware="true">
+            <intent-filter>
+                <action android:name="android.intent.action.BOOT_COMPLETED" />
+                <action android:name="android.intent.action.LOCKED_BOOT_COMPLETED" />
+                <action android:name="android.intent.action.TIME_SET" />
+                <action android:name="android.intent.action.TIMEZONE_CHANGED" />
+                <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
+            </intent-filter>
+        </receiver>
+
+        <activity
+            android:name=".AlarmActivity"
+            android:exported="false"
+            android:showOnLockScreen="true"
+            android:turnScreenOn="true"
+            android:showWhenLocked="true"
+            android:theme="@android:style/Theme.NoDisplay"
+            android:noHistory="true"
+            android:excludeFromRecents="true"
+            android:launchMode="singleInstance"
+            android:taskAffinity="" />
+
+        <service
+            android:name=".AlarmService"
+            android:exported="false"
+            android:foregroundServiceType="mediaPlayback" />
+    </application>
+</manifest>

package/android/src/main/java/com/rnalarmmodule/AlarmActivity.kt

@@ -0,0 +1,79 @@
+package com.rnalarmmodule
+
+import android.app.Activity
+import android.app.KeyguardManager
+import android.content.Context
+import android.os.Build
+import android.os.Bundle
+import android.util.Log
+import android.view.WindowManager
+
+class AlarmActivity : Activity() {
+
+    companion object {
+        private const val TAG = "AlarmActivity"
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        
+        Log.d(TAG, "onCreate - waking up screen for alarm")
+
+        // Enable showing on lock screen and turning screen on
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O_MR1) {
+            setShowWhenLocked(true)
+            setTurnScreenOn(true)
+            
+            val keyguardManager = getSystemService(Context.KEYGUARD_SERVICE) as KeyguardManager
+            keyguardManager.requestDismissKeyguard(this, null)
+        } else {
+            @Suppress("DEPRECATION")
+            window.addFlags(
+                WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED or
+                WindowManager.LayoutParams.FLAG_DISMISS_KEYGUARD or
+                WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON or
+                WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON
+            )
+        }
+
+        // Keep screen on while alarm is active
+        window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+
+        // Get alarm details from intent
+        val alarmId = intent.getStringExtra("alarmId")
+        val title = intent.getStringExtra("title") ?: "Alarm"
+        val body = intent.getStringExtra("body") ?: ""
+        val snoozeMinutes = intent.getIntExtra("snoozeMinutes", 5)
+
+        Log.d(TAG, "Alarm triggered: id=$alarmId, title=$title")
+
+        // Try to launch the main app
+        launchMainApp(alarmId)
+    }
+
+    private fun launchMainApp(alarmId: String?) {
+        try {
+            val launchIntent = packageManager.getLaunchIntentForPackage(packageName)
+            if (launchIntent != null) {
+                launchIntent.addFlags(
+                    android.content.Intent.FLAG_ACTIVITY_NEW_TASK or
+                    android.content.Intent.FLAG_ACTIVITY_CLEAR_TOP or
+                    android.content.Intent.FLAG_ACTIVITY_SINGLE_TOP
+                )
+                launchIntent.putExtra("alarmId", alarmId)
+                launchIntent.putExtra("fromAlarm", true)
+                startActivity(launchIntent)
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to launch main app: ${e.message}", e)
+        }
+
+        // Finish this transparent activity
+        finish()
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        Log.d(TAG, "onDestroy")
+    }
+}