@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/maintenance/window-refresh.ts

@@ -1,64 +1,64 @@
-/**
- * The window-refresh maintenance step.
- *
- * Runs at order 15 — after re-anchoring (10) so it expands against corrected
- * instants, before verification (20) so verification sees the refreshed set
- * rather than reporting occurrences the refresh was about to add.
- *
- * This step is the reason automatic maintenance exists at all: only the package
- * knows when a series' horizon has moved, and it can act on that without ever
- * needing a desired set from the consumer.
- */
-
-import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
-import type { RecurrenceRule } from '../contract/recurrence';
-import type { Recurrence } from '../recurrence';
-
-export const WINDOW_REFRESH_ORDER = 15;
-
-export interface WindowRefreshDependencies {
-	readonly recurrence: Recurrence;
-	/**
-	 * Rules the consumer has registered, supplied as a lookup rather than stored.
-	 *
-	 * The ledger records what the package expanded; the rule itself belongs to
-	 * the consumer, because persisting a rule would mean persisting its content
-	 * template — and FR-096a forbids the package holding notification content.
-	 */
-	readonly registeredRules: () => readonly RecurrenceRule[];
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export function createWindowRefreshStep(deps: WindowRefreshDependencies): MaintenanceStep {
-	return {
-		name: 'window-refresh',
-		order: WINDOW_REFRESH_ORDER,
-
-		async run(_context: MaintenanceContext): Promise<StepOutcome> {
-			const rules = deps.registeredRules();
-			if (rules.length === 0) {
-				return { operationCount: 0, windowRefreshed: false };
-			}
-
-			let scheduled = 0;
-			const cancelled: string[] = [];
-
-			for (const rule of rules) {
-				const result = await deps.recurrence.refreshSeries(rule);
-				scheduled += result.scheduled;
-				cancelled.push(...(result.cancelled ?? []));
-			}
-
-			return {
-				operationCount: scheduled + cancelled.length,
-				occurrencesScheduled: scheduled,
-				// A refresh that found nothing to add still ran; reporting it as
-				// refreshed distinguishes "nothing due" from "step never executed".
-				windowRefreshed: true,
-				// Only stale occurrences of series the package owns; reported so the
-				// registry's scope guard checks them rather than taking it on trust.
-				cancelledIds: cancelled,
-			};
-		},
-	};
-}
+/**
+ * The window-refresh maintenance step.
+ *
+ * Runs at order 15 — after re-anchoring (10) so it expands against corrected
+ * instants, before verification (20) so verification sees the refreshed set
+ * rather than reporting occurrences the refresh was about to add.
+ *
+ * This step is the reason automatic maintenance exists at all: only the package
+ * knows when a series' horizon has moved, and it can act on that without ever
+ * needing a desired set from the consumer.
+ */
+
+import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
+import type { RecurrenceRule } from '../contract/recurrence';
+import type { Recurrence } from '../recurrence';
+
+export const WINDOW_REFRESH_ORDER = 15;
+
+export interface WindowRefreshDependencies {
+	readonly recurrence: Recurrence;
+	/**
+	 * Rules the consumer has registered, supplied as a lookup rather than stored.
+	 *
+	 * The ledger records what the package expanded; the rule itself belongs to
+	 * the consumer, because persisting a rule would mean persisting its content
+	 * template — and FR-096a forbids the package holding notification content.
+	 */
+	readonly registeredRules: () => readonly RecurrenceRule[];
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export function createWindowRefreshStep(deps: WindowRefreshDependencies): MaintenanceStep {
+	return {
+		name: 'window-refresh',
+		order: WINDOW_REFRESH_ORDER,
+
+		async run(_context: MaintenanceContext): Promise<StepOutcome> {
+			const rules = deps.registeredRules();
+			if (rules.length === 0) {
+				return { operationCount: 0, windowRefreshed: false };
+			}
+
+			let scheduled = 0;
+			const cancelled: string[] = [];
+
+			for (const rule of rules) {
+				const result = await deps.recurrence.refreshSeries(rule);
+				scheduled += result.scheduled;
+				cancelled.push(...(result.cancelled ?? []));
+			}
+
+			return {
+				operationCount: scheduled + cancelled.length,
+				occurrencesScheduled: scheduled,
+				// A refresh that found nothing to add still ran; reporting it as
+				// refreshed distinguishes "nothing due" from "step never executed".
+				windowRefreshed: true,
+				// Only stale occurrences of series the package owns; reported so the
+				// registry's scope guard checks them rather than taking it on trust.
+				cancelledIds: cancelled,
+			};
+		},
+	};
+}

package/src/permission/index.ts

@@ -1,183 +1,183 @@
-/**
- * Permission coordination.
- *
- * Two rules shape everything here. Reading state never prompts, so the consumer
- * decides when the user is asked — a prompt at the wrong moment is a permanent
- * denial. And a refusal never fails the caller's business operation: the user's
- * actual work completes, and the lost capability is reported separately.
- */
-
-import type {
-	PermissionKind,
-	PermissionReport,
-	PermissionState,
-	RestrictionReport,
-} from '../contract/permission';
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import type { StateManager } from '../state/record';
-import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
-import { capabilityFor, normalizeState, type PlatformInfo } from './state';
-import { hasRequested, recordRequested } from '../state/permission-history';
-
-export interface PermissionDependencies {
-	readonly engine: NotificationEngineAdapter;
-	readonly state: StateManager;
-	readonly platform: PlatformInfo;
-	readonly now: () => number;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export type PermissionChangeHandler = (report: PermissionReport) => void;
-
-export function createPermissions(deps: PermissionDependencies) {
-	const emit = deps.emit ?? (() => {});
-	let listeners: PermissionChangeHandler[] = [];
-	let lastReport: PermissionReport | undefined;
-
-	const read = async (): Promise<PermissionReport> => {
-		// Never prompts. This is what lets a consumer decide the moment to ask.
-		const [display, exactAlarm] = await Promise.all([
-			deps.engine.getPermission('display'),
-			deps.engine.getPermission('exactAlarm'),
-		]);
-
-		return {
-			display: normalizeState('display', display, deps.platform),
-			exactAlarm: normalizeState('exactAlarm', exactAlarm, deps.platform),
-			readAt: deps.now(),
-		};
-	};
-
-	const notifyIfChanged = (report: PermissionReport): boolean => {
-		const changed =
-			lastReport === undefined ||
-			lastReport.display !== report.display ||
-			lastReport.exactAlarm !== report.exactAlarm;
-
-		lastReport = report;
-		if (!changed) return false;
-
-		for (const listener of listeners) {
-			try {
-				listener(report);
-			} catch {
-				// A consumer's handler must never break permission reading.
-			}
-		}
-		return true;
-	};
-
-	const request = async (kind: PermissionKind, ownerTag?: string): Promise<PermissionState> => {
-		const capability = capabilityFor(kind, deps.platform);
-
-		// Requesting something the platform version does not have is a no-op that
-		// shows no dialog, rather than a refusal.
-		if (!capability.supported) {
-			return 'notRequired';
-		}
-
-		recordRequested(deps.state, kind, deps.now(), ownerTag);
-
-		const raw = await deps.engine.requestPermission(kind);
-		const result = normalizeState(kind, raw, deps.platform);
-
-		if (result === 'denied' || result === 'permanentlyDenied') {
-			emit(
-				kind === 'display'
-					? result === 'permanentlyDenied'
-						? DIAGNOSTIC_CODES.DISPLAY_PERMISSION_PERMANENT
-						: DIAGNOSTIC_CODES.DISPLAY_PERMISSION_DENIED
-					: DIAGNOSTIC_CODES.EXACT_ALARM_UNAVAILABLE,
-				kind === 'display'
-					? 'Display permission was refused. The caller\'s operation still succeeded; notifications will not be shown until this is granted.'
-					: 'Exact-alarm capability is unavailable. Notifications are still scheduled, in approximate mode, and may be delivered late.',
-				{ kind, state: result },
-			);
-		}
-
-		notifyIfChanged(await read());
-		return result;
-	};
-
-	return {
-		/** Reads every permission state without triggering any dialog. */
-		async getPermissions(): Promise<PermissionReport> {
-			const report = await read();
-			notifyIfChanged(report);
-			return report;
-		},
-
-		/** Requested independently — an app may need one and not the other. */
-		requestDisplayPermission(ownerTag?: string): Promise<PermissionState> {
-			return request('display', ownerTag);
-		},
-
-		requestExactAlarmPermission(ownerTag?: string): Promise<PermissionState> {
-			return request('exactAlarm', ownerTag);
-		},
-
-		/** Whether the package has ever asked — the platform cannot answer this. */
-		hasEverRequested(kind: PermissionKind, ownerTag?: string): boolean {
-			return hasRequested(deps.state, kind, ownerTag);
-		},
-
-		/**
-		 * Opens the settings screen for one specific permission.
-		 *
-		 * Telling a user to "find it in settings" is how you lose them, so a
-		 * platform with no reachable screen is an error rather than a silent no-op.
-		 */
-		async openSettings(kind: PermissionKind): Promise<void> {
-			if (!capabilityFor(kind, deps.platform).supported) {
-				throw new NotificationError(
-					DIAGNOSTIC_CODES.SETTINGS_UNAVAILABLE,
-					`No settings screen exists for ${kind} on this platform version.`,
-					{ kind, os: deps.platform.os, apiLevel: deps.platform.apiLevel },
-				);
-			}
-			await deps.engine.openSettings(kind);
-		},
-
-		onPermissionChange(handler: PermissionChangeHandler): () => void {
-			listeners.push(handler);
-			return () => {
-				listeners = listeners.filter(l => l !== handler);
-			};
-		},
-
-		/**
-		 * Manufacturer background restrictions, reported for information only.
-		 *
-		 * `unknown` is a first-class answer: some vendors stop apps in ways with no
-		 * detection API, and guessing would be worse than admitting it. The package
-		 * changes none of these settings on the user's behalf.
-		 */
-		async getBackgroundRestrictions(): Promise<RestrictionReport> {
-			const report = await deps.engine.getRestrictions();
-
-			if (report.batteryOptimization === 'restricted' || report.autoStart === 'restricted') {
-				emit(
-					DIAGNOSTIC_CODES.BACKGROUND_RESTRICTED,
-					'The device applies a manufacturer background restriction. Notifications may be delayed or suppressed.',
-					{ battery: report.batteryOptimization, autoStart: report.autoStart },
-				);
-			} else if (report.batteryOptimization === 'unknown' || report.autoStart === 'unknown') {
-				emit(
-					DIAGNOSTIC_CODES.BACKGROUND_RESTRICTION_UNKNOWN,
-					'Manufacturer background restriction could not be determined on this device. Reported as unknown rather than guessed.',
-					{ battery: report.batteryOptimization, autoStart: report.autoStart },
-				);
-			}
-
-			return report;
-		},
-
-		/** Called by the permission-refresh maintenance step. */
-		async refresh(): Promise<{ readonly report: PermissionReport; readonly changed: boolean }> {
-			const report = await read();
-			return { report, changed: notifyIfChanged(report) };
-		},
-	};
-}
-
-export type Permissions = ReturnType<typeof createPermissions>;
+/**
+ * Permission coordination.
+ *
+ * Two rules shape everything here. Reading state never prompts, so the consumer
+ * decides when the user is asked — a prompt at the wrong moment is a permanent
+ * denial. And a refusal never fails the caller's business operation: the user's
+ * actual work completes, and the lost capability is reported separately.
+ */
+
+import type {
+	PermissionKind,
+	PermissionReport,
+	PermissionState,
+	RestrictionReport,
+} from '../contract/permission';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { StateManager } from '../state/record';
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+import { capabilityFor, normalizeState, type PlatformInfo } from './state';
+import { hasRequested, recordRequested } from '../state/permission-history';
+
+export interface PermissionDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly state: StateManager;
+	readonly platform: PlatformInfo;
+	readonly now: () => number;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export type PermissionChangeHandler = (report: PermissionReport) => void;
+
+export function createPermissions(deps: PermissionDependencies) {
+	const emit = deps.emit ?? (() => {});
+	let listeners: PermissionChangeHandler[] = [];
+	let lastReport: PermissionReport | undefined;
+
+	const read = async (): Promise<PermissionReport> => {
+		// Never prompts. This is what lets a consumer decide the moment to ask.
+		const [display, exactAlarm] = await Promise.all([
+			deps.engine.getPermission('display'),
+			deps.engine.getPermission('exactAlarm'),
+		]);
+
+		return {
+			display: normalizeState('display', display, deps.platform),
+			exactAlarm: normalizeState('exactAlarm', exactAlarm, deps.platform),
+			readAt: deps.now(),
+		};
+	};
+
+	const notifyIfChanged = (report: PermissionReport): boolean => {
+		const changed =
+			lastReport === undefined ||
+			lastReport.display !== report.display ||
+			lastReport.exactAlarm !== report.exactAlarm;
+
+		lastReport = report;
+		if (!changed) return false;
+
+		for (const listener of listeners) {
+			try {
+				listener(report);
+			} catch {
+				// A consumer's handler must never break permission reading.
+			}
+		}
+		return true;
+	};
+
+	const request = async (kind: PermissionKind, ownerTag?: string): Promise<PermissionState> => {
+		const capability = capabilityFor(kind, deps.platform);
+
+		// Requesting something the platform version does not have is a no-op that
+		// shows no dialog, rather than a refusal.
+		if (!capability.supported) {
+			return 'notRequired';
+		}
+
+		recordRequested(deps.state, kind, deps.now(), ownerTag);
+
+		const raw = await deps.engine.requestPermission(kind);
+		const result = normalizeState(kind, raw, deps.platform);
+
+		if (result === 'denied' || result === 'permanentlyDenied') {
+			emit(
+				kind === 'display'
+					? result === 'permanentlyDenied'
+						? DIAGNOSTIC_CODES.DISPLAY_PERMISSION_PERMANENT
+						: DIAGNOSTIC_CODES.DISPLAY_PERMISSION_DENIED
+					: DIAGNOSTIC_CODES.EXACT_ALARM_UNAVAILABLE,
+				kind === 'display'
+					? "Display permission was refused. The caller's operation still succeeded; notifications will not be shown until this is granted."
+					: 'Exact-alarm capability is unavailable. Notifications are still scheduled, in approximate mode, and may be delivered late.',
+				{ kind, state: result },
+			);
+		}
+
+		notifyIfChanged(await read());
+		return result;
+	};
+
+	return {
+		/** Reads every permission state without triggering any dialog. */
+		async getPermissions(): Promise<PermissionReport> {
+			const report = await read();
+			notifyIfChanged(report);
+			return report;
+		},
+
+		/** Requested independently — an app may need one and not the other. */
+		requestDisplayPermission(ownerTag?: string): Promise<PermissionState> {
+			return request('display', ownerTag);
+		},
+
+		requestExactAlarmPermission(ownerTag?: string): Promise<PermissionState> {
+			return request('exactAlarm', ownerTag);
+		},
+
+		/** Whether the package has ever asked — the platform cannot answer this. */
+		hasEverRequested(kind: PermissionKind, ownerTag?: string): boolean {
+			return hasRequested(deps.state, kind, ownerTag);
+		},
+
+		/**
+		 * Opens the settings screen for one specific permission.
+		 *
+		 * Telling a user to "find it in settings" is how you lose them, so a
+		 * platform with no reachable screen is an error rather than a silent no-op.
+		 */
+		async openSettings(kind: PermissionKind): Promise<void> {
+			if (!capabilityFor(kind, deps.platform).supported) {
+				throw new NotificationError(
+					DIAGNOSTIC_CODES.SETTINGS_UNAVAILABLE,
+					`No settings screen exists for ${kind} on this platform version.`,
+					{ kind, os: deps.platform.os, apiLevel: deps.platform.apiLevel },
+				);
+			}
+			await deps.engine.openSettings(kind);
+		},
+
+		onPermissionChange(handler: PermissionChangeHandler): () => void {
+			listeners.push(handler);
+			return () => {
+				listeners = listeners.filter(l => l !== handler);
+			};
+		},
+
+		/**
+		 * Manufacturer background restrictions, reported for information only.
+		 *
+		 * `unknown` is a first-class answer: some vendors stop apps in ways with no
+		 * detection API, and guessing would be worse than admitting it. The package
+		 * changes none of these settings on the user's behalf.
+		 */
+		async getBackgroundRestrictions(): Promise<RestrictionReport> {
+			const report = await deps.engine.getRestrictions();
+
+			if (report.batteryOptimization === 'restricted' || report.autoStart === 'restricted') {
+				emit(
+					DIAGNOSTIC_CODES.BACKGROUND_RESTRICTED,
+					'The device applies a manufacturer background restriction. Notifications may be delayed or suppressed.',
+					{ battery: report.batteryOptimization, autoStart: report.autoStart },
+				);
+			} else if (report.batteryOptimization === 'unknown' || report.autoStart === 'unknown') {
+				emit(
+					DIAGNOSTIC_CODES.BACKGROUND_RESTRICTION_UNKNOWN,
+					'Manufacturer background restriction could not be determined on this device. Reported as unknown rather than guessed.',
+					{ battery: report.batteryOptimization, autoStart: report.autoStart },
+				);
+			}
+
+			return report;
+		},
+
+		/** Called by the permission-refresh maintenance step. */
+		async refresh(): Promise<{ readonly report: PermissionReport; readonly changed: boolean }> {
+			const report = await read();
+			return { report, changed: notifyIfChanged(report) };
+		},
+	};
+}
+
+export type Permissions = ReturnType<typeof createPermissions>;

package/src/permission/state.ts

@@ -1,77 +1,77 @@
-/**
- * The permission state model.
- *
- * Six states, never collapsed. The two that matter most are the ones a naive
- * model loses: `notAsked` must stay distinguishable from `denied`, or reading
- * state without prompting buys nothing; and `notRequired` must never be
- * reported as `denied`, because a platform version with no such concept never
- * refused anything.
- */
-
-import type { PermissionCapability, PermissionKind, PermissionState } from '../contract/permission';
-
-/** Android runtime notification permission arrived in API 33. */
-export const ANDROID_DISPLAY_PERMISSION_API = 33;
-/** Android exact-alarm permission arrived in API 31. */
-export const ANDROID_EXACT_ALARM_API = 31;
-
-export interface PlatformInfo {
-	readonly os: 'ios' | 'android' | 'other';
-	/** Android API level. Ignored on iOS. */
-	readonly apiLevel?: number;
-}
-
-/**
- * Whether a permission concept exists at all on this platform version.
- *
- * Returning `supported: false` is what lets `notRequired` be reported honestly
- * rather than inventing a refusal.
- */
-export function capabilityFor(kind: PermissionKind, platform: PlatformInfo): PermissionCapability {
-	if (kind === 'display') {
-		if (platform.os === 'android' && (platform.apiLevel ?? 0) < ANDROID_DISPLAY_PERMISSION_API) {
-			return { kind, supported: false, settingsOnly: false };
-		}
-		return { kind, supported: true, settingsOnly: false };
-	}
-
-	// Exact alarms exist only on Android 12+, and are granted through system
-	// settings rather than an in-app dialog on the versions that gate them.
-	if (platform.os !== 'android' || (platform.apiLevel ?? 0) < ANDROID_EXACT_ALARM_API) {
-		return { kind, supported: false, settingsOnly: false };
-	}
-	return { kind, supported: true, settingsOnly: true };
-}
-
-/** Normalizes a platform reading into the six-state model. */
-export function normalizeState(
-	kind: PermissionKind,
-	raw: PermissionState,
-	platform: PlatformInfo,
-): PermissionState {
-	if (!capabilityFor(kind, platform).supported) {
-		return 'notRequired';
-	}
-	return raw;
-}
-
-/**
- * Whether a state means the package can still show notifications.
- *
- * `provisional` counts: iOS quiet delivery still reaches the user, just without
- * interrupting them. Treating it as denied would suppress notifications the
- * user is in fact receiving.
- */
-export function canDisplay(state: PermissionState): boolean {
-	return state === 'granted' || state === 'provisional' || state === 'notRequired';
-}
-
-/** Whether asking again could produce a dialog, or whether settings is the only route. */
-export function isTerminal(state: PermissionState): boolean {
-	return state === 'permanentlyDenied' || state === 'notRequired';
-}
-
-/** Whether the package has ever asked, which the platform cannot answer after the fact. */
-export function shouldOfferSettings(state: PermissionState): boolean {
-	return state === 'denied' || state === 'permanentlyDenied';
-}
+/**
+ * The permission state model.
+ *
+ * Six states, never collapsed. The two that matter most are the ones a naive
+ * model loses: `notAsked` must stay distinguishable from `denied`, or reading
+ * state without prompting buys nothing; and `notRequired` must never be
+ * reported as `denied`, because a platform version with no such concept never
+ * refused anything.
+ */
+
+import type { PermissionCapability, PermissionKind, PermissionState } from '../contract/permission';
+
+/** Android runtime notification permission arrived in API 33. */
+export const ANDROID_DISPLAY_PERMISSION_API = 33;
+/** Android exact-alarm permission arrived in API 31. */
+export const ANDROID_EXACT_ALARM_API = 31;
+
+export interface PlatformInfo {
+	readonly os: 'ios' | 'android' | 'other';
+	/** Android API level. Ignored on iOS. */
+	readonly apiLevel?: number;
+}
+
+/**
+ * Whether a permission concept exists at all on this platform version.
+ *
+ * Returning `supported: false` is what lets `notRequired` be reported honestly
+ * rather than inventing a refusal.
+ */
+export function capabilityFor(kind: PermissionKind, platform: PlatformInfo): PermissionCapability {
+	if (kind === 'display') {
+		if (platform.os === 'android' && (platform.apiLevel ?? 0) < ANDROID_DISPLAY_PERMISSION_API) {
+			return { kind, supported: false, settingsOnly: false };
+		}
+		return { kind, supported: true, settingsOnly: false };
+	}
+
+	// Exact alarms exist only on Android 12+, and are granted through system
+	// settings rather than an in-app dialog on the versions that gate them.
+	if (platform.os !== 'android' || (platform.apiLevel ?? 0) < ANDROID_EXACT_ALARM_API) {
+		return { kind, supported: false, settingsOnly: false };
+	}
+	return { kind, supported: true, settingsOnly: true };
+}
+
+/** Normalizes a platform reading into the six-state model. */
+export function normalizeState(
+	kind: PermissionKind,
+	raw: PermissionState,
+	platform: PlatformInfo,
+): PermissionState {
+	if (!capabilityFor(kind, platform).supported) {
+		return 'notRequired';
+	}
+	return raw;
+}
+
+/**
+ * Whether a state means the package can still show notifications.
+ *
+ * `provisional` counts: iOS quiet delivery still reaches the user, just without
+ * interrupting them. Treating it as denied would suppress notifications the
+ * user is in fact receiving.
+ */
+export function canDisplay(state: PermissionState): boolean {
+	return state === 'granted' || state === 'provisional' || state === 'notRequired';
+}
+
+/** Whether asking again could produce a dialog, or whether settings is the only route. */
+export function isTerminal(state: PermissionState): boolean {
+	return state === 'permanentlyDenied' || state === 'notRequired';
+}
+
+/** Whether the package has ever asked, which the platform cannot answer after the fact. */
+export function shouldOfferSettings(state: PermissionState): boolean {
+	return state === 'denied' || state === 'permanentlyDenied';
+}