@chipmobilesdk/rn-notification 0.1.1 → 0.2.0

package/src/diagnostics/burst.ts

@@ -1,101 +1,101 @@
-/**
- * Burst detection.
- *
- * Both platforms apply undocumented delivery rate limits and will silently drop
- * or delay past them — which is exactly the invisible failure this package
- * exists to eliminate. So volume is watched and reported.
- *
- * It is **not** acted upon. Nothing is throttled, delayed, coalesced, or
- * dropped: deciding which of a user's notifications to suppress is a product
- * decision the package has no basis to make. Noticing that something abnormal
- * is happening is one it can.
- *
- * Counters are in memory only. A burst is a live condition, and persisting it
- * would expand the state contract for no diagnostic gain.
- */
-
-import type { BurstThreshold } from '../contract/diagnostics';
-import { DEFAULT_BURST_THRESHOLD } from '../contract/diagnostics';
-import { DIAGNOSTIC_CODES } from '../contract/errors';
-
-const MINUTE_MS = 60_000;
-const HOUR_MS = 60 * MINUTE_MS;
-
-export interface BurstDetectorDependencies {
-	readonly threshold?: BurstThreshold;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export interface BurstStatus {
-	readonly ownerTag: string;
-	readonly lastMinute: number;
-	readonly lastHour: number;
-	readonly exceeded: boolean;
-}
-
-export function createBurstDetector(deps: BurstDetectorDependencies = {}) {
-	const threshold = deps.threshold ?? DEFAULT_BURST_THRESHOLD;
-	const emit = deps.emit ?? (() => {});
-	/** Per owner tag, because one busy account should not implicate another. */
-	const timestamps = new Map<string, number[]>();
-	/** Prevents one sustained burst producing a diagnostic per notification. */
-	const reportedAt = new Map<string, number>();
-
-	const prune = (tag: string, now: number): number[] => {
-		const kept = (timestamps.get(tag) ?? []).filter(at => now - at <= HOUR_MS);
-		timestamps.set(tag, kept);
-		return kept;
-	};
-
-	return {
-		/**
-		 * Records one presented notification and reports if the threshold is crossed.
-		 *
-		 * Always returns after recording — the caller delivers regardless of what
-		 * this says.
-		 */
-		record(now: number, ownerTag = '*'): BurstStatus {
-			const kept = prune(ownerTag, now);
-			kept.push(now);
-
-			const lastMinute = kept.filter(at => now - at <= MINUTE_MS).length;
-			const lastHour = kept.length;
-			const exceeded = lastMinute > threshold.perMinute || lastHour > threshold.perHour;
-
-			if (exceeded) {
-				const last = reportedAt.get(ownerTag) ?? 0;
-				// One report per minute per tag; a sustained burst is one condition,
-				// not a hundred.
-				if (now - last >= MINUTE_MS) {
-					reportedAt.set(ownerTag, now);
-					emit(
-						DIAGNOSTIC_CODES.BURST_THRESHOLD_EXCEEDED,
-						`Abnormal notification volume: ${lastMinute} in the last minute and ${lastHour} in the last hour (thresholds ${threshold.perMinute}/minute, ${threshold.perHour}/hour). Every notification was still delivered — the package throttles nothing.`,
-						{ ownerTag, lastMinute, lastHour, threshold },
-					);
-				}
-			}
-
-			return { ownerTag, lastMinute, lastHour, exceeded };
-		},
-
-		status(now: number, ownerTag = '*'): BurstStatus {
-			const kept = prune(ownerTag, now);
-			const lastMinute = kept.filter(at => now - at <= MINUTE_MS).length;
-
-			return {
-				ownerTag,
-				lastMinute,
-				lastHour: kept.length,
-				exceeded: lastMinute > threshold.perMinute || kept.length > threshold.perHour,
-			};
-		},
-
-		reset(): void {
-			timestamps.clear();
-			reportedAt.clear();
-		},
-	};
-}
-
-export type BurstDetector = ReturnType<typeof createBurstDetector>;
+/**
+ * Burst detection.
+ *
+ * Both platforms apply undocumented delivery rate limits and will silently drop
+ * or delay past them — which is exactly the invisible failure this package
+ * exists to eliminate. So volume is watched and reported.
+ *
+ * It is **not** acted upon. Nothing is throttled, delayed, coalesced, or
+ * dropped: deciding which of a user's notifications to suppress is a product
+ * decision the package has no basis to make. Noticing that something abnormal
+ * is happening is one it can.
+ *
+ * Counters are in memory only. A burst is a live condition, and persisting it
+ * would expand the state contract for no diagnostic gain.
+ */
+
+import type { BurstThreshold } from '../contract/diagnostics';
+import { DEFAULT_BURST_THRESHOLD } from '../contract/diagnostics';
+import { DIAGNOSTIC_CODES } from '../contract/errors';
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+
+export interface BurstDetectorDependencies {
+	readonly threshold?: BurstThreshold;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export interface BurstStatus {
+	readonly ownerTag: string;
+	readonly lastMinute: number;
+	readonly lastHour: number;
+	readonly exceeded: boolean;
+}
+
+export function createBurstDetector(deps: BurstDetectorDependencies = {}) {
+	const threshold = deps.threshold ?? DEFAULT_BURST_THRESHOLD;
+	const emit = deps.emit ?? (() => {});
+	/** Per owner tag, because one busy account should not implicate another. */
+	const timestamps = new Map<string, number[]>();
+	/** Prevents one sustained burst producing a diagnostic per notification. */
+	const reportedAt = new Map<string, number>();
+
+	const prune = (tag: string, now: number): number[] => {
+		const kept = (timestamps.get(tag) ?? []).filter(at => now - at <= HOUR_MS);
+		timestamps.set(tag, kept);
+		return kept;
+	};
+
+	return {
+		/**
+		 * Records one presented notification and reports if the threshold is crossed.
+		 *
+		 * Always returns after recording — the caller delivers regardless of what
+		 * this says.
+		 */
+		record(now: number, ownerTag = '*'): BurstStatus {
+			const kept = prune(ownerTag, now);
+			kept.push(now);
+
+			const lastMinute = kept.filter(at => now - at <= MINUTE_MS).length;
+			const lastHour = kept.length;
+			const exceeded = lastMinute > threshold.perMinute || lastHour > threshold.perHour;
+
+			if (exceeded) {
+				const last = reportedAt.get(ownerTag) ?? 0;
+				// One report per minute per tag; a sustained burst is one condition,
+				// not a hundred.
+				if (now - last >= MINUTE_MS) {
+					reportedAt.set(ownerTag, now);
+					emit(
+						DIAGNOSTIC_CODES.BURST_THRESHOLD_EXCEEDED,
+						`Abnormal notification volume: ${lastMinute} in the last minute and ${lastHour} in the last hour (thresholds ${threshold.perMinute}/minute, ${threshold.perHour}/hour). Every notification was still delivered — the package throttles nothing.`,
+						{ ownerTag, lastMinute, lastHour, threshold },
+					);
+				}
+			}
+
+			return { ownerTag, lastMinute, lastHour, exceeded };
+		},
+
+		status(now: number, ownerTag = '*'): BurstStatus {
+			const kept = prune(ownerTag, now);
+			const lastMinute = kept.filter(at => now - at <= MINUTE_MS).length;
+
+			return {
+				ownerTag,
+				lastMinute,
+				lastHour: kept.length,
+				exceeded: lastMinute > threshold.perMinute || kept.length > threshold.perHour,
+			};
+		},
+
+		reset(): void {
+			timestamps.clear();
+			reportedAt.clear();
+		},
+	};
+}
+
+export type BurstDetector = ReturnType<typeof createBurstDetector>;

package/src/diagnostics/events.ts

@@ -1,72 +1,72 @@
-/**
- * The structured event stream.
- *
- * With no sink attached the package emits nothing and buffers nothing. A
- * library that writes to the console in production has decided something for
- * its consumer; this one routes events wherever the app already sends its logs,
- * or stays silent.
- */
-
-import type { DiagnosticEvent, DiagnosticSeverity, EventSink } from '../contract/diagnostics';
-import type { DiagnosticCode } from '../contract/errors';
-import { isNonFailure } from '../contract/errors';
-import { redactContext } from './redact';
-
-export interface EmitterOptions {
-	readonly sink?: EventSink;
-	readonly verbose?: boolean;
-	readonly now?: () => number;
-}
-
-export class DiagnosticEmitter {
-	private sink?: EventSink;
-	private verbose: boolean;
-	private readonly now: () => number;
-
-	constructor(options: EmitterOptions = {}) {
-		this.sink = options.sink;
-		this.verbose = options.verbose ?? false;
-		this.now = options.now ?? (() => Date.now());
-	}
-
-	setSink(sink: EventSink | undefined): void {
-		this.sink = sink;
-	}
-
-	setVerbose(verbose: boolean): void {
-		this.verbose = verbose;
-	}
-
-	get hasSink(): boolean {
-		return this.sink !== undefined;
-	}
-
-	emit(
-		code: DiagnosticCode,
-		message: string,
-		context?: Readonly<Record<string, unknown>>,
-		severity?: DiagnosticSeverity,
-	): void {
-		// No sink means no work at all — not a buffer that grows until one appears.
-		if (this.sink === undefined) return;
-
-		const event: DiagnosticEvent = {
-			code,
-			severity: severity ?? (isNonFailure(code) ? 'info' : 'error'),
-			message,
-			at: this.now(),
-			context: redactContext(context, this.verbose),
-		};
-
-		try {
-			this.sink(event);
-		} catch {
-			// A failing sink is the consumer's problem and must never become ours.
-		}
-	}
-
-	/** Lifecycle transitions that are not failures: scheduled, delivered, reconciled. */
-	info(code: DiagnosticCode, message: string, context?: Readonly<Record<string, unknown>>): void {
-		this.emit(code, message, context, 'info');
-	}
-}
+/**
+ * The structured event stream.
+ *
+ * With no sink attached the package emits nothing and buffers nothing. A
+ * library that writes to the console in production has decided something for
+ * its consumer; this one routes events wherever the app already sends its logs,
+ * or stays silent.
+ */
+
+import type { DiagnosticEvent, DiagnosticSeverity, EventSink } from '../contract/diagnostics';
+import type { DiagnosticCode } from '../contract/errors';
+import { isNonFailure } from '../contract/errors';
+import { redactContext } from './redact';
+
+export interface EmitterOptions {
+	readonly sink?: EventSink;
+	readonly verbose?: boolean;
+	readonly now?: () => number;
+}
+
+export class DiagnosticEmitter {
+	private sink?: EventSink;
+	private verbose: boolean;
+	private readonly now: () => number;
+
+	constructor(options: EmitterOptions = {}) {
+		this.sink = options.sink;
+		this.verbose = options.verbose ?? false;
+		this.now = options.now ?? (() => Date.now());
+	}
+
+	setSink(sink: EventSink | undefined): void {
+		this.sink = sink;
+	}
+
+	setVerbose(verbose: boolean): void {
+		this.verbose = verbose;
+	}
+
+	get hasSink(): boolean {
+		return this.sink !== undefined;
+	}
+
+	emit(
+		code: DiagnosticCode,
+		message: string,
+		context?: Readonly<Record<string, unknown>>,
+		severity?: DiagnosticSeverity,
+	): void {
+		// No sink means no work at all — not a buffer that grows until one appears.
+		if (this.sink === undefined) return;
+
+		const event: DiagnosticEvent = {
+			code,
+			severity: severity ?? (isNonFailure(code) ? 'info' : 'error'),
+			message,
+			at: this.now(),
+			context: redactContext(context, this.verbose),
+		};
+
+		try {
+			this.sink(event);
+		} catch {
+			// A failing sink is the consumer's problem and must never become ours.
+		}
+	}
+
+	/** Lifecycle transitions that are not failures: scheduled, delivered, reconciled. */
+	info(code: DiagnosticCode, message: string, context?: Readonly<Record<string, unknown>>): void {
+		this.emit(code, message, context, 'info');
+	}
+}

package/src/diagnostics/redact.ts

@@ -1,72 +1,72 @@
-/**
- * Content redaction for diagnostics.
- *
- * A notification library that logs notification bodies has turned a diagnostic
- * aid into a privacy incident. Nothing content-bearing reaches an event unless
- * verbose diagnostics is explicitly enabled — and that setting is documented as
- * unsuitable for production.
- *
- * Values are replaced by their *shape* — a length, a type, a character position
- * — which is what actually helps someone debug a validation failure anyway.
- */
-
-/** Keys whose values are never emitted at any verbosity below verbose. */
-const REDACTED_KEYS = new Set([
-	'title',
-	'body',
-	'subtitle',
-	'content',
-	'routing',
-	'routingPayload',
-	'payload',
-	'token',
-	'pushToken',
-	'inputText',
-	'text',
-	'data',
-]);
-
-const REDACTED = '[redacted]';
-
-function describe(value: unknown): string {
-	if (value === null) return '[null]';
-	if (value === undefined) return '[undefined]';
-	if (typeof value === 'string') return `[string:${value.length}]`;
-	if (typeof value === 'number' || typeof value === 'boolean') return REDACTED;
-	if (Array.isArray(value)) return `[array:${value.length}]`;
-	if (typeof value === 'object') return `[object:${Object.keys(value).length}]`;
-	return REDACTED;
-}
-
-/**
- * Strips content values from a diagnostic context.
- *
- * Recurses so a nested `{ request: { content: { body } } }` is caught — a
- * top-level-only scrub is the kind of redaction that leaks the first time
- * anyone nests a payload.
- */
-export function redactContext(
-	context: Readonly<Record<string, unknown>> | undefined,
-	verbose: boolean,
-): Readonly<Record<string, unknown>> | undefined {
-	if (context === undefined) return undefined;
-	if (verbose) return context;
-
-	const walk = (value: unknown, depth: number): unknown => {
-		if (depth > 6 || value === null || typeof value !== 'object') return value;
-		if (Array.isArray(value)) return value.map(item => walk(item, depth + 1));
-
-		const output: Record<string, unknown> = {};
-		for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
-			output[key] = REDACTED_KEYS.has(key) ? describe(inner) : walk(inner, depth + 1);
-		}
-		return output;
-	};
-
-	return walk(context, 0) as Readonly<Record<string, unknown>>;
-}
-
-/** True when a key would be redacted. Exported so tests can assert the policy directly. */
-export function isRedactedKey(key: string): boolean {
-	return REDACTED_KEYS.has(key);
-}
+/**
+ * Content redaction for diagnostics.
+ *
+ * A notification library that logs notification bodies has turned a diagnostic
+ * aid into a privacy incident. Nothing content-bearing reaches an event unless
+ * verbose diagnostics is explicitly enabled — and that setting is documented as
+ * unsuitable for production.
+ *
+ * Values are replaced by their *shape* — a length, a type, a character position
+ * — which is what actually helps someone debug a validation failure anyway.
+ */
+
+/** Keys whose values are never emitted at any verbosity below verbose. */
+const REDACTED_KEYS = new Set([
+	'title',
+	'body',
+	'subtitle',
+	'content',
+	'routing',
+	'routingPayload',
+	'payload',
+	'token',
+	'pushToken',
+	'inputText',
+	'text',
+	'data',
+]);
+
+const REDACTED = '[redacted]';
+
+function describe(value: unknown): string {
+	if (value === null) return '[null]';
+	if (value === undefined) return '[undefined]';
+	if (typeof value === 'string') return `[string:${value.length}]`;
+	if (typeof value === 'number' || typeof value === 'boolean') return REDACTED;
+	if (Array.isArray(value)) return `[array:${value.length}]`;
+	if (typeof value === 'object') return `[object:${Object.keys(value).length}]`;
+	return REDACTED;
+}
+
+/**
+ * Strips content values from a diagnostic context.
+ *
+ * Recurses so a nested `{ request: { content: { body } } }` is caught — a
+ * top-level-only scrub is the kind of redaction that leaks the first time
+ * anyone nests a payload.
+ */
+export function redactContext(
+	context: Readonly<Record<string, unknown>> | undefined,
+	verbose: boolean,
+): Readonly<Record<string, unknown>> | undefined {
+	if (context === undefined) return undefined;
+	if (verbose) return context;
+
+	const walk = (value: unknown, depth: number): unknown => {
+		if (depth > 6 || value === null || typeof value !== 'object') return value;
+		if (Array.isArray(value)) return value.map(item => walk(item, depth + 1));
+
+		const output: Record<string, unknown> = {};
+		for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
+			output[key] = REDACTED_KEYS.has(key) ? describe(inner) : walk(inner, depth + 1);
+		}
+		return output;
+	};
+
+	return walk(context, 0) as Readonly<Record<string, unknown>>;
+}
+
+/** True when a key would be redacted. Exported so tests can assert the policy directly. */
+export function isRedactedKey(key: string): boolean {
+	return REDACTED_KEYS.has(key);
+}

