@chipmobilesdk/rn-notification 0.4.1 → 0.6.0

package/src/engine/adapter.ts

@@ -105,6 +105,12 @@ export interface NotificationEngineAdapter {
 
 	/** Full detail, so callers can diff rather than merely count. */
 	getPending(): Promise<readonly PendingEntry[]>;
+	/**
+	 * The identifiers of pending entries, without their payloads (NOT-08).
+	 * Optional: an engine without a cheap way to list them leaves it out and the
+	 * package reads `getPending()` instead.
+	 */
+	pendingIds?(): Promise<readonly string[]>;
 
 	/**
 	 * Applies a channel or category declaration.
@@ -119,6 +125,12 @@ export interface NotificationEngineAdapter {
 	declareGroups(groups: readonly ChannelGroup[]): Promise<void>;
 	/** Channel ids the platform currently holds, which re-declaration cannot reveal. */
 	listDeclaredChannels(): Promise<readonly string[]>;
+	/**
+	 * Runs `work` with the declared channels read once and kept current as `work`
+	 * declares and retires them (NOT-08). Optional; without it each declaration
+	 * reads the channel list itself.
+	 */
+	withChannelSnapshot?<T>(work: () => Promise<T>): Promise<T>;
 
 	getPermission(kind: PermissionKind): Promise<PermissionState>;
 	requestPermission(kind: PermissionKind): Promise<PermissionState>;
@@ -165,7 +177,15 @@ export interface NotificationEngineAdapter {
 	 * a consumer's behalf, which is why it is a documented setup step rather than
 	 * an internal detail — and why its absence is reported rather than guessed at.
 	 */
-	registerBackgroundDeliveryHandler(handler: (event: DeliveryEvent) => Promise<void>): void;
+	registerBackgroundDeliveryHandler(
+		handler: (event: DeliveryEvent) => Promise<void>,
+		/**
+		 * Taps, actions and dismissals that arrive while the app is not in front
+		 * (0.6.0). The engine has one background handler per process, so interactions
+		 * travel through this registration too; without it they were dropped.
+		 */
+		onInteraction?: (event: InteractionEvent) => Promise<void>,
+	): void;
 
 	/** Whether a background delivery handler has been registered in this process. */
 	hasBackgroundDeliveryHandler(): boolean;

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

@@ -0,0 +1,155 @@
+/**
+ * Reading what the engine hands back: pending entries, interactions, deliveries
+ * and authorization values, turned into the package's own shapes.
+ *
+ * Pure functions of the raw value and a clock, so they are testable without an
+ * engine and shared by the foreground, background and cold-start paths.
+ */
+import type { PendingEntry } from '../../contract/notification';
+import type { PermissionState } from '../../contract/permission';
+import type { InteractionEvent } from '../../contract/interaction';
+import { isRepeatStopId } from '../../repeat/marker';
+import type { DeliveryEvent, RepeatStop } from '../adapter';
+import { unpackData } from '../codec';
+import {
+	EVENT_TYPE_ACTION_PRESS,
+	EVENT_TYPE_DELIVERED,
+	EVENT_TYPE_DISMISSED,
+	EVENT_TYPE_PRESS,
+} from './module';
+
+type Raw = Record<string, unknown>;
+
+const bag = (value: unknown): Raw => (value ?? {}) as Raw;
+const dataOf = (notification: Raw): Record<string, string> =>
+	(notification.data ?? {}) as Record<string, string>;
+
+/** Reads a stop marker back out of a pending entry's data bag, if it is one. */
+export function 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 };
+}
+
+export function unpackEntry(raw: Raw, now: () => number): PendingEntry | undefined {
+	const notification = bag(raw.notification);
+	const trigger = bag(raw.trigger);
+	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(dataOf(notification)),
+	};
+}
+
+/** Every stop marker among the engine's pending triggers. */
+export function unpackRepeatStops(raw: readonly Raw[]): RepeatStop[] {
+	const stops: RepeatStop[] = [];
+	for (const entry of raw) {
+		const notification = bag(entry.notification);
+		const id = notification.id;
+		if (typeof id !== 'string') continue;
+		const stop = unpackRepeatStop(id, dataOf(notification));
+		if (stop !== undefined) stops.push(stop);
+	}
+	return stops;
+}
+
+/**
+ * An interaction, or undefined for anything that is not one.
+ *
+ * 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 reporting it as one would cancel a notification the user never touched.
+ */
+export function toInteraction(raw: Raw, now: () => number): InteractionEvent | undefined {
+	const eventType = raw.type;
+	if (
+		eventType !== EVENT_TYPE_DISMISSED &&
+		eventType !== EVENT_TYPE_PRESS &&
+		eventType !== EVENT_TYPE_ACTION_PRESS
+	) {
+		return undefined;
+	}
+
+	const detail = bag(raw.detail);
+	const notification = bag(detail.notification);
+	const pressAction = bag(detail.pressAction);
+	const id = notification.id;
+	if (typeof id !== 'string') return undefined;
+
+	const data = dataOf(notification);
+	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: isNamedAction ? actionId : undefined,
+		inputText: typeof detail.input === 'string' ? detail.input : undefined,
+		// The one decoder for the data bag, so routing is parsed the same way here
+		// and when reading the pending set back (NOT-18).
+		routing: unpackData(data).routing,
+		ownerTag: data.__cms_owner,
+		occurredAt: now(),
+		appState: 'foreground',
+		wasBuffered: false,
+	};
+}
+
+/** A delivery, or undefined for anything that is not one. */
+export function toDelivery(raw: Raw, now: () => number): DeliveryEvent | undefined {
+	if (raw.type !== EVENT_TYPE_DELIVERED) return undefined;
+
+	const notification = bag(bag(raw.detail).notification);
+	const id = notification.id;
+	if (typeof id !== 'string') return undefined;
+
+	return {
+		notificationId: id,
+		occurredAt: now(),
+		repeatStop: unpackRepeatStop(id, dataOf(notification)),
+	};
+}
+
+/**
+ * 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.
+ */
+export 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';
+		default:
+			return 'notAsked';
+	}
+}

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

