@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/contract/recurrence.ts

@@ -1,129 +1,129 @@
-/**
- * Recurrence declaration types.
- *
- * A caller declares a rule once; the package expands it inside a finite
- * lookahead window. No caller ever writes an expansion loop, and no unbounded
- * series is ever handed to the platform.
- */
-
-import type { AnchoringMode, NotificationContent, Action, RoutingPayload } from './notification';
-
-/** Days of the week, `0` = Sunday, matching `Date.prototype.getDay`. */
-export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
-
-/** Every day at the declared clock time. */
-export interface DailyPattern {
-	readonly kind: 'daily';
-	readonly hour: number;
-	readonly minute: number;
-	/** Fire every `interval` days. Defaults to 1. */
-	readonly interval?: number;
-}
-
-/** Selected weekdays at the declared clock time. */
-export interface WeeklyPattern {
-	readonly kind: 'weekly';
-	readonly weekdays: readonly Weekday[];
-	readonly hour: number;
-	readonly minute: number;
-	/** Fire every `interval` weeks. Defaults to 1. */
-	readonly interval?: number;
-}
-
-/**
- * A fixed day of the month at the declared clock time.
- *
- * Months shorter than `dayOfMonth` are skipped rather than clamped: a caller
- * asking for the 31st means the 31st, and inventing the 28th would be the
- * package deciding something it was not asked to decide.
- */
-export interface MonthlyByDayPattern {
-	readonly kind: 'monthlyByDay';
-	readonly dayOfMonth: number;
-	readonly hour: number;
-	readonly minute: number;
-	/** Fire every `interval` months. Defaults to 1. */
-	readonly interval?: number;
-}
-
-export type RecurrencePattern = DailyPattern | WeeklyPattern | MonthlyByDayPattern;
-
-/** When a series stops producing occurrences. */
-export type EndCondition =
-	| { readonly kind: 'unbounded' }
-	| { readonly kind: 'untilDate'; readonly until: number }
-	| { readonly kind: 'count'; readonly count: number };
-
-/** Content shared by every occurrence of a series. Identity and moment are derived. */
-export interface OccurrenceTemplate {
-	readonly content: NotificationContent;
-	readonly tone: string;
-	readonly routing?: RoutingPayload;
-	readonly actions?: readonly Action[];
-	readonly ownerTag?: string;
-	readonly groupTag?: string;
-}
-
-export interface RecurrenceRule {
-	/** Stable series identifier, subject to the same charset rules as a notification id. */
-	readonly id: string;
-	readonly pattern: RecurrencePattern;
-	/**
-	 * Declared once for the whole series and inherited by every occurrence.
-	 * A series may not mix modes. Defaults to `wallClock`.
-	 */
-	readonly anchoring?: AnchoringMode;
-	/** The instant from which occurrences are generated. Defaults to now. */
-	readonly startAt?: number;
-	readonly end: EndCondition;
-	readonly template: OccurrenceTemplate;
-}
-
-/**
- * How far ahead occurrences are registered with the platform.
- *
- * Bounded by both a duration and a count because either alone fails: a duration
- * alone lets a frequent series exhaust the platform ceiling, and a count alone
- * leaves an annual series scheduled a decade out.
- */
-export interface LookaheadConfig {
-	readonly days: number;
-	readonly occurrencesPerSeries: number;
-}
-
-export const DEFAULT_LOOKAHEAD: LookaheadConfig = {
-	days: 60,
-	occurrencesPerSeries: 32,
-};
-
-/** Bounds on consumer adjustment, because the platform ceiling is not negotiable. */
-export const LOOKAHEAD_BOUNDS = {
-	minDays: 1,
-	maxDays: 365,
-	minOccurrences: 1,
-	maxOccurrences: 64,
-} as const;
-
-export interface SeriesResult {
-	readonly seriesId: string;
-	/** Occurrences registered with the platform in this pass. */
-	readonly scheduled: number;
-	/** The horizon expansion reached, in epoch milliseconds. */
-	readonly expandedThrough: number;
-	/** True when the series has produced its final occurrence. */
-	readonly exhausted: boolean;
-	/**
-	 * Upcoming occurrences of this series removed because the expansion no longer
-	 * produces them — identifiers from before 0.4.0, or slots the rule dropped.
-	 * Added in 0.4.0.
-	 */
-	readonly cancelled?: readonly string[];
-}
-
-export interface SeriesSummary {
-	readonly seriesId: string;
-	readonly anchoring: AnchoringMode;
-	readonly expandedThrough: number;
-	readonly pendingOccurrences: number;
-	readonly exhausted: boolean;
-}
+/**
+ * Recurrence declaration types.
+ *
+ * A caller declares a rule once; the package expands it inside a finite
+ * lookahead window. No caller ever writes an expansion loop, and no unbounded
+ * series is ever handed to the platform.
+ */
+
+import type { AnchoringMode, NotificationContent, Action, RoutingPayload } from './notification';
+
+/** Days of the week, `0` = Sunday, matching `Date.prototype.getDay`. */
+export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+/** Every day at the declared clock time. */
+export interface DailyPattern {
+	readonly kind: 'daily';
+	readonly hour: number;
+	readonly minute: number;
+	/** Fire every `interval` days. Defaults to 1. */
+	readonly interval?: number;
+}
+
+/** Selected weekdays at the declared clock time. */
+export interface WeeklyPattern {
+	readonly kind: 'weekly';
+	readonly weekdays: readonly Weekday[];
+	readonly hour: number;
+	readonly minute: number;
+	/** Fire every `interval` weeks. Defaults to 1. */
+	readonly interval?: number;
+}
+
+/**
+ * A fixed day of the month at the declared clock time.
+ *
+ * Months shorter than `dayOfMonth` are skipped rather than clamped: a caller
+ * asking for the 31st means the 31st, and inventing the 28th would be the
+ * package deciding something it was not asked to decide.
+ */
+export interface MonthlyByDayPattern {
+	readonly kind: 'monthlyByDay';
+	readonly dayOfMonth: number;
+	readonly hour: number;
+	readonly minute: number;
+	/** Fire every `interval` months. Defaults to 1. */
+	readonly interval?: number;
+}
+
+export type RecurrencePattern = DailyPattern | WeeklyPattern | MonthlyByDayPattern;
+
+/** When a series stops producing occurrences. */
+export type EndCondition =
+	| { readonly kind: 'unbounded' }
+	| { readonly kind: 'untilDate'; readonly until: number }
+	| { readonly kind: 'count'; readonly count: number };
+
+/** Content shared by every occurrence of a series. Identity and moment are derived. */
+export interface OccurrenceTemplate {
+	readonly content: NotificationContent;
+	readonly tone: string;
+	readonly routing?: RoutingPayload;
+	readonly actions?: readonly Action[];
+	readonly ownerTag?: string;
+	readonly groupTag?: string;
+}
+
+export interface RecurrenceRule {
+	/** Stable series identifier, subject to the same charset rules as a notification id. */
+	readonly id: string;
+	readonly pattern: RecurrencePattern;
+	/**
+	 * Declared once for the whole series and inherited by every occurrence.
+	 * A series may not mix modes. Defaults to `wallClock`.
+	 */
+	readonly anchoring?: AnchoringMode;
+	/** The instant from which occurrences are generated. Defaults to now. */
+	readonly startAt?: number;
+	readonly end: EndCondition;
+	readonly template: OccurrenceTemplate;
+}
+
+/**
+ * How far ahead occurrences are registered with the platform.
+ *
+ * Bounded by both a duration and a count because either alone fails: a duration
+ * alone lets a frequent series exhaust the platform ceiling, and a count alone
+ * leaves an annual series scheduled a decade out.
+ */
+export interface LookaheadConfig {
+	readonly days: number;
+	readonly occurrencesPerSeries: number;
+}
+
+export const DEFAULT_LOOKAHEAD: LookaheadConfig = {
+	days: 60,
+	occurrencesPerSeries: 32,
+};
+
+/** Bounds on consumer adjustment, because the platform ceiling is not negotiable. */
+export const LOOKAHEAD_BOUNDS = {
+	minDays: 1,
+	maxDays: 365,
+	minOccurrences: 1,
+	maxOccurrences: 64,
+} as const;
+
+export interface SeriesResult {
+	readonly seriesId: string;
+	/** Occurrences registered with the platform in this pass. */
+	readonly scheduled: number;
+	/** The horizon expansion reached, in epoch milliseconds. */
+	readonly expandedThrough: number;
+	/** True when the series has produced its final occurrence. */
+	readonly exhausted: boolean;
+	/**
+	 * Upcoming occurrences of this series removed because the expansion no longer
+	 * produces them — identifiers from before 0.4.0, or slots the rule dropped.
+	 * Added in 0.4.0.
+	 */
+	readonly cancelled?: readonly string[];
+}
+
+export interface SeriesSummary {
+	readonly seriesId: string;
+	readonly anchoring: AnchoringMode;
+	readonly expandedThrough: number;
+	readonly pendingOccurrences: number;
+	readonly exhausted: boolean;
+}

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,81 @@
-/**
- * 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 { createDiagnosticChannel } from '@chipmobilesdk/rn-core';
+
+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;
+}
+
+const channel = createDiagnosticChannel<DiagnosticCode>('rn-notification');
+
+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 {
+		const resolvedSeverity = severity ?? (isNonFailure(code) ? 'info' : 'error');
+		// The app's SDK sinks (`installSdkSink`, CORE-08) never get content, even
+		// with verbose diagnostics on: verbose is for this package's own sink.
+		channel.emit(code, resolvedSeverity, redactContext(context, false));
+
+		// 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: resolvedSeverity,
+			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');
+	}
+}