@chipmobilesdk/rn-notification 0.1.2 → 0.2.0

package/src/index.ts

@@ -52,6 +52,7 @@ export type {
 	// Channel
 	ToneUrgency,
 	ToneSound,
+	ToneRepeatAlert,
 	ToneDeclaration,
 	ChannelGroup,
 	ChannelApplyResult,
@@ -80,6 +81,7 @@ export type {
 export {
 	DEFAULT_ANCHORING_MODE,
 	DEFAULT_LOOKAHEAD,
+	REPEAT_ALERT_BOUNDS,
 	LOOKAHEAD_BOUNDS,
 	INTERACTION_BUFFER_LIMITS,
 	MAX_ROUTING_PAYLOAD_BYTES,
@@ -100,8 +102,11 @@ export type { DiagnosticCode } from './contract';
  */
 export type {
 	NotificationEngineAdapter,
+	DeliveryEvent,
 	EngineCapabilities,
 	EngineScheduleRequest,
+	RepeatStop,
+	ToneDeclarationOutcome,
 } from './engine/adapter';
 
 /** The default engine. Consumers may substitute their own via the port above. */
@@ -128,6 +133,25 @@ export { occurrenceId } from './recurrence/expand';
 export { createChannels } from './channel/migrate';
 export type { Channels, ChannelDependencies } from './channel/migrate';
 export { channelIdFor, createToneResolver, parseChannelId, resolveTone } from './channel/tone-map';
+export { validateToneDeclaration, validateToneDeclarations } from './channel/validate-tone';
+
+/**
+ * Repeat expiry — what bounds an alert that repeats until it is handled.
+ *
+ * `registerBackgroundNotificationHandler` is the one piece a consumer wires up
+ * themselves, at module scope in `index.js`. An app that declares no repeating
+ * tone needs none of this.
+ */
+export {
+	createRepeatExpiryHandler,
+	registerBackgroundNotificationHandler,
+	REPEAT_STOP_PREFIX,
+} from './repeat';
+export type {
+	BackgroundHandlerRegistration,
+	RepeatExpiryHandler,
+	RepeatExpiryDependencies,
+} from './repeat';
 
 /** Interaction routing — one handler for foreground, background, and cold start. */
 export { createInteractions } from './interaction';

package/src/initialize.ts

@@ -1,174 +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 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.';
+	}
+}