@chipmobilesdk/rn-notification 0.1.1 → 0.2.0

package/src/testing/fake-engine.ts

@@ -1,284 +1,469 @@
-/**
- * In-memory engine for tests.
- *
- * Exists so every decision path is provable with no device, no emulator, and
- * no live provider. Its controls simulate the conditions that are otherwise
- * only reachable on hardware: virtual time, time-zone travel, permission
- * transitions, process death, boot-restoration gaps, and platform truncation.
- */
-
-import type {
-	NotificationEngineAdapter,
-	EngineCapabilities,
-	EngineScheduleRequest,
-} from '../engine/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';
-
-export interface FakeEngineOptions {
-	readonly pendingCeiling?: number;
-	readonly supportsExactAlarms?: boolean;
-	readonly supportsDoNotDisturbBypass?: boolean;
-	readonly backgroundWindowMs?: number;
-	readonly initialPermissions?: Partial<Record<PermissionKind, PermissionState>>;
-	readonly timeZone?: string;
-	readonly now?: number;
-}
-
-/** Every platform operation the engine was asked to perform, in order. */
-export interface RecordedOperation {
-	readonly kind: 'schedule' | 'cancel' | 'cancelAll' | 'declareTone' | 'retireTone';
-	readonly id?: string;
-	readonly at: number;
-}
-
-export interface FakeControls {
-	/** Operations recorded since the last reset. The idempotence assertion reads this. */
-	readonly operations: readonly RecordedOperation[];
-	clearOperations(): void;
-
-	/** Virtual clock, so tests never sleep. */
-	now(): number;
-	advanceTime(ms: number): void;
-	setTime(epochMs: number): void;
-
-	/** Simulates the user travelling. */
-	timeZone(): string;
-	setTimeZone(zone: string): void;
-
-	setPermission(kind: PermissionKind, state: PermissionState): void;
-	setRestrictions(report: Partial<RestrictionReport>): void;
-
-	/**
-	 * Drops entries the platform would have silently discarded past its ceiling,
-	 * so truncation behavior is testable without an iOS device.
-	 */
-	applyPlatformCeiling(): readonly string[];
-
-	/**
-	 * Simulates the process dying: in-memory listeners are lost while scheduled
-	 * notifications survive, which is exactly what happens on a real device.
-	 */
-	simulateProcessDeath(): void;
-
-	/** Simulates a manufacturer losing notifications across a reboot. */
-	simulateBootGap(ids: readonly string[]): void;
-
-	/** Queues an interaction that arrived before any handler existed. */
-	emitInteraction(event: InteractionEvent): void;
-	queueInitialInteraction(event: InteractionEvent): void;
-}
-
-export type FakeEngine = NotificationEngineAdapter & FakeControls;
-
-export function createFakeEngine(options: FakeEngineOptions = {}): FakeEngine {
-	const scheduled = new Map<string, PendingEntry>();
-	const channels = new Set<string>();
-	let operations: RecordedOperation[] = [];
-	let listeners: ((event: InteractionEvent) => void)[] = [];
-	let initialInteraction: InteractionEvent | undefined;
-
-	let currentTime = options.now ?? Date.UTC(2026, 0, 1, 12, 0, 0);
-	let currentZone = options.timeZone ?? 'UTC';
-
-	const permissions: Record<PermissionKind, PermissionState> = {
-		display: options.initialPermissions?.display ?? 'notAsked',
-		exactAlarm: options.initialPermissions?.exactAlarm ?? 'notAsked',
-	};
-
-	let restrictions: RestrictionReport = {
-		batteryOptimization: 'unrestricted',
-		autoStart: 'unrestricted',
-		readAt: currentTime,
-	};
-
-	const capabilities: EngineCapabilities = {
-		pendingCeiling: options.pendingCeiling ?? 64,
-		supportsExactAlarms: options.supportsExactAlarms ?? true,
-		supportsChannels: true,
-		supportsTextInputActions: true,
-		supportsDoNotDisturbBypass: options.supportsDoNotDisturbBypass ?? true,
-		backgroundWindowMs: options.backgroundWindowMs ?? 30_000,
-	};
-
-	const record = (kind: RecordedOperation['kind'], id?: string): void => {
-		operations.push({ kind, id, at: currentTime });
-	};
-
-	const toPendingEntry = (request: EngineScheduleRequest): PendingEntry => ({
-		id: request.request.id,
-		resolvedAt: request.resolvedAt,
-		anchoring: request.request.moment.anchoring ?? 'wallClock',
-		anchoringGeneration:
-			(request.request.moment.anchoring ?? 'wallClock') === 'wallClock' ? currentZone : undefined,
-		content: request.request.content,
-		tone: request.request.tone,
-		routing: request.request.routing,
-		actions: request.request.actions,
-		ownerTag: request.request.ownerTag,
-		groupTag: request.request.groupTag,
-		seriesId: request.seriesId,
-		mayBeDelayed: request.approximate,
-		pushCreated: request.pushCreated ?? false,
-	});
-
-	return {
-		name: 'fake',
-
-		async getCapabilities() {
-			return capabilities;
-		},
-
-		async schedule(request) {
-			record('schedule', request.request.id);
-			scheduled.set(request.request.id, toPendingEntry(request));
-		},
-
-		async cancel(id) {
-			record('cancel', id);
-			scheduled.delete(id);
-		},
-
-		async cancelMany(ids) {
-			for (const id of ids) {
-				record('cancel', id);
-				scheduled.delete(id);
-			}
-		},
-
-		async cancelAll() {
-			record('cancelAll');
-			scheduled.clear();
-		},
-
-		async getPending() {
-			return [...scheduled.values()].sort((a, b) => a.resolvedAt - b.resolvedAt);
-		},
-
-		async declareTone(tone: ResolvedTone) {
-			record('declareTone', tone.android.channelId);
-			if (channels.has(tone.android.channelId)) {
-				// Android silently ignores re-declaration. The fake does too, on purpose.
-				return false;
-			}
-			channels.add(tone.android.channelId);
-			return true;
-		},
-
-		async retireTone(channelId: string) {
-			record('retireTone', channelId);
-			return channels.delete(channelId);
-		},
-
-		async declareGroups(_groups: readonly ChannelGroup[]) {
-			// Groups are presentational; the fake accepts them without recording.
-		},
-
-		async listDeclaredChannels() {
-			return [...channels];
-		},
-
-		async getPermission(kind) {
-			return permissions[kind];
-		},
-
-		async requestPermission(kind) {
-			if (permissions[kind] === 'notAsked') {
-				permissions[kind] = 'granted';
-			}
-			return permissions[kind];
-		},
-
-		async openSettings(_kind) {
-			// No-op: the fake cannot open a settings screen, and pretending it did would be a lie.
-		},
-
-		async getRestrictions() {
-			return { ...restrictions, readAt: currentTime };
-		},
-
-		subscribeToInteractions(handler): Unsubscribe {
-			listeners.push(handler);
-			return () => {
-				listeners = listeners.filter(l => l !== handler);
-			};
-		},
-
-		async takeInitialInteraction() {
-			const event = initialInteraction;
-			initialInteraction = undefined;
-			return event;
-		},
-
-		// --- FakeControls ------------------------------------------------------
-
-		get operations() {
-			return operations;
-		},
-
-		clearOperations() {
-			operations = [];
-		},
-
-		now() {
-			return currentTime;
-		},
-
-		advanceTime(ms) {
-			currentTime += ms;
-		},
-
-		setTime(epochMs) {
-			currentTime = epochMs;
-		},
-
-		timeZone() {
-			return currentZone;
-		},
-
-		setTimeZone(zone) {
-			currentZone = zone;
-		},
-
-		setPermission(kind, state) {
-			permissions[kind] = state;
-		},
-
-		setRestrictions(report) {
-			restrictions = { ...restrictions, ...report };
-		},
-
-		applyPlatformCeiling() {
-			const ordered = [...scheduled.values()].sort((a, b) => a.resolvedAt - b.resolvedAt);
-			const dropped = ordered.slice(capabilities.pendingCeiling);
-			for (const entry of dropped) {
-				scheduled.delete(entry.id);
-			}
-			return dropped.map(entry => entry.id);
-		},
-
-		simulateProcessDeath() {
-			// Scheduled notifications live in the OS and survive; listeners do not.
-			listeners = [];
-			operations = [];
-		},
-
-		simulateBootGap(ids) {
-			for (const id of ids) {
-				scheduled.delete(id);
-			}
-		},
-
-		emitInteraction(event) {
-			for (const listener of listeners) {
-				listener(event);
-			}
-		},
-
-		queueInitialInteraction(event) {
-			initialInteraction = event;
-		},
-	};
-}
+/**
+ * In-memory engine for tests.
+ *
+ * Exists so every decision path is provable with no device, no emulator, and
+ * no live provider. Its controls simulate the conditions that are otherwise
+ * only reachable on hardware: virtual time, time-zone travel, permission
+ * transitions, process death, boot-restoration gaps, and platform truncation.
+ */
+
+import type {
+	NotificationEngineAdapter,
+	DeliveryEvent,
+	EngineCapabilities,
+	EngineScheduleRequest,
+	RepeatStop,
+	ToneDeclarationOutcome,
+} from '../engine/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 { isRepeatStopId } from '../repeat/marker';
+
+export interface FakeEngineOptions {
+	readonly pendingCeiling?: number;
+	readonly supportsExactAlarms?: boolean;
+	readonly supportsDoNotDisturbBypass?: boolean;
+	readonly supportsRepeatingAlert?: boolean;
+	readonly backgroundWindowMs?: number;
+	readonly initialPermissions?: Partial<Record<PermissionKind, PermissionState>>;
+	readonly timeZone?: string;
+	readonly now?: number;
+}
+
+/** Every platform operation the engine was asked to perform, in order. */
+export interface RecordedOperation {
+	readonly kind:
+		| 'schedule'
+		| 'cancel'
+		| 'cancelAll'
+		| 'declareTone'
+		| 'retireTone'
+		| 'silence';
+	readonly id?: string;
+	readonly at: number;
+}
+
+/** A notification the fake has delivered to the tray. */
+export interface DisplayedNotification {
+	readonly id: string;
+	readonly tone: string;
+	/** Whether its alert is still sounding — the property repeat expiry is about. */
+	readonly alerting: boolean;
+	readonly deliveredAt: number;
+}
+
+export interface FakeControls {
+	/** Operations recorded since the last reset. The idempotence assertion reads this. */
+	readonly operations: readonly RecordedOperation[];
+	clearOperations(): void;
+
+	/** Virtual clock, so tests never sleep. */
+	now(): number;
+	advanceTime(ms: number): void;
+	setTime(epochMs: number): void;
+
+	/** Simulates the user travelling. */
+	timeZone(): string;
+	setTimeZone(zone: string): void;
+
+	setPermission(kind: PermissionKind, state: PermissionState): void;
+	setRestrictions(report: Partial<RestrictionReport>): void;
+
+	/**
+	 * Drops entries the platform would have silently discarded past its ceiling,
+	 * so truncation behavior is testable without an iOS device.
+	 */
+	applyPlatformCeiling(): readonly string[];
+
+	/**
+	 * Simulates the process dying: in-memory listeners are lost while scheduled
+	 * notifications survive, which is exactly what happens on a real device.
+	 */
+	simulateProcessDeath(): void;
+
+	/** Simulates a manufacturer losing notifications across a reboot. */
+	simulateBootGap(ids: readonly string[]): void;
+
+	/** Queues an interaction that arrived before any handler existed. */
+	emitInteraction(event: InteractionEvent): void;
+	queueInitialInteraction(event: InteractionEvent): void;
+
+	/** The labels a declared channel currently carries, so a label refresh is assertable. */
+	channelLabels(channelId: string): { name: string; description?: string } | undefined;
+
+	/** Whether a delivered notification's alert is still sounding. */
+	isAlerting(id: string): boolean;
+
+	/** The tray. Distinct from the pending set: expiry is about what is *displayed*. */
+	displayed(): readonly DisplayedNotification[];
+
+	/**
+	 * Fires every trigger whose instant has passed, in order, on the virtual clock.
+	 *
+	 * The fake modelled time, process death, and boot gaps but never modelled
+	 * delivery — and expiry is a delivery-ordering property. Without this, proving
+	 * that an alert stops on its own would need a real device or a real wait.
+	 */
+	deliverDue(): Promise<readonly string[]>;
+
+	/** Simulates the user acting on a delivered notification: the alert stops, the entry goes. */
+	handleDisplayed(id: string): void;
+}
+
+export type FakeEngine = NotificationEngineAdapter & FakeControls;
+
+export function createFakeEngine(options: FakeEngineOptions = {}): FakeEngine {
+	const scheduled = new Map<string, PendingEntry>();
+	const channels = new Map<string, { name: string; description?: string }>();
+	const loops = new Map<string, boolean>();
+	const stops = new Map<string, RepeatStop>();
+	const tray = new Map<string, { tone: string; alerting: boolean; deliveredAt: number }>();
+	let operations: RecordedOperation[] = [];
+	let listeners: ((event: InteractionEvent) => void)[] = [];
+	let deliveryListeners: ((event: DeliveryEvent) => void)[] = [];
+	let backgroundHandler: ((event: DeliveryEvent) => Promise<void>) | undefined;
+	let initialInteraction: InteractionEvent | undefined;
+
+	let currentTime = options.now ?? Date.UTC(2026, 0, 1, 12, 0, 0);
+	let currentZone = options.timeZone ?? 'UTC';
+
+	const permissions: Record<PermissionKind, PermissionState> = {
+		display: options.initialPermissions?.display ?? 'notAsked',
+		exactAlarm: options.initialPermissions?.exactAlarm ?? 'notAsked',
+	};
+
+	let restrictions: RestrictionReport = {
+		batteryOptimization: 'unrestricted',
+		autoStart: 'unrestricted',
+		readAt: currentTime,
+	};
+
+	const capabilities: EngineCapabilities = {
+		pendingCeiling: options.pendingCeiling ?? 64,
+		supportsExactAlarms: options.supportsExactAlarms ?? true,
+		supportsChannels: true,
+		supportsTextInputActions: true,
+		supportsDoNotDisturbBypass: options.supportsDoNotDisturbBypass ?? true,
+		supportsRepeatingAlert: options.supportsRepeatingAlert ?? true,
+		backgroundWindowMs: options.backgroundWindowMs ?? 30_000,
+	};
+
+	const record = (kind: RecordedOperation['kind'], id?: string): void => {
+		operations.push({ kind, id, at: currentTime });
+	};
+
+	const toPendingEntry = (request: EngineScheduleRequest): PendingEntry => ({
+		id: request.request.id,
+		resolvedAt: request.resolvedAt,
+		anchoring: request.request.moment.anchoring ?? 'wallClock',
+		anchoringGeneration:
+			(request.request.moment.anchoring ?? 'wallClock') === 'wallClock' ? currentZone : undefined,
+		content: request.request.content,
+		tone: request.request.tone,
+		routing: request.request.routing,
+		actions: request.request.actions,
+		ownerTag: request.request.ownerTag,
+		groupTag: request.request.groupTag,
+		seriesId: request.seriesId,
+		mayBeDelayed: request.approximate,
+		pushCreated: request.pushCreated ?? false,
+	});
+
+	return {
+		name: 'fake',
+
+		async getCapabilities() {
+			return capabilities;
+		},
+
+		async schedule(request) {
+			record('schedule', request.request.id);
+			scheduled.set(request.request.id, toPendingEntry(request));
+			loops.set(request.request.id, request.tone.android.loopSound);
+			if (request.repeatStop !== undefined) {
+				stops.set(request.request.id, request.repeatStop);
+			}
+		},
+
+		async cancel(id) {
+			record('cancel', id);
+			scheduled.delete(id);
+			loops.delete(id);
+			stops.delete(id);
+			tray.delete(id);
+		},
+
+		async cancelMany(ids) {
+			for (const id of ids) {
+				record('cancel', id);
+				scheduled.delete(id);
+				loops.delete(id);
+				stops.delete(id);
+				tray.delete(id);
+			}
+		},
+
+		async cancelAll() {
+			record('cancelAll');
+			scheduled.clear();
+			loops.clear();
+			stops.clear();
+			tray.clear();
+		},
+
+		async getPending() {
+			// Stop markers are package-owned artifacts, not user notifications. A
+			// consumer diffing the device against its own intent must never see one.
+			return [...scheduled.values()]
+				.filter(entry => !isRepeatStopId(entry.id))
+				.sort((a, b) => a.resolvedAt - b.resolvedAt);
+		},
+
+		async declareTone(tone: ResolvedTone): Promise<ToneDeclarationOutcome> {
+			record('declareTone', tone.android.channelId);
+			const existing = channels.get(tone.android.channelId);
+
+			if (existing === undefined) {
+				channels.set(tone.android.channelId, {
+					name: tone.android.name,
+					description: tone.android.description,
+				});
+				return 'created';
+			}
+
+			// Android freezes importance, sound, vibration and DND once a channel
+			// exists, but re-declaring updates the name and description. The fake
+			// mirrors exactly that: labels move, everything else is ignored — which
+			// is what makes a label correction free for the user.
+			if (
+				existing.name === tone.android.name &&
+				existing.description === tone.android.description
+			) {
+				return 'unchanged';
+			}
+
+			channels.set(tone.android.channelId, {
+				name: tone.android.name,
+				description: tone.android.description,
+			});
+			return 'labelsRefreshed';
+		},
+
+		async retireTone(channelId: string) {
+			record('retireTone', channelId);
+			return channels.delete(channelId);
+		},
+
+		async declareGroups(_groups: readonly ChannelGroup[]) {
+			// Groups are presentational; the fake accepts them without recording.
+		},
+
+		async listDeclaredChannels() {
+			return [...channels.keys()];
+		},
+
+		async getPermission(kind) {
+			return permissions[kind];
+		},
+
+		async requestPermission(kind) {
+			if (permissions[kind] === 'notAsked') {
+				permissions[kind] = 'granted';
+			}
+			return permissions[kind];
+		},
+
+		async openSettings(_kind) {
+			// No-op: the fake cannot open a settings screen, and pretending it did would be a lie.
+		},
+
+		async getRestrictions() {
+			return { ...restrictions, readAt: currentTime };
+		},
+
+		subscribeToInteractions(handler): Unsubscribe {
+			listeners.push(handler);
+			return () => {
+				listeners = listeners.filter(l => l !== handler);
+			};
+		},
+
+		async takeInitialInteraction() {
+			const event = initialInteraction;
+			initialInteraction = undefined;
+			return event;
+		},
+
+		async silenceDelivered(id: string) {
+			record('silence', id);
+			const entry = tray.get(id);
+			// Absent is the ordinary case, not an error: the user handled it before
+			// the window ran out.
+			if (entry === undefined) return false;
+
+			// Replaced in place, never removed. A notification that vanished is a
+			// worse outcome than one that never sounded.
+			tray.set(id, { ...entry, alerting: false });
+			return true;
+		},
+
+		async listRepeatStops() {
+			return [...stops.values()].filter(stop => scheduled.has(stop.markerId));
+		},
+
+		subscribeToDeliveries(handler): Unsubscribe {
+			deliveryListeners.push(handler);
+			return () => {
+				deliveryListeners = deliveryListeners.filter(l => l !== handler);
+			};
+		},
+
+		registerBackgroundDeliveryHandler(handler) {
+			backgroundHandler = handler;
+		},
+
+		hasBackgroundDeliveryHandler() {
+			return backgroundHandler !== undefined;
+		},
+
+		// --- FakeControls ------------------------------------------------------
+
+		get operations() {
+			return operations;
+		},
+
+		clearOperations() {
+			operations = [];
+		},
+
+		now() {
+			return currentTime;
+		},
+
+		advanceTime(ms) {
+			currentTime += ms;
+		},
+
+		setTime(epochMs) {
+			currentTime = epochMs;
+		},
+
+		timeZone() {
+			return currentZone;
+		},
+
+		setTimeZone(zone) {
+			currentZone = zone;
+		},
+
+		setPermission(kind, state) {
+			permissions[kind] = state;
+		},
+
+		setRestrictions(report) {
+			restrictions = { ...restrictions, ...report };
+		},
+
+		applyPlatformCeiling() {
+			const ordered = [...scheduled.values()].sort((a, b) => a.resolvedAt - b.resolvedAt);
+			const dropped = ordered.slice(capabilities.pendingCeiling);
+			for (const entry of dropped) {
+				scheduled.delete(entry.id);
+			}
+			return dropped.map(entry => entry.id);
+		},
+
+		simulateProcessDeath() {
+			// Scheduled notifications live in the OS and survive; in-process
+			// listeners do not. The background handler does survive, because on a
+			// real device it is registered at module scope and the platform starts
+			// a fresh process to run it — which is the entire reason repeat expiry
+			// depends on it rather than on a foreground subscription.
+			listeners = [];
+			deliveryListeners = [];
+			operations = [];
+		},
+
+		simulateBootGap(ids) {
+			for (const id of ids) {
+				scheduled.delete(id);
+			}
+		},
+
+		emitInteraction(event) {
+			for (const listener of listeners) {
+				listener(event);
+			}
+		},
+
+		queueInitialInteraction(event) {
+			initialInteraction = event;
+		},
+
+		channelLabels(channelId) {
+			return channels.get(channelId);
+		},
+
+		isAlerting(id) {
+			return tray.get(id)?.alerting ?? false;
+		},
+
+		displayed() {
+			return [...tray.entries()].map(([id, entry]) => ({
+				id,
+				tone: entry.tone,
+				alerting: entry.alerting,
+				deliveredAt: entry.deliveredAt,
+			}));
+		},
+
+		async deliverDue() {
+			const due = [...scheduled.values()]
+				.filter(entry => entry.resolvedAt <= currentTime)
+				.sort((a, b) => a.resolvedAt - b.resolvedAt);
+
+			const delivered: string[] = [];
+
+			for (const entry of due) {
+				scheduled.delete(entry.id);
+				const stop = stops.get(entry.id);
+
+				if (stop === undefined) {
+					// A real notification: it lands in the tray and, if its tone
+					// repeats, keeps sounding until something stops it.
+					tray.set(entry.id, {
+						tone: entry.tone,
+						alerting: loops.get(entry.id) ?? false,
+						deliveredAt: currentTime,
+					});
+				}
+
+				const event: DeliveryEvent = {
+					notificationId: entry.id,
+					occurredAt: currentTime,
+					repeatStop: stop,
+				};
+
+				// Foreground listeners when the process is alive, the background
+				// handler when it is not — the same fork a real device makes.
+				if (deliveryListeners.length > 0) {
+					for (const listener of deliveryListeners) {
+						listener(event);
+					}
+				} else if (backgroundHandler !== undefined) {
+					await backgroundHandler(event);
+				}
+
+				delivered.push(entry.id);
+			}
+
+			return delivered;
+		},
+
+		handleDisplayed(id) {
+			tray.delete(id);
+		},
+	};
+}