@chipmobilesdk/rn-notification 0.1.0

package/src/push/fcm-provider.ts

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

package/src/push/gate.ts

@@ -0,0 +1,190 @@
+/**
+ * The push gate.
+ *
+ * Everything a consumer sees about push comes through here, in one normalized
+ * shape with zero provider types. Substituting a provider is therefore an
+ * adapter swap rather than a consumer rewrite.
+ *
+ * Two behaviours are deliberate and easy to get wrong. A push arriving in the
+ * **foreground is never auto-displayed** — presentation is the app's decision,
+ * and a library that decided for it would fight every consumer's design. And a
+ * malformed payload is **dropped safely**, because a broken message from a
+ * server must not be able to crash an installed app.
+ */
+
+import type { PushEnvelope, PushProviderAdapter, PushAvailability } from './provider-adapter';
+import type { StateManager } from '../state/record';
+import type { Unsubscribe } from '../contract/interaction';
+import { DIAGNOSTIC_CODES, isNotificationError } from '../contract/errors';
+import { normalizeEnvelope, IMPLEMENTED_PAYLOAD_VERSION } from './envelope';
+import { recordSeen } from '../state/dedup-ledger';
+
+export type PushHandler = (envelope: PushEnvelope) => void | Promise<void>;
+
+export interface PushGateDependencies {
+	readonly provider: PushProviderAdapter;
+	readonly state: StateManager;
+	readonly now: () => number;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export type UndeliverableCause =
+	| 'missingPermission'
+	| 'expiredToken'
+	| 'platformRestriction'
+	| 'malformedPayload'
+	| 'suspectedRateLimit';
+
+export function createPushGate(deps: PushGateDependencies) {
+	const emit = deps.emit ?? (() => {});
+	let handlers: PushHandler[] = [];
+	let subscription: Unsubscribe | undefined;
+	let tokenSubscription: Unsubscribe | undefined;
+	let deliveryChain: Promise<void> = Promise.resolve();
+
+	const dispatch = (envelope: PushEnvelope): void => {
+		deliveryChain = deliveryChain.then(async () => {
+			for (const handler of handlers) {
+				try {
+					await handler(envelope);
+				} catch {
+					// A consumer's handler failing must not stop the next payload.
+				}
+			}
+		});
+	};
+
+	const receive = (raw: unknown): PushEnvelope | undefined => {
+		let normalized;
+		try {
+			normalized = normalizeEnvelope(raw, deps.now());
+		} catch (error) {
+			// Dropped safely and recorded. A broken message must never crash the app
+			// or corrupt the local schedule.
+			emit(
+				DIAGNOSTIC_CODES.PAYLOAD_MALFORMED,
+				isNotificationError(error)
+					? error.message
+					: 'Push payload could not be interpreted and was discarded.',
+				isNotificationError(error) ? error.context : undefined,
+			);
+			return undefined;
+		}
+
+		const { envelope, versionSkew } = normalized;
+
+		if (versionSkew) {
+			emit(
+				DIAGNOSTIC_CODES.PAYLOAD_VERSION_SKEW,
+				`Push payload declares contract version ${envelope.version}; this build implements ${IMPLEMENTED_PAYLOAD_VERSION}. Processed best-effort — known fields honoured, unknown fields ignored.`,
+				{ received: envelope.version, implemented: IMPLEMENTED_PAYLOAD_VERSION },
+			);
+		}
+
+		// Deduplication survives process death, which is the case that matters:
+		// a redelivery usually arrives in a fresh process.
+		if (recordSeen(deps.state, envelope.dedupId, deps.now(), envelope.ownerTag)) {
+			emit(
+				DIAGNOSTIC_CODES.PAYLOAD_DUPLICATE,
+				'Push payload was already handled and was suppressed.',
+				{ dedupId: envelope.dedupId },
+			);
+			return undefined;
+		}
+
+		dispatch(envelope);
+		return envelope;
+	};
+
+	return {
+		/** Reports whether platform push services exist, so degradation is controlled. */
+		async getAvailability(): Promise<PushAvailability> {
+			const availability = await deps.provider.getAvailability();
+
+			if (availability === 'unavailable') {
+				emit(
+					DIAGNOSTIC_CODES.PUSH_UNAVAILABLE,
+					'Platform push services are unavailable on this device. The push path is disabled; the entire local notification path is unaffected.',
+				);
+			}
+			return availability;
+		},
+
+		/** Waits for a genuine token. Never returns a placeholder presented as one. */
+		async getToken(): Promise<string> {
+			const token = await deps.provider.getToken();
+
+			if (typeof token !== 'string' || token.length === 0) {
+				emit(
+					DIAGNOSTIC_CODES.TOKEN_UNAVAILABLE,
+					'The provider has no registration token yet. An empty value is never returned as if it were one.',
+				);
+				throw new Error('Push token is not yet available.');
+			}
+			// The token value itself is never logged.
+			return token;
+		},
+
+		onTokenChange(handler: (token: string) => void): Unsubscribe {
+			tokenSubscription = deps.provider.onTokenChange(handler);
+			return tokenSubscription;
+		},
+
+		async invalidateToken(): Promise<boolean> {
+			const ok = await deps.provider.invalidateToken();
+
+			if (!ok) {
+				emit(
+					DIAGNOSTIC_CODES.TOKEN_INVALIDATION_FAILED,
+					'Token invalidation did not succeed. The device may keep receiving messages for the previous account.',
+				);
+			}
+			return ok;
+		},
+
+		/**
+		 * Subscribes to inbound payloads.
+		 *
+		 * Nothing is displayed automatically — the consumer decides whether and how
+		 * to present a foreground push.
+		 */
+		onPushReceived(handler: PushHandler): Unsubscribe {
+			handlers.push(handler);
+			subscription ??= deps.provider.subscribeToMessages(receive);
+
+			return () => {
+				handlers = handlers.filter(h => h !== handler);
+			};
+		},
+
+		/** Processes the payload that launched the app, if any. */
+		async collectInitial(): Promise<PushEnvelope | undefined> {
+			const raw = await deps.provider.takeInitialMessage();
+			return raw === undefined ? undefined : receive(raw);
+		},
+
+		/** Reports a specific cause rather than leaving a non-delivery unexplained. */
+		reportUndeliverable(cause: UndeliverableCause, context?: Record<string, unknown>): void {
+			emit(
+				DIAGNOSTIC_CODES.PUSH_UNDELIVERABLE,
+				`A push could not be delivered or displayed: ${cause}.`,
+				{ cause, ...context },
+			);
+		},
+
+		/** Exposed for tests and orderly shutdown. */
+		async flush(): Promise<void> {
+			await deliveryChain;
+		},
+
+		dispose(): void {
+			subscription?.();
+			tokenSubscription?.();
+			subscription = undefined;
+			tokenSubscription = undefined;
+			handlers = [];
+		},
+	};
+}
+
+export type PushGate = ReturnType<typeof createPushGate>;

package/src/push/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Push surface: `@chipmobilesdk/rn-notification/push`
+ *
+ * Separate from the default entrypoint so an app that never imports this ships
+ * zero provider code, zero push permissions, and zero entitlements — and takes
+ * on none of the provider's data-collection declarations.
+ */
+
+export { createPushGate } from './gate';
+export type { PushGate, PushGateDependencies, PushHandler, UndeliverableCause } from './gate';
+
+export { createFcmProvider } from './fcm-provider';
+export type { FcmProviderOptions } from './fcm-provider';
+
+export { createSignOut } from './signout';
+export type { SignOut, SignOutDependencies, SignOutResult } from './signout';
+
+export { createInstructionHandler } from './instructions';
+export type { InstructionHandler, InstructionDependencies, InstructionOutcome } from './instructions';
+
+export { normalizeEnvelope, IMPLEMENTED_PAYLOAD_VERSION } from './envelope';
+export type { NormalizeResult } from './envelope';
+
+export type {
+	PushProviderAdapter,
+	PushEnvelope,
+	PushConfig,
+	PushAvailability,
+} from './provider-adapter';

package/src/push/instructions.ts

@@ -0,0 +1,109 @@
+/**
+ * Push-driven local scheduling.
+ *
+ * Where the two paths meet. A server can schedule or cancel a local
+ * notification, and it gets **no privileged path**: an instruction arriving by
+ * push passes exactly the same identifier validation, moment validation, tone
+ * resolution, and permission rules as a request from app code.
+ *
+ * That symmetry is the point. A server that could bypass validation would be
+ * able to put the device into a state the app itself could not produce, and no
+ * amount of local correctness would survive it.
+ */
+
+import type { PushEnvelope } from './provider-adapter';
+import type { Scheduler } from '../schedule';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import { DIAGNOSTIC_CODES, isNotificationError } from '../contract/errors';
+
+export interface InstructionDependencies {
+	readonly scheduler: Scheduler;
+	readonly engine: NotificationEngineAdapter;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export type InstructionOutcome =
+	| { readonly kind: 'scheduled'; readonly id: string; readonly replaced: boolean }
+	| { readonly kind: 'cancelled'; readonly id: string }
+	| { readonly kind: 'suppressed'; readonly id: string; readonly reason: string }
+	| { readonly kind: 'rejected'; readonly id: string; readonly code: string; readonly reason: string }
+	| { readonly kind: 'ignored'; readonly id: string };
+
+export function createInstructionHandler(deps: InstructionDependencies) {
+	const emit = deps.emit ?? (() => {});
+
+	/**
+	 * Whether a local schedule already covers this event.
+	 *
+	 * Local wins: it is the entry the device can present at the right moment with
+	 * no network. A server that genuinely wants to override sends an explicit
+	 * cancel followed by a schedule, which is unambiguous in a way "last write
+	 * wins" is not.
+	 */
+	const localAlreadyCovers = async (id: string): Promise<boolean> => {
+		const pending = await deps.engine.getPending();
+		const existing = pending.find(entry => entry.id === id);
+		return existing !== undefined && !existing.pushCreated;
+	};
+
+	return {
+		async handle(envelope: PushEnvelope): Promise<InstructionOutcome> {
+			if (envelope.kind !== 'schedule' && envelope.kind !== 'cancel') {
+				return { kind: 'ignored', id: envelope.id };
+			}
+
+			try {
+				if (envelope.kind === 'cancel') {
+					await deps.scheduler.cancel(envelope.id);
+					return { kind: 'cancelled', id: envelope.id };
+				}
+
+				if (envelope.moment === undefined || envelope.content === undefined) {
+					throw Object.assign(
+						new Error('A schedule instruction must carry both a moment and content.'),
+						{ code: DIAGNOSTIC_CODES.PAYLOAD_MALFORMED },
+					);
+				}
+
+				if (await localAlreadyCovers(envelope.id)) {
+					emit(
+						DIAGNOSTIC_CODES.PAYLOAD_DUPLICATE,
+						'A local schedule already covers this event; the push instruction was suppressed so the user sees exactly one notification.',
+						{ id: envelope.id },
+					);
+					return {
+						kind: 'suppressed',
+						id: envelope.id,
+						reason: 'A local schedule already covers this event.',
+					};
+				}
+
+				const result = await deps.scheduler.schedule(
+					{
+						id: envelope.id,
+						content: envelope.content,
+						tone: envelope.tone ?? '',
+						moment: envelope.moment,
+						routing: envelope.routing,
+						ownerTag: envelope.ownerTag,
+					},
+					{ pushCreated: true },
+				);
+
+				return { kind: 'scheduled', id: envelope.id, replaced: result.replaced };
+			} catch (error) {
+				// Rejected under exactly the rules an app-initiated request would face,
+				// and recorded rather than swallowed.
+				const code = isNotificationError(error)
+					? error.code
+					: ((error as { code?: string }).code ?? 'UNKNOWN');
+				const reason = error instanceof Error ? error.message : String(error);
+
+				emit(code, `Push instruction rejected: ${reason}`, { id: envelope.id });
+				return { kind: 'rejected', id: envelope.id, code, reason };
+			}
+		},
+	};
+}
+
+export type InstructionHandler = ReturnType<typeof createInstructionHandler>;

package/src/push/provider-adapter.ts

@@ -0,0 +1,54 @@
+/**
+ * The port every push provider satisfies.
+ *
+ * No provider type appears in any signature, which is what makes swapping the
+ * provider cost the consumer nothing.
+ */
+
+import type { RoutingPayload, NotificationContent } from '../contract/notification';
+import type { Unsubscribe } from '../contract/interaction';
+
+/** The single normalized shape every provider's payload is reduced to. */
+export interface PushEnvelope {
+	/** Contract version carried by the payload. See contracts/push-payload.md. */
+	readonly version: number;
+	readonly kind: 'display' | 'data' | 'schedule' | 'cancel';
+	readonly id: string;
+	readonly ownerTag?: string;
+	readonly content?: NotificationContent;
+	readonly tone?: string;
+	readonly moment?: { readonly at: number; readonly anchoring?: 'wallClock' | 'absolute' };
+	readonly routing?: RoutingPayload;
+	/** De-duplication key, falling back to `id` when absent. */
+	readonly dedupId: string;
+	readonly receivedAt: number;
+	/**
+	 * True when the payload declared a version this build does not implement and
+	 * was processed best-effort, honouring known fields and ignoring the rest.
+	 */
+	readonly versionSkew: boolean;
+}
+
+export interface PushConfig {
+	/** Called when the provider reports a new or refreshed registration token. */
+	readonly onTokenChange?: (token: string) => void;
+}
+
+export type PushAvailability = 'available' | 'unavailable' | 'unknown';
+
+export interface PushProviderAdapter {
+	readonly name: string;
+
+	/** Reports whether platform push services exist, so degradation is controlled rather than opaque. */
+	getAvailability(): Promise<PushAvailability>;
+
+	/** Waits for a genuine token. Never returns a placeholder presented as a token. */
+	getToken(): Promise<string>;
+	onTokenChange(handler: (token: string) => void): Unsubscribe;
+	invalidateToken(): Promise<boolean>;
+
+	/** Raw provider payloads, normalized by the gate rather than by the adapter. */
+	subscribeToMessages(handler: (raw: unknown) => void): Unsubscribe;
+	/** A payload that launched the app, consumed exactly once. */
+	takeInitialMessage(): Promise<unknown | undefined>;
+}

package/src/push/signout.ts

@@ -0,0 +1,65 @@
+/**
+ * Sign-out cleanup.
+ *
+ * Three things must happen together, and the order matters: invalidate the
+ * token first so no further messages arrive for the account being left, then
+ * cancel its notifications, then clear its persisted state.
+ *
+ * Deliberately **scoped to one owner tag**. On a shared device, signing one
+ * account out must not clear another's deduplication history or cancel their
+ * reminders — and must not discard the channel migration ledger, which
+ * describes the device rather than any account.
+ */
+
+import type { PushGate } from './gate';
+import type { Scheduler } from '../schedule';
+import type { StateManager } from '../state/record';
+import { clearOwner } from '../state/reset';
+
+export interface SignOutDependencies {
+	readonly scheduler: Scheduler;
+	readonly state: StateManager;
+	/** Absent for a local-only app, which still needs the rest of the cleanup. */
+	readonly push?: PushGate;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export interface SignOutResult {
+	readonly ownerTag: string;
+	readonly tokenInvalidated: boolean;
+	readonly cancelledIds: readonly string[];
+	readonly clearedCollections: readonly string[];
+}
+
+export function createSignOut(deps: SignOutDependencies) {
+	return {
+		async signOut(ownerTag: string): Promise<SignOutResult> {
+			// Token first: stop the inbound flow before removing what would have
+			// handled it, so nothing arrives for an account that is already gone.
+			let tokenInvalidated = false;
+			if (deps.push !== undefined) {
+				try {
+					tokenInvalidated = await deps.push.invalidateToken();
+				} catch {
+					// A failed invalidation must not prevent local cleanup — leaving a
+					// signed-out account's notifications on the device is the worse of
+					// the two outcomes.
+					tokenInvalidated = false;
+				}
+			}
+
+			const cancelledIds = await deps.scheduler.cancelByOwner(ownerTag);
+			const { clearedCollections } = clearOwner(deps.state, ownerTag);
+
+			deps.emit?.(
+				'SIGN_OUT',
+				`Signed out ${ownerTag}: token ${tokenInvalidated ? 'invalidated' : 'not invalidated'}, ${cancelledIds.length} notification(s) cancelled, per-owner state cleared.`,
+				{ ownerTag, tokenInvalidated, cancelled: cancelledIds.length },
+			);
+
+			return { ownerTag, tokenInvalidated, cancelledIds, clearedCollections };
+		},
+	};
+}
+
+export type SignOut = ReturnType<typeof createSignOut>;

package/src/reconcile/chunk.ts

@@ -0,0 +1,53 @@
+/**
+ * Chunked application.
+ *
+ * A 500-entry reconciliation must not drop frames on a list screen, so work is
+ * applied in slices with a yield between them. No single slice may occupy the
+ * interface thread for more than 16 ms, which is what holds 60 fps while
+ * reconciliation is in flight.
+ */
+
+export const DEFAULT_CHUNK_SIZE = 25;
+
+/** Yields to the event loop so the interface thread can render between slices. */
+export function yieldToEventLoop(): Promise<void> {
+	return new Promise(resolve => setTimeout(resolve, 0));
+}
+
+export interface ChunkOptions {
+	readonly size?: number;
+	readonly onYield?: () => Promise<void>;
+}
+
+/**
+ * Applies `work` to every item, yielding between chunks.
+ *
+ * Sequential within a chunk rather than parallel: these calls bridge to native,
+ * and a burst of concurrent scheduling is where duplicate-delivery races come
+ * from.
+ */
+export async function applyInChunks<T>(
+	items: readonly T[],
+	work: (item: T) => Promise<void>,
+	options: ChunkOptions = {},
+): Promise<number> {
+	const size = Math.max(1, options.size ?? DEFAULT_CHUNK_SIZE);
+	const yieldFn = options.onYield ?? yieldToEventLoop;
+	let applied = 0;
+
+	for (let start = 0; start < items.length; start += size) {
+		const chunk = items.slice(start, start + size);
+
+		for (const item of chunk) {
+			await work(item);
+			applied += 1;
+		}
+
+		// No yield after the final chunk — the caller is about to resume anyway.
+		if (start + size < items.length) {
+			await yieldFn();
+		}
+	}
+
+	return applied;
+}