@chipmobilesdk/rn-notification 0.1.0

package/src/state/record.ts

@@ -0,0 +1,246 @@
+/**
+ * The persisted state record.
+ *
+ * Six collections, holding only what the platform will not tell us. No
+ * notification content, no push token, no desired set. The interaction buffer
+ * is the sole content-bearing exception, and it evicts on delivery.
+ *
+ * Corrupt or incompatible state is discarded and rebuilt rather than blocking:
+ * everything already scheduled lives in the OS and is unaffected, which is what
+ * makes discarding safe rather than destructive.
+ */
+
+import type { StateStore } from './store';
+import { evict, COLLECTION_CAPS, type CollectionName, type Timestamped } from './caps';
+import type { AnchoringMode, RoutingPayload } from '../contract/notification';
+import type { CollectionHealth, StateHealth } from '../contract/diagnostics';
+import { DIAGNOSTIC_CODES, type DiagnosticCode } from '../contract/errors';
+
+const STATE_KEY = 'chipmobilesdk.notification.state';
+
+/**
+ * Bumped whenever the shape below changes. A mismatch discards and rebuilds —
+ * never a migration, because none of this data is worth migrating and all of it
+ * is reconstructible.
+ */
+export const STATE_SCHEMA_VERSION = 1;
+
+export interface DedupEntry extends Timestamped {
+	readonly dedupId: string;
+	readonly ownerTag?: string;
+}
+
+export interface BufferedInteraction extends Timestamped {
+	readonly id: string;
+	readonly kind: 'tap' | 'action' | 'dismiss';
+	readonly notificationId: string;
+	readonly actionId?: string;
+	readonly inputText?: string;
+	/** The one content-bearing thing persisted. Evicted the moment it is delivered. */
+	readonly routing?: RoutingPayload;
+	readonly ownerTag?: string;
+}
+
+export interface MigrationEntry extends Timestamped {
+	readonly toneId: string;
+	readonly appliedVersion: number;
+	readonly channelId: string;
+	readonly retired: boolean;
+}
+
+export interface SeriesEntry extends Timestamped {
+	readonly seriesId: string;
+	readonly anchoring: AnchoringMode;
+	readonly expandedThrough: number;
+	readonly emittedCount: number;
+	readonly exhausted: boolean;
+}
+
+export interface PermissionHistoryEntry extends Timestamped {
+	readonly key: string;
+	readonly requested: boolean;
+}
+
+export interface StateRecord {
+	readonly schemaVersion: number;
+	readonly dedupLedger: readonly DedupEntry[];
+	readonly interactionBuffer: readonly BufferedInteraction[];
+	readonly migrationLedger: readonly MigrationEntry[];
+	readonly seriesLedger: readonly SeriesEntry[];
+	readonly permissionHistory: readonly PermissionHistoryEntry[];
+	readonly lastReconcileSummary?: Readonly<Record<string, unknown>>;
+	readonly lastMaintenanceSummary?: Readonly<Record<string, unknown>>;
+}
+
+export function emptyRecord(): StateRecord {
+	return {
+		schemaVersion: STATE_SCHEMA_VERSION,
+		dedupLedger: [],
+		interactionBuffer: [],
+		migrationLedger: [],
+		seriesLedger: [],
+		permissionHistory: [],
+	};
+}
+
+export interface StateEvent {
+	readonly code: DiagnosticCode;
+	readonly context?: Readonly<Record<string, unknown>>;
+}
+
+export interface StateManagerOptions {
+	readonly store: StateStore;
+	readonly now: () => number;
+	readonly emit?: (event: StateEvent) => void;
+}
+
+/**
+ * Owns the record's lifecycle. Reads are synchronous and cheap; writes are
+ * best-effort and never propagate a failure to the caller's operation.
+ */
+export class StateManager {
+	private record: StateRecord;
+	private rebuilt = false;
+	private readonly store: StateStore;
+	private readonly now: () => number;
+	private readonly emit: (event: StateEvent) => void;
+
+	constructor(options: StateManagerOptions) {
+		this.store = options.store;
+		this.now = options.now;
+		this.emit = options.emit ?? (() => {});
+		this.record = this.load();
+	}
+
+	private load(): StateRecord {
+		const raw = this.store.getString(STATE_KEY);
+		if (raw === undefined) {
+			return emptyRecord();
+		}
+
+		try {
+			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,
+				});
+			}
+			return {
+				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,
+			};
+		} catch {
+			return this.discardAndRebuild('unparseable');
+		}
+	}
+
+	private discardAndRebuild(
+		reason: string,
+		extra?: Readonly<Record<string, unknown>>,
+	): StateRecord {
+		this.rebuilt = true;
+		this.store.delete(STATE_KEY);
+		this.emit({
+			code: DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT,
+			// Note what is actually lost, so the consequence is stated rather than implied.
+			context: { reason, lost: ['dedupLedger', 'interactionBuffer'], ...extra },
+		});
+		return emptyRecord();
+	}
+
+	/** Never throws. A storage failure degrades the affected guarantee, nothing more. */
+	private persist(): void {
+		try {
+			this.store.setString(STATE_KEY, JSON.stringify(this.record));
+		} catch (error) {
+			this.emit({
+				code: DIAGNOSTIC_CODES.STATE_WRITE_FAILED,
+				context: { reason: error instanceof Error ? error.name : 'unknown' },
+			});
+		}
+	}
+
+	read(): StateRecord {
+		return this.record;
+	}
+
+	/** Applies a change, evicts the touched collection, and persists. */
+	update<K extends CollectionName>(
+		collection: K,
+		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());
+
+		if (evicted.length > 0) {
+			this.emit({
+				code:
+					collection === 'interactionBuffer'
+						? DIAGNOSTIC_CODES.INTERACTION_BUFFER_EVICTED
+						: DIAGNOSTIC_CODES.STATE_CAP_EVICTED,
+				context: { collection, evicted: evicted.length, reason },
+			});
+		}
+
+		this.record = { ...this.record, [collection]: kept } as StateRecord;
+		this.persist();
+	}
+
+	setSummary(key: 'lastReconcileSummary' | 'lastMaintenanceSummary', value: Readonly<Record<string, unknown>>): void {
+		this.record = { ...this.record, [key]: value };
+		this.persist();
+	}
+
+	/** Clears everything. Public through `resetState()`. */
+	reset(): void {
+		this.record = emptyRecord();
+		this.rebuilt = false;
+		this.store.delete(STATE_KEY);
+	}
+
+	/**
+	 * Clears one owner tag's entries, leaving every other tag untouched.
+	 *
+	 * Collections without an owner tag are left alone: a migration ledger and a
+	 * series ledger describe the device, not an account.
+	 */
+	clearOwner(ownerTag: string): void {
+		this.record = {
+			...this.record,
+			dedupLedger: this.record.dedupLedger.filter(e => e.ownerTag !== ownerTag),
+			interactionBuffer: this.record.interactionBuffer.filter(e => e.ownerTag !== ownerTag),
+			permissionHistory: this.record.permissionHistory.filter(
+				e => !e.key.startsWith(`${ownerTag}:`),
+			),
+		};
+		this.persist();
+	}
+
+	health(): StateHealth {
+		const collections: CollectionHealth[] = (
+			Object.keys(COLLECTION_CAPS) as CollectionName[]
+		).map(name => {
+			const entries = this.record[name] as readonly Timestamped[];
+			return {
+				name,
+				size: entries.length,
+				cap: COLLECTION_CAPS[name].maxEntries,
+				oldestEntryAt: entries.length > 0 ? Math.min(...entries.map(e => e.at)) : undefined,
+			};
+		});
+
+		return {
+			readable: true,
+			rebuilt: this.rebuilt,
+			collections,
+			approximateBytes: this.store.approximateBytes(),
+		};
+	}
+}

