@chipmobilesdk/rn-notification 0.3.0 → 0.4.1

package/src/contract/channel.ts

@@ -1,188 +1,192 @@
-/**
- * Channel, category, and tone declaration types.
- *
- * A tone is declared once and mapped by the package to each platform's
- * equivalent concepts, so consumer code contains no platform branches.
- *
- * Two tones must never be merged into one: channel configuration belongs to
- * the user, and collapsing two tones collapses two independent user choices.
- */
-
-/** How insistently a notification asks for attention. */
-export type ToneUrgency = 'min' | 'low' | 'default' | 'high' | 'max';
-
-export interface ToneSound {
-	/** Consumer-supplied resource name, resolved by the platform. */
-	readonly name?: string;
-	/** When false, the tone is silent. Defaults to true. */
-	readonly enabled?: boolean;
-}
-
-/**
- * A repeating alert and the bound on how long it may repeat.
- *
- * The two are one object rather than two fields because an unbounded repeating
- * alert must be *unrepresentable*, not merely discouraged. A boolean `repeat`
- * beside an optional duration would make the dangerous state the easiest one to
- * write, and the dangerous state here is a phone that keeps sounding until its
- * owner comes home to it.
- */
-export interface ToneRepeatAlert {
-	/**
-	 * How long the alert may keep repeating, measured from delivery.
-	 *
-	 * Required. Bounded by REPEAT_ALERT_BOUNDS, which is enforced at declaration
-	 * time — a type can forbid an absent duration but not a zero one.
-	 */
-	readonly forMs: number;
-}
-
-/**
- * The declarable range for a repeating alert.
- *
- * The floor exists because a repeat shorter than a minute is indistinguishable
- * from a single chime and buys nothing for the complexity it costs. The ceiling
- * exists because an hour is already past the point where a person who has not
- * responded is going to.
- */
-export const REPEAT_ALERT_BOUNDS = {
-	minMs: 60_000,
-	maxMs: 3_600_000,
-} as const;
-
-export interface ToneDeclaration {
-	/** Stable tone identifier, subject to the same charset rules as a notification id. */
-	readonly id: string;
-	/** Human-readable name shown in system settings. */
-	readonly name: string;
-	readonly description?: string;
-	readonly urgency: ToneUrgency;
-	readonly sound?: ToneSound;
-	readonly vibration?: boolean;
-	readonly badge?: boolean;
-	/** Optional grouping in system settings. */
-	readonly groupId?: string;
-	/**
-	 * Request the platform's Do Not Disturb bypass. Honoured where the platform
-	 * permits it and reported honestly where it does not. This is *not* an
-	 * override of the device's silent mode, which is out of scope.
-	 */
-	readonly bypassDoNotDisturb?: boolean;
-	/**
-	 * Present when the alert sound should repeat until the user handles the
-	 * notification, rather than sounding once.
-	 *
-	 * Realized per notification rather than as channel configuration, so adding
-	 * or changing it never obliges a consumer to bump `version`. Honoured where
-	 * the platform permits it and reported through `repeatUnavailable` where it
-	 * does not.
-	 */
-	readonly repeatAlert?: ToneRepeatAlert;
-	/**
-	 * Ask the platform to treat notifications on this tone as time-sensitive
-	 * alerts. Like `repeatAlert`, realized per notification, so it needs no
-	 * version bump.
-	 */
-	readonly timeSensitive?: boolean;
-	/**
-	 * Incremented by the consumer when a field the platform freezes changes:
-	 * `urgency`, `sound`, `vibration`, `badge`, `groupId`, or
-	 * `bypassDoNotDisturb`.
-	 *
-	 * Android freezes those once a channel exists, so changing one is a
-	 * migration rather than an assignment, and this version is what makes the
-	 * migration detectable.
-	 *
-	 * `name`, `description`, `repeatAlert`, and `timeSensitive` are deliberately
-	 * *not* on that list. Android updates a channel's labels in place, and the
-	 * two alert attributes are realized per notification — so none of them needs
-	 * a bump. This matters: a bump means a new channel, and a new channel means
-	 * the user loses every setting they adjusted. Nobody should have to pay that
-	 * to correct a typo.
-	 */
-	readonly version: number;
-}
-
-export interface ChannelGroup {
-	readonly id: string;
-	readonly name: string;
-	readonly description?: string;
-}
-
-/** What a tone resolves to on each platform. Internal to the engine adapter. */
-export interface ResolvedTone {
-	readonly toneId: string;
-	readonly version: number;
-	readonly android: {
-		/** Platform channel id, derived from tone id and version so a change creates a new channel. */
-		readonly channelId: string;
-		/**
-		 * The channel's user-visible name.
-		 *
-		 * Required rather than optional on purpose. Its absence is what let the
-		 * adapter fall back to the tone id, so users read a technical identifier
-		 * on the one screen these strings exist to serve. A type that permits no
-		 * name permits that bug back.
-		 */
-		readonly name: string;
-		/** The channel's user-visible description. */
-		readonly description?: string;
-		readonly importance: 'none' | 'min' | 'low' | 'default' | 'high';
-		readonly sound?: string;
-		readonly vibration: boolean;
-		readonly badge: boolean;
-		readonly bypassDnd: boolean;
-		readonly groupId?: string;
-		/** Repeat the alert sound until handled. Per notification, not channel configuration. */
-		readonly loopSound: boolean;
-		/** Mark the notification as an alarm-category alert. Per notification. */
-		readonly alarmCategory: boolean;
-		/** How long repetition may continue, so the adapter knows when to place the stop marker. */
-		readonly repeatForMs?: number;
-	};
-	readonly ios: {
-		readonly categoryId: string;
-		readonly interruptionLevel: 'passive' | 'active' | 'timeSensitive' | 'critical';
-		readonly sound?: string;
-		readonly badge: boolean;
-		/**
-		 * True when a repeating alert was declared and iOS will not honour it.
-		 *
-		 * iOS has no looping-sound API, and the one level that overrides the mute
-		 * switch is entitlement-gated and does not loop either. Recording the
-		 * refusal as data rather than as a comment is what lets `apply()` report
-		 * it instead of dropping it silently.
-		 */
-		readonly repeatRefused: boolean;
-	};
-}
-
-/**
- * Outcome of applying a channel configuration, including any migration performed.
- *
- * A tone appears in exactly one of `created`, `migrated`, `labelsRefreshed`, and
- * `unchanged`. The `*Unavailable` arrays are orthogonal and may accompany any of
- * them: a platform refusing an attribute says nothing about whether the tone was
- * newly created.
- */
-export interface ChannelApplyResult {
-	readonly created: readonly string[];
-	readonly migrated: readonly { readonly toneId: string; readonly from: number; readonly to: number }[];
-	/**
-	 * Tones whose name or description was updated in place on a channel that
-	 * already existed. No channel was recreated and no user setting was reset —
-	 * the platform itself refuses to overwrite the rest of the configuration,
-	 * which is what makes a label correction free.
-	 */
-	readonly labelsRefreshed: readonly string[];
-	readonly retired: readonly string[];
-	/** Notifications moved to the new channel during migration. */
-	readonly reHomed: readonly string[];
-	/** Notifications cancelled because they could not be re-homed. */
-	readonly cancelled: readonly string[];
-	/** Tones whose requested DND bypass the platform refused. */
-	readonly bypassUnavailable: readonly string[];
-	/** Tones whose requested repeating alert the platform refused. */
-	readonly repeatUnavailable: readonly string[];
-	readonly unchanged: readonly string[];
-}
+/**
+ * Channel, category, and tone declaration types.
+ *
+ * A tone is declared once and mapped by the package to each platform's
+ * equivalent concepts, so consumer code contains no platform branches.
+ *
+ * Two tones must never be merged into one: channel configuration belongs to
+ * the user, and collapsing two tones collapses two independent user choices.
+ */
+
+/** How insistently a notification asks for attention. */
+export type ToneUrgency = 'min' | 'low' | 'default' | 'high' | 'max';
+
+export interface ToneSound {
+	/** Consumer-supplied resource name, resolved by the platform. */
+	readonly name?: string;
+	/** When false, the tone is silent. Defaults to true. */
+	readonly enabled?: boolean;
+}
+
+/**
+ * A repeating alert and the bound on how long it may repeat.
+ *
+ * The two are one object rather than two fields because an unbounded repeating
+ * alert must be *unrepresentable*, not merely discouraged. A boolean `repeat`
+ * beside an optional duration would make the dangerous state the easiest one to
+ * write, and the dangerous state here is a phone that keeps sounding until its
+ * owner comes home to it.
+ */
+export interface ToneRepeatAlert {
+	/**
+	 * How long the alert may keep repeating, measured from delivery.
+	 *
+	 * Required. Bounded by REPEAT_ALERT_BOUNDS, which is enforced at declaration
+	 * time — a type can forbid an absent duration but not a zero one.
+	 */
+	readonly forMs: number;
+}
+
+/**
+ * The declarable range for a repeating alert.
+ *
+ * The floor exists because a repeat shorter than a minute is indistinguishable
+ * from a single chime and buys nothing for the complexity it costs. The ceiling
+ * exists because an hour is already past the point where a person who has not
+ * responded is going to.
+ */
+export const REPEAT_ALERT_BOUNDS = {
+	minMs: 60_000,
+	maxMs: 3_600_000,
+} as const;
+
+export interface ToneDeclaration {
+	/** Stable tone identifier, subject to the same charset rules as a notification id. */
+	readonly id: string;
+	/** Human-readable name shown in system settings. */
+	readonly name: string;
+	readonly description?: string;
+	readonly urgency: ToneUrgency;
+	readonly sound?: ToneSound;
+	readonly vibration?: boolean;
+	readonly badge?: boolean;
+	/** Optional grouping in system settings. */
+	readonly groupId?: string;
+	/**
+	 * Request the platform's Do Not Disturb bypass. Honoured where the platform
+	 * permits it and reported honestly where it does not. This is *not* an
+	 * override of the device's silent mode, which is out of scope.
+	 */
+	readonly bypassDoNotDisturb?: boolean;
+	/**
+	 * Present when the alert sound should repeat until the user handles the
+	 * notification, rather than sounding once.
+	 *
+	 * Realized per notification rather than as channel configuration, so adding
+	 * or changing it never obliges a consumer to bump `version`. Honoured where
+	 * the platform permits it and reported through `repeatUnavailable` where it
+	 * does not.
+	 */
+	readonly repeatAlert?: ToneRepeatAlert;
+	/**
+	 * Ask the platform to treat notifications on this tone as time-sensitive
+	 * alerts. Like `repeatAlert`, realized per notification, so it needs no
+	 * version bump.
+	 */
+	readonly timeSensitive?: boolean;
+	/**
+	 * Incremented by the consumer when a field the platform freezes changes:
+	 * `urgency`, `sound`, `vibration`, `badge`, `groupId`, or
+	 * `bypassDoNotDisturb`.
+	 *
+	 * Android freezes those once a channel exists, so changing one is a
+	 * migration rather than an assignment, and this version is what makes the
+	 * migration detectable.
+	 *
+	 * `name`, `description`, `repeatAlert`, and `timeSensitive` are deliberately
+	 * *not* on that list. Android updates a channel's labels in place, and the
+	 * two alert attributes are realized per notification — so none of them needs
+	 * a bump. This matters: a bump means a new channel, and a new channel means
+	 * the user loses every setting they adjusted. Nobody should have to pay that
+	 * to correct a typo.
+	 */
+	readonly version: number;
+}
+
+export interface ChannelGroup {
+	readonly id: string;
+	readonly name: string;
+	readonly description?: string;
+}
+
+/** What a tone resolves to on each platform. Internal to the engine adapter. */
+export interface ResolvedTone {
+	readonly toneId: string;
+	readonly version: number;
+	readonly android: {
+		/** Platform channel id, derived from tone id and version so a change creates a new channel. */
+		readonly channelId: string;
+		/**
+		 * The channel's user-visible name.
+		 *
+		 * Required rather than optional on purpose. Its absence is what let the
+		 * adapter fall back to the tone id, so users read a technical identifier
+		 * on the one screen these strings exist to serve. A type that permits no
+		 * name permits that bug back.
+		 */
+		readonly name: string;
+		/** The channel's user-visible description. */
+		readonly description?: string;
+		readonly importance: 'none' | 'min' | 'low' | 'default' | 'high';
+		readonly sound?: string;
+		readonly vibration: boolean;
+		readonly badge: boolean;
+		readonly bypassDnd: boolean;
+		readonly groupId?: string;
+		/** Repeat the alert sound until handled. Per notification, not channel configuration. */
+		readonly loopSound: boolean;
+		/** Mark the notification as an alarm-category alert. Per notification. */
+		readonly alarmCategory: boolean;
+		/** How long repetition may continue, so the adapter knows when to place the stop marker. */
+		readonly repeatForMs?: number;
+	};
+	readonly ios: {
+		readonly categoryId: string;
+		readonly interruptionLevel: 'passive' | 'active' | 'timeSensitive' | 'critical';
+		readonly sound?: string;
+		readonly badge: boolean;
+		/**
+		 * True when a repeating alert was declared and iOS will not honour it.
+		 *
+		 * iOS has no looping-sound API, and the one level that overrides the mute
+		 * switch is entitlement-gated and does not loop either. Recording the
+		 * refusal as data rather than as a comment is what lets `apply()` report
+		 * it instead of dropping it silently.
+		 */
+		readonly repeatRefused: boolean;
+	};
+}
+
+/**
+ * Outcome of applying a channel configuration, including any migration performed.
+ *
+ * A tone appears in exactly one of `created`, `migrated`, `labelsRefreshed`, and
+ * `unchanged`. The `*Unavailable` arrays are orthogonal and may accompany any of
+ * them: a platform refusing an attribute says nothing about whether the tone was
+ * newly created.
+ */
+export interface ChannelApplyResult {
+	readonly created: readonly string[];
+	readonly migrated: readonly {
+		readonly toneId: string;
+		readonly from: number;
+		readonly to: number;
+	}[];
+	/**
+	 * Tones whose name or description was updated in place on a channel that
+	 * already existed. No channel was recreated and no user setting was reset —
+	 * the platform itself refuses to overwrite the rest of the configuration,
+	 * which is what makes a label correction free.
+	 */
+	readonly labelsRefreshed: readonly string[];
+	readonly retired: readonly string[];
+	/** Notifications moved to the new channel during migration. */
+	readonly reHomed: readonly string[];
+	/** Notifications cancelled because they could not be re-homed. */
+	readonly cancelled: readonly string[];
+	/** Tones whose requested DND bypass the platform refused. */
+	readonly bypassUnavailable: readonly string[];
+	/** Tones whose requested repeating alert the platform refused. */
+	readonly repeatUnavailable: readonly string[];
+	readonly unchanged: readonly string[];
+}

