@chipmobilesdk/rn-notification 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,161 @@
 # @chipmobilesdk/rn-notification
 
+## 0.6.0
+
+### Minor Changes
+
+- `createNotifications(config, deps?)` assembles the whole package in one call. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  - It returns the scheduler, reconciler, recurrence, permissions, channels, interactions
+    and snapshot, wired over one engine, one state store and the one redacting
+    diagnostic emitter, plus `onInteraction`, `runMaintenance`, `canScheduleExactly` and
+    `dispose`. The engine, store, clock and time zone default to the real ones and can
+    be injected.
+  - `canScheduleExactly` follows the exact-alarm permission the package last read,
+    instead of each app passing its own callback (often `() => true`).
+  - Automatic maintenance has its standard steps registered: re-anchoring after a
+    time-zone change and the permission re-read, plus recurrence window refresh when you
+    pass `recurrenceRules`.
+  - The individual factories stay exported from the root, and are also available from
+    the new `@chipmobilesdk/rn-notification/advanced` entrypoint for apps that wire the
+    package themselves.
+  - Push: `getAvailability()` no longer fetches a token (which registered the device
+    with FCM, and APNs on iOS, just to answer the question). The new
+    `gate.handleBackground(raw)` runs a background payload through the same
+    normalization and persisted deduplication as a foreground one. Several
+    `onTokenChange` subscriptions no longer leak each other, and `dispose()` releases
+    them all.
+  - The README starts from `createNotifications`; its quick start is checked against a
+    type-checked example in the tests.
+
+- Fewer reads across the native bridge, storage written per collection, and one
+  pending budget for the whole app. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  - A reconcile, a group or owner cancel, and a tone apply each read the pending set
+    (or the channel list) once per pass instead of once per operation. Reconciling 100
+    changes now makes at most two full reads of the trigger list; it used to make one
+    or more per change. Scheduling one notification asks for identifiers only where the
+    engine can list them (`pendingIds`, optional on the engine port).
+  - Persisted state is stored under one key per collection. Recording a push
+    deduplication entry writes the dedup ledger alone, where every update used to
+    serialize the whole record. A record written by an earlier version is migrated on
+    first load.
+  - The series and migration ledgers no longer evict live entries at their cap. Only
+    exhausted series and retired channels are dropped; if live entries alone exceed the
+    cap they are all kept and the new `STATE_CAP_EXCEEDED` diagnostic says so. Evicting a
+    live entry reset a series' count and made a migrated tone look new.
+  - Reconciliation budgets a domain against the platform ceiling minus what other
+    domains, series and direct schedules already hold. Two domains could previously
+    overflow iOS's 64 pending notifications together while each reported no truncation.
+
+- Three fixes: what a tone change cancels, background interactions, and permanent denial. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  - `channels.apply()` cancels a pending notification only when it is on a tone the
+    package applied earlier and the configuration no longer declares. It used to cancel
+    everything whose tone was not in the list passed to that call, which included
+    notifications scheduled by other code through the same engine.
+  - Taps, actions and dismissals that arrive while the app is in the background are
+    delivered. `registerBackgroundNotificationHandler` takes an optional `onInteraction`
+    callback and an optional `store`: a running app's `onInteraction` handlers get the
+    event with `appState: 'background'`; otherwise the callback does; with no callback, or
+    one that throws, the event is kept in the store and delivered on the next start.
+    Before, background actions such as "Taken" or "Snooze" never reached the app.
+  - `permanentlyDenied` is now reported: after one refused display request on iOS, two on
+    Android 13+, and `DISPLAY_PERMISSION_PERMANENT` is emitted. The count resets once the
+    permission is seen granted. After `requestExactAlarmPermission()` the package re-reads
+    the capability when the user returns from system settings and notifies
+    `onPermissionChange`.
+
+### Patch Changes
+
+- The notify-kit engine is split by platform. Android and iOS behaviour live in separate
+  strategy files chosen once when the engine is created, instead of about fifteen
+  `Platform.OS` branches in one 790-line file. `createNotifyKitEngine` accepts an optional
+  `platform` for testing one platform's behaviour. No behaviour change. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+## 0.5.0
+
+### Minor Changes
+
+- Privacy (NOT-14), on top of `NotificationError` now extending `SdkError` from the new
+  `@chipmobilesdk/rn-core` dependency: ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - Text the user types into a reply action is no longer written to disk. It is held in
+    memory, so a handler registered later in the same process still receives
+    `inputText`; after process death the event arrives without it.
+  - A state snapshot reports pending entries with their content and routing values
+    reduced to their shape (`[string:12]`). Pass `verbose: () => true` to
+    `createSnapshot` to include the values while debugging.
+  - A `NotificationError`'s `context`, and every diagnostic context, also has token-,
+    URL- and e-mail-shaped strings removed under any key.
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Formatters come from rn-core's cache instead of being built per call. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-notification: resolving a time zone builds one `Intl.DateTimeFormat` per zone
+    instead of one per occurrence; expanding 32 series of 32 occurrences went from
+    about 230 ms to under 30 ms on Node. Zone validity is memoized.
+  - rn-i18n: number, currency and date formatters are cached. A bad option (an unknown
+    currency such as `usd1`) goes through the invalid-format policy instead of
+    throwing out of a render, and a locale's `defaultCurrency` must be a three-letter
+    ISO 4217 code at startup.
+
+### Patch Changes
+
+- One app-lifecycle source, and a startup that needs no extra frame. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `appLifecycle()`, a shared, reference-counted `AppState` subscription that
+    reports changes only (`active`, `inactive`, `background`), with `onForeground` for a
+    return from the background and `createManualLifecycle` in `./testing`.
+  - rn-camera, rn-ads and rn-notification hear the lifecycle through it instead of
+    subscribing to `AppState` each, so an app holds one native listener. The camera
+    controller's core layer no longer imports `react-native`.
+  - rn-payment: `syncOnForeground(engine)` and `<PaymentProvider syncOnForeground>` call
+    `handleForeground()` on each return from the background. Off by default; calling
+    `handleForeground()` yourself works as before.
+  - rn-i18n: `i18n.initSync()` resolves the locale before the first render when the
+    storage adapter has the new optional `getItemSync`, and returns false otherwise.
+    `localeStorageFromKeyValue(port)` builds such an adapter from rn-core's
+    `KeyValuePort` (MMKV).
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -17,6 +17,55 @@ Every notification feature re-solves the same problems, and most of them are dis
 - Display permission and exact-alarm permission are **different things**, asked separately, and a refusal must not break the user's actual work.
 - Android channels are **immutable once created** — changing one is a migration, not an assignment.
 
