@chipmobilesdk/rn-notification 0.1.2 → 0.2.0

package/src/contract/errors.ts

@@ -1,123 +1,130 @@
-/**
- * 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);
-}
+/**
+ * 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',
+	INVALID_TONE_REPEAT: 'INVALID_TONE_REPEAT',
+
+	// --- 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',
+	TONE_LABELS_REFRESHED: 'TONE_LABELS_REFRESHED',
+	REPEAT_ALERT_UNAVAILABLE: 'REPEAT_ALERT_UNAVAILABLE',
+	REPEAT_STOP_HANDLER_MISSING: 'REPEAT_STOP_HANDLER_MISSING',
+
+	// --- 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,
+	DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED,
+	DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE,
+	DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING,
+]);
+
+export function isNonFailure(code: DiagnosticCode): boolean {
+	return NON_FAILURE_CODES.includes(code);
+}

package/src/contract/index.ts

@@ -1,10 +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';
+/** 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

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

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