@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/contract/errors.ts

@@ -1,134 +1,142 @@
-/**
- * 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',
-
-	// --- Maintenance (0.4.0) -------------------------------------------------
-	/** An automatic maintenance cycle threw. Reported here because no caller awaits it. */
-	MAINTENANCE_FAILED: 'MAINTENANCE_FAILED',
-} 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);
-}
+/**
+ * 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`.
+ */
+
+import { SdkError } from '@chipmobilesdk/rn-core';
+
+import { redactContext } from '../diagnostics/redact';
+
+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',
+	/** The durable store could not open; state lasts for this session only. */
+	STATE_STORE_DEGRADED: 'STATE_STORE_DEGRADED',
+	STATE_CAP_EVICTED: 'STATE_CAP_EVICTED',
+
+	// --- Volume --------------------------------------------------------------
+	BURST_THRESHOLD_EXCEEDED: 'BURST_THRESHOLD_EXCEEDED',
+
+	// --- Maintenance (0.4.0) -------------------------------------------------
+	/** An automatic maintenance cycle threw. Reported here because no caller awaits it. */
+	MAINTENANCE_FAILED: 'MAINTENANCE_FAILED',
+} 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 SdkError<DiagnosticCode> {
+	readonly context?: Readonly<Record<string, unknown>>;
+
+	constructor(code: DiagnosticCode, message: string, context?: Readonly<Record<string, unknown>>) {
+		super('rn-notification', code, { message });
+		this.name = 'NotificationError';
+		// Redacted on the way in: an error object reaches crash reporters, which
+		// never run with verbose diagnostics.
+		const redacted = redactContext(context, false);
+		if (redacted !== undefined) {
+			this.context = redacted;
+		}
+	}
+}
+
+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;