@chipmobilesdk/rn-notification 0.1.0

package/src/schedule/anchor.ts

@@ -0,0 +1,267 @@
+/**
+ * Time-zone anchoring and re-anchoring.
+ *
+ * Wall-clock is the default because reminders are wall-clock things: an 08:00
+ * reminder should stay 08:00 after the user crosses a time zone, and a caller
+ * who does not choose should get what their users expect rather than a silent
+ * shift.
+ *
+ * The cost is re-anchoring. When the device zone changes, every scheduled
+ * wall-clock entry must be rewritten to preserve the clock time it named, and
+ * every absolute entry must be left completely alone.
+ *
+ * The limit this cannot fix is stated rather than hidden: a wall-clock
+ * notification whose moment arrives while the app has not run since the zone
+ * changed fires at the previously anchored instant. The anchoring generation on
+ * each entry is what makes that detectable instead of invisible.
+ */
+
+import type { AnchoringMode, PendingEntry } from '../contract/notification';
+import { DEFAULT_ANCHORING_MODE } from '../contract/notification';
+
+/** Reads the platform time zone. Injected so the pure logic needs no native module. */
+export type TimeZoneReader = () => string;
+
+/**
+ * Resolves the platform zone via `react-native-localize`.
+ *
+ * Pure JavaScript is not sufficient here: `Intl.DateTimeFormat().resolvedOptions().timeZone`
+ * is documented in React Native as not reliably updating when the device zone
+ * changes, so it cannot back re-anchoring. Falls back to `Intl` only when the
+ * module is absent, which is better than failing outright.
+ */
+export function createPlatformTimeZoneReader(): TimeZoneReader {
+	return () => {
+		try {
+			const localize = require('react-native-localize') as { getTimeZone(): string };
+			return localize.getTimeZone();
+		} catch {
+			try {
+				return Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
+			} catch {
+				return 'UTC';
+			}
+		}
+	};
+}
+
+/** The calendar fields a wall-clock moment actually names. */
+export interface WallClockParts {
+	readonly year: number;
+	readonly month: number;
+	readonly day: number;
+	readonly hour: number;
+	readonly minute: number;
+	readonly second: number;
+}
+
+/**
+ * Whether a zone name is one the runtime can actually format against.
+ *
+ * Hermes throws a hard `JSRangeErrorException: Invalid timezone name!` for a
+ * bad zone, which kills the JavaScript thread rather than returning an error.
+ * A stored anchoring generation is data that can be wrong — a corrupted record,
+ * an entry written by an older build, or a defect like the one that stored a
+ * tone id here — so it must be checked before it reaches `Intl`.
+ */
+export function isValidTimeZone(timeZone: string): boolean {
+	if (timeZone.length === 0) return false;
+	try {
+		new Intl.DateTimeFormat('en-US', { timeZone }).format(0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Decomposes an instant into the clock reading it produces in a given zone.
+ *
+ * Falls back to UTC for an unusable zone rather than throwing: a bad stored
+ * value should degrade one entry's anchoring, not crash the app.
+ */
+export function partsInZone(instant: number, timeZone: string): WallClockParts {
+	const zone = isValidTimeZone(timeZone) ? timeZone : 'UTC';
+	const formatter = new Intl.DateTimeFormat('en-US', {
+		timeZone: zone,
+		year: 'numeric',
+		month: '2-digit',
+		day: '2-digit',
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+		hour12: false,
+	});
+
+	const fields: Record<string, number> = {};
+	for (const part of formatter.formatToParts(new Date(instant))) {
+		if (part.type !== 'literal') {
+			fields[part.type] = Number.parseInt(part.value, 10);
+		}
+	}
+
+	return {
+		year: fields.year,
+		month: fields.month,
+		day: fields.day,
+		// Intl renders midnight as hour 24 in some environments; normalize it.
+		hour: fields.hour === 24 ? 0 : fields.hour,
+		minute: fields.minute,
+		second: fields.second,
+	};
+}
+
+/** The zone's offset from UTC, in milliseconds, at a given instant. */
+function offsetAt(instant: number, timeZone: string): number {
+	const parts = partsInZone(instant, timeZone);
+	const asUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+	return asUtc - Math.floor(instant / 1000) * 1000;
+}
+
+/**
+ * Finds the instant at which a zone shows the given clock reading.
+ *
+ * Two passes, because the offset itself depends on the instant: the first guess
+ * uses the offset at the naive UTC interpretation, the second corrects for a
+ * daylight-saving boundary crossed by that guess.
+ *
+ * Daylight-saving resolution, per the documented rule:
+ * - a clock time that does not exist resolves **forward** to the next valid instant;
+ * - a clock time that occurs twice resolves to its **first** occurrence, so
+ *   exactly one notification results rather than two.
+ */
+export function instantForParts(parts: WallClockParts, timeZone: string): number {
+	const naive = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+
+	let candidate = naive - offsetAt(naive, timeZone);
+	candidate = naive - offsetAt(candidate, timeZone);
+
+	const rendered = partsInZone(candidate, timeZone);
+
+	if (rendered.hour === parts.hour && rendered.minute === parts.minute) {
+		// Ambiguous readings (the repeated hour) land here on the first, earlier
+		// offset, which is the documented choice.
+		return candidate;
+	}
+
+	// The reading does not exist in this zone — a spring-forward gap. Step
+	// forward to the next instant that does exist rather than skipping the
+	// occurrence or failing.
+	const gapStep = 60 * 60 * 1000;
+	for (let attempt = 1; attempt <= 4; attempt += 1) {
+		const shifted = candidate + gapStep * attempt;
+		const shiftedParts = partsInZone(shifted, timeZone);
+		if (shiftedParts.day === parts.day || shiftedParts.hour > parts.hour) {
+			return shifted;
+		}
+	}
+
+	return candidate;
+}
+
+export interface AnchorInput {
+	readonly at: number;
+	readonly anchoring?: AnchoringMode;
+}
+
+export interface AnchoredMoment {
+	readonly resolvedAt: number;
+	readonly anchoring: AnchoringMode;
+	/** The zone this was anchored against. Absent for absolute-instant moments. */
+	readonly generation?: string;
+}
+
+/**
+ * Resolves a caller-supplied moment into a firing instant.
+ *
+ * An absolute moment passes through untouched — that is the entire distinction.
+ */
+export function anchorMoment(input: AnchorInput, timeZone: string): AnchoredMoment {
+	const anchoring = input.anchoring ?? DEFAULT_ANCHORING_MODE;
+
+	if (anchoring === 'absolute') {
+		return { resolvedAt: input.at, anchoring };
+	}
+
+	return { resolvedAt: input.at, anchoring, generation: timeZone };
+}
+
+export interface ReAnchorPlan {
+	/** Entries whose firing instant must be rewritten, with their new instant. */
+	readonly rewrites: readonly { readonly entry: PendingEntry; readonly resolvedAt: number }[];
+	readonly fromZone: string | undefined;
+	readonly toZone: string;
+	readonly zoneChanged: boolean;
+	/**
+	 * Entries carrying an anchoring generation the runtime cannot interpret.
+	 *
+	 * Left alone rather than re-anchored against a guess. Reported so a corrupted
+	 * or older-build record is visible instead of quietly producing wrong firing
+	 * instants.
+	 */
+	readonly unreadableGeneration: readonly string[];
+}
+
+/**
+ * Computes what a zone change requires.
+ *
+ * Returns an empty plan when the zone has not moved, which is what makes
+ * re-anchoring idempotent: the no-change check costs one comparison per entry
+ * and issues zero platform operations.
+ */
+export function planReAnchor(
+	pending: readonly PendingEntry[],
+	currentZone: string,
+): ReAnchorPlan {
+	const rewrites: { entry: PendingEntry; resolvedAt: number }[] = [];
+	const unreadableGeneration: string[] = [];
+	let fromZone: string | undefined;
+
+	for (const entry of pending) {
+		// Absolute-instant entries are never re-anchored, re-scheduled, or touched.
+		if (entry.anchoring === 'absolute') continue;
+
+		const generation = entry.anchoringGeneration;
+		if (generation === undefined || generation === currentZone) continue;
+
+		// A stored generation is data, and data can be wrong. Re-anchoring against
+		// a zone the runtime cannot read would move the entry to an arbitrary
+		// instant, which is worse than leaving it where it is and saying so.
+		if (!isValidTimeZone(generation)) {
+			unreadableGeneration.push(entry.id);
+			continue;
+		}
+
+		fromZone ??= generation;
+
+		// Preserve the clock reading the entry originally named, not the instant.
+		const originalParts = partsInZone(entry.resolvedAt, generation);
+		const resolvedAt = instantForParts(originalParts, currentZone);
+
+		if (resolvedAt !== entry.resolvedAt) {
+			rewrites.push({ entry, resolvedAt });
+		}
+	}
+
+	return {
+		rewrites,
+		fromZone,
+		toZone: currentZone,
+		zoneChanged: rewrites.length > 0 || fromZone !== undefined,
+		unreadableGeneration,
+	};
+}
+
+/**
+ * True when an entry was anchored against a zone the device has since left.
+ *
+ * This is the FR-007c condition: the entry will fire at its old instant, and a
+ * consumer can detect and explain that rather than being told nothing happened.
+ */
+export function isStaleAnchor(entry: PendingEntry, currentZone: string): boolean {
+	return (
+		entry.anchoring === 'wallClock' &&
+		entry.anchoringGeneration !== undefined &&
+		entry.anchoringGeneration !== currentZone
+	);
+}

package/src/schedule/index.ts

@@ -0,0 +1,173 @@
+/**
+ * The scheduling operations.
+ *
+ * Validation runs in a fixed order and completes entirely before any platform
+ * call: identifier, tags, content, moment shape, tone, actions, routing size.
+ * A caller therefore never sees a native-level error surface through the
+ * package, and a rejected request leaves the device untouched.
+ *
+ * Scheduling an identifier that already has a notification **replaces** it.
+ * That is the defined semantic rather than a side effect, which is what lets a
+ * caller stop tracking whether it has already scheduled something.
+ */
+
+import type {
+	NotificationRequest,
+	PendingEntry,
+	ScheduleResult,
+} from '../contract/notification';
+import type { ResolvedTone } from '../contract/channel';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import {
+	DIAGNOSTIC_CODES,
+	NotificationError,
+} from '../contract/errors';
+import { MAX_ACTIONS_PER_NOTIFICATION, MAX_ROUTING_PAYLOAD_BYTES } from '../contract/interaction';
+import { validateIdentifier, validateOptionalTag } from './validate-identifier';
+import { validateContent, byteLength } from './validate-content';
+import { resolveMoment, validateMoment } from './resolve-moment';
+import { anchorMoment, type TimeZoneReader } from './anchor';
+import { idsForTag } from './partition';
+
+export interface ScheduleDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly resolveTone: (toneId: string) => ResolvedTone | undefined;
+	readonly timeZone: TimeZoneReader;
+	readonly now: () => number;
+	/** False when exact-alarm capability is unavailable, forcing approximate mode. */
+	readonly canScheduleExactly: () => boolean;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+/** Validates a request completely, before the engine is touched at all. */
+export function validateRequest(
+	request: NotificationRequest,
+	resolveTone: (toneId: string) => ResolvedTone | undefined,
+): ResolvedTone {
+	validateIdentifier(request.id, 'id');
+	validateOptionalTag(request.ownerTag, 'ownerTag');
+	validateOptionalTag(request.groupTag, 'groupTag');
+	validateContent(request.content);
+	validateMoment(request.moment);
+
+	const tone = resolveTone(request.tone);
+	if (tone === undefined) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.UNDECLARED_TONE,
+			`Tone "${request.tone}" was never declared in the package configuration. Declare it before scheduling against it.`,
+			{ toneId: request.tone },
+		);
+	}
+
+	if (request.actions !== undefined) {
+		if (request.actions.length > MAX_ACTIONS_PER_NOTIFICATION) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.TOO_MANY_ACTIONS,
+				`A notification may carry at most ${MAX_ACTIONS_PER_NOTIFICATION} actions; ${request.actions.length} were supplied.`,
+				{ count: request.actions.length, limit: MAX_ACTIONS_PER_NOTIFICATION },
+			);
+		}
+		for (const action of request.actions) {
+			validateIdentifier(action.id, 'actionId');
+		}
+	}
+
+	if (request.routing !== undefined) {
+		// Sized at schedule time rather than discovered as truncated at tap time,
+		// which is where an over-large payload would otherwise surface.
+		const size = byteLength(JSON.stringify(request.routing));
+		if (size > MAX_ROUTING_PAYLOAD_BYTES) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.ROUTING_PAYLOAD_TOO_LARGE,
+				`Routing payload is ${size} bytes, over the ${MAX_ROUTING_PAYLOAD_BYTES}-byte limit.`,
+				{ bytes: size, limit: MAX_ROUTING_PAYLOAD_BYTES },
+			);
+		}
+	}
+
+	return tone;
+}
+
+export function createScheduler(deps: ScheduleDependencies) {
+	const emit = deps.emit ?? (() => {});
+
+	const scheduleOne = async (
+		request: NotificationRequest,
+		options: { readonly seriesId?: string; readonly pushCreated?: boolean } = {},
+	): Promise<ScheduleResult> => {
+		const tone = validateRequest(request, deps.resolveTone);
+
+		const zone = deps.timeZone();
+		const anchored = anchorMoment(request.moment, zone);
+		const resolution = resolveMoment(anchored.resolvedAt, deps.now());
+
+		const existing = await deps.engine.getPending();
+		const replaced = existing.some(entry => entry.id === request.id);
+
+		// Approximate mode is a degradation, not a refusal: the notification is
+		// still scheduled and the caller is told it may arrive late.
+		const approximate = !deps.canScheduleExactly();
+		if (approximate) {
+			emit(
+				DIAGNOSTIC_CODES.EXACT_ALARM_UNAVAILABLE,
+				'Scheduled in approximate mode; delivery may be late.',
+				{ id: request.id },
+			);
+		}
+
+		await deps.engine.schedule({
+			request,
+			resolvedAt: resolution.at,
+			tone,
+			// The zone this was anchored against, so `getPending` can report it and a
+			// consumer can detect a stale anchor (FR-007c). Absent for absolute
+			// moments, which are never anchored to a zone.
+			anchoringGeneration: anchored.generation,
+			approximate,
+			seriesId: options.seriesId,
+			pushCreated: options.pushCreated,
+		});
+
+		return {
+			id: request.id,
+			resolvedAt: resolution.at,
+			anchoring: anchored.anchoring,
+			replaced,
+			deliveredImmediately: resolution.kind === 'immediate',
+			mayBeDelayed: approximate,
+		};
+	};
+
+	return {
+		schedule: scheduleOne,
+
+		async cancel(id: string): Promise<void> {
+			validateIdentifier(id, 'id');
+			await deps.engine.cancel(id);
+		},
+
+		async cancelByGroup(groupTag: string): Promise<readonly string[]> {
+			validateIdentifier(groupTag, 'groupTag');
+			const ids = idsForTag(await deps.engine.getPending(), 'group', groupTag);
+			await deps.engine.cancelMany(ids);
+			return ids;
+		},
+
+		async cancelByOwner(ownerTag: string): Promise<readonly string[]> {
+			validateIdentifier(ownerTag, 'ownerTag');
+			const ids = idsForTag(await deps.engine.getPending(), 'owner', ownerTag);
+			await deps.engine.cancelMany(ids);
+			return ids;
+		},
+
+		async cancelAll(): Promise<void> {
+			await deps.engine.cancelAll();
+		},
+
+		async getPending(): Promise<readonly PendingEntry[]> {
+			return deps.engine.getPending();
+		},
+	};
+}
+
+export type Scheduler = ReturnType<typeof createScheduler>;

