@chipmobilesdk/rn-notification 0.1.0

package/src/channel/tone-map.ts

@@ -0,0 +1,90 @@
+/**
+ * Tone-to-platform mapping.
+ *
+ * A tone is declared once and realized on each platform here, so consumer code
+ * contains zero platform branches. The two platforms model urgency differently
+ * — Android by channel importance, iOS by interruption level — and reconciling
+ * that difference is exactly the work this package exists to absorb.
+ *
+ * The channel id carries the tone version. Android channels are immutable once
+ * created and re-declaration is silently ignored, so a configuration change has
+ * to produce a *new* channel or it will never reach a device that already holds
+ * the old one.
+ */
+
+import type { ResolvedTone, ToneDeclaration, ToneUrgency } from '../contract/channel';
+
+type AndroidImportance = ResolvedTone['android']['importance'];
+type IosInterruption = ResolvedTone['ios']['interruptionLevel'];
+
+const ANDROID_IMPORTANCE: Record<ToneUrgency, AndroidImportance> = {
+	min: 'min',
+	low: 'low',
+	default: 'default',
+	high: 'high',
+	// Android has no level above `high`; max urgency is expressed by the DND
+	// bypass rather than by a distinct importance.
+	max: 'high',
+};
+
+const IOS_INTERRUPTION: Record<ToneUrgency, IosInterruption> = {
+	min: 'passive',
+	low: 'passive',
+	default: 'active',
+	high: 'active',
+	// `timeSensitive` is the highest level available without the Critical Alerts
+	// entitlement, which is out of scope for v1.
+	max: 'timeSensitive',
+};
+
+/** Channel id for a tone at a given version. Stable, derived, never random. */
+export function channelIdFor(toneId: string, version: number): string {
+	return `${toneId}.v${version}`;
+}
+
+/** Extracts the tone and version encoded in a channel id, if it is one of ours. */
+export function parseChannelId(
+	channelId: string,
+): { readonly toneId: string; readonly version: number } | undefined {
+	const separator = channelId.lastIndexOf('.v');
+	if (separator === -1) return undefined;
+
+	const version = Number.parseInt(channelId.slice(separator + 2), 10);
+	if (!Number.isInteger(version) || version < 1) return undefined;
+
+	return { toneId: channelId.slice(0, separator), version };
+}
+
+export function resolveTone(tone: ToneDeclaration): ResolvedTone {
+	const silent = tone.sound?.enabled === false;
+
+	return {
+		toneId: tone.id,
+		version: tone.version,
+		android: {
+			channelId: channelIdFor(tone.id, tone.version),
+			importance: ANDROID_IMPORTANCE[tone.urgency],
+			sound: silent ? undefined : tone.sound?.name,
+			vibration: tone.vibration ?? false,
+			badge: tone.badge ?? false,
+			bypassDnd: tone.bypassDoNotDisturb ?? false,
+			groupId: tone.groupId,
+		},
+		ios: {
+			// iOS categories are not versioned: they carry actions rather than
+			// user-adjustable settings, so re-declaring one is harmless.
+			categoryId: tone.id,
+			interruptionLevel: IOS_INTERRUPTION[tone.urgency],
+			sound: silent ? undefined : tone.sound?.name,
+			badge: tone.badge ?? false,
+		},
+	};
+}
+
+/** Builds a lookup over a declared configuration. */
+export function createToneResolver(
+	tones: readonly ToneDeclaration[],
+): (toneId: string) => ResolvedTone | undefined {
+	const resolved = new Map(tones.map(tone => [tone.id, resolveTone(tone)]));
+	return toneId => resolved.get(toneId);
+}

package/src/contract/channel.ts

@@ -0,0 +1,89 @@
+/**
+ * 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;
+}
+
+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;
+	/**
+	 * Incremented by the consumer when any field above changes.
+	 *
+	 * Android channels are immutable once created and re-declaration is silently
+	 * ignored, so a configuration change is a migration rather than an
+	 * assignment. This version is what makes the migration detectable.
+	 */
+	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;
+		readonly importance: 'none' | 'min' | 'low' | 'default' | 'high';
+		readonly sound?: string;
+		readonly vibration: boolean;
+		readonly badge: boolean;
+		readonly bypassDnd: boolean;
+		readonly groupId?: string;
+	};
+	readonly ios: {
+		readonly categoryId: string;
+		readonly interruptionLevel: 'passive' | 'active' | 'timeSensitive' | 'critical';
+		readonly sound?: string;
+		readonly badge: boolean;
+	};
+}
+
+/** Outcome of applying a channel configuration, including any migration performed. */
+export interface ChannelApplyResult {
+	readonly created: readonly string[];
+	readonly migrated: readonly { readonly toneId: string; readonly from: number; readonly to: number }[];
+	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[];
+	readonly unchanged: readonly string[];
+}

