@chipmobilesdk/rn-notification 0.4.0 → 0.4.1

package/src/engine/adapter.ts

@@ -1,172 +1,172 @@
-/**
- * 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;
-	/**
-	 * Marks this request as a package-owned stop marker rather than a consumer
-	 * notification.
-	 *
-	 * Carried here rather than smuggled through `ownerTag` or `routing` so it can
-	 * never collide with a value a consumer owns, and so the adapter can keep
-	 * markers out of `getPending` without inspecting consumer data.
-	 */
-	readonly repeatStop?: RepeatStop;
-}
-
-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;
-	/**
-	 * Whether a notification's alert sound can be made to repeat until handled.
-	 *
-	 * Decides two things: whether a refused repeat is reported to the caller, and
-	 * whether a stop marker is placed at all. Where this is false no marker is
-	 * created, so the platform's pending ceiling is untouched by the feature.
-	 */
-	readonly supportsRepeatingAlert: boolean;
-	/** Milliseconds a background action or silent payload may run for. */
-	readonly backgroundWindowMs: number;
-}
-
-/**
- * What applying a tone declaration actually did.
- *
- * A boolean cannot carry this: a caller has to tell a label correction from a
- * newly created channel from a no-op, and reporting a refresh as a creation
- * would make every apply look like a write.
- */
-export type ToneDeclarationOutcome = 'created' | 'labelsRefreshed' | 'unchanged';
-
-/**
- * A package-owned artifact scheduled to end a repeating alert.
- *
- * Never a consumer notification. It exists because no platform offers "stop the
- * sound at time T but keep the notification", so something has to run at T.
- */
-export interface RepeatStop {
-	readonly markerId: string;
-	/** The consumer notification whose alert this stops. */
-	readonly targetId: string;
-	readonly dueAt: number;
-}
-
-/** A notification arriving, as opposed to a user acting on one. */
-export interface DeliveryEvent {
-	readonly notificationId: string;
-	readonly occurredAt: number;
-	/** Present when this delivery is a package-owned stop marker rather than a real notification. */
-	readonly repeatStop?: RepeatStop;
-}
-
-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.
-	 *
-	 * Must return `labelsRefreshed` only when a label actually changed. Returning
-	 * it unconditionally would turn every apply into a write and quietly break
-	 * the zero-operation guarantee reconciliation idempotence rests on.
-	 */
-	declareTone(tone: ResolvedTone): Promise<ToneDeclarationOutcome>;
-	/** 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>;
-
-	/**
-	 * Stops a delivered notification's repeating alert without removing it.
-	 *
-	 * Re-posts the notification under the same identifier with the alert
-	 * suppressed. The same identifier means the same tray slot, so it replaces in
-	 * place: the sound stops and the notification stays. Cancelling instead would
-	 * be worse than never alerting at all — the user comes home to a silent phone
-	 * and no idea what they missed.
-	 *
-	 * Returns false when the notification is no longer displayed, which is the
-	 * ordinary case once the user has handled it.
-	 */
-	silenceDelivered(id: string): Promise<boolean>;
-
-	/** Package-owned stop markers currently scheduled. Never consumer notifications. */
-	listRepeatStops(): Promise<readonly RepeatStop[]>;
-
-	/**
-	 * Deliveries, as distinct from interactions.
-	 *
-	 * `subscribeToInteractions` deliberately discards delivery events, because
-	 * reporting an arrival as a tap would cancel a notification the user never
-	 * touched. Repeat expiry needs exactly the events that filter throws away, so
-	 * it gets its own subscription rather than loosening that one.
-	 */
-	subscribeToDeliveries(handler: (event: DeliveryEvent) => void): Unsubscribe;
-
-	/**
-	 * Registers the handler that runs when the app process is not alive.
-	 *
-	 * Must be called at module scope, outside the React tree, because that is
-	 * where the engine registers its headless task. The package cannot do this on
-	 * a consumer's behalf, which is why it is a documented setup step rather than
-	 * an internal detail — and why its absence is reported rather than guessed at.
-	 */
-	registerBackgroundDeliveryHandler(handler: (event: DeliveryEvent) => Promise<void>): void;
-
-	/** Whether a background delivery handler has been registered in this process. */
-	hasBackgroundDeliveryHandler(): boolean;
-}
+/**
+ * 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;
+	/**
+	 * Marks this request as a package-owned stop marker rather than a consumer
+	 * notification.
+	 *
+	 * Carried here rather than smuggled through `ownerTag` or `routing` so it can
+	 * never collide with a value a consumer owns, and so the adapter can keep
+	 * markers out of `getPending` without inspecting consumer data.
+	 */
+	readonly repeatStop?: RepeatStop;
+}
+
+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;
+	/**
+	 * Whether a notification's alert sound can be made to repeat until handled.
+	 *
+	 * Decides two things: whether a refused repeat is reported to the caller, and
+	 * whether a stop marker is placed at all. Where this is false no marker is
+	 * created, so the platform's pending ceiling is untouched by the feature.
+	 */
+	readonly supportsRepeatingAlert: boolean;
+	/** Milliseconds a background action or silent payload may run for. */
+	readonly backgroundWindowMs: number;
+}
+
+/**
+ * What applying a tone declaration actually did.
+ *
+ * A boolean cannot carry this: a caller has to tell a label correction from a
+ * newly created channel from a no-op, and reporting a refresh as a creation
+ * would make every apply look like a write.
+ */
+export type ToneDeclarationOutcome = 'created' | 'labelsRefreshed' | 'unchanged';
+
+/**
+ * A package-owned artifact scheduled to end a repeating alert.
+ *
+ * Never a consumer notification. It exists because no platform offers "stop the
+ * sound at time T but keep the notification", so something has to run at T.
+ */
+export interface RepeatStop {
+	readonly markerId: string;
+	/** The consumer notification whose alert this stops. */
+	readonly targetId: string;
+	readonly dueAt: number;
+}
+
+/** A notification arriving, as opposed to a user acting on one. */
+export interface DeliveryEvent {
+	readonly notificationId: string;
+	readonly occurredAt: number;
+	/** Present when this delivery is a package-owned stop marker rather than a real notification. */
+	readonly repeatStop?: RepeatStop;
+}
+
+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.
+	 *
+	 * Must return `labelsRefreshed` only when a label actually changed. Returning
+	 * it unconditionally would turn every apply into a write and quietly break
+	 * the zero-operation guarantee reconciliation idempotence rests on.
+	 */
+	declareTone(tone: ResolvedTone): Promise<ToneDeclarationOutcome>;
+	/** 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>;
+
+	/**
+	 * Stops a delivered notification's repeating alert without removing it.
+	 *
+	 * Re-posts the notification under the same identifier with the alert
+	 * suppressed. The same identifier means the same tray slot, so it replaces in
+	 * place: the sound stops and the notification stays. Cancelling instead would
+	 * be worse than never alerting at all — the user comes home to a silent phone
+	 * and no idea what they missed.
+	 *
+	 * Returns false when the notification is no longer displayed, which is the
+	 * ordinary case once the user has handled it.
+	 */
+	silenceDelivered(id: string): Promise<boolean>;
+
+	/** Package-owned stop markers currently scheduled. Never consumer notifications. */
+	listRepeatStops(): Promise<readonly RepeatStop[]>;
+
+	/**
+	 * Deliveries, as distinct from interactions.
+	 *
+	 * `subscribeToInteractions` deliberately discards delivery events, because
+	 * reporting an arrival as a tap would cancel a notification the user never
+	 * touched. Repeat expiry needs exactly the events that filter throws away, so
+	 * it gets its own subscription rather than loosening that one.
+	 */
+	subscribeToDeliveries(handler: (event: DeliveryEvent) => void): Unsubscribe;
+
+	/**
+	 * Registers the handler that runs when the app process is not alive.
+	 *
+	 * Must be called at module scope, outside the React tree, because that is
+	 * where the engine registers its headless task. The package cannot do this on
+	 * a consumer's behalf, which is why it is a documented setup step rather than
+	 * an internal detail — and why its absence is reported rather than guessed at.
+	 */
+	registerBackgroundDeliveryHandler(handler: (event: DeliveryEvent) => Promise<void>): void;
+
+	/** Whether a background delivery handler has been registered in this process. */
+	hasBackgroundDeliveryHandler(): boolean;
+}

