@chipmobilesdk/rn-notification 0.1.0

package/src/initialize.ts

@@ -0,0 +1,174 @@
+/**
+ * Package initialization.
+ *
+ * Composes the parts that must be in place before the first schedule call:
+ * validate configuration, load persisted state, apply tone declarations, run
+ * any pending channel migration, and start the maintenance registry.
+ *
+ * Budgeted at 100 ms of app startup, which is why state loading is synchronous
+ * and tone declaration is the only platform round-trip.
+ */
+
+import type { InitializeResult, NotificationConfig } from './contract/diagnostics';
+import { DEFAULT_LOOKAHEAD, LOOKAHEAD_BOUNDS, type LookaheadConfig } from './contract/recurrence';
+import { DIAGNOSTIC_CODES, NotificationError } from './contract/errors';
+import { DiagnosticEmitter } from './diagnostics/events';
+import { MaintenanceRegistry } from './maintenance/cycle';
+import { MaintenanceController } from './maintenance/toggle';
+import { StateManager } from './state/record';
+import type { StateStore } from './state/store';
+import type { NotificationEngineAdapter } from './engine/adapter';
+
+export interface RuntimeDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly store: StateStore;
+	readonly now?: () => number;
+}
+
+/** Everything assembled at initialization, shared by the operation modules. */
+export interface NotificationRuntime {
+	readonly engine: NotificationEngineAdapter;
+	readonly state: StateManager;
+	readonly emitter: DiagnosticEmitter;
+	readonly registry: MaintenanceRegistry;
+	readonly maintenance: MaintenanceController;
+	readonly lookahead: LookaheadConfig;
+	readonly config: NotificationConfig;
+	readonly now: () => number;
+}
+
+/**
+ * Clamps the lookahead into its documented bounds.
+ *
+ * Bounded on adjustment because the platform ceiling is not negotiable: a
+ * consumer asking for a five-year window would silently exhaust the 64-entry
+ * iOS ceiling on the first frequent series.
+ */
+export function resolveLookahead(partial: Partial<LookaheadConfig> | undefined): LookaheadConfig {
+	const days = partial?.days ?? DEFAULT_LOOKAHEAD.days;
+	const occurrencesPerSeries = partial?.occurrencesPerSeries ?? DEFAULT_LOOKAHEAD.occurrencesPerSeries;
+
+	return {
+		days: Math.min(Math.max(days, LOOKAHEAD_BOUNDS.minDays), LOOKAHEAD_BOUNDS.maxDays),
+		occurrencesPerSeries: Math.min(
+			Math.max(occurrencesPerSeries, LOOKAHEAD_BOUNDS.minOccurrences),
+			LOOKAHEAD_BOUNDS.maxOccurrences,
+		),
+	};
+}
+
+/** Fails before any platform call, so a bad configuration never half-applies. */
+export function validateConfig(config: NotificationConfig): void {
+	if (config.tones.length === 0) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.UNDECLARED_TONE,
+			'At least one tone must be declared before notifications can be scheduled.',
+		);
+	}
+
+	const seen = new Set<string>();
+	for (const tone of config.tones) {
+		if (seen.has(tone.id)) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.UNDECLARED_TONE,
+				`Tone "${tone.id}" is declared more than once.`,
+				{ toneId: tone.id },
+			);
+		}
+		seen.add(tone.id);
+
+		if (!Number.isInteger(tone.version) || tone.version < 1) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
+				`Tone "${tone.id}" must carry an integer version of 1 or greater, because a channel configuration change is a migration rather than an assignment.`,
+				{ toneId: tone.id, version: tone.version },
+			);
+		}
+	}
+
+	const groupIds = new Set((config.channelGroups ?? []).map(group => group.id));
+	for (const tone of config.tones) {
+		if (tone.groupId !== undefined && !groupIds.has(tone.groupId)) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.UNDECLARED_TONE,
+				`Tone "${tone.id}" references undeclared channel group "${tone.groupId}".`,
+				{ toneId: tone.id, groupId: tone.groupId },
+			);
+		}
+	}
+}
+
+export async function initialize(
+	config: NotificationConfig,
+	deps: RuntimeDependencies,
+): Promise<{ runtime: NotificationRuntime; result: InitializeResult }> {
+	const now = deps.now ?? (() => Date.now());
+	const startedAt = now();
+
+	validateConfig(config);
+
+	const emitter = new DiagnosticEmitter({
+		sink: config.eventSink,
+		verbose: config.verboseDiagnostics,
+		now,
+	});
+
+	const state = new StateManager({
+		store: deps.store,
+		now,
+		emit: event => emitter.emit(event.code, describeStateEvent(event.code), event.context),
+	});
+
+	if (config.channelGroups !== undefined && config.channelGroups.length > 0) {
+		await deps.engine.declareGroups(config.channelGroups);
+	}
+
+	const registry = new MaintenanceRegistry();
+	const maintenance = new MaintenanceController({
+		registry,
+		now,
+		// Owned identifiers come from the series ledger: those are the entries
+		// automatic maintenance created and may therefore retire.
+		ownedIds: () => new Set(state.read().seriesLedger.map(entry => entry.seriesId)),
+		enabled: config.automaticMaintenance ?? true,
+	});
+
+	const runtime: NotificationRuntime = {
+		engine: deps.engine,
+		state,
+		emitter,
+		registry,
+		maintenance,
+		lookahead: resolveLookahead(config.lookahead),
+		config,
+		now,
+	};
+
+	return {
+		runtime,
+		result: {
+			// Tone application and migration are performed by the channel module,
+			// which registers itself during User Story 5.
+			tonesApplied: 0,
+			migrationsRun: 0,
+			stateRebuilt: state.health().rebuilt,
+			automaticMaintenance: maintenance.isEnabled,
+			durationMs: now() - startedAt,
+		},
+	};
+}
+
+function describeStateEvent(code: string): string {
+	switch (code) {
+		case DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT:
+			return 'Persisted state was unreadable and has been rebuilt. Deduplication history and buffered interactions from before the loss are gone; scheduled notifications are unaffected.';
+		case DIAGNOSTIC_CODES.STATE_WRITE_FAILED:
+			return 'Persisted state could not be written. The affected guarantee degrades to this session only.';
+		case DIAGNOSTIC_CODES.STATE_CAP_EVICTED:
+			return 'A persisted collection reached its cap and the oldest entries were evicted.';
+		case DIAGNOSTIC_CODES.INTERACTION_BUFFER_EVICTED:
+			return 'Buffered interactions were evicted at the cap or retention limit.';
+		default:
+			return 'Persisted state event.';
+	}
+}

