warm_alarm_platform_interface 0.1.1

A common platform interface for the warm_alarm plugin.

warm_alarm_platform_interface

The common platform interface for the warm_alarm plugin. This package defines the abstract contract that all platform implementations must satisfy, and houses all hand-written public model classes shared across platforms.

---

What's in this package

WarmAlarmPlatform — abstract contract

The abstract class that every platform implementation extends. Platform plugins call WarmAlarmPlatform.instance = MyPlatformImpl() in their registerWith() to install themselves. The default instance is MethodChannelWarmAlarm, which returns empty / unknown values for all methods (it never throws) and serves as a no-op fallback for apps that have not registered a real platform implementation.

Contract methods:

Method	Returns	Description
init()	Future<void>	Rehydrate native alarm state after a process restart
getCapabilities()	WarmAlarmCapabilities	Per-feature support status for this platform
getPermissionState()	WarmAlarmPermissionState	Current notification and exact-alarm permission grants
getReadiness()	WarmAlarmReadiness	Aggregated readiness level with reason codes
requestNotificationPermission()	WarmAlarmRemediationResult	Request notification authorization and return current state
openReadinessSettings(reason)	WarmAlarmRemediationResult	Open supported native settings and return current state
scheduleAlarm(schedule)	WarmAlarmScheduleResult	Schedule an alarm and return its assigned ID
cancelAlarm(id)	Future<void>	Cancel a specific alarm by ID
cancelAllAlarms()	Future<void>	Cancel all scheduled alarms
getScheduledAlarms()	List<WarmAlarmSnapshot>	Enumerate all currently scheduled alarms
isRinging({id})	Future<bool>	Whether an alarm (or any alarm) is ringing
setKillWarning(title,body)	Future<void>	Post a persistent kill-warning notification
clearKillWarning()	Future<void>	Dismiss the kill-warning notification
events	Stream<WarmAlarmEvent>	Broadcast stream of alarm lifecycle events

The two remediation methods carry an unsupported default, so a platform package built against an earlier version of this contract keeps working and simply reports that it cannot remediate. The endorsed Android, iOS, and macOS implementations ship in their own packages once they depend on this version. openReadinessSettings() hands the user off to a separate screen and returns as soon as the platform accepts the request, so its snapshot describes the state before the user acted on it — call getReadiness() again after the app resumes. requestNotificationPermission() awaits the system dialog, so its snapshot is the state after the user answered.

Public models

All public-facing model classes live in lib/src/models/ and are stable across platform implementations. Pigeon-generated wire DTOs (in lib/src/messages.g.dart of each platform package) are never exposed here.

Model	Purpose
WarmAlarmSchedule	Full alarm configuration passed to scheduleAlarm()
WarmAlarmAudio	Audio source, looping, volume, fade-in curve, and vibration settings
WarmAlarmNotification	Notification title, body, action button labels, and Android-specific icon/color
WarmAlarmSnooze	Snooze duration
WarmAlarmRecurrence	Weekly recurrence via a list of ISO weekday numbers (weekdays, 1 = Monday … 7 = Sunday)
WarmAlarmWakeCheck	Wake-check configuration: check delay, optional retrigger delay, and max retrigger count
WarmAlarmSnapshot	Full read-back of a scheduled alarm (mirrors WarmAlarmSchedule fields)
WarmAlarmCapabilities	Per-feature WarmAlarmSupportStatus: notification & exact scheduling, background audio, full-screen, wake-check, Live Activity
WarmAlarmPermissionState	Runtime permission grant flags
WarmAlarmReadiness	Aggregated readiness level plus a list of actionable WarmAlarmReadinessReason codes
WarmAlarmRemediationResult	Action status plus permission and readiness state when the action returns
WarmAlarmScheduleResult	Schedule outcome: alarmId, readiness snapshot, optional WarmAlarmWarning
WarmAlarmEvent	Sealed class hierarchy covering every alarm lifecycle transition
WarmAlarmVolumeFadeStep	A single (time, volume) breakpoint in a custom fade curve

---

Implementing a new platform

1. Add warm_alarm_platform_interface as a dependency.
2. Extend WarmAlarmPlatform (do not implement it — extending ensures forward compatibility when new methods are added with default implementations).
3. Call WarmAlarmPlatform.instance = YourImpl() in your static void registerWith() method.

import 'package:warm_alarm_platform_interface/warm_alarm_platform_interface.dart';

class WarmAlarmMyPlatform extends WarmAlarmPlatform {
  static void registerWith() {
    WarmAlarmPlatform.instance = WarmAlarmMyPlatform();
  }

  @override
  Future<WarmAlarmCapabilities> getCapabilities() async { /* ... */ }

  // ... implement remaining methods
}

All native ↔ Dart communication should be code-generated by Pigeon. Keep generated wire types in lib/src/ (private) and map them to the public models from this package at the Dart layer.

---

License

BSD-3-Clause — Copyright (c) 2026, Dongmin Yu. See LICENSE for details.