package/src/contract/diagnostics.ts

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

package/src/contract/errors.ts

@@ -0,0 +1,123 @@
+/**
+ * Typed error taxonomy and stable diagnostic identifiers.
+ *
+ * Every failure condition carries its own identifier. None collapses into a
+ * generic failure — an error that says only "scheduling failed" reproduces the
+ * problem this package exists to solve.
+ *
+ * Identifiers are stable across releases and safe to switch on. Adding new ones
+ * is an additive minor change.
+ *
+ * See `specs/009-rn-notification-package/contracts/errors.md`.
+ */
+
+export const DIAGNOSTIC_CODES = {
+	// --- Validation: raised before any platform call -------------------------
+	INVALID_ID_EMPTY: 'INVALID_ID_EMPTY',
+	INVALID_ID_LENGTH: 'INVALID_ID_LENGTH',
+	INVALID_ID_CHARSET: 'INVALID_ID_CHARSET',
+	INVALID_OWNER_TAG: 'INVALID_OWNER_TAG',
+	INVALID_GROUP_TAG: 'INVALID_GROUP_TAG',
+	MOMENT_IN_PAST: 'MOMENT_IN_PAST',
+	UNDECLARED_TONE: 'UNDECLARED_TONE',
+	ROUTING_PAYLOAD_TOO_LARGE: 'ROUTING_PAYLOAD_TOO_LARGE',
+	CONTENT_TOO_LARGE: 'CONTENT_TOO_LARGE',
+	TOO_MANY_ACTIONS: 'TOO_MANY_ACTIONS',
+	INVALID_RECURRENCE: 'INVALID_RECURRENCE',
+
+	// --- Reconciliation ------------------------------------------------------
+	DUPLICATE_IDENTIFIER: 'DUPLICATE_IDENTIFIER',
+	TRUNCATED_OVER_CEILING: 'TRUNCATED_OVER_CEILING',
+	RECONCILE_INTERRUPTED: 'RECONCILE_INTERRUPTED',
+	PENDING_SET_DISCREPANCY: 'PENDING_SET_DISCREPANCY',
+
+	// --- Permissions ---------------------------------------------------------
+	DISPLAY_PERMISSION_DENIED: 'DISPLAY_PERMISSION_DENIED',
+	DISPLAY_PERMISSION_PERMANENT: 'DISPLAY_PERMISSION_PERMANENT',
+	EXACT_ALARM_UNAVAILABLE: 'EXACT_ALARM_UNAVAILABLE',
+	SETTINGS_UNAVAILABLE: 'SETTINGS_UNAVAILABLE',
+	BACKGROUND_RESTRICTED: 'BACKGROUND_RESTRICTED',
+	BACKGROUND_RESTRICTION_UNKNOWN: 'BACKGROUND_RESTRICTION_UNKNOWN',
+
+	// --- Channels ------------------------------------------------------------
+	CHANNEL_MIGRATION_REQUIRED: 'CHANNEL_MIGRATION_REQUIRED',
+	CHANNEL_MIGRATION_FAILED: 'CHANNEL_MIGRATION_FAILED',
+	CHANNEL_ORPHANS_FOUND: 'CHANNEL_ORPHANS_FOUND',
+	DND_BYPASS_UNAVAILABLE: 'DND_BYPASS_UNAVAILABLE',
+
+	// --- Interaction ---------------------------------------------------------
+	TARGET_MISSING: 'TARGET_MISSING',
+	INTERACTION_BUFFER_EVICTED: 'INTERACTION_BUFFER_EVICTED',
+	BACKGROUND_WINDOW_EXCEEDED: 'BACKGROUND_WINDOW_EXCEEDED',
+
+	// --- Push ----------------------------------------------------------------
+	PUSH_UNAVAILABLE: 'PUSH_UNAVAILABLE',
+	TOKEN_UNAVAILABLE: 'TOKEN_UNAVAILABLE',
+	TOKEN_INVALIDATION_FAILED: 'TOKEN_INVALIDATION_FAILED',
+	PAYLOAD_MALFORMED: 'PAYLOAD_MALFORMED',
+	PAYLOAD_VERSION_SKEW: 'PAYLOAD_VERSION_SKEW',
+	PAYLOAD_DUPLICATE: 'PAYLOAD_DUPLICATE',
+	PUSH_UNDELIVERABLE: 'PUSH_UNDELIVERABLE',
+
+	// --- Persisted state -----------------------------------------------------
+	STATE_CORRUPT_REBUILT: 'STATE_CORRUPT_REBUILT',
+	STATE_WRITE_FAILED: 'STATE_WRITE_FAILED',
+	STATE_CAP_EVICTED: 'STATE_CAP_EVICTED',
+
+	// --- Volume --------------------------------------------------------------
+	BURST_THRESHOLD_EXCEEDED: 'BURST_THRESHOLD_EXCEEDED',
+} as const;
+
+export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
+
+/** Every identifier, for exhaustiveness tests and the documentation table. */
+export const ALL_DIAGNOSTIC_CODES: readonly DiagnosticCode[] = Object.freeze(
+	Object.values(DIAGNOSTIC_CODES),
+);
+
+/**
+ * A typed package failure.
+ *
+ * Carries enough context to choose a recovery, and never carries notification
+ * body text, routing payload values, or token material. Where a value violated
+ * a rule, the *shape* of the violation is reported — a length, a character
+ * position — rather than the value itself.
+ */
+export class NotificationError extends Error {
+	readonly code: DiagnosticCode;
+	readonly context?: Readonly<Record<string, unknown>>;
+
+	constructor(code: DiagnosticCode, message: string, context?: Readonly<Record<string, unknown>>) {
+		super(message);
+		this.name = 'NotificationError';
+		this.code = code;
+		this.context = context;
+		Object.setPrototypeOf(this, NotificationError.prototype);
+	}
+}
+
+export function isNotificationError(value: unknown): value is NotificationError {
+	return value instanceof NotificationError;
+}
+
+/**
+ * Conditions that are reported outcomes rather than failures: the operation
+ * succeeded, and something the caller needs to know happened alongside it.
+ */
+export const NON_FAILURE_CODES: readonly DiagnosticCode[] = Object.freeze([
+	DIAGNOSTIC_CODES.TRUNCATED_OVER_CEILING,
+	DIAGNOSTIC_CODES.PENDING_SET_DISCREPANCY,
+	DIAGNOSTIC_CODES.EXACT_ALARM_UNAVAILABLE,
+	DIAGNOSTIC_CODES.TARGET_MISSING,
+	DIAGNOSTIC_CODES.BURST_THRESHOLD_EXCEEDED,
+	DIAGNOSTIC_CODES.PAYLOAD_VERSION_SKEW,
+	DIAGNOSTIC_CODES.PAYLOAD_DUPLICATE,
+	DIAGNOSTIC_CODES.STATE_CAP_EVICTED,
+	DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT,
+	DIAGNOSTIC_CODES.BACKGROUND_RESTRICTION_UNKNOWN,
+	DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,
+]);
+
+export function isNonFailure(code: DiagnosticCode): boolean {
+	return NON_FAILURE_CODES.includes(code);
+}

