expo-pusher-push-notifications 0.5.0 → 0.5.2

package/README.md

@@ -7,22 +7,48 @@ Push notifications for Expo and React Native. Two ways to use it:
 
 Both get custom sounds, Android channels, badges, and local notifications.
 
+## Prerequisites
+
+Do these before installing. Which ones you need depends on your path.
+
+**Android (all paths)**
+
+1. Create a project in the [Firebase console](https://console.firebase.google.com) and add an Android app with your `android.package`.
+2. Download `google-services.json` into your project and set `"android": { "googleServicesFile": "./google-services.json" }` in `app.json`.
+3. Beams path only: in Firebase → Project settings → Service accounts, generate a private key (JSON). You'll upload it to Beams.
+
+**Apple (all paths)**
+
+1. In your Apple Developer account, enable the **Push Notifications** capability on your App ID (`ios.bundleIdentifier`).
+2. Create an **APNs auth key (.p8)** under Keys (note the Key ID and Team ID). A .p12 certificate works too, but the key is simpler and doesn't expire.
+3. Set `apsEnvironment` in the plugin: `development` for dev builds, `production` for TestFlight / App Store. The plugin writes the `aps-environment` entitlement for you.
+
+**Beams (Interests / Users paths only)**
+
+Create a Beams instance in the [Pusher dashboard](https://dashboard.pusher.com/beams), upload your APNs key and FCM service account JSON, and copy the instance ID. Skip this entirely for the device-token path.
+
+Full details in [Setup](docs/setup.md).
+
+## Install
+
 ```sh
 npx expo install expo-pusher-push-notifications
 ```
 
-Needs Expo SDK 58+ and a development build (Expo Go can't load native modules).
+Needs Expo SDK 58+ and a development build (Expo Go can't load native modules). Run `npx expo prebuild` after adding the plugin.
+
+## Getting started
 
-## Quick start
+Pick the path that matches how you send pushes. You can combine Interests and Users; DeviceToken is for when you don't use Beams at all.
 
-Add the config plugin to `app.json`:
+### Interests (Beams topics)
+
+`app.json`:
 
 ```json
 ["expo-pusher-push-notifications", { "instanceId": "YOUR_BEAMS_INSTANCE_ID" }]
 ```
 
-Then in your app:
-
 ```ts
 import { Interests } from 'expo-pusher-push-notifications';
 
@@ -30,7 +56,43 @@ await Interests.start('YOUR_BEAMS_INSTANCE_ID');
 await Interests.subscribe('news');
 ```
 
-That device now gets pushes sent to `news`. Full console steps (APNs, Firebase, Beams) are in [Setup](docs/setup.md).
+That device now gets pushes sent to `news`.
+
+### Users (Beams, bind to your signed-in user)
+
+`app.json`:
+
+```json
+["expo-pusher-push-notifications", { "instanceId": "YOUR_BEAMS_INSTANCE_ID", "mode": "users" }]
+```
+
+```ts
+import { Users } from 'expo-pusher-push-notifications';
+
+await Users.start('YOUR_BEAMS_INSTANCE_ID');
+// after your own sign-in; url = your Beams token provider
+await Users.login('user-123', {
+  url: 'YOUR_BEAMS_TOKEN_URL',
+  headers: { Authorization: `Bearer ${sessionToken}` },
+});
+```
+
+That user now gets pushes on every device they're signed in on.
+
+### DeviceToken (no Beams)
+
+`app.json` — no `instanceId`:
+
+```json
+["expo-pusher-push-notifications", { "mode": "device" }]
+```
+
+```ts
+import { DeviceToken } from 'expo-pusher-push-notifications';
+
+const { type, token } = await DeviceToken.start(); // type: 'fcm' | 'apns'
+// send token to your backend, which pushes via FCM / APNs directly
+```
 
 ## Path 1: Pusher Beams
 
@@ -103,6 +165,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/direct.md

@@ -1,5 +1,7 @@
 # Device token (raw FCM / APNs, no Beams)
 
+
+> Before you start: finish the [Prerequisites](setup.md#prerequisites) (Firebase + APNs; no Beams instance needed).
 **Use this when** your app has its own push path: your backend (or another provider) sends to FCM and APNs directly.
 No Beams instance needed. You get the raw native token and do what you want with it.
 

package/docs/interests.md

@@ -1,5 +1,7 @@
 # Interests (topics)
 
+
+> Before you start: finish the [Prerequisites](setup.md#prerequisites) (Firebase + APNs, plus a Beams instance).
 Use interests when many devices should get the same push. Think topics: `news`, `order-42`, `team-7`.
 
 ## Client

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/docs/setup.md

@@ -1,5 +1,27 @@
 # Setup
 
+## Prerequisites
+
+Set these up first. Android and Apple steps apply to every path; the Beams step only to Interests / Users.
+
+### Android: Firebase / FCM
+
+1. Create a project in the [Firebase console](https://console.firebase.google.com).
+2. Add an Android app whose package name matches `android.package` in `app.json`.
+3. Download `google-services.json`, put it in your project root, and set `"android": { "googleServicesFile": "./google-services.json" }`.
+4. **Beams only:** Project settings → Service accounts → *Generate new private key*. Keep the JSON for the Beams dashboard.
+
+### Apple: APNs
+
+1. In [Apple Developer → Identifiers](https://developer.apple.com/account/resources/identifiers/list), open your App ID (`ios.bundleIdentifier`) and enable **Push Notifications**.
+2. Under Keys, create a key with **Apple Push Notifications service (APNs)** enabled. Download the `.p8` and note the Key ID and your Team ID. (A `.p12` APNs certificate also works, but certificates expire yearly.)
+3. Choose `apsEnvironment` in the plugin config: `development` for dev builds, `production` for TestFlight and the App Store. The plugin writes the `aps-environment` entitlement and the `remote-notification` background mode — you don't edit Xcode by hand.
+4. Test on a real device; the iOS simulator doesn't get APNs tokens reliably.
+
+### Beams (Interests / Users only)
+
+Create an instance in the [Pusher dashboard](https://dashboard.pusher.com/beams), upload the APNs key (with Key ID / Team ID) and the FCM service account JSON, and copy the instance ID. For the device-token path, skip this — your backend talks to FCM / APNs with those same credentials.
+
 ## Install
 
 ```sh
@@ -31,6 +53,8 @@ npx expo install expo-pusher-push-notifications
 }
 ```
 
+Leave out `instanceId` (and set `"mode": "device"`) if you use the device-token path.
+
 Then run `npx expo prebuild` and build a development build. Expo Go cannot load this native module.
 
 ### Plugin options
@@ -47,11 +71,15 @@ Then run `npx expo prebuild` and build a development build. Expo Go cannot load
 
 The plugin also adds the `remote-notification` background mode on iOS. On Android, the library manifest declares one FCM service (it extends the Beams `MessagingService`), the `POST_NOTIFICATIONS` permission, and a receiver for scheduled local notifications.
 
-## Console setup
+## Start, per path
 
-1. **iOS:** enable the Push Notifications capability. The plugin sets the entitlement. Create an APNs auth key (.p8).
-2. **Android:** create a Firebase project, download `google-services.json`, and point `android.googleServicesFile` at it.
-3. **Beams path only:** create a Beams instance in the [Pusher dashboard](https://dashboard.pusher.com/beams), then upload your APNs key and your FCM service account to it.
+Pick one (Interests and Users can be combined).
+
+| Path | Plugin config | First call |
+|---|---|---|
+| Interests | `instanceId` | `Interests.start(instanceId)` then `Interests.subscribe('news')` — see [Interests](interests.md) |
+| Users | `instanceId`, `mode: "users"` | `Users.start(instanceId)` then `Users.login(userId, tokenProvider)` after sign-in — see [Users](users.md) |
+| DeviceToken | `mode: "device"`, no `instanceId` | `DeviceToken.start()` → send `token` to your backend — see [Device token](direct.md) |
 
 ## Permissions
 

package/docs/users.md

@@ -1,5 +1,7 @@
 # Bind a device to a user
 
+
+> Before you start: finish the [Prerequisites](setup.md#prerequisites) (Firebase + APNs, plus a Beams instance).
 Bind the device to the signed-in user so pushes for that user reach every device they're signed in on. Call `Users.login` after your own sign-in, and `Users.logout` on sign-out.
 
 ## In the app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-pusher-push-notifications",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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