expo-pusher-push-notifications 0.5.0 → 0.5.1

package/README.md

@@ -103,6 +103,14 @@ Custom sounds go in the plugin's `sounds` option. Details in [Extras](docs/extra
 - [Full API](docs/api.md)
 - [Migrating from react-native-pusher-push-notifications](docs/migrating.md)
 
+## Agent migration
+
+Migrating from `react-native-pusher-push-notifications` (b8ne / forks) with Cursor, Claude, Grok or another coding agent? Tell it:
+
+> Follow `node_modules/expo-pusher-push-notifications/skills/migrate-from-b8ne/SKILL.md` to migrate this app.
+
+The skill has the inventory commands, search/replace table, native cleanup steps and a checklist. Human version: [Migrating](docs/migrating.md). Copy it into `.cursor/skills/` or `.claude/skills/` to make it auto-discoverable.
+
 ## Good to know
 
 - This module owns the iOS notification delegate and the Android FCM service, so don't run it alongside `expo-notifications` or `@react-native-firebase/messaging`.

package/docs/migrating.md

@@ -1,32 +1,97 @@
 # Migrating from react-native-pusher-push-notifications
 
-This is a rewrite of [ZeptInc/react-native-pusher-push-notifications](https://github.com/ZeptInc/react-native-pusher-push-notifications) (itself a fork of [b8ne's](https://github.com/b8ne/react-native-pusher-push-notifications)).
+Covers [`b8ne/react-native-pusher-push-notifications`](https://github.com/b8ne/react-native-pusher-push-notifications) (and its forks such as ZeptInc / pusher-community) → `expo-pusher-push-notifications` **0.5.x**.
 
-Here is what the ZeptInc and b8ne packages had, and where it lives now:
+> **This is not a drop-in replacement.** The API is promise-based, start-up is a single `start()`/`Interests.start()` call, and native setup moves from hand-edited AppDelegate/MainApplication code to an Expo config plugin. Budget a small refactor, not a package swap.
 
-| Original | Here |
+Using an AI agent? Point it at [`skills/migrate-from-b8ne/SKILL.md`](../skills/migrate-from-b8ne/SKILL.md) (shipped in the npm package).
+
+## 1. Install / remove
+
+```sh
+npm uninstall react-native-pusher-push-notifications
+npx expo install expo-pusher-push-notifications
+```
+
+Requires an Expo dev build / prebuild (not Expo Go). Bare RN apps need `expo` modules installed (`npx install-expo-modules`).
+
+## 2. Native setup: config plugin instead of AppDelegate edits
+
+| Old (manual) | New |
 |---|---|
-| `setInstanceId` / `setAppKey` | `start({ instanceId })` |
-| `subscribe` / `unsubscribe` with callbacks | Promise-based. |
-| `setSubscriptions` (iOS only), `getSubscriptions` (Android only) | Both on both platforms. |
-| `setOnSubscriptionsChangedListener` (Android only) | `subscriptionsChanged` event on both platforms. |
-| `setUserId(userId, token, onError, onSuccess)` (b8ne, static token) | `setUserId(userId, token)`. A remote token provider is also supported. |
-| `clearAllState` (b8ne) | `clearAllState()` |
-| `on('registered' \| 'notification')` | Same, plus `error`, and it returns a removable subscription. |
-| iOS foreground / background / opened states | `appState` on every notification. |
-| `aps.data.incrementBadge` (b8ne, iOS) | Supported on iOS and Android, plus full badge APIs. |
-| Android launch-intent notification delivery (b8ne) | `getInitialNotification()` and an `opened` event on tap. |
-
-Neither original had custom sounds, notification channels, or local and scheduled notifications. Those are new here.
+| Carthage/CocoaPods `PushNotifications` framework, `RNPusherPushNotifications` imports | Autolinking (pods pulled automatically) |
+| AppDelegate: `didRegisterForRemoteNotificationsWithDeviceToken` → `[[RNPusherPushNotifications alloc] setDeviceToken:]`, `didReceiveRemoteNotification` forwarding | Expo AppDelegate subscriber in this module – **delete** those lines |
+| Android: `google-services.json` + gradle plugin lines, `MainApplication` / manifest service edits | Plugin config + `android.googleServicesFile` in app.json |
+| Push capability / background modes toggled in Xcode | Added by the plugin on prebuild |
 
-## Coming from 0.4
+```json
+{
+  "expo": {
+    "android": { "googleServicesFile": "./google-services.json" },
+    "plugins": [["expo-pusher-push-notifications", { "instanceId": "YOUR_BEAMS_INSTANCE_ID" }]]
+  }
+}
+```
 
-0.5 brings back device-token support (`DeviceToken`, `registerForDeviceToken`, `getDevicePushToken`, `deleteDevicePushToken`, and `mode: 'device'`), same API as 0.3. Beams code from 0.4 keeps working unchanged.
+Then `npx expo prebuild --clean`. See [Setup](setup.md).
 
-## Steps
+## 3. API mapping
+
+| b8ne / forks | expo-pusher-push-notifications 0.5 |
+|---|---|
+| `import RNPusherPushNotifications from 'react-native-pusher-push-notifications'` | `import { Interests, Users, on } from 'expo-pusher-push-notifications'` |
+| `setInstanceId(id)` (+ `setAppKey` on some forks) | `await Interests.start(id)` or `await start({ instanceId: id })` |
+| `subscribe(interest, onError, onSuccess)` | `await Interests.subscribe(interest)` (try/catch) |
+| `unsubscribe(interest, onError, onSuccess)` | `await Interests.unsubscribe(interest)` |
+| `setSubscriptions(arr)` (iOS only) | `await Interests.set(arr)` (both platforms) |
+| `getSubscriptions(cb)` (Android only) | `const list = await Interests.get()` |
+| `setOnSubscriptionsChangedListener(cb)` | `on('subscriptionsChanged', cb)` |
+| `setUserId(userId, token, onError, onSuccess)` | `await Users.start(id)` then `await Users.login(userId, token)` — or pass `{ url, headers }` token provider instead of a static token |
+| `clearAllState()` | `await Users.logout()` / `Interests.reset()` / `clearAllState()` |
+| `on('registered', cb)` | `const sub = on('registered', cb)`; later `sub.remove()` |
+| `on('notification', cb)` with iOS `appState` | Same; `appState` on both platforms; also `opened` and `error` events |
+| Android launch-intent delivery | `await getInitialNotification()` + `on('opened', …)` |
+| `aps.data.incrementBadge` | Supported both platforms + `setBadgeCount` / `incrementBadgeCount` |
+| _(none)_ | Sounds, Android channels, local/scheduled notifications, raw device tokens (`DeviceToken`) |
 
-Remove the old package, its Carthage framework, and any `RNPusherPushNotifications` code in your AppDelegate and MainApplication. Autolinking, the config plugin, and the Expo AppDelegate subscriber replace them.
+### Before / after
+
+```ts
+// before
+RNPusherPushNotifications.setInstanceId(INSTANCE_ID);
+RNPusherPushNotifications.on('registered', () => {
+  RNPusherPushNotifications.subscribe('news', err => console.warn(err), () => console.log('ok'));
+});
+RNPusherPushNotifications.on('notification', n => handle(n));
+
+// after
+import { Interests, on } from 'expo-pusher-push-notifications';
+const sub = on('notification', n => handle(n));
+await Interests.start(INSTANCE_ID);   // no need to wait for 'registered'
+await Interests.subscribe('news');
+// cleanup: sub.remove();
+```
+
+```ts
+// users — before
+RNPusherPushNotifications.setUserId(userId, beamsToken, onError, onSuccess);
+// after
+await Users.start(INSTANCE_ID);
+await Users.login(userId, { url: 'https://api.example.com/beams-token', headers: { Authorization: `Bearer ${jwt}` } });
+// sign-out
+await Users.logout();
+```
+
+## 4. Gotchas
+
+- Notification payload shape may differ slightly; log one and update field access (`n.title`, `n.body`, `n.data`).
+- Don't run alongside `expo-notifications` or `@react-native-firebase/messaging` (this module owns the delegate/FCM service).
+- `start()` requests notification permission by default; pass `{ requestPermission: false }` to control it yourself.
+- Calling Beams APIs before `start()` throws.
+
+## Coming from 0.4
 
+0.5 brings back device-token support (`DeviceToken`, `registerForDeviceToken`, `getDevicePushToken`, `deleteDevicePushToken`, `mode: 'device'`). Beams code from 0.4 is unchanged.
 
 ---
 [← Back to README](../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-pusher-push-notifications",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Push notifications for Expo: Pusher Beams (interests / users) or raw FCM/APNs device tokens (no EAS needed), with custom sounds, channels, badges and local notifications",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -66,6 +66,7 @@
   },
   "files": [
     "docs",
+    "skills",
     "build",
     "plugin/build",
     "ios",

package/skills/migrate-from-b8ne/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: migrate-from-b8ne
+description: Migrate a React Native / Expo app from react-native-pusher-push-notifications (b8ne, ZeptInc, pusher-community forks) to expo-pusher-push-notifications 0.5.x. Use when an app imports react-native-pusher-push-notifications or has RNPusherPushNotifications native code.
+---
+
+# Migrate from react-native-pusher-push-notifications
+
+Not a drop-in swap: callbacks become promises, init becomes `start()`, native code becomes an Expo config plugin. Full reference: `docs/migrating.md` in this package.
+
+## Step 1 — Inventory (read-only)
+
+```sh
+rg -n "react-native-pusher-push-notifications|RNPusherPushNotifications" --glob '!node_modules'
+rg -n "setInstanceId|setAppKey|setUserId|setSubscriptions|getSubscriptions|setOnSubscriptionsChangedListener|clearAllState" --glob '!node_modules' -t js -t ts
+rg -n "PushNotifications|RNPusher|incrementBadge" ios android --glob '!Pods'
+```
+
+Record: instance ID source, interests used, whether users/`setUserId` is used, notification handler code, native files touched.
+
+## Step 2 — Dependencies
+
+```sh
+npm uninstall react-native-pusher-push-notifications   # or yarn/pnpm equivalent
+npx expo install expo-pusher-push-notifications
+```
+Bare RN without Expo modules: `npx install-expo-modules@latest` first. Expo Go is not supported (needs dev build).
+
+## Step 3 — Native config
+
+1. Add to `app.json`/`app.config.*` plugins: `["expo-pusher-push-notifications", { "instanceId": "<BEAMS_INSTANCE_ID>" }]`.
+2. Ensure `expo.android.googleServicesFile` points at `google-services.json`.
+3. If the project has committed `ios/`/`android/` (bare): delete `RNPusherPushNotifications` imports and calls in AppDelegate (`setDeviceToken`, `handleNotification`, didRegister/didReceive forwarding), Carthage/Pod entries for `PushNotifications` added manually, and Android `MainApplication`/manifest additions from the old README. Keep unrelated code.
+4. Run `npx expo prebuild --clean` (managed) or `cd ios && pod install` (bare).
+
+## Step 4 — JS rewrites
+
+| Find | Replace with |
+|---|---|
+| `import X from 'react-native-pusher-push-notifications'` | `import { Interests, Users, on, getInitialNotification } from 'expo-pusher-push-notifications'` |
+| `X.setInstanceId(ID)` | `await Interests.start(ID)` (or `Users.start(ID)` if users are used) |
+| `X.subscribe(i, onErr, onOk)` | `try { await Interests.subscribe(i); onOk?.() } catch (e) { onErr?.(e) }` |
+| `X.unsubscribe(i, onErr, onOk)` | same pattern with `Interests.unsubscribe` |
+| `X.setSubscriptions(arr)` | `await Interests.set(arr)` |
+| `X.getSubscriptions(cb)` | `cb(await Interests.get())` |
+| `X.setOnSubscriptionsChangedListener(cb)` | `on('subscriptionsChanged', cb)` |
+| `X.setUserId(uid, token, onErr, onOk)` | `await Users.login(uid, token)` (prefer `{ url, headers }` token provider) |
+| `X.clearAllState()` | `await Users.logout()` |
+| `X.on('registered'\|'notification', cb)` | `const sub = on(...)`; remove `sub` on unmount |
+
+Rules:
+- Make enclosing functions `async` or use `.then/.catch`. Never leave a floating promise without error handling.
+- Remove logic that waits for `'registered'` before subscribing; `start()` resolves when ready.
+- Call `start` once (app root), before any subscribe/login.
+- Android cold-start taps: add `getInitialNotification()` + `on('opened', ...)`.
+- If `expo-notifications` or `@react-native-firebase/messaging` is installed for push, flag it to the user — conflict.
+
+## Step 5 — Verify
+
+```sh
+rg -n "react-native-pusher-push-notifications|RNPusherPushNotifications" --glob '!node_modules'   # expect no hits
+npx tsc --noEmit
+npx expo run:ios && npx expo run:android
+```
+Send a test push to an interest from the Beams dashboard on a real device; check foreground, background, and cold-start tap.
+
+## Checklist
+- [ ] Old package + native code removed
+- [ ] Plugin added with instanceId; googleServicesFile set; prebuild run
+- [ ] All callbacks converted to promises with error handling
+- [ ] Listeners return subscriptions that are removed
+- [ ] Users flow: login after sign-in, logout on sign-out
+- [ ] Typecheck passes; test push received on both platforms
+- [ ] Summarize changes and any manual console steps (APNs key, Firebase) for the user