@chipmobilesdk/rn-notification 0.1.0

package/src/schedule/validate-content.ts

@@ -0,0 +1,111 @@
+/**
+ * Content validation.
+ *
+ * The package passes content through **unchanged** and never truncates it.
+ * Display truncation is the platform's decision and differs between them; a
+ * library that pre-truncated would be guessing at a rule it does not own, and
+ * would corrupt content that would have displayed fine.
+ *
+ * What it does refuse is content over the platform's hard payload limit, where
+ * the alternative is not a shortened notification but a failed or undefined
+ * delivery. That is a real error and is reported as one, before any platform
+ * call.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+import type { NotificationContent } from '../contract/notification';
+
+/**
+ * Hard payload ceilings.
+ *
+ * These are *not* display limits. A title longer than a phone shows is fine and
+ * is passed through; the README documents where each platform visually
+ * truncates so a caller can decide for itself.
+ *
+ * The total is deliberately lower than the sum of the parts, so it actually
+ * binds — a per-field check that can never be exceeded in aggregate would be
+ * dead code. It sits under the 4 KB payload budget both platforms enforce,
+ * leaving headroom for the routing payload that shares it.
+ */
+export const CONTENT_LIMITS = {
+	maxTitleBytes: 512,
+	maxBodyBytes: 3072,
+	maxSubtitleBytes: 512,
+	maxTotalBytes: 3584,
+} as const;
+
+/** UTF-8 byte length — the unit the platforms actually bound. */
+export function byteLength(value: string): number {
+	let bytes = 0;
+	for (const char of value) {
+		const code = char.codePointAt(0) ?? 0;
+		if (code <= 0x7f) bytes += 1;
+		else if (code <= 0x7ff) bytes += 2;
+		else if (code <= 0xffff) bytes += 3;
+		else bytes += 4;
+	}
+	return bytes;
+}
+
+function requireString(value: unknown, field: string): string {
+	if (typeof value !== 'string') {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
+			`Notification content field "${field}" must be a string of resolved display text. The package performs no locale resolution.`,
+			{ field, received: typeof value },
+		);
+	}
+	return value;
+}
+
+/**
+ * Validates content and returns it **byte-identical**.
+ *
+ * The return value is the same object reference where possible, so nothing
+ * downstream can mistake this for a transformation step.
+ */
+export function validateContent(content: NotificationContent): NotificationContent {
+	const title = requireString(content.title, 'title');
+	const body = requireString(content.body, 'body');
+	const subtitle =
+		content.subtitle === undefined ? undefined : requireString(content.subtitle, 'subtitle');
+
+	if (title.length === 0 && body.length === 0) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
+			'A notification must carry a title or a body; both were empty.',
+			{ field: 'title+body' },
+		);
+	}
+
+	const checks: [string, string, number][] = [
+		['title', title, CONTENT_LIMITS.maxTitleBytes],
+		['body', body, CONTENT_LIMITS.maxBodyBytes],
+	];
+	if (subtitle !== undefined) {
+		checks.push(['subtitle', subtitle, CONTENT_LIMITS.maxSubtitleBytes]);
+	}
+
+	for (const [field, value, limit] of checks) {
+		const size = byteLength(value);
+		if (size > limit) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
+				`Notification "${field}" is ${size} bytes, over the ${limit}-byte platform limit. ` +
+					'It was refused rather than truncated, because the package does not decide where a caller\'s content should be cut.',
+				{ field, bytes: size, limit },
+			);
+		}
+	}
+
+	const total = byteLength(title) + byteLength(body) + (subtitle ? byteLength(subtitle) : 0);
+	if (total > CONTENT_LIMITS.maxTotalBytes) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
+			`Notification content totals ${total} bytes, over the ${CONTENT_LIMITS.maxTotalBytes}-byte payload limit.`,
+			{ field: 'total', bytes: total, limit: CONTENT_LIMITS.maxTotalBytes },
+		);
+	}
+
+	return content;
+}

package/src/schedule/validate-identifier.ts