package/src/interaction/index.ts

@@ -0,0 +1,146 @@
+/**
+ * Interaction routing.
+ *
+ * One handler covers foreground, background, and cold start. The hard case is
+ * the last one: the tap happens before any JavaScript exists to receive it, so
+ * the event has to wait — durably — until a handler registers.
+ *
+ * Events are delivered in occurrence order and never dropped for want of a
+ * listener. After delivery the notification leaves the tray, because a
+ * notification the user has already acted on sitting there is noise.
+ */
+
+import type {
+	InteractionEvent,
+	InteractionHandler,
+	TargetMissingSignal,
+	Unsubscribe,
+} from '../contract/interaction';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { StateManager } from '../state/record';
+import { DIAGNOSTIC_CODES } from '../contract/errors';
+import { buffer, bufferedCount, drain } from '../state/interaction-buffer';
+
+export interface InteractionDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly state: StateManager;
+	readonly now: () => number;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export function createInteractions(deps: InteractionDependencies) {
+	const emit = deps.emit ?? (() => {});
+	let handlers: InteractionHandler[] = [];
+	let engineSubscription: Unsubscribe | undefined;
+	/** Serializes delivery so rapid interactions arrive in order, never interleaved. */
+	let deliveryChain: Promise<void> = Promise.resolve();
+
+	const deliver = (event: InteractionEvent): void => {
+		deliveryChain = deliveryChain.then(async () => {
+			for (const handler of handlers) {
+				try {
+					await handler(event);
+				} catch {
+					// A consumer's handler failing must not stop the next event, or one
+					// bad tap would silently swallow every tap after it.
+				}
+			}
+
+			// Acted on, so it leaves the tray and stops making noise.
+			if (event.kind !== 'dismiss') {
+				await deps.engine.cancel(event.notificationId).catch(() => undefined);
+			}
+		});
+	};
+
+	const route = (event: InteractionEvent): void => {
+		if (handlers.length === 0) {
+			buffer(deps.state, event);
+			return;
+		}
+		deliver(event);
+	};
+
+	const ensureSubscribed = (): void => {
+		engineSubscription ??= deps.engine.subscribeToInteractions(route);
+	};
+
+	// Subscribing immediately rather than on first handler registration: an
+	// interaction arriving in the gap would otherwise be lost entirely, which is
+	// the exact failure the buffer exists to prevent.
+	ensureSubscribed();
+
+	return {
+		/**
+		 * Registers a handler and immediately drains anything that was waiting.
+		 *
+		 * The drain is what makes a cold-start tap work: the event was persisted
+		 * before this handler existed, possibly before this process existed.
+		 */
+		onInteraction(handler: InteractionHandler): Unsubscribe {
+			handlers.push(handler);
+
+			for (const event of drain(deps.state)) {
+				deliver(event);
+			}
+
+			return () => {
+				handlers = handlers.filter(h => h !== handler);
+			};
+		},
+
+		/**
+		 * Collects the interaction that launched the app, if any.
+		 *
+		 * Called once during startup. If no handler exists yet the event is
+		 * buffered rather than discarded.
+		 */
+		async collectInitial(): Promise<void> {
+			const initial = await deps.engine.takeInitialInteraction();
+			if (initial === undefined) return;
+			route(initial);
+		},
+
+		/**
+		 * Signals that a routing target no longer exists.
+		 *
+		 * The consumer chooses its own fallback screen. No platform error is ever
+		 * shown to the user for this — a notification pointing at deleted data is
+		 * an ordinary condition, not a crash.
+		 */
+		reportTargetMissing(signal: TargetMissingSignal): void {
+			emit(
+				DIAGNOSTIC_CODES.TARGET_MISSING,
+				'The routing target no longer exists. The consumer chooses a fallback; no platform error is shown to the user.',
+				{ notificationId: signal.notificationId },
+			);
+		},
+
+		/** Reports that a background action exceeded the platform's execution window. */
+		reportBackgroundTimeout(notificationId: string, windowMs: number): void {
+			emit(
+				DIAGNOSTIC_CODES.BACKGROUND_WINDOW_EXCEEDED,
+				`A background action exceeded the platform's ${windowMs} ms execution window and was cut short.`,
+				{ notificationId, windowMs },
+			);
+		},
+
+		/** How many interactions are waiting for a handler. */
+		pendingCount(): number {
+			return bufferedCount(deps.state);
+		},
+
+		/** Settles outstanding deliveries. Exists for tests and orderly shutdown. */
+		async flush(): Promise<void> {
+			await deliveryChain;
+		},
+
+		dispose(): void {
+			engineSubscription?.();
+			engineSubscription = undefined;
+			handlers = [];
+		},
+	};
+}
+
+export type Interactions = ReturnType<typeof createInteractions>;

