@chipmobilesdk/rn-notification 0.5.0 → 0.7.0

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/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/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 —
@@ -80,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 {
@@ -134,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.
@@ -176,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,
@@ -188,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;
 	}
@@ -198,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({
@@ -211,7 +298,7 @@ export class StateManager {
 		}
 
 		this.record = { ...this.record, [collection]: kept } as StateRecord;
-		this.persist();
+		this.persist(collection);
 	}
 
 	setSummary(
@@ -219,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();
 	}
 
 	/**
@@ -244,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/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);