@chipmobilesdk/rn-notification 0.5.0 → 0.7.0

package/src/engine/notify-kit-engine.ts

@@ -1,112 +1,49 @@
 /**
  * The `react-native-notify-kit` engine implementation.
  *
- * Every import of the engine is confined to this file. Nothing above it knows
- * which engine is in use — which is what allowed the original Notifee choice to
- * be swapped for its maintained fork without touching a requirement, a test, or
- * a line of consumer code.
+ * Nothing above this adapter knows which engine is in use — which is what
+ * allowed the original Notifee choice to be swapped for its maintained fork
+ * without touching a requirement, a test, or a line of consumer code.
  *
- * The module is required lazily so the package loads in Jest and in any
- * environment without the native module. An absent engine is reported through
- * the normal diagnostic path rather than crashing at import time.
+ * This file is what both platforms share: scheduling, cancelling, reading the
+ * pending set, and routing events. The engine module and its constants live in
+ * `notify-kit/module.ts`, decoding in `notify-kit/events.ts`, and everything
+ * that differs between Android and iOS in `notify-kit/platform/` — chosen once
+ * when the engine is created (NOT-18, IOS-08).
  */
 
-import { lazyPeer } from '@chipmobilesdk/rn-core';
-
-import { Platform } from 'react-native';
 import type {
 	NotificationEngineAdapter,
 	DeliveryEvent,
-	EngineCapabilities,
 	EngineScheduleRequest,
 	RepeatStop,
-	ToneDeclarationOutcome,
 } from './adapter';
 import { isRepeatStopId } from '../repeat/marker';
-import { packData, unpackData } from './codec';
+import { packData } from './codec';
 import type { PendingEntry } from '../contract/notification';
-import type { PermissionKind, PermissionState, RestrictionReport } from '../contract/permission';
-import type { ResolvedTone, ChannelGroup } from '../contract/channel';
+import type { PermissionKind, PermissionState } from '../contract/permission';
 import type { InteractionEvent, Unsubscribe } from '../contract/interaction';
 import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