package/src/schedule/partition.ts

@@ -0,0 +1,85 @@
+/**
+ * Owner-tag and group-tag partitioning.
+ *
+ * A tag is an opaque label the caller supplies and the package never
+ * interprets. That is deliberate: modelling identity would mean acquiring an
+ * opinion about it, and this package is forbidden from knowing anything about
+ * accounts, tenants, or users.
+ *
+ * What the tag buys is one call — "clear this account's notifications" — on a
+ * shared device, without the package ever learning what an account is.
+ */
+
+import type { PendingEntry } from '../contract/notification';
+
+export type PartitionKind = 'owner' | 'group';
+
+/** Selects entries carrying a tag. Comparison is exact; nothing is normalized. */
+export function selectByTag(
+	entries: readonly PendingEntry[],
+	kind: PartitionKind,
+	tag: string,
+): readonly PendingEntry[] {
+	return entries.filter(entry =>
+		kind === 'owner' ? entry.ownerTag === tag : entry.groupTag === tag,
+	);
+}
+
+/** Identifiers to cancel for a tag. */
+export function idsForTag(
+	entries: readonly PendingEntry[],
+	kind: PartitionKind,
+	tag: string,
+): readonly string[] {
+	return selectByTag(entries, kind, tag).map(entry => entry.id);
+}
+
+/**
+ * Groups entries by a tag, keeping untagged entries under a distinct bucket.
+ *
+ * Untagged is not the same as any tag: an entry with no owner belongs to no
+ * account, and folding it into one would make a sign-out delete notifications
+ * that were never that account's.
+ */
+export function partition(
+	entries: readonly PendingEntry[],
+	kind: PartitionKind,
+): { readonly tagged: ReadonlyMap<string, readonly PendingEntry[]>; readonly untagged: readonly PendingEntry[] } {
+	const tagged = new Map<string, PendingEntry[]>();
+	const untagged: PendingEntry[] = [];
+
+	for (const entry of entries) {
+		const tag = kind === 'owner' ? entry.ownerTag : entry.groupTag;
+		if (tag === undefined) {
+			untagged.push(entry);
+			continue;
+		}
+		const bucket = tagged.get(tag);
+		if (bucket === undefined) {
+			tagged.set(tag, [entry]);
+		} else {
+			bucket.push(entry);
+		}
+	}
+
+	return { tagged, untagged };
+}
+
+/**
+ * True when cancelling `tag` would affect any entry outside it.
+ *
+ * Exists so isolation can be asserted directly rather than inferred from a
+ * count — the property that matters is that one account's sign-out changes
+ * exactly zero of another account's notifications.
+ */
+export function wouldAffectOtherTags(
+	entries: readonly PendingEntry[],
+	kind: PartitionKind,
+	tag: string,
+): boolean {
+	const selected = new Set(idsForTag(entries, kind, tag));
+	return entries.some(entry => {
+		const entryTag = kind === 'owner' ? entry.ownerTag : entry.groupTag;
+		return selected.has(entry.id) && entryTag !== tag;
+	});
+}