@@ -0,0 +1,148 @@
+/**
+ * The slice of `react-native-notify-kit` this package uses, and how it is loaded.
+ *
+ * Every import of the engine is confined to this file. 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 { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import { DIAGNOSTIC_CODES, NotificationError } from '../../contract/errors';
+
+/** Both platforms bound background execution for a silent payload or background action. */
+export 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.
+ */
+export const ANDROID_IMPORTANCE = {
+	none: 0,
+	min: 1,
+	low: 2,
+	default: 3,
+	high: 4,
+} as const;
+
+/** `TriggerType.TIMESTAMP`. */
+export const TRIGGER_TYPE_TIMESTAMP = 0;
+
+/** `AlarmType.SET_EXACT_AND_ALLOW_WHILE_IDLE` — exact delivery, survives Doze. */
+export const ALARM_TYPE_EXACT_AND_ALLOW_WHILE_IDLE = 3;
+
+/** `AlarmType.SET_AND_ALLOW_WHILE_IDLE` — the approximate degradation of the above. */
+export 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.
+ */
+export const EVENT_TYPE_DISMISSED = 0;
+export const EVENT_TYPE_PRESS = 1;
+export const EVENT_TYPE_ACTION_PRESS = 2;
+
+/** `EventType.DELIVERED` — an arrival, which is emphatically not an interaction. */
+export 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.
+ */
+export 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.
+ */
+export const MARKER_CHANNEL_ID = 'cms.internal.stop.v1';
+
+/** Minimal shape used from the engine, so its full surface never leaks into typing. */
+export 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>[]>;
+	/** Identifiers only. Optional, because not every release of the binding has it. */
+	getTriggerNotificationIds?(): Promise<string[]>;
+	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.
+ */
+export 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;
+	}
+});
+
+export 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;
+}

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

