@chipmobilesdk/rn-notification 0.1.1 → 0.2.0

package/src/schedule/index.ts

@@ -1,173 +1,184 @@
-/**
- * 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>;
+/**
+ * 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';
+import { createStopPlacement } from '../repeat/place';
+
+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 stops = createStopPlacement(deps.engine);
+
+	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,
+		});
+
+		await stops.sync(request.id, tone, resolution.at);
+
+		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);
+			// A marker guarding a notification that no longer exists would fire
+			// against nothing. Harmless, but it holds platform capacity a real
+			// notification could use.
+			await stops.release(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);
+			for (const id of ids) await stops.release(id);
+			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);
+			for (const id of ids) await stops.release(id);
+			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

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