@chipmobilesdk/rn-notification 0.3.0 → 0.4.1

package/src/schedule/writer.ts

@@ -0,0 +1,55 @@
+/**
+ * The one door every consumer notification goes through to reach the engine.
+ *
+ * Scheduler, reconciler, recurrence, re-anchoring and channel re-homing all
+ * write notifications. Each used to call `engine.schedule` itself, and the
+ * guarantees attached to a write — a repeating alert gets its stop marker, and
+ * that marker moves when the notification moves — existed only on the paths
+ * that remembered them. A recurring alarm never stopped, and a re-anchored one
+ * stopped at the old instant.
+ *
+ * Validation stays with each caller, because each has its own failure policy:
+ * the scheduler throws, reconciliation rejects one entry and carries on, and
+ * recurrence validates its template once at registration.
+ */
+
+import type { NotificationEngineAdapter, EngineScheduleRequest } from '../engine/adapter';
+import { createStopPlacement } from '../repeat/place';
+
+export interface ScheduleWriter {
+	/** Writes one notification and brings its stop marker in line with it. */
+	write(input: EngineScheduleRequest): Promise<void>;
+	/** Cancels one notification and the marker guarding it. */
+	cancel(id: string): Promise<void>;
+	/** Drops the marker for a notification already cancelled some other way. */
+	releaseStop(targetId: string): Promise<void>;
+	/**
+	 * Platform slots consumer notifications can actually use: stop markers hold
+	 * real capacity, so the usable ceiling is the platform's minus theirs.
+	 */
+	capacity(): Promise<number>;
+}
+
+export function createScheduleWriter(engine: NotificationEngineAdapter): ScheduleWriter {
+	const stops = createStopPlacement(engine);
+
+	return {
+		async write(input) {
+			await engine.schedule(input);
+			await stops.sync(input.request.id, input.tone, input.resolvedAt);
+		},
+
+		async cancel(id) {
+			await engine.cancel(id);
+			await stops.release(id);
+		},
+
+		releaseStop: targetId => stops.release(targetId),
+
+		async capacity() {
+			const capabilities = await engine.getCapabilities();
+			const markerCost = (await engine.listRepeatStops()).length;
+			return Math.max(0, capabilities.pendingCeiling - markerCost);
+		},
+	};
+}

package/src/state/caps.ts