@@ -0,0 +1,172 @@
+/**
+ * Android: channels, exact alarms, battery optimisation, looping alerts.
+ */
+import type { RestrictionReport } from '../../../contract/permission';
+import { toPermissionState } from '../events';
+import { ANDROID_IMPORTANCE, BACKGROUND_WINDOW_MS, MARKER_CHANNEL_ID, compact } from '../module';
+import type { NotifyKitPlatform, PlatformContext } from './types';
+
+/** Android has no hard pending ceiling like iOS; this bound keeps behavior predictable. */
+const ANDROID_PENDING_BUDGET = 500;
+/** Android 13: the first version with a runtime display permission. */
+const DISPLAY_PERMISSION_API = 33;
+/** Android 12: the first version that gates exact alarms. */
+const EXACT_ALARM_API = 31;
+
+type DeclaredChannel = { id: string; name?: string; description?: string };
+
+export function createAndroidPlatform({ engine, apiLevel }: PlatformContext): NotifyKitPlatform {
+	let markerChannelReady = false;
+	/** The declared channels for the duration of one `withChannelSnapshot` (NOT-08). */
+	let channelSnapshot: DeclaredChannel[] | undefined;
+	const declaredChannels = async (): Promise<DeclaredChannel[]> =>
+		channelSnapshot ?? engine().getChannels();
+	// An unknown API level is treated as current: gating is the safe assumption.
+	const atLeast = (level: number): boolean => (apiLevel() ?? Number.POSITIVE_INFINITY) >= level;
+
+	return {
+		capabilities: () => ({
+			pendingCeiling: ANDROID_PENDING_BUDGET,
+			supportsExactAlarms: true,
+			supportsChannels: true,
+			supportsTextInputActions: true,
+			supportsDoNotDisturbBypass: true,
+			supportsRepeatingAlert: true,
+			backgroundWindowMs: BACKGROUND_WINDOW_MS,
+		}),
+
+		/**
+		 * 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.
+		 */
+		async ensureMarkerChannel() {
+			if (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;
+		},
+
+		async withChannelSnapshot(work) {
+			if (channelSnapshot !== undefined) {
+				return work();
+			}
+			channelSnapshot = await engine().getChannels();
+			try {
+				return await work();
+			} finally {
+				channelSnapshot = undefined;
+			}
+		},
+
+		async declareTone(tone) {
+			const existing = await declaredChannels();
+			const held = existing.find(channel => channel.id === tone.android.channelId);
+			const remember = () => {
+				channelSnapshot = channelSnapshot
+					?.filter(channel => channel.id !== tone.android.channelId)
+					.concat({
+						id: tone.android.channelId,
+						name: tone.android.name,
+						description: tone.android.description,
+					});
+			};
+
+			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);
+				remember();
+				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: the platform declines to overwrite the user's settings.
+			await engine().createChannel(payload);
+			remember();
+			return 'labelsRefreshed';
+		},
+
+		async retireTone(channelId) {
+			const existing = await declaredChannels();
+			if (!existing.some(channel => channel.id === channelId)) return false;
+			await engine().deleteChannel(channelId);
+			channelSnapshot = channelSnapshot?.filter(channel => channel.id !== channelId);
+			return true;
+		},
+
+		async declareGroups(groups) {
+			for (const group of groups) {
+				await engine().createChannelGroup(
+					compact({ id: group.id, name: group.name, description: group.description }),
+				);
+			}
+		},
+
+		async listDeclaredChannels() {
+			return (await declaredChannels()).map(channel => channel.id);
+		},
+
+		permissionFrom(kind, settings) {
+			if (kind === 'display') {
+				// Android below 13 has no runtime display permission at all.
+				return atLeast(DISPLAY_PERMISSION_API)
+					? toPermissionState(settings.authorizationStatus)
+					: 'notRequired';
+			}
+			// Before Android 12 the concept does not apply: "not required", not "denied".
+			if (!atLeast(EXACT_ALARM_API)) {
+				return 'notRequired';
+			}
+			const android = (settings.android ?? {}) as Record<string, unknown>;
+			return android.alarm === 1 ? 'granted' : 'denied';
+		},
+
+		gatesExactAlarms: () => atLeast(EXACT_ALARM_API),
+
+		async restrictions(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(),
+			};
+		},
+	};
+}

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