package/src/state/reset.ts

@@ -0,0 +1,41 @@
+/**
+ * Public state reset and per-owner clearing.
+ *
+ * These are the only two ways a consumer may touch the persisted record. The
+ * record itself is unreachable — a consumer can discard state, but can never
+ * read or write it.
+ */
+
+import type { StateManager } from './record';
+
+export interface ResetOutcome {
+	readonly clearedCollections: readonly string[];
+}
+
+/** Discards the entire record. Nothing already scheduled with the OS is affected. */
+export function resetState(state: StateManager): ResetOutcome {
+	state.reset();
+	return {
+		clearedCollections: [
+			'dedupLedger',
+			'interactionBuffer',
+			'migrationLedger',
+			'seriesLedger',
+			'permissionHistory',
+		],
+	};
+}
+
+/**
+ * Clears one owner tag's entries on sign-out.
+ *
+ * Deliberately narrower than a full reset: the migration and series ledgers
+ * describe the device rather than an account, so signing one account out must
+ * not discard channel migration history that every account depends on.
+ */
+export function clearOwner(state: StateManager, ownerTag: string): ResetOutcome {
+	state.clearOwner(ownerTag);
+	return {
+		clearedCollections: ['dedupLedger', 'interactionBuffer', 'permissionHistory'],
+	};
+}

