@chipmobilesdk/rn-notification 0.4.1 → 0.6.0

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.
  *

package/src/repeat/place.ts

@@ -27,47 +27,86 @@ export interface StopPlacement {
 	sync(targetId: string, tone: ResolvedTone, deliversAt: number): Promise<void>;
 	/** Drops any marker still guarding an identifier. */
 	release(targetId: string): Promise<void>;
+	/** How many markers are outstanding: platform capacity they hold. */
+	count(): Promise<number>;
+	/**
+	 * A placement for one pass of many operations (NOT-08). It reads the
+	 * outstanding markers once and keeps that view current as it places and
+	 * releases, instead of reading every pending trigger across the bridge for
+	 * each operation — which made a reconcile of a few hundred changes do a few
+	 * hundred full reads.
+	 */
+	pass(): StopPlacement;
 }
 
 export function createStopPlacement(engine: NotificationEngineAdapter): StopPlacement {
-	const release = async (targetId: string): Promise<void> => {
-		const outstanding = await engine.listRepeatStops();
-		const held = outstanding.find(stop => stop.targetId === targetId);
-		if (held !== undefined) {
-			await engine.cancel(held.markerId);
-		}
-	};
+	/** `snapshot`: read once and kept current, for a pass; otherwise read on every call. */
+	function placement(snapshot: boolean): StopPlacement {
+		let known: Map<string, string> | undefined;
+
+		/** targetId → markerId of every outstanding stop. */
+		const outstanding = async (): Promise<Map<string, string>> => {
+			if (snapshot && known) {
+				return known;
+			}
+			const read = new Map(
+				(await engine.listRepeatStops()).map(stop => [stop.targetId, stop.markerId] as const),
+			);
+			if (snapshot) {
+				known = read;
+			}
+			return read;
+		};
+
+		const release = async (targetId: string): Promise<void> => {
+			const stops = await outstanding();
+			const markerId = stops.get(targetId);
+			if (markerId !== undefined) {
+				await engine.cancel(markerId);
+				stops.delete(targetId);
+			}
+		};
+
+		return {
+			release,
+
+			async count() {
+				return (await outstanding()).size;
+			},
+
+			async sync(targetId, tone, deliversAt) {
+				await release(targetId);
 
-	return {
-		release,
+				const forMs = tone.android.repeatForMs;
+				if (!tone.android.loopSound || forMs === undefined) return;
 
-		async sync(targetId, tone, deliversAt) {
-			await release(targetId);
+				const capabilities = await engine.getCapabilities();
+				if (!capabilities.supportsRepeatingAlert) return;
 
-			const forMs = tone.android.repeatForMs;
-			if (!tone.android.loopSound || forMs === undefined) return;
+				const stop = repeatStopFor(targetId, deliversAt, forMs);
+				await engine.schedule({
+					request: {
+						id: stop.markerId,
+						// Deliberately empty. A marker is delivered and removed within the
+						// same handler invocation; anything readable here would be text a
+						// user might glimpse and be confused by.
+						content: { title: '', body: '' },
+						tone: tone.toneId,
+						// Absolute: the bound is a duration from a known instant, not a
+						// wall-clock time that should follow the user across time zones.
+						moment: { at: stop.dueAt, anchoring: 'absolute' },
+					},
+					resolvedAt: stop.dueAt,
+					tone,
+					approximate: false,
+					repeatStop: stop,
+				});
+				known?.set(targetId, stop.markerId);
+			},
 
-			const capabilities = await engine.getCapabilities();
-			if (!capabilities.supportsRepeatingAlert) return;
+			pass: () => placement(true),
+		};
+	}
 
-			const stop = repeatStopFor(targetId, deliversAt, forMs);
-			await engine.schedule({
-				request: {
-					id: stop.markerId,
-					// Deliberately empty. A marker is delivered and removed within the
-					// same handler invocation; anything readable here would be text a
-					// user might glimpse and be confused by.
-					content: { title: '', body: '' },
-					tone: tone.toneId,
-					// Absolute: the bound is a duration from a known instant, not a
-					// wall-clock time that should follow the user across time zones.
-					moment: { at: stop.dueAt, anchoring: 'absolute' },
-				},
-				resolvedAt: stop.dueAt,
-				tone,
-				approximate: false,
-				repeatStop: stop,
-			});
-		},
-	};
+	return placement(false);
 }

package/src/schedule/anchor.ts

@@ -16,12 +16,27 @@
  * each entry is what makes that detectable instead of invisible.
  */
 
