@chipmobilesdk/rn-notification 0.5.0 → 0.6.0

package/src/index.ts

@@ -112,6 +112,15 @@ export type {
 /** The default engine. Consumers may substitute their own via the port above. */
 export { createNotifyKitEngine } from './engine/notify-kit-engine';
 
+/**
+ * The whole package, assembled (0.6.0): scheduler, reconciler, recurrence,
+ * permissions, channels, interactions, snapshot and maintenance, wired the way the
+ * package means them to be. Start here; the factories below are for an app that
+ * needs a different wiring, and are also exported from `./advanced`.
+ */
+export { createNotifications } from './notifications';
+export type { Notifications, NotificationsDependencies } from './notifications';
+
 /** Initialization and the assembled runtime. */
 export { initialize } from './initialize';
 export type { RuntimeDependencies, NotificationRuntime } from './initialize';

package/src/notifications.ts

@@ -0,0 +1,195 @@
+/**
+ * One call that assembles the whole package (NOT-07).
+ *
+ * Until 0.5.0 an app wired a dozen factories itself — scheduler, reconciler,
+ * recurrence, permissions, channels, interactions, snapshot, maintenance steps
+ * — repeating the engine, tone resolver, clock and time-zone reader for each,
+ * and usually hard-coding `canScheduleExactly: () => true`. `createNotifications`
+ * does that wiring once, the way the package means it:
+ *
+ * - every part reports through the one redacting diagnostic emitter;
+ * - `canScheduleExactly` follows the exact-alarm permission the package last
+ *   read, instead of a guess;
+ * - automatic maintenance has the standard steps registered (re-anchoring after
+ *   a time-zone change, refreshing permissions, and refreshing recurrence
+ *   windows when the app supplies its rules), so it does something on every
+ *   return to the foreground.
+ *
+ * The individual factories stay exported for an app that needs a different
+ * wiring; they are also available from `@chipmobilesdk/rn-notification/advanced`.
+ */
+import type { Channels } from './channel/migrate';
+import { createToneResolver } from './channel/tone-map';
+import type { DiagnosticCode, InitializeResult, NotificationConfig } from './contract';
+import type { PermissionState } from './contract/permission';
+import type { ReconcileResult } from './contract/reconcile';
+import type { MaintenanceResult } from './contract/reconcile';
+import type { RecurrenceRule } from './contract/recurrence';
+import { createSnapshot, type Snapshot } from './diagnostics/snapshot';
+import type { NotificationEngineAdapter } from './engine/adapter';
+import { createNotifyKitEngine } from './engine/notify-kit-engine';
+import { detectPlatform } from './engine/notify-kit/platform';
+import { initialize, type NotificationRuntime } from './initialize';
+import { createInteractions, type Interactions } from './interaction';
+import { createPermissionRefreshStep } from './maintenance/permission-refresh';
+import { createReAnchorStep } from './maintenance/reanchor';
+import { createWindowRefreshStep } from './maintenance/window-refresh';
+import { createPermissions, type Permissions } from './permission';
+import type { PlatformInfo } from './permission/state';
+import { createReconciler, type Reconciler } from './reconcile';
+import { createRecurrence, type Recurrence } from './recurrence';
+import { createScheduler, type Scheduler } from './schedule';
+import { createPlatformTimeZoneReader, type TimeZoneReader } from './schedule/anchor';
+import { createMmkvStore } from './state/mmkv-store';
+import type { StateStore } from './state/store';
+
+export interface NotificationsDependencies {
+	/** Defaults to the notify-kit engine. Inject a fake in tests. */
+	readonly engine?: NotificationEngineAdapter;
+	/** Defaults to MMKV-backed state. */
+	readonly store?: StateStore;
+	readonly timeZone?: TimeZoneReader;
+	readonly now?: () => number;
+	/** Defaults to the running OS and, on Android, its API level. */
+	readonly platform?: PlatformInfo;
+	/**
+	 * The recurrence rules the app has registered. With it, maintenance refreshes
+	 * their windows on every foreground return; the package never stores a rule
+	 * itself, because a rule carries notification content (FR-096a).
+	 */
+	readonly recurrenceRules?: () => readonly RecurrenceRule[];
+	/** Whether the app holds a push token, for the snapshot. Presence only. */
+	readonly hasPushToken?: () => boolean;
+}
+
+export interface Notifications {
+	readonly scheduler: Scheduler;
+	readonly reconciler: Reconciler;
+	readonly recurrence: Recurrence;
+	readonly permissions: Permissions;
+	readonly channels: Channels;
+	readonly interactions: Interactions;
+	readonly snapshot: Snapshot;
+	/** State, diagnostics and the maintenance controller `initialize` assembled. */
+	readonly runtime: NotificationRuntime;
+	/** What initialization did: tones applied, migrations run, how long it took. */
+	readonly initialization: InitializeResult;
+	/** The time-zone reader every part schedules against. */
+	readonly timeZone: TimeZoneReader;
+	/** Handles a tap or action; a shortcut for `interactions.onInteraction`. */
+	onInteraction: Interactions['onInteraction'];
+	/** Runs maintenance now, whatever the app state. */
+	runMaintenance(): Promise<MaintenanceResult>;
+	/** Whether the exact-alarm capability is granted, as last read. */
+	canScheduleExactly(): boolean;
+	/** Stops the lifecycle observer and every listener. */
+	dispose(): void;
+}
+
+/** Exact scheduling only on a positive answer; unknown degrades to approximate, never fails. */
+function allowsExact(state: PermissionState | undefined): boolean {
+	return state === 'granted' || state === 'notRequired';
+}
+
+export async function createNotifications(
+	config: NotificationConfig,
+	deps: NotificationsDependencies = {},
+): Promise<Notifications> {
+	const engine = deps.engine ?? createNotifyKitEngine();
+	const now = deps.now ?? (() => Date.now());
+	const timeZone = deps.timeZone ?? createPlatformTimeZoneReader();
+	const { runtime, result } = await initialize(config, {
+		engine,
+		store: deps.store ?? createMmkvStore(),
+		now,
+		timeZone,
+	});
+	const { state } = runtime;
+	const emit = (code: string, message: string, context?: Record<string, unknown>) =>
+		runtime.emitter.emit(code as DiagnosticCode, message, context);
+	const resolveTone = createToneResolver(config.tones);
+
+	const permissions = createPermissions({
+		engine,
+		state,
+		platform: deps.platform ?? detectPlatform(),
+		now,
+		emit,
+	});
+	let exactAlarm: PermissionState | undefined;
+	const stopWatchingPermissions = permissions.onPermissionChange(report => {
+		exactAlarm = report.exactAlarm;
+	});
+	// Seeds the answer before anything is scheduled. A failed read leaves it
+	// unknown, which schedules in approximate mode rather than failing.
+	await permissions.getPermissions().catch(() => undefined);
+	const canScheduleExactly = () => allowsExact(exactAlarm);
+
+	const scheduling = { engine, resolveTone, timeZone, now, canScheduleExactly, emit };
+	const scheduler = createScheduler(scheduling);
+	const reconcilerCore = createReconciler(scheduling);
+	let lastReconcile: ReconcileResult | undefined;
+	const reconciler: Reconciler = {
+		...reconcilerCore,
+		async reconcile(input) {
+			lastReconcile = await reconcilerCore.reconcile(input);
+			return lastReconcile;
+		},
+	};
+	const recurrence = createRecurrence({ ...scheduling, state, lookahead: runtime.lookahead });
+	const interactions = createInteractions({ engine, state, now, emit });
+
+	let lastExplicit: MaintenanceResult | undefined;
+	const snapshot = createSnapshot({
+		engine,
+		state,
+		now,
+		permissions: () => permissions.getPermissions(),
+		restrictions: () => permissions.getBackgroundRestrictions(),
+		appliedTones: () => runtime.channels.appliedVersions(),
+		lastReconcile: () => lastReconcile,
+		lastMaintenance: () => runtime.lastAutomaticMaintenance() ?? lastExplicit,
+		hasPushToken: deps.hasPushToken ?? (() => false),
+	});
+
+	const unregister = [
+		runtime.registry.register(
+			createReAnchorStep({ engine, timeZone, resolveTone, canScheduleExactly, emit }),
+		),
+		runtime.registry.register(createPermissionRefreshStep({ permissions })),
+		...(deps.recurrenceRules
+			? [
+					runtime.registry.register(
+						createWindowRefreshStep({ recurrence, registeredRules: deps.recurrenceRules, emit }),
+					),
+				]
+			: []),
+	];
+
+	return {
+		scheduler,
+		reconciler,
+		recurrence,
+		permissions,
+		channels: runtime.channels,
+		interactions,
+		snapshot,
+		runtime,
+		initialization: result,
+		timeZone,
+		onInteraction: handler => interactions.onInteraction(handler),
+		async runMaintenance() {
+			lastExplicit = await runtime.maintenance.runExplicit();
+			return lastExplicit;
+		},
+		canScheduleExactly,
+		dispose() {
+			stopWatchingPermissions();
+			for (const remove of unregister) {
+				remove();
+			}
+			interactions.dispose();
+			runtime.dispose();
+		},
+	};
+}

package/src/permission/index.ts

@@ -17,7 +17,15 @@ import type { NotificationEngineAdapter } from '../engine/adapter';
 import type { StateManager } from '../state/record';
 import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
 import { capabilityFor, normalizeState, type PlatformInfo } from './state';
-import { hasRequested, recordRequested } from '../state/permission-history';
+import { onForeground as onAppForeground } from '@chipmobilesdk/rn-core';
+
+import {
+	clearDenials,
+	denialCount,
+	hasRequested,
+	recordDenial,
+	recordRequested,
+} from '../state/permission-history';
 
 export interface PermissionDependencies {
 	readonly engine: NotificationEngineAdapter;
@@ -25,6 +33,19 @@ export interface PermissionDependencies {
 	readonly platform: PlatformInfo;
 	readonly now: () => number;
 	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+	/**
+	 * Calls back when the app returns from the background. Defaults to rn-core's
+	 * shared lifecycle; injected in tests.
+	 */
+	readonly onForeground?: (listener: () => void) => () => void;
+}
+
+/**
+ * Refusals after which the system stops showing its prompt (NOT-12). Android 13+
+ * allows a second ask; iOS allows one.
+ */
+function denialLimit(platform: PlatformInfo): number {
+	return platform.os === 'android' ? 2 : 1;
 }
 
 export type PermissionChangeHandler = (report: PermissionReport) => void;
@@ -34,6 +55,24 @@ export function createPermissions(deps: PermissionDependencies) {
 	let listeners: PermissionChangeHandler[] = [];
 	let lastReport: PermissionReport | undefined;
 
+	/**
+	 * The engine's answer plus what only the package remembers. The platform
+	 * reports a refusal as `denied` however often it happened; once the user has
+	 * refused as many times as the system will ask, another request shows nothing,
+	 * so the state is `permanentlyDenied` and the app should offer Settings.
+	 */
+	const derive = (kind: PermissionKind, raw: PermissionState): PermissionState => {
+		const state = normalizeState(kind, raw, deps.platform);
+		if (kind !== 'display') return state;
+		if (state === 'granted' || state === 'provisional') {
+			clearDenials(deps.state, kind);
+			return state;
+		}
+		return state === 'denied' && denialCount(deps.state, kind) >= denialLimit(deps.platform)
+			? 'permanentlyDenied'
+			: state;
+	};
+
 	const read = async (): Promise<PermissionReport> => {
 		// Never prompts. This is what lets a consumer decide the moment to ask.
 		const [display, exactAlarm] = await Promise.all([
@@ -42,12 +81,28 @@ export function createPermissions(deps: PermissionDependencies) {
 		]);
 
 		return {
-			display: normalizeState('display', display, deps.platform),
-			exactAlarm: normalizeState('exactAlarm', exactAlarm, deps.platform),
+			display: derive('display', display),
+			exactAlarm: derive('exactAlarm', exactAlarm),
 			readAt: deps.now(),
 		};
 	};
 
+	const whenForeground = deps.onForeground ?? (listener => onAppForeground(listener));
+	let stopAwaitingSettings: (() => void) | undefined;
+	/**
+	 * Exact alarms are granted on a system settings screen, so the answer read
+	 * straight after opening it is always the old one. The real answer is read
+	 * when the user comes back, and listeners hear it then (NOT-12).
+	 */
+	const rereadOnReturn = (): void => {
+		stopAwaitingSettings?.();
+		stopAwaitingSettings = whenForeground(() => {
+			stopAwaitingSettings?.();
+			stopAwaitingSettings = undefined;
+			read().then(notifyIfChanged, () => undefined);
+		});
+	};
+
 	const notifyIfChanged = (report: PermissionReport): boolean => {
 		const changed =
 			lastReport === undefined ||
@@ -79,7 +134,13 @@ export function createPermissions(deps: PermissionDependencies) {
 		recordRequested(deps.state, kind, deps.now(), ownerTag);
 
 		const raw = await deps.engine.requestPermission(kind);
-		const result = normalizeState(kind, raw, deps.platform);
+		if (kind === 'display' && normalizeState(kind, raw, deps.platform) === 'denied') {
+			recordDenial(deps.state, kind, deps.now());
+		}
+		const result = derive(kind, raw);
+		if (capability.settingsOnly && result !== 'granted') {
+			rereadOnReturn();
+		}
 
 		if (result === 'denied' || result === 'permanentlyDenied') {
 			emit(

package/src/push/fcm-provider.ts

@@ -88,12 +88,22 @@ export function createFcmProvider(options: FcmProviderOptions = {}): PushProvide
 			// the optional peer. Either way the local path is unaffected.
 			if (instance === undefined) return 'unavailable';
 
+			// Asked without registering: fetching a token here would create an FCM
+			// registration (and an APNs one on iOS) just to answer a yes-or-no
+			// question, before the app asked for permission (NOT-24).
 			try {
-				await instance.getToken();
-				return 'available';
+				if (instance.isDeviceRegisteredForRemoteMessages === true) {
+					return 'available';
+				}
+				if (instance.hasPermission !== undefined) {
+					// Messaging is present; whether it may deliver is the permission's
+					// question, and that is answered without registering anything.
+					await instance.hasPermission();
+					return 'available';
+				}
+				return 'unknown';
 			} catch {
-				// Registration can fail for reasons the SDK does not distinguish, so
-				// `unknown` is reported rather than a guess at which one.
+				// The SDK does not say why, so `unknown` rather than a guess.
 				return 'unknown';
 			}
 		},

package/src/push/gate.ts

@@ -39,7 +39,8 @@ export function createPushGate(deps: PushGateDependencies) {
 	const emit = deps.emit ?? (() => {});
 	let handlers: PushHandler[] = [];
 	let subscription: Unsubscribe | undefined;
-	let tokenSubscription: Unsubscribe | undefined;
+	/** Every token subscription, so a second one does not leak the first (NOT-24). */
+	const tokenSubscriptions = new Set<Unsubscribe>();
 	let deliveryChain: Promise<void> = Promise.resolve();
 
 	const dispatch = (envelope: PushEnvelope): void => {
@@ -126,8 +127,13 @@ export function createPushGate(deps: PushGateDependencies) {
 		},
 
 		onTokenChange(handler: (token: string) => void): Unsubscribe {
-			tokenSubscription = deps.provider.onTokenChange(handler);
-			return tokenSubscription;
+			const unsubscribe = deps.provider.onTokenChange(handler);
+			tokenSubscriptions.add(unsubscribe);
+			return () => {
+				if (tokenSubscriptions.delete(unsubscribe)) {
+					unsubscribe();
+				}
+			};
 		},
 
 		async invalidateToken(): Promise<boolean> {
@@ -157,6 +163,20 @@ export function createPushGate(deps: PushGateDependencies) {
 			};
 		},
 
+		/**
+		 * Processes a payload delivered while the app was in the background, from
+		 * the module-scope handler `setBackgroundMessageHandler` requires (NOT-24).
+		 *
+		 * The same normalization and the same persisted deduplication as a
+		 * foreground payload, so a redelivery after the process restarted is
+		 * suppressed rather than handled twice. Resolves once every handler has run.
+		 */
+		async handleBackground(raw: unknown): Promise<PushEnvelope | undefined> {
+			const envelope = receive(raw);
+			await deliveryChain;
+			return envelope;
+		},
+
 		/** Processes the payload that launched the app, if any. */
 		async collectInitial(): Promise<PushEnvelope | undefined> {
 			const raw = await deps.provider.takeInitialMessage();
@@ -179,9 +199,11 @@ export function createPushGate(deps: PushGateDependencies) {
 
 		dispose(): void {
 			subscription?.();
-			tokenSubscription?.();
 			subscription = undefined;
-			tokenSubscription = undefined;
+			for (const unsubscribe of tokenSubscriptions) {
+				unsubscribe();
+			}
+			tokenSubscriptions.clear();
 			handlers = [];
 		},
 	};

package/src/reconcile/diff.ts

@@ -31,42 +31,53 @@ export interface DiffResult {
 	readonly unchanged: readonly string[];
 }
 
-/** Stable serialization of the fields that make a delivered notification different. */
-function fingerprint(request: NotificationRequest, resolvedAt: number): string {
+/** The fields that make one delivered notification different from another. */
+interface FingerprintFields {
+	readonly resolvedAt: number;
+	readonly anchoring: string;
+	readonly content: NotificationRequest['content'];
+	readonly tone: string;
+	readonly ownerTag?: string;
+	readonly groupTag?: string;
+	readonly routing?: NotificationRequest['routing'];
+	readonly actions?: NotificationRequest['actions'];
+}
+
+/**
+ * Stable serialization of those fields. One function for what the app wants and
+ * what the device holds, so the two cannot drift into comparing different
+ * things (NOT-19).
+ */
+function fingerprintFields(fields: FingerprintFields): string {
 	return JSON.stringify([
-		resolvedAt,
-		request.moment.anchoring ?? 'wallClock',
-		request.content.title,
-		request.content.body,
-		request.content.subtitle ?? null,
-		request.tone,
-		request.ownerTag ?? null,
-		request.groupTag ?? null,
+		fields.resolvedAt,
+		fields.anchoring,
+		fields.content.title,
+		fields.content.body,
+		fields.content.subtitle ?? null,
+		fields.tone,
+		fields.ownerTag ?? null,
+		fields.groupTag ?? null,
 		// Key order is not stable across constructions, so sort before comparing —
 		// otherwise two structurally identical payloads could compare unequal and
 		// the second pass would rewrite every entry carrying routing data.
-		request.routing === undefined ? null : stableStringify(request.routing),
-		request.actions === undefined
+		fields.routing === undefined ? null : stableStringify(fields.routing),
+		fields.actions === undefined
 			? null
-			: request.actions.map(a => [a.id, a.title, a.mode, a.input?.placeholder ?? null]),
+			: fields.actions.map(a => [a.id, a.title, a.mode, a.input?.placeholder ?? null]),
 	]);
 }
 
+function fingerprint(request: NotificationRequest, resolvedAt: number): string {
+	return fingerprintFields({
+		...request,
+		resolvedAt,
+		anchoring: request.moment.anchoring ?? 'wallClock',
+	});
+}
+
 function entryFingerprint(entry: PendingEntry): string {
-	return JSON.stringify([
-		entry.resolvedAt,
-		entry.anchoring,
-		entry.content.title,
-		entry.content.body,
-		entry.content.subtitle ?? null,
-		entry.tone,
-		entry.ownerTag ?? null,
-		entry.groupTag ?? null,
-		entry.routing === undefined ? null : stableStringify(entry.routing),
-		entry.actions === undefined
-			? null
-			: entry.actions.map(a => [a.id, a.title, a.mode, a.input?.placeholder ?? null]),
-	]);
+	return fingerprintFields(entry);
 }
 
 /** Key-order-independent JSON, so structurally equal payloads compare equal. */

package/src/reconcile/index.ts

@@ -59,7 +59,13 @@ export function createReconciler(deps: ReconcileDependencies) {
 		const startedAt = deps.now();
 		const zone = deps.timeZone();
 
-		const device = (await deps.engine.getPending()).filter(entry => inDomain(entry, input));
+		const everything = await deps.engine.getPending();
+		const device = everything.filter(entry => inDomain(entry, input));
+		// The ceiling is the platform's, shared with every other domain, every
+		// recurring series and every directly scheduled notification. Budgeting a
+		// domain against the whole of it let two domains and a series overflow iOS's
+		// 64 together while each reported "nothing truncated" (NOT-11).
+		const heldElsewhere = everything.length - device.length;
 		const existingIds = new Set(device.map(entry => entry.id));
 
 		// Duplicates first: a repeated identifier is refused before anything else
@@ -94,10 +100,13 @@ export function createReconciler(deps: ReconcileDependencies) {
 		// notifications can actually use is smaller than the platform's own.
 		// Hiding that would let the package quietly reduce how many notifications
 		// fit and report a full set as registered when it was not.
+		// One pass: the outstanding stop markers are read once for the capacity and
+		// every operation below, not once per operation (NOT-08).
+		const pass = writer.pass();
 		const { kept, report: truncation } = truncateToCeiling(
 			valid,
 			resolvedAt,
-			await writer.capacity(),
+			Math.max(0, (await pass.capacity()) - heldElsewhere),
 		);
 
 		if (truncation !== undefined) {
@@ -128,14 +137,14 @@ export function createReconciler(deps: ReconcileDependencies) {
 			operations,
 			async operation => {
 				if (operation.kind === 'cancel') {
-					await writer.cancel(operation.id);
+					await pass.cancel(operation.id);
 					cancelled.push(operation.id);
 					return;
 				}
 
 				const request = operation.request!;
 				const tone = deps.resolveTone(request.tone)!;
-				await writer.write({
+				await pass.write({
 					request,
 					resolvedAt: operation.resolvedAt!,
 					tone,

package/src/recurrence/index.ts

@@ -248,7 +248,8 @@ export function createRecurrence(deps: RecurrenceDependencies) {
 			const ids = pending.filter(entry => belongsTo(entry, seriesId)).map(entry => entry.id);
 
 			await deps.engine.cancelMany(ids);
-			for (const id of ids) await writer.releaseStop(id);
+			const pass = writer.pass();
+			for (const id of ids) await pass.releaseStop(id);
 			removeSeries(deps.state, seriesId);
 			return ids;
 		},

package/src/repeat/expiry.ts

@@ -10,6 +10,7 @@
  */
 
 import type { DeliveryEvent, NotificationEngineAdapter } from '../engine/adapter';
+import { createStopPlacement } from './place';
 
 export interface RepeatExpiryDependencies {
 	readonly engine: NotificationEngineAdapter;
@@ -43,11 +44,6 @@ export function createRepeatExpiryHandler(deps: RepeatExpiryDependencies): Repea
 			await deps.engine.cancel(stop.markerId);
 		},
 
-		async release(targetId: string): Promise<void> {
-			const outstanding = await deps.engine.listRepeatStops();
-			const marker = outstanding.find(stop => stop.targetId === targetId);
-			if (marker === undefined) return;
-			await deps.engine.cancel(marker.markerId);
-		},
+		release: targetId => createStopPlacement(deps.engine).release(targetId),
 	};
 }

package/src/repeat/index.ts

@@ -8,7 +8,11 @@
  * An app that declares no repeating tone needs none of this.
  */
 
+import type { InteractionEvent } from '../contract/interaction';
 import type { NotificationEngineAdapter } from '../engine/adapter';
+import { buffer } from '../state/interaction-buffer';
+import { StateManager } from '../state/record';
+import type { StateStore } from '../state/store';
 import { createRepeatExpiryHandler } from './expiry';
 
 export { createRepeatExpiryHandler } from './expiry';
@@ -18,6 +22,22 @@ export { REPEAT_STOP_PREFIX, isRepeatStopId, markerIdFor, repeatStopFor } from '
 export interface BackgroundHandlerRegistration {
 	readonly engine: NotificationEngineAdapter;
 	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+	/**
+	 * Handles a tap, action or dismissal that arrives while no part of the app is
+	 * listening — typically a background action in a process the system started
+	 * just for it (0.6.0). Runs inside the platform's background window, so keep
+	 * it short. When the app's own `onInteraction` handlers are alive they get the
+	 * event instead, with `appState: 'background'`.
+	 */
+	readonly onInteraction?: (event: InteractionEvent) => Promise<void> | void;
+	/**
+	 * Where to keep an interaction nobody handled, so `onInteraction` delivers it
+	 * when the app next starts: the same store the runtime uses
+	 * (`createMmkvStore()`). Used when `onInteraction` is absent or throws.
+	 */
+	readonly store?: StateStore;
+	/** The clock for what is kept. Defaults to the system clock; injected in tests. */
+	readonly now?: () => number;
 }
 
 /**
@@ -37,7 +57,31 @@ export function registerBackgroundNotificationHandler(
 ): void {
 	const handler = createRepeatExpiryHandler(registration);
 
-	registration.engine.registerBackgroundDeliveryHandler(event => handler.handle(event));
+	const keep = (event: InteractionEvent): void => {
+		if (registration.store === undefined) return;
+		// A manager of its own: this runs in a process with no runtime, and the
+		// runtime created later loads what is written here.
+		buffer(
+			new StateManager({ store: registration.store, now: registration.now ?? (() => Date.now()) }),
+			event,
+		);
+	};
+
+	registration.engine.registerBackgroundDeliveryHandler(
+		event => handler.handle(event),
+		async event => {
+			if (registration.onInteraction === undefined) {
+				keep(event);
+				return;
+			}
+			try {
+				await registration.onInteraction(event);
+			} catch {
+				// The app's handler failed; the interaction is kept rather than lost.
+				keep(event);
+			}
+		},
+	);
 
 	// Both paths, not just the background one. The engine routes a delivery to
 	// the foreground listener while the app is alive and to the headless task

package/src/repeat/marker.ts

@@ -14,6 +14,7 @@
  * consumer identifier ends up colliding with an internal one.
  */
 
+import { fnv1a, hex8 } from '../contract/hash';
 import type { RepeatStop } from '../engine/adapter';
 
 /**
@@ -25,28 +26,6 @@ import type { RepeatStop } from '../engine/adapter';
  */
 export const REPEAT_STOP_PREFIX = 'cms.stop:';
 
-/**
- * FNV-1a, 32-bit. Deterministic, dependency-free, and stable across releases.
- *
- * Bitwise operators are the algorithm, not a micro-optimisation: arithmetic
- * equivalents would not wrap to 32 bits, and a marker id that changed between
- * releases would orphan every marker already scheduled on a device.
- */
-/* eslint-disable no-bitwise */
-function fnv1a(value: string, basis: number): number {
-	let hash = basis;
-	for (let index = 0; index < value.length; index += 1) {
-		hash ^= value.codePointAt(index) ?? 0;
-		hash = Math.imul(hash, 0x01000193) >>> 0;
-	}
-	return hash >>> 0;
-}
-/* eslint-enable no-bitwise */
-
-function hex8(value: number): string {
-	return value.toString(16).padStart(8, '0');
-}
-
 /**
  * The marker identifier for a target notification.
  *