@chipmobilesdk/rn-notification 0.1.1 → 0.2.0

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/instructions.ts

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