@@ -0,0 +1,114 @@
+/**
+ * Identifier validation.
+ *
+ * Identity is the caller's contract: only the caller can derive an identifier
+ * reproducibly from its own data, so the package never generates one.
+ *
+ * The charset is composite-friendly because real derived keys are hierarchical
+ * — `task:1234:reminder:2`. A charset that forced encoding of natural keys
+ * would work against caller-supplied identity being readable and reproducible,
+ * which is most of its value.
+ *
+ * Nothing is normalized, trimmed, case-folded, or hashed. Two identifiers
+ * differing in any character are different identifiers, and the value visible
+ * at the platform boundary is exactly what the caller supplied — which is what
+ * lets a notification be traced back to the data that produced it.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError, type DiagnosticCode } from '../contract/errors';
+
+export const MAX_IDENTIFIER_LENGTH = 128;
+
+/** `A–Z a–z 0–9 . _ - : /` — printable, unambiguous, and safe at every boundary. */
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9._:/-]+$/;
+
+/** Reports the first offending character so a failure is actionable without echoing the value. */
+function firstInvalidCharacter(value: string): { char: string; index: number } | undefined {
+	for (let index = 0; index < value.length; index += 1) {
+		const char = value[index];
+		if (!/[A-Za-z0-9._:/-]/.test(char)) {
+			return { char, index };
+		}
+	}
+	return undefined;
+}
+
+export type IdentifierKind = 'id' | 'ownerTag' | 'groupTag' | 'seriesId' | 'actionId';
+
+const EMPTY_CODE: Record<IdentifierKind, DiagnosticCode> = {
+	id: DIAGNOSTIC_CODES.INVALID_ID_EMPTY,
+	ownerTag: DIAGNOSTIC_CODES.INVALID_OWNER_TAG,
+	groupTag: DIAGNOSTIC_CODES.INVALID_GROUP_TAG,
+	seriesId: DIAGNOSTIC_CODES.INVALID_ID_EMPTY,
+	actionId: DIAGNOSTIC_CODES.INVALID_ID_EMPTY,
+};
+
+const LENGTH_CODE: Record<IdentifierKind, DiagnosticCode> = {
+	id: DIAGNOSTIC_CODES.INVALID_ID_LENGTH,
+	ownerTag: DIAGNOSTIC_CODES.INVALID_OWNER_TAG,
+	groupTag: DIAGNOSTIC_CODES.INVALID_GROUP_TAG,
+	seriesId: DIAGNOSTIC_CODES.INVALID_ID_LENGTH,
+	actionId: DIAGNOSTIC_CODES.INVALID_ID_LENGTH,
+};
+
+const CHARSET_CODE: Record<IdentifierKind, DiagnosticCode> = {
+	id: DIAGNOSTIC_CODES.INVALID_ID_CHARSET,
+	ownerTag: DIAGNOSTIC_CODES.INVALID_OWNER_TAG,
+	groupTag: DIAGNOSTIC_CODES.INVALID_GROUP_TAG,
+	seriesId: DIAGNOSTIC_CODES.INVALID_ID_CHARSET,
+	actionId: DIAGNOSTIC_CODES.INVALID_ID_CHARSET,
+};
+
+/**
+ * Throws a typed error naming the violated rule.
+ *
+ * The offending character and its position are reported; the value itself never
+ * is, because an identifier can carry user data a caller derived it from.
+ */
+export function validateIdentifier(value: unknown, kind: IdentifierKind = 'id'): string {
+	if (typeof value !== 'string' || value.length === 0) {
+		throw new NotificationError(
+			EMPTY_CODE[kind],
+			`A ${kind} must be a non-empty string supplied by the caller. The package never generates one.`,
+			{ kind, received: typeof value },
+		);
+	}
+
+	if (value.length > MAX_IDENTIFIER_LENGTH) {
+		throw new NotificationError(
+			LENGTH_CODE[kind],
+			`A ${kind} must be at most ${MAX_IDENTIFIER_LENGTH} characters.`,
+			{ kind, length: value.length, max: MAX_IDENTIFIER_LENGTH },
+		);
+	}
+
+	if (!IDENTIFIER_PATTERN.test(value)) {
+		const offender = firstInvalidCharacter(value);
+		throw new NotificationError(
+			CHARSET_CODE[kind],
+			`A ${kind} may contain only A-Z, a-z, 0-9, and the separators . _ - : / — whitespace and control characters are not permitted.`,
+			{ kind, index: offender?.index, charCode: offender?.char.charCodeAt(0) },
+		);
+	}
+
+	return value;
+}
+
+/** Non-throwing form, for validating a batch without unwinding on the first failure. */
+export function isValidIdentifier(value: unknown): value is string {
+	return (
+		typeof value === 'string' &&
+		value.length > 0 &&
+		value.length <= MAX_IDENTIFIER_LENGTH &&
+		IDENTIFIER_PATTERN.test(value)
+	);
+}
+
+/** Validates an optional tag, returning undefined when absent rather than failing. */
+export function validateOptionalTag(
+	value: string | undefined,
+	kind: Extract<IdentifierKind, 'ownerTag' | 'groupTag'>,
+): string | undefined {
+	if (value === undefined) return undefined;
+	return validateIdentifier(value, kind);
+}