package/src/contract/index.ts

@@ -0,0 +1,10 @@
+/** Public contract types. Types only — no logic lives in this layer. */
+
+export * from './notification';
+export * from './recurrence';
+export * from './reconcile';
+export * from './permission';
+export * from './channel';
+export * from './interaction';
+export * from './diagnostics';
+export * from './errors';

package/src/contract/interaction.ts

@@ -0,0 +1,62 @@
+/**
+ * Interaction types.
+ *
+ * One event shape covers foreground, background, and cold start, so a consumer
+ * writes one handler. Events that occur before a handler registers are buffered
+ * durably and delivered on registration — the cold-start case is the one most
+ * integrations quietly get wrong.
+ */
+
+import type { RoutingPayload } from './notification';
+
+export type InteractionKind = 'tap' | 'action' | 'dismiss';
+
+/** Which app state the interaction arrived in. Informational; the shape never varies. */
+export type AppStateAtInteraction = 'foreground' | 'background' | 'coldStart';
+
+export interface InteractionEvent {
+	readonly kind: InteractionKind;
+	readonly notificationId: string;
+	/** Present when `kind` is `action`. */
+	readonly actionId?: string;
+	/** Present when the action accepted typed input. */
+	readonly inputText?: string;
+	/** Round-trips unchanged from schedule time. */
+	readonly routing?: RoutingPayload;
+	readonly ownerTag?: string;
+	readonly occurredAt: number;
+	readonly appState: AppStateAtInteraction;
+	/**
+	 * True when the event was held in the durable buffer before a handler
+	 * existed to receive it — including across a process death.
+	 */
+	readonly wasBuffered: boolean;
+}
+
+/**
+ * Signals the routing target no longer exists.
+ *
+ * The consumer chooses its own fallback screen. A platform error is never
+ * shown to the user for this — a notification pointing at deleted data is an
+ * ordinary condition, not a crash.
+ */
+export interface TargetMissingSignal {
+	readonly notificationId: string;
+	readonly routing?: RoutingPayload;
+}
+
+export type InteractionHandler = (event: InteractionEvent) => void | Promise<void>;
+
+export type Unsubscribe = () => void;
+
+/** Limits on the durable interaction buffer, so it can never grow without bound. */
+export const INTERACTION_BUFFER_LIMITS = {
+	maxEntries: 50,
+	retentionMs: 7 * 24 * 60 * 60 * 1000,
+} as const;
+
+/** Maximum size of a routing payload, validated at schedule time rather than discovered at tap time. */
+export const MAX_ROUTING_PAYLOAD_BYTES = 4 * 1024;
+
+/** Maximum action buttons on one notification. */
+export const MAX_ACTIONS_PER_NOTIFICATION = 10;