package/src/engine/codec.ts

@@ -1,89 +1,89 @@
-/**
- * The metadata codec for a notification's platform data bag.
- *
- * Anchoring, series origin, tags, routing and actions have no engine
- * equivalent, and `getPending` must return them (FR-010) or a consumer cannot
- * diff against intent. They travel as strings in the free-form data bag, which
- * is the one field both platforms carry through unchanged.
- *
- * Shared by the real engine and the fake. When the fake stored requests
- * verbatim it could not lose a field the real engine lost — `actions` never
- * came back from a device, so every reconcile replaced every notification that
- * had them, and the fake-backed tests never saw it.
- */
-
-import type { EngineScheduleRequest } from './adapter';
-import type { Action, AnchoringMode, PendingEntry, RoutingPayload } from '../contract/notification';
-
-/** Everything `getPending` reports that only the data bag can carry. */
-export type PackedMetadata = Pick<
-	PendingEntry,
-	| 'anchoring'
-	| 'anchoringGeneration'
-	| 'tone'
-	| 'routing'
-	| 'actions'
-	| 'ownerTag'
-	| 'groupTag'
-	| 'seriesId'
-	| 'mayBeDelayed'
-	| 'pushCreated'
->;
-
-export function packData(request: EngineScheduleRequest): Record<string, string> {
-	return {
-		__cms_anchoring: request.request.moment.anchoring ?? 'wallClock',
-		// The IANA zone, not the tone. Storing the wrong value here does not merely
-		// mislabel an entry: the re-anchoring pass feeds it straight to
-		// Intl.DateTimeFormat, which throws a hard Hermes error on an invalid zone.
-		...(request.anchoringGeneration !== undefined
-			? { __cms_generation: request.anchoringGeneration }
-			: {}),
-		__cms_tone: request.request.tone,
-		__cms_approximate: String(request.approximate),
-		__cms_pushCreated: String(request.pushCreated ?? false),
-		...(request.seriesId !== undefined ? { __cms_series: request.seriesId } : {}),
-		...(request.request.ownerTag !== undefined ? { __cms_owner: request.request.ownerTag } : {}),
-		...(request.request.groupTag !== undefined ? { __cms_group: request.request.groupTag } : {}),
-		...(request.request.routing !== undefined
-			? { __cms_routing: JSON.stringify(request.request.routing) }
-			: {}),
-		...(request.request.actions !== undefined
-			? { __cms_actions: JSON.stringify(request.request.actions) }
-			: {}),
-		// A stop marker's whole payload. It travels here rather than in `ownerTag`
-		// or `routing` so it can never collide with a value a consumer owns.
-		...(request.repeatStop !== undefined
-			? {
-					__cms_stop_target: request.repeatStop.targetId,
-					__cms_stop_due: String(request.repeatStop.dueAt),
-				}
-			: {}),
-	};
-}
-
-/** A JSON field we cannot parse is reported as absent: the notification is still valid. */
-function parseJson<T>(raw: string | undefined): T | undefined {
-	if (typeof raw !== 'string') return undefined;
-	try {
-		return JSON.parse(raw) as T;
-	} catch {
-		return undefined;
-	}
-}
-
-export function unpackData(data: Record<string, string>): PackedMetadata {
-	const anchoring: AnchoringMode = data.__cms_anchoring === 'absolute' ? 'absolute' : 'wallClock';
-	return {
-		anchoring,
-		anchoringGeneration: anchoring === 'absolute' ? undefined : data.__cms_generation,
-		tone: data.__cms_tone ?? '',
-		routing: parseJson<RoutingPayload>(data.__cms_routing),
-		actions: parseJson<readonly Action[]>(data.__cms_actions),
-		ownerTag: data.__cms_owner,
-		groupTag: data.__cms_group,
-		seriesId: data.__cms_series,
-		mayBeDelayed: data.__cms_approximate === 'true',
-		pushCreated: data.__cms_pushCreated === 'true',
-	};
-}
+/**
+ * The metadata codec for a notification's platform data bag.
+ *
+ * Anchoring, series origin, tags, routing and actions have no engine
+ * equivalent, and `getPending` must return them (FR-010) or a consumer cannot
+ * diff against intent. They travel as strings in the free-form data bag, which
+ * is the one field both platforms carry through unchanged.
+ *
+ * Shared by the real engine and the fake. When the fake stored requests
+ * verbatim it could not lose a field the real engine lost — `actions` never
+ * came back from a device, so every reconcile replaced every notification that
+ * had them, and the fake-backed tests never saw it.
+ */
+
+import type { EngineScheduleRequest } from './adapter';
+import type { Action, AnchoringMode, PendingEntry, RoutingPayload } from '../contract/notification';
+
+/** Everything `getPending` reports that only the data bag can carry. */
+export type PackedMetadata = Pick<
+	PendingEntry,
+	| 'anchoring'
+	| 'anchoringGeneration'
+	| 'tone'
+	| 'routing'
+	| 'actions'
+	| 'ownerTag'
+	| 'groupTag'
+	| 'seriesId'
+	| 'mayBeDelayed'
+	| 'pushCreated'
+>;
+
+export function packData(request: EngineScheduleRequest): Record<string, string> {
+	return {
+		__cms_anchoring: request.request.moment.anchoring ?? 'wallClock',
+		// The IANA zone, not the tone. Storing the wrong value here does not merely
+		// mislabel an entry: the re-anchoring pass feeds it straight to
+		// Intl.DateTimeFormat, which throws a hard Hermes error on an invalid zone.
+		...(request.anchoringGeneration !== undefined
+			? { __cms_generation: request.anchoringGeneration }
+			: {}),
+		__cms_tone: request.request.tone,
+		__cms_approximate: String(request.approximate),
+		__cms_pushCreated: String(request.pushCreated ?? false),
+		...(request.seriesId !== undefined ? { __cms_series: request.seriesId } : {}),
+		...(request.request.ownerTag !== undefined ? { __cms_owner: request.request.ownerTag } : {}),
+		...(request.request.groupTag !== undefined ? { __cms_group: request.request.groupTag } : {}),
+		...(request.request.routing !== undefined
+			? { __cms_routing: JSON.stringify(request.request.routing) }
+			: {}),
+		...(request.request.actions !== undefined
+			? { __cms_actions: JSON.stringify(request.request.actions) }
+			: {}),
+		// A stop marker's whole payload. It travels here rather than in `ownerTag`
+		// or `routing` so it can never collide with a value a consumer owns.
+		...(request.repeatStop !== undefined
+			? {
+					__cms_stop_target: request.repeatStop.targetId,
+					__cms_stop_due: String(request.repeatStop.dueAt),
+				}
+			: {}),
+	};
+}
+
+/** A JSON field we cannot parse is reported as absent: the notification is still valid. */
+function parseJson<T>(raw: string | undefined): T | undefined {
+	if (typeof raw !== 'string') return undefined;
+	try {
+		return JSON.parse(raw) as T;
+	} catch {
+		return undefined;
+	}
+}
+
+export function unpackData(data: Record<string, string>): PackedMetadata {
+	const anchoring: AnchoringMode = data.__cms_anchoring === 'absolute' ? 'absolute' : 'wallClock';
+	return {
+		anchoring,
+		anchoringGeneration: anchoring === 'absolute' ? undefined : data.__cms_generation,
+		tone: data.__cms_tone ?? '',
+		routing: parseJson<RoutingPayload>(data.__cms_routing),
+		actions: parseJson<readonly Action[]>(data.__cms_actions),
+		ownerTag: data.__cms_owner,
+		groupTag: data.__cms_group,
+		seriesId: data.__cms_series,
+		mayBeDelayed: data.__cms_approximate === 'true',
+		pushCreated: data.__cms_pushCreated === 'true',
+	};
+}