package/src/maintenance/cycle.ts

@@ -0,0 +1,147 @@
+/**
+ * The automatic maintenance cycle.
+ *
+ * Covers exactly what only the package can know — window refresh, recurrence
+ * expansion, wall-clock re-anchoring, pending-set verification, permission
+ * re-reads. Full desired-set reconciliation is never automatic, because only
+ * the consumer knows what its data implies and a package that guessed would
+ * cancel notifications it does not understand.
+ *
+ * Steps register themselves here rather than being wired in a fixed order. That
+ * is what lets scheduling, reconciliation, recurrence, and permissions each
+ * contribute a step without importing one another.
+ *
+ * The rule that makes automatic work safe: a step may act only on notifications
+ * the package owns, and may never cancel anything else. It is enforced here
+ * rather than trusted to each step.
+ */
+
+import type { MaintenanceResult, PendingDiscrepancy } from '../contract/reconcile';
+
+export type MaintenanceTrigger =
+	| 'foreground'
+	| 'delivery'
+	| 'timeZoneChange'
+	| 'permissionChange'
+	| 'explicit';
+
+export interface MaintenanceContext {
+	readonly trigger: MaintenanceTrigger;
+	readonly now: number;
+	/**
+	 * Identifiers the package owns — series occurrences and entries it created.
+	 * A step may cancel only within this set.
+	 */
+	readonly ownedIds: ReadonlySet<string>;
+}
+
+export interface StepOutcome {
+	readonly occurrencesScheduled?: number;
+	readonly reAnchored?: number;
+	readonly windowRefreshed?: boolean;
+	readonly timeZoneChanged?: boolean;
+	readonly permissionChanged?: boolean;
+	readonly discrepancy?: PendingDiscrepancy;
+	/** Platform operations issued. Zero on a no-change pass. */
+	readonly operationCount?: number;
+	/** Identifiers this step cancelled, checked against `ownedIds`. */
+	readonly cancelledIds?: readonly string[];
+}
+
+export interface MaintenanceStep {
+	readonly name: string;
+	/** Lower runs first. Re-anchoring must precede verification, or verification sees stale instants. */
+	readonly order: number;
+	run(context: MaintenanceContext): Promise<StepOutcome>;
+}
+
+export class MaintenanceScopeViolation extends Error {
+	readonly step: string;
+	readonly offendingIds: readonly string[];
+
+	constructor(step: string, offendingIds: readonly string[]) {
+		super(
+			`Maintenance step "${step}" attempted to cancel ${offendingIds.length} notification(s) it does not own. ` +
+				'Automatic maintenance may never cancel a directly-scheduled notification.',
+		);
+		this.name = 'MaintenanceScopeViolation';
+		this.step = step;
+		this.offendingIds = offendingIds;
+		Object.setPrototypeOf(this, MaintenanceScopeViolation.prototype);
+	}
+}
+
+export class MaintenanceRegistry {
+	private steps: MaintenanceStep[] = [];
+	private running = false;
+
+	register(step: MaintenanceStep): () => void {
+		this.steps.push(step);
+		this.steps.sort((a, b) => a.order - b.order);
+		return () => {
+			this.steps = this.steps.filter(s => s !== step);
+		};
+	}
+
+	get registered(): readonly string[] {
+		return this.steps.map(s => s.name);
+	}
+
+	/**
+	 * Runs every registered step in order.
+	 *
+	 * Overlapping cycles are collapsed rather than queued: a second foreground
+	 * event arriving mid-cycle wants the same work the running cycle is already
+	 * doing.
+	 */
+	async run(context: MaintenanceContext): Promise<MaintenanceResult> {
+		const started = context.now;
+
+		if (this.running) {
+			return {
+				ranAt: started,
+				windowRefreshed: false,
+				occurrencesScheduled: 0,
+				reAnchored: 0,
+				timeZoneChanged: false,
+				permissionChanged: false,
+				operationCount: 0,
+				durationMs: 0,
+			};
+		}
+
+		this.running = true;
+		const aggregate = {
+			windowRefreshed: false,
+			occurrencesScheduled: 0,
+			reAnchored: 0,
+			timeZoneChanged: false,
+			permissionChanged: false,
+			operationCount: 0,
+		};
+		let discrepancy: PendingDiscrepancy | undefined;
+
+		try {
+			for (const step of this.steps) {
+				const outcome = await step.run(context);
+
+				const offending = (outcome.cancelledIds ?? []).filter(id => !context.ownedIds.has(id));
+				if (offending.length > 0) {
+					throw new MaintenanceScopeViolation(step.name, offending);
+				}
+
+				aggregate.windowRefreshed ||= outcome.windowRefreshed ?? false;
+				aggregate.occurrencesScheduled += outcome.occurrencesScheduled ?? 0;
+				aggregate.reAnchored += outcome.reAnchored ?? 0;
+				aggregate.timeZoneChanged ||= outcome.timeZoneChanged ?? false;
+				aggregate.permissionChanged ||= outcome.permissionChanged ?? false;
+				aggregate.operationCount += outcome.operationCount ?? 0;
+				discrepancy ??= outcome.discrepancy;
+			}
+		} finally {
+			this.running = false;
+		}
+
+		return { ranAt: started, ...aggregate, discrepancy, durationMs: 0 };
+	}
+}

