@chipmobilesdk/rn-notification 0.3.0 → 0.4.1

package/src/state/record.ts

@@ -1,258 +1,266 @@
-/**
- * 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;
-	/**
-	 * Fingerprint of the labels last pushed to the platform.
-	 *
-	 * Optional because records written before labels were carried at all have
-	 * none — and their absence is exactly right: an unknown fingerprint refreshes
-	 * once, which is the one-time correction every existing device needs, since
-	 * every existing channel currently carries the tone id as its name.
-	 *
-	 * A fingerprint rather than the labels themselves. Persisted state holds no
-	 * consumer text, and a hash answers the only question asked of it.
-	 */
-	readonly labelFingerprint?: string;
-}
-
-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(),
-		};
-	}
-}
+/**
+ * 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;
+	/**
+	 * Fingerprint of the labels last pushed to the platform.
+	 *
+	 * Optional because records written before labels were carried at all have
+	 * none — and their absence is exactly right: an unknown fingerprint refreshes
+	 * once, which is the one-time correction every existing device needs, since
+	 * every existing channel currently carries the tone id as its name.
+	 *
+	 * A fingerprint rather than the labels themselves. Persisted state holds no
+	 * consumer text, and a hash answers the only question asked of it.
+	 */
+	readonly labelFingerprint?: string;
+}
+
+export interface SeriesEntry extends Timestamped {
+	readonly seriesId: string;
+	readonly anchoring: AnchoringMode;
+	readonly expandedThrough: number;
+	readonly emittedCount: number;
+	readonly exhausted: boolean;
+	/**
+	 * Calendar key of the latest occurrence counted into `emittedCount`. Absent in
+	 * entries written before 0.4.0; recovered from the device on next expansion.
+	 */
+	readonly lastEmittedKey?: string;
+}
+
+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

@@ -1,41 +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'],
-	};
-}
+/**
+ * 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'],
+	};
+}