+import {
+	getDateTimeFormat,
+	isValidTimeZone as isZoneValid,
+	lazyPeer,
+} from '@chipmobilesdk/rn-core';
+
 import type { AnchoringMode, PendingEntry } from '../contract/notification';
 import { DEFAULT_ANCHORING_MODE } from '../contract/notification';
 
 /** Reads the platform time zone. Injected so the pure logic needs no native module. */
 export type TimeZoneReader = () => string;
 
+const localizePeer = lazyPeer('react-native-localize', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-localize') as { getTimeZone(): string };
+	} catch (cause) {
+		throw cause;
+	}
+});
+
 /**
  * Resolves the platform zone via `react-native-localize`.
  *
@@ -32,9 +47,10 @@ export type TimeZoneReader = () => string;
  */
 export function createPlatformTimeZoneReader(): TimeZoneReader {
 	return () => {
+		const localize = localizePeer.get();
 		try {
-			const localize = require('react-native-localize') as { getTimeZone(): string };
-			return localize.getTimeZone();
+			if (localize.ok) return localize.module.getTimeZone();
+			return Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
 		} catch {
 			try {
 				return Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
@@ -65,15 +81,22 @@ export interface WallClockParts {
  * tone id here — so it must be checked before it reaches `Intl`.
  */
 export function isValidTimeZone(timeZone: string): boolean {
-	if (timeZone.length === 0) return false;
-	try {
-		new Intl.DateTimeFormat('en-US', { timeZone }).format(0);
-		return true;
-	} catch {
-		return false;
-	}
+	// rn-core memoizes the answer per zone: a recurrence expansion asks thousands
+	// of times about the same few zones (PERF-01).
+	return isZoneValid(timeZone);
 }
 
+/** The options `partsInZone` formats with; one shared formatter per zone. */
+const PARTS_OPTIONS = {
+	year: 'numeric',
+	month: '2-digit',
+	day: '2-digit',
+	hour: '2-digit',
+	minute: '2-digit',
+	second: '2-digit',
+	hour12: false,
+} as const;
+
 /**
  * Decomposes an instant into the clock reading it produces in a given zone.
  *
@@ -82,16 +105,9 @@ export function isValidTimeZone(timeZone: string): boolean {
  */
 export function partsInZone(instant: number, timeZone: string): WallClockParts {
 	const zone = isValidTimeZone(timeZone) ? timeZone : 'UTC';
-	const formatter = new Intl.DateTimeFormat('en-US', {
-		timeZone: zone,
-		year: 'numeric',
-		month: '2-digit',
-		day: '2-digit',
-		hour: '2-digit',
-		minute: '2-digit',
-		second: '2-digit',
-		hour12: false,
-	});
+	// Built once per zone and reused (PERF-01): constructing one per call was
+	// most of the cost of expanding a recurrence.
+	const formatter = getDateTimeFormat('en-US', { ...PARTS_OPTIONS, timeZone: zone });
 
 	const fields: Record<string, number> = {};
 	for (const part of formatter.formatToParts(new Date(instant))) {

package/src/schedule/index.ts

@@ -97,8 +97,12 @@ export function createScheduler(deps: ScheduleDependencies) {
 		const anchored = anchorMoment(request.moment, zone);
 		const resolution = resolveMoment(anchored.resolvedAt, deps.now());
 
-		const existing = await deps.engine.getPending();
-		const replaced = existing.some(entry => entry.id === request.id);
+		// Identifiers only where the engine can list them cheaply: reading every
+		// pending payload across the bridge just to answer "was this one already
+		// there" cost a full read per schedule (NOT-08).
+		const replaced = deps.engine.pendingIds
+			? (await deps.engine.pendingIds()).includes(request.id)
+			: (await deps.engine.getPending()).some(entry => entry.id === request.id);
 
 		// Approximate mode is a degradation, not a refusal: the notification is
 		// still scheduled and the caller is told it may arrive late.
@@ -149,7 +153,8 @@ export function createScheduler(deps: ScheduleDependencies) {
 			validateIdentifier(groupTag, 'groupTag');
 			const ids = idsForTag(await deps.engine.getPending(), 'group', groupTag);
 			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);
 			return ids;
 		},
 
@@ -157,7 +162,8 @@ export function createScheduler(deps: ScheduleDependencies) {
 			validateIdentifier(ownerTag, 'ownerTag');
 			const ids = idsForTag(await deps.engine.getPending(), 'owner', ownerTag);
 			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);
 			return ids;
 		},
 

package/src/schedule/partition.ts

@@ -67,22 +67,3 @@ export function partition(
 
 	return { tagged, untagged };
 }
-
-/**
- * True when cancelling `tag` would affect any entry outside it.
- *
- * Exists so isolation can be asserted directly rather than inferred from a
- * count — the property that matters is that one account's sign-out changes
- * exactly zero of another account's notifications.
- */
-export function wouldAffectOtherTags(
-	entries: readonly PendingEntry[],
-	kind: PartitionKind,
-	tag: string,
-): boolean {
-	const selected = new Set(idsForTag(entries, kind, tag));
-	return entries.some(entry => {
-		const entryTag = kind === 'owner' ? entry.ownerTag : entry.groupTag;
-		return selected.has(entry.id) && entryTag !== tag;
-	});
-}

package/src/schedule/validate-identifier.ts

@@ -108,12 +108,14 @@ export function validateIdentifier(value: unknown, kind: IdentifierKind = 'id'):
 
 /** Non-throwing form, for validating a batch without unwinding on the first failure. */
 export function isValidIdentifier(value: unknown): value is string {
-	return (
-		typeof value === 'string' &&
-		value.length > 0 &&
-		value.length <= MAX_IDENTIFIER_LENGTH &&
-		IDENTIFIER_PATTERN.test(value)
-	);
+	// The throwing form is the rule; this one only reports whether it holds, so
+	// the two cannot disagree (the reserved marker prefix was missing here).
+	try {
+		validateIdentifier(value);
+		return true;
+	} catch {
+		return false;
+	}
 }
 
 /** Validates an optional tag, returning undefined when absent rather than failing. */

package/src/schedule/writer.ts

@@ -14,7 +14,7 @@
  */
 
 import type { NotificationEngineAdapter, EngineScheduleRequest } from '../engine/adapter';
-import { createStopPlacement } from '../repeat/place';
+import { createStopPlacement, type StopPlacement } from '../repeat/place';
 
 export interface ScheduleWriter {
 	/** Writes one notification and brings its stop marker in line with it. */
@@ -28,11 +28,19 @@ export interface ScheduleWriter {
 	 * real capacity, so the usable ceiling is the platform's minus theirs.
 	 */
 	capacity(): Promise<number>;
+	/**
+	 * A writer for one pass of many writes (NOT-08): it reads the outstanding stop
+	 * markers once and keeps that view current, instead of a full read of every
+	 * pending trigger per operation.
+	 */
+	pass(): ScheduleWriter;
 }
 
 export function createScheduleWriter(engine: NotificationEngineAdapter): ScheduleWriter {
-	const stops = createStopPlacement(engine);
+	return writerOver(engine, createStopPlacement(engine));
+}
 
+function writerOver(engine: NotificationEngineAdapter, stops: StopPlacement): ScheduleWriter {
 	return {
 		async write(input) {
 			await engine.schedule(input);
@@ -48,8 +56,9 @@ export function createScheduleWriter(engine: NotificationEngineAdapter): Schedul
 
 		async capacity() {
 			const capabilities = await engine.getCapabilities();
-			const markerCost = (await engine.listRepeatStops()).length;
-			return Math.max(0, capabilities.pendingCeiling - markerCost);
+			return Math.max(0, capabilities.pendingCeiling - (await stops.count()));
 		},
+
+		pass: () => writerOver(engine, stops.pass()),
 	};
 }

package/src/state/caps.ts

@@ -26,8 +26,21 @@ export interface EvictionOutcome<T> {
 	readonly kept: readonly T[];
 	readonly evicted: readonly T[];
 	readonly reason: 'none' | 'cap' | 'retention' | 'cap+retention';
+	/** Entries kept beyond the cap because none of them may be evicted (NOT-16). */
+	readonly overCap: number;
 }
 
+/**
+ * Which entries a cap may drop (NOT-16). The migration and series ledgers record
+ * live facts: an active channel's applied version, a series' count. Dropping one
+ * makes the package treat a migrated tone as new and restart a series from zero,
+ * so only retired and exhausted entries go; the rest are kept and reported.
+ */
+const EVICTABLE: Partial<Record<CollectionName, (entry: unknown) => boolean>> = {
+	migrationLedger: entry => (entry as { retired?: boolean }).retired === true,
+	seriesLedger: entry => (entry as { exhausted?: boolean }).exhausted === true,
+};
+
 /**
  * Applies retention first, then the size cap.
  *
@@ -55,8 +68,15 @@ export function evict<T extends Timestamped>(
 	// Oldest first, so the tail is what we keep when trimming.
 	live.sort((a, b) => a.at - b.at);
 
-	const overflow = live.length > maxEntries ? live.slice(0, live.length - maxEntries) : [];
-	const kept = live.length > maxEntries ? live.slice(live.length - maxEntries) : live;
+	const evictable = EVICTABLE[collection] ?? (() => true);
+	const excess = Math.max(0, live.length - maxEntries);
+	const overflow: T[] = [];
+	for (const entry of live) {
+		if (overflow.length === excess) break;
+		if (evictable(entry)) overflow.push(entry);
+	}
+	const dropped = new Set(overflow);
+	const kept = overflow.length === 0 ? live : live.filter(entry => !dropped.has(entry));
 
 	let reason: EvictionOutcome<T>['reason'] = 'none';
 	if (expired.length > 0 && overflow.length > 0) {
@@ -67,5 +87,10 @@ export function evict<T extends Timestamped>(
 		reason = 'retention';
 	}
 
-	return { kept, evicted: [...expired, ...overflow], reason };
+	return {
+		kept,
+		evicted: [...expired, ...overflow],
+		reason,
+		overCap: Math.max(0, kept.length - maxEntries),
+	};
 }

package/src/state/interaction-buffer.ts

@@ -9,11 +9,28 @@
  * cannot be delivered without its routing payload. It is evicted the moment it
  * is delivered, and time-limited regardless, so an event nobody ever collects
  * cannot sit on disk forever.
+ *
+ * Text the user typed into a reply action is never written to disk (NOT-14): it
+ * is free text, and the store is not encrypted. It is held in memory beside the
+ * buffer, so a handler registered later in the same process still receives it;
+ * if the process dies first, the event is delivered without `inputText`.
  */
 
 import type { StateManager, BufferedInteraction } from './record';
 import type { InteractionEvent } from '../contract/interaction';
 
+/** Typed replies, in memory only, per state manager and buffered event id. */
+const typedReplies = new WeakMap<StateManager, Map<string, string>>();
+
+function repliesOf(state: StateManager): Map<string, string> {
+	let replies = typedReplies.get(state);
+	if (!replies) {
+		replies = new Map();
+		typedReplies.set(state, replies);
+	}
+	return replies;
+}
+
 /** Identity for a buffered event, derived so re-buffering cannot duplicate. */
 function bufferedId(event: InteractionEvent): string {
 	return `${event.kind}:${event.notificationId}:${event.actionId ?? ''}:${event.occurredAt}`;
@@ -21,6 +38,9 @@ function bufferedId(event: InteractionEvent): string {
 
 export function buffer(state: StateManager, event: InteractionEvent): void {
 	const id = bufferedId(event);
+	if (event.inputText !== undefined) {
+		repliesOf(state).set(id, event.inputText);
+	}
 
 	state.update('interactionBuffer', current => {
 		if (current.some(entry => entry.id === id)) return current;
@@ -31,7 +51,6 @@ export function buffer(state: StateManager, event: InteractionEvent): void {
 			kind: event.kind,
 			notificationId: event.notificationId,
 			actionId: event.actionId,
-			inputText: event.inputText,
 			routing: event.routing,
 			ownerTag: event.ownerTag,
 		};
@@ -52,12 +71,15 @@ export function drain(state: StateManager): readonly InteractionEvent[] {
 	if (buffered.length === 0) return [];
 
 	state.update('interactionBuffer', () => []);
+	const replies = repliesOf(state);
 
 	return buffered.map(entry => ({
 		kind: entry.kind,
 		notificationId: entry.notificationId,
 		actionId: entry.actionId,
-		inputText: entry.inputText,
+		// A record written before 0.5 may still carry the text on disk; it is
+		// delivered once, and the buffer was just cleared.
+		inputText: takeReply(replies, entry.id) ?? entry.inputText,
 		routing: entry.routing,
 		ownerTag: entry.ownerTag,
 		occurredAt: entry.at,
@@ -71,3 +93,9 @@ export function drain(state: StateManager): readonly InteractionEvent[] {
 export function bufferedCount(state: StateManager): number {
 	return state.read().interactionBuffer.length;
 }
+
+function takeReply(replies: Map<string, string>, id: string): string | undefined {
+	const text = replies.get(id);
+	replies.delete(id);
+	return text;
+}