package/src/maintenance/permission-refresh.ts

@@ -0,0 +1,41 @@
+/**
+ * The permission re-read maintenance step.
+ *
+ * The user can change permission in system settings while the app is
+ * backgrounded, and the platform does not tell anyone. Re-reading on foreground
+ * is the only way a consumer's interface avoids showing a stale answer.
+ *
+ * Runs last (order 30): permission state does not affect what the earlier steps
+ * expand or re-anchor, and reading it after they have run means the report
+ * reflects the device as the cycle leaves it.
+ */
+
+import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
+import type { Permissions } from '../permission';
+
+export const PERMISSION_REFRESH_ORDER = 30;
+
+export interface PermissionRefreshDependencies {
+	readonly permissions: Permissions;
+}
+
+export function createPermissionRefreshStep(
+	deps: PermissionRefreshDependencies,
+): MaintenanceStep {
+	return {
+		name: 'permission-refresh',
+		order: PERMISSION_REFRESH_ORDER,
+
+		async run(_context: MaintenanceContext): Promise<StepOutcome> {
+			const { changed } = await deps.permissions.refresh();
+
+			return {
+				// Reading permission is not a platform mutation, so it never counts
+				// toward the zero-operation guarantee.
+				operationCount: 0,
+				permissionChanged: changed,
+				cancelledIds: [],
+			};
+		},
+	};
+}

