@chipmobilesdk/rn-notification 0.1.2 → 0.2.1

package/src/push/provider-adapter.ts

@@ -1,54 +1,54 @@
-/**
- * The port every push provider satisfies.
- *
- * No provider type appears in any signature, which is what makes swapping the
- * provider cost the consumer nothing.
- */
-
-import type { RoutingPayload, NotificationContent } from '../contract/notification';
-import type { Unsubscribe } from '../contract/interaction';
-
-/** The single normalized shape every provider's payload is reduced to. */
-export interface PushEnvelope {
-	/** Contract version carried by the payload. See contracts/push-payload.md. */
-	readonly version: number;
-	readonly kind: 'display' | 'data' | 'schedule' | 'cancel';
-	readonly id: string;
-	readonly ownerTag?: string;
-	readonly content?: NotificationContent;
-	readonly tone?: string;
-	readonly moment?: { readonly at: number; readonly anchoring?: 'wallClock' | 'absolute' };
-	readonly routing?: RoutingPayload;
-	/** De-duplication key, falling back to `id` when absent. */
-	readonly dedupId: string;
-	readonly receivedAt: number;
-	/**
-	 * True when the payload declared a version this build does not implement and
-	 * was processed best-effort, honouring known fields and ignoring the rest.
-	 */
-	readonly versionSkew: boolean;
-}
-
-export interface PushConfig {
-	/** Called when the provider reports a new or refreshed registration token. */
-	readonly onTokenChange?: (token: string) => void;
-}
-
-export type PushAvailability = 'available' | 'unavailable' | 'unknown';
-
-export interface PushProviderAdapter {
-	readonly name: string;
-
-	/** Reports whether platform push services exist, so degradation is controlled rather than opaque. */
-	getAvailability(): Promise<PushAvailability>;
-
-	/** Waits for a genuine token. Never returns a placeholder presented as a token. */
-	getToken(): Promise<string>;
-	onTokenChange(handler: (token: string) => void): Unsubscribe;
-	invalidateToken(): Promise<boolean>;
-
-	/** Raw provider payloads, normalized by the gate rather than by the adapter. */
-	subscribeToMessages(handler: (raw: unknown) => void): Unsubscribe;
-	/** A payload that launched the app, consumed exactly once. */
-	takeInitialMessage(): Promise<unknown | undefined>;
-}
+/**
+ * The port every push provider satisfies.
+ *
+ * No provider type appears in any signature, which is what makes swapping the
+ * provider cost the consumer nothing.
+ */
+
+import type { RoutingPayload, NotificationContent } from '../contract/notification';
+import type { Unsubscribe } from '../contract/interaction';
+
+/** The single normalized shape every provider's payload is reduced to. */
+export interface PushEnvelope {
+	/** Contract version carried by the payload. See contracts/push-payload.md. */
+	readonly version: number;
+	readonly kind: 'display' | 'data' | 'schedule' | 'cancel';
+	readonly id: string;
+	readonly ownerTag?: string;
+	readonly content?: NotificationContent;
+	readonly tone?: string;
+	readonly moment?: { readonly at: number; readonly anchoring?: 'wallClock' | 'absolute' };
+	readonly routing?: RoutingPayload;
+	/** De-duplication key, falling back to `id` when absent. */
+	readonly dedupId: string;
+	readonly receivedAt: number;
+	/**
+	 * True when the payload declared a version this build does not implement and
+	 * was processed best-effort, honouring known fields and ignoring the rest.
+	 */
+	readonly versionSkew: boolean;
+}
+
+export interface PushConfig {
+	/** Called when the provider reports a new or refreshed registration token. */
+	readonly onTokenChange?: (token: string) => void;
+}
+
+export type PushAvailability = 'available' | 'unavailable' | 'unknown';
+
+export interface PushProviderAdapter {
+	readonly name: string;
+
+	/** Reports whether platform push services exist, so degradation is controlled rather than opaque. */
+	getAvailability(): Promise<PushAvailability>;
+
+	/** Waits for a genuine token. Never returns a placeholder presented as a token. */
+	getToken(): Promise<string>;
+	onTokenChange(handler: (token: string) => void): Unsubscribe;
+	invalidateToken(): Promise<boolean>;
+
+	/** Raw provider payloads, normalized by the gate rather than by the adapter. */
+	subscribeToMessages(handler: (raw: unknown) => void): Unsubscribe;
+	/** A payload that launched the app, consumed exactly once. */
+	takeInitialMessage(): Promise<unknown | undefined>;
+}