@@ -1,71 +1,71 @@
-/**
- * Caps and eviction for the persisted collections.
- *
- * No collection may grow without bound. Eviction is oldest-first and always
- * observable — a silent eviction would turn a bounded guarantee into an
- * unexplained one.
- */
-
-/** Every persisted collection with a size or age bound. */
-export const COLLECTION_CAPS = {
-	dedupLedger: { maxEntries: 500, retentionMs: 24 * 60 * 60 * 1000 },
-	interactionBuffer: { maxEntries: 50, retentionMs: 7 * 24 * 60 * 60 * 1000 },
-	migrationLedger: { maxEntries: 20, retentionMs: Number.POSITIVE_INFINITY },
-	seriesLedger: { maxEntries: 32, retentionMs: Number.POSITIVE_INFINITY },
-	permissionHistory: { maxEntries: 64, retentionMs: Number.POSITIVE_INFINITY },
-} as const;
-
-export type CollectionName = keyof typeof COLLECTION_CAPS;
-
-/** Anything stored with a timestamp, which is everything that can age out. */
-export interface Timestamped {
-	readonly at: number;
-}
-
-export interface EvictionOutcome<T> {
-	readonly kept: readonly T[];
-	readonly evicted: readonly T[];
-	readonly reason: 'none' | 'cap' | 'retention' | 'cap+retention';
-}
-
-/**
- * Applies retention first, then the size cap.
- *
- * Order matters: expiring stale entries before trimming means a burst of new
- * entries does not evict fresh ones while stale ones sit protected by
- * recency ordering.
- */
-export function evict<T extends Timestamped>(
-	entries: readonly T[],
-	collection: CollectionName,
-	now: number,
-): EvictionOutcome<T> {
-	const { maxEntries, retentionMs } = COLLECTION_CAPS[collection];
-
-	const expired: T[] = [];
-	const live: T[] = [];
-	for (const entry of entries) {
-		if (Number.isFinite(retentionMs) && now - entry.at > retentionMs) {
-			expired.push(entry);
-		} else {
-			live.push(entry);
-		}
-	}
-
-	// 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;
-
-	let reason: EvictionOutcome<T>['reason'] = 'none';
-	if (expired.length > 0 && overflow.length > 0) {
-		reason = 'cap+retention';
-	} else if (overflow.length > 0) {
-		reason = 'cap';
-	} else if (expired.length > 0) {
-		reason = 'retention';
-	}
-
-	return { kept, evicted: [...expired, ...overflow], reason };
-}
+/**
+ * Caps and eviction for the persisted collections.
+ *
+ * No collection may grow without bound. Eviction is oldest-first and always
+ * observable — a silent eviction would turn a bounded guarantee into an
+ * unexplained one.
+ */
+
+/** Every persisted collection with a size or age bound. */
+export const COLLECTION_CAPS = {
+	dedupLedger: { maxEntries: 500, retentionMs: 24 * 60 * 60 * 1000 },
+	interactionBuffer: { maxEntries: 50, retentionMs: 7 * 24 * 60 * 60 * 1000 },
+	migrationLedger: { maxEntries: 20, retentionMs: Number.POSITIVE_INFINITY },
+	seriesLedger: { maxEntries: 32, retentionMs: Number.POSITIVE_INFINITY },
+	permissionHistory: { maxEntries: 64, retentionMs: Number.POSITIVE_INFINITY },
+} as const;
+
+export type CollectionName = keyof typeof COLLECTION_CAPS;
+
+/** Anything stored with a timestamp, which is everything that can age out. */
+export interface Timestamped {
+	readonly at: number;
+}
+
+export interface EvictionOutcome<T> {
+	readonly kept: readonly T[];
+	readonly evicted: readonly T[];
+	readonly reason: 'none' | 'cap' | 'retention' | 'cap+retention';
+}
+
+/**
+ * Applies retention first, then the size cap.
+ *
+ * Order matters: expiring stale entries before trimming means a burst of new
+ * entries does not evict fresh ones while stale ones sit protected by
+ * recency ordering.
+ */
+export function evict<T extends Timestamped>(
+	entries: readonly T[],
+	collection: CollectionName,
+	now: number,
+): EvictionOutcome<T> {
+	const { maxEntries, retentionMs } = COLLECTION_CAPS[collection];
+
+	const expired: T[] = [];
+	const live: T[] = [];
+	for (const entry of entries) {
+		if (Number.isFinite(retentionMs) && now - entry.at > retentionMs) {
+			expired.push(entry);
+		} else {
+			live.push(entry);
+		}
+	}
+
+	// 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;
+
+	let reason: EvictionOutcome<T>['reason'] = 'none';
+	if (expired.length > 0 && overflow.length > 0) {
+		reason = 'cap+retention';
+	} else if (overflow.length > 0) {
+		reason = 'cap';
+	} else if (expired.length > 0) {
+		reason = 'retention';
+	}
+
+	return { kept, evicted: [...expired, ...overflow], reason };
+}

package/src/state/dedup-ledger.ts

