@chipmobilesdk/rn-notification 0.3.0 → 0.4.1

package/src/push/gate.ts

@@ -1,190 +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>;
+/**
+ * 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

@@ -1,29 +1,33 @@
-/**
- * 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';
+/**
+ * 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';