package/src/schedule/resolve-moment.ts

@@ -0,0 +1,80 @@
+/**
+ * Delivery moment resolution.
+ *
+ * Two rules, and they are two sides of one decision rather than a threshold:
+ * a moment more than the tolerance in the past is a caller error and is
+ * refused; a moment a few seconds in the past is a processing delay and is
+ * delivered promptly. Both outcomes are reported, so a caller never has to
+ * guess which happened.
+ *
+ * Sixty seconds is long enough to absorb reconciling a large desired set, cold
+ * start work, and clock skew, and short enough that a genuinely stale schedule
+ * is still caught rather than fired at the user minutes late with no
+ * explanation.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+import type { DeliveryMoment } from '../contract/notification';
+
+export const PAST_TOLERANCE_MS = 60_000;
+
+export type MomentResolution =
+	| { readonly kind: 'future'; readonly at: number }
+	| { readonly kind: 'immediate'; readonly at: number; readonly lateBy: number };
+
+/**
+ * Classifies a resolved instant against now.
+ *
+ * Takes an already-anchored instant: anchoring decides *which* instant a moment
+ * means, and this decides whether that instant is usable. Keeping them separate
+ * is what lets each be tested without the other.
+ */
+export function resolveMoment(resolvedAt: number, now: number): MomentResolution {
+	if (!Number.isFinite(resolvedAt)) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.MOMENT_IN_PAST,
+			'A delivery moment must be a finite epoch-millisecond timestamp.',
+			{ received: String(resolvedAt) },
+		);
+	}
+
+	if (resolvedAt >= now) {
+		return { kind: 'future', at: resolvedAt };
+	}
+
+	const lateBy = now - resolvedAt;
+
+	if (lateBy <= PAST_TOLERANCE_MS) {
+		return { kind: 'immediate', at: now, lateBy };
+	}
+
+	throw new NotificationError(
+		DIAGNOSTIC_CODES.MOMENT_IN_PAST,
+		`Delivery moment is ${Math.round(lateBy / 1000)}s in the past, beyond the ${PAST_TOLERANCE_MS / 1000}s tolerance. ` +
+			'It was not scheduled, because handing it to the platform would fire it immediately without explanation.',
+		{ lateByMs: lateBy, toleranceMs: PAST_TOLERANCE_MS },
+	);
+}
+
+/** Validates the shape of a caller-supplied moment before anchoring resolves it. */
+export function validateMoment(moment: DeliveryMoment): void {
+	if (typeof moment.at !== 'number' || !Number.isFinite(moment.at)) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.MOMENT_IN_PAST,
+			'A delivery moment must carry a finite epoch-millisecond `at` value.',
+			{ received: typeof moment.at },
+		);
+	}
+
+	if (
+		moment.anchoring !== undefined &&
+		moment.anchoring !== 'wallClock' &&
+		moment.anchoring !== 'absolute'
+	) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.MOMENT_IN_PAST,
+			'Anchoring must be either "wallClock" or "absolute".',
+			{ received: String(moment.anchoring) },
+		);
+	}
+}