npm package: @scalejet/capacitor-alarm-notification
Description: A Capacitor plugin for scheduling full-screen alarm notifications.
Author: Karthik S
Latest version: 0.0.10

# @scalejet/capacitor-alarm-notification

A Capacitor plugin for scheduling full-screen alarm notifications that work even when the app is closed.

## Installation

```bash
npm install @scalejet/capacitor-alarm-notification
```

## Usage

```typescript
import { AlarmNotification } from '@scalejet/capacitor-alarm-notification';

// Check and request permissions first
const checkPermission = async () => {
  const { hasPermission } = await AlarmNotification.checkPermission();
  if (!hasPermission) {
    await AlarmNotification.requestPermission();
  }
};

// Set an alarm
const setAlarm = async () => {
  try {
    const result = await AlarmNotification.setAlarm({
      delay: 5000, // delay in milliseconds
      title: "Wake Up!",
      message: "Time to get up!",
      id: "my-alarm", // optional
      openButtonText: "Open App" // optional
    });
    console.log('Alarm set:', result);
  } catch (error) {
    console.error('Error setting alarm:', error);
  }
};

// Cancel the alarm
const cancelAlarm = async () => {
  try {
    const result = await AlarmNotification.cancelAlarm();
    console.log('Alarm cancelled:', result);
  } catch (error) {
    console.error('Error cancelling alarm:', error);
  }
};

// Listen for alarm actions
AlarmNotification.addListener('alarmAction', (data) => {
  console.log('Alarm action:', data.action);
  if (data.action === 'snooze') {
    console.log('Snooze for', data.snoozeMinutes, 'minutes');
  }
});
```

## Features

- ✅ Exact alarms that work when app is closed
- ✅ Full-screen alarm UI with modern design
- ✅ Alarm sound and vibration
- ✅ Wake up device from sleep
- ✅ Show on lock screen
- ✅ Handle device reboots
- ✅ Battery optimization handling
- ✅ Permission management
- ✅ Cross-platform support (Android & iOS)
- ✅ Snooze functionality
- ✅ Customizable alarm interface
- ✅ Action buttons (Open, Dismiss, Snooze)
- ✅ Event listeners for alarm actions

## Platform Support

### Android
- **Full native alarm implementation** with exact timing
- **Foreground service** for reliable alarm delivery
- **Boot completion handling** to restore alarms after device restart
- **Battery optimization bypass** for critical alarms
- **Custom full-screen alarm activity** with snooze functionality
- **Wake lock support** to ensure device wakes up

### iOS
- **Native iOS notification system** using UNUserNotificationCenter
- **Action buttons** (Open, Dismiss, Snooze) for user interaction
- **Background app refresh** support for reliable delivery
- **Notification categories** for organized alarm management
- **Sound and vibration** support
- **Permission handling** for notifications

### Web
- **Local storage-based** alarm simulation for development
- **Notification API** integration when available
- **Custom event system** for alarm triggers
- **Fallback implementation** for testing

## Android Permissions

The plugin requires the following permissions:

- `SCHEDULE_EXACT_ALARM` (Android 12+)
- `USE_EXACT_ALARM` (Android 12+)
- `FOREGROUND_SERVICE`
- `FOREGROUND_SERVICE_SPECIAL_USE`
- `POST_NOTIFICATIONS` (Android 13+)
- `WAKE_LOCK`
- `RECEIVE_BOOT_COMPLETED`
- `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`

## iOS Permissions

For iOS, the plugin requires:
- **Notification permissions** (alert, sound, badge)
- **Background app refresh** capability (optional, for better reliability)

## API Reference

### Methods

#### `setAlarm(options)`
Schedule a new alarm notification.

**Parameters:**
- `delay` (number): Delay in milliseconds before alarm triggers
- `title` (string): Alarm title
- `message` (string): Alarm message
- `id` (string, optional): Unique identifier for the alarm
- `openButtonText` (string, optional): Custom text for the open button

#### `cancelAlarm()`
Cancel all scheduled alarms.

#### `checkPermission()`
Check if notification permissions are granted.

#### `requestPermission()`
Request notification permissions from the user.

#### `checkIntentExtras()`
Check if the app was opened from an alarm notification.

#### `checkAlarmOpened()`
Check if any alarms were opened by the user.

#### `checkAlarmDismissed()`
Check if any alarms were dismissed by the user.

#### `addListener(eventName, listener)`
Add an event listener for alarm actions.

#### `removeAllListeners(eventName)`
Remove all event listeners for a specific event.

### Events

#### `alarmAction`
Fired when user interacts with alarm actions (snooze, dismiss, open).

**Event data:**
- `action` (string): Action type ('snooze', 'dismiss', 'open')
- `notificationId` (string): Alarm identifier
- `title` (string): Alarm title
- `message` (string): Alarm message
- `snoozeMinutes` (number): Snooze duration (for snooze action)

## Development

### Building the Plugin

```bash
npm run build
```

### Running Tests

```bash
npm run verify
```

### Code Quality

```bash
npm run lint
npm run fmt
```

## License

MIT

## Author

Karthik S

## Repository

- GitHub: https://github.com/srikarthiks/capacitoralarm
- Issues: https://github.com/srikarthiks/capacitoralarm/issues

---

## 🚀 Key Features

- 🔔 Schedule full-screen alarms with exact timing
- ⏰ Wake the device and show alert, even when locked
- ✅ `cancelAlarm()` and snooze support
- 📱 Opens the main activity when alarm triggers
- 🍎 Cross-platform: Android & iOS support
- 🎨 Modern, customizable alarm interface
- 📦 Ready to publish on npm
- 🔧 Comprehensive development tools
- 🎯 Action buttons for user interaction
- 📡 Event-driven architecture

---

## 📦 Quick Start

```bash
npm install @scalejet/capacitor-alarm-notification
npx cap sync