@chipmobilesdk/rn-notification 0.1.0

package/src/maintenance/verify.ts

@@ -0,0 +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: [],
+			};
+		},
+	};
+}

package/src/maintenance/window-refresh.ts

@@ -0,0 +1,61 @@
+/**
+ * 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;
+
+			for (const rule of rules) {
+				const result = await deps.recurrence.refreshSeries(rule);
+				scheduled += result.scheduled;
+			}
+
+			return {
+				operationCount: scheduled,
+				occurrencesScheduled: scheduled,
+				// A refresh that found nothing to add still ran; reporting it as
+				// refreshed distinguishes "nothing due" from "step never executed".
+				windowRefreshed: true,
+				// Refresh only ever adds occurrences within series the package owns.
+				cancelledIds: [],
+			};
+		},
+	};
+}

package/src/permission/index.ts

@@ -0,0 +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>;

package/src/permission/state.ts

@@ -0,0 +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';
+}

package/src/push/envelope.ts

@@ -0,0 +1,165 @@
+/**
+ * Payload normalization.
+ *
+ * Every provider's payload is reduced to one envelope shape before it reaches
+ * the consumer, so changing provider costs consumer code nothing.
+ *
+ * Version handling is best-effort: a payload declaring a version this build
+ * does not implement is still processed, honouring the fields it understands
+ * and ignoring the rest. Servers deploy ahead of app adoption and old app
+ * versions live on devices for months, so gating every server-side change on
+ * app rollout is the more expensive failure.
+ *
+ * That is only safe under an append-only discipline — a released field's
+ * meaning must never be repurposed. The version-skew diagnostic exists so a
+ * misprocessing incident is traceable to the skew rather than investigated as a
+ * logic defect.
+ */
+
+import type { PushEnvelope } from './provider-adapter';
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+
+/** The contract version this build implements. */
+export const IMPLEMENTED_PAYLOAD_VERSION = 1;
+
+const KINDS = new Set(['display', 'data', 'schedule', 'cancel']);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+/**
+ * Text, or nothing.
+ *
+ * Deliberately not `String(value)`: an object coerces to the literal string
+ * "[object Object]", which would be rendered to the user as a notification
+ * title. A field that is not text is treated as absent.
+ */
+function asText(value: unknown): string | undefined {
+	if (typeof value === 'string') return value;
+	if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+	return undefined;
+}
+
+/** An epoch instant from either a number or an ISO-8601 string. */
+function asInstant(value: unknown): number {
+	if (typeof value === 'number' && Number.isFinite(value)) return value;
+	if (typeof value === 'string') return Date.parse(value);
+	return Number.NaN;
+}
+
+/** Extracts and validates the contract version, which every payload must declare. */
+function readVersion(body: Record<string, unknown>): number {
+	const raw = body.v;
+	const version = typeof raw === 'number' ? raw : Number.parseInt(asText(raw) ?? '', 10);
+
+	if (!Number.isInteger(version) || version < 1) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.PAYLOAD_MALFORMED,
+			'Push payload carries no usable contract version. Every payload must declare `v` from the first release.',
+			{ received: typeof raw },
+		);
+	}
+	return version;
+}
+
+function readKind(body: Record<string, unknown>): PushEnvelope['kind'] {
+	const kind = asText(body.kind);
+
+	if (kind === undefined || !KINDS.has(kind)) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.PAYLOAD_MALFORMED,
+			`Push payload declares unknown kind "${kind ?? ''}".`,
+			{ kind },
+		);
+	}
+	return kind as PushEnvelope['kind'];
+}
+
+function readId(body: Record<string, unknown>): string {
+	const id = asText(body.id);
+
+	if (id === undefined || id.length === 0) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.PAYLOAD_MALFORMED,
+			'Push payload carries no identifier.',
+		);
+	}
+	return id;
+}
+
+function readContent(body: Record<string, unknown>): PushEnvelope['content'] {
+	const content = asRecord(body.content);
+	if (content === undefined) return undefined;
+
+	return {
+		title: asText(content.title) ?? '',
+		body: asText(content.body) ?? '',
+		subtitle: asText(content.subtitle),
+	};
+}
+
+function readMoment(body: Record<string, unknown>): PushEnvelope['moment'] {
+	const moment = asRecord(body.moment);
+	if (moment === undefined) return undefined;
+
+	return {
+		at: asInstant(moment.at),
+		anchoring: moment.anchoring === 'absolute' ? 'absolute' : 'wallClock',
+	};
+}
+
+export interface NormalizeResult {
+	readonly envelope: PushEnvelope;
+	readonly versionSkew: boolean;
+}
+
+/**
+ * Normalizes a raw provider payload.
+ *
+ * Throws only for a **structurally unparseable** payload — a broken message.
+ * An unrecognized version is a healthy message from a newer contract and must
+ * never collapse into the same condition.
+ */
+export function normalizeEnvelope(raw: unknown, receivedAt: number): NormalizeResult {
+	const record = asRecord(raw);
+	if (record === undefined) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.PAYLOAD_MALFORMED,
+			'Push payload is not an object and cannot be interpreted.',
+			{ received: Array.isArray(raw) ? 'array' : typeof raw },
+		);
+	}
+
+	// Providers deliver the payload under a data bag; accept either shape so the
+	// adapter does not have to reshape before handing it over.
+	const body = asRecord(record.data) ?? record;
+
+	const version = readVersion(body);
+	const kind = readKind(body);
+	const id = readId(body);
+	const versionSkew = version !== IMPLEMENTED_PAYLOAD_VERSION;
+
+	return {
+		versionSkew,
+		envelope: {
+			version,
+			kind,
+			id,
+			ownerTag: asText(body.ownerTag),
+			content: readContent(body),
+			tone: asText(body.tone),
+			moment: readMoment(body),
+			routing: asRecord(body.routing),
+			// Falls back to the identifier, so a server that omits it still gets
+			// de-duplication rather than silently losing it.
+			dedupId: asText(body.dedupId) ?? id,
+			receivedAt,
+			versionSkew,
+			// Fields this build does not understand are simply not read — that is
+			// what best-effort processing means in practice.
+		},
+	};
+}