package/src/contract/notification.ts

@@ -0,0 +1,118 @@
+/**
+ * Core notification request types.
+ *
+ * Nothing here carries business meaning. The package accepts fully-described
+ * requests and is responsible only for delivering them at the right moment.
+ */
+
+/**
+ * How a delivery moment is pinned to the passage of time.
+ *
+ * - `wallClock` — the local clock time named. An 08:00 reminder stays 08:00
+ *   after the user crosses a time zone. This is the default, because reminders
+ *   are wall-clock things and a caller who does not choose should get what
+ *   their users expect.
+ * - `absolute` — one fixed instant worldwide, unaffected by zone changes.
+ */
+export type AnchoringMode = 'wallClock' | 'absolute';
+
+export const DEFAULT_ANCHORING_MODE: AnchoringMode = 'wallClock';
+
+/** When a notification should be presented, and how that moment is anchored. */
+export interface DeliveryMoment {
+	/** Epoch milliseconds. Interpreted per {@link DeliveryMoment.anchoring}. */
+	readonly at: number;
+	/** Defaults to `wallClock` when omitted. */
+	readonly anchoring?: AnchoringMode;
+}
+
+/**
+ * Resolved display strings. The package performs no translation, formatting,
+ * or locale resolution — only the consuming app knows its content model.
+ */
+export interface NotificationContent {
+	readonly title: string;
+	readonly body: string;
+	/** Optional short text shown in collapsed form on some platforms. */
+	readonly subtitle?: string;
+}
+
+/** Structured data carried to the interaction handler, unchanged. */
+export type RoutingPayload = Readonly<Record<string, unknown>>;
+
+/** A button on a notification. */
+export interface Action {
+	/** Stable action identifier, subject to the same charset rules as a notification id. */
+	readonly id: string;
+	readonly title: string;
+	/**
+	 * `foreground` brings the app up; `background` is handled without opening it,
+	 * inside the platform's bounded execution window.
+	 */
+	readonly mode: 'foreground' | 'background';
+	/** When present, the action accepts short typed input. */
+	readonly input?: {
+		readonly placeholder?: string;
+		readonly submitLabel?: string;
+	};
+}
+
+/** The complete, self-contained description of one notification. */
+export interface NotificationRequest {
+	/**
+	 * Caller-supplied, stable, derived from the caller's own data.
+	 * The package never generates, normalizes, or hashes it.
+	 */
+	readonly id: string;
+	readonly content: NotificationContent;
+	/** Must reference a tone declared in the package configuration. */
+	readonly tone: string;
+	readonly moment: DeliveryMoment;
+	readonly routing?: RoutingPayload;
+	readonly actions?: readonly Action[];
+	/** Opaque partition label. Never interpreted by the package. */
+	readonly ownerTag?: string;
+	/** Opaque cancellation group. Never interpreted by the package. */
+	readonly groupTag?: string;
+}
+
+/** One entry the platform is currently holding, in enough detail to diff against intent. */
+export interface PendingEntry {
+	readonly id: string;
+	/** The instant the platform will actually fire, after anchoring resolution. */
+	readonly resolvedAt: number;
+	readonly anchoring: AnchoringMode;
+	/**
+	 * The IANA zone this entry was last anchored against.
+	 * `undefined` for absolute-instant entries, which are never anchored.
+	 *
+	 * Exists so the one case re-anchoring cannot fix — a zone change while the
+	 * app never ran — is detectable rather than invisible.
+	 */
+	readonly anchoringGeneration?: string;
+	readonly content: NotificationContent;
+	readonly tone: string;
+	readonly routing?: RoutingPayload;
+	readonly actions?: readonly Action[];
+	readonly ownerTag?: string;
+	readonly groupTag?: string;
+	/** Present when this entry was expanded from a recurrence series. */
+	readonly seriesId?: string;
+	/** True when scheduled without exact-alarm capability; delivery may be late. */
+	readonly mayBeDelayed: boolean;
+	/** True when created by a push instruction rather than by app code. */
+	readonly pushCreated: boolean;
+}
+
+/** Outcome of a single schedule call. */
+export interface ScheduleResult {
+	readonly id: string;
+	readonly resolvedAt: number;
+	readonly anchoring: AnchoringMode;
+	/** True when an existing notification under this identifier was replaced. */
+	readonly replaced: boolean;
+	/** True when the moment had just passed and was delivered inside the tolerance window. */
+	readonly deliveredImmediately: boolean;
+	/** True when scheduled in approximate mode for want of exact-alarm capability. */
+	readonly mayBeDelayed: boolean;
+}

