@chipmobilesdk/rn-notification 0.5.0 → 0.6.0

package/src/channel/migrate.ts

@@ -74,192 +74,202 @@ export function createChannels(deps: ChannelDependencies) {
 	// has to follow, or it would retire with the old channel.
 	const writer = createScheduleWriter(deps.engine);
 
-	return {
-		/**
-		 * Applies a tone configuration, migrating any tone whose version moved.
-		 *
-		 * Applying an unchanged configuration performs no work at all: no channel
-		 * is recreated and no migration is triggered.
-		 */
-		async apply(
-			tones: readonly ToneDeclaration[],
-			groups: readonly ChannelGroup[] = [],
-		): Promise<ChannelApplyResult> {
-			// Validation completes before the first engine call, so a rejected
-			// declaration leaves the device exactly as it was — the same order the
-			// scheduler has always used.
-			validateToneDeclarations(tones);
+	const applyTones = async (
+		tones: readonly ToneDeclaration[],
+		groups: readonly ChannelGroup[],
+	): Promise<ChannelApplyResult> => {
+		// Validation completes before the first engine call, so a rejected
+		// declaration leaves the device exactly as it was — the same order the
+		// scheduler has always used.
+		validateToneDeclarations(tones);
 
-			const now = deps.now();
+		const now = deps.now();
 
-			const created: string[] = [];
-			const migrated: { toneId: string; from: number; to: number }[] = [];
-			const labelsRefreshed: string[] = [];
-			const retired: string[] = [];
-			const reHomed: string[] = [];
-			const cancelled: string[] = [];
-			const bypassUnavailable: string[] = [];
-			const repeatUnavailable: string[] = [];
-			const unchanged: string[] = [];
+		const created: string[] = [];
+		const migrated: { toneId: string; from: number; to: number }[] = [];
+		const labelsRefreshed: string[] = [];
+		const retired: string[] = [];
+		const reHomed: string[] = [];
+		const cancelled: string[] = [];
+		const bypassUnavailable: string[] = [];
+		const repeatUnavailable: string[] = [];
+		const unchanged: string[] = [];
 
-			if (groups.length > 0) {
-				await deps.engine.declareGroups(groups);
-			}
+		if (groups.length > 0) {
+			await deps.engine.declareGroups(groups);
+		}
+
+		const capabilities = await deps.engine.getCapabilities();
 
-			const capabilities = await deps.engine.getCapabilities();
+		for (const tone of tones) {
+			const previous = ledgerFor(deps.state, tone.id);
+			const resolved = resolveTone(tone);
+			const fingerprint = toneLabelFingerprint(tone);
 
-			for (const tone of tones) {
-				const previous = ledgerFor(deps.state, tone.id);
-				const resolved = resolveTone(tone);
-				const fingerprint = toneLabelFingerprint(tone);
+			// Refusals are reported for every tone that asked, whether or not
+			// anything else about it moved. A platform declining an attribute
+			// says nothing about whether the channel is new.
+			if (tone.bypassDoNotDisturb === true && !capabilities.supportsDoNotDisturbBypass) {
+				// Reported honestly rather than silently dropped — a consumer that
+				// asked for a bypass deserves to know the platform refused.
+				bypassUnavailable.push(tone.id);
+				emit(
+					DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,
+					`Tone "${tone.id}" requested a Do Not Disturb bypass, which this platform does not permit.`,
+					{ toneId: tone.id },
+				);
+			}
 
-				// Refusals are reported for every tone that asked, whether or not
-				// anything else about it moved. A platform declining an attribute
-				// says nothing about whether the channel is new.
-				if (tone.bypassDoNotDisturb === true && !capabilities.supportsDoNotDisturbBypass) {
-					// Reported honestly rather than silently dropped — a consumer that
-					// asked for a bypass deserves to know the platform refused.
-					bypassUnavailable.push(tone.id);
+			if (tone.repeatAlert !== undefined) {
+				if (!capabilities.supportsRepeatingAlert) {
+					repeatUnavailable.push(tone.id);
 					emit(
-						DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,
-						`Tone "${tone.id}" requested a Do Not Disturb bypass, which this platform does not permit.`,
+						DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE,
+						`Tone "${tone.id}" requested a repeating alert, which this platform does not offer. The notification still delivers and still sounds once.`,
+						{ toneId: tone.id },
+					);
+				} else if (!deps.engine.hasBackgroundDeliveryHandler()) {
+					// Said out loud at declaration time, because the alternative is a
+					// user meeting it as a phone that will not stop ringing.
+					emit(
+						DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING,
+						`Tone "${tone.id}" declares a repeating alert, but no background notification handler is registered. Its alert will not stop on its own while the app is not running. Call registerBackgroundNotificationHandler at module scope in index.js.`,
 						{ toneId: tone.id },
 					);
 				}
+			}
 
-				if (tone.repeatAlert !== undefined) {
-					if (!capabilities.supportsRepeatingAlert) {
-						repeatUnavailable.push(tone.id);
-						emit(
-							DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE,
-							`Tone "${tone.id}" requested a repeating alert, which this platform does not offer. The notification still delivers and still sounds once.`,
-							{ toneId: tone.id },
-						);
-					} else if (!deps.engine.hasBackgroundDeliveryHandler()) {
-						// Said out loud at declaration time, because the alternative is a
-						// user meeting it as a phone that will not stop ringing.
-						emit(
-							DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING,
-							`Tone "${tone.id}" declares a repeating alert, but no background notification handler is registered. Its alert will not stop on its own while the app is not running. Call registerBackgroundNotificationHandler at module scope in index.js.`,
-							{ toneId: tone.id },
-						);
-					}
-				}
-
-				const versionMoved = previous !== undefined && previous.appliedVersion !== tone.version;
-
-				if (previous !== undefined && !versionMoved) {
-					// The version is the same, so nothing the platform freezes has
-					// changed. Only the labels can still be stale — and correcting
-					// those must cost the user nothing, so the platform is touched
-					// only when the fingerprint actually moved.
-					if (previous.labelFingerprint === fingerprint) {
-						unchanged.push(tone.id);
-						continue;
-					}
-
-					const outcome = await deps.engine.declareTone(resolved);
-					if (outcome === 'created') {
-						// The channel was gone — deleted by the user, or lost with the
-						// app's data — so this is a first declaration rather than a
-						// refresh, whatever our ledger believed.
-						created.push(resolved.android.channelId);
-					} else if (outcome === 'labelsRefreshed') {
-						labelsRefreshed.push(tone.id);
-						emit(
-							DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED,
-							`Tone "${tone.id}" had its name and description updated in place. No channel was recreated, so every setting the user adjusted on it is untouched.`,
-							{ toneId: tone.id },
-						);
-					} else {
-						unchanged.push(tone.id);
-					}
+			const versionMoved = previous !== undefined && previous.appliedVersion !== tone.version;
 
-					recordApplied(deps.state, tone, now, undefined, fingerprint);
+			if (previous !== undefined && !versionMoved) {
+				// The version is the same, so nothing the platform freezes has
+				// changed. Only the labels can still be stale — and correcting
+				// those must cost the user nothing, so the platform is touched
+				// only when the fingerprint actually moved.
+				if (previous.labelFingerprint === fingerprint) {
+					unchanged.push(tone.id);
 					continue;
 				}
 
 				const outcome = await deps.engine.declareTone(resolved);
 				if (outcome === 'created') {
+					// The channel was gone — deleted by the user, or lost with the
+					// app's data — so this is a first declaration rather than a
+					// refresh, whatever our ledger believed.
 					created.push(resolved.android.channelId);
+				} else if (outcome === 'labelsRefreshed') {
+					labelsRefreshed.push(tone.id);
+					emit(
+						DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED,
+						`Tone "${tone.id}" had its name and description updated in place. No channel was recreated, so every setting the user adjusted on it is untouched.`,
+						{ toneId: tone.id },
+					);
+				} else {
+					unchanged.push(tone.id);
 				}
 
-				if (previous === undefined) {
-					recordApplied(deps.state, tone, now, undefined, fingerprint);
-					continue;
-				}
+				recordApplied(deps.state, tone, now, undefined, fingerprint);
+				continue;
+			}
 
-				// A version moved, so this is a migration rather than a first
-				// declaration. Re-home before retiring: the reverse order would leave
-				// live notifications attached to a channel that no longer exists.
-				emit(
-					DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
-					`Tone "${tone.id}" moved from version ${previous.appliedVersion} to ${tone.version}. Android channels are immutable, so a new channel was created and the old one is being retired.`,
-					{ toneId: tone.id, from: previous.appliedVersion, to: tone.version },
-				);
+			const outcome = await deps.engine.declareTone(resolved);
+			if (outcome === 'created') {
+				created.push(resolved.android.channelId);
+			}
 
-				const pending = await deps.engine.getPending();
-				const affected = pending.filter(entry => entry.tone === tone.id);
+			if (previous === undefined) {
+				recordApplied(deps.state, tone, now, undefined, fingerprint);
+				continue;
+			}
 
-				for (const entry of affected) {
-					await writer.write({
-						request: {
-							id: entry.id,
-							content: entry.content,
-							tone: entry.tone,
-							moment: { at: entry.resolvedAt, anchoring: entry.anchoring },
-							routing: entry.routing,
-							actions: entry.actions,
-							ownerTag: entry.ownerTag,
-							groupTag: entry.groupTag,
-						},
-						resolvedAt: entry.resolvedAt,
-						tone: resolved,
-						// Re-homing changes the channel, not the anchoring — preserve it.
-						anchoringGeneration: entry.anchoringGeneration,
-						approximate: entry.mayBeDelayed,
-						seriesId: entry.seriesId,
-						pushCreated: entry.pushCreated,
-					});
-					reHomed.push(entry.id);
-				}
+			// A version moved, so this is a migration rather than a first
+			// declaration. Re-home before retiring: the reverse order would leave
+			// live notifications attached to a channel that no longer exists.
+			emit(
+				DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
+				`Tone "${tone.id}" moved from version ${previous.appliedVersion} to ${tone.version}. Android channels are immutable, so a new channel was created and the old one is being retired.`,
+				{ toneId: tone.id, from: previous.appliedVersion, to: tone.version },
+			);
 
-				const didRetire = await deps.engine.retireTone(previous.channelId);
-				if (didRetire) {
-					retired.push(previous.channelId);
-				}
+			const pending = await deps.engine.getPending();
+			const affected = pending.filter(entry => entry.tone === tone.id);
 
-				// A version move outranks a label change: the new channel simply
-				// carries the new labels, and reporting it as a refresh would hide a
-				// migration the consumer needs to know about.
-				migrated.push({ toneId: tone.id, from: previous.appliedVersion, to: tone.version });
-				recordApplied(deps.state, tone, now, previous.channelId, fingerprint);
+			for (const entry of affected) {
+				await writer.write({
+					request: {
+						id: entry.id,
+						content: entry.content,
+						tone: entry.tone,
+						moment: { at: entry.resolvedAt, anchoring: entry.anchoring },
+						routing: entry.routing,
+						actions: entry.actions,
+						ownerTag: entry.ownerTag,
+						groupTag: entry.groupTag,
+					},
+					resolvedAt: entry.resolvedAt,
+					tone: resolved,
+					// Re-homing changes the channel, not the anchoring — preserve it.
+					anchoringGeneration: entry.anchoringGeneration,
+					approximate: entry.mayBeDelayed,
+					seriesId: entry.seriesId,
+					pushCreated: entry.pushCreated,
+				});
+				reHomed.push(entry.id);
 			}
 
-			// Anything left on a retired channel would be an orphan — a notification
-			// the user can no longer control from system settings.
-			const orphans = await findOrphans(deps, tones);
-			if (orphans.length > 0) {
-				await deps.engine.cancelMany(orphans);
-				cancelled.push(...orphans);
-				emit(
-					DIAGNOSTIC_CODES.CHANNEL_ORPHANS_FOUND,
-					`${orphans.length} notification(s) remained on a retired channel and were cancelled, rather than left uncontrollable from system settings.`,
-					{ count: orphans.length },
-				);
+			const didRetire = await deps.engine.retireTone(previous.channelId);
+			if (didRetire) {
+				retired.push(previous.channelId);
 			}
 
-			return {
-				created,
-				migrated,
-				labelsRefreshed,
-				retired,
-				reHomed,
-				cancelled,
-				bypassUnavailable,
-				repeatUnavailable,
-				unchanged,
-			};
+			// A version move outranks a label change: the new channel simply
+			// carries the new labels, and reporting it as a refresh would hide a
+			// migration the consumer needs to know about.
+			migrated.push({ toneId: tone.id, from: previous.appliedVersion, to: tone.version });
+			recordApplied(deps.state, tone, now, previous.channelId, fingerprint);
+		}
+
+		// Anything left on a retired channel would be an orphan — a notification
+		// the user can no longer control from system settings.
+		const orphans = await findOrphans(deps, tones);
+		if (orphans.length > 0) {
+			await deps.engine.cancelMany(orphans);
+			cancelled.push(...orphans);
+			emit(
+				DIAGNOSTIC_CODES.CHANNEL_ORPHANS_FOUND,
+				`${orphans.length} notification(s) remained on a retired channel and were cancelled, rather than left uncontrollable from system settings.`,
+				{ count: orphans.length },
+			);
+		}
+
+		return {
+			created,
+			migrated,
+			labelsRefreshed,
+			retired,
+			reHomed,
+			cancelled,
+			bypassUnavailable,
+			repeatUnavailable,
+			unchanged,
+		};
+	};
+
+	return {
+		/**
+		 * Applies a tone configuration, migrating any tone whose version moved.
+		 *
+		 * Applying an unchanged configuration performs no work at all: no channel
+		 * is recreated and no migration is triggered.
+		 */
+		apply(
+			tones: readonly ToneDeclaration[],
+			groups: readonly ChannelGroup[] = [],
+		): Promise<ChannelApplyResult> {
+			// The declared channels are read once for the whole apply rather than once
+			// per tone, when the engine can hold them (NOT-08).
+			const run = () => applyTones(tones, groups);
+			return deps.engine.withChannelSnapshot ? deps.engine.withChannelSnapshot(run) : run();
 		},
 
 		/** Which version of each tone this device actually holds. */
@@ -278,8 +288,16 @@ async function findOrphans(
 	tones: readonly ToneDeclaration[],
 ): Promise<readonly string[]> {
 	const declared = new Set(tones.map(tone => tone.id));
+	// Only tones this package once applied can leave orphans (NOT-05). An entry
+	// with no tone metadata was scheduled by other code through the same engine,
+	// and a tone the ledger has never seen is not ours to judge either: cancelling
+	// on "not in this call's list" silently deleted other libraries' notifications,
+	// and a feature module's own when it applied only its subset of tones.
+	const onceApplied = new Set(deps.state.read().migrationLedger.map(entry => entry.toneId));
 	const pending = await deps.engine.getPending();
-	return pending.filter(entry => !declared.has(entry.tone)).map(entry => entry.id);
+	return pending
+		.filter(entry => entry.tone !== '' && onceApplied.has(entry.tone) && !declared.has(entry.tone))
+		.map(entry => entry.id);
 }
 
 export type Channels = ReturnType<typeof createChannels>;

package/src/channel/tone-map.ts

@@ -13,6 +13,7 @@
  */
 
 import type { ResolvedTone, ToneDeclaration, ToneUrgency } from '../contract/channel';
+import { fnv1a, hex8 } from '../contract/hash';
 
 type AndroidImportance = ResolvedTone['android']['importance'];
 type IosInterruption = ResolvedTone['ios']['interruptionLevel'];
@@ -109,16 +110,7 @@ export function toneLabelFingerprint(tone: ToneDeclaration): string {
 	// of the two would never get its correction.
 	const source = `${tone.name}\u0000${tone.description ?? ''}`;
 
-	// FNV-1a. Bitwise operators are the algorithm, not a micro-optimisation:
-	// arithmetic equivalents would not wrap to 32 bits and the hash would drift.
-	/* eslint-disable no-bitwise */
-	let hash = 0x811c9dc5;
-	for (let index = 0; index < source.length; index += 1) {
-		hash ^= source.codePointAt(index) ?? 0;
-		hash = Math.imul(hash, 0x01000193) >>> 0;
-	}
-	return (hash >>> 0).toString(16).padStart(8, '0');
-	/* eslint-enable no-bitwise */
+	return hex8(fnv1a(source));
 }
 
 /** Builds a lookup over a declared configuration. */

package/src/contract/errors.ts

@@ -73,6 +73,12 @@ export const DIAGNOSTIC_CODES = {
 	/** The durable store could not open; state lasts for this session only. */
 	STATE_STORE_DEGRADED: 'STATE_STORE_DEGRADED',
 	STATE_CAP_EVICTED: 'STATE_CAP_EVICTED',
+	/**
+	 * A ledger holds more live entries than its cap (0.6.0). They are all kept:
+	 * dropping a live series or channel record would lose a migration or reset a
+	 * series count. Reported so the cap can be raised or the app's use reviewed.
+	 */
+	STATE_CAP_EXCEEDED: 'STATE_CAP_EXCEEDED',
 
 	// --- Volume --------------------------------------------------------------
 	BURST_THRESHOLD_EXCEEDED: 'BURST_THRESHOLD_EXCEEDED',
@@ -129,6 +135,7 @@ export const NON_FAILURE_CODES: readonly DiagnosticCode[] = Object.freeze([
 	DIAGNOSTIC_CODES.PAYLOAD_VERSION_SKEW,
 	DIAGNOSTIC_CODES.PAYLOAD_DUPLICATE,
 	DIAGNOSTIC_CODES.STATE_CAP_EVICTED,
+	DIAGNOSTIC_CODES.STATE_CAP_EXCEEDED,
 	DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT,
 	DIAGNOSTIC_CODES.BACKGROUND_RESTRICTION_UNKNOWN,
 	DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,

package/src/contract/hash.ts

@@ -0,0 +1,26 @@
+/**
+ * FNV-1a, 32-bit: the package's one hash (NOT-19). Deterministic,
+ * dependency-free, and stable across releases.
+ *
+ * Bitwise operators are the algorithm, not a micro-optimisation: arithmetic
+ * equivalents would not wrap to 32 bits. Stability matters: a marker id or a
+ * label fingerprint that changed between releases would orphan every marker
+ * already scheduled, or refresh every channel label once more.
+ */
+export const FNV_OFFSET_BASIS = 0x811c9dc5;
+
+/* eslint-disable no-bitwise */
+export function fnv1a(value: string, basis: number = FNV_OFFSET_BASIS): 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 */
+
+/** Eight lowercase hex digits. */
+export function hex8(value: number): string {
+	return value.toString(16).padStart(8, '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';
+	}
+}