package/src/state/caps.ts

@@ -0,0 +1,71 @@
+/**
+ * Caps and eviction for the persisted collections.
+ *
+ * No collection may grow without bound. Eviction is oldest-first and always
+ * observable — a silent eviction would turn a bounded guarantee into an
+ * unexplained one.
+ */
+
+/** Every persisted collection with a size or age bound. */
+export const COLLECTION_CAPS = {
+	dedupLedger: { maxEntries: 500, retentionMs: 24 * 60 * 60 * 1000 },
+	interactionBuffer: { maxEntries: 50, retentionMs: 7 * 24 * 60 * 60 * 1000 },
+	migrationLedger: { maxEntries: 20, retentionMs: Number.POSITIVE_INFINITY },
+	seriesLedger: { maxEntries: 32, retentionMs: Number.POSITIVE_INFINITY },
+	permissionHistory: { maxEntries: 64, retentionMs: Number.POSITIVE_INFINITY },
+} as const;
+
+export type CollectionName = keyof typeof COLLECTION_CAPS;
+
+/** Anything stored with a timestamp, which is everything that can age out. */
+export interface Timestamped {
+	readonly at: number;
+}
+
+export interface EvictionOutcome<T> {
+	readonly kept: readonly T[];
+	readonly evicted: readonly T[];
+	readonly reason: 'none' | 'cap' | 'retention' | 'cap+retention';
+}
+
+/**
+ * Applies retention first, then the size cap.
+ *
+ * Order matters: expiring stale entries before trimming means a burst of new
+ * entries does not evict fresh ones while stale ones sit protected by
+ * recency ordering.
+ */
+export function evict<T extends Timestamped>(
+	entries: readonly T[],
+	collection: CollectionName,
+	now: number,
+): EvictionOutcome<T> {
+	const { maxEntries, retentionMs } = COLLECTION_CAPS[collection];
+
+	const expired: T[] = [];
+	const live: T[] = [];
+	for (const entry of entries) {
+		if (Number.isFinite(retentionMs) && now - entry.at > retentionMs) {
+			expired.push(entry);
+		} else {
+			live.push(entry);
+		}
+	}
+
+	// Oldest first, so the tail is what we keep when trimming.
+	live.sort((a, b) => a.at - b.at);
+
+	const overflow = live.length > maxEntries ? live.slice(0, live.length - maxEntries) : [];
+	const kept = live.length > maxEntries ? live.slice(live.length - maxEntries) : live;
+
+	let reason: EvictionOutcome<T>['reason'] = 'none';
+	if (expired.length > 0 && overflow.length > 0) {
+		reason = 'cap+retention';
+	} else if (overflow.length > 0) {
+		reason = 'cap';
+	} else if (expired.length > 0) {
+		reason = 'retention';
+	}
+
+	return { kept, evicted: [...expired, ...overflow], reason };
+}

