@chipmobilesdk/rn-notification 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-notification",
-	"version": "0.3.0",
+	"version": "0.4.1",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -23,22 +23,8 @@
 		}
 	},
 	"files": [
-		"src/index.ts",
-		"src/initialize.ts",
-		"src/channel",
-		"src/contract",
-		"src/diagnostics",
-		"src/engine",
-		"src/interaction",
-		"src/maintenance",
-		"src/permission",
-		"src/push",
-		"src/recurrence",
-		"src/repeat",
-		"src/reconcile",
-		"src/schedule",
-		"src/state",
-		"src/testing",
+		"src",
+		"!src/**/__tests__",
 		"skills",
 		"README.md",
 		"CHANGELOG.md"
@@ -46,7 +32,7 @@
 	"sideEffects": false,
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
+		"pack:check": "npm pack --dry-run"
 	},
 	"peerDependencies": {
 		"@react-native-firebase/app": ">=26.0.0",
@@ -65,9 +51,6 @@
 			"optional": true
 		}
 	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
 	"publishConfig": {
 		"access": "public",
 		"registry": "https://registry.npmjs.org/"

package/skills/sdk-rn-notification/SKILL.md

@@ -3,7 +3,6 @@ name: sdk-rn-notification
 description: "Local and push notifications via @chipmobilesdk/rn-notification: scheduling, identifiers, wall-clock vs absolute anchoring, idempotent reconciliation, recurrence windows, permissions, alarm-style repeating tones with a bounded window, tone labels in system settings, Android channel migration, tap routing, FCM. Use when scheduling a reminder or alarm, making a notification repeat until handled, naming a tone users see in settings, handling a notification tap, requesting notification permission, changing a channel, or debugging a notification that did not arrive."
 metadata:
   package: "@chipmobilesdk/rn-notification"
-  packageVersion: "0.3.0"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -36,9 +35,11 @@ Three things cause most of the bugs, and none is visible in the type signatures:
 2. **Wall-clock is the default anchoring mode** — an 08:00 reminder stays 08:00 after the
    user changes time zone. One case re-anchoring cannot fix: read
    `### What re-anchoring cannot fix` before promising exact behaviour to anyone.
-3. **Reconciliation is never automatic.** The package maintains its own recurrence windows
-   and re-anchoring, but never invents a desired set. Data changed and you did not call
-   `reconcile()` means the device is stale, by design.
+3. **Reconciliation is never automatic.** Maintenance steps registered on
+   `runtime.registry` (window refresh, re-anchoring, verification, permission re-read) run
+   on every foreground return, but the package never invents a desired set. Data changed
+   and you did not call `reconcile()` means the device is stale, by design. The steps are
+   not registered for you — they need your rules and expected ids.
 
 Read `## Choosing identifiers`, `## Choosing an anchoring mode`, and
 `## Maintenance versus reconciliation` before designing anything.

package/src/channel/migrate.ts

@@ -1,285 +1,285 @@
-/**
- * Channel declaration and migration.
- *
- * Android channels are immutable once created: declaring a channel whose id
- * already exists silently keeps the original configuration. That single fact is
- * why changing a tone is a **migration** rather than an assignment, and why
- * this package keeps its own ledger — the platform will not tell you which
- * version of a channel a device already holds.
- *
- * Migration creates the new channel, re-homes notifications still pointing at
- * the old one, and only then retires it. That order matters: retiring first
- * would leave live notifications attached to a channel that no longer exists.
- */
-
-import type {
-	ChannelApplyResult,
-	ChannelGroup,
-	ToneDeclaration,
-} from '../contract/channel';
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import type { StateManager, MigrationEntry } from '../state/record';
-import { DIAGNOSTIC_CODES } from '../contract/errors';
-import { channelIdFor, resolveTone, toneLabelFingerprint } from './tone-map';
-import { validateToneDeclarations } from './validate-tone';
-
-export interface ChannelDependencies {
-	readonly engine: NotificationEngineAdapter;
-	readonly state: StateManager;
-	readonly now: () => number;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-function ledgerFor(state: StateManager, toneId: string): MigrationEntry | undefined {
-	return state.read().migrationLedger.find(entry => entry.toneId === toneId && !entry.retired);
-}
-
-function recordApplied(
-	state: StateManager,
-	tone: ToneDeclaration,
-	now: number,
-	retiredChannelId: string | undefined,
-	labelFingerprint: string,
-): void {
-	state.update('migrationLedger', current => {
-		const withoutTone = current.filter(entry => entry.toneId !== tone.id);
-		const retired =
-			retiredChannelId === undefined
-				? []
-				: [
-						{
-							at: now,
-							toneId: tone.id,
-							appliedVersion: 0,
-							channelId: retiredChannelId,
-							retired: true,
-						},
-					];
-
-		return [
-			...withoutTone,
-			...retired,
-			{
-				at: now,
-				toneId: tone.id,
-				appliedVersion: tone.version,
-				channelId: channelIdFor(tone.id, tone.version),
-				retired: false,
-				labelFingerprint,
-			},
-		];
-	});
-}
-
-export function createChannels(deps: ChannelDependencies) {
-	const emit = deps.emit ?? (() => {});
-
-	return {
-		/**
-		 * Applies a tone configuration, migrating any tone whose version moved.
-		 *
-		 * Applying an unchanged configuration performs no work at all: no channel
-		 * is recreated and no migration is triggered.
-		 */
-		async apply(
-			tones: readonly ToneDeclaration[],
-			groups: readonly ChannelGroup[] = [],
-		): Promise<ChannelApplyResult> {
-			// Validation completes before the first engine call, so a rejected
-			// declaration leaves the device exactly as it was — the same order the
-			// scheduler has always used.
-			validateToneDeclarations(tones);
-
-			const now = deps.now();
-
-			const created: string[] = [];
-			const migrated: { toneId: string; from: number; to: number }[] = [];
-			const labelsRefreshed: string[] = [];
-			const retired: string[] = [];
-			const reHomed: string[] = [];
-			const cancelled: string[] = [];
-			const bypassUnavailable: string[] = [];
-			const repeatUnavailable: string[] = [];
-			const unchanged: string[] = [];
-
-			if (groups.length > 0) {
-				await deps.engine.declareGroups(groups);
-			}
-
-			const capabilities = await deps.engine.getCapabilities();
-
-			for (const tone of tones) {
-				const previous = ledgerFor(deps.state, tone.id);
-				const resolved = resolveTone(tone);
-				const fingerprint = toneLabelFingerprint(tone);
-
-				// Refusals are reported for every tone that asked, whether or not
-				// anything else about it moved. A platform declining an attribute
-				// says nothing about whether the channel is new.
-				if (tone.bypassDoNotDisturb === true && !capabilities.supportsDoNotDisturbBypass) {
-					// Reported honestly rather than silently dropped — a consumer that
-					// asked for a bypass deserves to know the platform refused.
-					bypassUnavailable.push(tone.id);
-					emit(
-						DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,
-						`Tone "${tone.id}" requested a Do Not Disturb bypass, which this platform does not permit.`,
-						{ toneId: tone.id },
-					);
-				}
-
-				if (tone.repeatAlert !== undefined) {
-					if (!capabilities.supportsRepeatingAlert) {
-						repeatUnavailable.push(tone.id);
-						emit(
-							DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE,
-							`Tone "${tone.id}" requested a repeating alert, which this platform does not offer. The notification still delivers and still sounds once.`,
-							{ toneId: tone.id },
-						);
-					} else if (!deps.engine.hasBackgroundDeliveryHandler()) {
-						// Said out loud at declaration time, because the alternative is a
-						// user meeting it as a phone that will not stop ringing.
-						emit(
-							DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING,
-							`Tone "${tone.id}" declares a repeating alert, but no background notification handler is registered. Its alert will not stop on its own while the app is not running. Call registerBackgroundNotificationHandler at module scope in index.js.`,
-							{ toneId: tone.id },
-						);
-					}
-				}
-
-				const versionMoved = previous !== undefined && previous.appliedVersion !== tone.version;
-
-				if (previous !== undefined && !versionMoved) {
-					// The version is the same, so nothing the platform freezes has
-					// changed. Only the labels can still be stale — and correcting
-					// those must cost the user nothing, so the platform is touched
-					// only when the fingerprint actually moved.
-					if (previous.labelFingerprint === fingerprint) {
-						unchanged.push(tone.id);
-						continue;
-					}
-
-					const outcome = await deps.engine.declareTone(resolved);
-					if (outcome === 'created') {
-						// The channel was gone — deleted by the user, or lost with the
-						// app's data — so this is a first declaration rather than a
-						// refresh, whatever our ledger believed.
-						created.push(resolved.android.channelId);
-					} else if (outcome === 'labelsRefreshed') {
-						labelsRefreshed.push(tone.id);
-						emit(
-							DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED,
-							`Tone "${tone.id}" had its name and description updated in place. No channel was recreated, so every setting the user adjusted on it is untouched.`,
-							{ toneId: tone.id },
-						);
-					} else {
-						unchanged.push(tone.id);
-					}
-
-					recordApplied(deps.state, tone, now, undefined, fingerprint);
-					continue;
-				}
-
-				const outcome = await deps.engine.declareTone(resolved);
-				if (outcome === 'created') {
-					created.push(resolved.android.channelId);
-				}
-
-				if (previous === undefined) {
-					recordApplied(deps.state, tone, now, undefined, fingerprint);
-					continue;
-				}
-
-				// A version moved, so this is a migration rather than a first
-				// declaration. Re-home before retiring: the reverse order would leave
-				// live notifications attached to a channel that no longer exists.
-				emit(
-					DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
-					`Tone "${tone.id}" moved from version ${previous.appliedVersion} to ${tone.version}. Android channels are immutable, so a new channel was created and the old one is being retired.`,
-					{ toneId: tone.id, from: previous.appliedVersion, to: tone.version },
-				);
-
-				const pending = await deps.engine.getPending();
-				const affected = pending.filter(entry => entry.tone === tone.id);
-
-				for (const entry of affected) {
-					await deps.engine.schedule({
-						request: {
-							id: entry.id,
-							content: entry.content,
-							tone: entry.tone,
-							moment: { at: entry.resolvedAt, anchoring: entry.anchoring },
-							routing: entry.routing,
-							actions: entry.actions,
-							ownerTag: entry.ownerTag,
-							groupTag: entry.groupTag,
-						},
-						resolvedAt: entry.resolvedAt,
-						tone: resolved,
-						// Re-homing changes the channel, not the anchoring — preserve it.
-						anchoringGeneration: entry.anchoringGeneration,
-						approximate: entry.mayBeDelayed,
-						seriesId: entry.seriesId,
-						pushCreated: entry.pushCreated,
-					});
-					reHomed.push(entry.id);
-				}
-
-				const didRetire = await deps.engine.retireTone(previous.channelId);
-				if (didRetire) {
-					retired.push(previous.channelId);
-				}
-
-				// A version move outranks a label change: the new channel simply
-				// carries the new labels, and reporting it as a refresh would hide a
-				// migration the consumer needs to know about.
-				migrated.push({ toneId: tone.id, from: previous.appliedVersion, to: tone.version });
-				recordApplied(deps.state, tone, now, previous.channelId, fingerprint);
-			}
-
-			// Anything left on a retired channel would be an orphan — a notification
-			// the user can no longer control from system settings.
-			const orphans = await findOrphans(deps, tones);
-			if (orphans.length > 0) {
-				await deps.engine.cancelMany(orphans);
-				cancelled.push(...orphans);
-				emit(
-					DIAGNOSTIC_CODES.CHANNEL_ORPHANS_FOUND,
-					`${orphans.length} notification(s) remained on a retired channel and were cancelled, rather than left uncontrollable from system settings.`,
-					{ count: orphans.length },
-				);
-			}
-
-			return {
-				created,
-				migrated,
-				labelsRefreshed,
-				retired,
-				reHomed,
-				cancelled,
-				bypassUnavailable,
-				repeatUnavailable,
-				unchanged,
-			};
-		},
-
-		/** Which version of each tone this device actually holds. */
-		appliedVersions(): readonly { readonly toneId: string; readonly appliedVersion: number }[] {
-			return deps.state
-				.read()
-				.migrationLedger.filter(entry => !entry.retired)
-				.map(entry => ({ toneId: entry.toneId, appliedVersion: entry.appliedVersion }));
-		},
-	};
-}
-
-/** Notifications whose tone is no longer declared at all. */
-async function findOrphans(
-	deps: ChannelDependencies,
-	tones: readonly ToneDeclaration[],
-): Promise<readonly string[]> {
-	const declared = new Set(tones.map(tone => tone.id));
-	const pending = await deps.engine.getPending();
-	return pending.filter(entry => !declared.has(entry.tone)).map(entry => entry.id);
-}
-
-export type Channels = ReturnType<typeof createChannels>;
+/**
+ * Channel declaration and migration.
+ *
+ * Android channels are immutable once created: declaring a channel whose id
+ * already exists silently keeps the original configuration. That single fact is
+ * why changing a tone is a **migration** rather than an assignment, and why
+ * this package keeps its own ledger — the platform will not tell you which
+ * version of a channel a device already holds.
+ *
+ * Migration creates the new channel, re-homes notifications still pointing at
+ * the old one, and only then retires it. That order matters: retiring first
+ * would leave live notifications attached to a channel that no longer exists.
+ */
+
+import type { ChannelApplyResult, ChannelGroup, ToneDeclaration } from '../contract/channel';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { StateManager, MigrationEntry } from '../state/record';
+import { DIAGNOSTIC_CODES } from '../contract/errors';
+import { channelIdFor, resolveTone, toneLabelFingerprint } from './tone-map';
+import { validateToneDeclarations } from './validate-tone';
+import { createScheduleWriter } from '../schedule/writer';
+
+export interface ChannelDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly state: StateManager;
+	readonly now: () => number;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+function ledgerFor(state: StateManager, toneId: string): MigrationEntry | undefined {
+	return state.read().migrationLedger.find(entry => entry.toneId === toneId && !entry.retired);
+}
+
+function recordApplied(
+	state: StateManager,
+	tone: ToneDeclaration,
+	now: number,
+	retiredChannelId: string | undefined,
+	labelFingerprint: string,
+): void {
+	state.update('migrationLedger', current => {
+		const withoutTone = current.filter(entry => entry.toneId !== tone.id);
+		const retired =
+			retiredChannelId === undefined
+				? []
+				: [
+						{
+							at: now,
+							toneId: tone.id,
+							appliedVersion: 0,
+							channelId: retiredChannelId,
+							retired: true,
+						},
+					];
+
+		return [
+			...withoutTone,
+			...retired,
+			{
+				at: now,
+				toneId: tone.id,
+				appliedVersion: tone.version,
+				channelId: channelIdFor(tone.id, tone.version),
+				retired: false,
+				labelFingerprint,
+			},
+		];
+	});
+}
+
+export function createChannels(deps: ChannelDependencies) {
+	const emit = deps.emit ?? (() => {});
+	// Re-homing re-writes each notification on the new channel; its stop marker
+	// has to follow, or it would retire with the old channel.
+	const writer = createScheduleWriter(deps.engine);
+
+	return {
+		/**
+		 * Applies a tone configuration, migrating any tone whose version moved.
+		 *
+		 * Applying an unchanged configuration performs no work at all: no channel
+		 * is recreated and no migration is triggered.
+		 */
+		async apply(
+			tones: readonly ToneDeclaration[],
+			groups: readonly ChannelGroup[] = [],
+		): Promise<ChannelApplyResult> {
+			// Validation completes before the first engine call, so a rejected
+			// declaration leaves the device exactly as it was — the same order the
+			// scheduler has always used.
+			validateToneDeclarations(tones);
+
+			const now = deps.now();
+
+			const created: string[] = [];
+			const migrated: { toneId: string; from: number; to: number }[] = [];
+			const labelsRefreshed: string[] = [];
+			const retired: string[] = [];
+			const reHomed: string[] = [];
+			const cancelled: string[] = [];
+			const bypassUnavailable: string[] = [];
+			const repeatUnavailable: string[] = [];
+			const unchanged: string[] = [];
+
+			if (groups.length > 0) {
+				await deps.engine.declareGroups(groups);
+			}
+
+			const capabilities = await deps.engine.getCapabilities();
+
+			for (const tone of tones) {
+				const previous = ledgerFor(deps.state, tone.id);
+				const resolved = resolveTone(tone);
+				const fingerprint = toneLabelFingerprint(tone);
+
+				// Refusals are reported for every tone that asked, whether or not
+				// anything else about it moved. A platform declining an attribute
+				// says nothing about whether the channel is new.
+				if (tone.bypassDoNotDisturb === true && !capabilities.supportsDoNotDisturbBypass) {
+					// Reported honestly rather than silently dropped — a consumer that
+					// asked for a bypass deserves to know the platform refused.
+					bypassUnavailable.push(tone.id);
+					emit(
+						DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,
+						`Tone "${tone.id}" requested a Do Not Disturb bypass, which this platform does not permit.`,
+						{ toneId: tone.id },
+					);
+				}
+
+				if (tone.repeatAlert !== undefined) {
+					if (!capabilities.supportsRepeatingAlert) {
+						repeatUnavailable.push(tone.id);
+						emit(
+							DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE,
+							`Tone "${tone.id}" requested a repeating alert, which this platform does not offer. The notification still delivers and still sounds once.`,
+							{ toneId: tone.id },
+						);
+					} else if (!deps.engine.hasBackgroundDeliveryHandler()) {
+						// Said out loud at declaration time, because the alternative is a
+						// user meeting it as a phone that will not stop ringing.
+						emit(
+							DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING,
+							`Tone "${tone.id}" declares a repeating alert, but no background notification handler is registered. Its alert will not stop on its own while the app is not running. Call registerBackgroundNotificationHandler at module scope in index.js.`,
+							{ toneId: tone.id },
+						);
+					}
+				}
+
+				const versionMoved = previous !== undefined && previous.appliedVersion !== tone.version;
+
+				if (previous !== undefined && !versionMoved) {
+					// The version is the same, so nothing the platform freezes has
+					// changed. Only the labels can still be stale — and correcting
+					// those must cost the user nothing, so the platform is touched
+					// only when the fingerprint actually moved.
+					if (previous.labelFingerprint === fingerprint) {
+						unchanged.push(tone.id);
+						continue;
+					}
+
+					const outcome = await deps.engine.declareTone(resolved);
+					if (outcome === 'created') {
+						// The channel was gone — deleted by the user, or lost with the
+						// app's data — so this is a first declaration rather than a
+						// refresh, whatever our ledger believed.
+						created.push(resolved.android.channelId);
+					} else if (outcome === 'labelsRefreshed') {
+						labelsRefreshed.push(tone.id);
+						emit(
+							DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED,
+							`Tone "${tone.id}" had its name and description updated in place. No channel was recreated, so every setting the user adjusted on it is untouched.`,
+							{ toneId: tone.id },
+						);
+					} else {
+						unchanged.push(tone.id);
+					}
+
+					recordApplied(deps.state, tone, now, undefined, fingerprint);
+					continue;
+				}
+
+				const outcome = await deps.engine.declareTone(resolved);
+				if (outcome === 'created') {
+					created.push(resolved.android.channelId);
+				}
+
+				if (previous === undefined) {
+					recordApplied(deps.state, tone, now, undefined, fingerprint);
+					continue;
+				}
+
+				// A version moved, so this is a migration rather than a first
+				// declaration. Re-home before retiring: the reverse order would leave
+				// live notifications attached to a channel that no longer exists.
+				emit(
+					DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
+					`Tone "${tone.id}" moved from version ${previous.appliedVersion} to ${tone.version}. Android channels are immutable, so a new channel was created and the old one is being retired.`,
+					{ toneId: tone.id, from: previous.appliedVersion, to: tone.version },
+				);
+
+				const pending = await deps.engine.getPending();
+				const affected = pending.filter(entry => entry.tone === tone.id);
+
+				for (const entry of affected) {
+					await writer.write({
+						request: {
+							id: entry.id,
+							content: entry.content,
+							tone: entry.tone,
+							moment: { at: entry.resolvedAt, anchoring: entry.anchoring },
+							routing: entry.routing,
+							actions: entry.actions,
+							ownerTag: entry.ownerTag,
+							groupTag: entry.groupTag,
+						},
+						resolvedAt: entry.resolvedAt,
+						tone: resolved,
+						// Re-homing changes the channel, not the anchoring — preserve it.
+						anchoringGeneration: entry.anchoringGeneration,
+						approximate: entry.mayBeDelayed,
+						seriesId: entry.seriesId,
+						pushCreated: entry.pushCreated,
+					});
+					reHomed.push(entry.id);
+				}
+
+				const didRetire = await deps.engine.retireTone(previous.channelId);
+				if (didRetire) {
+					retired.push(previous.channelId);
+				}
+
+				// A version move outranks a label change: the new channel simply
+				// carries the new labels, and reporting it as a refresh would hide a
+				// migration the consumer needs to know about.
+				migrated.push({ toneId: tone.id, from: previous.appliedVersion, to: tone.version });
+				recordApplied(deps.state, tone, now, previous.channelId, fingerprint);
+			}
+
+			// Anything left on a retired channel would be an orphan — a notification
+			// the user can no longer control from system settings.
+			const orphans = await findOrphans(deps, tones);
+			if (orphans.length > 0) {
+				await deps.engine.cancelMany(orphans);
+				cancelled.push(...orphans);
+				emit(
+					DIAGNOSTIC_CODES.CHANNEL_ORPHANS_FOUND,
+					`${orphans.length} notification(s) remained on a retired channel and were cancelled, rather than left uncontrollable from system settings.`,
+					{ count: orphans.length },
+				);
+			}
+
+			return {
+				created,
+				migrated,
+				labelsRefreshed,
+				retired,
+				reHomed,
+				cancelled,
+				bypassUnavailable,
+				repeatUnavailable,
+				unchanged,
+			};
+		},
+
+		/** Which version of each tone this device actually holds. */
+		appliedVersions(): readonly { readonly toneId: string; readonly appliedVersion: number }[] {
+			return deps.state
+				.read()
+				.migrationLedger.filter(entry => !entry.retired)
+				.map(entry => ({ toneId: entry.toneId, appliedVersion: entry.appliedVersion }));
+		},
+	};
+}
+
+/** Notifications whose tone is no longer declared at all. */
+async function findOrphans(
+	deps: ChannelDependencies,
+	tones: readonly ToneDeclaration[],
+): Promise<readonly string[]> {
+	const declared = new Set(tones.map(tone => tone.id));
+	const pending = await deps.engine.getPending();
+	return pending.filter(entry => !declared.has(entry.tone)).map(entry => entry.id);
+}
+
+export type Channels = ReturnType<typeof createChannels>;