@@ -0,0 +1,55 @@
+/**
+ * The one place this package asks which platform it is on (IOS-08).
+ *
+ * rn-core's `currentPlatform()` decides the OS; the Android API level is read
+ * from React Native lazily, when asked, so the module loads without it.
+ */
+import { currentPlatform, lazyPeer } from '@chipmobilesdk/rn-core';
+
+import type { PlatformInfo } from '../../../permission/state';
+import type { NotifyKitModule } from '../module';
+import { createAndroidPlatform } from './android';
+import { createIosPlatform } from './ios';
+import type { NotifyKitPlatform } from './types';
+
+export type { NotifyKitPlatform } from './types';
+
+type ReactNativeSlice = { Platform?: { Version?: unknown } };
+
+const reactNative = lazyPeer<ReactNativeSlice>('react-native', () => {
+	try {
+		return require('react-native') as ReactNativeSlice;
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+/** The running OS and, on Android, its API level. */
+export function detectPlatform(): PlatformInfo {
+	const os = currentPlatform();
+	if (os !== 'android') {
+		return { os: os === 'ios' ? 'ios' : 'other' };
+	}
+	const result = reactNative.get();
+	const version = result.ok ? result.module.Platform?.Version : undefined;
+	return { os, apiLevel: typeof version === 'number' ? version : undefined };
+}
+
+/**
+ * The strategy for `platform`, or for the running one. Only Android gets the
+ * Android strategy; anywhere else nothing channel- or alarm-specific is called.
+ */
+export function createNotifyKitPlatform(
+	engine: () => NotifyKitModule,
+	platform?: PlatformInfo,
+): NotifyKitPlatform {
+	const os = platform?.os ?? detectPlatform().os;
+	if (os !== 'android') {
+		return createIosPlatform();
+	}
+	return createAndroidPlatform({
+		engine,
+		// Read when asked rather than once, so it follows the device (and a test).
+		apiLevel: () => (platform ? platform.apiLevel : detectPlatform().apiLevel),
+	});
+}

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

@@ -0,0 +1,54 @@
+/**
+ * iOS: no channels, no exact-alarm gate, a hard ceiling of 64 pending
+ * notifications. Categories are declared per request rather than up front.
+ */
+import { toPermissionState } from '../events';
+import { BACKGROUND_WINDOW_MS } from '../module';
+import type { NotifyKitPlatform } from './types';
+
+/**
+ * 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;
+
+export function createIosPlatform(): NotifyKitPlatform {
+	return {
+		capabilities: () => ({
+			pendingCeiling: IOS_PENDING_CEILING,
+			supportsExactAlarms: false,
+			supportsChannels: false,
+			supportsTextInputActions: true,
+			supportsDoNotDisturbBypass: false,
+			// 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: false,
+			backgroundWindowMs: BACKGROUND_WINDOW_MS,
+		}),
+
+		// No marker is ever placed where alerts cannot repeat.
+		async ensureMarkerChannel() {},
+
+		withChannelSnapshot: work => work(),
+		// Categories are declared at request time rather than up front.
+		declareTone: async () => 'unchanged',
+		retireTone: async () => false,
+		async declareGroups() {},
+		listDeclaredChannels: async () => [],
+
+		permissionFrom: (kind, settings) =>
+			// Exact alarms are an Android concept: "not required", not "denied".
+			kind === 'display' ? toPermissionState(settings.authorizationStatus) : 'notRequired',
+
+		gatesExactAlarms: () => false,
+
+		restrictions: async now => ({
+			batteryOptimization: 'unrestricted',
+			autoStart: 'unrestricted',
+			readAt: now(),
+		}),
+	};
+}

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

@@ -0,0 +1,40 @@
+/**
+ * What differs between Android and iOS in the notify-kit engine (NOT-18, IOS-08).
+ *
+ * The engine picks one implementation when it is created and never branches on
+ * the OS again. Changing iOS behaviour touches `ios.ts` only, and the Android
+ * file that runs in production stays as it is.
+ */
+import type { ChannelGroup, ResolvedTone } from '../../../contract/channel';
+import type {
+	PermissionKind,
+	PermissionState,
+	RestrictionReport,
+} from '../../../contract/permission';
+import type { EngineCapabilities, ToneDeclarationOutcome } from '../../adapter';
+import type { NotifyKitModule } from '../module';
+
+export interface NotifyKitPlatform {
+	capabilities(): EngineCapabilities;
+	/** Creates the channel stop markers are posted on, the first time one is needed. */
+	ensureMarkerChannel(): Promise<void>;
+
+	withChannelSnapshot<T>(work: () => Promise<T>): Promise<T>;
+	declareTone(tone: ResolvedTone): Promise<ToneDeclarationOutcome>;
+	retireTone(channelId: string): Promise<boolean>;
+	declareGroups(groups: readonly ChannelGroup[]): Promise<void>;
+	listDeclaredChannels(): Promise<readonly string[]>;
+
+	/** The state of `kind`, from the engine's settings as just read. */
+	permissionFrom(kind: PermissionKind, settings: Record<string, unknown>): PermissionState;
+	/** Whether exact alarms are a capability the user grants here. */
+	gatesExactAlarms(): boolean;
+	restrictions(now: () => number): Promise<RestrictionReport>;
+}
+
+export interface PlatformContext {
+	/** The engine module, resolved lazily. */
+	readonly engine: () => NotifyKitModule;
+	/** Android API level, read when asked; undefined elsewhere or when unknown. */
+	readonly apiLevel: () => number | undefined;
+}