@chipmobilesdk/rn-notification 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @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

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,26 @@ 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`.
 
@@ -342,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:
@@ -412,7 +502,7 @@ The state snapshot (`createSnapshot`) reports the pending set entry by entry, bu
 
 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.5.0",
+	"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",

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';