-
-/**
- * iOS keeps only the 64 soonest pending notifications and silently discards the
- * rest. This number is the entire reason truncation must be computed and
- * reported by the package rather than left to the platform.
- */
-const IOS_PENDING_CEILING = 64;
-
-/** Android has no comparable hard ceiling; this bound keeps behavior predictable. */
-const ANDROID_PENDING_BUDGET = 500;
-
-/** Both platforms bound background execution for a silent payload or background action. */
-const BACKGROUND_WINDOW_MS = 30_000;
-
-/**
- * The engine's own enum values, mirrored as literals.
- *
- * These are **numeric** enums in the engine's type definitions, and its native
- * validator rejects the string names — `importance: 'default'` fails with
- * "expected a valid Importance". Mirroring them here rather than importing the
- * enums keeps the engine out of the module graph, which is what lets the
- * package load without the native module present.
- *
- * The package's own `ResolvedTone` deliberately stays platform-neutral strings;
- * translating to the engine's representation is this adapter's job and nobody
- * else's.
- */
-const ANDROID_IMPORTANCE = {
-	none: 0,
-	min: 1,
-	low: 2,
-	default: 3,
-	high: 4,
-} as const;
-
-/** `TriggerType.TIMESTAMP`. */
-const TRIGGER_TYPE_TIMESTAMP = 0;
-
-/** `AlarmType.SET_EXACT_AND_ALLOW_WHILE_IDLE` — exact delivery, survives Doze. */
-const ALARM_TYPE_EXACT_AND_ALLOW_WHILE_IDLE = 3;
-
-/** `AlarmType.SET_AND_ALLOW_WHILE_IDLE` — the approximate degradation of the above. */
-const ALARM_TYPE_INEXACT_AND_ALLOW_WHILE_IDLE = 1;
-
-/**
- * `EventType` values that represent a real user interaction.
- *
- * The engine emits far more than interactions on this channel — `DELIVERED`,
- * `TRIGGER_NOTIFICATION_CREATED`, `CHANNEL_BLOCKED` and others all arrive here.
- * Treating anything that is not a dismissal as a press would report a
- * notification *arriving* while the app is open as the user having tapped it,
- * and the interaction path cancels on tap — so the notification would vanish
- * from the tray in front of the user, unread.
- */
-const EVENT_TYPE_DISMISSED = 0;
-const EVENT_TYPE_PRESS = 1;
-const EVENT_TYPE_ACTION_PRESS = 2;
-
-/** `EventType.DELIVERED` — an arrival, which is emphatically not an interaction. */
-const EVENT_TYPE_DELIVERED = 3;
-
-/**
- * `AndroidCategory.ALARM`, the engine's marking for a time-sensitive alert.
- *
- * A per-notification property, not channel configuration — which is why
- * declaring `timeSensitive` on an existing tone never obliges a version bump.
- */
-const ANDROID_CATEGORY_ALARM = 'alarm';
-
-/**
- * The channel stop markers are posted on.
- *
- * A marker exists to be delivered and immediately removed, so it is given the
- * quietest configuration the platform offers: minimum importance, no sound, no
- * vibration. Its version is fixed because nothing about it is consumer-declared,
- * so it never migrates.
- */
-const MARKER_CHANNEL_ID = 'cms.internal.stop.v1';
+import type { PlatformInfo } from '../permission/state';
+import {
+	toDelivery,
+	toInteraction,
+	toPermissionState,
+	unpackEntry,
+	unpackRepeatStops,
+} from './notify-kit/events';
+import {
+	ALARM_TYPE_EXACT_AND_ALLOW_WHILE_IDLE,
+	ALARM_TYPE_INEXACT_AND_ALLOW_WHILE_IDLE,
+	ANDROID_CATEGORY_ALARM,
+	ANDROID_IMPORTANCE,
+	MARKER_CHANNEL_ID,
+	TRIGGER_TYPE_TIMESTAMP,
+	compact,
+	loadEngine,
+	type NotifyKitModule,
+} from './notify-kit/module';
+import { createNotifyKitPlatform } from './notify-kit/platform';
 
 /**
  * Whether this *process* has a background delivery handler.
@@ -118,104 +55,20 @@ const MARKER_CHANNEL_ID = 'cms.internal.stop.v1';
  * because the warning tells the consumer to fix something that is not broken.
  */
 let backgroundHandlerRegistered = false;