package/src/diagnostics/snapshot.ts

@@ -1,64 +1,64 @@
-/**
- * The state snapshot.
- *
- * The readable answer to "why didn't it arrive?" — assembled in one place so
- * that question can be answered without attaching a native debugger.
- *
- * The push token appears as **presence only**. Its value is never exposed here
- * or anywhere else, because a snapshot is the thing most likely to be pasted
- * into a bug report.
- */
-
-import type { StateSnapshot } from '../contract/diagnostics';
-import type { PendingEntry } from '../contract/notification';
-import type { PermissionReport, RestrictionReport } from '../contract/permission';
-import type { MaintenanceResult, PendingDiscrepancy, ReconcileResult } from '../contract/reconcile';
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import type { StateManager } from '../state/record';
-
-export interface SnapshotDependencies {
-	readonly engine: NotificationEngineAdapter;
-	readonly state: StateManager;
-	readonly now: () => number;
-	readonly permissions: () => Promise<PermissionReport>;
-	readonly restrictions: () => Promise<RestrictionReport>;
-	readonly appliedTones: () => readonly { readonly toneId: string; readonly appliedVersion: number }[];
-	readonly lastReconcile: () => ReconcileResult | undefined;
-	readonly lastMaintenance: () => MaintenanceResult | undefined;
-	/** Presence only — never the value. */
-	readonly hasPushToken: () => boolean;
-}
-
-export function createSnapshot(deps: SnapshotDependencies) {
-	return {
-		async capture(): Promise<StateSnapshot> {
-			const [permissions, restrictions, pending] = await Promise.all([
-				deps.permissions(),
-				deps.restrictions(),
-				deps.engine.getPending(),
-			]);
-
-			const maintenance = deps.lastMaintenance();
-			const discrepancy: PendingDiscrepancy | undefined = maintenance?.discrepancy;
-
-			return {
-				permissions,
-				restrictions,
-				tones: deps.appliedTones().map(tone => ({
-					id: tone.toneId,
-					appliedVersion: tone.appliedVersion,
-				})),
-				pendingCount: pending.length,
-				pending: pending as readonly PendingEntry[],
-				lastReconcile: deps.lastReconcile(),
-				lastMaintenance: maintenance,
-				discrepancy,
-				stateHealth: deps.state.health(),
-				pushTokenPresent: deps.hasPushToken(),
-				capturedAt: deps.now(),
-			};
-		},
-	};
-}
-
-export type Snapshot = ReturnType<typeof createSnapshot>;
+/**
+ * The state snapshot.
+ *
+ * The readable answer to "why didn't it arrive?" — assembled in one place so
+ * that question can be answered without attaching a native debugger.
+ *
+ * The push token appears as **presence only**. Its value is never exposed here
+ * or anywhere else, because a snapshot is the thing most likely to be pasted
+ * into a bug report.
+ */
+
+import type { StateSnapshot } from '../contract/diagnostics';
+import type { PendingEntry } from '../contract/notification';
+import type { PermissionReport, RestrictionReport } from '../contract/permission';
+import type { MaintenanceResult, PendingDiscrepancy, ReconcileResult } from '../contract/reconcile';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { StateManager } from '../state/record';
+
+export interface SnapshotDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly state: StateManager;
+	readonly now: () => number;
+	readonly permissions: () => Promise<PermissionReport>;
+	readonly restrictions: () => Promise<RestrictionReport>;
+	readonly appliedTones: () => readonly { readonly toneId: string; readonly appliedVersion: number }[];
+	readonly lastReconcile: () => ReconcileResult | undefined;
+	readonly lastMaintenance: () => MaintenanceResult | undefined;
+	/** Presence only — never the value. */
+	readonly hasPushToken: () => boolean;
+}
+
+export function createSnapshot(deps: SnapshotDependencies) {
+	return {
+		async capture(): Promise<StateSnapshot> {
+			const [permissions, restrictions, pending] = await Promise.all([
+				deps.permissions(),
+				deps.restrictions(),
+				deps.engine.getPending(),
+			]);
+
+			const maintenance = deps.lastMaintenance();
+			const discrepancy: PendingDiscrepancy | undefined = maintenance?.discrepancy;
+
+			return {
+				permissions,
+				restrictions,
+				tones: deps.appliedTones().map(tone => ({
+					id: tone.toneId,
+					appliedVersion: tone.appliedVersion,
+				})),
+				pendingCount: pending.length,
+				pending: pending as readonly PendingEntry[],
+				lastReconcile: deps.lastReconcile(),
+				lastMaintenance: maintenance,
+				discrepancy,
+				stateHealth: deps.state.health(),
+				pushTokenPresent: deps.hasPushToken(),
+				capturedAt: deps.now(),
+			};
+		},
+	};
+}
+
+export type Snapshot = ReturnType<typeof createSnapshot>;