@@ -1,35 +1,35 @@
-/**
- * The push deduplication ledger.
- *
- * Providers redeliver. The redelivery typically arrives in a **fresh process**,
- * which is precisely why this is persisted rather than held in memory — an
- * in-memory set would forget exactly when it matters.
- *
- * Bounded by cap and retention. A payload redelivered after its entry has aged
- * out is treated as new: that is the documented bound of the guarantee, not a
- * defect.
- */
-
-import type { StateManager } from './record';
-
-export function isDuplicate(state: StateManager, dedupId: string): boolean {
-	return state.read().dedupLedger.some(entry => entry.dedupId === dedupId);
-}
-
-/**
- * Records a payload as seen.
- *
- * Returns true when it was already known, so a caller can branch on the same
- * read that records it rather than checking twice.
- */
-export function recordSeen(
-	state: StateManager,
-	dedupId: string,
-	now: number,
-	ownerTag?: string,
-): boolean {
-	if (isDuplicate(state, dedupId)) return true;
-
-	state.update('dedupLedger', current => [...current, { at: now, dedupId, ownerTag }]);
-	return false;
-}
+/**
+ * The push deduplication ledger.
+ *
+ * Providers redeliver. The redelivery typically arrives in a **fresh process**,
+ * which is precisely why this is persisted rather than held in memory — an
+ * in-memory set would forget exactly when it matters.
+ *
+ * Bounded by cap and retention. A payload redelivered after its entry has aged
+ * out is treated as new: that is the documented bound of the guarantee, not a
+ * defect.
+ */
+
+import type { StateManager } from './record';
+
+export function isDuplicate(state: StateManager, dedupId: string): boolean {
+	return state.read().dedupLedger.some(entry => entry.dedupId === dedupId);
+}
+
+/**
+ * Records a payload as seen.
+ *
+ * Returns true when it was already known, so a caller can branch on the same
+ * read that records it rather than checking twice.
+ */
+export function recordSeen(
+	state: StateManager,
+	dedupId: string,
+	now: number,
+	ownerTag?: string,
+): boolean {
+	if (isDuplicate(state, dedupId)) return true;
+
+	state.update('dedupLedger', current => [...current, { at: now, dedupId, ownerTag }]);
+	return false;
+}

package/src/state/interaction-buffer.ts

