@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/schedule/writer.ts

@@ -1,55 +1,55 @@
-/**
- * The one door every consumer notification goes through to reach the engine.
- *
- * Scheduler, reconciler, recurrence, re-anchoring and channel re-homing all
- * write notifications. Each used to call `engine.schedule` itself, and the
- * guarantees attached to a write — a repeating alert gets its stop marker, and
- * that marker moves when the notification moves — existed only on the paths
- * that remembered them. A recurring alarm never stopped, and a re-anchored one
- * stopped at the old instant.
- *
- * Validation stays with each caller, because each has its own failure policy:
- * the scheduler throws, reconciliation rejects one entry and carries on, and
- * recurrence validates its template once at registration.
- */
-
-import type { NotificationEngineAdapter, EngineScheduleRequest } from '../engine/adapter';
-import { createStopPlacement } from '../repeat/place';
-
-export interface ScheduleWriter {
-	/** Writes one notification and brings its stop marker in line with it. */
-	write(input: EngineScheduleRequest): Promise<void>;
-	/** Cancels one notification and the marker guarding it. */
-	cancel(id: string): Promise<void>;
-	/** Drops the marker for a notification already cancelled some other way. */
-	releaseStop(targetId: string): Promise<void>;
-	/**
-	 * Platform slots consumer notifications can actually use: stop markers hold
-	 * real capacity, so the usable ceiling is the platform's minus theirs.
-	 */
-	capacity(): Promise<number>;
-}
-
-export function createScheduleWriter(engine: NotificationEngineAdapter): ScheduleWriter {
-	const stops = createStopPlacement(engine);
-
-	return {
-		async write(input) {
-			await engine.schedule(input);
-			await stops.sync(input.request.id, input.tone, input.resolvedAt);
-		},
-
-		async cancel(id) {
-			await engine.cancel(id);
-			await stops.release(id);
-		},
-
-		releaseStop: targetId => stops.release(targetId),
-
-		async capacity() {
-			const capabilities = await engine.getCapabilities();
-			const markerCost = (await engine.listRepeatStops()).length;
-			return Math.max(0, capabilities.pendingCeiling - markerCost);
-		},
-	};
-}
+/**
+ * The one door every consumer notification goes through to reach the engine.
+ *
+ * Scheduler, reconciler, recurrence, re-anchoring and channel re-homing all
+ * write notifications. Each used to call `engine.schedule` itself, and the
+ * guarantees attached to a write — a repeating alert gets its stop marker, and
+ * that marker moves when the notification moves — existed only on the paths
+ * that remembered them. A recurring alarm never stopped, and a re-anchored one
+ * stopped at the old instant.
+ *
+ * Validation stays with each caller, because each has its own failure policy:
+ * the scheduler throws, reconciliation rejects one entry and carries on, and
+ * recurrence validates its template once at registration.
+ */
+
+import type { NotificationEngineAdapter, EngineScheduleRequest } from '../engine/adapter';
+import { createStopPlacement } from '../repeat/place';
+
+export interface ScheduleWriter {
+	/** Writes one notification and brings its stop marker in line with it. */
+	write(input: EngineScheduleRequest): Promise<void>;
+	/** Cancels one notification and the marker guarding it. */
+	cancel(id: string): Promise<void>;
+	/** Drops the marker for a notification already cancelled some other way. */
+	releaseStop(targetId: string): Promise<void>;
+	/**
+	 * Platform slots consumer notifications can actually use: stop markers hold
+	 * real capacity, so the usable ceiling is the platform's minus theirs.
+	 */
+	capacity(): Promise<number>;
+}
+
+export function createScheduleWriter(engine: NotificationEngineAdapter): ScheduleWriter {
+	const stops = createStopPlacement(engine);
+
+	return {
+		async write(input) {
+			await engine.schedule(input);
+			await stops.sync(input.request.id, input.tone, input.resolvedAt);
+		},
+
+		async cancel(id) {
+			await engine.cancel(id);
+			await stops.release(id);
+		},
+
+		releaseStop: targetId => stops.release(targetId),
+
+		async capacity() {
+			const capabilities = await engine.getCapabilities();
+			const markerCost = (await engine.listRepeatStops()).length;
+			return Math.max(0, capabilities.pendingCeiling - markerCost);
+		},
+	};
+}

package/src/state/caps.ts

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

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

package/src/state/interaction-buffer.ts

@@ -1,73 +1,101 @@
-/**
- * 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;
-}
+/**
+ * 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.
+ *
+ * Text the user typed into a reply action is never written to disk (NOT-14): it
+ * is free text, and the store is not encrypted. It is held in memory beside the
+ * buffer, so a handler registered later in the same process still receives it;
+ * if the process dies first, the event is delivered without `inputText`.
+ */
+
+import type { StateManager, BufferedInteraction } from './record';
+import type { InteractionEvent } from '../contract/interaction';
+
+/** Typed replies, in memory only, per state manager and buffered event id. */
+const typedReplies = new WeakMap<StateManager, Map<string, string>>();
+
+function repliesOf(state: StateManager): Map<string, string> {
+	let replies = typedReplies.get(state);
+	if (!replies) {
+		replies = new Map();
+		typedReplies.set(state, replies);
+	}
+	return replies;
+}
+
+/** 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);
+	if (event.inputText !== undefined) {
+		repliesOf(state).set(id, event.inputText);
+	}
+
+	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,
+			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', () => []);
+	const replies = repliesOf(state);
+
+	return buffered.map(entry => ({
+		kind: entry.kind,
+		notificationId: entry.notificationId,
+		actionId: entry.actionId,
+		// A record written before 0.5 may still carry the text on disk; it is
+		// delivered once, and the buffer was just cleared.
+		inputText: takeReply(replies, entry.id) ?? 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;
+}
+
+function takeReply(replies: Map<string, string>, id: string): string | undefined {
+	const text = replies.get(id);
+	replies.delete(id);
+	return text;
+}