package/src/maintenance/reanchor.ts

@@ -0,0 +1,95 @@
+/**
+ * The re-anchoring maintenance step.
+ *
+ * Registers itself with the maintenance registry rather than being wired into
+ * a fixed sequence, which is what keeps scheduling independent of
+ * reconciliation, recurrence, and permissions despite all four contributing a
+ * step.
+ *
+ * Runs early (order 10) because verification compares firing instants: if
+ * verification ran first it would compare against instants re-anchoring is
+ * about to rewrite, and report discrepancies that do not exist.
+ */
+
+import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { ResolvedTone } from '../contract/channel';
+import { planReAnchor, type TimeZoneReader } from '../schedule/anchor';
+
+export interface ReAnchorStepDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly timeZone: TimeZoneReader;
+	readonly resolveTone: (toneId: string) => ResolvedTone | undefined;
+	readonly canScheduleExactly: () => boolean;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export const RE_ANCHOR_ORDER = 10;
+
+export function createReAnchorStep(deps: ReAnchorStepDependencies): MaintenanceStep {
+	return {
+		name: 'reanchor',
+		order: RE_ANCHOR_ORDER,
+
+		async run(_context: MaintenanceContext): Promise<StepOutcome> {
+			const zone = deps.timeZone();
+			const pending = await deps.engine.getPending();
+			const plan = planReAnchor(pending, zone);
+
+			// The no-change path costs one comparison per entry and issues zero
+			// platform operations. That is what makes re-anchoring idempotent.
+			if (plan.rewrites.length === 0) {
+				return { operationCount: 0, reAnchored: 0, timeZoneChanged: false };
+			}
+
+			deps.emit?.(
+				'REANCHOR',
+				`Device time zone changed from ${plan.fromZone ?? 'unknown'} to ${plan.toZone}; re-anchoring ${plan.rewrites.length} wall-clock notification(s).`,
+				{ from: plan.fromZone, to: plan.toZone, count: plan.rewrites.length },
+			);
+
+			let operationCount = 0;
+
+			for (const { entry, resolvedAt } of plan.rewrites) {
+				const tone = deps.resolveTone(entry.tone);
+				if (tone === undefined) {
+					// A tone that no longer exists means this entry belongs to a
+					// configuration the app has since dropped. Leaving it alone is
+					// correct: re-anchoring must never repair, only preserve.
+					continue;
+				}
+
+				await deps.engine.schedule({
+					request: {
+						id: entry.id,
+						content: entry.content,
+						tone: entry.tone,
+						moment: { at: resolvedAt, anchoring: 'wallClock' },
+						routing: entry.routing,
+						actions: entry.actions,
+						ownerTag: entry.ownerTag,
+						groupTag: entry.groupTag,
+					},
+					resolvedAt,
+					tone,
+					// Re-anchored against the zone the device is in now — this is the
+					// value that stops the entry being reported as stale next time.
+					anchoringGeneration: zone,
+					approximate: !deps.canScheduleExactly(),
+					seriesId: entry.seriesId,
+					pushCreated: entry.pushCreated,
+				});
+				operationCount += 1;
+			}
+
+			return {
+				operationCount,
+				reAnchored: operationCount,
+				timeZoneChanged: true,
+				// Re-anchoring replaces in place and cancels nothing, so it can never
+				// touch a notification outside what it was handed.
+				cancelledIds: [],
+			};
+		},
+	};
+}