@@ -1,73 +1,73 @@
-/**
- * The durable interaction buffer.
- *
- * A cold-start tap arrives before any handler exists. Holding it in memory
- * would be enough if the process always survived — but the process is exactly
- * what does not survive a cold start, so the buffer is persisted.
- *
- * This is the one content-bearing thing the package stores: an interaction
- * 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.
- */
-
-import type { StateManager, BufferedInteraction } from './record';
-import type { InteractionEvent } from '../contract/interaction';
-
-/** 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}`;
-}
-
-export function buffer(state: StateManager, event: InteractionEvent): void {
-	const id = bufferedId(event);
-
-	state.update('interactionBuffer', current => {
-		if (current.some(entry => entry.id === id)) return current;
-
-		const entry: BufferedInteraction = {
-			at: event.occurredAt,
-			id,
-			kind: event.kind,
-			notificationId: event.notificationId,
-			actionId: event.actionId,
-			inputText: event.inputText,
-			routing: event.routing,
-			ownerTag: event.ownerTag,
-		};
-		return [...current, entry];
-	});
-}
-
-/**
- * Takes every buffered event in occurrence order and clears them.
- *
- * Draining and clearing together is deliberate: delivering an event twice is
- * worse than the alternative, because a consumer that acts on an interaction
- * (marking a task done, sending a reply) would act twice.
- */
-export function drain(state: StateManager): readonly InteractionEvent[] {
-	const buffered = [...state.read().interactionBuffer].sort((a, b) => a.at - b.at);
-
-	if (buffered.length === 0) return [];
-
-	state.update('interactionBuffer', () => []);
-
-	return buffered.map(entry => ({
-		kind: entry.kind,
-		notificationId: entry.notificationId,
-		actionId: entry.actionId,
-		inputText: entry.inputText,
-		routing: entry.routing,
-		ownerTag: entry.ownerTag,
-		occurredAt: entry.at,
-		// The state it arrived in is gone; what matters to a consumer is that it
-		// waited, which is what `wasBuffered` says.
-		appState: 'coldStart' as const,
-		wasBuffered: true,
-	}));
-}
-
-export function bufferedCount(state: StateManager): number {
-	return state.read().interactionBuffer.length;
-}
+/**
+ * The durable interaction buffer.
+ *
+ * A cold-start tap arrives before any handler exists. Holding it in memory
+ * would be enough if the process always survived — but the process is exactly
+ * what does not survive a cold start, so the buffer is persisted.
+ *
+ * This is the one content-bearing thing the package stores: an interaction
+ * 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.
+ */
+
+import type { StateManager, BufferedInteraction } from './record';
+import type { InteractionEvent } from '../contract/interaction';
+
+/** 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}`;
+}
+
+export function buffer(state: StateManager, event: InteractionEvent): void {
+	const id = bufferedId(event);
+
+	state.update('interactionBuffer', current => {
+		if (current.some(entry => entry.id === id)) return current;
+
+		const entry: BufferedInteraction = {
+			at: event.occurredAt,
+			id,
+			kind: event.kind,
+			notificationId: event.notificationId,
+			actionId: event.actionId,
+			inputText: event.inputText,
+			routing: event.routing,
+			ownerTag: event.ownerTag,
+		};
+		return [...current, entry];
+	});
+}
+
+/**
+ * Takes every buffered event in occurrence order and clears them.
+ *
+ * Draining and clearing together is deliberate: delivering an event twice is
+ * worse than the alternative, because a consumer that acts on an interaction
+ * (marking a task done, sending a reply) would act twice.
+ */
+export function drain(state: StateManager): readonly InteractionEvent[] {
+	const buffered = [...state.read().interactionBuffer].sort((a, b) => a.at - b.at);
+
+	if (buffered.length === 0) return [];
+
+	state.update('interactionBuffer', () => []);
+
+	return buffered.map(entry => ({
+		kind: entry.kind,
+		notificationId: entry.notificationId,
+		actionId: entry.actionId,
+		inputText: entry.inputText,
+		routing: entry.routing,
+		ownerTag: entry.ownerTag,
+		occurredAt: entry.at,
+		// The state it arrived in is gone; what matters to a consumer is that it
+		// waited, which is what `wasBuffered` says.
+		appState: 'coldStart' as const,
+		wasBuffered: true,
+	}));
+}
+
+export function bufferedCount(state: StateManager): number {
+	return state.read().interactionBuffer.length;
+}

package/src/state/mmkv-store.ts

@@ -1,75 +1,75 @@
-/**
- * MMKV-backed state store.
- *
- * Every MMKV import is confined to this file, so the rest of the package stays
- * testable without a native module.
- *
- * Backup exclusion is achieved by *where* the data lives rather than by setting
- * a file attribute: on iOS the instance is rooted under `Library/Caches`, which
- * the platform excludes from iCloud and iTunes backup by design. The OS may
- * purge that directory under storage pressure — acceptable here precisely
- * because discarding and rebuilding this record is already a specified,
- * non-blocking condition.
- *
- * On Android, backup exclusion is declared in the consuming app's
- * `data_extraction_rules.xml` and `full_backup_content`, documented in the
- * README. It is the app's manifest, so it is the app's declaration to make.
- */
-
-import { Platform } from 'react-native';
-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[];
-}
-
-/**
- * Creates the persistent store, falling back to memory when MMKV is absent.
- *
- * 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.
- */
-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();
-	}
-
-	return {
-		getString: key => instance.getString(key),
-		setString: (key, value) => instance.set(key, value),
-		delete: key => instance.remove(key),
-		clearAll: () => instance.clearAll(),
-		approximateBytes: () => {
-			let total = 0;
-			for (const key of instance.getAllKeys()) {
-				total += key.length + (instance.getString(key)?.length ?? 0);
-			}
-			return total;
-		},
-	};
-}
+/**
+ * MMKV-backed state store.
+ *
+ * Every MMKV import is confined to this file, so the rest of the package stays
+ * testable without a native module.
+ *
+ * Backup exclusion is achieved by *where* the data lives rather than by setting
+ * a file attribute: on iOS the instance is rooted under `Library/Caches`, which
+ * the platform excludes from iCloud and iTunes backup by design. The OS may
+ * purge that directory under storage pressure — acceptable here precisely
+ * because discarding and rebuilding this record is already a specified,
+ * non-blocking condition.
+ *
+ * On Android, backup exclusion is declared in the consuming app's
+ * `data_extraction_rules.xml` and `full_backup_content`, documented in the
+ * README. It is the app's manifest, so it is the app's declaration to make.
+ */
+
+import { Platform } from 'react-native';
+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[];
+}
+
+/**
+ * Creates the persistent store, falling back to memory when MMKV is absent.
+ *
+ * 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.
+ */
+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();
+	}
+
+	return {
+		getString: key => instance.getString(key),
+		setString: (key, value) => instance.set(key, value),
+		delete: key => instance.remove(key),
+		clearAll: () => instance.clearAll(),
+		approximateBytes: () => {
+			let total = 0;
+			for (const key of instance.getAllKeys()) {
+				total += key.length + (instance.getString(key)?.length ?? 0);
+			}
+			return total;
+		},
+	};
+}

