@chipmobilesdk/rn-notification 0.1.1 → 0.2.0

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

@@ -1,535 +1,761 @@
-/**
- * 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.
- *
- * 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.
- */
-
-import { Platform } from 'react-native';
-import type {
-	NotificationEngineAdapter,
-	EngineCapabilities,
-	EngineScheduleRequest,
-} from './adapter';
-import type { PendingEntry } from '../contract/notification';
-import type { PermissionKind, PermissionState, RestrictionReport } from '../contract/permission';
-import type { ResolvedTone, ChannelGroup } from '../contract/channel';
-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;
-
-/** 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>;
-	getChannels(): Promise<{ id: string }[]>;
-	createChannelGroup(group: Record<string, unknown>): Promise<string>;
-	createTriggerNotification(
-		notification: Record<string, unknown>,
-		trigger: Record<string, unknown>,
-	): Promise<string>;
-	cancelNotification(id: string): Promise<void>;
-	cancelAllNotifications(): Promise<void>;
-	getTriggerNotifications(): Promise<Record<string, unknown>[]>;
-	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>;
-}
-
-function loadEngine(): NotifyKitModule {
-	try {
-		const module = require('react-native-notify-kit') as { default: NotifyKitModule };
-		return module.default;
-	} catch (error) {
-		throw 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: error instanceof Error ? error.name : 'unknown' },
-		);
-	}
-}
-
-/**
- * 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.
- */
-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';
-	}
-}
-
-export interface NotifyKitEngineOptions {
-	/** Injected in tests; production resolves the real module. */
-	readonly module?: NotifyKitModule;
-	readonly now?: () => number;
-}
-
-export function createNotifyKitEngine(
-	options: NotifyKitEngineOptions = {},
-): NotificationEngineAdapter {
-	let cached: NotifyKitModule | undefined = options.module;
-	const engine = (): NotifyKitModule => (cached ??= loadEngine());
-	const now = options.now ?? (() => Date.now());
-
-	/**
-	 * Round-trips our own metadata through the engine's free-form data bag.
-	 *
-	 * Anchoring mode, generation, and series origin have no engine equivalent,
-	 * and `getPending` must return them (FR-010) or a consumer cannot diff
-	 * against intent. Values are stringified because the platform data bag
-	 * carries strings on both platforms.
-	 */
-	const packData = (request: EngineScheduleRequest): Record<string, string> => ({
-		__cms_anchoring: request.request.moment.anchoring ?? 'wallClock',
-		// The IANA zone, not the tone. Storing the wrong value here does not merely
-		// mislabel an entry: the re-anchoring pass feeds it straight to
-		// Intl.DateTimeFormat, which throws a hard Hermes error on an invalid zone.
-		...(request.anchoringGeneration !== undefined
-			? { __cms_generation: request.anchoringGeneration }
-			: {}),
-		__cms_tone: request.request.tone,
-		__cms_approximate: String(request.approximate),
-		__cms_pushCreated: String(request.pushCreated ?? false),
-		...(request.seriesId !== undefined ? { __cms_series: request.seriesId } : {}),
-		...(request.request.ownerTag !== undefined ? { __cms_owner: request.request.ownerTag } : {}),
-		...(request.request.groupTag !== undefined ? { __cms_group: request.request.groupTag } : {}),
-		...(request.request.routing !== undefined
-			? { __cms_routing: JSON.stringify(request.request.routing) }
-			: {}),
-	});
-
-	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;
-
-		let routing: Record<string, unknown> | undefined;
-		if (typeof data.__cms_routing === 'string') {
-			try {
-				routing = JSON.parse(data.__cms_routing) as Record<string, unknown>;
-			} catch {
-				// A payload we cannot parse is reported as absent rather than as a
-				// crash: the notification is still valid, only its routing is lost.
-				routing = undefined;
-			}
-		}
-
-		return {
-			id,
-			resolvedAt: typeof trigger.timestamp === 'number' ? trigger.timestamp : now(),
-			anchoring: data.__cms_anchoring === 'absolute' ? 'absolute' : 'wallClock',
-			anchoringGeneration:
-				data.__cms_anchoring === 'absolute' ? undefined : data.__cms_generation,
-			content: {
-				title: typeof notification.title === 'string' ? notification.title : '',
-				body: typeof notification.body === 'string' ? notification.body : '',
-				subtitle: typeof notification.subtitle === 'string' ? notification.subtitle : undefined,
-			},
-			tone: data.__cms_tone ?? '',
-			routing,
-			ownerTag: data.__cms_owner,
-			groupTag: data.__cms_group,
-			seriesId: data.__cms_series,
-			mayBeDelayed: data.__cms_approximate === 'true',
-			pushCreated: data.__cms_pushCreated === 'true',
-		};
-	};
-
-	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,
-		};
-	};
-
-	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',
-				backgroundWindowMs: BACKGROUND_WINDOW_MS,
-			};
-		},
-
-		async schedule(request: EngineScheduleRequest): Promise<void> {
-			const actions = request.request.actions?.map(action =>
-				compact({
-					title: action.title,
-					pressAction: compact({
-						id: action.id,
-						launchActivity: action.mode === 'foreground' ? 'default' : undefined,
-					}),
-					input: action.input === undefined ? undefined : compact({ placeholder: action.input.placeholder }),
-				}),
-			);
-
-			await engine().createTriggerNotification(
-				compact({
-					id: request.request.id,
-					title: request.request.content.title,
-					body: request.request.content.body,
-					subtitle: request.request.content.subtitle,
-					data: packData(request),
-					android: compact({
-						channelId: request.tone.android.channelId,
-						// Numeric enum, not the string name — see ANDROID_IMPORTANCE.
-						importance: ANDROID_IMPORTANCE[request.tone.android.importance],
-						sound: request.tone.android.sound,
-						groupId: request.tone.android.groupId,
-						actions,
-					}),
-					ios: compact({
-						categoryId: request.tone.ios.categoryId,
-						// This one genuinely is a string union in the engine's types.
-						interruptionLevel: request.tone.ios.interruptionLevel,
-						sound: request.tone.ios.sound,
-					}),
-				}),
-				{
-					type: TRIGGER_TYPE_TIMESTAMP,
-					timestamp: request.resolvedAt,
-					// Approximate mode is a degradation, not a failure: the notification
-					// is still scheduled and the caller is told it may arrive late.
-					alarmManager: {
-						allowWhileIdle: true,
-						type: request.approximate
-							? ALARM_TYPE_INEXACT_AND_ALLOW_WHILE_IDLE
-							: ALARM_TYPE_EXACT_AND_ALLOW_WHILE_IDLE,
-					},
-				},
-			);
-		},
-
-		async cancel(id: string): Promise<void> {
-			await engine().cancelNotification(id);
-		},
-
-		async cancelMany(ids: readonly string[]): Promise<void> {
-			// Sequential rather than parallel: the engine bridges each call to
-			// native, and a burst of concurrent cancels is where duplicate-delivery
-			// races have historically appeared.
-			for (const id of ids) {
-				await engine().cancelNotification(id);
-			}
-		},
-
-		async cancelAll(): Promise<void> {
-			await engine().cancelAllNotifications();
-		},
-
-		async getPending(): Promise<readonly PendingEntry[]> {
-			const raw = await engine().getTriggerNotifications();
-			return raw
-				.map(unpackEntry)
-				.filter((entry): entry is PendingEntry => entry !== undefined)
-				.sort((a, b) => a.resolvedAt - b.resolvedAt);
-		},
-
-		async declareTone(tone: ResolvedTone): Promise<boolean> {
-			if (Platform.OS !== 'android') {
-				// iOS categories are declared at request time rather than up front.
-				return false;
-			}
-
-			const existing = await engine().getChannels();
-			if (existing.some(channel => channel.id === tone.android.channelId)) {
-				// Android silently ignores re-declaration, which is exactly why the
-				// package keeps its own migration ledger rather than asking here.
-				return false;
-			}
-
-			await engine().createChannel(
-				compact({
-					id: tone.android.channelId,
-					name: tone.toneId,
-					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,
-				}),
-			);
-			return true;
-		},
-
-		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';
-			}
-
-			const android = (settings.android ?? {}) as Record<string, unknown>;
-			return android.alarm === 1 ? 'granted' : 'denied';
-		},
-
-		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) {
-				return 'notRequired';
-			}
-			await engine().openAlarmPermissionSettings();
-			return this.getPermission('exactAlarm');
-		},
-
-		async openSettings(kind: PermissionKind): Promise<void> {
-			if (kind === 'exactAlarm') {
-				if (Platform.OS !== 'android' || (Platform.Version as number) < 31) {
-					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();
-				return;
-			}
-			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(),
-			};
-		},
-
-		subscribeToInteractions(handler: (event: InteractionEvent) => void): Unsubscribe {
-			return engine().onForegroundEvent(raw => {
-				const event = toInteraction(raw);
-				if (event !== undefined) handler(event);
-			});
-		},
-
-		async takeInitialInteraction(): Promise<InteractionEvent | undefined> {
-			const raw = await engine().getInitialNotification();
-			if (raw === null) return undefined;
-
-			const event = toInteraction(raw);
-			// 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' };
-		},
-	};
-}
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+import { Platform } from 'react-native';
+import type {
+	NotificationEngineAdapter,
+	DeliveryEvent,
+	EngineCapabilities,
+	EngineScheduleRequest,
+	RepeatStop,
+	ToneDeclarationOutcome,
+} from './adapter';
+import { isRepeatStopId } from '../repeat/marker';
+import type { PendingEntry } from '../contract/notification';
+import type { PermissionKind, PermissionState, RestrictionReport } from '../contract/permission';
+import type { ResolvedTone, ChannelGroup } from '../contract/channel';
+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';
+
+/**
+ * Whether this *process* has a background delivery handler.
+ *
+ * Module scope, not adapter instance state. The engine registers one headless
+ * task per process, so registering through any adapter registers it for all of
+ * them. Keeping the flag per instance made an app that had wired the handler up
+ * correctly report that it had not — which is worse than not reporting at all,
+ * 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>;
+}
+
+function loadEngine(): NotifyKitModule {
+	try {
+		const module = require('react-native-notify-kit') as { default: NotifyKitModule };
+		return module.default;
+	} catch (error) {
+		throw 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: error instanceof Error ? error.name : 'unknown' },
+		);
+	}
+}
+
+/**
+ * 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.
+ */
+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';
+	}
+}
+
+export interface NotifyKitEngineOptions {
+	/** Injected in tests; production resolves the real module. */
+	readonly module?: NotifyKitModule;
+	readonly now?: () => number;
+}
+
+export function createNotifyKitEngine(
+	options: NotifyKitEngineOptions = {},
+): NotificationEngineAdapter {
+	let cached: NotifyKitModule | undefined = options.module;
+	const engine = (): NotifyKitModule => (cached ??= loadEngine());
+	const now = options.now ?? (() => Date.now());
+
+	/**
+	 * Round-trips our own metadata through the engine's free-form data bag.
+	 *
+	 * Anchoring mode, generation, and series origin have no engine equivalent,
+	 * and `getPending` must return them (FR-010) or a consumer cannot diff
+	 * against intent. Values are stringified because the platform data bag
+	 * carries strings on both platforms.
+	 */
+	const packData = (request: EngineScheduleRequest): Record<string, string> => ({
+		__cms_anchoring: request.request.moment.anchoring ?? 'wallClock',
+		// The IANA zone, not the tone. Storing the wrong value here does not merely
+		// mislabel an entry: the re-anchoring pass feeds it straight to
+		// Intl.DateTimeFormat, which throws a hard Hermes error on an invalid zone.
+		...(request.anchoringGeneration !== undefined
+			? { __cms_generation: request.anchoringGeneration }
+			: {}),
+		__cms_tone: request.request.tone,
+		__cms_approximate: String(request.approximate),
+		__cms_pushCreated: String(request.pushCreated ?? false),
+		...(request.seriesId !== undefined ? { __cms_series: request.seriesId } : {}),
+		...(request.request.ownerTag !== undefined ? { __cms_owner: request.request.ownerTag } : {}),
+		...(request.request.groupTag !== undefined ? { __cms_group: request.request.groupTag } : {}),
+		...(request.request.routing !== undefined
+			? { __cms_routing: JSON.stringify(request.request.routing) }
+			: {}),
+		// A stop marker's whole payload. It travels here rather than in `ownerTag`
+		// or `routing` so it can never collide with a value a consumer owns.
+		...(request.repeatStop !== undefined
+			? {
+					__cms_stop_target: request.repeatStop.targetId,
+					__cms_stop_due: String(request.repeatStop.dueAt),
+				}
+			: {}),
+	});
+
+	/** 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;
+
+		let routing: Record<string, unknown> | undefined;
+		if (typeof data.__cms_routing === 'string') {
+			try {
+				routing = JSON.parse(data.__cms_routing) as Record<string, unknown>;
+			} catch {
+				// A payload we cannot parse is reported as absent rather than as a
+				// crash: the notification is still valid, only its routing is lost.
+				routing = undefined;
+			}
+		}
+
+		return {
+			id,
+			resolvedAt: typeof trigger.timestamp === 'number' ? trigger.timestamp : now(),
+			anchoring: data.__cms_anchoring === 'absolute' ? 'absolute' : 'wallClock',
+			anchoringGeneration:
+				data.__cms_anchoring === 'absolute' ? undefined : data.__cms_generation,
+			content: {
+				title: typeof notification.title === 'string' ? notification.title : '',
+				body: typeof notification.body === 'string' ? notification.body : '',
+				subtitle: typeof notification.subtitle === 'string' ? notification.subtitle : undefined,
+			},
+			tone: data.__cms_tone ?? '',
+			routing,
+			ownerTag: data.__cms_owner,
+			groupTag: data.__cms_group,
+			seriesId: data.__cms_series,
+			mayBeDelayed: data.__cms_approximate === 'true',
+			pushCreated: data.__cms_pushCreated === 'true',
+		};
+	};
+
+	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),
+		};
+	};
+
+	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,
+			};
+		},
+
+		async schedule(request: EngineScheduleRequest): Promise<void> {
+			const actions = request.request.actions?.map(action =>
+				compact({
+					title: action.title,
+					pressAction: compact({
+						id: action.id,
+						launchActivity: action.mode === 'foreground' ? 'default' : undefined,
+					}),
+					input: action.input === undefined ? undefined : compact({ placeholder: action.input.placeholder }),
+				}),
+			);
+
+			const isMarker = request.repeatStop !== undefined;
+			if (isMarker) {
+				await ensureMarkerChannel();
+			}
+
+			await engine().createTriggerNotification(
+				compact({
+					id: request.request.id,
+					title: request.request.content.title,
+					body: request.request.content.body,
+					subtitle: request.request.content.subtitle,
+					data: packData(request),
+					android: compact({
+						// A marker gets the quietest channel the package owns rather than
+						// the consumer's tone. It exists to be delivered and removed, and
+						// borrowing the alarm's own channel would make it alarm too.
+						channelId: isMarker ? MARKER_CHANNEL_ID : request.tone.android.channelId,
+						// Numeric enum, not the string name — see ANDROID_IMPORTANCE.
+						importance: isMarker
+							? ANDROID_IMPORTANCE.min
+							: ANDROID_IMPORTANCE[request.tone.android.importance],
+						sound: isMarker ? undefined : request.tone.android.sound,
+						groupId: isMarker ? undefined : request.tone.android.groupId,
+						// Per-notification, not channel configuration. That is what lets
+						// a consumer add a repeating alert to an existing tone without
+						// bumping its version and costing the user their settings.
+						loopSound: !isMarker && request.tone.android.loopSound ? true : undefined,
+						category:
+							!isMarker && request.tone.android.alarmCategory
+								? ANDROID_CATEGORY_ALARM
+								: undefined,
+						actions: isMarker ? undefined : actions,
+					}),
+					ios: compact({
+						categoryId: request.tone.ios.categoryId,
+						// This one genuinely is a string union in the engine's types.
+						interruptionLevel: request.tone.ios.interruptionLevel,
+						sound: request.tone.ios.sound,
+					}),
+				}),
+				{
+					type: TRIGGER_TYPE_TIMESTAMP,
+					timestamp: request.resolvedAt,
+					// Approximate mode is a degradation, not a failure: the notification
+					// is still scheduled and the caller is told it may arrive late.
+					alarmManager: {
+						allowWhileIdle: true,
+						type: request.approximate
+							? ALARM_TYPE_INEXACT_AND_ALLOW_WHILE_IDLE
+							: ALARM_TYPE_EXACT_AND_ALLOW_WHILE_IDLE,
+					},
+				},
+			);
+		},
+
+		async cancel(id: string): Promise<void> {
+			await engine().cancelNotification(id);
+		},
+
+		async cancelMany(ids: readonly string[]): Promise<void> {
+			// Sequential rather than parallel: the engine bridges each call to
+			// native, and a burst of concurrent cancels is where duplicate-delivery
+			// races have historically appeared.
+			for (const id of ids) {
+				await engine().cancelNotification(id);
+			}
+		},
+
+		async cancelAll(): Promise<void> {
+			await engine().cancelAllNotifications();
+		},
+
+		async getPending(): Promise<readonly PendingEntry[]> {
+			const raw = await engine().getTriggerNotifications();
+			return raw
+				.map(unpackEntry)
+				.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
+				// never scheduled and, quite reasonably, cancel it.
+				.filter(entry => !isRepeatStopId(entry.id))
+				.sort((a, b) => a.resolvedAt - b.resolvedAt);
+		},
+
+		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';
+			}
+
+			const android = (settings.android ?? {}) as Record<string, unknown>;
+			return android.alarm === 1 ? 'granted' : 'denied';
+		},
+
+		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) {
+				return 'notRequired';
+			}
+			await engine().openAlarmPermissionSettings();
+			return this.getPermission('exactAlarm');
+		},
+
+		async openSettings(kind: PermissionKind): Promise<void> {
+			if (kind === 'exactAlarm') {
+				if (Platform.OS !== 'android' || (Platform.Version as number) < 31) {
+					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();
+				return;
+			}
+			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(),
+			};
+		},
+
+		subscribeToInteractions(handler: (event: InteractionEvent) => void): Unsubscribe {
+			return engine().onForegroundEvent(raw => {
+				const event = toInteraction(raw);
+				if (event !== undefined) handler(event);
+			});
+		},
+
+		async takeInitialInteraction(): Promise<InteractionEvent | undefined> {
+			const raw = await engine().getInitialNotification();
+			if (raw === null) return undefined;
+
+			const event = toInteraction(raw);
+			// 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' };
+		},
+
+		async silenceDelivered(id: string): Promise<boolean> {
+			const displayed = await engine().getDisplayedNotifications();
+			const match = displayed.find(entry => {
+				const notification = (entry.notification ?? entry) as Record<string, unknown>;
+				return notification.id === id;
+			});
+
+			// Not displayed is the ordinary outcome, not a failure: the user handled
+			// it before the window ran out.
+			if (match === undefined) return false;
+
+			const notification = (match.notification ?? match) as Record<string, unknown>;
+			const android = (notification.android ?? {}) as Record<string, unknown>;
+
+			// Re-posted under the *same* identifier, so it lands on the same tray
+			// slot and replaces in place. Cancelling instead would remove it, and a
+			// notification that vanished is worse than one that never sounded — the
+			// user comes home to a silent phone and no idea what they missed.
+			await engine().displayNotification({
+				...notification,
+				android: {
+					...android,
+					loopSound: false,
+					// Without this the replacement re-alerts once on its way to going
+					// quiet, which is a strange thing to do to someone who has already
+					// heard it for fifteen minutes.
+					onlyAlertOnce: true,
+				},
+			});
+			return true;
+		},
+
+		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;
+		},
+
+		subscribeToDeliveries(handler: (event: DeliveryEvent) => void): Unsubscribe {
+			deliveryListeners.push(handler);
+
+			const unsubscribe = engine().onForegroundEvent(raw => {
+				const event = toDelivery(raw);
+				if (event !== undefined) handler(event);
+			});
+
+			return () => {
+				deliveryListeners = deliveryListeners.filter(l => l !== handler);
+				unsubscribe();
+			};
+		},
+
+		registerBackgroundDeliveryHandler(
+			handler: (event: DeliveryEvent) => Promise<void>,
+		): void {
+			engine().onBackgroundEvent(async raw => {
+				const event = toDelivery(raw);
+				if (event !== undefined) await handler(event);
+			});
+			backgroundHandlerRegistered = true;
+		},
+
+		hasBackgroundDeliveryHandler(): boolean {
+			return backgroundHandlerRegistered;
+		},
+	};
+}