@chipmobilesdk/rn-notification 0.4.1 → 0.6.0

package/src/state/mmkv-store.ts

@@ -16,19 +16,35 @@
  * README. It is the app's manifest, so it is the app's declaration to make.
  */
 
-import { Platform } from 'react-native';
+import {
+	createDiagnosticChannel,
+	currentPlatform,
+	lazyPeer,
+	openDurable,
+	type MmkvLike,
+} from '@chipmobilesdk/rn-core';
+
+import { DIAGNOSTIC_CODES } from '../contract/errors';
 import type { StateStore } from './store';
-import { createMemoryStore } from './store';
 
 const INSTANCE_ID = 'chipmobilesdk.notification';
 
-/** The slice of a react-native-mmkv v4 instance this store uses (v4 names). */
-interface MmkvLike {
-	getString(key: string): string | undefined;
-	set(key: string, value: string): void;
-	remove(key: string): unknown;
-	clearAll(): void;
-	getAllKeys(): string[];
+const mmkv = lazyPeer('react-native-mmkv', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-mmkv') as {
+			createMMKV: (config: { id: string; path?: string }) => MmkvLike;
+		};
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+const channel = createDiagnosticChannel('rn-notification');
+
+export interface MmkvStoreOptions {
+	/** Told once, with the reason, when the store falls back to memory. */
+	readonly onDegraded?: (cause: unknown) => void;
 }
 
 /**
@@ -36,40 +52,41 @@ interface MmkvLike {
  *
  * The fallback is deliberate: a missing optional native module degrades
  * deduplication and cold-start buffering to session scope, which is a
- * documented degradation. It must never stop notifications being delivered.
+ * documented degradation. It must never stop notifications being delivered, and
+ * it is never silent (NOT-15): it reports `STATE_STORE_DEGRADED` to the app's SDK
+ * sinks and to `onDegraded`, and the store reports `durable: false`.
  */
-export function createMmkvStore(): StateStore {
-	let instance: MmkvLike;
-
-	try {
-		// Required lazily so the package loads in environments without the native module.
-		// v4's factory: up to 0.2.0 this called the v3 `new MMKV()`, which v4 — the
-		// only major the peer range allows — no longer exports as a value, so every
-		// device silently got the session-scoped memory store.
-		const { createMMKV } = require('react-native-mmkv') as {
-			createMMKV: (config: { id: string; path?: string }) => MmkvLike;
-		};
-
-		instance = createMMKV({
-			id: INSTANCE_ID,
-			// Caches is backup-excluded by platform design; see the note above.
-			path: Platform.OS === 'ios' ? 'Library/Caches/chipmobilesdk-notification' : undefined,
-		});
-	} catch {
-		return createMemoryStore();
-	}
-
+export function createMmkvStore(options: MmkvStoreOptions = {}): StateStore {
+	const port = openDurable(
+		() =>
+			// v4's factory: up to 0.2.0 this called the v3 `new MMKV()`, which v4 no
+			// longer exports as a value, so every device silently got memory.
+			mmkv
+				.require(peer => new Error(`${peer} is not installed`))
+				.createMMKV({
+					id: INSTANCE_ID,
+					// Caches is backup-excluded by platform design; see the note above.
+					...(currentPlatform() === 'ios'
+						? { path: 'Library/Caches/chipmobilesdk-notification' }
+						: {}),
+				}),
+		cause => {
+			channel.emit(DIAGNOSTIC_CODES.STATE_STORE_DEGRADED, 'warn');
+			options.onDegraded?.(cause);
+		},
+	);
 	return {
-		getString: key => instance.getString(key),
-		setString: (key, value) => instance.set(key, value),
-		delete: key => instance.remove(key),
-		clearAll: () => instance.clearAll(),
+		getString: key => port.getString(key),
+		setString: (key, value) => port.set(key, value),
+		delete: key => port.remove(key),
+		clearAll: () => port.clearAll(),
 		approximateBytes: () => {
 			let total = 0;
-			for (const key of instance.getAllKeys()) {
-				total += key.length + (instance.getString(key)?.length ?? 0);
+			for (const key of port.keys()) {
+				total += key.length + (port.getString(key)?.length ?? 0);
 			}
 			return total;
 		},
+		durable: port.durable,
 	};
 }

package/src/state/permission-history.ts

@@ -39,3 +39,28 @@ export function recordRequested(
 		{ at: now, key: target, requested: true },
 	]);
 }
+
+/** The device-wide key: a refusal is the user's answer to the app, not to one account. */
+const DEVICE = '#device';
+
+/** How many requests for `kind` the user has refused on this device. */
+export function denialCount(state: StateManager, kind: PermissionKind): number {
+	const target = key(kind, DEVICE);
+	return state.read().permissionHistory.find(entry => entry.key === target)?.denials ?? 0;
+}
+
+export function recordDenial(state: StateManager, kind: PermissionKind, now: number): void {
+	const target = key(kind, DEVICE);
+	const denials = denialCount(state, kind) + 1;
+	state.update('permissionHistory', current => [
+		...current.filter(entry => entry.key !== target),
+		{ at: now, key: target, requested: true, denials },
+	]);
+}
+
+/** Forgets refusals once the permission is seen granted: the next refusal starts over. */
+export function clearDenials(state: StateManager, kind: PermissionKind): void {
+	if (denialCount(state, kind) === 0) return;
+	const target = key(kind, DEVICE);
+	state.update('permissionHistory', current => current.filter(entry => entry.key !== target));
+}

package/src/state/record.ts

@@ -16,7 +16,23 @@ import type { AnchoringMode, RoutingPayload } from '../contract/notification';
 import type { CollectionHealth, StateHealth } from '../contract/diagnostics';
 import { DIAGNOSTIC_CODES, type DiagnosticCode } from '../contract/errors';
 
+/** The single record before 0.6.0; read once to migrate, then deleted. */
 const STATE_KEY = 'chipmobilesdk.notification.state';
+/**
+ * Since 0.6.0 each collection has its own key, plus one for the schema version and
+ * summaries, so recording one dedup entry writes the dedup ledger and nothing else
+ * (NOT-16). Before, every update serialized the whole record — the 500-entry dedup
+ * ledger included — synchronously on the JS thread.
+ */
+const META_KEY = `${STATE_KEY}:meta`;
+const COLLECTIONS: readonly CollectionName[] = [
+	'dedupLedger',
+	'interactionBuffer',
+	'migrationLedger',
+	'seriesLedger',
+	'permissionHistory',
+];
+const keyFor = (collection: CollectionName) => `${STATE_KEY}:${collection}`;
 
 /**
  * Bumped whenever the shape below changes. A mismatch discards and rebuilds —
@@ -35,6 +51,10 @@ export interface BufferedInteraction extends Timestamped {
 	readonly kind: 'tap' | 'action' | 'dismiss';
 	readonly notificationId: string;
 	readonly actionId?: string;
+	/**
+	 * Only ever present in a record written before 0.5: typed replies are no
+	 * longer persisted (interaction-buffer.ts).
+	 */
 	readonly inputText?: string;
 	/** The one content-bearing thing persisted. Evicted the moment it is delivered. */
 	readonly routing?: RoutingPayload;
@@ -76,6 +96,8 @@ export interface SeriesEntry extends Timestamped {
 export interface PermissionHistoryEntry extends Timestamped {
 	readonly key: string;
 	readonly requested: boolean;
+	/** Requests the user refused, so a permanent denial can be told apart (0.6.0). */
+	readonly denials?: number;
 }
 
 export interface StateRecord {
@@ -130,40 +152,77 @@ export class StateManager {
 	}
 
 	private load(): StateRecord {
-		const raw = this.store.getString(STATE_KEY);
-		if (raw === undefined) {
-			return emptyRecord();
-		}
-
 		try {
-			const parsed = JSON.parse(raw) as Partial<StateRecord>;
+			const meta = this.store.getString(META_KEY);
+			if (meta === undefined) {
+				return this.migrateLegacy();
+			}
+			const parsed = JSON.parse(meta) as Partial<StateRecord>;
 			if (parsed.schemaVersion !== STATE_SCHEMA_VERSION) {
 				return this.discardAndRebuild('schema-version-mismatch', {
 					found: parsed.schemaVersion,
 					expected: STATE_SCHEMA_VERSION,
 				});
 			}
-			return {
+			const record: Record<string, unknown> = {
 				schemaVersion: STATE_SCHEMA_VERSION,
-				dedupLedger: parsed.dedupLedger ?? [],
-				interactionBuffer: parsed.interactionBuffer ?? [],
-				migrationLedger: parsed.migrationLedger ?? [],
-				seriesLedger: parsed.seriesLedger ?? [],
-				permissionHistory: parsed.permissionHistory ?? [],
 				lastReconcileSummary: parsed.lastReconcileSummary,
 				lastMaintenanceSummary: parsed.lastMaintenanceSummary,
 			};
+			for (const collection of COLLECTIONS) {
+				const raw = this.store.getString(keyFor(collection));
+				const entries: unknown = raw === undefined ? [] : JSON.parse(raw);
+				if (!Array.isArray(entries)) {
+					return this.discardAndRebuild('unparseable', { collection });
+				}
+				record[collection] = entries;
+			}
+			return record as unknown as StateRecord;
 		} catch {
 			return this.discardAndRebuild('unparseable');
 		}
 	}
 
+	/** Reads the pre-0.6.0 single record, writes it out per collection, and drops it. */
+	private migrateLegacy(): StateRecord {
+		const raw = this.store.getString(STATE_KEY);
+		if (raw === undefined) {
+			const fresh = emptyRecord();
+			this.persistMeta(fresh);
+			return fresh;
+		}
+		const parsed = JSON.parse(raw) as Partial<StateRecord>;
+		if (parsed.schemaVersion !== STATE_SCHEMA_VERSION) {
+			return this.discardAndRebuild('schema-version-mismatch', {
+				found: parsed.schemaVersion,
+				expected: STATE_SCHEMA_VERSION,
+			});
+		}
+		this.record = {
+			schemaVersion: STATE_SCHEMA_VERSION,
+			dedupLedger: parsed.dedupLedger ?? [],
+			interactionBuffer: parsed.interactionBuffer ?? [],
+			migrationLedger: parsed.migrationLedger ?? [],
+			seriesLedger: parsed.seriesLedger ?? [],
+			permissionHistory: parsed.permissionHistory ?? [],
+			lastReconcileSummary: parsed.lastReconcileSummary,
+			lastMaintenanceSummary: parsed.lastMaintenanceSummary,
+		};
+		for (const collection of COLLECTIONS) {
+			this.persist(collection);
+		}
+		this.persistMeta(this.record);
+		this.store.delete(STATE_KEY);
+		return this.record;
+	}
+
 	private discardAndRebuild(
 		reason: string,
 		extra?: Readonly<Record<string, unknown>>,
 	): StateRecord {
 		this.rebuilt = true;
-		this.store.delete(STATE_KEY);
+		this.deleteAll();
+		this.persistMeta(emptyRecord());
 		this.emit({
 			code: DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT,
 			// Note what is actually lost, so the consequence is stated rather than implied.
@@ -172,10 +231,18 @@ export class StateManager {
 		return emptyRecord();
 	}
 
+	private deleteAll(): void {
+		this.store.delete(STATE_KEY);
+		this.store.delete(META_KEY);
+		for (const collection of COLLECTIONS) {
+			this.store.delete(keyFor(collection));
+		}
+	}
+
 	/** Never throws. A storage failure degrades the affected guarantee, nothing more. */
-	private persist(): void {
+	private write(key: string, value: unknown): void {
 		try {
-			this.store.setString(STATE_KEY, JSON.stringify(this.record));
+			this.store.setString(key, JSON.stringify(value));
 		} catch (error) {
 			this.emit({
 				code: DIAGNOSTIC_CODES.STATE_WRITE_FAILED,
@@ -184,6 +251,20 @@ export class StateManager {
 		}
 	}
 
+	/** Writes one collection, and only that one. */
+	private persist(collection: CollectionName): void {
+		this.write(keyFor(collection), this.record[collection]);
+	}
+
+	/** The schema version and summaries. Present whenever any collection is stored. */
+	private persistMeta(record: StateRecord = this.record): void {
+		this.write(META_KEY, {
+			schemaVersion: STATE_SCHEMA_VERSION,
+			lastReconcileSummary: record.lastReconcileSummary,
+			lastMaintenanceSummary: record.lastMaintenanceSummary,
+		});
+	}
+
 	read(): StateRecord {
 		return this.record;
 	}
@@ -194,7 +275,17 @@ export class StateManager {
 		mutate: (current: StateRecord[K]) => StateRecord[K],
 	): void {
 		const next = mutate(this.record[collection]);
-		const { kept, evicted, reason } = evict(next as readonly Timestamped[], collection, this.now());
+		const { kept, evicted, reason, overCap } = evict(
+			next as readonly Timestamped[],
+			collection,
+			this.now(),
+		);
+		if (overCap > 0) {
+			this.emit({
+				code: DIAGNOSTIC_CODES.STATE_CAP_EXCEEDED,
+				context: { collection, overCap, cap: COLLECTION_CAPS[collection].maxEntries },
+			});
+		}
 
 		if (evicted.length > 0) {
 			this.emit({
@@ -207,7 +298,7 @@ export class StateManager {
 		}
 
 		this.record = { ...this.record, [collection]: kept } as StateRecord;
-		this.persist();
+		this.persist(collection);
 	}
 
 	setSummary(
@@ -215,14 +306,15 @@ export class StateManager {
 		value: Readonly<Record<string, unknown>>,
 	): void {
 		this.record = { ...this.record, [key]: value };
-		this.persist();
+		this.persistMeta();
 	}
 
 	/** Clears everything. Public through `resetState()`. */
 	reset(): void {
 		this.record = emptyRecord();
 		this.rebuilt = false;
-		this.store.delete(STATE_KEY);
+		this.deleteAll();
+		this.persistMeta();
 	}
 
 	/**
@@ -240,7 +332,9 @@ export class StateManager {
 				e => !e.key.startsWith(`${ownerTag}:`),
 			),
 		};
-		this.persist();
+		this.persist('dedupLedger');
+		this.persist('interactionBuffer');
+		this.persist('permissionHistory');
 	}
 
 	health(): StateHealth {

package/src/state/store.ts

@@ -13,6 +13,8 @@ export interface StateStore {
 	clearAll(): void;
 	/** Approximate on-disk size, for the health report. */
 	approximateBytes(): number;
+	/** False when writes do not survive a restart (the memory fallback). */
+	readonly durable?: boolean;
 }
 
 /** In-memory store, used by tests and as the fallback when MMKV is unavailable. */
@@ -36,5 +38,6 @@ export function createMemoryStore(): StateStore {
 			}
 			return total;
 		},
+		durable: false,
 	};
 }

package/src/testing/fake-engine.ts

@@ -83,6 +83,11 @@ export interface FakeControls {
 
 	/** Queues an interaction that arrived before any handler existed. */
 	emitInteraction(event: InteractionEvent): void;
+	/**
+	 * An interaction while the app is not in front: live `subscribeToInteractions`
+	 * handlers get it, otherwise the registered background handler does.
+	 */
+	emitBackgroundInteraction(event: InteractionEvent): Promise<void>;
 	queueInitialInteraction(event: InteractionEvent): void;
 
 	/** The labels a declared channel currently carries, so a label refresh is assertable. */
@@ -119,6 +124,7 @@ export function createFakeEngine(options: FakeEngineOptions = {}): FakeEngine {
 	let listeners: ((event: InteractionEvent) => void)[] = [];
 	let deliveryListeners: ((event: DeliveryEvent) => void)[] = [];
 	let backgroundHandler: ((event: DeliveryEvent) => Promise<void>) | undefined;
+	let backgroundInteractionHandler: ((event: InteractionEvent) => Promise<void>) | undefined;
 	let initialInteraction: InteractionEvent | undefined;
 
 	let currentTime = options.now ?? Date.UTC(2026, 0, 1, 12, 0, 0);
@@ -313,8 +319,9 @@ export function createFakeEngine(options: FakeEngineOptions = {}): FakeEngine {
 			};
 		},
 
-		registerBackgroundDeliveryHandler(handler) {
+		registerBackgroundDeliveryHandler(handler, onInteraction) {
 			backgroundHandler = handler;
+			backgroundInteractionHandler = onInteraction;
 		},
 
 		hasBackgroundDeliveryHandler() {
@@ -385,6 +392,15 @@ export function createFakeEngine(options: FakeEngineOptions = {}): FakeEngine {
 			}
 		},
 
+		async emitBackgroundInteraction(event) {
+			const background: InteractionEvent = { ...event, appState: 'background' };
+			if (listeners.length > 0) {
+				for (const listener of [...listeners]) listener(background);
+				return;
+			}
+			await backgroundInteractionHandler?.(background);
+		},
+
 		emitInteraction(event) {
 			for (const listener of listeners) {
 				listener(event);