@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/maintenance/permission-refresh.ts

@@ -1,41 +1,39 @@
-/**
- * The permission re-read maintenance step.
- *
- * The user can change permission in system settings while the app is
- * backgrounded, and the platform does not tell anyone. Re-reading on foreground
- * is the only way a consumer's interface avoids showing a stale answer.
- *
- * Runs last (order 30): permission state does not affect what the earlier steps
- * expand or re-anchor, and reading it after they have run means the report
- * reflects the device as the cycle leaves it.
- */
-
-import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
-import type { Permissions } from '../permission';
-
-export const PERMISSION_REFRESH_ORDER = 30;
-
-export interface PermissionRefreshDependencies {
-	readonly permissions: Permissions;
-}
-
-export function createPermissionRefreshStep(
-	deps: PermissionRefreshDependencies,
-): MaintenanceStep {
-	return {
-		name: 'permission-refresh',
-		order: PERMISSION_REFRESH_ORDER,
-
-		async run(_context: MaintenanceContext): Promise<StepOutcome> {
-			const { changed } = await deps.permissions.refresh();
-
-			return {
-				// Reading permission is not a platform mutation, so it never counts
-				// toward the zero-operation guarantee.
-				operationCount: 0,
-				permissionChanged: changed,
-				cancelledIds: [],
-			};
-		},
-	};
-}
+/**
+ * The permission re-read maintenance step.
+ *
+ * The user can change permission in system settings while the app is
+ * backgrounded, and the platform does not tell anyone. Re-reading on foreground
+ * is the only way a consumer's interface avoids showing a stale answer.
+ *
+ * Runs last (order 30): permission state does not affect what the earlier steps
+ * expand or re-anchor, and reading it after they have run means the report
+ * reflects the device as the cycle leaves it.
+ */
+
+import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
+import type { Permissions } from '../permission';
+
+export const PERMISSION_REFRESH_ORDER = 30;
+
+export interface PermissionRefreshDependencies {
+	readonly permissions: Permissions;
+}
+
+export function createPermissionRefreshStep(deps: PermissionRefreshDependencies): MaintenanceStep {
+	return {
+		name: 'permission-refresh',
+		order: PERMISSION_REFRESH_ORDER,
+
+		async run(_context: MaintenanceContext): Promise<StepOutcome> {
+			const { changed } = await deps.permissions.refresh();
+
+			return {
+				// Reading permission is not a platform mutation, so it never counts
+				// toward the zero-operation guarantee.
+				operationCount: 0,
+				permissionChanged: changed,
+				cancelledIds: [],
+			};
+		},
+	};
+}

package/src/maintenance/reanchor.ts

