@chipmobilesdk/rn-notification 0.1.0

package/src/reconcile/diff.ts

@@ -0,0 +1,145 @@
+/**
+ * Desired-versus-device diffing.
+ *
+ * The package's central promise lives here: reconciling twice with unchanged
+ * input must produce **zero** platform operations on the second run. That is
+ * only true if "unchanged" is decided by comparing everything that would make
+ * the delivered notification different — miss a field and the second run
+ * rewrites entries needlessly; include a volatile one and it never settles.
+ *
+ * Anchoring mode is part of the comparison key deliberately. A mode change on
+ * the same identifier must force a replacement rather than read as unchanged,
+ * because the two modes resolve to different instants the moment a zone
+ * changes.
+ */
+
+import type { NotificationRequest, PendingEntry } from '../contract/notification';
+
+export type OperationKind = 'create' | 'replace' | 'cancel';
+
+export interface DiffOperation {
+	readonly kind: OperationKind;
+	readonly id: string;
+	/** Present for create and replace. */
+	readonly request?: NotificationRequest;
+	/** The instant the entry should fire, after anchoring resolution. */
+	readonly resolvedAt?: number;
+}
+
+export interface DiffResult {
+	readonly operations: readonly DiffOperation[];
+	readonly unchanged: readonly string[];
+}
+
+/** Stable serialization of the fields that make a delivered notification different. */
+function fingerprint(
+	request: NotificationRequest,
+	resolvedAt: number,
+): string {
+	return JSON.stringify([
+		resolvedAt,
+		request.moment.anchoring ?? 'wallClock',
+		request.content.title,
+		request.content.body,
+		request.content.subtitle ?? null,
+		request.tone,
+		request.ownerTag ?? null,
+		request.groupTag ?? null,
+		// Key order is not stable across constructions, so sort before comparing —
+		// otherwise two structurally identical payloads could compare unequal and
+		// the second pass would rewrite every entry carrying routing data.
+		request.routing === undefined ? null : stableStringify(request.routing),
+		request.actions === undefined
+			? null
+			: request.actions.map(a => [a.id, a.title, a.mode, a.input?.placeholder ?? null]),
+	]);
+}
+
+function entryFingerprint(entry: PendingEntry): string {
+	return JSON.stringify([
+		entry.resolvedAt,
+		entry.anchoring,
+		entry.content.title,
+		entry.content.body,
+		entry.content.subtitle ?? null,
+		entry.tone,
+		entry.ownerTag ?? null,
+		entry.groupTag ?? null,
+		entry.routing === undefined ? null : stableStringify(entry.routing),
+		entry.actions === undefined
+			? null
+			: entry.actions.map(a => [a.id, a.title, a.mode, a.input?.placeholder ?? null]),
+	]);
+}
+
+/** Key-order-independent JSON, so structurally equal payloads compare equal. */
+function stableStringify(value: unknown): string {
+	if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+
+	const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
+		a < b ? -1 : a > b ? 1 : 0,
+	);
+	return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`;
+}
+
+export interface DiffInput {
+	readonly desired: readonly NotificationRequest[];
+	/** Resolved firing instant per desired identifier, after anchoring. */
+	readonly resolvedAt: ReadonlyMap<string, number>;
+	/** What the device currently holds, already narrowed to the caller's domain. */
+	readonly device: readonly PendingEntry[];
+	/**
+	 * Identifiers that were rejected before diffing and must be left alone.
+	 *
+	 * Without this they would look like strays — present on the device, absent
+	 * from the desired set — and be cancelled. But a rejection is not a
+	 * cancellation: the package could not decide what the caller meant, so
+	 * destroying the existing notification would be the worst available answer.
+	 */
+	readonly protectedIds?: ReadonlySet<string>;
+}
+
+/**
+ * Computes the minimal operation set.
+ *
+ * Cancels are emitted before creates so an interrupted pass leaves a
+ * recoverable gap rather than a duplicate: a missing notification is fixed by
+ * the next reconcile, whereas two notifications for one subject is a defect the
+ * user sees.
+ */
+export function diff(input: DiffInput): DiffResult {
+	const deviceById = new Map(input.device.map(entry => [entry.id, entry]));
+	const desiredIds = new Set(input.desired.map(request => request.id));
+
+	const cancels: DiffOperation[] = [];
+	const writes: DiffOperation[] = [];
+	const unchanged: string[] = [];
+
+	const protectedIds = input.protectedIds ?? new Set<string>();
+
+	for (const entry of input.device) {
+		if (!desiredIds.has(entry.id) && !protectedIds.has(entry.id)) {
+			cancels.push({ kind: 'cancel', id: entry.id });
+		}
+	}
+
+	for (const request of input.desired) {
+		const resolvedAt = input.resolvedAt.get(request.id) ?? request.moment.at;
+		const existing = deviceById.get(request.id);
+
+		if (existing === undefined) {
+			writes.push({ kind: 'create', id: request.id, request, resolvedAt });
+			continue;
+		}
+
+		if (fingerprint(request, resolvedAt) === entryFingerprint(existing)) {
+			unchanged.push(request.id);
+			continue;
+		}
+
+		writes.push({ kind: 'replace', id: request.id, request, resolvedAt });
+	}
+
+	return { operations: [...cancels, ...writes], unchanged };
+}

package/src/reconcile/duplicates.ts

@@ -0,0 +1,73 @@
+/**
+ * Duplicate identifier resolution.
+ *
+ * An identifier appearing twice in one desired set means the caller's key
+ * derivation produced two notifications for one identity. That is a bug, not a
+ * preference, so the package refuses rather than silently picking a winner.
+ *
+ * **Every** copy is rejected — no entry wins. Order-independence then follows
+ * for free rather than having to be engineered: there is no "first" or "last"
+ * to depend on.
+ *
+ * The rule applies even to byte-identical duplicates. Treating those as
+ * mergeable would require a deep-equality definition that becomes a contract of
+ * its own, and a repeated identifier is a key-derivation bug either way.
+ */
+
+import type { NotificationRequest } from '../contract/notification';
+import type { RejectedEntry } from '../contract/reconcile';
+import { DIAGNOSTIC_CODES } from '../contract/errors';
+
+export interface DuplicateSplit {
+	/** Entries whose identifier appeared exactly once. */
+	readonly unique: readonly NotificationRequest[];
+	/** One rejection record per repeated identifier, not per copy. */
+	readonly rejected: readonly RejectedEntry[];
+}
+
+/**
+ * Splits a desired set into applicable entries and rejections.
+ *
+ * `existingIds` lets the rejection state whether a notification already
+ * scheduled under that identifier was left in place — without it a caller could
+ * reasonably read "rejected" as "cancelled".
+ */
+export function splitDuplicates(
+	desired: readonly NotificationRequest[],
+	existingIds: ReadonlySet<string> = new Set(),
+): DuplicateSplit {
+	const counts = new Map<string, number>();
+	for (const request of desired) {
+		counts.set(request.id, (counts.get(request.id) ?? 0) + 1);
+	}
+
+	const unique: NotificationRequest[] = [];
+	const rejected: RejectedEntry[] = [];
+
+	for (const request of desired) {
+		if ((counts.get(request.id) ?? 0) === 1) {
+			unique.push(request);
+		}
+	}
+
+	// Sorted so the report itself is order-independent, not merely its effect.
+	const repeated = [...counts.entries()]
+		.filter(([, count]) => count > 1)
+		.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+
+	for (const [id, occurrences] of repeated) {
+		rejected.push({
+			id,
+			code: DIAGNOSTIC_CODES.DUPLICATE_IDENTIFIER,
+			reason:
+				`Identifier appeared ${occurrences} times in one desired set. Every copy was rejected, because the package cannot know which was intended.` +
+				(existingIds.has(id)
+					? ' Any notification already scheduled under it was left in place — this is a rejection, not a cancellation.'
+					: ''),
+			occurrences,
+			existingLeftInPlace: existingIds.has(id),
+		});
+	}
+
+	return { unique, rejected };
+}

package/src/reconcile/index.ts

@@ -0,0 +1,175 @@
+/**
+ * The reconciliation operation.
+ *
+ * A caller hands over the complete set its data implies; the package works out
+ * what to add, replace, and remove. This is **never** run automatically — only
+ * the caller knows what its data implies, and a package that guessed a desired
+ * set would cancel notifications it does not understand.
+ *
+ * Overlapping calls are serialized rather than run concurrently, because two
+ * passes interleaving their cancels and creates is exactly how duplicates
+ * appear.
+ */
+
+import type { NotificationRequest, PendingEntry } from '../contract/notification';
+import type { ReconcileInput, ReconcileResult } from '../contract/reconcile';
+import type { ResolvedTone } from '../contract/channel';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import { DIAGNOSTIC_CODES } from '../contract/errors';
+import { anchorMoment, type TimeZoneReader } from '../schedule/anchor';
+import { resolveMoment } from '../schedule/resolve-moment';
+import { validateRequest } from '../schedule';
+import { isNotificationError } from '../contract/errors';
+import type { RejectedEntry } from '../contract/reconcile';
+import { splitDuplicates } from './duplicates';
+import { truncateToCeiling } from './truncate';
+import { diff } from './diff';
+import { applyInChunks } from './chunk';
+
+export interface ReconcileDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly resolveTone: (toneId: string) => ResolvedTone | undefined;
+	readonly timeZone: TimeZoneReader;
+	readonly now: () => number;
+	readonly canScheduleExactly: () => boolean;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+	/** Overridable for tests that need to observe chunk boundaries. */
+	readonly chunkSize?: number;
+}
+
+/**
+ * Narrows the device set to the caller's declared domain.
+ *
+ * Everything outside it is invisible to this pass, which is what makes it safe
+ * to cancel strays: a notification from another domain or another library is
+ * never a stray, it simply is not ours.
+ */
+function inDomain(entry: PendingEntry, input: ReconcileInput): boolean {
+	if (entry.pushCreated && input.includePushCreated !== true) return false;
+	return entry.groupTag === input.domain;
+}
+
+export function createReconciler(deps: ReconcileDependencies) {
+	const emit = deps.emit ?? (() => {});
+	let inFlight: Promise<ReconcileResult> = Promise.resolve() as unknown as Promise<ReconcileResult>;
+
+	const run = async (input: ReconcileInput): Promise<ReconcileResult> => {
+		const startedAt = deps.now();
+		const zone = deps.timeZone();
+
+		const device = (await deps.engine.getPending()).filter(entry => inDomain(entry, input));
+		const existingIds = new Set(device.map(entry => entry.id));
+
+		// Duplicates first: a repeated identifier is refused before anything else
+		// looks at it, so no later stage has to decide which copy it meant.
+		const { unique, rejected: duplicateRejections } = splitDuplicates(input.desired, existingIds);
+		const rejected: RejectedEntry[] = [...duplicateRejections];
+
+		// Validate and anchor. A rejection here removes one entry; it never fails
+		// the pass, because 499 valid entries should not be lost to one bad one.
+		const valid: NotificationRequest[] = [];
+		const resolvedAt = new Map<string, number>();
+
+		for (const request of unique) {
+			try {
+				validateRequest(request, deps.resolveTone);
+				const anchored = anchorMoment(request.moment, zone);
+				const resolution = resolveMoment(anchored.resolvedAt, deps.now());
+				resolvedAt.set(request.id, resolution.at);
+				valid.push(request);
+			} catch (error) {
+				rejected.push({
+					id: request.id,
+					code: isNotificationError(error) ? error.code : 'UNKNOWN',
+					reason: error instanceof Error ? error.message : String(error),
+					occurrences: 1,
+					existingLeftInPlace: existingIds.has(request.id),
+				});
+			}
+		}
+
+		const capabilities = await deps.engine.getCapabilities();
+		const { kept, report: truncation } = truncateToCeiling(
+			valid,
+			resolvedAt,
+			capabilities.pendingCeiling,
+		);
+
+		if (truncation !== undefined) {
+			emit(
+				DIAGNOSTIC_CODES.TRUNCATED_OVER_CEILING,
+				`Desired set exceeded the platform ceiling of ${truncation.ceiling}; ${truncation.droppedCount} furthest-out entries were not registered. They are re-evaluated at the next window refresh.`,
+				{ ceiling: truncation.ceiling, dropped: truncation.droppedCount },
+			);
+		}
+
+		// Every rejected identifier is protected from cancellation. A rejection
+		// means the package could not tell what the caller intended, and
+		// destroying the existing notification on that basis would be the worst
+		// available answer (FR-028c).
+		const { operations, unchanged } = diff({
+			desired: kept,
+			resolvedAt,
+			device,
+			protectedIds: new Set(rejected.map(entry => entry.id)),
+		});
+
+		const created: string[] = [];
+		const replaced: string[] = [];
+		const cancelled: string[] = [];
+		const approximate = !deps.canScheduleExactly();
+
+		await applyInChunks(
+			operations,
+			async operation => {
+				if (operation.kind === 'cancel') {
+					await deps.engine.cancel(operation.id);
+					cancelled.push(operation.id);
+					return;
+				}
+
+				const request = operation.request!;
+				const tone = deps.resolveTone(request.tone)!;
+				await deps.engine.schedule({
+					request,
+					resolvedAt: operation.resolvedAt!,
+					tone,
+					anchoringGeneration:
+						(request.moment.anchoring ?? 'wallClock') === 'absolute' ? undefined : zone,
+					approximate,
+				});
+				(operation.kind === 'create' ? created : replaced).push(operation.id);
+			},
+			{ size: deps.chunkSize },
+		);
+
+		return {
+			domain: input.domain,
+			created,
+			replaced,
+			cancelled,
+			unchanged,
+			rejected,
+			truncated: truncation,
+			operationCount: operations.length,
+			durationMs: deps.now() - startedAt,
+		};
+	};
+
+	return {
+		/**
+		 * Serialized against itself: a second call waits for the first rather than
+		 * interleaving with it.
+		 */
+		async reconcile(input: ReconcileInput): Promise<ReconcileResult> {
+			const next = inFlight.then(
+				() => run(input),
+				() => run(input),
+			);
+			inFlight = next.catch(() => undefined) as Promise<ReconcileResult>;
+			return next;
+		},
+	};
+}
+
+export type Reconciler = ReturnType<typeof createReconciler>;

package/src/reconcile/truncate.ts

@@ -0,0 +1,56 @@
+/**
+ * Platform-ceiling truncation.
+ *
+ * iOS keeps only the 64 soonest pending notifications and silently discards the
+ * rest. The package computes the same cut deliberately, so the outcome is
+ * reported rather than discovered as missing notifications.
+ *
+ * Soonest-first is the only rule that degrades gracefully: dropped entries are
+ * not lost, they are simply not yet registered, and each window refresh
+ * registers those that have moved into range.
+ */
+
+import type { NotificationRequest } from '../contract/notification';
+import type { TruncationReport } from '../contract/reconcile';
+
+export interface TruncationOutcome {
+	readonly kept: readonly NotificationRequest[];
+	readonly report?: TruncationReport;
+}
+
+/**
+ * Keeps the `ceiling` soonest entries.
+ *
+ * Ties on the delivery instant are broken by identifier so the cut is
+ * deterministic — otherwise two runs over the same data could drop different
+ * entries and the idempotence guarantee would not hold.
+ */
+export function truncateToCeiling(
+	desired: readonly NotificationRequest[],
+	resolvedAt: ReadonlyMap<string, number>,
+	ceiling: number,
+): TruncationOutcome {
+	if (desired.length <= ceiling) {
+		return { kept: desired };
+	}
+
+	const ordered = [...desired].sort((a, b) => {
+		const aAt = resolvedAt.get(a.id) ?? a.moment.at;
+		const bAt = resolvedAt.get(b.id) ?? b.moment.at;
+		if (aAt !== bAt) return aAt - bAt;
+		return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+	});
+
+	const kept = ordered.slice(0, ceiling);
+	const dropped = ordered.slice(ceiling);
+
+	return {
+		kept,
+		report: {
+			ceiling,
+			droppedCount: dropped.length,
+			droppedIds: dropped.map(entry => entry.id),
+			reEvaluatedOnNextRefresh: true,
+		},
+	};
+}

package/src/recurrence/clock-guard.ts

@@ -0,0 +1,71 @@
+/**
+ * Clock-discontinuity bounding.
+ *
+ * A device clock moved backwards makes past occurrences look future again. Left
+ * alone, the next expansion would re-register every occurrence the user already
+ * received, and moving the clock forward again would fire them all at once.
+ *
+ * The guard is deliberately blunt: occurrences at or before the last horizon the
+ * series already expanded through are never re-emitted. The package would
+ * rather lose an occurrence after a manual clock change than deliver a burst of
+ * notifications for events that already happened.
+ */
+
+import type { Occurrence } from './expand';
+
+/** A jump larger than this is treated as a clock change rather than ordinary drift. */
+export const CLOCK_DISCONTINUITY_THRESHOLD_MS = 60 * 60 * 1000;
+
+export interface ClockGuardInput {
+	readonly occurrences: readonly Occurrence[];
+	/** Horizon this series had already expanded through before now. */
+	readonly previousHorizon: number | undefined;
+	readonly now: number;
+	/** The clock reading when the series was last expanded, if known. */
+	readonly previousNow: number | undefined;
+}
+
+export interface ClockGuardResult {
+	readonly occurrences: readonly Occurrence[];
+	readonly suppressed: number;
+	readonly discontinuity: 'none' | 'backwards' | 'forwards';
+}
+
+/**
+ * Drops occurrences that a clock discontinuity would otherwise resurrect.
+ *
+ * Forward jumps are detected and reported but not filtered: an occurrence that
+ * became due because time genuinely passed is legitimate, and the platform's
+ * own delivery is the right place for it to be resolved.
+ */
+export function guardAgainstClockChange(input: ClockGuardInput): ClockGuardResult {
+	const { occurrences, previousHorizon, now, previousNow } = input;
+
+	let discontinuity: ClockGuardResult['discontinuity'] = 'none';
+	if (previousNow !== undefined) {
+		const delta = now - previousNow;
+		if (delta < -CLOCK_DISCONTINUITY_THRESHOLD_MS) {
+			discontinuity = 'backwards';
+		} else if (delta > CLOCK_DISCONTINUITY_THRESHOLD_MS * 24) {
+			discontinuity = 'forwards';
+		}
+	}
+
+	if (previousHorizon === undefined) {
+		return { occurrences, suppressed: 0, discontinuity };
+	}
+
+	// Anything at or before the previously-expanded horizon was already handled
+	// once. Re-emitting it would mean delivering a notification for an event the
+	// user has already seen.
+	const kept = occurrences.filter(occurrence => occurrence.at > previousHorizon || occurrence.at > now);
+	const alreadyHandled = occurrences.filter(
+		occurrence => occurrence.at <= previousHorizon && occurrence.at <= now,
+	);
+
+	return {
+		occurrences: kept,
+		suppressed: alreadyHandled.length,
+		discontinuity,
+	};
+}