@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/package.json

@@ -1,75 +1,61 @@
-{
-	"name": "@chipmobilesdk/rn-notification",
-	"version": "0.4.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		},
-		"./push": {
-			"types": "./src/push/index.ts",
-			"react-native": "./src/push/index.ts",
-			"default": "./src/push/index.ts"
-		},
-		"./testing": {
-			"types": "./src/testing/index.ts",
-			"react-native": "./src/testing/index.ts",
-			"default": "./src/testing/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/initialize.ts",
-		"src/channel",
-		"src/contract",
-		"src/diagnostics",
-		"src/engine",
-		"src/interaction",
-		"src/maintenance",
-		"src/permission",
-		"src/push",
-		"src/recurrence",
-		"src/repeat",
-		"src/reconcile",
-		"src/schedule",
-		"src/state",
-		"src/testing",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"@react-native-firebase/app": ">=26.0.0",
-		"@react-native-firebase/messaging": ">=26.0.0",
-		"react": ">=19",
-		"react-native": ">=0.85",
-		"react-native-localize": ">=3.7.0",
-		"react-native-mmkv": ">=4.0.0",
-		"react-native-notify-kit": ">=10.5.0"
-	},
-	"peerDependenciesMeta": {
-		"@react-native-firebase/app": {
-			"optional": true
-		},
-		"@react-native-firebase/messaging": {
-			"optional": true
-		}
-	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-notification",
+	"version": "0.5.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./push": {
+			"types": "./src/push/index.ts",
+			"react-native": "./src/push/index.ts",
+			"default": "./src/push/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		}
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"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",
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-localize": ">=3.7.0",
+		"react-native-mmkv": ">=4.0.0",
+		"react-native-notify-kit": ">=10.5.0"
+	},
+	"peerDependenciesMeta": {
+		"@react-native-firebase/app": {
+			"optional": true
+		},
+		"@react-native-firebase/messaging": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

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

@@ -1,173 +1,172 @@
----
-name: sdk-rn-notification
-description: "Local and push notifications via @chipmobilesdk/rn-notification: scheduling, identifiers, wall-clock vs absolute anchoring, idempotent reconciliation, recurrence windows, permissions, alarm-style repeating tones with a bounded window, tone labels in system settings, Android channel migration, tap routing, FCM. Use when scheduling a reminder or alarm, making a notification repeat until handled, naming a tone users see in settings, handling a notification tap, requesting notification permission, changing a channel, or debugging a notification that did not arrive."
-metadata:
-  package: "@chipmobilesdk/rn-notification"
-  packageVersion: "0.3.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-notification
-
-Scheduled local notifications with stable identity and idempotent reconciliation,
-provider-agnostic push, permissions, declarative channels and tones, and tap routing that
-survives a cold start.
-
-## Use this when
-
-- Scheduling, replacing, or cancelling a notification
-- Reacting to a tap, an action button, or a dismissal
-- Requesting notification or exact-alarm permission
-- Declaring or changing a tone/channel, or enabling push
-- Building an alarm-style reminder that repeats until the user handles it
-- Debugging a notification that did not arrive, or arrived twice
-
-**Not** for in-app banners or an inbox (this package renders nothing), for storing app
-data (`@chipmobilesdk/rn-local-db`), or for translating text — resolve strings yourself.
-
-## Read before writing any code
-
-Three things cause most of the bugs, and none is visible in the type signatures:
-
-1. **Identifiers are yours and must be derived from data.** `crypto.randomUUID()` means
-   you can never replace or cancel what you scheduled. Nothing is normalized, so
-   `Task:1` and `task:1` are two different notifications.
-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.
-
-Read `## Choosing identifiers`, `## Choosing an anchoring mode`, and
-`## Maintenance versus reconciliation` before designing anything.
-
-**A refusal must never break the user's work.** Permission denial is a degradation, not a
-failure: the caller's operation still succeeds and the lost capability is reported
-separately. Without exact-alarm capability notifications are still scheduled, flagged
-`mayBeDelayed`. Never gate a user action on a permission answer.
-
-## Android: two manifest entries you must add yourself
-
-Consumer-owned; this package cannot ship either.
-
-- **`SCHEDULE_EXACT_ALARM` arrives whether you want it or not** — the engine declares it
-  and manifest merging is transitive. It is store-restricted and needs a Play Console
-  declaration. Remove it with `tools:node="remove"` unless you need precise timing.
-- **Backup exclusion** for the state record — a deduplication ledger restored onto another
-  device claims payloads were already delivered, silently suppressing real ones.
-
-See `### Android` and `### Backup exclusion`.
-
-## Public API
-
-Three entrypoints. The **root** exports one factory per concern (`createScheduler`,
-`createReconciler`, `createRecurrence`, `createPermissions`, `createChannels`,
-`createInteractions`, `createSnapshot`), the maintenance steps and their registry, plus
-`resolveTone`, `registerBackgroundNotificationHandler`, `resetState`, `clearOwner`,
-`isNonFailure`, `REPEAT_ALERT_BOUNDS` and `DIAGNOSTIC_CODES`.
-**`/push`** carries the push gate, FCM provider, instruction handler and sign-out —
-**import it only if you enable push**, because an app that never touches this subpath ships
-no provider code, no push permissions, and no entitlements. **`/testing`** carries the fake
-engine and provider, the conformance suite and the fault injector.
-
-Enumerate exact names from `node_modules/@chipmobilesdk/rn-notification/src/index.ts`
-rather than guessing.
-
-## Where the detail lives
-
-`node_modules/@chipmobilesdk/rn-notification/README.md`:
-
-| Need | Section |
-|---|---|
-| Install, peers, enabling push | `## Installation`, `### Enabling push (optional)` |
-| Native setup | `### iOS`, `### Android`, `### Backup exclusion` |
-| Naming notifications | `## Choosing identifiers` |
-| Tones, alarms, labels, version bumps | `## Tones and channels` |
-| Time zones and travel | `## Choosing an anchoring mode` |
-| Automatic vs your responsibility | `## Maintenance versus reconciliation` |
-| Converging the device to your data | `## Reconciliation`, `## Recurrence` |
-| Permission timing and recovery | `## Permissions` |
-| Taps, actions, cold start | `## Interaction` |
-| Push and the backend contract | `## Push` |
-| On-device storage and privacy | `## What is persisted`, `## Data behaviour …` |
-| Limits and timing budgets | `## Budgets` |
-| Error codes | `## Diagnostic identifiers` |
-
-## Alarm-style tones (0.2.0+)
-
-For a reminder that must not be missed — medication, a wake-up, an appointment — declare
-the repeat on the **tone**, not on each notification:
-
-```ts
-await channels.apply([{
-  id: 'medication',
-  name: t('notifications.medication.name'),   // localized; users read this in settings
-  description: t('notifications.medication.hint'),
-  urgency: 'max',
-  sound: { name: 'chime' },
-  vibration: true,
-  bypassDoNotDisturb: true,                    // an alarm silenced by DND is not an alarm
-  repeatAlert: { forMs: 15 * 60 * 1000 },      // required bound, 1–60 minutes
-  timeSensitive: true,
-  version: 1,                                  // unchanged — these need no bump
-}]);
-```
-
-Four things to get right, none of them visible in the signatures:
-
-1. **The duration is mandatory and bounded (1–60 min, `REPEAT_ALERT_BOUNDS`).** There is no
-   unbounded form; the type forbids it. Do not reach for a workaround — an alert with no
-   bound means a user comes home to a phone still ringing.
-2. **Expiry stops the sound; it never removes the notification.** The user must still be
-   able to see what they missed. If you find yourself cancelling at expiry, you have
-   inverted the requirement. The window is a **floor**, not a precise stop — the entry
-   that ends the alert inherits normal delivery accuracy, so without exact alarms it
-   overruns (a declared 2 min measured 2m35s–3m00s). Never promise a caller an exact cut-off.
-3. **Repeating tones need one setup step**, at module scope in `index.js`, never in a
-   component or an effect:
-   ```js
-   import { registerBackgroundNotificationHandler } from '@chipmobilesdk/rn-notification';
-   registerBackgroundNotificationHandler({ engine });
-   ```
-   Without it nothing ends the alert while the app is dead. `apply()` reports
-   `REPEAT_STOP_HANDLER_MISSING`. An app with no repeating tone needs none of this.
-4. **iOS refuses repetition entirely** — no looping API exists, and the alert level that
-   would need an Apple-granted entitlement does not loop either. It is reported in
-   `result.repeatUnavailable`; the notification still delivers and sounds once. Never
-   promise a caller an iOS alarm loops. `timeSensitive` on iOS also needs the consuming
-   app's own Time Sensitive Notifications capability, or it degrades to `active`.
-
-Read `## Tones and channels` before promising behaviour to anyone: it carries the
-per-platform matrix and six limits that stay true (notification volume rather than alarm
-volume on Android, the shade stopping an insistent sound, vendor battery management).
-
-## Changing a tone: when a version bump is required
-
-A bump means a **new channel**, and a new channel means the user loses every setting they
-adjusted. Never bump one to fix a label.
-
-| Change | Bump `version`? |
-|---|---|
-| `name`, `description` | **No** — updated in place on existing installs |
-| `repeatAlert`, `timeSensitive` | **No** — realized per notification |
-| `urgency`, `sound`, `vibration`, `badge`, `groupId`, `bypassDoNotDisturb` | **Yes** |
-
-`apply()` reports a label correction as `labelsRefreshed`, distinct from `created`,
-`migrated`, and `unchanged`.
-
-## Debugging "it did not arrive"
-
-First check the installed version: **before 0.2.1** the state record never persisted on a
-device (it used react-native-mmkv's v3 constructor, absent in v4), so deduplication and
-cold-start tap buffering only lasted one session. Require `0.2.1` or later.
-
-Capture a state snapshot (`createSnapshot`) before guessing — permissions, applied channel
-versions, pending set, last maintenance cycle, discrepancies and state health, in one
-place. Some codes are **reported outcomes, not failures** (`TRUNCATED_OVER_CEILING`,
-`EXACT_ALARM_UNAVAILABLE`, `PENDING_SET_DISCREPANCY`, `BURST_THRESHOLD_EXCEEDED`,
-`PAYLOAD_VERSION_SKEW`); use `isNonFailure(code)` rather than treating every code as an
-error.
+---
+name: sdk-rn-notification
+description: "Local and push notifications via @chipmobilesdk/rn-notification: scheduling, identifiers, wall-clock vs absolute anchoring, idempotent reconciliation, recurrence windows, permissions, alarm-style repeating tones with a bounded window, tone labels in system settings, Android channel migration, tap routing, FCM. Use when scheduling a reminder or alarm, making a notification repeat until handled, naming a tone users see in settings, handling a notification tap, requesting notification permission, changing a channel, or debugging a notification that did not arrive."
+metadata:
+  package: "@chipmobilesdk/rn-notification"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-notification
+
+Scheduled local notifications with stable identity and idempotent reconciliation,
+provider-agnostic push, permissions, declarative channels and tones, and tap routing that
+survives a cold start.
+
+## Use this when
+
+- Scheduling, replacing, or cancelling a notification
+- Reacting to a tap, an action button, or a dismissal
+- Requesting notification or exact-alarm permission
+- Declaring or changing a tone/channel, or enabling push
+- Building an alarm-style reminder that repeats until the user handles it
+- Debugging a notification that did not arrive, or arrived twice
+
+**Not** for in-app banners or an inbox (this package renders nothing), for storing app
+data (`@chipmobilesdk/rn-local-db`), or for translating text — resolve strings yourself.
+
+## Read before writing any code
+
+Three things cause most of the bugs, and none is visible in the type signatures:
+
+1. **Identifiers are yours and must be derived from data.** `crypto.randomUUID()` means
+   you can never replace or cancel what you scheduled. Nothing is normalized, so
+   `Task:1` and `task:1` are two different notifications.
+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.
+
+Read `## Choosing identifiers`, `## Choosing an anchoring mode`, and
+`## Maintenance versus reconciliation` before designing anything.
+
+**A refusal must never break the user's work.** Permission denial is a degradation, not a
+failure: the caller's operation still succeeds and the lost capability is reported
+separately. Without exact-alarm capability notifications are still scheduled, flagged
+`mayBeDelayed`. Never gate a user action on a permission answer.
+
+## Android: two manifest entries you must add yourself
+
+Consumer-owned; this package cannot ship either.
+
+- **`SCHEDULE_EXACT_ALARM` arrives whether you want it or not** — the engine declares it
+  and manifest merging is transitive. It is store-restricted and needs a Play Console
+  declaration. Remove it with `tools:node="remove"` unless you need precise timing.
+- **Backup exclusion** for the state record — a deduplication ledger restored onto another
+  device claims payloads were already delivered, silently suppressing real ones.
+
+See `### Android` and `### Backup exclusion`.
+
+## Public API
+
+Three entrypoints. The **root** exports one factory per concern (`createScheduler`,
+`createReconciler`, `createRecurrence`, `createPermissions`, `createChannels`,
+`createInteractions`, `createSnapshot`), the maintenance steps and their registry, plus
+`resolveTone`, `registerBackgroundNotificationHandler`, `resetState`, `clearOwner`,
+`isNonFailure`, `REPEAT_ALERT_BOUNDS` and `DIAGNOSTIC_CODES`.
+**`/push`** carries the push gate, FCM provider, instruction handler and sign-out —
+**import it only if you enable push**, because an app that never touches this subpath ships
+no provider code, no push permissions, and no entitlements. **`/testing`** carries the fake
+engine and provider, the conformance suite and the fault injector.
+
+Enumerate exact names from `node_modules/@chipmobilesdk/rn-notification/src/index.ts`
+rather than guessing.
+
+## Where the detail lives
+
+`node_modules/@chipmobilesdk/rn-notification/README.md`:
+
+| Need | Section |
+|---|---|
+| Install, peers, enabling push | `## Installation`, `### Enabling push (optional)` |
+| Native setup | `### iOS`, `### Android`, `### Backup exclusion` |
+| Naming notifications | `## Choosing identifiers` |
+| Tones, alarms, labels, version bumps | `## Tones and channels` |
+| Time zones and travel | `## Choosing an anchoring mode` |
+| Automatic vs your responsibility | `## Maintenance versus reconciliation` |
+| Converging the device to your data | `## Reconciliation`, `## Recurrence` |
+| Permission timing and recovery | `## Permissions` |
+| Taps, actions, cold start | `## Interaction` |
+| Push and the backend contract | `## Push` |
+| On-device storage and privacy | `## What is persisted`, `## Data behaviour …` |
+| Limits and timing budgets | `## Budgets` |
+| Error codes | `## Diagnostic identifiers` |
+
+## Alarm-style tones (0.2.0+)
+
+For a reminder that must not be missed — medication, a wake-up, an appointment — declare
+the repeat on the **tone**, not on each notification:
+
+```ts
+await channels.apply([{
+  id: 'medication',
+  name: t('notifications.medication.name'),   // localized; users read this in settings
+  description: t('notifications.medication.hint'),
+  urgency: 'max',
+  sound: { name: 'chime' },
+  vibration: true,
+  bypassDoNotDisturb: true,                    // an alarm silenced by DND is not an alarm
+  repeatAlert: { forMs: 15 * 60 * 1000 },      // required bound, 1–60 minutes
+  timeSensitive: true,
+  version: 1,                                  // unchanged — these need no bump
+}]);
+```
+
+Four things to get right, none of them visible in the signatures:
+
+1. **The duration is mandatory and bounded (1–60 min, `REPEAT_ALERT_BOUNDS`).** There is no
+   unbounded form; the type forbids it. Do not reach for a workaround — an alert with no
+   bound means a user comes home to a phone still ringing.
+2. **Expiry stops the sound; it never removes the notification.** The user must still be
+   able to see what they missed. If you find yourself cancelling at expiry, you have
+   inverted the requirement. The window is a **floor**, not a precise stop — the entry
+   that ends the alert inherits normal delivery accuracy, so without exact alarms it
+   overruns (a declared 2 min measured 2m35s–3m00s). Never promise a caller an exact cut-off.
+3. **Repeating tones need one setup step**, at module scope in `index.js`, never in a
+   component or an effect:
+   ```js
+   import { registerBackgroundNotificationHandler } from '@chipmobilesdk/rn-notification';
+   registerBackgroundNotificationHandler({ engine });
+   ```
+   Without it nothing ends the alert while the app is dead. `apply()` reports
+   `REPEAT_STOP_HANDLER_MISSING`. An app with no repeating tone needs none of this.
+4. **iOS refuses repetition entirely** — no looping API exists, and the alert level that
+   would need an Apple-granted entitlement does not loop either. It is reported in
+   `result.repeatUnavailable`; the notification still delivers and sounds once. Never
+   promise a caller an iOS alarm loops. `timeSensitive` on iOS also needs the consuming
+   app's own Time Sensitive Notifications capability, or it degrades to `active`.
+
+Read `## Tones and channels` before promising behaviour to anyone: it carries the
+per-platform matrix and six limits that stay true (notification volume rather than alarm
+volume on Android, the shade stopping an insistent sound, vendor battery management).
+
+## Changing a tone: when a version bump is required
+
+A bump means a **new channel**, and a new channel means the user loses every setting they
+adjusted. Never bump one to fix a label.
+
+| Change | Bump `version`? |
+|---|---|
+| `name`, `description` | **No** — updated in place on existing installs |
+| `repeatAlert`, `timeSensitive` | **No** — realized per notification |
+| `urgency`, `sound`, `vibration`, `badge`, `groupId`, `bypassDoNotDisturb` | **Yes** |
+
+`apply()` reports a label correction as `labelsRefreshed`, distinct from `created`,
+`migrated`, and `unchanged`.
+
+## Debugging "it did not arrive"
+
+First check the installed version: **before 0.2.1** the state record never persisted on a
+device (it used react-native-mmkv's v3 constructor, absent in v4), so deduplication and
+cold-start tap buffering only lasted one session. Require `0.2.1` or later.
+
+Capture a state snapshot (`createSnapshot`) before guessing — permissions, applied channel
+versions, pending set, last maintenance cycle, discrepancies and state health, in one
+place. Some codes are **reported outcomes, not failures** (`TRUNCATED_OVER_CEILING`,
+`EXACT_ALARM_UNAVAILABLE`, `PENDING_SET_DISCREPANCY`, `BURST_THRESHOLD_EXCEEDED`,
+`PAYLOAD_VERSION_SKEW`); use `isNonFailure(code)` rather than treating every code as an
+error.