package/src/state/series-ledger.ts

@@ -0,0 +1,84 @@
+/**
+ * The recurrence series ledger.
+ *
+ * What makes automatic maintenance possible without a desired set from the
+ * consumer: the package remembers which series it owns, how far each has been
+ * expanded, and how many occurrences a count-limited series has already
+ * emitted. None of that is derivable from the platform's pending set, which
+ * knows only about individual notifications.
+ *
+ * It also defines what maintenance is allowed to touch. An occurrence belongs
+ * to a series in this ledger, so cancelling it is within scope; anything else
+ * is a directly-scheduled notification the package does not own.
+ */
+
+import type { StateManager, SeriesEntry } from './record';
+import type { RecurrenceRule } from '../contract/recurrence';
+import type { AnchoringMode } from '../contract/notification';
+
+export interface SeriesRecord {
+	readonly seriesId: string;
+	readonly anchoring: AnchoringMode;
+	readonly expandedThrough: number;
+	readonly emittedCount: number;
+	readonly exhausted: boolean;
+	readonly at: number;
+}
+
+export function readSeries(state: StateManager, seriesId: string): SeriesRecord | undefined {
+	return state.read().seriesLedger.find(entry => entry.seriesId === seriesId);
+}
+
+export function listSeries(state: StateManager): readonly SeriesRecord[] {
+	return state.read().seriesLedger;
+}
+
+/** Records or updates a series. Replaces in place so a re-registration cannot duplicate. */
+export function upsertSeries(
+	state: StateManager,
+	rule: RecurrenceRule,
+	update: { readonly expandedThrough: number; readonly emittedCount: number; readonly exhausted: boolean },
+	now: number,
+): void {
+	const entry: SeriesEntry = {
+		at: now,
+		seriesId: rule.id,
+		anchoring: rule.anchoring ?? 'wallClock',
+		expandedThrough: update.expandedThrough,
+		emittedCount: update.emittedCount,
+		exhausted: update.exhausted,
+	};
+
+	state.update('seriesLedger', current => [
+		...current.filter(existing => existing.seriesId !== rule.id),
+		entry,
+	]);
+}
+
+export function removeSeries(state: StateManager, seriesId: string): void {
+	state.update('seriesLedger', current => current.filter(entry => entry.seriesId !== seriesId));
+}
+
+/**
+ * Identifiers the package owns.
+ *
+ * An occurrence identifier is `<seriesId>#<instant>`, so ownership is decided
+ * by prefix rather than by an enumeration the ledger would have to keep in sync
+ * with the device. That keeps the check correct even for occurrences scheduled
+ * before the app last restarted.
+ */
+export function ownsIdentifier(state: StateManager, id: string): boolean {
+	const separator = id.lastIndexOf('#');
+	if (separator === -1) return false;
+
+	const seriesId = id.slice(0, separator);
+	return state.read().seriesLedger.some(entry => entry.seriesId === seriesId);
+}
+
+/** Every occurrence identifier currently attributable to a tracked series. */
+export function ownedIdentifiers(
+	state: StateManager,
+	pendingIds: readonly string[],
+): ReadonlySet<string> {
+	return new Set(pendingIds.filter(id => ownsIdentifier(state, id)));
+}

