@chipmobilesdk/rn-notification 0.5.0 → 0.6.0

package/src/engine/notify-kit/module.ts

@@ -0,0 +1,148 @@
+/**
+ * The slice of `react-native-notify-kit` this package uses, and how it is loaded.
+ *
+ * Every import of the engine is confined to this file. The module is required
+ * lazily so the package loads in Jest and in any environment without the native
+ * module; an absent engine is reported through the normal diagnostic path
+ * rather than crashing at import time.
+ */
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import { DIAGNOSTIC_CODES, NotificationError } from '../../contract/errors';
+
+/** Both platforms bound background execution for a silent payload or background action. */
+export const BACKGROUND_WINDOW_MS = 30_000;
+
+/**
+ * The engine's own enum values, mirrored as literals.
+ *
+ * These are **numeric** enums in the engine's type definitions, and its native
+ * validator rejects the string names — `importance: 'default'` fails with
+ * "expected a valid Importance". Mirroring them here rather than importing the
+ * enums keeps the engine out of the module graph, which is what lets the
+ * package load without the native module present.
+ *
+ * The package's own `ResolvedTone` deliberately stays platform-neutral strings;
+ * translating to the engine's representation is this adapter's job and nobody
+ * else's.
+ */
+export const ANDROID_IMPORTANCE = {
+	none: 0,
+	min: 1,
+	low: 2,
+	default: 3,
+	high: 4,
+} as const;
+
+/** `TriggerType.TIMESTAMP`. */
+export const TRIGGER_TYPE_TIMESTAMP = 0;
+
+/** `AlarmType.SET_EXACT_AND_ALLOW_WHILE_IDLE` — exact delivery, survives Doze. */
+export const ALARM_TYPE_EXACT_AND_ALLOW_WHILE_IDLE = 3;
+
+/** `AlarmType.SET_AND_ALLOW_WHILE_IDLE` — the approximate degradation of the above. */
+export const ALARM_TYPE_INEXACT_AND_ALLOW_WHILE_IDLE = 1;
+
+/**
+ * `EventType` values that represent a real user interaction.
+ *
+ * The engine emits far more than interactions on this channel — `DELIVERED`,
+ * `TRIGGER_NOTIFICATION_CREATED`, `CHANNEL_BLOCKED` and others all arrive here.
+ * Treating anything that is not a dismissal as a press would report a
+ * notification *arriving* while the app is open as the user having tapped it,
+ * and the interaction path cancels on tap — so the notification would vanish
+ * from the tray in front of the user, unread.
+ */
+export const EVENT_TYPE_DISMISSED = 0;
+export const EVENT_TYPE_PRESS = 1;
+export const EVENT_TYPE_ACTION_PRESS = 2;
+
+/** `EventType.DELIVERED` — an arrival, which is emphatically not an interaction. */
+export const EVENT_TYPE_DELIVERED = 3;
+
+/**
+ * `AndroidCategory.ALARM`, the engine's marking for a time-sensitive alert.
+ *
+ * A per-notification property, not channel configuration — which is why
+ * declaring `timeSensitive` on an existing tone never obliges a version bump.
+ */
+export const ANDROID_CATEGORY_ALARM = 'alarm';
+
+/**
+ * The channel stop markers are posted on.
+ *
+ * A marker exists to be delivered and immediately removed, so it is given the
+ * quietest configuration the platform offers: minimum importance, no sound, no
+ * vibration. Its version is fixed because nothing about it is consumer-declared,
+ * so it never migrates.
+ */
+export const MARKER_CHANNEL_ID = 'cms.internal.stop.v1';
+
+/** Minimal shape used from the engine, so its full surface never leaks into typing. */
+export interface NotifyKitModule {
+	createChannel(channel: Record<string, unknown>): Promise<string>;
+	deleteChannel(channelId: string): Promise<void>;
+	/**
+	 * Labels come back with the id. That is what makes a label refresh decidable
+	 * against the device rather than against a ledger of our own — and a ledger
+	 * drifts after a restore, a reinstall, or a change the user made themselves.
+	 */
+	getChannels(): Promise<{ id: string; name?: string; description?: string }[]>;
+	createChannelGroup(group: Record<string, unknown>): Promise<string>;
+	createTriggerNotification(
+		notification: Record<string, unknown>,
+		trigger: Record<string, unknown>,
+	): Promise<string>;
+	displayNotification(notification: Record<string, unknown>): Promise<string>;
+	getDisplayedNotifications(): Promise<Record<string, unknown>[]>;
+	cancelNotification(id: string): Promise<void>;
+	cancelAllNotifications(): Promise<void>;
+	getTriggerNotifications(): Promise<Record<string, unknown>[]>;
+	/** Identifiers only. Optional, because not every release of the binding has it. */
+	getTriggerNotificationIds?(): Promise<string[]>;
+	onBackgroundEvent(handler: (event: Record<string, unknown>) => Promise<void>): void;
+	requestPermission(options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+	getNotificationSettings(): Promise<Record<string, unknown>>;
+	openNotificationSettings(): Promise<void>;
+	openAlarmPermissionSettings(): Promise<void>;
+	isBatteryOptimizationEnabled(): Promise<boolean>;
+	onForegroundEvent(handler: (event: Record<string, unknown>) => void): () => void;
+	getInitialNotification(): Promise<Record<string, unknown> | null>;
+}
+
+/**
+ * Drops keys whose value is `undefined`.
+ *
+ * The engine validates its arguments by key presence, not by value: passing
+ * `{ groupId: undefined }` fails with "expected a string value", while omitting
+ * the key entirely is accepted. JavaScript treats the two as interchangeable
+ * almost everywhere, which is exactly why this is easy to get wrong — and why
+ * it only surfaces on a real device, where the native validator runs.
+ */
+export function compact<T extends Record<string, unknown>>(value: T): Partial<T> {
+	const output: Record<string, unknown> = {};
+	for (const [key, entry] of Object.entries(value)) {
+		if (entry !== undefined) output[key] = entry;
+	}
+	return output as Partial<T>;
+}
+
+const notifyKit = lazyPeer('react-native-notify-kit', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-notify-kit') as { default: NotifyKitModule };
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+export function loadEngine(): NotifyKitModule {
+	return notifyKit.require(
+		(_peer, cause) =>
+			new NotificationError(
+				DIAGNOSTIC_CODES.PUSH_UNAVAILABLE,
+				'react-native-notify-kit is not installed or its native module is not linked. Install it as a peer dependency and rebuild the app.',
+				{ reason: cause instanceof Error ? cause.name : 'unknown' },
+			),
+	).default;
+}

package/src/engine/notify-kit/platform/android.ts

@@ -0,0 +1,172 @@
+/**
+ * Android: channels, exact alarms, battery optimisation, looping alerts.
+ */
+import type { RestrictionReport } from '../../../contract/permission';
+import { toPermissionState } from '../events';
+import { ANDROID_IMPORTANCE, BACKGROUND_WINDOW_MS, MARKER_CHANNEL_ID, compact } from '../module';
+import type { NotifyKitPlatform, PlatformContext } from './types';
+
+/** Android has no hard pending ceiling like iOS; this bound keeps behavior predictable. */
+const ANDROID_PENDING_BUDGET = 500;
+/** Android 13: the first version with a runtime display permission. */
+const DISPLAY_PERMISSION_API = 33;
+/** Android 12: the first version that gates exact alarms. */
+const EXACT_ALARM_API = 31;
+
+type DeclaredChannel = { id: string; name?: string; description?: string };
+
+export function createAndroidPlatform({ engine, apiLevel }: PlatformContext): NotifyKitPlatform {
+	let markerChannelReady = false;
+	/** The declared channels for the duration of one `withChannelSnapshot` (NOT-08). */
+	let channelSnapshot: DeclaredChannel[] | undefined;
+	const declaredChannels = async (): Promise<DeclaredChannel[]> =>
+		channelSnapshot ?? engine().getChannels();
+	// An unknown API level is treated as current: gating is the safe assumption.
+	const atLeast = (level: number): boolean => (apiLevel() ?? Number.POSITIVE_INFINITY) >= level;
+
+	return {
+		capabilities: () => ({
+			pendingCeiling: ANDROID_PENDING_BUDGET,
+			supportsExactAlarms: true,
+			supportsChannels: true,
+			supportsTextInputActions: true,
+			supportsDoNotDisturbBypass: true,
+			supportsRepeatingAlert: true,
+			backgroundWindowMs: BACKGROUND_WINDOW_MS,
+		}),
+
+		/**
+		 * Lazily rather than at initialization, so an app that never declares a
+		 * repeating tone never grows an extra entry in the user's notification
+		 * settings for a feature it does not use.
+		 */
+		async ensureMarkerChannel() {
+			if (markerChannelReady) return;
+			await engine().createChannel({
+				id: MARKER_CHANNEL_ID,
+				name: 'Background maintenance',
+				description:
+					'Used briefly to end a repeating alert. Notifications here are removed immediately.',
+				importance: ANDROID_IMPORTANCE.min,
+				vibration: false,
+				badge: false,
+			});
+			markerChannelReady = true;
+		},
+
+		async withChannelSnapshot(work) {
+			if (channelSnapshot !== undefined) {
+				return work();
+			}
+			channelSnapshot = await engine().getChannels();
+			try {
+				return await work();
+			} finally {
+				channelSnapshot = undefined;
+			}
+		},
+
+		async declareTone(tone) {
+			const existing = await declaredChannels();
+			const held = existing.find(channel => channel.id === tone.android.channelId);
+			const remember = () => {
+				channelSnapshot = channelSnapshot
+					?.filter(channel => channel.id !== tone.android.channelId)
+					.concat({
+						id: tone.android.channelId,
+						name: tone.android.name,
+						description: tone.android.description,
+					});
+			};
+
+			const payload = compact({
+				id: tone.android.channelId,
+				// The consumer's declared label, not the tone identifier. Passing the
+				// identifier here is what put a technical string in front of users on
+				// the one screen these labels exist to serve.
+				name: tone.android.name,
+				description: tone.android.description,
+				importance: ANDROID_IMPORTANCE[tone.android.importance],
+				sound: tone.android.sound,
+				vibration: tone.android.vibration,
+				badge: tone.android.badge,
+				bypassDnd: tone.android.bypassDnd,
+				groupId: tone.android.groupId,
+			});
+
+			if (held === undefined) {
+				await engine().createChannel(payload);
+				remember();
+				return 'created';
+			}
+			if (held.name === tone.android.name && held.description === tone.android.description) {
+				// Nothing to say to the platform. Skipping the call is what keeps an
+				// unchanged configuration genuinely free, which reconciliation
+				// idempotence depends on.
+				return 'unchanged';
+			}
+			// Android accepts a re-declaration of an existing channel and applies only
+			// the name and description, ignoring importance, sound, vibration and DND
+			// — because those belong to the user once the channel exists. That refusal
+			// is the guarantee: the platform declines to overwrite the user's settings.
+			await engine().createChannel(payload);
+			remember();
+			return 'labelsRefreshed';
+		},
+
+		async retireTone(channelId) {
+			const existing = await declaredChannels();
+			if (!existing.some(channel => channel.id === channelId)) return false;
+			await engine().deleteChannel(channelId);
+			channelSnapshot = channelSnapshot?.filter(channel => channel.id !== channelId);
+			return true;
+		},
+
+		async declareGroups(groups) {
+			for (const group of groups) {
+				await engine().createChannelGroup(
+					compact({ id: group.id, name: group.name, description: group.description }),
+				);
+			}
+		},
+
+		async listDeclaredChannels() {
+			return (await declaredChannels()).map(channel => channel.id);
+		},
+
+		permissionFrom(kind, settings) {
+			if (kind === 'display') {
+				// Android below 13 has no runtime display permission at all.
+				return atLeast(DISPLAY_PERMISSION_API)
+					? toPermissionState(settings.authorizationStatus)
+					: 'notRequired';
+			}
+			// Before Android 12 the concept does not apply: "not required", not "denied".
+			if (!atLeast(EXACT_ALARM_API)) {
+				return 'notRequired';
+			}
+			const android = (settings.android ?? {}) as Record<string, unknown>;
+			return android.alarm === 1 ? 'granted' : 'denied';
+		},
+
+		gatesExactAlarms: () => atLeast(EXACT_ALARM_API),
+
+		async restrictions(now) {
+			let batteryOptimization: RestrictionReport['batteryOptimization'] = 'unknown';
+			try {
+				batteryOptimization = (await engine().isBatteryOptimizationEnabled())
+					? 'restricted'
+					: 'unrestricted';
+			} catch {
+				batteryOptimization = 'unknown';
+			}
+			return {
+				batteryOptimization,
+				// No standard API exposes vendor auto-start policy, and guessing would
+				// be worse than admitting it. `unknown` is a first-class answer here.
+				autoStart: 'unknown',
+				readAt: now(),
+			};
+		},
+	};
+}

package/src/engine/notify-kit/platform/index.ts

@@ -0,0 +1,55 @@
+/**
+ * The one place this package asks which platform it is on (IOS-08).
+ *
+ * rn-core's `currentPlatform()` decides the OS; the Android API level is read
+ * from React Native lazily, when asked, so the module loads without it.
+ */
+import { currentPlatform, lazyPeer } from '@chipmobilesdk/rn-core';
+
+import type { PlatformInfo } from '../../../permission/state';
+import type { NotifyKitModule } from '../module';
+import { createAndroidPlatform } from './android';
+import { createIosPlatform } from './ios';
+import type { NotifyKitPlatform } from './types';
+
+export type { NotifyKitPlatform } from './types';
+
+type ReactNativeSlice = { Platform?: { Version?: unknown } };
+
+const reactNative = lazyPeer<ReactNativeSlice>('react-native', () => {
+	try {
+		return require('react-native') as ReactNativeSlice;
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+/** The running OS and, on Android, its API level. */
+export function detectPlatform(): PlatformInfo {
+	const os = currentPlatform();
+	if (os !== 'android') {
+		return { os: os === 'ios' ? 'ios' : 'other' };
+	}
+	const result = reactNative.get();
+	const version = result.ok ? result.module.Platform?.Version : undefined;
+	return { os, apiLevel: typeof version === 'number' ? version : undefined };
+}
+
+/**
+ * The strategy for `platform`, or for the running one. Only Android gets the
+ * Android strategy; anywhere else nothing channel- or alarm-specific is called.
+ */
+export function createNotifyKitPlatform(
+	engine: () => NotifyKitModule,
+	platform?: PlatformInfo,
+): NotifyKitPlatform {
+	const os = platform?.os ?? detectPlatform().os;
+	if (os !== 'android') {
+		return createIosPlatform();
+	}
+	return createAndroidPlatform({
+		engine,
+		// Read when asked rather than once, so it follows the device (and a test).
+		apiLevel: () => (platform ? platform.apiLevel : detectPlatform().apiLevel),
+	});
+}

package/src/engine/notify-kit/platform/ios.ts

@@ -0,0 +1,54 @@
+/**
+ * iOS: no channels, no exact-alarm gate, a hard ceiling of 64 pending
+ * notifications. Categories are declared per request rather than up front.
+ */
+import { toPermissionState } from '../events';
+import { BACKGROUND_WINDOW_MS } from '../module';
+import type { NotifyKitPlatform } from './types';
+
+/**
+ * iOS keeps only the 64 soonest pending notifications and silently discards the
+ * rest. This number is the entire reason truncation must be computed and
+ * reported by the package rather than left to the platform.
+ */
+const IOS_PENDING_CEILING = 64;
+
+export function createIosPlatform(): NotifyKitPlatform {
+	return {
+		capabilities: () => ({
+			pendingCeiling: IOS_PENDING_CEILING,
+			supportsExactAlarms: false,
+			supportsChannels: false,
+			supportsTextInputActions: true,
+			supportsDoNotDisturbBypass: false,
+			// iOS exposes no looping-sound API. The one alert level that overrides the
+			// mute switch is entitlement-gated by Apple, and does not loop either — so
+			// there is nothing to partially support, and a partial emulation would be
+			// worse than an honest refusal.
+			supportsRepeatingAlert: false,
+			backgroundWindowMs: BACKGROUND_WINDOW_MS,
+		}),
+
+		// No marker is ever placed where alerts cannot repeat.
+		async ensureMarkerChannel() {},
+
+		withChannelSnapshot: work => work(),
+		// Categories are declared at request time rather than up front.
+		declareTone: async () => 'unchanged',
+		retireTone: async () => false,
+		async declareGroups() {},
+		listDeclaredChannels: async () => [],
+
+		permissionFrom: (kind, settings) =>
+			// Exact alarms are an Android concept: "not required", not "denied".
+			kind === 'display' ? toPermissionState(settings.authorizationStatus) : 'notRequired',
+
+		gatesExactAlarms: () => false,
+
+		restrictions: async now => ({
+			batteryOptimization: 'unrestricted',
+			autoStart: 'unrestricted',
+			readAt: now(),
+		}),
+	};
+}

package/src/engine/notify-kit/platform/types.ts

@@ -0,0 +1,40 @@
+/**
+ * What differs between Android and iOS in the notify-kit engine (NOT-18, IOS-08).
+ *
+ * The engine picks one implementation when it is created and never branches on
+ * the OS again. Changing iOS behaviour touches `ios.ts` only, and the Android
+ * file that runs in production stays as it is.
+ */
+import type { ChannelGroup, ResolvedTone } from '../../../contract/channel';
+import type {
+	PermissionKind,
+	PermissionState,
+	RestrictionReport,
+} from '../../../contract/permission';
+import type { EngineCapabilities, ToneDeclarationOutcome } from '../../adapter';
+import type { NotifyKitModule } from '../module';
+
+export interface NotifyKitPlatform {
+	capabilities(): EngineCapabilities;
+	/** Creates the channel stop markers are posted on, the first time one is needed. */
+	ensureMarkerChannel(): Promise<void>;
+
+	withChannelSnapshot<T>(work: () => Promise<T>): Promise<T>;
+	declareTone(tone: ResolvedTone): Promise<ToneDeclarationOutcome>;
+	retireTone(channelId: string): Promise<boolean>;
+	declareGroups(groups: readonly ChannelGroup[]): Promise<void>;
+	listDeclaredChannels(): Promise<readonly string[]>;
+
+	/** The state of `kind`, from the engine's settings as just read. */
+	permissionFrom(kind: PermissionKind, settings: Record<string, unknown>): PermissionState;
+	/** Whether exact alarms are a capability the user grants here. */
+	gatesExactAlarms(): boolean;
+	restrictions(now: () => number): Promise<RestrictionReport>;
+}
+
+export interface PlatformContext {
+	/** The engine module, resolved lazily. */
+	readonly engine: () => NotifyKitModule;
+	/** Android API level, read when asked; undefined elsewhere or when unknown. */
+	readonly apiLevel: () => number | undefined;
+}