@chipmobilesdk/rn-notification 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-notification",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -38,6 +38,7 @@
 		"src/schedule",
 		"src/state",
 		"src/testing",
+		"skills",
 		"README.md",
 		"CHANGELOG.md"
 	],

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

@@ -0,0 +1,102 @@
+---
+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, Android channel migration, tap routing, FCM. Use when scheduling a reminder, 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.1.1"
+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
+- 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.** The package maintains its own recurrence windows
+   and re-anchoring, but never invents a desired set. Data changed and you did not call
+   `reconcile()` means the device is stale, by design.
+
+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`, `resetState`, `clearOwner`, `isNonFailure` 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` |
+| 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` |
+
+## Debugging "it did not arrive"
+
+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.