@@ -1,101 +1,101 @@
-/**
- * The re-anchoring maintenance step.
- *
- * Registers itself with the maintenance registry rather than being wired into
- * a fixed sequence, which is what keeps scheduling independent of
- * reconciliation, recurrence, and permissions despite all four contributing a
- * step.
- *
- * Runs early (order 10) because verification compares firing instants: if
- * verification ran first it would compare against instants re-anchoring is
- * about to rewrite, and report discrepancies that do not exist.
- */
-
-import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import type { ResolvedTone } from '../contract/channel';
-import { planReAnchor, type TimeZoneReader } from '../schedule/anchor';
-import { createScheduleWriter } from '../schedule/writer';
-
-export interface ReAnchorStepDependencies {
-	readonly engine: NotificationEngineAdapter;
-	readonly timeZone: TimeZoneReader;
-	readonly resolveTone: (toneId: string) => ResolvedTone | undefined;
-	readonly canScheduleExactly: () => boolean;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export const RE_ANCHOR_ORDER = 10;
-
-export function createReAnchorStep(deps: ReAnchorStepDependencies): MaintenanceStep {
-	// Through the shared writer so a repeating alert's stop marker moves with it;
-	// written directly, the marker kept the old instant and cut the alert short
-	// or let it run past its bound.
-	const writer = createScheduleWriter(deps.engine);
-
-	return {
-		name: 'reanchor',
-		order: RE_ANCHOR_ORDER,
-
-		async run(_context: MaintenanceContext): Promise<StepOutcome> {
-			const zone = deps.timeZone();
-			const pending = await deps.engine.getPending();
-			const plan = planReAnchor(pending, zone);
-
-			// The no-change path costs one comparison per entry and issues zero
-			// platform operations. That is what makes re-anchoring idempotent.
-			if (plan.rewrites.length === 0) {
-				return { operationCount: 0, reAnchored: 0, timeZoneChanged: false };
-			}
-
-			deps.emit?.(
-				'REANCHOR',
-				`Device time zone changed from ${plan.fromZone ?? 'unknown'} to ${plan.toZone}; re-anchoring ${plan.rewrites.length} wall-clock notification(s).`,
-				{ from: plan.fromZone, to: plan.toZone, count: plan.rewrites.length },
-			);
-
-			let operationCount = 0;
-
-			for (const { entry, resolvedAt } of plan.rewrites) {
-				const tone = deps.resolveTone(entry.tone);
-				if (tone === undefined) {
-					// A tone that no longer exists means this entry belongs to a
-					// configuration the app has since dropped. Leaving it alone is
-					// correct: re-anchoring must never repair, only preserve.
-					continue;
-				}
-
-				await writer.write({
-					request: {
-						id: entry.id,
-						content: entry.content,
-						tone: entry.tone,
-						moment: { at: resolvedAt, anchoring: 'wallClock' },
-						routing: entry.routing,
-						actions: entry.actions,
-						ownerTag: entry.ownerTag,
-						groupTag: entry.groupTag,
-					},
-					resolvedAt,
-					tone,
-					// Re-anchored against the zone the device is in now — this is the
-					// value that stops the entry being reported as stale next time.
-					anchoringGeneration: zone,
-					approximate: !deps.canScheduleExactly(),
-					seriesId: entry.seriesId,
-					pushCreated: entry.pushCreated,
-				});
-				operationCount += 1;
-			}
-
-			return {
-				operationCount,
-				reAnchored: operationCount,
-				timeZoneChanged: true,
-				// Re-anchoring replaces in place and cancels nothing, so it can never
-				// touch a notification outside what it was handed.
-				cancelledIds: [],
-			};
-		},
-	};
-}
+/**
+ * The re-anchoring maintenance step.
+ *
+ * Registers itself with the maintenance registry rather than being wired into
+ * a fixed sequence, which is what keeps scheduling independent of
+ * reconciliation, recurrence, and permissions despite all four contributing a
+ * step.
+ *
+ * Runs early (order 10) because verification compares firing instants: if
+ * verification ran first it would compare against instants re-anchoring is
+ * about to rewrite, and report discrepancies that do not exist.
+ */
+
+import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { ResolvedTone } from '../contract/channel';
+import { planReAnchor, type TimeZoneReader } from '../schedule/anchor';
+import { createScheduleWriter } from '../schedule/writer';
+
+export interface ReAnchorStepDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly timeZone: TimeZoneReader;
+	readonly resolveTone: (toneId: string) => ResolvedTone | undefined;
+	readonly canScheduleExactly: () => boolean;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export const RE_ANCHOR_ORDER = 10;
+
+export function createReAnchorStep(deps: ReAnchorStepDependencies): MaintenanceStep {
+	// Through the shared writer so a repeating alert's stop marker moves with it;
+	// written directly, the marker kept the old instant and cut the alert short
+	// or let it run past its bound.
+	const writer = createScheduleWriter(deps.engine);
+
+	return {
+		name: 'reanchor',
+		order: RE_ANCHOR_ORDER,
+
+		async run(_context: MaintenanceContext): Promise<StepOutcome> {
+			const zone = deps.timeZone();
+			const pending = await deps.engine.getPending();
+			const plan = planReAnchor(pending, zone);
+
+			// The no-change path costs one comparison per entry and issues zero
+			// platform operations. That is what makes re-anchoring idempotent.
+			if (plan.rewrites.length === 0) {
+				return { operationCount: 0, reAnchored: 0, timeZoneChanged: false };
+			}
+
+			deps.emit?.(
+				'REANCHOR',
+				`Device time zone changed from ${plan.fromZone ?? 'unknown'} to ${plan.toZone}; re-anchoring ${plan.rewrites.length} wall-clock notification(s).`,
+				{ from: plan.fromZone, to: plan.toZone, count: plan.rewrites.length },
+			);
+
+			let operationCount = 0;
+
+			for (const { entry, resolvedAt } of plan.rewrites) {
+				const tone = deps.resolveTone(entry.tone);
+				if (tone === undefined) {
+					// A tone that no longer exists means this entry belongs to a
+					// configuration the app has since dropped. Leaving it alone is
+					// correct: re-anchoring must never repair, only preserve.
+					continue;
+				}
+
+				await writer.write({
+					request: {
+						id: entry.id,
+						content: entry.content,
+						tone: entry.tone,
+						moment: { at: resolvedAt, anchoring: 'wallClock' },
+						routing: entry.routing,
+						actions: entry.actions,
+						ownerTag: entry.ownerTag,
+						groupTag: entry.groupTag,
+					},
+					resolvedAt,
+					tone,
+					// Re-anchored against the zone the device is in now — this is the
+					// value that stops the entry being reported as stale next time.
+					anchoringGeneration: zone,
+					approximate: !deps.canScheduleExactly(),
+					seriesId: entry.seriesId,
+					pushCreated: entry.pushCreated,
+				});
+				operationCount += 1;
+			}
+
+			return {
+				operationCount,
+				reAnchored: operationCount,
+				timeZoneChanged: true,
+				// Re-anchoring replaces in place and cancels nothing, so it can never
+				// touch a notification outside what it was handed.
+				cancelledIds: [],
+			};
+		},
+	};
+}

package/src/maintenance/toggle.ts

@@ -1,64 +1,66 @@
-/**
- * The automatic-maintenance switch.
- *
- * A package that acts on its own must offer a way to stop it — and a consumer
- * that takes control must not lose a feature as the price. Disabling automatic
- * maintenance leaves every operation explicitly invocable through
- * `runMaintenance()`, producing identical device state.
- */
-
-import type { MaintenanceResult } from '../contract/reconcile';
-import type { MaintenanceContext, MaintenanceRegistry, MaintenanceTrigger } from './cycle';
-
-export interface MaintenanceControllerOptions {
-	readonly registry: MaintenanceRegistry;
-	readonly now: () => number;
-	/**
-	 * Identifiers the package owns at the start of a cycle. May read the device,
-	 * since ownership is decided per pending occurrence, not per series.
-	 */
-	readonly ownedIds: () => ReadonlySet<string> | Promise<ReadonlySet<string>>;
-	readonly enabled?: boolean;
-}
-
-export class MaintenanceController {
-	private enabled: boolean;
-	private readonly registry: MaintenanceRegistry;
-	private readonly now: () => number;
-	private readonly ownedIds: () => ReadonlySet<string> | Promise<ReadonlySet<string>>;
-
-	constructor(options: MaintenanceControllerOptions) {
-		this.registry = options.registry;
-		this.now = options.now;
-		this.ownedIds = options.ownedIds;
-		this.enabled = options.enabled ?? true;
-	}
-
-	get isEnabled(): boolean {
-		return this.enabled;
-	}
-
-	setEnabled(enabled: boolean): void {
-		this.enabled = enabled;
-	}
-
-	/** Called by lifecycle observers. A no-op when automatic maintenance is off. */
-	async runAutomatic(trigger: Exclude<MaintenanceTrigger, 'explicit'>): Promise<MaintenanceResult | undefined> {
-		if (!this.enabled) return undefined;
-		return this.execute(trigger);
-	}
-
-	/** Always runs, regardless of the switch. This is what preserves capability parity. */
-	async runExplicit(): Promise<MaintenanceResult> {
-		return this.execute('explicit');
-	}
-
-	private async execute(trigger: MaintenanceTrigger): Promise<MaintenanceResult> {
-		const context: MaintenanceContext = {
-			trigger,
-			now: this.now(),
-			ownedIds: await this.ownedIds(),
-		};
-		return this.registry.run(context);
-	}
-}
+/**
+ * The automatic-maintenance switch.
+ *
+ * A package that acts on its own must offer a way to stop it — and a consumer
+ * that takes control must not lose a feature as the price. Disabling automatic
+ * maintenance leaves every operation explicitly invocable through
+ * `runMaintenance()`, producing identical device state.
+ */
+
+import type { MaintenanceResult } from '../contract/reconcile';
+import type { MaintenanceContext, MaintenanceRegistry, MaintenanceTrigger } from './cycle';
+
+export interface MaintenanceControllerOptions {
+	readonly registry: MaintenanceRegistry;
+	readonly now: () => number;
+	/**
+	 * Identifiers the package owns at the start of a cycle. May read the device,
+	 * since ownership is decided per pending occurrence, not per series.
+	 */
+	readonly ownedIds: () => ReadonlySet<string> | Promise<ReadonlySet<string>>;
+	readonly enabled?: boolean;
+}
+
+export class MaintenanceController {
+	private enabled: boolean;
+	private readonly registry: MaintenanceRegistry;
+	private readonly now: () => number;
+	private readonly ownedIds: () => ReadonlySet<string> | Promise<ReadonlySet<string>>;
+
+	constructor(options: MaintenanceControllerOptions) {
+		this.registry = options.registry;
+		this.now = options.now;
+		this.ownedIds = options.ownedIds;
+		this.enabled = options.enabled ?? true;
+	}
+
+	get isEnabled(): boolean {
+		return this.enabled;
+	}
+
+	setEnabled(enabled: boolean): void {
+		this.enabled = enabled;
+	}
+
+	/** Called by lifecycle observers. A no-op when automatic maintenance is off. */
+	async runAutomatic(
+		trigger: Exclude<MaintenanceTrigger, 'explicit'>,
+	): Promise<MaintenanceResult | undefined> {
+		if (!this.enabled) return undefined;
+		return this.execute(trigger);
+	}
+
+	/** Always runs, regardless of the switch. This is what preserves capability parity. */
+	async runExplicit(): Promise<MaintenanceResult> {
+		return this.execute('explicit');
+	}
+
+	private async execute(trigger: MaintenanceTrigger): Promise<MaintenanceResult> {
+		const context: MaintenanceContext = {
+			trigger,
+			now: this.now(),
+			ownedIds: await this.ownedIds(),
+		};
+		return this.registry.run(context);
+	}
+}

package/src/maintenance/verify.ts

@@ -1,83 +1,83 @@
-/**
- * Pending-set verification.
- *
- * Engine boot restoration coverage varies by manufacturer, so after a restart
- * the device may hold fewer notifications than the package expects. This step
- * notices that.
- *
- * It **detects and reports only**. It never re-registers, cancels, or repairs
- * anything — the package deliberately does not persist a desired set, so it
- * cannot tell a restoration gap from an intentional consumer change. Guessing
- * would mean either resurrecting notifications the user cancelled or deleting
- * ones they still want. Repair is consumer-invoked reconciliation.
- *
- * Runs at order 20, after re-anchoring (order 10): re-anchoring rewrites firing
- * instants, and verifying first would compare against instants that are about
- * to change.
- */
-
-import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import type { PendingDiscrepancy } from '../contract/reconcile';
-import { DIAGNOSTIC_CODES } from '../contract/errors';
-
-export const VERIFY_ORDER = 20;
-
-export interface VerifyStepDependencies {
-	readonly engine: NotificationEngineAdapter;
-	/**
-	 * Identifiers the package expects the device to hold — the union of series
-	 * occurrences and the last reconciliation's result. Absent expectations mean
-	 * nothing to verify, which is different from expecting nothing.
-	 */
-	readonly expectedIds: () => ReadonlySet<string> | undefined;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export function createVerifyStep(deps: VerifyStepDependencies): MaintenanceStep {
-	return {
-		name: 'verify',
-		order: VERIFY_ORDER,
-
-		async run(context: MaintenanceContext): Promise<StepOutcome> {
-			const expected = deps.expectedIds();
-
-			// No recorded expectation is not the same as expecting an empty device.
-			// Reporting every pending entry as "unrecognized" on a fresh install
-			// would be noise, not a finding.
-			if (expected === undefined) {
-				return { operationCount: 0 };
-			}
-
-			const pending = await deps.engine.getPending();
-			const actual = new Set(pending.map(entry => entry.id));
-
-			const missing = [...expected].filter(id => !actual.has(id)).sort();
-			const unrecognized = [...actual].filter(id => !expected.has(id)).sort();
-
-			if (missing.length === 0 && unrecognized.length === 0) {
-				return { operationCount: 0 };
-			}
-
-			const discrepancy: PendingDiscrepancy = {
-				missing,
-				unrecognized,
-				detectedAt: context.now,
-			};
-
-			deps.emit?.(
-				DIAGNOSTIC_CODES.PENDING_SET_DISCREPANCY,
-				`Pending set differs from expectation: ${missing.length} expected but absent, ${unrecognized.length} present but unrecognized. ` +
-					'Reported only — run reconciliation to repair, since the package cannot distinguish a restoration gap from an intentional change.',
-				{ missing: missing.length, unrecognized: unrecognized.length },
-			);
-
-			return {
-				operationCount: 0,
-				discrepancy,
-				// Verification repairs nothing, so it cancels nothing.
-				cancelledIds: [],
-			};
-		},
-	};
-}
+/**
+ * Pending-set verification.
+ *
+ * Engine boot restoration coverage varies by manufacturer, so after a restart
+ * the device may hold fewer notifications than the package expects. This step
+ * notices that.
+ *
+ * It **detects and reports only**. It never re-registers, cancels, or repairs
+ * anything — the package deliberately does not persist a desired set, so it
+ * cannot tell a restoration gap from an intentional consumer change. Guessing
+ * would mean either resurrecting notifications the user cancelled or deleting
+ * ones they still want. Repair is consumer-invoked reconciliation.
+ *
+ * Runs at order 20, after re-anchoring (order 10): re-anchoring rewrites firing
+ * instants, and verifying first would compare against instants that are about
+ * to change.
+ */
+
+import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { PendingDiscrepancy } from '../contract/reconcile';
+import { DIAGNOSTIC_CODES } from '../contract/errors';
+
+export const VERIFY_ORDER = 20;
+
+export interface VerifyStepDependencies {
+	readonly engine: NotificationEngineAdapter;
+	/**
+	 * Identifiers the package expects the device to hold — the union of series
+	 * occurrences and the last reconciliation's result. Absent expectations mean
+	 * nothing to verify, which is different from expecting nothing.
+	 */
+	readonly expectedIds: () => ReadonlySet<string> | undefined;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export function createVerifyStep(deps: VerifyStepDependencies): MaintenanceStep {
+	return {
+		name: 'verify',
+		order: VERIFY_ORDER,
+
+		async run(context: MaintenanceContext): Promise<StepOutcome> {
+			const expected = deps.expectedIds();
+
+			// No recorded expectation is not the same as expecting an empty device.
+			// Reporting every pending entry as "unrecognized" on a fresh install
+			// would be noise, not a finding.
+			if (expected === undefined) {
+				return { operationCount: 0 };
+			}
+
+			const pending = await deps.engine.getPending();
+			const actual = new Set(pending.map(entry => entry.id));
+
+			const missing = [...expected].filter(id => !actual.has(id)).sort();
+			const unrecognized = [...actual].filter(id => !expected.has(id)).sort();
+
+			if (missing.length === 0 && unrecognized.length === 0) {
+				return { operationCount: 0 };
+			}
+
+			const discrepancy: PendingDiscrepancy = {
+				missing,
+				unrecognized,
+				detectedAt: context.now,
+			};
+
+			deps.emit?.(
+				DIAGNOSTIC_CODES.PENDING_SET_DISCREPANCY,
+				`Pending set differs from expectation: ${missing.length} expected but absent, ${unrecognized.length} present but unrecognized. ` +
+					'Reported only — run reconciliation to repair, since the package cannot distinguish a restoration gap from an intentional change.',
+				{ missing: missing.length, unrecognized: unrecognized.length },
+			);
+
+			return {
+				operationCount: 0,
+				discrepancy,
+				// Verification repairs nothing, so it cancels nothing.
+				cancelledIds: [],
+			};
+		},
+	};
+}