package/src/state/store.ts

@@ -0,0 +1,40 @@
+/**
+ * The storage port behind the persisted state record.
+ *
+ * Kept as a port so the pure state logic is testable with no native module,
+ * and so MMKV stays confined to one file. This is internal — a consumer can
+ * reset or clear state, but can never read or write the record directly.
+ */
+
+export interface StateStore {
+	getString(key: string): string | undefined;
+	setString(key: string, value: string): void;
+	delete(key: string): void;
+	clearAll(): void;
+	/** Approximate on-disk size, for the health report. */
+	approximateBytes(): number;
+}
+
+/** In-memory store, used by tests and as the fallback when MMKV is unavailable. */
+export function createMemoryStore(): StateStore {
+	const map = new Map<string, string>();
+	return {
+		getString: key => map.get(key),
+		setString: (key, value) => {
+			map.set(key, value);
+		},
+		delete: key => {
+			map.delete(key);
+		},
+		clearAll: () => {
+			map.clear();
+		},
+		approximateBytes: () => {
+			let total = 0;
+			for (const [key, value] of map) {
+				total += key.length + value.length;
+			}
+			return total;
+		},
+	};
+}

package/src/testing/conformance/index.ts

@@ -0,0 +1,194 @@
+/**
+ * The shared conformance suite.
+ *
+ * The executable definition of what an engine adapter must do. Run against the
+ * real engine and against the fake, it is what backs the claim that testing
+ * with fakes proves something about production — if the two ever diverge, this
+ * is where it shows up rather than on a user's device.
+ *
+ * Written as a plain async function rather than a Jest suite so it can be
+ * driven from the demo app on a real device as well as from continuous
+ * integration.
+ */
+
+import type { NotificationEngineAdapter } from '../../engine/adapter';
+import type { ResolvedTone } from '../../contract/channel';
+
+const TONE: ResolvedTone = {
+	toneId: 'conformance',
+	version: 1,
+	android: {
+		channelId: 'conformance.v1',
+		importance: 'default',
+		vibration: false,
+		badge: false,
+		bypassDnd: false,
+	},
+	ios: { categoryId: 'conformance', interruptionLevel: 'active', badge: false },
+};
+
+export interface ConformanceCheck {
+	readonly name: string;
+	readonly passed: boolean;
+	readonly detail?: string;
+}
+
+export interface ConformanceReport {
+	readonly adapter: string;
+	readonly checks: readonly ConformanceCheck[];
+	readonly passed: number;
+	readonly failed: number;
+}
+
+export interface ConformanceOptions {
+	/** Injected so the suite never depends on wall-clock time. */
+	readonly now?: () => number;
+	/** Identifier prefix, so a device run cannot collide with real notifications. */
+	readonly prefix?: string;
+}
+
+export async function runConformanceSuite(
+	adapter: NotificationEngineAdapter,
+	options: ConformanceOptions = {},
+): Promise<ConformanceReport> {
+	const now = options.now ?? (() => Date.now());
+	const prefix = options.prefix ?? 'conformance';
+	const checks: ConformanceCheck[] = [];
+
+	const check = async (name: string, run: () => Promise<boolean | string>): Promise<void> => {
+		try {
+			const outcome = await run();
+			checks.push(
+				outcome === true
+					? { name, passed: true }
+					: { name, passed: false, detail: typeof outcome === 'string' ? outcome : 'returned false' },
+			);
+		} catch (error) {
+			checks.push({
+				name,
+				passed: false,
+				detail: error instanceof Error ? error.message : String(error),
+			});
+		}
+	};
+
+	const id = (suffix: string) => `${prefix}:${suffix}`;
+	const at = now() + 3_600_000;
+
+	const schedule = (suffix: string, overrides: Record<string, unknown> = {}) =>
+		adapter.schedule({
+			request: {
+				id: id(suffix),
+				content: { title: `Conformance ${suffix}`, body: 'Suite entry' },
+				tone: 'conformance',
+				moment: { at },
+				...overrides,
+			},
+			resolvedAt: at,
+			tone: TONE,
+			approximate: false,
+		});
+
+	// Start clean so a previous run cannot mask a failure.
+	await adapter.cancelAll();
+
+	await check('reports its capabilities', async () => {
+		const capabilities = await adapter.getCapabilities();
+		return (
+			capabilities.pendingCeiling > 0 ||
+			`pendingCeiling must be positive, got ${capabilities.pendingCeiling}`
+		);
+	});
+
+	await check('schedules and reads back an entry', async () => {
+		await schedule('a');
+		const pending = await adapter.getPending();
+		return pending.some(entry => entry.id === id('a')) || 'scheduled entry was not returned';
+	});
+
+	await check('returns enough detail to diff, not merely to count', async () => {
+		const [entry] = (await adapter.getPending()).filter(e => e.id === id('a'));
+		if (entry === undefined) return 'entry missing';
+
+		return (
+			(entry.content.title.length > 0 && entry.resolvedAt > 0 && entry.anchoring !== undefined) ||
+			'entry lacked content, instant, or anchoring mode'
+		);
+	});
+
+	await check('replaces rather than duplicates on the same identifier', async () => {
+		await schedule('a', { content: { title: 'Replaced', body: 'Newer' } });
+		const matching = (await adapter.getPending()).filter(entry => entry.id === id('a'));
+		return matching.length === 1 || `expected exactly 1 entry, found ${matching.length}`;
+	});
+
+	await check('round-trips a routing payload unchanged', async () => {
+		await schedule('routing', { routing: { screen: 'task', nested: { deep: true } } });
+		const entry = (await adapter.getPending()).find(e => e.id === id('routing'));
+		return (
+			JSON.stringify(entry?.routing) === JSON.stringify({ screen: 'task', nested: { deep: true } }) ||
+			`routing payload changed: ${JSON.stringify(entry?.routing)}`
+		);
+	});
+
+	await check('preserves the anchoring mode it was given', async () => {
+		await schedule('absolute', { moment: { at, anchoring: 'absolute' } });
+		const entry = (await adapter.getPending()).find(e => e.id === id('absolute'));
+		return entry?.anchoring === 'absolute' || `expected absolute, got ${entry?.anchoring}`;
+	});
+
+	await check('cancels one entry without touching the others', async () => {
+		const before = (await adapter.getPending()).length;
+		await adapter.cancel(id('a'));
+		const after = await adapter.getPending();
+
+		return (
+			(after.length === before - 1 && !after.some(entry => entry.id === id('a'))) ||
+			'cancel removed the wrong number of entries'
+		);
+	});
+
+	await check('cancelling something absent is harmless', async () => {
+		await adapter.cancel(id('never-existed'));
+		return true;
+	});
+
+	await check('reports permission state without throwing', async () => {
+		const state = await adapter.getPermission('display');
+		return (
+			['notAsked', 'granted', 'denied', 'permanentlyDenied', 'provisional', 'notRequired'].includes(
+				state,
+			) || `unexpected permission state: ${state}`
+		);
+	});
+
+	await check('reports background restrictions, admitting unknown', async () => {
+		const report = await adapter.getRestrictions();
+		return (
+			['unrestricted', 'restricted', 'unknown'].includes(report.batteryOptimization) ||
+			`unexpected restriction status: ${report.batteryOptimization}`
+		);
+	});
+
+	await check('returns pending entries in ascending delivery order', async () => {
+		const pending = await adapter.getPending();
+		const instants = pending.map(entry => entry.resolvedAt);
+		const sorted = [...instants].sort((x, y) => x - y);
+		return JSON.stringify(instants) === JSON.stringify(sorted) || 'entries were not time-ordered';
+	});
+
+	await check('cancelAll leaves nothing behind', async () => {
+		await adapter.cancelAll();
+		const pending = await adapter.getPending();
+		return pending.length === 0 || `${pending.length} entries survived cancelAll`;
+	});
+
+	const passed = checks.filter(entry => entry.passed).length;
+
+	return {
+		adapter: adapter.name,
+		checks,
+		passed,
+		failed: checks.length - passed,
+	};
+}