package/src/maintenance/toggle.ts

@@ -0,0 +1,60 @@
+/**
+ * The automatic-maintenance switch.
+ *
+ * A package that acts on its own must offer a way to stop it — and a consumer
+ * that takes control must not lose a feature as the price. Disabling automatic
+ * maintenance leaves every operation explicitly invocable through
+ * `runMaintenance()`, producing identical device state.
+ */
+
+import type { MaintenanceResult } from '../contract/reconcile';
+import type { MaintenanceContext, MaintenanceRegistry, MaintenanceTrigger } from './cycle';
+
+export interface MaintenanceControllerOptions {
+	readonly registry: MaintenanceRegistry;
+	readonly now: () => number;
+	readonly ownedIds: () => ReadonlySet<string>;
+	readonly enabled?: boolean;
+}
+
+export class MaintenanceController {
+	private enabled: boolean;
+	private readonly registry: MaintenanceRegistry;
+	private readonly now: () => number;
+	private readonly ownedIds: () => ReadonlySet<string>;
+
+	constructor(options: MaintenanceControllerOptions) {
+		this.registry = options.registry;
+		this.now = options.now;
+		this.ownedIds = options.ownedIds;
+		this.enabled = options.enabled ?? true;
+	}
+
+	get isEnabled(): boolean {
+		return this.enabled;
+	}
+
+	setEnabled(enabled: boolean): void {
+		this.enabled = enabled;
+	}
+
+	/** Called by lifecycle observers. A no-op when automatic maintenance is off. */
+	async runAutomatic(trigger: Exclude<MaintenanceTrigger, 'explicit'>): Promise<MaintenanceResult | undefined> {
+		if (!this.enabled) return undefined;
+		return this.execute(trigger);
+	}
+
+	/** Always runs, regardless of the switch. This is what preserves capability parity. */
+	async runExplicit(): Promise<MaintenanceResult> {
+		return this.execute('explicit');
+	}
+
+	private async execute(trigger: MaintenanceTrigger): Promise<MaintenanceResult> {
+		const context: MaintenanceContext = {
+			trigger,
+			now: this.now(),
+			ownedIds: this.ownedIds(),
+		};
+		return this.registry.run(context);
+	}
+}