-
-/** Minimal shape used from the engine, so its full surface never leaks into typing. */
-interface NotifyKitModule {
-	createChannel(channel: Record<string, unknown>): Promise<string>;
-	deleteChannel(channelId: string): Promise<void>;
-	/**
-	 * Labels come back with the id. That is what makes a label refresh decidable
-	 * against the device rather than against a ledger of our own — and a ledger
-	 * drifts after a restore, a reinstall, or a change the user made themselves.
-	 */
-	getChannels(): Promise<{ id: string; name?: string; description?: string }[]>;
-	createChannelGroup(group: Record<string, unknown>): Promise<string>;
-	createTriggerNotification(
-		notification: Record<string, unknown>,
-		trigger: Record<string, unknown>,
-	): Promise<string>;
-	displayNotification(notification: Record<string, unknown>): Promise<string>;
-	getDisplayedNotifications(): Promise<Record<string, unknown>[]>;
-	cancelNotification(id: string): Promise<void>;
-	cancelAllNotifications(): Promise<void>;
-	getTriggerNotifications(): Promise<Record<string, unknown>[]>;
-	onBackgroundEvent(handler: (event: Record<string, unknown>) => Promise<void>): void;
-	requestPermission(options?: Record<string, unknown>): Promise<Record<string, unknown>>;
-	getNotificationSettings(): Promise<Record<string, unknown>>;
-	openNotificationSettings(): Promise<void>;
-	openAlarmPermissionSettings(): Promise<void>;
-	isBatteryOptimizationEnabled(): Promise<boolean>;
-	onForegroundEvent(handler: (event: Record<string, unknown>) => void): () => void;
-	getInitialNotification(): Promise<Record<string, unknown> | null>;
-}
-
-/**
- * Drops keys whose value is `undefined`.
- *
- * The engine validates its arguments by key presence, not by value: passing
- * `{ groupId: undefined }` fails with "expected a string value", while omitting
- * the key entirely is accepted. JavaScript treats the two as interchangeable
- * almost everywhere, which is exactly why this is easy to get wrong — and why
- * it only surfaces on a real device, where the native validator runs.
- */
-function compact<T extends Record<string, unknown>>(value: T): Partial<T> {
-	const output: Record<string, unknown> = {};
-	for (const [key, entry] of Object.entries(value)) {
-		if (entry !== undefined) output[key] = entry;
-	}
-	return output as Partial<T>;
-}
-
-const notifyKit = lazyPeer('react-native-notify-kit', () => {
-	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
-	try {
-		return require('react-native-notify-kit') as { default: NotifyKitModule };
-	} catch (cause) {
-		throw cause;
-	}
-});
-
-function loadEngine(): NotifyKitModule {
-	return notifyKit.require(
-		(_peer, cause) =>
-			new NotificationError(
-				DIAGNOSTIC_CODES.PUSH_UNAVAILABLE,
-				'react-native-notify-kit is not installed or its native module is not linked. Install it as a peer dependency and rebuild the app.',
-				{ reason: cause instanceof Error ? cause.name : 'unknown' },
-			),
-	).default;
-}
-
 /**
- * Maps engine authorization values onto our six-state model.
- *
- * `notAsked` and `denied` must stay distinguishable — being able to read state
- * without prompting is worthless if the two collapse. `provisional` is its own
- * state on both edges, never folded into granted or denied.
+ * Interaction subscribers alive in this process, across engine instances: the
+ * one registered at module scope in `index.js` and the one the app's runtime
+ * uses are different instances, and a background interaction has to reach the
+ * runtime's subscribers when there are any (NOT-10).
  */
