@chipmobilesdk/rn-notification 0.3.0 → 0.4.1

package/src/push/instructions.ts

@@ -1,109 +1,114 @@
-/**
- * Push-driven local scheduling.
- *
- * Where the two paths meet. A server can schedule or cancel a local
- * notification, and it gets **no privileged path**: an instruction arriving by
- * push passes exactly the same identifier validation, moment validation, tone
- * resolution, and permission rules as a request from app code.
- *
- * That symmetry is the point. A server that could bypass validation would be
- * able to put the device into a state the app itself could not produce, and no
- * amount of local correctness would survive it.
- */
-
-import type { PushEnvelope } from './provider-adapter';
-import type { Scheduler } from '../schedule';
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import { DIAGNOSTIC_CODES, isNotificationError } from '../contract/errors';
-
-export interface InstructionDependencies {
-	readonly scheduler: Scheduler;
-	readonly engine: NotificationEngineAdapter;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export type InstructionOutcome =
-	| { readonly kind: 'scheduled'; readonly id: string; readonly replaced: boolean }
-	| { readonly kind: 'cancelled'; readonly id: string }
-	| { readonly kind: 'suppressed'; readonly id: string; readonly reason: string }
-	| { readonly kind: 'rejected'; readonly id: string; readonly code: string; readonly reason: string }
-	| { readonly kind: 'ignored'; readonly id: string };
-
-export function createInstructionHandler(deps: InstructionDependencies) {
-	const emit = deps.emit ?? (() => {});
-
-	/**
-	 * Whether a local schedule already covers this event.
-	 *
-	 * Local wins: it is the entry the device can present at the right moment with
-	 * no network. A server that genuinely wants to override sends an explicit
-	 * cancel followed by a schedule, which is unambiguous in a way "last write
-	 * wins" is not.
-	 */
-	const localAlreadyCovers = async (id: string): Promise<boolean> => {
-		const pending = await deps.engine.getPending();
-		const existing = pending.find(entry => entry.id === id);
-		return existing !== undefined && !existing.pushCreated;
-	};
-
-	return {
-		async handle(envelope: PushEnvelope): Promise<InstructionOutcome> {
-			if (envelope.kind !== 'schedule' && envelope.kind !== 'cancel') {
-				return { kind: 'ignored', id: envelope.id };
-			}
-
-			try {
-				if (envelope.kind === 'cancel') {
-					await deps.scheduler.cancel(envelope.id);
-					return { kind: 'cancelled', id: envelope.id };
-				}
-
-				if (envelope.moment === undefined || envelope.content === undefined) {
-					throw Object.assign(
-						new Error('A schedule instruction must carry both a moment and content.'),
-						{ code: DIAGNOSTIC_CODES.PAYLOAD_MALFORMED },
-					);
-				}
-
-				if (await localAlreadyCovers(envelope.id)) {
-					emit(
-						DIAGNOSTIC_CODES.PAYLOAD_DUPLICATE,
-						'A local schedule already covers this event; the push instruction was suppressed so the user sees exactly one notification.',
-						{ id: envelope.id },
-					);
-					return {
-						kind: 'suppressed',
-						id: envelope.id,
-						reason: 'A local schedule already covers this event.',
-					};
-				}
-
-				const result = await deps.scheduler.schedule(
-					{
-						id: envelope.id,
-						content: envelope.content,
-						tone: envelope.tone ?? '',
-						moment: envelope.moment,
-						routing: envelope.routing,
-						ownerTag: envelope.ownerTag,
-					},
-					{ pushCreated: true },
-				);
-
-				return { kind: 'scheduled', id: envelope.id, replaced: result.replaced };
-			} catch (error) {
-				// Rejected under exactly the rules an app-initiated request would face,
-				// and recorded rather than swallowed.
-				const code = isNotificationError(error)
-					? error.code
-					: ((error as { code?: string }).code ?? 'UNKNOWN');
-				const reason = error instanceof Error ? error.message : String(error);
-
-				emit(code, `Push instruction rejected: ${reason}`, { id: envelope.id });
-				return { kind: 'rejected', id: envelope.id, code, reason };
-			}
-		},
-	};
-}
-
-export type InstructionHandler = ReturnType<typeof createInstructionHandler>;
+/**
+ * Push-driven local scheduling.
+ *
+ * Where the two paths meet. A server can schedule or cancel a local
+ * notification, and it gets **no privileged path**: an instruction arriving by
+ * push passes exactly the same identifier validation, moment validation, tone
+ * resolution, and permission rules as a request from app code.
+ *
+ * That symmetry is the point. A server that could bypass validation would be
+ * able to put the device into a state the app itself could not produce, and no
+ * amount of local correctness would survive it.
+ */
+
+import type { PushEnvelope } from './provider-adapter';
+import type { Scheduler } from '../schedule';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import { DIAGNOSTIC_CODES, isNotificationError } from '../contract/errors';
+
+export interface InstructionDependencies {
+	readonly scheduler: Scheduler;
+	readonly engine: NotificationEngineAdapter;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export type InstructionOutcome =
+	| { readonly kind: 'scheduled'; readonly id: string; readonly replaced: boolean }
+	| { readonly kind: 'cancelled'; readonly id: string }
+	| { readonly kind: 'suppressed'; readonly id: string; readonly reason: string }
+	| {
+			readonly kind: 'rejected';
+			readonly id: string;
+			readonly code: string;
+			readonly reason: string;
+	  }
+	| { readonly kind: 'ignored'; readonly id: string };
+
+export function createInstructionHandler(deps: InstructionDependencies) {
+	const emit = deps.emit ?? (() => {});
+
+	/**
+	 * Whether a local schedule already covers this event.
+	 *
+	 * Local wins: it is the entry the device can present at the right moment with
+	 * no network. A server that genuinely wants to override sends an explicit
+	 * cancel followed by a schedule, which is unambiguous in a way "last write
+	 * wins" is not.
+	 */
+	const localAlreadyCovers = async (id: string): Promise<boolean> => {
+		const pending = await deps.engine.getPending();
+		const existing = pending.find(entry => entry.id === id);
+		return existing !== undefined && !existing.pushCreated;
+	};
+
+	return {
+		async handle(envelope: PushEnvelope): Promise<InstructionOutcome> {
+			if (envelope.kind !== 'schedule' && envelope.kind !== 'cancel') {
+				return { kind: 'ignored', id: envelope.id };
+			}
+
+			try {
+				if (envelope.kind === 'cancel') {
+					await deps.scheduler.cancel(envelope.id);
+					return { kind: 'cancelled', id: envelope.id };
+				}
+
+				if (envelope.moment === undefined || envelope.content === undefined) {
+					throw Object.assign(
+						new Error('A schedule instruction must carry both a moment and content.'),
+						{ code: DIAGNOSTIC_CODES.PAYLOAD_MALFORMED },
+					);
+				}
+
+				if (await localAlreadyCovers(envelope.id)) {
+					emit(
+						DIAGNOSTIC_CODES.PAYLOAD_DUPLICATE,
+						'A local schedule already covers this event; the push instruction was suppressed so the user sees exactly one notification.',
+						{ id: envelope.id },
+					);
+					return {
+						kind: 'suppressed',
+						id: envelope.id,
+						reason: 'A local schedule already covers this event.',
+					};
+				}
+
+				const result = await deps.scheduler.schedule(
+					{
+						id: envelope.id,
+						content: envelope.content,
+						tone: envelope.tone ?? '',
+						moment: envelope.moment,
+						routing: envelope.routing,
+						ownerTag: envelope.ownerTag,
+					},
+					{ pushCreated: true },
+				);
+
+				return { kind: 'scheduled', id: envelope.id, replaced: result.replaced };
+			} catch (error) {
+				// Rejected under exactly the rules an app-initiated request would face,
+				// and recorded rather than swallowed.
+				const code = isNotificationError(error)
+					? error.code
+					: ((error as { code?: string }).code ?? 'UNKNOWN');
+				const reason = error instanceof Error ? error.message : String(error);
+
+				emit(code, `Push instruction rejected: ${reason}`, { id: envelope.id });
+				return { kind: 'rejected', id: envelope.id, code, reason };
+			}
+		},
+	};
+}
+
+export type InstructionHandler = ReturnType<typeof createInstructionHandler>;

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;
+}