+## Quick start
+
+`createNotifications` assembles the whole package: scheduler, reconciler, recurrence,
+permissions, channels, interactions, a diagnostic snapshot, and automatic maintenance.
+It applies your tones, loads persisted state, and schedules exactly only while the
+exact-alarm permission allows it.
+
+<!-- quick-start -->
+```ts
+import { createNotifications } from '@chipmobilesdk/rn-notification';
+
+export async function setUpNotifications(navigate: (routing: unknown) => void) {
+	const notifications = await createNotifications({
+		tones: [
+			{
+				id: 'reminder',
+				name: 'Reminders',
+				urgency: 'high',
+				sound: { enabled: true },
+				vibration: true,
+				badge: true,
+				version: 1,
+			},
+		],
+	});
+
+	await notifications.permissions.requestDisplayPermission();
+
+	await notifications.scheduler.schedule({
+		id: 'task:42:due', // derived from your data, never random
+		content: { title: 'Pay the rent', body: 'Due today' },
+		tone: 'reminder',
+		moment: { at: Date.parse('2026-12-01T08:00:00') },
+		routing: { screen: 'task', taskId: '42' },
+	});
+
+	notifications.onInteraction(async event => {
+		if (event.kind === 'tap') navigate(event.routing);
+	});
+
+	return notifications;
+}
+```
+<!-- /quick-start -->
+
+The individual factories (`createScheduler`, `createReconciler`, `initialize`, the
+maintenance steps, ...) remain available, from the package root and from
+`@chipmobilesdk/rn-notification/advanced`, for an app that needs a different wiring.
+
 ## Installation
 
 ```sh
@@ -150,18 +199,25 @@ The package re-anchors wall-clock notifications when it notices the device zone
 | Applies `config.tones` (and any channel migration) during `initialize()` | `reconcile()` — the desired set |
 | Runs every step on `runtime.registry` when the app returns to the foreground — with the trigger `timeZoneChange` when the device zone moved meanwhile | |
 
-The steps themselves need inputs only your app has — the series rules it registered, the identifiers it expects, its permission module — so you register them once on `runtime.registry` after `initialize()`:
+`createNotifications` registers the standard steps for you: re-anchoring after a
+time-zone change, re-reading permissions, and — when you pass your recurrence rules —
+refreshing their windows. Steps that need inputs only your app has are added on
+`notifications.runtime.registry`:
 
 ```ts
