@chipmobilesdk/rn-notification 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,42 +1,80 @@
-# Changelog
-
-All notable changes to `@chipmobilesdk/rn-notification` are documented here.
-
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased] — 0.1.0
-
-First release. New package, no existing consumers, no migration burden.
-
-### Added
-
-- **Scheduling** — caller-supplied identifiers, replacement semantics, a two-sided 60-second tolerance window, and full-detail pending reads that let a consumer diff the device against its own intent.
-- **Time anchoring** — wall-clock (default) and absolute modes, with re-anchoring on device time-zone change and an `anchoringGeneration` on every entry so the one case re-anchoring cannot fix stays detectable.
-- **Reconciliation** — desired-set convergence that is idempotent, domain-scoped, chunked, and serialized against itself.
-- **Recurrence** — declare a rule once; the package maintains a bounded 60-day / 32-occurrence window and refreshes it, with deterministic daylight-saving resolution and clock-discontinuity bounding.
-- **Permissions** — six states that never collapse, independent display and exact-alarm requests, per-permission settings deep links, external-change detection, and manufacturer restriction reporting that admits `unknown`.
-- **Channels and tones** — one declarative configuration mapped to each platform, with a real migration path for Android's immutable channels.
-- **Interaction** — one handler for foreground, background, and cold start, backed by a durable buffer that survives process death.
-- **Push** — a provider-agnostic gate with a normalized envelope, token lifecycle, deduplication across process death, and best-effort handling of newer payload versions.
-- **Observability** — a structured event stream with content redaction, a state snapshot, burst detection, fault injection, and a shared conformance suite.
-
-### Notes
-
-- **Local engine substitution — approved 2026-08-16.** The specification named Notifee as the default engine. Its repository was archived on 2026-04-07 with its last release in December 2024, failing the constitution's actively-maintained-dependency requirement. This package uses `react-native-notify-kit`, the maintained 100%-API-compatible fork, **confirmed by the project owner**. The engine sits behind `NotificationEngineAdapter` and no consumer-facing behaviour depends on the choice — this substitution changed no functional requirement, success criterion, or user story. `expo-notifications` is the recorded migration target should the fork stall.
-- **Push is an optional peer.** An app that never imports `/push` ships no provider code, no push permissions, and no entitlements, and takes on none of the provider's data-collection declarations.
-- **No exact-alarm permission is declared by this package.** Consumers opt in; without it, notifications are scheduled in approximate mode with an explicit `mayBeDelayed` flag. `USE_EXACT_ALARM` is never recommended — Google Play restricts it to alarm, timer, and calendar apps.
-
-### Stability
-
-| Surface | Stability |
-|---|---|
-| Identifier rules | Stable — breaking to change (persisted by the platform on user devices) |
-| Routing payload contract | Stable — breaking to change |
-| Push payload contract | Stable — **append-only**; repurposing a released field is a contract violation, not a version bump |
-| Scheduling, reconciliation, permissions, interaction | Stable — additive minor releases only |
-| Adapter ports | Experimental — may gain members in minor releases |
-| Persisted state schema | Private — incompatible versions are discarded and rebuilt, never migrated |
-
-### Reserved for additive minor releases
-
-Additional push provider adapters, additional recurrence kinds, additional tone attributes, additional diagnostic identifiers, a consumer-supplied storage port, and in-app notification presentation.
+# Changelog
+
+All notable changes to `@chipmobilesdk/rn-notification` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0]
+
+Additive minor, delivering on the reserved **additional tone attributes** commitment below. **No consumer source change, no configuration change, and no tone version bump is required.**
+
+### Added
+
+- **Alarm-capable tones.** `ToneDeclaration` gains `repeatAlert` — an alert sound that repeats until the user handles the notification — and `timeSensitive`, which asks the platform for its time-sensitive treatment. `repeatAlert` carries a **required** duration, so an unbounded repeating alert is unrepresentable rather than merely discouraged; the range is 1 to 60 minutes, exported as `REPEAT_ALERT_BOUNDS`.
+- **A repeating alert stops on its own, and the notification stays.** When the declared window elapses the sound ends and the notification remains in the tray. Handling it earlier stops the sound immediately. Both hold with the app process dead, which is where the expiry almost always falls.
+- **`registerBackgroundNotificationHandler`.** The one piece a consumer wires up themselves, at module scope in `index.js`. Required only by an app that declares a repeating tone; its absence is reported as `REPEAT_STOP_HANDLER_MISSING` rather than discovered as a phone that will not stop ringing.
+- **`ChannelApplyResult.labelsRefreshed`** and **`ChannelApplyResult.repeatUnavailable`**, so a caller can tell a label correction from a creation, a migration, and a no-op — and can see which attributes the platform refused.
+- Four diagnostic identifiers: `INVALID_TONE_REPEAT`, and the non-failures `TONE_LABELS_REFRESHED`, `REPEAT_ALERT_UNAVAILABLE`, `REPEAT_STOP_HANDLER_MISSING`. The stable set is now **43**.
+
+### Fixed
+
+- **Tone labels reach system settings.** `ToneDeclaration.name` was documented as the name shown in system settings and never reached one: `ResolvedTone` carried no label at all, so the adapter passed the tone *identifier* as the channel name. Users read `reminder` where a consumer had written a localized label. `description` shared the same fate.
+- **A tone label can be corrected after the first install.** Declaring a tone the device already held returned early, so a label could be set exactly once per device, forever. Android permits updating a channel's name and description in place — and ignores everything else, which is precisely what keeps the user's own importance, sound, and Do-Not-Disturb choices intact. Correcting a label now costs no version bump and no user setting.
+
+### Changed
+
+- **One-time label refresh on upgrade.** The first `apply()` after upgrading performs a single label-refresh write per existing tone, because every channel on every existing device currently carries the tone id as its name. Every apply after that is zero-operation again, as before. Nothing is recreated, retired, re-homed, or cancelled.
+- **`NotificationEngineAdapter` gained members** (*Experimental* per the stability table below): `declareTone` now returns `'created' | 'labelsRefreshed' | 'unchanged'` instead of a boolean, `EngineCapabilities` gained `supportsRepeatingAlert`, and the port gained `silenceDelivered`, `listRepeatStops`, `subscribeToDeliveries`, `registerBackgroundDeliveryHandler`, and `hasBackgroundDeliveryHandler`. Only an app supplying its own engine is affected.
+- **`cms.stop:` is now a reserved identifier prefix.** Repeat expiry cancels its markers by identifier, so a consumer identifier that looked like one would be deleted out from under a real notification.
+
+### Platform limits — stated rather than papered over
+
+- **iOS does not repeat an alert sound.** There is no looping API, and the one interruption level that overrides the mute switch requires an entitlement Apple grants by application — which this package does not hold and does not request. A repeating alert on iOS is reported in `repeatUnavailable`; the notification still delivers and still sounds once.
+- **iOS `timeSensitive` needs the consuming app's own Time Sensitive Notifications capability.** Without it iOS delivers at `active`. This was already true for `urgency: 'max'` in 0.1.x and was previously undocumented.
+- **The declared window is a floor, not a precise stop.** The entry that ends the alert is scheduled like any other notification and inherits the same delivery accuracy — within 60 s with exact alarms, up to 15 minutes without. Measured on an emulator without `SCHEDULE_EXACT_ALARM`: a declared 2-minute window ran 2m35s and 3m00s.
+- **Android alarm audio uses the notification volume, not the alarm volume.** A device with notifications muted stays silent. Not fixable without native changes.
+- **Android also stops an insistent sound when the user opens the notification shade** — platform behaviour, and arguably the right one.
+- **The stop marker is briefly visible in the tray** before it is removed, on a minimum-importance, silent channel. A scheduled notification is the only OS-driven execution the engine offers.
+- **Without the registered background handler, a repeating alert does not stop while the app is dead.**
+- **Aggressive vendor battery management can delay marker delivery**, in the same way and for the same reasons the package already reports `mayBeDelayed` and `unknown`.
+
+### Migration
+
+None required. Every addition is optional, `repeatAlert` and `timeSensitive` are realized per notification rather than as channel configuration, and labels are updated in place — so no tone version moves and no channel is recreated. Only an app that declares a repeating tone needs the new setup step in `index.js`.
+
+## [Unreleased] — 0.1.0
+
+First release. New package, no existing consumers, no migration burden.
+
+### Added
+
+- **Scheduling** — caller-supplied identifiers, replacement semantics, a two-sided 60-second tolerance window, and full-detail pending reads that let a consumer diff the device against its own intent.
+- **Time anchoring** — wall-clock (default) and absolute modes, with re-anchoring on device time-zone change and an `anchoringGeneration` on every entry so the one case re-anchoring cannot fix stays detectable.
+- **Reconciliation** — desired-set convergence that is idempotent, domain-scoped, chunked, and serialized against itself.
+- **Recurrence** — declare a rule once; the package maintains a bounded 60-day / 32-occurrence window and refreshes it, with deterministic daylight-saving resolution and clock-discontinuity bounding.
+- **Permissions** — six states that never collapse, independent display and exact-alarm requests, per-permission settings deep links, external-change detection, and manufacturer restriction reporting that admits `unknown`.
+- **Channels and tones** — one declarative configuration mapped to each platform, with a real migration path for Android's immutable channels.
+- **Interaction** — one handler for foreground, background, and cold start, backed by a durable buffer that survives process death.
+- **Push** — a provider-agnostic gate with a normalized envelope, token lifecycle, deduplication across process death, and best-effort handling of newer payload versions.
+- **Observability** — a structured event stream with content redaction, a state snapshot, burst detection, fault injection, and a shared conformance suite.
+
+### Notes
+
+- **Local engine substitution — approved 2026-08-16.** The specification named Notifee as the default engine. Its repository was archived on 2026-04-07 with its last release in December 2024, failing the constitution's actively-maintained-dependency requirement. This package uses `react-native-notify-kit`, the maintained 100%-API-compatible fork, **confirmed by the project owner**. The engine sits behind `NotificationEngineAdapter` and no consumer-facing behaviour depends on the choice — this substitution changed no functional requirement, success criterion, or user story. `expo-notifications` is the recorded migration target should the fork stall.
+- **Push is an optional peer.** An app that never imports `/push` ships no provider code, no push permissions, and no entitlements, and takes on none of the provider's data-collection declarations.
+- **No exact-alarm permission is declared by this package.** Consumers opt in; without it, notifications are scheduled in approximate mode with an explicit `mayBeDelayed` flag. `USE_EXACT_ALARM` is never recommended — Google Play restricts it to alarm, timer, and calendar apps.
+
+### Stability
+
+| Surface | Stability |
+|---|---|
+| Identifier rules | Stable — breaking to change (persisted by the platform on user devices) |
+| Routing payload contract | Stable — breaking to change |
+| Push payload contract | Stable — **append-only**; repurposing a released field is a contract violation, not a version bump |
+| Scheduling, reconciliation, permissions, interaction | Stable — additive minor releases only |
+| Adapter ports | Experimental — may gain members in minor releases |
+| Persisted state schema | Private — incompatible versions are discarded and rebuilt, never migrated |
+
+### Reserved for additive minor releases
+
+Additional push provider adapters, additional recurrence kinds, ~~additional tone attributes~~ *(delivered in 0.2.0)*, additional diagnostic identifiers, a consumer-supplied storage port, and in-app notification presentation.