package/src/state/permission-history.ts

@@ -1,41 +1,41 @@
-/**
- * Permission-request history.
- *
- * The platform cannot tell you whether you have already asked. On both
- * platforms a second request after a denial is silently a no-op, so an app that
- * does not remember will keep "asking" and keep appearing to be refused.
- *
- * Keyed by owner tag so a multi-account device can clear one account's history
- * on sign-out without forgetting what it asked the others.
- */
-
-import type { StateManager } from './record';
-import type { PermissionKind } from '../contract/permission';
-
-function key(kind: PermissionKind, ownerTag?: string): string {
-	return `${ownerTag ?? '*'}:${kind}`;
-}
-
-export function hasRequested(
-	state: StateManager,
-	kind: PermissionKind,
-	ownerTag?: string,
-): boolean {
-	const target = key(kind, ownerTag);
-	return state.read().permissionHistory.some(entry => entry.key === target && entry.requested);
-}
-
-export function recordRequested(
-	state: StateManager,
-	kind: PermissionKind,
-	now: number,
-	ownerTag?: string,
-): void {
-	const target = key(kind, ownerTag);
-	if (hasRequested(state, kind, ownerTag)) return;
-
-	state.update('permissionHistory', current => [
-		...current.filter(entry => entry.key !== target),
-		{ at: now, key: target, requested: true },
-	]);
-}
+/**
+ * Permission-request history.
+ *
+ * The platform cannot tell you whether you have already asked. On both
+ * platforms a second request after a denial is silently a no-op, so an app that
+ * does not remember will keep "asking" and keep appearing to be refused.
+ *
+ * Keyed by owner tag so a multi-account device can clear one account's history
+ * on sign-out without forgetting what it asked the others.
+ */
+
+import type { StateManager } from './record';
+import type { PermissionKind } from '../contract/permission';
+
+function key(kind: PermissionKind, ownerTag?: string): string {
+	return `${ownerTag ?? '*'}:${kind}`;
+}
+
+export function hasRequested(
+	state: StateManager,
+	kind: PermissionKind,
+	ownerTag?: string,
+): boolean {
+	const target = key(kind, ownerTag);
+	return state.read().permissionHistory.some(entry => entry.key === target && entry.requested);
+}
+
+export function recordRequested(
+	state: StateManager,
+	kind: PermissionKind,
+	now: number,
+	ownerTag?: string,
+): void {
+	const target = key(kind, ownerTag);
+	if (hasRequested(state, kind, ownerTag)) return;
+
+	state.update('permissionHistory', current => [
+		...current.filter(entry => entry.key !== target),
+		{ at: now, key: target, requested: true },
+	]);
+}