-const { runtime } = await initialize(config, { engine, store });
-runtime.registry.register(createReAnchorStep({ engine, timeZone, resolveTone, canScheduleExactly }));
-runtime.registry.register(createWindowRefreshStep({ recurrence, registeredRules: () => myRules }));
-runtime.registry.register(createVerifyStep({ engine, expectedIds: () => myExpectedIds }));
-runtime.registry.register(createPermissionRefreshStep({ permissions }));
-// On teardown (tests, a sign-out that rebuilds the runtime):
-runtime.dispose();
+const notifications = await createNotifications(config, {
+  recurrenceRules: () => myRules, // the rules your app registered; the package never stores them
+});
+notifications.runtime.registry.register(
+  createVerifyStep({ engine: notifications.runtime.engine, expectedIds: () => myExpectedIds }),
+);
+// On teardown (tests, a sign-out that rebuilds everything):
+notifications.dispose();
 ```
 
+Wiring it yourself with `initialize()` and the step factories (from `./advanced`) still
+works; then registering the steps is yours.
+
 Before 0.4.0 nothing triggered these steps; they ran only when the app called `runMaintenance()` itself. A cycle that throws is reported as `MAINTENANCE_FAILED`, because nothing awaits it.
 
 **Reconciliation never runs on its own.** Only you know what your data implies; a package that guessed would cancel notifications it does not understand.
@@ -298,6 +354,13 @@ await permissions.openSettings('display');                  // per-permission
 
 Six states, never collapsed: `notAsked`, `granted`, `denied`, `permanentlyDenied`, `provisional`, `notRequired`.
 
+`permanentlyDenied` means the system will not show its prompt again, so offer Settings
+(`shouldOfferSettings(state)`). The platform itself only ever says `denied`; the package
+counts refusals — one on iOS, two on Android 13+ — and forgets them once the permission
+is seen granted. The exact-alarm capability is granted on a system settings screen, so
+`requestExactAlarmPermission()` answers with the state before the user chose; the real
+answer is re-read when they return to the app and reaches `onPermissionChange`.
+
 **Ask after intent, never on first launch.** A prompt at the wrong moment is a permanent denial.
 
 **A refusal never fails your operation.** The user's work completes; the lost capability is reported separately.
@@ -310,7 +373,28 @@ notifications.onInteraction(async event => {
 });
 ```
 
-One handler, identical shape in foreground, background, and cold start. Events that arrive before your handler registers are **buffered durably** — they survive process death, which is exactly what a cold-start tap is.
+One handler, identical shape in foreground, background, and cold start (`event.appState` says which).
+
+**Background actions need the module-scope handler.** The engine has one background
+handler per process, registered in `index.js`. Pass it your store and, optionally, a
+callback:
+
+```ts
+registerBackgroundNotificationHandler({
+  engine,
+  store: createMmkvStore(), // an interaction nobody handled is kept for the next start
+  onInteraction: async event => {
+    // Optional: handle "Taken" or "Snooze" right away, inside the background window.
+  },
+});
+```
+
+While the app is running, a background tap or action goes to your `onInteraction`
+handlers as usual. In a process started only for the event, it goes to the callback
+above; without one (or if it throws) it is kept in the store and delivered when the app
+next starts. Before 0.6.0 these events were dropped. Events that arrive before your handler registers are **buffered durably** — they survive process death, which is exactly what a cold-start tap is.
+
+Text the user typed into a reply action (`inputText`) is the exception: it is free text, so it is **never written to disk**. It is held in memory beside the buffer, so a handler that registers later in the same process still receives it; if the process dies first, the event is delivered without `inputText`.
 
 When the target is gone, call `reportTargetMissing()` and pick your own fallback. No platform error is ever shown to the user.
 
