@chipmobilesdk/rn-notification 0.1.2 → 0.2.0

package/src/repeat/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Repeat expiry — bounding an alert that repeats until it is handled.
+ *
+ * The one piece of this package a consumer has to wire up themselves. The
+ * engine registers its background task at module scope, outside the React tree,
+ * and no library can perform that registration on an app's behalf.
+ *
+ * An app that declares no repeating tone needs none of this.
+ */
+
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import { createRepeatExpiryHandler } from './expiry';
+
+export { createRepeatExpiryHandler } from './expiry';
+export type { RepeatExpiryHandler, RepeatExpiryDependencies } from './expiry';
+export { REPEAT_STOP_PREFIX, isRepeatStopId, markerIdFor, repeatStopFor } from './marker';
+
+export interface BackgroundHandlerRegistration {
+	readonly engine: NotificationEngineAdapter;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+/**
+ * Registers the handler that ends a repeating alert while the app is dead.
+ *
+ * Call this at module scope in `index.js`, beside the app registration — not
+ * inside a component, and not inside an effect. By the time a component mounts,
+ * the process that needed this handler has already been asked to run it.
+ *
+ * Without it a repeating alert still starts and still stops when the user
+ * handles it, but nothing ends it on a device left face-down on a table. That
+ * is the whole reason the feature exists, so `apply()` reports its absence
+ * rather than letting anyone find out the hard way.
+ */
+export function registerBackgroundNotificationHandler(
+	registration: BackgroundHandlerRegistration,
+): void {
+	const handler = createRepeatExpiryHandler(registration);
+
+	registration.engine.registerBackgroundDeliveryHandler(event => handler.handle(event));
+
+	// Both paths, not just the background one. The engine routes a delivery to
+	// the foreground listener while the app is alive and to the headless task
+	// only when it is not — so registering only the latter leaves the alert
+	// sounding for anyone holding the phone when the window runs out, which is
+	// the one case they would certainly notice.
+	registration.engine.subscribeToDeliveries(event => {
+		// Deliberately not awaited: the engine's foreground listener is
+		// synchronous, and a rejection here must not take the subscription down
+		// with it — a handler that stopped listening would leave every later
+		// alarm unbounded.
+		handler.handle(event).catch(() => {});
+	});
+}

package/src/repeat/marker.ts

@@ -0,0 +1,72 @@
+/**
+ * Stop-marker identity.
+ *
+ * A repeating alert has to end without the app being alive, and no platform
+ * offers "stop the sound at time T but keep the notification". So the package
+ * schedules its own notification at T and reacts to its delivery. That
+ * notification is a *marker*: it exists to be delivered and immediately
+ * removed, never to be read.
+ *
+ * The marker's identifier is derived from the target's by hashing rather than by
+ * concatenation. Concatenation would overflow the package's 128-character
+ * identifier limit for any target already near it, and would make the marker's
+ * identity a function of a value the consumer controls — which is how a
+ * consumer identifier ends up colliding with an internal one.
+ */
+
+import type { RepeatStop } from '../engine/adapter';
+
+/**
+ * Reserved identifier namespace.
+ *
+ * Rejected as a consumer identifier prefix. A consumer id colliding with a
+ * marker would not merely confuse a listing: the expiry handler cancels
+ * markers, so the collision would delete a real notification.
+ */
+export const REPEAT_STOP_PREFIX = 'cms.stop:';
+
+/**
+ * FNV-1a, 32-bit. Deterministic, dependency-free, and stable across releases.
+ *
+ * Bitwise operators are the algorithm, not a micro-optimisation: arithmetic
+ * equivalents would not wrap to 32 bits, and a marker id that changed between
+ * releases would orphan every marker already scheduled on a device.
+ */
+/* eslint-disable no-bitwise */
+function fnv1a(value: string, basis: number): number {
+	let hash = basis;
+	for (let index = 0; index < value.length; index += 1) {
+		hash ^= value.codePointAt(index) ?? 0;
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return hash >>> 0;
+}
+/* eslint-enable no-bitwise */
+
+function hex8(value: number): string {
+	return value.toString(16).padStart(8, '0');
+}
+
+/**
+ * The marker identifier for a target notification.
+ *
+ * Two independent hashes rather than one: a single 32-bit hash collides often
+ * enough to matter once a device holds a handful of alarms, and a collision here
+ * means one alarm's marker silences the other alarm and never silences its own.
+ */
+export function markerIdFor(targetId: string): string {
+	return `${REPEAT_STOP_PREFIX}${hex8(fnv1a(targetId, 0x811c9dc5))}${hex8(fnv1a(targetId, 0x9e3779b9))}`;
+}
+
+export function isRepeatStopId(id: string): boolean {
+	return id.startsWith(REPEAT_STOP_PREFIX);
+}
+
+/** Describes the stop for a target whose alert must end at a known instant. */
+export function repeatStopFor(targetId: string, deliveredAt: number, forMs: number): RepeatStop {
+	return {
+		markerId: markerIdFor(targetId),
+		targetId,
+		dueAt: deliveredAt + forMs,
+	};
+}

package/src/repeat/place.ts

@@ -0,0 +1,73 @@
+/**
+ * Keeping a notification's stop marker in step with the notification.
+ *
+ * Shared by the scheduler and the reconciler rather than written twice. They are
+ * two doors into the same act — reconciliation is how most consumers schedule —
+ * and a bound that only existed on one path would be a bound that mostly did not
+ * exist.
+ */
+
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { ResolvedTone } from '../contract/channel';
+import { repeatStopFor } from './marker';
+
+export interface StopPlacement {
+	/**
+	 * Places the marker for a repeating notification, replacing any it already
+	 * had.
+	 *
+	 * Called on every schedule, replacements included: re-scheduling under an
+	 * identifier that already had one must leave exactly one entry and exactly
+	 * one marker, and the old marker's instant is no longer the right one.
+	 *
+	 * Nothing is placed when the tone does not repeat or the platform will not
+	 * honour repetition, so a non-repeating notification costs no extra platform
+	 * capacity at all.
+	 */
+	sync(targetId: string, tone: ResolvedTone, deliversAt: number): Promise<void>;
+	/** Drops any marker still guarding an identifier. */
+	release(targetId: string): Promise<void>;
+}
+
+export function createStopPlacement(engine: NotificationEngineAdapter): StopPlacement {
+	const release = async (targetId: string): Promise<void> => {
+		const outstanding = await engine.listRepeatStops();
+		const held = outstanding.find(stop => stop.targetId === targetId);
+		if (held !== undefined) {
+			await engine.cancel(held.markerId);
+		}
+	};
+
+	return {
+		release,
+
+		async sync(targetId, tone, deliversAt) {
+			await release(targetId);
+
+			const forMs = tone.android.repeatForMs;
+			if (!tone.android.loopSound || forMs === undefined) return;
+
+			const capabilities = await engine.getCapabilities();
+			if (!capabilities.supportsRepeatingAlert) return;
+
+			const stop = repeatStopFor(targetId, deliversAt, forMs);
+			await engine.schedule({
+				request: {
+					id: stop.markerId,
+					// Deliberately empty. A marker is delivered and removed within the
+					// same handler invocation; anything readable here would be text a
+					// user might glimpse and be confused by.
+					content: { title: '', body: '' },
+					tone: tone.toneId,
+					// Absolute: the bound is a duration from a known instant, not a
+					// wall-clock time that should follow the user across time zones.
+					moment: { at: stop.dueAt, anchoring: 'absolute' },
+				},
+				resolvedAt: stop.dueAt,
+				tone,
+				approximate: false,
+				repeatStop: stop,
+			});
+		},
+	};
+}