package/src/push/signout.ts

@@ -1,65 +1,65 @@
-/**
- * Sign-out cleanup.
- *
- * Three things must happen together, and the order matters: invalidate the
- * token first so no further messages arrive for the account being left, then
- * cancel its notifications, then clear its persisted state.
- *
- * Deliberately **scoped to one owner tag**. On a shared device, signing one
- * account out must not clear another's deduplication history or cancel their
- * reminders — and must not discard the channel migration ledger, which
- * describes the device rather than any account.
- */
-
-import type { PushGate } from './gate';
-import type { Scheduler } from '../schedule';
-import type { StateManager } from '../state/record';
-import { clearOwner } from '../state/reset';
-
-export interface SignOutDependencies {
-	readonly scheduler: Scheduler;
-	readonly state: StateManager;
-	/** Absent for a local-only app, which still needs the rest of the cleanup. */
-	readonly push?: PushGate;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export interface SignOutResult {
-	readonly ownerTag: string;
-	readonly tokenInvalidated: boolean;
-	readonly cancelledIds: readonly string[];
-	readonly clearedCollections: readonly string[];
-}
-
-export function createSignOut(deps: SignOutDependencies) {
-	return {
-		async signOut(ownerTag: string): Promise<SignOutResult> {
-			// Token first: stop the inbound flow before removing what would have
-			// handled it, so nothing arrives for an account that is already gone.
-			let tokenInvalidated = false;
-			if (deps.push !== undefined) {
-				try {
-					tokenInvalidated = await deps.push.invalidateToken();
-				} catch {
-					// A failed invalidation must not prevent local cleanup — leaving a
-					// signed-out account's notifications on the device is the worse of
-					// the two outcomes.
-					tokenInvalidated = false;
-				}
-			}
-
-			const cancelledIds = await deps.scheduler.cancelByOwner(ownerTag);
-			const { clearedCollections } = clearOwner(deps.state, ownerTag);
-
-			deps.emit?.(
-				'SIGN_OUT',
-				`Signed out ${ownerTag}: token ${tokenInvalidated ? 'invalidated' : 'not invalidated'}, ${cancelledIds.length} notification(s) cancelled, per-owner state cleared.`,
-				{ ownerTag, tokenInvalidated, cancelled: cancelledIds.length },
-			);
-
-			return { ownerTag, tokenInvalidated, cancelledIds, clearedCollections };
-		},
-	};
-}
-
-export type SignOut = ReturnType<typeof createSignOut>;
+/**
+ * Sign-out cleanup.
+ *
+ * Three things must happen together, and the order matters: invalidate the
+ * token first so no further messages arrive for the account being left, then
+ * cancel its notifications, then clear its persisted state.
+ *
+ * Deliberately **scoped to one owner tag**. On a shared device, signing one
+ * account out must not clear another's deduplication history or cancel their
+ * reminders — and must not discard the channel migration ledger, which
+ * describes the device rather than any account.
+ */
+
+import type { PushGate } from './gate';
+import type { Scheduler } from '../schedule';
+import type { StateManager } from '../state/record';
+import { clearOwner } from '../state/reset';
+
+export interface SignOutDependencies {
+	readonly scheduler: Scheduler;
+	readonly state: StateManager;
+	/** Absent for a local-only app, which still needs the rest of the cleanup. */
+	readonly push?: PushGate;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export interface SignOutResult {
+	readonly ownerTag: string;
+	readonly tokenInvalidated: boolean;
+	readonly cancelledIds: readonly string[];
+	readonly clearedCollections: readonly string[];
+}
+
+export function createSignOut(deps: SignOutDependencies) {
+	return {
+		async signOut(ownerTag: string): Promise<SignOutResult> {
+			// Token first: stop the inbound flow before removing what would have
+			// handled it, so nothing arrives for an account that is already gone.
+			let tokenInvalidated = false;
+			if (deps.push !== undefined) {
+				try {
+					tokenInvalidated = await deps.push.invalidateToken();
+				} catch {
+					// A failed invalidation must not prevent local cleanup — leaving a
+					// signed-out account's notifications on the device is the worse of
+					// the two outcomes.
+					tokenInvalidated = false;
+				}
+			}
+
+			const cancelledIds = await deps.scheduler.cancelByOwner(ownerTag);
+			const { clearedCollections } = clearOwner(deps.state, ownerTag);
+
+			deps.emit?.(
+				'SIGN_OUT',
+				`Signed out ${ownerTag}: token ${tokenInvalidated ? 'invalidated' : 'not invalidated'}, ${cancelledIds.length} notification(s) cancelled, per-owner state cleared.`,
+				{ ownerTag, tokenInvalidated, cancelled: cancelledIds.length },
+			);
+
+			return { ownerTag, tokenInvalidated, cancelledIds, clearedCollections };
+		},
+	};
+}
+
+export type SignOut = ReturnType<typeof createSignOut>;

package/src/reconcile/chunk.ts

@@ -1,53 +1,53 @@
-/**
- * Chunked application.
- *
- * A 500-entry reconciliation must not drop frames on a list screen, so work is
- * applied in slices with a yield between them. No single slice may occupy the
- * interface thread for more than 16 ms, which is what holds 60 fps while
- * reconciliation is in flight.
- */
-
-export const DEFAULT_CHUNK_SIZE = 25;
-
-/** Yields to the event loop so the interface thread can render between slices. */
-export function yieldToEventLoop(): Promise<void> {
-	return new Promise(resolve => setTimeout(resolve, 0));
-}
-
-export interface ChunkOptions {
-	readonly size?: number;
-	readonly onYield?: () => Promise<void>;
-}
-
-/**
- * Applies `work` to every item, yielding between chunks.
- *
- * Sequential within a chunk rather than parallel: these calls bridge to native,
- * and a burst of concurrent scheduling is where duplicate-delivery races come
- * from.
- */
-export async function applyInChunks<T>(
-	items: readonly T[],
-	work: (item: T) => Promise<void>,
-	options: ChunkOptions = {},
-): Promise<number> {
-	const size = Math.max(1, options.size ?? DEFAULT_CHUNK_SIZE);
-	const yieldFn = options.onYield ?? yieldToEventLoop;
-	let applied = 0;
-
-	for (let start = 0; start < items.length; start += size) {
-		const chunk = items.slice(start, start + size);
-
-		for (const item of chunk) {
-			await work(item);
-			applied += 1;
-		}
-
-		// No yield after the final chunk — the caller is about to resume anyway.
-		if (start + size < items.length) {
-			await yieldFn();
-		}
-	}
-
-	return applied;
-}
+/**
+ * Chunked application.
+ *
+ * A 500-entry reconciliation must not drop frames on a list screen, so work is
+ * applied in slices with a yield between them. No single slice may occupy the
+ * interface thread for more than 16 ms, which is what holds 60 fps while
+ * reconciliation is in flight.
+ */
+
+export const DEFAULT_CHUNK_SIZE = 25;
+
+/** Yields to the event loop so the interface thread can render between slices. */
+export function yieldToEventLoop(): Promise<void> {
+	return new Promise(resolve => setTimeout(resolve, 0));
+}
+
+export interface ChunkOptions {
+	readonly size?: number;
+	readonly onYield?: () => Promise<void>;
+}
+
+/**
+ * Applies `work` to every item, yielding between chunks.
+ *
+ * Sequential within a chunk rather than parallel: these calls bridge to native,
+ * and a burst of concurrent scheduling is where duplicate-delivery races come
+ * from.
+ */
+export async function applyInChunks<T>(
+	items: readonly T[],
+	work: (item: T) => Promise<void>,
+	options: ChunkOptions = {},
+): Promise<number> {
+	const size = Math.max(1, options.size ?? DEFAULT_CHUNK_SIZE);
+	const yieldFn = options.onYield ?? yieldToEventLoop;
+	let applied = 0;
+
+	for (let start = 0; start < items.length; start += size) {
+		const chunk = items.slice(start, start + size);
+
+		for (const item of chunk) {
+			await work(item);
+			applied += 1;
+		}
+
+		// No yield after the final chunk — the caller is about to resume anyway.
+		if (start + size < items.length) {
+			await yieldFn();
+		}
+	}
+
+	return applied;
+}

package/src/reconcile/diff.ts

@@ -1,145 +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 };
-}
+/**
+ * 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 };
+}