@@ -340,6 +424,14 @@ Foreground pushes are **never auto-displayed** — presentation is your decision
 
 Local schedules take precedence over push for the same identifier. A server that wants to override sends `cancel` then `schedule`.
 
+## Channel changes and notifications already scheduled
+
+`channels.apply()` cancels a pending notification only when it sits on a tone this
+package applied earlier and the configuration no longer declares. Notifications
+scheduled by other code through the same engine, and tones the package has never
+applied, are left alone (0.6.0; before, anything not in the list passed to `apply()` was
+cancelled).
+
 ## What is persisted
 
 Six collections, in app-private, backup-excluded storage:
@@ -353,7 +445,7 @@ Six collections, in app-private, backup-excluded storage:
 | Permission history | 64 | — |
 | Last reconcile summary | 1 | — |
 
-**No notification content, no push token, no desired set.** The interaction buffer is the sole content-bearing exception, and it evicts on delivery.
+**No notification content, no push token, no desired set, no typed reply.** The interaction buffer is the sole content-bearing exception (its routing payload), and it evicts on delivery.
 
 Corrupt state is **discarded and rebuilt**, never blocking. What you lose: deduplication history and buffered interactions. What is unaffected: **every notification already scheduled with the OS**.
 
@@ -404,9 +496,13 @@ Delivery accuracy: within **60 s** with exact alarms; within **15 min** without,
 
 ## Diagnostic identifiers
 
-43 stable identifiers across validation, reconciliation, permissions, channels, interaction, push, state, and volume. Every one is reachable through the fault injector. See `ALL_DIAGNOSTIC_CODES`.
+`NotificationError` extends `SdkError` from `@chipmobilesdk/rn-core` (`isSdkError`, `error.pkg === 'rn-notification'`), and its `context` is redacted when the error is built: content keys become their shape, and other strings lose anything shaped like a token, URL or e-mail address.
+
+The state snapshot (`createSnapshot`) reports the pending set entry by entry, but a snapshot is what gets pasted into a bug report, so each entry's content and routing values are reduced to their shape (`[string:12]`). Pass `verbose: () => true` to include the values while debugging.
+
+45 stable identifiers across validation, reconciliation, permissions, channels, interaction, push, state, and volume. Every one is reachable through the fault injector. See `ALL_DIAGNOSTIC_CODES`.
 
-Some are **reported outcomes, not failures** — the operation succeeded and something you should know happened alongside it: `TRUNCATED_OVER_CEILING`, `EXACT_ALARM_UNAVAILABLE`, `TARGET_MISSING`, `PENDING_SET_DISCREPANCY`, `BURST_THRESHOLD_EXCEEDED`, `PAYLOAD_VERSION_SKEW`, `PAYLOAD_DUPLICATE`, `STATE_CAP_EVICTED`, `STATE_CORRUPT_REBUILT`, `DND_BYPASS_UNAVAILABLE`, `TONE_LABELS_REFRESHED`, `REPEAT_ALERT_UNAVAILABLE`, `REPEAT_STOP_HANDLER_MISSING`. Use `isNonFailure(code)`.
+Some are **reported outcomes, not failures** — the operation succeeded and something you should know happened alongside it: `TRUNCATED_OVER_CEILING`, `EXACT_ALARM_UNAVAILABLE`, `TARGET_MISSING`, `PENDING_SET_DISCREPANCY`, `BURST_THRESHOLD_EXCEEDED`, `PAYLOAD_VERSION_SKEW`, `PAYLOAD_DUPLICATE`, `STATE_CAP_EVICTED`, `STATE_CAP_EXCEEDED`, `STATE_CORRUPT_REBUILT`, `DND_BYPASS_UNAVAILABLE`, `TONE_LABELS_REFRESHED`, `REPEAT_ALERT_UNAVAILABLE`, `REPEAT_STOP_HANDLER_MISSING`. Use `isNonFailure(code)`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-notification",
-	"version": "0.4.1",
+	"version": "0.6.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -11,6 +11,11 @@
 			"react-native": "./src/index.ts",
 			"default": "./src/index.ts"
 		},