package/src/contract/permission.ts

@@ -0,0 +1,60 @@
+/**
+ * Permission types.
+ *
+ * Display permission and exact-alarm permission are different things serving
+ * different purposes, so they are requested and reported independently. State
+ * is always readable without triggering a dialog.
+ */
+
+export type PermissionKind = 'display' | 'exactAlarm';
+
+/**
+ * Six states, never collapsed into one another.
+ *
+ * - `notAsked` — distinguishable from `denied`, which is the whole point of
+ *   being able to read state without prompting.
+ * - `provisional` — iOS quiet delivery. Neither granted nor denied.
+ * - `notRequired` — the running platform version has no such concept. Never
+ *   reported as `denied`, which would imply a refusal that never happened.
+ */
+export type PermissionState =
+	| 'notAsked'
+	| 'granted'
+	| 'denied'
+	| 'permanentlyDenied'
+	| 'provisional'
+	| 'notRequired';
+
+export interface PermissionReport {
+	readonly display: PermissionState;
+	readonly exactAlarm: PermissionState;
+	readonly readAt: number;
+}
+
+/** Whether a manufacturer-level restriction is in force, where it can be known. */
+export type RestrictionStatus = 'unrestricted' | 'restricted' | 'unknown';
+
+/**
+ * Manufacturer background restrictions, reported for information only.
+ *
+ * `unknown` is a first-class answer: some vendors stop apps in ways with no
+ * standard detection API, and guessing would be worse than admitting it.
+ * The package never changes any of these settings on the user's behalf.
+ */
+export interface RestrictionReport {
+	readonly batteryOptimization: RestrictionStatus;
+	readonly autoStart: RestrictionStatus;
+	readonly manufacturer?: string;
+	readonly readAt: number;
+}
+
+/** Whether a permission request can even be presented on this platform version. */
+export interface PermissionCapability {
+	readonly kind: PermissionKind;
+	readonly supported: boolean;
+	/**
+	 * True when the platform grants this only through system settings rather
+	 * than an in-app dialog.
+	 */
+	readonly settingsOnly: boolean;
+}