-function toPermissionState(raw: unknown): PermissionState {
-	switch (raw) {
-		case 1:
-		case 'authorized':
-			return 'granted';
-		case 2:
-		case 'provisional':
-			return 'provisional';
-		case 0:
-		case 'denied':
-			return 'denied';
-		case -1:
-		case 'notDetermined':
-			return 'notAsked';
-		default:
-			return 'notAsked';
-	}
-}
+const liveInteractionListeners = new Set<(event: InteractionEvent) => void>();
 
 export interface NotifyKitEngineOptions {
 	/** Injected in tests; production resolves the real module. */
 	readonly module?: NotifyKitModule;
 	readonly now?: () => number;
+	/** Defaults to the running platform. Injected to test one platform's behaviour. */
+	readonly platform?: PlatformInfo;
 }
 
 export function createNotifyKitEngine(
@@ -224,154 +77,29 @@ export function createNotifyKitEngine(
 	let cached: NotifyKitModule | undefined = options.module;
 	const engine = (): NotifyKitModule => (cached ??= loadEngine());
 	const now = options.now ?? (() => Date.now());
+	const platform = createNotifyKitPlatform(engine, options.platform);
 
-	/** Reads a stop marker back out of a pending entry's data bag, if it is one. */
-	const unpackRepeatStop = (id: string, data: Record<string, string>): RepeatStop | undefined => {
-		if (!isRepeatStopId(id)) return undefined;
-		const targetId = data.__cms_stop_target;
-		const dueAt = Number.parseInt(data.__cms_stop_due ?? '', 10);
-		if (typeof targetId !== 'string' || !Number.isFinite(dueAt)) return undefined;
-		return { markerId: id, targetId, dueAt };
-	};
-
-	const unpackEntry = (raw: Record<string, unknown>): PendingEntry | undefined => {
-		const notification = (raw.notification ?? {}) as Record<string, unknown>;
-		const trigger = (raw.trigger ?? {}) as Record<string, unknown>;
-		const data = (notification.data ?? {}) as Record<string, string>;
-		const id = notification.id;
-
-		if (typeof id !== 'string') return undefined;
-
-		return {
-			id,
-			resolvedAt: typeof trigger.timestamp === 'number' ? trigger.timestamp : now(),
-			content: {
-				title: typeof notification.title === 'string' ? notification.title : '',
-				body: typeof notification.body === 'string' ? notification.body : '',
-				subtitle: typeof notification.subtitle === 'string' ? notification.subtitle : undefined,
-			},
-			...unpackData(data),
-		};
-	};
-
-	const toInteraction = (raw: Record<string, unknown>): InteractionEvent | undefined => {
-		const eventType = raw.type;
-
-		// Only a dismissal or a press is an interaction. Everything else the
-		// engine emits on this channel — delivery, trigger creation, channel
-		// blocking — is not, and must not be reported as one.
-		if (
-			eventType !== EVENT_TYPE_DISMISSED &&
-			eventType !== EVENT_TYPE_PRESS &&
-			eventType !== EVENT_TYPE_ACTION_PRESS
-		) {
-			return undefined;
-		}
-
-		const detail = (raw.detail ?? {}) as Record<string, unknown>;
-		const notification = (detail.notification ?? {}) as Record<string, unknown>;
-		const pressAction = (detail.pressAction ?? {}) as Record<string, unknown>;
-		const id = notification.id;
-
-		if (typeof id !== 'string') return undefined;
-
-		const data = (notification.data ?? {}) as Record<string, string>;
-		let routing: Record<string, unknown> | undefined;
-		if (typeof data.__cms_routing === 'string') {
-			try {
-				routing = JSON.parse(data.__cms_routing) as Record<string, unknown>;
-			} catch {
-				routing = undefined;
-			}
-		}
-
-		const actionId = typeof pressAction.id === 'string' ? pressAction.id : undefined;
-		// `default` is the engine's own press-action id for tapping the body, so
-		// it is a tap rather than a named action.
-		const isNamedAction = actionId !== undefined && actionId !== 'default';
-		let kind: InteractionEvent['kind'];
-		if (eventType === EVENT_TYPE_DISMISSED) {
-			kind = 'dismiss';
-		} else if (isNamedAction) {
-			kind = 'action';
-		} else {
-			kind = 'tap';
-		}
-
-		return {
-			kind,
-			notificationId: id,
-			actionId: actionId !== 'default' ? actionId : undefined,
-			inputText: typeof detail.input === 'string' ? detail.input : undefined,
-			routing,
-			ownerTag: data.__cms_owner,
-			occurredAt: now(),
-			appState: 'foreground',
-			wasBuffered: false,
-		};
-	};
-
-	/**
-	 * Creates the marker channel the first time one is needed.
-	 *
-	 * Lazily rather than at initialization, so an app that never declares a
-	 * repeating tone never grows an extra entry in the user's notification
-	 * settings for a feature it does not use.
-	 */
-	let markerChannelReady = false;
-	const ensureMarkerChannel = async (): Promise<void> => {
-		if (Platform.OS !== 'android' || markerChannelReady) return;
-
-		await engine().createChannel({
-			id: MARKER_CHANNEL_ID,
-			name: 'Background maintenance',
-			description:
-				'Used briefly to end a repeating alert. Notifications here are removed immediately.',
-			importance: ANDROID_IMPORTANCE.min,
-			vibration: false,
-			badge: false,
-		});
-		markerChannelReady = true;
-	};
-
-	let deliveryListeners: ((event: DeliveryEvent) => void)[] = [];
-
-	/** A delivery, or undefined for anything that is not one. */
-	const toDelivery = (raw: Record<string, unknown>): DeliveryEvent | undefined => {
-		if (raw.type !== EVENT_TYPE_DELIVERED) return undefined;
-
-		const detail = (raw.detail ?? {}) as Record<string, unknown>;
-		const notification = (detail.notification ?? {}) as Record<string, unknown>;
-		const id = notification.id;
-		if (typeof id !== 'string') return undefined;
-
-		const data = (notification.data ?? {}) as Record<string, string>;
-		return {
-			notificationId: id,
-			occurredAt: now(),
-			repeatStop: unpackRepeatStop(id, data),
-		};
-	};
+	const getPermission = async (kind: PermissionKind): Promise<PermissionState> =>
+		platform.permissionFrom(kind, await engine().getNotificationSettings());
 
 	return {
 		name: 'react-native-notify-kit',
 
-		async getCapabilities(): Promise<EngineCapabilities> {
-			return {
-				pendingCeiling: Platform.OS === 'ios' ? IOS_PENDING_CEILING : ANDROID_PENDING_BUDGET,
-				supportsExactAlarms: Platform.OS === 'android',
-				supportsChannels: Platform.OS === 'android',
-				supportsTextInputActions: true,
-				supportsDoNotDisturbBypass: Platform.OS === 'android',
-				// iOS exposes no looping-sound API. The one alert level that
-				// overrides the mute switch is entitlement-gated by Apple, and does
-				// not loop either — so there is nothing to partially support, and a
-				// partial emulation would be worse than an honest refusal.
-				supportsRepeatingAlert: Platform.OS === 'android',
-				backgroundWindowMs: BACKGROUND_WINDOW_MS,
-			};
+		withChannelSnapshot: work => platform.withChannelSnapshot(work),
+
+		async pendingIds(): Promise<readonly string[]> {
+			const module = engine();
+			if (module.getTriggerNotificationIds) {
+				return module.getTriggerNotificationIds();
+			}
+			return (await module.getTriggerNotifications()).flatMap(raw => {
+				const id = (raw as { notification?: { id?: unknown } }).notification?.id;
+				return typeof id === 'string' ? [id] : [];
+			});
 		},
 
+		getCapabilities: async () => platform.capabilities(),
+
 		async schedule(request: EngineScheduleRequest): Promise<void> {
 			const actions = request.request.actions?.map(action =>
 				compact({
@@ -389,7 +117,7 @@ export function createNotifyKitEngine(
 
 			const isMarker = request.repeatStop !== undefined;
 			if (isMarker) {
-				await ensureMarkerChannel();
+				await platform.ensureMarkerChannel();
 			}
 
 			await engine().createTriggerNotification(
@@ -461,7 +189,7 @@ export function createNotifyKitEngine(
 			const raw = await engine().getTriggerNotifications();
 			return (
 				raw
-					.map(unpackEntry)
+					.map(entry => unpackEntry(entry, now))
 					.filter((entry): entry is PendingEntry => entry !== undefined)
 					// Stop markers are package-owned artifacts. A consumer diffing the
 					// device against its own intent would otherwise see a notification it
@@ -471,120 +199,33 @@ export function createNotifyKitEngine(
 			);
 		},
 
-		async declareTone(tone: ResolvedTone): Promise<ToneDeclarationOutcome> {
-			if (Platform.OS !== 'android') {
-				// iOS categories are declared at request time rather than up front.
-				return 'unchanged';
-			}
-
-			const existing = await engine().getChannels();
-			const held = existing.find(channel => channel.id === tone.android.channelId);
-
-			const payload = compact({
-				id: tone.android.channelId,
-				// The consumer's declared label, not the tone identifier. Passing the
-				// identifier here is what put a technical string in front of users on
-				// the one screen these labels exist to serve.
-				name: tone.android.name,
-				description: tone.android.description,
-				importance: ANDROID_IMPORTANCE[tone.android.importance],
-				sound: tone.android.sound,
-				vibration: tone.android.vibration,
-				badge: tone.android.badge,
-				bypassDnd: tone.android.bypassDnd,
-				groupId: tone.android.groupId,
-			});
-
-			if (held === undefined) {
-				await engine().createChannel(payload);
-				return 'created';
-			}
-
-			if (held.name === tone.android.name && held.description === tone.android.description) {
-				// Nothing to say to the platform. Skipping the call is what keeps an
-				// unchanged configuration genuinely free, which reconciliation
-				// idempotence depends on.
-				return 'unchanged';
-			}
-
-			// Android accepts a re-declaration of an existing channel and applies
-			// only the name and description, ignoring importance, sound, vibration
-			// and DND — because those belong to the user once the channel exists.
-			// That refusal is the guarantee: we do not have to protect the user's
-			// settings here, the platform declines to overwrite them.
-			await engine().createChannel(payload);
-			return 'labelsRefreshed';
-		},
-
-		async retireTone(channelId: string): Promise<boolean> {
-			if (Platform.OS !== 'android') return false;
-
-			const existing = await engine().getChannels();
-			if (!existing.some(channel => channel.id === channelId)) return false;
-
-			await engine().deleteChannel(channelId);
-			return true;
-		},
-
-		async declareGroups(groups: readonly ChannelGroup[]): Promise<void> {
-			if (Platform.OS !== 'android') return;
-
-			for (const group of groups) {
-				await engine().createChannelGroup(
-					compact({ id: group.id, name: group.name, description: group.description }),
-				);
-			}
-		},
-
-		async listDeclaredChannels(): Promise<readonly string[]> {
-			if (Platform.OS !== 'android') return [];
-			const channels = await engine().getChannels();
-			return channels.map(channel => channel.id);
-		},
-
-		async getPermission(kind: PermissionKind): Promise<PermissionState> {
-			const settings = await engine().getNotificationSettings();
-
-			if (kind === 'display') {
-				// Android below 13 has no runtime display permission at all.
-				if (Platform.OS === 'android' && (Platform.Version as number) < 33) {
-					return 'notRequired';
-				}
-				return toPermissionState(settings.authorizationStatus);
-			}
-
-			// Exact alarms exist only on Android 12+; elsewhere the concept does not
-			// apply, which is "not required" rather than "denied".
-			if (Platform.OS !== 'android' || (Platform.Version as number) < 31) {
-				return 'notRequired';
-			}
+		declareTone: tone => platform.declareTone(tone),
+		retireTone: channelId => platform.retireTone(channelId),
+		declareGroups: groups => platform.declareGroups(groups),
+		listDeclaredChannels: () => platform.listDeclaredChannels(),
 
-			const android = (settings.android ?? {}) as Record<string, unknown>;
-			return android.alarm === 1 ? 'granted' : 'denied';
-		},
+		getPermission,
 
 		async requestPermission(kind: PermissionKind): Promise<PermissionState> {
 			if (kind === 'display') {
 				const result = await engine().requestPermission();
 				return toPermissionState(result.authorizationStatus);
 			}
-
 			// Exact-alarm capability is granted only through system settings on the
 			// versions that gate it — there is no in-app dialog to present.
-			if (Platform.OS !== 'android' || (Platform.Version as number) < 31) {
+			if (!platform.gatesExactAlarms()) {
 				return 'notRequired';
 			}
 			await engine().openAlarmPermissionSettings();
-			return this.getPermission('exactAlarm');
+			return getPermission('exactAlarm');
 		},
 
 		async openSettings(kind: PermissionKind): Promise<void> {
 			if (kind === 'exactAlarm') {
-				if (Platform.OS !== 'android' || (Platform.Version as number) < 31) {
+				if (!platform.gatesExactAlarms()) {
 					throw new NotificationError(
 						DIAGNOSTIC_CODES.SETTINGS_UNAVAILABLE,
 						'No exact-alarm settings screen exists on this platform version.',
-						{ platform: Platform.OS, version: Platform.Version },
 					);
 				}
 				await engine().openAlarmPermissionSettings();
@@ -593,45 +234,25 @@ export function createNotifyKitEngine(
 			await engine().openNotificationSettings();
 		},
 
-		async getRestrictions(): Promise<RestrictionReport> {
-			if (Platform.OS !== 'android') {
-				return {
-					batteryOptimization: 'unrestricted',
-					autoStart: 'unrestricted',
-					readAt: now(),
-				};
-			}
-
-			let batteryOptimization: RestrictionReport['batteryOptimization'] = 'unknown';
-			try {
-				batteryOptimization = (await engine().isBatteryOptimizationEnabled())
-					? 'restricted'
-					: 'unrestricted';
-			} catch {
-				batteryOptimization = 'unknown';
-			}
-
-			return {
-				batteryOptimization,
-				// No standard API exposes vendor auto-start policy, and guessing would
-				// be worse than admitting it. `unknown` is a first-class answer here.
-				autoStart: 'unknown',
-				readAt: now(),
-			};
-		},
+		getRestrictions: () => platform.restrictions(now),
 
 		subscribeToInteractions(handler: (event: InteractionEvent) => void): Unsubscribe {
-			return engine().onForegroundEvent(raw => {
-				const event = toInteraction(raw);
+			liveInteractionListeners.add(handler);
+			const unsubscribe = engine().onForegroundEvent(raw => {
+				const event = toInteraction(raw, now);
 				if (event !== undefined) handler(event);
 			});
+			return () => {
+				liveInteractionListeners.delete(handler);
+				unsubscribe();
+			};
 		},
 
 		async takeInitialInteraction(): Promise<InteractionEvent | undefined> {
 			const raw = await engine().getInitialNotification();
 			if (raw === null) return undefined;
 
-			const event = toInteraction(raw);
+			const event = toInteraction(raw, now);
 			// A cold-start tap arrives before any handler exists, so it is reported
 			// with the state that actually produced it.
 			return event === undefined ? undefined : { ...event, appState: 'coldStart' };
@@ -670,40 +291,38 @@ export function createNotifyKitEngine(
 		},
 
 		async listRepeatStops(): Promise<readonly RepeatStop[]> {
-			const raw = await engine().getTriggerNotifications();
-			const stops: RepeatStop[] = [];
-
-			for (const entry of raw) {
-				const notification = (entry.notification ?? {}) as Record<string, unknown>;
-				const id = notification.id;
-				if (typeof id !== 'string') continue;
-
-				const data = (notification.data ?? {}) as Record<string, string>;
-				const stop = unpackRepeatStop(id, data);
-				if (stop !== undefined) stops.push(stop);
-			}
-
-			return stops;
+			return unpackRepeatStops(await engine().getTriggerNotifications());
 		},
 
 		subscribeToDeliveries(handler: (event: DeliveryEvent) => void): Unsubscribe {
-			deliveryListeners.push(handler);
-
-			const unsubscribe = engine().onForegroundEvent(raw => {
-				const event = toDelivery(raw);
+			return engine().onForegroundEvent(raw => {
+				const event = toDelivery(raw, now);
 				if (event !== undefined) handler(event);
 			});
-
-			return () => {
-				deliveryListeners = deliveryListeners.filter(l => l !== handler);
-				unsubscribe();
-			};
 		},
 
-		registerBackgroundDeliveryHandler(handler: (event: DeliveryEvent) => Promise<void>): void {
+		registerBackgroundDeliveryHandler(
+			handler: (event: DeliveryEvent) => Promise<void>,
+			onInteraction?: (event: InteractionEvent) => Promise<void>,
+		): void {
 			engine().onBackgroundEvent(async raw => {
-				const event = toDelivery(raw);
-				if (event !== undefined) await handler(event);
+				const delivery = toDelivery(raw, now);
+				if (delivery !== undefined) {
+					await handler(delivery);
+					return;
+				}
+				// A tap, an action or a dismissal while the app was not in front. Until
+				// 0.6.0 only deliveries were looked at here, so a background action
+				// ("Taken", "Snooze", an inline reply) never reached the app (NOT-10).
+				const interaction = toInteraction(raw, now);
+				if (interaction === undefined) return;
+				const event: InteractionEvent = { ...interaction, appState: 'background' };
+				if (liveInteractionListeners.size > 0) {
+					// The app's runtime is alive: its handlers get it, as in the foreground.
+					for (const listener of [...liveInteractionListeners]) listener(event);
+				} else {
+					await onInteraction?.(event);
+				}
 			});
 			backgroundHandlerRegistered = true;
 		},