package/src/state/dedup-ledger.ts

@@ -0,0 +1,39 @@
+/**
+ * The push deduplication ledger.
+ *
+ * Providers redeliver. The redelivery typically arrives in a **fresh process**,
+ * which is precisely why this is persisted rather than held in memory — an
+ * in-memory set would forget exactly when it matters.
+ *
+ * Bounded by cap and retention. A payload redelivered after its entry has aged
+ * out is treated as new: that is the documented bound of the guarantee, not a
+ * defect.
+ */
+
+import type { StateManager } from './record';
+
+export function isDuplicate(state: StateManager, dedupId: string): boolean {
+	return state.read().dedupLedger.some(entry => entry.dedupId === dedupId);
+}
+
+/**
+ * Records a payload as seen.
+ *
+ * Returns true when it was already known, so a caller can branch on the same
+ * read that records it rather than checking twice.
+ */
+export function recordSeen(
+	state: StateManager,
+	dedupId: string,
+	now: number,
+	ownerTag?: string,
+): boolean {
+	if (isDuplicate(state, dedupId)) return true;
+
+	state.update('dedupLedger', current => [...current, { at: now, dedupId, ownerTag }]);
+	return false;
+}
+
+export function dedupCount(state: StateManager): number {
+	return state.read().dedupLedger.length;
+}

package/src/state/interaction-buffer.ts

@@ -0,0 +1,73 @@
+/**
+ * The durable interaction buffer.
+ *
+ * A cold-start tap arrives before any handler exists. Holding it in memory
+ * would be enough if the process always survived — but the process is exactly
+ * what does not survive a cold start, so the buffer is persisted.
+ *
+ * This is the one content-bearing thing the package stores: an interaction
+ * cannot be delivered without its routing payload. It is evicted the moment it
+ * is delivered, and time-limited regardless, so an event nobody ever collects
+ * cannot sit on disk forever.
+ */
+
+import type { StateManager, BufferedInteraction } from './record';
+import type { InteractionEvent } from '../contract/interaction';
+
+/** Identity for a buffered event, derived so re-buffering cannot duplicate. */
+function bufferedId(event: InteractionEvent): string {
+	return `${event.kind}:${event.notificationId}:${event.actionId ?? ''}:${event.occurredAt}`;
+}
+
+export function buffer(state: StateManager, event: InteractionEvent): void {
+	const id = bufferedId(event);
+
+	state.update('interactionBuffer', current => {
+		if (current.some(entry => entry.id === id)) return current;
+
+		const entry: BufferedInteraction = {
+			at: event.occurredAt,
+			id,
+			kind: event.kind,
+			notificationId: event.notificationId,
+			actionId: event.actionId,
+			inputText: event.inputText,
+			routing: event.routing,
+			ownerTag: event.ownerTag,
+		};
+		return [...current, entry];
+	});
+}
+
+/**
+ * Takes every buffered event in occurrence order and clears them.
+ *
+ * Draining and clearing together is deliberate: delivering an event twice is
+ * worse than the alternative, because a consumer that acts on an interaction
+ * (marking a task done, sending a reply) would act twice.
+ */
+export function drain(state: StateManager): readonly InteractionEvent[] {
+	const buffered = [...state.read().interactionBuffer].sort((a, b) => a.at - b.at);
+
+	if (buffered.length === 0) return [];
+
+	state.update('interactionBuffer', () => []);
+
+	return buffered.map(entry => ({
+		kind: entry.kind,
+		notificationId: entry.notificationId,
+		actionId: entry.actionId,
+		inputText: entry.inputText,
+		routing: entry.routing,
+		ownerTag: entry.ownerTag,
+		occurredAt: entry.at,
+		// The state it arrived in is gone; what matters to a consumer is that it
+		// waited, which is what `wasBuffered` says.
+		appState: 'coldStart' as const,
+		wasBuffered: true,
+	}));
+}
+
+export function bufferedCount(state: StateManager): number {
+	return state.read().interactionBuffer.length;
+}

