@chipmobilesdk/rn-notification 0.1.2 → 0.2.1

package/src/engine/adapter.ts

@@ -1,79 +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;
-}
-
-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>;
-}
+/**
+ * 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;
+}