@chipmobilesdk/rn-notification 0.3.0 → 0.4.1

package/src/channel/tone-map.ts

@@ -1,130 +1,130 @@
-/**
- * Tone-to-platform mapping.
- *
- * A tone is declared once and realized on each platform here, so consumer code
- * contains zero platform branches. The two platforms model urgency differently
- * — Android by channel importance, iOS by interruption level — and reconciling
- * that difference is exactly the work this package exists to absorb.
- *
- * The channel id carries the tone version. Android channels are immutable once
- * created and re-declaration is silently ignored, so a configuration change has
- * to produce a *new* channel or it will never reach a device that already holds
- * the old one.
- */
-
-import type { ResolvedTone, ToneDeclaration, ToneUrgency } from '../contract/channel';
-
-type AndroidImportance = ResolvedTone['android']['importance'];
-type IosInterruption = ResolvedTone['ios']['interruptionLevel'];
-
-const ANDROID_IMPORTANCE: Record<ToneUrgency, AndroidImportance> = {
-	min: 'min',
-	low: 'low',
-	default: 'default',
-	high: 'high',
-	// Android has no level above `high`; max urgency is expressed by the DND
-	// bypass rather than by a distinct importance.
-	max: 'high',
-};
-
-const IOS_INTERRUPTION: Record<ToneUrgency, IosInterruption> = {
-	min: 'passive',
-	low: 'passive',
-	default: 'active',
-	high: 'active',
-	// `timeSensitive` is the highest level available without the Critical Alerts
-	// entitlement, which is out of scope for v1.
-	max: 'timeSensitive',
-};
-
-/** Channel id for a tone at a given version. Stable, derived, never random. */
-export function channelIdFor(toneId: string, version: number): string {
-	return `${toneId}.v${version}`;
-}
-
-/** Extracts the tone and version encoded in a channel id, if it is one of ours. */
-export function parseChannelId(
-	channelId: string,
-): { readonly toneId: string; readonly version: number } | undefined {
-	const separator = channelId.lastIndexOf('.v');
-	if (separator === -1) return undefined;
-
-	const version = Number.parseInt(channelId.slice(separator + 2), 10);
-	if (!Number.isInteger(version) || version < 1) return undefined;
-
-	return { toneId: channelId.slice(0, separator), version };
-}
-
-export function resolveTone(tone: ToneDeclaration): ResolvedTone {
-	const silent = tone.sound?.enabled === false;
-	const repeats = tone.repeatAlert !== undefined;
-
-	return {
-		toneId: tone.id,
-		version: tone.version,
-		android: {
-			channelId: channelIdFor(tone.id, tone.version),
-			// The declared label, not the identifier. Passing the identifier here
-			// is what put a technical string on the one screen these exist for.
-			name: tone.name,
-			description: tone.description,
-			importance: ANDROID_IMPORTANCE[tone.urgency],
-			sound: silent ? undefined : tone.sound?.name,
-			vibration: tone.vibration ?? false,
-			badge: tone.badge ?? false,
-			bypassDnd: tone.bypassDoNotDisturb ?? false,
-			groupId: tone.groupId,
-			// Both are per-notification rather than channel configuration, which
-			// is precisely why neither obliges a consumer to bump `version`.
-			loopSound: repeats,
-			alarmCategory: tone.timeSensitive ?? false,
-			repeatForMs: tone.repeatAlert?.forMs,
-		},
-		ios: {
-			// iOS categories are not versioned: they carry actions rather than
-			// user-adjustable settings, so re-declaring one is harmless.
-			categoryId: tone.id,
-			interruptionLevel:
-				tone.timeSensitive === true ? 'timeSensitive' : IOS_INTERRUPTION[tone.urgency],
-			sound: silent ? undefined : tone.sound?.name,
-			badge: tone.badge ?? false,
-			// iOS exposes no looping-sound API at all. Recorded as data so the
-			// refusal can be reported rather than discovered.
-			repeatRefused: repeats,
-		},
-	};
-}
-
-/**
- * A stable fingerprint of a tone's user-visible labels.
- *
- * Lets an unchanged configuration skip the platform entirely, which is what
- * keeps "re-applying changes nothing" literally true rather than merely
- * approximately true. A hash rather than the labels themselves, so persisted
- * state continues to hold no consumer-supplied text.
- */
-export function toneLabelFingerprint(tone: ToneDeclaration): string {
-	// The separator matters: without it, a name of "ab" with description "c" and
-	// a name of "a" with description "bc" would fingerprint identically, and one
-	// of the two would never get its correction.
-	const source = `${tone.name}\u0000${tone.description ?? ''}`;
-
-	// FNV-1a. Bitwise operators are the algorithm, not a micro-optimisation:
-	// arithmetic equivalents would not wrap to 32 bits and the hash would drift.
-	/* eslint-disable no-bitwise */
-	let hash = 0x811c9dc5;
-	for (let index = 0; index < source.length; index += 1) {
-		hash ^= source.codePointAt(index) ?? 0;
-		hash = Math.imul(hash, 0x01000193) >>> 0;
-	}
-	return (hash >>> 0).toString(16).padStart(8, '0');
-	/* eslint-enable no-bitwise */
-}
-
-/** Builds a lookup over a declared configuration. */
-export function createToneResolver(
-	tones: readonly ToneDeclaration[],
-): (toneId: string) => ResolvedTone | undefined {
-	const resolved = new Map(tones.map(tone => [tone.id, resolveTone(tone)]));
-	return toneId => resolved.get(toneId);
-}
+/**
+ * Tone-to-platform mapping.
+ *
+ * A tone is declared once and realized on each platform here, so consumer code
+ * contains zero platform branches. The two platforms model urgency differently
+ * — Android by channel importance, iOS by interruption level — and reconciling
+ * that difference is exactly the work this package exists to absorb.
+ *
+ * The channel id carries the tone version. Android channels are immutable once
+ * created and re-declaration is silently ignored, so a configuration change has
+ * to produce a *new* channel or it will never reach a device that already holds
+ * the old one.
+ */
+
+import type { ResolvedTone, ToneDeclaration, ToneUrgency } from '../contract/channel';
+
+type AndroidImportance = ResolvedTone['android']['importance'];
+type IosInterruption = ResolvedTone['ios']['interruptionLevel'];
+
+const ANDROID_IMPORTANCE: Record<ToneUrgency, AndroidImportance> = {
+	min: 'min',
+	low: 'low',
+	default: 'default',
+	high: 'high',
+	// Android has no level above `high`; max urgency is expressed by the DND
+	// bypass rather than by a distinct importance.
+	max: 'high',
+};
+
+const IOS_INTERRUPTION: Record<ToneUrgency, IosInterruption> = {
+	min: 'passive',
+	low: 'passive',
+	default: 'active',
+	high: 'active',
+	// `timeSensitive` is the highest level available without the Critical Alerts
+	// entitlement, which is out of scope for v1.
+	max: 'timeSensitive',
+};
+
+/** Channel id for a tone at a given version. Stable, derived, never random. */
+export function channelIdFor(toneId: string, version: number): string {
+	return `${toneId}.v${version}`;
+}
+
+/** Extracts the tone and version encoded in a channel id, if it is one of ours. */
+export function parseChannelId(
+	channelId: string,
+): { readonly toneId: string; readonly version: number } | undefined {
+	const separator = channelId.lastIndexOf('.v');
+	if (separator === -1) return undefined;
+
+	const version = Number.parseInt(channelId.slice(separator + 2), 10);
+	if (!Number.isInteger(version) || version < 1) return undefined;
+
+	return { toneId: channelId.slice(0, separator), version };
+}
+
+export function resolveTone(tone: ToneDeclaration): ResolvedTone {
+	const silent = tone.sound?.enabled === false;
+	const repeats = tone.repeatAlert !== undefined;
+
+	return {
+		toneId: tone.id,
+		version: tone.version,
+		android: {
+			channelId: channelIdFor(tone.id, tone.version),
+			// The declared label, not the identifier. Passing the identifier here
+			// is what put a technical string on the one screen these exist for.
+			name: tone.name,
+			description: tone.description,
+			importance: ANDROID_IMPORTANCE[tone.urgency],
+			sound: silent ? undefined : tone.sound?.name,
+			vibration: tone.vibration ?? false,
+			badge: tone.badge ?? false,
+			bypassDnd: tone.bypassDoNotDisturb ?? false,
+			groupId: tone.groupId,
+			// Both are per-notification rather than channel configuration, which
+			// is precisely why neither obliges a consumer to bump `version`.
+			loopSound: repeats,
+			alarmCategory: tone.timeSensitive ?? false,
+			repeatForMs: tone.repeatAlert?.forMs,
+		},
+		ios: {
+			// iOS categories are not versioned: they carry actions rather than
+			// user-adjustable settings, so re-declaring one is harmless.
+			categoryId: tone.id,
+			interruptionLevel:
+				tone.timeSensitive === true ? 'timeSensitive' : IOS_INTERRUPTION[tone.urgency],
+			sound: silent ? undefined : tone.sound?.name,
+			badge: tone.badge ?? false,
+			// iOS exposes no looping-sound API at all. Recorded as data so the
+			// refusal can be reported rather than discovered.
+			repeatRefused: repeats,
+		},
+	};
+}
+
+/**
+ * A stable fingerprint of a tone's user-visible labels.
+ *
+ * Lets an unchanged configuration skip the platform entirely, which is what
+ * keeps "re-applying changes nothing" literally true rather than merely
+ * approximately true. A hash rather than the labels themselves, so persisted
+ * state continues to hold no consumer-supplied text.
+ */
+export function toneLabelFingerprint(tone: ToneDeclaration): string {
+	// The separator matters: without it, a name of "ab" with description "c" and
+	// a name of "a" with description "bc" would fingerprint identically, and one
+	// of the two would never get its correction.
+	const source = `${tone.name}\u0000${tone.description ?? ''}`;
+
+	// FNV-1a. Bitwise operators are the algorithm, not a micro-optimisation:
+	// arithmetic equivalents would not wrap to 32 bits and the hash would drift.
+	/* eslint-disable no-bitwise */
+	let hash = 0x811c9dc5;
+	for (let index = 0; index < source.length; index += 1) {
+		hash ^= source.codePointAt(index) ?? 0;
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return (hash >>> 0).toString(16).padStart(8, '0');
+	/* eslint-enable no-bitwise */
+}
+
+/** Builds a lookup over a declared configuration. */
+export function createToneResolver(
+	tones: readonly ToneDeclaration[],
+): (toneId: string) => ResolvedTone | undefined {
+	const resolved = new Map(tones.map(tone => [tone.id, resolveTone(tone)]));
+	return toneId => resolved.get(toneId);
+}

package/src/channel/validate-tone.ts

@@ -1,61 +1,61 @@
-/**
- * Tone declaration validation.
- *
- * Runs before the first engine call, like every other validation in this
- * package: a rejected declaration must leave the device exactly as it was.
- *
- * Only the new alert attributes are checked here. The rest of a tone has always
- * been validated by the platform's own charset and shape rules, and duplicating
- * those would create two sources of truth for the same constraint.
- */
-
-import type { ToneDeclaration } from '../contract/channel';
-import { REPEAT_ALERT_BOUNDS } from '../contract/channel';
-import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
-
-/**
- * Throws when a tone's repeating alert is unusable.
- *
- * The type already forbids a repeat without a duration. What it cannot forbid
- * is a duration of zero, a fractional millisecond, or an hour and a half — and
- * an alert that repeats for an unchecked span is the failure this whole feature
- * exists to prevent.
- */
-export function validateToneDeclaration(tone: ToneDeclaration): void {
-	const repeat = tone.repeatAlert;
-	if (repeat === undefined) return;
-
-	if (!Number.isInteger(repeat.forMs)) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.INVALID_TONE_REPEAT,
-			`Tone "${tone.id}" declared a repeating alert whose duration is not a whole number of milliseconds.`,
-			{ toneId: tone.id, forMs: repeat.forMs },
-		);
-	}
-
-	if (repeat.forMs < REPEAT_ALERT_BOUNDS.minMs || repeat.forMs > REPEAT_ALERT_BOUNDS.maxMs) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.INVALID_TONE_REPEAT,
-			`Tone "${tone.id}" declared a repeating alert of ${repeat.forMs}ms, outside the permitted ${REPEAT_ALERT_BOUNDS.minMs}–${REPEAT_ALERT_BOUNDS.maxMs}ms range. A shorter repeat is indistinguishable from a single chime; a longer one outlasts anyone's willingness to respond.`,
-			{ toneId: tone.id, forMs: repeat.forMs, ...REPEAT_ALERT_BOUNDS },
-		);
-	}
-
-	if (tone.sound?.enabled === false) {
-		// Two instructions that cannot both be honoured. Picking one silently
-		// would ship whichever the reader did not expect, and the consumer would
-		// discover it on a device rather than here.
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.INVALID_TONE_REPEAT,
-			`Tone "${tone.id}" declares both a repeating alert and a silent sound. Repeating silence is not a behaviour; drop one of the two.`,
-			{ toneId: tone.id },
-		);
-	}
-}
-
-/** Validates a whole configuration before any of it is applied. */
-export function validateToneDeclarations(tones: readonly ToneDeclaration[]): void {
-	for (const tone of tones) {
-		validateToneDeclaration(tone);
-	}
-}
+/**
+ * Tone declaration validation.
+ *
+ * Runs before the first engine call, like every other validation in this
+ * package: a rejected declaration must leave the device exactly as it was.
+ *
+ * Only the new alert attributes are checked here. The rest of a tone has always
+ * been validated by the platform's own charset and shape rules, and duplicating
+ * those would create two sources of truth for the same constraint.
+ */
+
+import type { ToneDeclaration } from '../contract/channel';
+import { REPEAT_ALERT_BOUNDS } from '../contract/channel';
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+
+/**
+ * Throws when a tone's repeating alert is unusable.
+ *
+ * The type already forbids a repeat without a duration. What it cannot forbid
+ * is a duration of zero, a fractional millisecond, or an hour and a half — and
+ * an alert that repeats for an unchecked span is the failure this whole feature
+ * exists to prevent.
+ */
+export function validateToneDeclaration(tone: ToneDeclaration): void {
+	const repeat = tone.repeatAlert;
+	if (repeat === undefined) return;
+
+	if (!Number.isInteger(repeat.forMs)) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.INVALID_TONE_REPEAT,
+			`Tone "${tone.id}" declared a repeating alert whose duration is not a whole number of milliseconds.`,
+			{ toneId: tone.id, forMs: repeat.forMs },
+		);
+	}
+
+	if (repeat.forMs < REPEAT_ALERT_BOUNDS.minMs || repeat.forMs > REPEAT_ALERT_BOUNDS.maxMs) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.INVALID_TONE_REPEAT,
+			`Tone "${tone.id}" declared a repeating alert of ${repeat.forMs}ms, outside the permitted ${REPEAT_ALERT_BOUNDS.minMs}–${REPEAT_ALERT_BOUNDS.maxMs}ms range. A shorter repeat is indistinguishable from a single chime; a longer one outlasts anyone's willingness to respond.`,
+			{ toneId: tone.id, forMs: repeat.forMs, ...REPEAT_ALERT_BOUNDS },
+		);
+	}
+
+	if (tone.sound?.enabled === false) {
+		// Two instructions that cannot both be honoured. Picking one silently
+		// would ship whichever the reader did not expect, and the consumer would
+		// discover it on a device rather than here.
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.INVALID_TONE_REPEAT,
+			`Tone "${tone.id}" declares both a repeating alert and a silent sound. Repeating silence is not a behaviour; drop one of the two.`,
+			{ toneId: tone.id },
+		);
+	}
+}
+
+/** Validates a whole configuration before any of it is applied. */
+export function validateToneDeclarations(tones: readonly ToneDeclaration[]): void {
+	for (const tone of tones) {
+		validateToneDeclaration(tone);
+	}
+}