package/src/state/mmkv-store.ts

@@ -0,0 +1,71 @@
+/**
+ * MMKV-backed state store.
+ *
+ * Every MMKV import is confined to this file, so the rest of the package stays
+ * testable without a native module.
+ *
+ * Backup exclusion is achieved by *where* the data lives rather than by setting
+ * a file attribute: on iOS the instance is rooted under `Library/Caches`, which
+ * the platform excludes from iCloud and iTunes backup by design. The OS may
+ * purge that directory under storage pressure — acceptable here precisely
+ * because discarding and rebuilding this record is already a specified,
+ * non-blocking condition.
+ *
+ * On Android, backup exclusion is declared in the consuming app's
+ * `data_extraction_rules.xml` and `full_backup_content`, documented in the
+ * README. It is the app's manifest, so it is the app's declaration to make.
+ */
+
+import { Platform } from 'react-native';
+import type { StateStore } from './store';
+import { createMemoryStore } from './store';
+
+const INSTANCE_ID = 'chipmobilesdk.notification';
+
+interface MmkvLike {
+	getString(key: string): string | undefined;
+	set(key: string, value: string): void;
+	delete(key: string): void;
+	clearAll(): void;
+	getAllKeys(): string[];
+}
+
+/**
+ * Creates the persistent store, falling back to memory when MMKV is absent.
+ *
+ * The fallback is deliberate: a missing optional native module degrades
+ * deduplication and cold-start buffering to session scope, which is a
+ * documented degradation. It must never stop notifications being delivered.
+ */
+export function createMmkvStore(): StateStore {
+	let instance: MmkvLike;
+
+	try {
+		// Required lazily so the package loads in environments without the native module.
+		const { MMKV } = require('react-native-mmkv') as {
+			MMKV: new (config: { id: string; path?: string }) => MmkvLike;
+		};
+
+		instance = new MMKV({
+			id: INSTANCE_ID,
+			// Caches is backup-excluded by platform design; see the note above.
+			path: Platform.OS === 'ios' ? 'Library/Caches/chipmobilesdk-notification' : undefined,
+		});
+	} catch {
+		return createMemoryStore();
+	}
+
+	return {
+		getString: key => instance.getString(key),
+		setString: (key, value) => instance.set(key, value),
+		delete: key => instance.delete(key),
+		clearAll: () => instance.clearAll(),
+		approximateBytes: () => {
+			let total = 0;
+			for (const key of instance.getAllKeys()) {
+				total += key.length + (instance.getString(key)?.length ?? 0);
+			}
+			return total;
+		},
+	};
+}

package/src/state/permission-history.ts

@@ -0,0 +1,41 @@
+/**
+ * Permission-request history.
+ *
+ * The platform cannot tell you whether you have already asked. On both
+ * platforms a second request after a denial is silently a no-op, so an app that
+ * does not remember will keep "asking" and keep appearing to be refused.
+ *
+ * Keyed by owner tag so a multi-account device can clear one account's history
+ * on sign-out without forgetting what it asked the others.
+ */
+
+import type { StateManager } from './record';
+import type { PermissionKind } from '../contract/permission';
+
+function key(kind: PermissionKind, ownerTag?: string): string {
+	return `${ownerTag ?? '*'}:${kind}`;
+}
+
+export function hasRequested(
+	state: StateManager,
+	kind: PermissionKind,
+	ownerTag?: string,
+): boolean {
+	const target = key(kind, ownerTag);
+	return state.read().permissionHistory.some(entry => entry.key === target && entry.requested);
+}
+
+export function recordRequested(
+	state: StateManager,
+	kind: PermissionKind,
+	now: number,
+	ownerTag?: string,
+): void {
+	const target = key(kind, ownerTag);
+	if (hasRequested(state, kind, ownerTag)) return;
+
+	state.update('permissionHistory', current => [
+		...current.filter(entry => entry.key !== target),
+		{ at: now, key: target, requested: true },
+	]);
+}