@chipmobilesdk/rn-notification 0.1.0

package/src/contract/reconcile.ts

@@ -0,0 +1,88 @@
+/**
+ * Reconciliation types.
+ *
+ * A caller hands over the complete set its data currently implies; the package
+ * computes the minimal operation set that makes the device match. Running it
+ * twice with unchanged input performs zero platform operations — that
+ * idempotence is the package's central testable promise.
+ */
+
+import type { NotificationRequest } from './notification';
+
+export interface ReconcileInput {
+	/**
+	 * Bounds what may be cancelled. Notifications outside this domain are never
+	 * touched, including those scheduled by other parts of the app or by other
+	 * libraries.
+	 */
+	readonly domain: string;
+	readonly desired: readonly NotificationRequest[];
+	/**
+	 * When false (the default), push-created notifications are left alone rather
+	 * than cancelled for being absent from a locally-computed desired set.
+	 */
+	readonly includePushCreated?: boolean;
+}
+
+/** Why a desired entry was refused rather than applied. */
+export interface RejectedEntry {
+	readonly id: string;
+	readonly code: string;
+	readonly reason: string;
+	/** How many times this identifier appeared in the desired set. */
+	readonly occurrences: number;
+	/**
+	 * True when a notification already scheduled under this identifier was left
+	 * in place. Stated explicitly so a rejection is never misread as a
+	 * cancellation.
+	 */
+	readonly existingLeftInPlace: boolean;
+}
+
+/** What was dropped for exceeding the platform's pending ceiling. */
+export interface TruncationReport {
+	readonly ceiling: number;
+	readonly droppedCount: number;
+	readonly droppedIds: readonly string[];
+	/**
+	 * Dropped entries are not lost — they are re-evaluated at each window
+	 * refresh as nearer entries deliver.
+	 */
+	readonly reEvaluatedOnNextRefresh: true;
+}
+
+export interface ReconcileResult {
+	readonly domain: string;
+	readonly created: readonly string[];
+	readonly replaced: readonly string[];
+	readonly cancelled: readonly string[];
+	readonly unchanged: readonly string[];
+	readonly rejected: readonly RejectedEntry[];
+	readonly truncated?: TruncationReport;
+	/** Total platform operations issued. Zero on a no-change pass. */
+	readonly operationCount: number;
+	readonly durationMs: number;
+}
+
+/** A discrepancy between what the package expects and what the platform holds. */
+export interface PendingDiscrepancy {
+	/** Expected from the series ledger or last reconciliation, but absent. */
+	readonly missing: readonly string[];
+	/** Present on the platform but not recognized by the package. */
+	readonly unrecognized: readonly string[];
+	readonly detectedAt: number;
+}
+
+/** Outcome of one automatic maintenance cycle. */
+export interface MaintenanceResult {
+	readonly ranAt: number;
+	readonly windowRefreshed: boolean;
+	readonly occurrencesScheduled: number;
+	readonly reAnchored: number;
+	readonly timeZoneChanged: boolean;
+	readonly permissionChanged: boolean;
+	/** Detected and reported only — never repaired. */
+	readonly discrepancy?: PendingDiscrepancy;
+	readonly operationCount: number;
+	readonly durationMs: number;
+}

package/src/contract/recurrence.ts

@@ -0,0 +1,123 @@
+/**
+ * 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;
+}
+
+export interface SeriesSummary {
+	readonly seriesId: string;
+	readonly anchoring: AnchoringMode;
+	readonly expandedThrough: number;
+	readonly pendingOccurrences: number;
+	readonly exhausted: boolean;
+}

package/src/diagnostics/burst.ts

@@ -0,0 +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>;

package/src/diagnostics/events.ts

@@ -0,0 +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');
+	}
+}

package/src/diagnostics/redact.ts

@@ -0,0 +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);
+}

package/src/diagnostics/snapshot.ts

@@ -0,0 +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>;

package/src/engine/adapter.ts

@@ -0,0 +1,79 @@
+/**
+ * The port every local notification engine satisfies.
+ *
+ * No engine type appears in any signature here. That is what makes the engine
+ * replaceable — and it has already been exercised once, when the archived
+ * Notifee was swapped for its maintained fork with no consumer impact.
+ */
+
+import type { PendingEntry, NotificationRequest } from '../contract/notification';
+import type { PermissionKind, PermissionState, RestrictionReport } from '../contract/permission';
+import type { ResolvedTone, ChannelGroup } from '../contract/channel';
+import type { InteractionEvent, Unsubscribe } from '../contract/interaction';
+
+/** A request whose anchoring has already been resolved to a firing instant. */
+export interface EngineScheduleRequest {
+	readonly request: NotificationRequest;
+	/** The absolute instant the platform should fire, after anchoring resolution. */
+	readonly resolvedAt: number;
+	/** Resolved platform channel and category for the request's tone. */
+	readonly tone: ResolvedTone;
+	/**
+	 * The IANA time zone this moment was anchored against.
+	 *
+	 * Carried explicitly because the adapter has to round-trip it through the
+	 * platform data bag — `getPending` must report it (FR-010) so a consumer can
+	 * detect the one case re-anchoring cannot fix (FR-007c). Absent for
+	 * absolute-instant moments, which are never anchored to a zone at all.
+	 */
+	readonly anchoringGeneration?: string;
+	/** True when exact-alarm capability is unavailable and approximate mode applies. */
+	readonly approximate: boolean;
+	readonly seriesId?: string;
+	readonly pushCreated?: boolean;
+}
+
+export interface EngineCapabilities {
+	/** iOS holds only the 64 soonest pending notifications and silently drops the rest. */
+	readonly pendingCeiling: number;
+	readonly supportsExactAlarms: boolean;
+	readonly supportsChannels: boolean;
+	readonly supportsTextInputActions: boolean;
+	readonly supportsDoNotDisturbBypass: boolean;
+	/** Milliseconds a background action or silent payload may run for. */
+	readonly backgroundWindowMs: number;
+}
+
+export interface NotificationEngineAdapter {
+	readonly name: string;
+
+	getCapabilities(): Promise<EngineCapabilities>;
+
+	/** Scheduling an existing identifier replaces it; exactly one entry results. */
+	schedule(request: EngineScheduleRequest): Promise<void>;
+
+	cancel(id: string): Promise<void>;
+	cancelMany(ids: readonly string[]): Promise<void>;
+	cancelAll(): Promise<void>;
+
+	/** Full detail, so callers can diff rather than merely count. */
+	getPending(): Promise<readonly PendingEntry[]>;
+
+	/** Applies a channel or category declaration. Returns true when the platform created it. */
+	declareTone(tone: ResolvedTone): Promise<boolean>;
+	/** Removes a retired channel. Returns true when one was actually removed. */
+	retireTone(channelId: string): Promise<boolean>;
+	declareGroups(groups: readonly ChannelGroup[]): Promise<void>;
+	/** Channel ids the platform currently holds, which re-declaration cannot reveal. */
+	listDeclaredChannels(): Promise<readonly string[]>;
+
+	getPermission(kind: PermissionKind): Promise<PermissionState>;
+	requestPermission(kind: PermissionKind): Promise<PermissionState>;
+	openSettings(kind: PermissionKind): Promise<void>;
+	getRestrictions(): Promise<RestrictionReport>;
+
+	/** Interactions arriving before a handler registers are the caller's problem to buffer, not the engine's. */
+	subscribeToInteractions(handler: (event: InteractionEvent) => void): Unsubscribe;
+	/** Any interaction that launched the app, consumed exactly once. */
+	takeInitialInteraction(): Promise<InteractionEvent | undefined>;
+}