package/src/contract/diagnostics.ts

@@ -1,102 +1,102 @@
-/**
- * Diagnostics and configuration types.
- *
- * The package's stated purpose is to make invisible notification failures
- * diagnosable, so every lifecycle transition emits a structured event with a
- * stable identifier — and none of those events carries content by default.
- */
-
-import type { PermissionReport, RestrictionReport } from './permission';
-import type { PendingDiscrepancy, MaintenanceResult, ReconcileResult } from './reconcile';
-import type { ToneDeclaration, ChannelGroup } from './channel';
-import type { LookaheadConfig } from './recurrence';
-import type { PendingEntry } from './notification';
-
-export type DiagnosticSeverity = 'debug' | 'info' | 'warn' | 'error';
-
-export interface DiagnosticEvent {
-	/** Stable identifier, safe to switch on. See contracts/errors.md. */
-	readonly code: string;
-	readonly severity: DiagnosticSeverity;
-	readonly message: string;
-	readonly at: number;
-	/**
-	 * Structured context. Never contains notification body text, routing payload
-	 * values, or push tokens unless verbose diagnostics is explicitly enabled.
-	 */
-	readonly context?: Readonly<Record<string, unknown>>;
-}
-
-export type EventSink = (event: DiagnosticEvent) => void;
-
-/** Health of one persisted collection against its cap. */
-export interface CollectionHealth {
-	readonly name: string;
-	readonly size: number;
-	readonly cap: number;
-	readonly oldestEntryAt?: number;
-}
-
-export interface StateHealth {
-	readonly readable: boolean;
-	/** True when the record was discarded and rebuilt, e.g. after corruption. */
-	readonly rebuilt: boolean;
-	readonly collections: readonly CollectionHealth[];
-	readonly approximateBytes: number;
-}
-
-/** The readable answer to "why didn't it arrive". */
-export interface StateSnapshot {
-	readonly permissions: PermissionReport;
-	readonly restrictions: RestrictionReport;
-	readonly tones: readonly { readonly id: string; readonly appliedVersion: number }[];
-	readonly pendingCount: number;
-	readonly pending: readonly PendingEntry[];
-	readonly lastReconcile?: ReconcileResult;
-	readonly lastMaintenance?: MaintenanceResult;
-	readonly discrepancy?: PendingDiscrepancy;
-	readonly stateHealth: StateHealth;
-	/** Presence only. The token value is never exposed here or anywhere else. */
-	readonly pushTokenPresent: boolean;
-	readonly capturedAt: number;
-}
-
-/** Abnormal notification volume. Reported, never acted upon. */
-export interface BurstThreshold {
-	readonly perMinute: number;
-	readonly perHour: number;
-}
-
-export const DEFAULT_BURST_THRESHOLD: BurstThreshold = {
-	perMinute: 10,
-	perHour: 60,
-};
-
-export interface NotificationConfig {
-	/** Every tone, category, and channel in one place. */
-	readonly tones: readonly ToneDeclaration[];
-	readonly channelGroups?: readonly ChannelGroup[];
-	readonly lookahead?: Partial<LookaheadConfig>;
-	/**
-	 * Automatic maintenance covers only what the package alone can know:
-	 * window refresh, expansion, re-anchoring, verification, permission re-read.
-	 * Full desired-set reconciliation is never automatic. Defaults to true.
-	 */
-	readonly automaticMaintenance?: boolean;
-	readonly burstThreshold?: BurstThreshold;
-	/** With no sink supplied the package emits nothing rather than writing to a console. */
-	readonly eventSink?: EventSink;
-	/**
-	 * Includes content values in diagnostics. Documented as unsuitable for
-	 * production, and off by default.
-	 */
-	readonly verboseDiagnostics?: boolean;
-}
-
-export interface InitializeResult {
-	readonly tonesApplied: number;
-	readonly migrationsRun: number;
-	readonly stateRebuilt: boolean;
-	readonly automaticMaintenance: boolean;
-	readonly durationMs: number;
-}
+/**
+ * Diagnostics and configuration types.
+ *
+ * The package's stated purpose is to make invisible notification failures
+ * diagnosable, so every lifecycle transition emits a structured event with a
+ * stable identifier — and none of those events carries content by default.
+ */
+
+import type { PermissionReport, RestrictionReport } from './permission';
+import type { PendingDiscrepancy, MaintenanceResult, ReconcileResult } from './reconcile';
+import type { ToneDeclaration, ChannelGroup } from './channel';
+import type { LookaheadConfig } from './recurrence';
+import type { PendingEntry } from './notification';
+
+export type DiagnosticSeverity = 'debug' | 'info' | 'warn' | 'error';
+
+export interface DiagnosticEvent {
+	/** Stable identifier, safe to switch on. See contracts/errors.md. */
+	readonly code: string;
+	readonly severity: DiagnosticSeverity;
+	readonly message: string;
+	readonly at: number;
+	/**
+	 * Structured context. Never contains notification body text, routing payload
+	 * values, or push tokens unless verbose diagnostics is explicitly enabled.
+	 */
+	readonly context?: Readonly<Record<string, unknown>>;
+}
+
+export type EventSink = (event: DiagnosticEvent) => void;
+
+/** Health of one persisted collection against its cap. */
+export interface CollectionHealth {
+	readonly name: string;
+	readonly size: number;
+	readonly cap: number;
+	readonly oldestEntryAt?: number;
+}
+
+export interface StateHealth {
+	readonly readable: boolean;
+	/** True when the record was discarded and rebuilt, e.g. after corruption. */
+	readonly rebuilt: boolean;
+	readonly collections: readonly CollectionHealth[];
+	readonly approximateBytes: number;
+}
+
+/** The readable answer to "why didn't it arrive". */
+export interface StateSnapshot {
+	readonly permissions: PermissionReport;
+	readonly restrictions: RestrictionReport;
+	readonly tones: readonly { readonly id: string; readonly appliedVersion: number }[];
+	readonly pendingCount: number;
+	readonly pending: readonly PendingEntry[];
+	readonly lastReconcile?: ReconcileResult;
+	readonly lastMaintenance?: MaintenanceResult;
+	readonly discrepancy?: PendingDiscrepancy;
+	readonly stateHealth: StateHealth;
+	/** Presence only. The token value is never exposed here or anywhere else. */
+	readonly pushTokenPresent: boolean;
+	readonly capturedAt: number;
+}
+
+/** Abnormal notification volume. Reported, never acted upon. */
+export interface BurstThreshold {
+	readonly perMinute: number;
+	readonly perHour: number;
+}
+
+export const DEFAULT_BURST_THRESHOLD: BurstThreshold = {
+	perMinute: 10,
+	perHour: 60,
+};
+
+export interface NotificationConfig {
+	/** Every tone, category, and channel in one place. */
+	readonly tones: readonly ToneDeclaration[];
+	readonly channelGroups?: readonly ChannelGroup[];
+	readonly lookahead?: Partial<LookaheadConfig>;
+	/**
+	 * Automatic maintenance covers only what the package alone can know:
+	 * window refresh, expansion, re-anchoring, verification, permission re-read.
+	 * Full desired-set reconciliation is never automatic. Defaults to true.
+	 */
+	readonly automaticMaintenance?: boolean;
+	readonly burstThreshold?: BurstThreshold;
+	/** With no sink supplied the package emits nothing rather than writing to a console. */
+	readonly eventSink?: EventSink;
+	/**
+	 * Includes content values in diagnostics. Documented as unsuitable for
+	 * production, and off by default.
+	 */
+	readonly verboseDiagnostics?: boolean;
+}
+
+export interface InitializeResult {
+	readonly tonesApplied: number;
+	readonly migrationsRun: number;
+	readonly stateRebuilt: boolean;
+	readonly automaticMaintenance: boolean;
+	readonly durationMs: number;
+}