Add push noty script and docs (#10380)

2026-05-05 14:34:55 -05:00
parent 6f4ae14f36
commit 9bf06a80a5
7 changed files with 247 additions and 0 deletions
@@ -0,0 +1,97 @@
+# push-notification
+
+Sends sample APNS payloads to a booted iOS simulator via `xcrun simctl push`.
+Useful for exercising `useNotificationsHandler` (`src/lib/hooks/useNotificationHandler.ts`)
+without a real APNS round-trip — foreground display behavior, tap responses,
+and notification-driven navigation.
+
+## What this does and doesn't cover
+
+**Covers** — anything in `useNotificationsHandler`:
+
+- `setNotificationHandler` foreground behavior (banner, list, badge, sound flags)
+- `addNotificationResponseReceivedListener` tap handling
+- Account-switch flow when `recipientDid` differs from the signed-in account
+- Navigation routing for each `reason` (post threads, profiles, conversations)
+
+**Does not cover** — `BlueskyNSE` (the iOS Notification Service Extension):
+
+- Communication Notification styling for chat messages
+- Badge increment via `mutateWithBadge`
+- Custom `dm.aiff` sound for chat messages
+
+The simulator does not reliably invoke NSEs for `simctl push` on recent iOS
+versions (verified bypassed on iOS 26.4). To test NSE behavior, run on a real
+device with a real APNS push, or unit-test `NotificationService.didReceive`
+directly in Xcode.
+
+## Setup
+
+1. Boot an iOS simulator and install the app:
+   ```
+   yarn ios
+   ```
+2. Sign in to the account you'll be testing against. The `recipientDid` in
+   each payload is substituted at send time and must match the signed-in DID,
+   otherwise:
+   - Chat notifications trigger the account-switch flow
+   - Other reasons are silently dropped by the handler
+3. Find your DID. Easiest: visit your profile in a web browser and copy it
+   from the URL, or grep dev logs for `currentAccount`.
+
+## Usage
+
+```
+./send.sh <payload-name> [--did <did>] [--device <udid>] [--bundle <id>]
+```
+
+Pass the DID once via env var to avoid repeating it:
+
+```
+export BLUESKY_TEST_DID=did:plc:yourdidhere
+
+./send.sh like
+./send.sh chat-message
+./send.sh follow
+```
+
+Defaults: `--device booted`, `--bundle xyz.blueskyweb.app`. Run `./send.sh --help`
+for the full list of available payloads.
+
+## Foreground vs background
+
+`useNotificationsHandler` behaves differently depending on app state:
+
+- **Foreground** — `setNotificationHandler.handleNotification` decides whether
+  to show a banner, play a sound, etc. For chat reasons, the banner is
+  suppressed if `payload.convoId === currentConvoId` (you're already viewing
+  that conversation).
+- **Background or tapped** — `addNotificationResponseReceivedListener` fires
+  on tap and runs the navigation routing in `notificationToURL`.
+
+To test the response listener, background the app first (`cmd+shift+H` in the
+sim), send the push, then tap the banner.
+
+## Available payloads
+
+| Payload | Reason | Navigation target |
+|---|---|---|
+| `like.apns` | `like` | post thread (from `subject`) |
+| `reply.apns` | `reply` | post thread (from `uri`) |
+| `follow.apns` | `follow` | sender's profile (from `uri.host`) |
+| `chat-message.apns` | `chat-message` | `MessagesConversation` with `convoId` |
+| `chat-reaction.apns` | `chat-reaction` | `MessagesConversation` with `convoId` |
+
+The `subject` AT URIs reference fake post rkeys, so the destination screens
+will fail to load real content — that's expected. Routing exercises the
+navigation path, not the data fetch.
+
+## Adding a new payload
+
+1. Copy an existing `.apns` file in `payloads/` whose shape matches.
+2. Set `aps.mutable-content: 1` and a real `aps.alert.{title,body}`.
+3. Match the payload shape to `NotificationPayload` in
+   `src/lib/hooks/useNotificationHandler.ts` for the `reason` you're testing.
+4. Use `__RECIPIENT_DID__` as the placeholder for the recipient — `send.sh`
+   substitutes it at send time. Use it anywhere a DID needs to belong to the
+   logged-in user (typically `recipientDid`, and post `subject` for likes/replies).