+		"./advanced": {
+			"types": "./src/advanced.ts",
+			"react-native": "./src/advanced.ts",
+			"default": "./src/advanced.ts"
+		},
 		"./push": {
 			"types": "./src/push/index.ts",
 			"react-native": "./src/push/index.ts",
@@ -31,9 +36,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"@react-native-firebase/app": ">=26.0.0",
 		"@react-native-firebase/messaging": ">=26.0.0",

package/skills/sdk-rn-notification/SKILL.md

@@ -35,11 +35,12 @@ Three things cause most of the bugs, and none is visible in the type signatures:
 2. **Wall-clock is the default anchoring mode** — an 08:00 reminder stays 08:00 after the
    user changes time zone. One case re-anchoring cannot fix: read
    `### What re-anchoring cannot fix` before promising exact behaviour to anyone.
-3. **Reconciliation is never automatic.** Maintenance steps registered on
-   `runtime.registry` (window refresh, re-anchoring, verification, permission re-read) run
-   on every foreground return, but the package never invents a desired set. Data changed
-   and you did not call `reconcile()` means the device is stale, by design. The steps are
-   not registered for you — they need your rules and expected ids.
+3. **Reconciliation is never automatic.** Start from `createNotifications(config, deps)`:
+   it registers re-anchoring and the permission re-read, plus window refresh when you pass
+   `recurrenceRules`, and runs them on every foreground return. It never invents a desired
+   set: data changed and you did not call `reconcile()` means the device is stale, by
+   design. Wiring with `initialize()` and the factories from `./advanced` leaves step
+   registration to you.
 
 Read `## Choosing identifiers`, `## Choosing an anchoring mode`, and
 `## Maintenance versus reconciliation` before designing anything.

package/src/advanced.ts

@@ -0,0 +1,35 @@
+/**
+ * `@chipmobilesdk/rn-notification/advanced`: the individual factories, for an app
+ * that wires the package itself instead of using `createNotifications` (NOT-07).
+ *
+ * The package root still exports them too, for compatibility; new code that needs
+ * them should import from here, where they are documented as the advanced path.
+ */
+export { initialize } from './initialize';
+export type { NotificationRuntime, RuntimeDependencies } from './initialize';
+export { createScheduler } from './schedule';
+export type { Scheduler, ScheduleDependencies } from './schedule';
+export { createReconciler } from './reconcile';
+export type { Reconciler, ReconcileDependencies } from './reconcile';
+export { createRecurrence } from './recurrence';
+export type { Recurrence, RecurrenceDependencies } from './recurrence';
+export { createChannels } from './channel/migrate';
+export type { ChannelDependencies, Channels } from './channel/migrate';
+export { createToneResolver } from './channel/tone-map';
+export { createInteractions } from './interaction';
+export type { InteractionDependencies, Interactions } from './interaction';
+export { createSnapshot } from './diagnostics/snapshot';
+export type { Snapshot, SnapshotDependencies } from './diagnostics/snapshot';
+export { createBurstDetector } from './diagnostics/burst';
+export { createPermissions } from './permission';
+export type { PermissionDependencies, Permissions } from './permission';
+export { createPermissionRefreshStep } from './maintenance/permission-refresh';
+export { createReAnchorStep } from './maintenance/reanchor';
+export { createVerifyStep } from './maintenance/verify';
+export { createWindowRefreshStep } from './maintenance/window-refresh';
+export { MaintenanceController } from './maintenance/toggle';
+export { MaintenanceRegistry } from './maintenance/cycle';
+export type { MaintenanceContext, MaintenanceStep, MaintenanceTrigger } from './maintenance/cycle';
+export { StateManager } from './state/record';
+export { createMmkvStore } from './state/mmkv-store';
+export { createPlatformTimeZoneReader } from './schedule/anchor';