@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/push/envelope.ts

@@ -1,165 +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.
-		},
-	};
-}
+/**
+ * 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.
+		},
+	};
+}

package/src/push/fcm-provider.ts

@@ -1,146 +1,150 @@
-/**
- * The Firebase Cloud Messaging provider.
- *
- * Every `@react-native-firebase/messaging` import is confined to this file, so
- * the rest of the package — and every consuming app — stays free of provider
- * types. Substituting a provider is an adapter swap, not a rewrite.
- *
- * The module is required **lazily**. That matters more here than for the
- * engine: messaging is an *optional* peer dependency, and an app that never
- * enables push must not fail at import time for a package it deliberately did
- * not install.
- */
-
-import type {
-	PushAvailability,
-	PushProviderAdapter,
-} from './provider-adapter';
-import type { Unsubscribe } from '../contract/interaction';
-
-/** Minimal shape used from the SDK, so its full surface never leaks into typing. */
-interface MessagingModule {
-	(): MessagingInstance;
-	AuthorizationStatus?: Record<string, number>;
-}
-
-interface MessagingInstance {
-	getToken(): Promise<string>;
-	deleteToken(): Promise<void>;
-	onTokenRefresh(handler: (token: string) => void): () => void;
-	onMessage(handler: (message: unknown) => Promise<void> | void): () => void;
-	setBackgroundMessageHandler(handler: (message: unknown) => Promise<void>): void;
-	getInitialNotification(): Promise<unknown | null>;
-	hasPermission?(): Promise<number>;
-	isDeviceRegisteredForRemoteMessages?: boolean;
-}
-
-function loadMessaging(): MessagingModule | undefined {
-	try {
-		const module = require('@react-native-firebase/messaging') as { default: MessagingModule };
-		return module.default;
-	} catch {
-		// Absent optional peer, or missing native module. Reported as
-		// unavailability through the normal path rather than thrown at import.
-		return undefined;
-	}
-}
-
-export interface FcmProviderOptions {
-	/** Injected in tests; production resolves the real module. */
-	readonly module?: MessagingModule;
-	/**
-	 * Registers the background message handler.
-	 *
-	 * Left to the consumer by default because the SDK requires it to be
-	 * registered at module scope in `index.js`, outside React's lifecycle — a
-	 * constraint the package documents rather than works around.
-	 */
-	readonly onBackgroundMessage?: (message: unknown) => Promise<void>;
-}
-
-export function createFcmProvider(options: FcmProviderOptions = {}): PushProviderAdapter {
-	let cached: MessagingModule | undefined = options.module;
-	let resolved = options.module !== undefined;
-
-	const messaging = (): MessagingInstance | undefined => {
-		if (!resolved) {
-			cached = loadMessaging();
-			resolved = true;
-		}
-		return cached?.();
-	};
-
-	if (options.onBackgroundMessage !== undefined) {
-		messaging()?.setBackgroundMessageHandler(options.onBackgroundMessage);
-	}
-
-	return {
-		name: '@react-native-firebase/messaging',
-
-		async getAvailability(): Promise<PushAvailability> {
-			const instance = messaging();
-
-			// A device without Google Play Services, or an app that never installed
-			// the optional peer. Either way the local path is unaffected.
-			if (instance === undefined) return 'unavailable';
-
-			try {
-				await instance.getToken();
-				return 'available';
-			} catch {
-				// Registration can fail for reasons the SDK does not distinguish, so
-				// `unknown` is reported rather than a guess at which one.
-				return 'unknown';
-			}
-		},
-
-		async getToken(): Promise<string> {
-			const instance = messaging();
-			if (instance === undefined) {
-				throw new Error('Push provider is unavailable on this device.');
-			}
-			// Resolves only once a genuine token exists; the gate never presents an
-			// empty value as if it were one.
-			return instance.getToken();
-		},
-
-		onTokenChange(handler: (token: string) => void): Unsubscribe {
-			const instance = messaging();
-			if (instance === undefined) return () => undefined;
-			return instance.onTokenRefresh(handler);
-		},
-
-		async invalidateToken(): Promise<boolean> {
-			const instance = messaging();
-			if (instance === undefined) return false;
-
-			try {
-				await instance.deleteToken();
-				return true;
-			} catch {
-				// Reported as a failed invalidation rather than assumed successful —
-				// the device may keep receiving the previous account's messages.
-				return false;
-			}
-		},
-
-		subscribeToMessages(handler: (raw: unknown) => void): Unsubscribe {
-			const instance = messaging();
-			if (instance === undefined) return () => undefined;
-
-			// Foreground only. Background delivery arrives through the handler the
-			// consumer registers at module scope, which the README documents.
-			return instance.onMessage(message => {
-				handler(message);
-			});
-		},
-
-		async takeInitialMessage(): Promise<unknown | undefined> {
-			const instance = messaging();
-			if (instance === undefined) return undefined;
-
-			const message = await instance.getInitialNotification();
-			return message ?? undefined;
-		},
-	};
-}
+/**
+ * The Firebase Cloud Messaging provider.
+ *
+ * Every `@react-native-firebase/messaging` import is confined to this file, so
+ * the rest of the package — and every consuming app — stays free of provider
+ * types. Substituting a provider is an adapter swap, not a rewrite.
+ *
+ * The module is required **lazily**. That matters more here than for the
+ * engine: messaging is an *optional* peer dependency, and an app that never
+ * enables push must not fail at import time for a package it deliberately did
+ * not install.
+ */
+
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import type { PushAvailability, PushProviderAdapter } from './provider-adapter';
+import type { Unsubscribe } from '../contract/interaction';
+
+/** Minimal shape used from the SDK, so its full surface never leaks into typing. */
+interface MessagingModule {
+	(): MessagingInstance;
+	AuthorizationStatus?: Record<string, number>;
+}
+
+interface MessagingInstance {
+	getToken(): Promise<string>;
+	deleteToken(): Promise<void>;
+	onTokenRefresh(handler: (token: string) => void): () => void;
+	onMessage(handler: (message: unknown) => Promise<void> | void): () => void;
+	setBackgroundMessageHandler(handler: (message: unknown) => Promise<void>): void;
+	getInitialNotification(): Promise<unknown | null>;
+	hasPermission?(): Promise<number>;
+	isDeviceRegisteredForRemoteMessages?: boolean;
+}
+
+const messagingPeer = lazyPeer('@react-native-firebase/messaging', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('@react-native-firebase/messaging') as { default: MessagingModule };
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+function loadMessaging(): MessagingModule | undefined {
+	// Absent optional peer, or missing native module: reported as unavailability
+	// through the normal path rather than thrown at import.
+	const result = messagingPeer.get();
+	return result.ok ? result.module.default : undefined;
+}
+
+export interface FcmProviderOptions {
+	/** Injected in tests; production resolves the real module. */
+	readonly module?: MessagingModule;
+	/**
+	 * Registers the background message handler.
+	 *
+	 * Left to the consumer by default because the SDK requires it to be
+	 * registered at module scope in `index.js`, outside React's lifecycle — a
+	 * constraint the package documents rather than works around.
+	 */
+	readonly onBackgroundMessage?: (message: unknown) => Promise<void>;
+}
+
+export function createFcmProvider(options: FcmProviderOptions = {}): PushProviderAdapter {
+	let cached: MessagingModule | undefined = options.module;
+	let resolved = options.module !== undefined;
+
+	const messaging = (): MessagingInstance | undefined => {
+		if (!resolved) {
+			cached = loadMessaging();
+			resolved = true;
+		}
+		return cached?.();
+	};
+
+	if (options.onBackgroundMessage !== undefined) {
+		messaging()?.setBackgroundMessageHandler(options.onBackgroundMessage);
+	}
+
+	return {
+		name: '@react-native-firebase/messaging',
+
+		async getAvailability(): Promise<PushAvailability> {
+			const instance = messaging();
+
+			// A device without Google Play Services, or an app that never installed
+			// the optional peer. Either way the local path is unaffected.
+			if (instance === undefined) return 'unavailable';
+
+			try {
+				await instance.getToken();
+				return 'available';
+			} catch {
+				// Registration can fail for reasons the SDK does not distinguish, so
+				// `unknown` is reported rather than a guess at which one.
+				return 'unknown';
+			}
+		},
+
+		async getToken(): Promise<string> {
+			const instance = messaging();
+			if (instance === undefined) {
+				throw new Error('Push provider is unavailable on this device.');
+			}
+			// Resolves only once a genuine token exists; the gate never presents an
+			// empty value as if it were one.
+			return instance.getToken();
+		},
+
+		onTokenChange(handler: (token: string) => void): Unsubscribe {
+			const instance = messaging();
+			if (instance === undefined) return () => undefined;
+			return instance.onTokenRefresh(handler);
+		},
+
+		async invalidateToken(): Promise<boolean> {
+			const instance = messaging();
+			if (instance === undefined) return false;
+
+			try {
+				await instance.deleteToken();
+				return true;
+			} catch {
+				// Reported as a failed invalidation rather than assumed successful —
+				// the device may keep receiving the previous account's messages.
+				return false;
+			}
+		},
+
+		subscribeToMessages(handler: (raw: unknown) => void): Unsubscribe {
+			const instance = messaging();
+			if (instance === undefined) return () => undefined;
+
+			// Foreground only. Background delivery arrives through the handler the
+			// consumer registers at module scope, which the README documents.
+			return instance.onMessage(message => {
+				handler(message);
+			});
+		},
+
+		async takeInitialMessage(): Promise<unknown | undefined> {
+			const instance = messaging();
+			if (instance === undefined) return undefined;
+
+			const message = await instance.getInitialNotification();
+			return message ?? undefined;
+		},
+	};
+}