@usergist/feedback-react-native 0.1.1 → 0.2.0-beta.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0-beta.0
+
+- Add Expo config plugin, iOS extension/EAS setup, and an optional notification adapter.
+- Preserve existing Expo notification ownership and shared provider tokens.
+- Add scoped native delivery-receipt retries, Expo onboarding, demo and consumer checks.
+- Keep logout and consent changes from accepting stale request responses or disabling a newer push session.
+- Expo support remains prerelease until signed-device acceptance is complete.
+
 All notable changes to `@usergist/feedback-react-native` are documented here.
 Releases use [Semantic Versioning](https://semver.org/).
 

package/EXPO-ACCEPTANCE.md

@@ -0,0 +1,57 @@
+# Expo release evidence
+
+Status: implementation under validation; stable release is blocked.
+
+Record the exact npm archive SHA256, source commit, Expo/React Native versions,
+build profile, and app identifiers alongside each result. Never record tokens
+or provider private keys. A mocked provider or generated Firebase fixture does
+not count as a live push test.
+
+## Automated gates
+
+- Packed archive resolves every existing export, `/expo`, the Node config
+  plugin, Expo subscriber, Kotlin dispatcher, and notification extension files.
+- Expo 56.0.21 and 57.0.20: automatic and expo-notifications mode, iOS and
+  Android, with the New Architecture and repeated non-destructive prebuild.
+- Existing React Native typecheck, unit tests, codegen/package check, and builds.
+- Dashboard/API validation, Expo platform mapping, AI snippets, and onboarding.
+
+## Signed-device gates (pending)
+
+- Physical iPhone and Android: anonymous startup, identify, logout/account switch,
+  offline relaunch and eventual synchronization; no cross-user data or token binding.
+- All reference demo feedback types, surveys, in-app messages, request board,
+  comments/votes/follows, targeting, branding, and analytics.
+- UserGist push: foreground/background/terminated launch; token refresh, permission
+  denial and later recovery, channels, badge behavior, images, actions, JSON actions,
+  deep links, silent reachability and delivered/open evidence.
+- Coexistence: interleave unrelated Expo and UserGist messages, including cold
+  starts; one presentation and handler invocation per event/action. Disable
+  UserGist and verify unrelated notifications still arrive.
+- Turn off networking while a native receipt is recorded; restore it and verify
+  the original delivery timestamp is acknowledged once. Logout before retry and
+  verify that old work is never attributed to the new account.
+- iOS development APNs signing and a distribution-signed build, including
+  extension embedding, provisioning, App Group persistence and rich delivery.
+
+## Promotion
+
+Publish a prerelease with npm tag `next` for consumer acceptance after package
+and native build gates pass. Keep stable `latest` unchanged until all signed
+device gates above have evidence. Do not describe Expo support as production
+validated while this document remains pending.
+
+The public release workflow enforces this through
+`tools/expo/check-release-evidence.mjs`. Supply the repository variable
+`USERGIST_EXPO_RELEASE_EVIDENCE` as JSON with `version`, `archiveSha256`,
+`sourceCommit`, `nativeBuildRunId`, and arrays `nativeBuilds`, `regressions`, `physicalDevices`.
+Each entry has `name`, `passed: true`, and a durable HTTPS `evidenceUrl` to
+the corresponding build or device report. The script lists the exact required
+names. Prereleases require package, prebuild, ordinary React Native regression,
+and all eight Expo native combinations; stable additionally requires signed
+physical-device evidence. A missing variable blocks publication. CI builds one archive and passes that file
+to every consumer; the publish job downloads it from `nativeBuildRunId` instead
+of rebuilding it. The release tag must point to that run’s source commit.
+
+For stable promotion, validate the final stable archive too: changing a
+prerelease version changes the package bytes and invalidates its earlier hash.

package/EXPO.md

@@ -0,0 +1,103 @@
+# Expo integration (0.2 prerelease)
+
+Expo uses the same `UserGist`, `Push`, and `UserGistProvider` as React Native.
+The supported build targets are Expo 56 and 57 on iOS and Android, with the New
+Architecture enabled. Use a development client or production binary. Expo Go
+cannot provide the native bridge or durable secure storage. Browser targets
+use `@usergist/feedback-web` separately.
+
+## Base setup
+
+```sh
+npx expo install @usergist/feedback-react-native \
+  @react-native-async-storage/async-storage react-native-safe-area-context
+```
+
+Add `"@usergist/feedback-react-native"` to `expo.plugins` in app.json or
+app.config.js. Mount `UserGistProvider` once around the existing application:
+in Expo Router's `app/_layout.tsx` wrap `Slot`/`Stack`; otherwise wrap App's
+existing navigation. Call `initAsync` once with the public write key.
+
+Anonymous users work without login. For identified users, obtain a scoped
+subject token from your authenticated backend and call `identifyAsync`.
+Never put a server API token in an `EXPO_PUBLIC_` variable. Connect `setConsent`
+to the host's consent decisions, and await `reset()` before changing accounts.
+The consent screen in our demo is a test harness, not a customer requirement.
+
+## Push configuration
+
+```js
+plugins: [
+  ['@usergist/feedback-react-native', {
+    push: {
+      mode: 'automatic',
+      ios: { apsEnvironment: 'development' },
+      // android: { notificationIcon: './assets/notification-icon.png',
+      //            notificationColor: '#3366FF' },
+    },
+  }],
+]
+```
+
+Set `ios.bundleIdentifier`, `android.package`, and `android.googleServicesFile`.
+The Google JSON is Firebase's client configuration for that package ID, not
+a service-account private key. Upload APNs/FCM sending credentials to UserGist.
+Never include the .p8 or service-account key in an Expo config or application.
+
+`apsEnvironment` must match signing: development provisioning uses
+`development`; TestFlight/App Store uses `production`. This is independent of
+the UserGist data environment. Runtime registration reads this plugin setting;
+call `enablePush()` without an environment override to use it.
+
+The plugin generates the notification service extension and App Group needed
+for rich media and native iOS delivery receipts. Defaults are
+`UserGistNotificationServiceExtension`, `<bundleId>.UserGistNotificationServiceExtension`,
+and `group.<bundleId>.usergist`. Override these with `extensionTargetName`,
+`extensionBundleIdentifier`, and `appGroupIdentifier` under `push.ios`.
+EAS receives the extension metadata before provisioning. Verify the app and
+extension profiles include the same App Group.
+
+Omitting `push` keeps notification acquisition disabled. Initialization and
+configuration never request permission. After the user opts in and consent
+synchronizes, call `enablePush` from a user action. Check `result.granted` and
+`result.error`; `native_module_unavailable` or `push_not_configured` describes
+build configuration, not an OS denial. Restore opt-in only after checking
+current OS permission. `disablePush()` disables UserGist without removing an
+Expo app's shared APNs/FCM registration.
+
+## Existing expo-notifications
+
+Keep its existing plugin and handlers; place its plugin before UserGist's and
+select `push.mode: 'expo-notifications'`. Configure the adapter before init:
+
+```ts
+import * as Notifications from 'expo-notifications'
+import { configureExpoNotifications } from '@usergist/feedback-react-native/expo'
+const dispose = configureExpoNotifications(Notifications)
+```
+
+Call once in the app bootstrap, not on every screen mount. Cleanup removes
+the adapter listeners without modifying host notification handlers. The helper
+does not request permissions, grant consent, or register a user on import.
+UserGist uses native device tokens from `getDevicePushTokenAsync`, never
+ExpoPushToken values. The Android dispatcher routes UserGist payloads to our
+native renderer and other messages to Expo. On iOS, Expo retains foreground
+presentation policy and response handling. Your existing Router/deep-link
+handlers remain responsible for navigation.
+
+## Rebuilds and conflicts
+
+Native/plugin changes require rebuilding with `npx expo run:ios`,
+`npx expo run:android`, or EAS Build. EAS Update cannot add a native module.
+For manually running prebuild against existing directories, Expo 57 requires
+`--no-clean` to preserve those directories; Expo 56 preserves them by default.
+
+The plugin does not overwrite a foreign extension target or custom FCM service.
+If one exists, preserve it and integrate the existing host-forwarded `Push`
+API and extension base class following the React Native README. Do not enable
+two FCM services. Automatic composition is supported for expo-notifications;
+other SDKs require an explicit integration. Change ownership modes in a fresh
+native fixture, or review the existing host configuration before migrating.
+
+Use the Expo demo and `EXPO-ACCEPTANCE.md` for acceptance. Building or receiving
+a JavaScript callback alone is not physical-device push validation.

package/README.md

@@ -2,8 +2,16 @@
 
 Production userGist SDK for React Native and the behavioral reference for the
 iOS, Android, and Flutter packages. Use the dashboard's SDK setup flow to
-verify authentication and ingestion; push releases additionally require APNs
-or FCM configuration and physical-device validation.
+verify authentication and ingestion. The userGist APNs and FCM paths have
+passed end-to-end physical-device validation; each host app still needs its own
+provider credentials, identifiers, native callback setup, and signed-device
+acceptance test.
+
+## Expo
+
+Expo 56/57 development and production build integration is being validated for
+0.2. Use the same package with its config plugin; see [EXPO.md](EXPO.md).
+Expo Go cannot load the native bridge. See [release gates](EXPO-ACCEPTANCE.md).
 
 ## Install
 

package/UserGistFeedback.podspec

@@ -23,7 +23,10 @@ Pod::Spec.new do |s|
   # The RN bridge module: RCTBridgeModule, RCTEventEmitter, Swift impl.
   # Pulls in React-Core because it imports <React/...> headers.
   s.subspec 'Core' do |core|
-    core.source_files = 'ios/*.{h,m,mm,swift}'
+    core.source_files = 'ios/*.{h,m,mm,swift}', 'ios/Shared/*.swift'
+    # This shim is internal to the Obj-C implementation. Exporting its React
+    # imports through our Swift umbrella can hide React types in host modules.
+    core.private_header_files = 'ios/UserGistPush.h'
     core.frameworks   = 'UIKit', 'UserNotifications', 'Security'
     core.dependency 'React-Core'
   end

package/UserGistFeedbackExtension.podspec

@@ -18,6 +18,6 @@ Pod::Spec.new do |s|
   s.source           = { :git => 'https://github.com/Future-Picnic/usergist-js.git', :tag => "v#{s.version}" }
   s.requires_arc     = true
   s.swift_version    = '5.7'
-  s.source_files     = 'ios/Extension/*.swift'
+  s.source_files     = 'ios/Extension/*.swift', 'ios/Shared/*.swift'
   s.frameworks       = 'UserNotifications'
 end

package/android/build.gradle

@@ -85,7 +85,9 @@ dependencies {
   // plugin in their app/build.gradle (Google's hard requirement for FCM).
   // Use a floor version that's broadly compatible with current Firebase BoM
   // ranges; consumer's BoM (if any) will pick the actual version.
-  implementation "com.google.firebase:firebase-messaging:23.4.1"
+  // The public native dispatcher accepts RemoteMessage, so host adapters need
+  // Firebase on their compile classpath as well as at runtime.
+  api "com.google.firebase:firebase-messaging:23.4.1"
 
   implementation "androidx.core:core-ktx:1.12.0"
   implementation "androidx.security:security-crypto:1.1.0-alpha06"

package/android/src/main/AndroidManifest.xml

@@ -9,6 +9,7 @@
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
     <application>
+        <receiver android:name="studio.usergist.feedback.UserGistNotificationDismissReceiver" android:exported="false" />
         <!-- Library-supplied FirebaseMessagingService. Hosts that already own
              FCM delivery must set userGistFirebaseServiceEnabled=false and
              forward tokens/messages through the public Push API. -->

package/android/src/main/java/studio/usergist/feedback/UserGistFirebaseMessagingService.kt

@@ -31,15 +31,30 @@ import org.json.JSONArray
  */
 class UserGistFirebaseMessagingService : FirebaseMessagingService() {
 
-  override fun onNewToken(token: String) {
-    super.onNewToken(token)
-    UserGistPushEventBus.emitToken(token)
+  override fun onNewToken(token: String) = handleToken(token)
+  override fun onMessageReceived(message: RemoteMessage) = handleMessage(this, message)
+  companion object {
+    @JvmStatic fun handleToken(token: String) = UserGistPushEventBus.emitToken(token)
+    @JvmStatic fun handleMessage(context: Context, message: RemoteMessage) {
+      if (!UserGistPushState.enabled(context)) return
+      // FCM already invokes this on its worker thread. Keep the service alive
+      // until presentation completes instead of leaving detached work behind.
+      UserGistMessageHandler(context.applicationContext).receive(message)
+    }
   }
+}
 
-  override fun onMessageReceived(remoteMessage: RemoteMessage) {
-    super.onMessageReceived(remoteMessage)
-
-    val payload = normalize(remoteMessage)
+private class UserGistMessageHandler(context: Context) : android.content.ContextWrapper(context) {
+  fun receive(remoteMessage: RemoteMessage) {
+    val recipient = remoteMessage.data["usergist_anonymous_id"] ?: UserGistPushState.anonymousId(this)
+    if (!UserGistPushState.accepts(this, recipient)) return
+    if (remoteMessage.data["usergist_silent"] == "1") {
+      UserGistPushState.receipt(this, "silent-ack", remoteMessage.data["usergist_ping_id"] ?: "")
+      return
+    }
+    if (!remoteMessage.data.containsKey("usergist_campaign_id")) return
+    UserGistPushState.receipt(this, "delivered", remoteMessage.data["usergist_delivery_id"] ?: "")
+    val payload = normalize(remoteMessage, recipient)
     UserGistPushEventBus.emitNotificationReceived(payload)
 
     // Surface a system notification when the user-visible content is set.
@@ -52,7 +67,7 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
       postSystemNotification(
         title = title,
         body = body,
-        data = remoteMessage.data
+        data = remoteMessage.data + ("usergist_anonymous_id" to recipient)
       )
     }
   }
@@ -74,17 +89,22 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
     val pendingFlags = PendingIntent.FLAG_UPDATE_CURRENT or
       (if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) PendingIntent.FLAG_IMMUTABLE else 0)
     val contentIntent = launchIntent?.let {
-      PendingIntent.getActivity(this, 0, it, pendingFlags)
+      PendingIntent.getActivity(this, (data["usergist_delivery_id"] ?: data.toString()).hashCode(), it, pendingFlags)
     }
 
-    val notifId = (System.currentTimeMillis() % Int.MAX_VALUE).toInt()
+    val notifId = (data["usergist_delivery_id"] ?: data.toString()).hashCode()
     val builder = NotificationCompat.Builder(this, channelId)
-      .setSmallIcon(applicationInfo.icon.takeIf { it != 0 } ?: android.R.drawable.ic_dialog_info)
+      .setSmallIcon(packageManager.getApplicationInfo(packageName, android.content.pm.PackageManager.GET_META_DATA).metaData?.getInt("UserGistNotificationIcon", 0)?.takeIf { it != 0 } ?: android.R.drawable.ic_dialog_info)
       .setContentTitle(title)
       .setContentText(body)
       .setAutoCancel(true)
       .setContentIntent(contentIntent)
       .setPriority(NotificationCompat.PRIORITY_DEFAULT)
+    data["usergist_badge"]?.let { raw ->
+      val badges = getSharedPreferences("usergist_push_badges", Context.MODE_PRIVATE)
+      val count = if (raw == "+1") badges.getInt("count", 0) + 1 else raw.toIntOrNull()
+      if (count != null && count >= 0) { builder.setNumber(count); badges.edit().putInt("count", count).apply() }
+    }
 
     val rawActions = data["usergist_actions"]
     if (!rawActions.isNullOrBlank() && launchIntent != null) {
@@ -107,8 +127,53 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
       }
     }
 
+    val color = packageManager.getApplicationInfo(packageName, android.content.pm.PackageManager.GET_META_DATA).metaData?.get("UserGistNotificationColor")
+    when (color) {
+      is Int -> builder.setColor(color)
+      is String -> runCatching { builder.setColor(android.graphics.Color.parseColor(color)) }
+    }
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O && data["usergist_sound"] != "none") {
+      val sound = data["usergist_sound"]
+      val custom = sound?.takeIf { it != "default" }?.let { resources.getIdentifier(it.substringBeforeLast('.'), "raw", packageName) } ?: 0
+      builder.setSound(if (custom != 0) android.net.Uri.parse("android.resource://$packageName/$custom") else android.media.RingtoneManager.getDefaultUri(android.media.RingtoneManager.TYPE_NOTIFICATION))
+    }
+    data["usergist_image_url"]?.let { raw ->
+      var connection: java.net.HttpURLConnection? = null
+      try {
+        val url = java.net.URL(raw)
+        if (url.protocol == "https") {
+          connection = url.openConnection() as java.net.HttpURLConnection
+          connection.connectTimeout = 4000; connection.readTimeout = 4000
+          connection.instanceFollowRedirects = false
+          if (connection.responseCode in 200..299) {
+            val bytes = connection.inputStream.use { stream ->
+              val out = java.io.ByteArrayOutputStream(); val buffer = ByteArray(8192)
+              while (out.size() <= 5 * 1024 * 1024) { val count = stream.read(buffer); if (count < 0) break; out.write(buffer, 0, count) }
+              out.toByteArray()
+            }
+            if (bytes.size <= 5 * 1024 * 1024) {
+              val bounds = android.graphics.BitmapFactory.Options().apply { inJustDecodeBounds = true }
+              android.graphics.BitmapFactory.decodeByteArray(bytes, 0, bytes.size, bounds)
+              val decode = android.graphics.BitmapFactory.Options().apply { inSampleSize = (maxOf(bounds.outWidth, bounds.outHeight) / 1024).coerceAtLeast(1) }
+              android.graphics.BitmapFactory.decodeByteArray(bytes, 0, bytes.size, decode)?.let { builder.setStyle(NotificationCompat.BigPictureStyle().bigPicture(it)) }
+            }
+          }
+        }
+      } catch (_: Exception) { /* Text notification still displays. */ }
+      finally { connection?.disconnect() }
+    }
+    val dismiss = Intent(this, UserGistNotificationDismissReceiver::class.java).apply {
+      data.forEach { (k, v) -> putExtra(k, v) }
+    }
+    builder.setDeleteIntent(PendingIntent.getBroadcast(this, notifId, dismiss, pendingFlags))
     val nm = NotificationManagerCompat.from(this)
+    if (!UserGistPushState.accepts(this, data["usergist_anonymous_id"]) || !nm.areNotificationsEnabled()) return
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && nm.getNotificationChannel(channelId)?.importance == NotificationManager.IMPORTANCE_NONE) return
     nm.notify(notifId, builder.build())
+    UserGistPushState.receipt(this, "displayed", data["usergist_delivery_id"] ?: "")
+    val displayed = Arguments.createMap()
+    displayed.putMap("data", Arguments.createMap().apply { data.forEach { (k, v) -> putString(k, v) } })
+    UserGistPushEventBus.emitNotificationDisplayed(displayed)
   }
 
   private fun ensureChannel(ctx: Context): String {
@@ -133,7 +198,7 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
     return if (nm.getNotificationChannel(requested) != null) requested else ensureChannel(ctx)
   }
 
-  private fun normalize(msg: RemoteMessage): WritableMap {
+  private fun normalize(msg: RemoteMessage, recipient: String): WritableMap {
     val out = Arguments.createMap()
     msg.notification?.title?.let { out.putString("title", it) }
     msg.notification?.body?.let { out.putString("body", it) }
@@ -141,6 +206,7 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
     for ((k, v) in msg.data) {
       data.putString(k, v)
     }
+    data.putString("usergist_anonymous_id", recipient)
     out.putMap("data", data)
     val deliveryId = msg.data["delivery_id"] ?: msg.data["usergist_delivery_id"]
     if (deliveryId != null) out.putString("deliveryId", deliveryId)

package/android/src/main/java/studio/usergist/feedback/UserGistNotificationDismissReceiver.kt

@@ -0,0 +1,17 @@
+package studio.usergist.feedback
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+
+class UserGistNotificationDismissReceiver : BroadcastReceiver() {
+  override fun onReceive(context: Context, intent: Intent) {
+    if (!UserGistPushState.accepts(context, intent.getStringExtra("usergist_anonymous_id"))) return
+    UserGistPushState.receipt(context, "dismissed", intent.getStringExtra("usergist_delivery_id") ?: "")
+    val body = com.facebook.react.bridge.Arguments.createMap()
+    body.putMap("data", com.facebook.react.bridge.Arguments.createMap().apply {
+      intent.extras?.keySet()?.forEach { key -> intent.getStringExtra(key)?.let { putString(key, it) } }
+    })
+    UserGistPushEventBus.emitNotificationDismissed(body)
+  }
+}

package/android/src/main/java/studio/usergist/feedback/UserGistPushModule.kt

@@ -49,6 +49,12 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
   }
 
   override fun getName(): String = NAME
+  override fun invalidate() {
+    reactApplicationContext.removeLifecycleEventListener(this)
+    reactApplicationContext.removeActivityEventListener(this)
+    UserGistPushEventBus.detach(reactApplicationContext)
+    super.invalidate()
+  }
 
   private val securePreferences by lazy {
     val masterKey = MasterKey.Builder(reactApplicationContext)
@@ -64,7 +70,8 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
   }
 
   override fun onHostResume() {
-    currentActivity?.intent?.let { consumeNotificationIntent(it) }
+    UserGistPushState.retry(reactApplicationContext)
+    reactApplicationContext.currentActivity?.intent?.let { consumeNotificationIntent(it) }
   }
 
   override fun onHostPause() = Unit
@@ -77,6 +84,7 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
 
   private fun consumeNotificationIntent(intent: Intent) {
     val extras = intent.extras ?: return
+    if (!UserGistPushState.accepts(reactApplicationContext, extras.getString("usergist_anonymous_id"))) return
     val keys = extras.keySet().filter { it.startsWith("usergist_") }
     if (keys.isEmpty()) return
     val body = Arguments.createMap()
@@ -99,8 +107,23 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
 
   // MARK: - Exported methods
 
+  @ReactMethod
+  fun getPushConfiguration(promise: Promise) {
+    promise.resolve(Arguments.createMap().apply { putString("mode", UserGistPushState.mode(reactApplicationContext)) })
+  }
+
+  @ReactMethod
+  fun configurePushState(state: ReadableMap, promise: Promise) {
+    runCatching { UserGistPushState.configure(reactApplicationContext, org.json.JSONObject(state.toHashMap())) }
+      .onSuccess { promise.resolve(null) }.onFailure { promise.reject("push_state_failed", it) }
+  }
+
   @ReactMethod
   fun enablePush(_options: ReadableMap?, promise: Promise) {
+    if (UserGistPushState.mode(reactApplicationContext) == "disabled") {
+      promise.resolve(buildResult(false, "not_determined", null, "push_not_configured"))
+      return
+    }
     // Android < 13: notification permission is install-time, no runtime
     // prompt. We can short-circuit straight to the token fetch.
     if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
@@ -112,7 +135,7 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
       fetchTokenAndResolve(promise, status = "authorized")
       return
     }
-    val activity = currentActivity
+    val activity = reactApplicationContext.currentActivity
     if (activity == null) {
       // No activity: can't ask for permission. Resolve with current state.
       val granted = ActivityCompat.checkSelfPermission(
@@ -165,6 +188,8 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
 
   @ReactMethod
   fun disablePush(promise: Promise) {
+    UserGistPushState.disable(reactApplicationContext)
+    if (UserGistPushState.isExpo(reactApplicationContext)) { promise.resolve(null); return }
     FirebaseMessaging.getInstance().deleteToken()
       .addOnCompleteListener { promise.resolve(null) }
   }
@@ -233,10 +258,10 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
   // Required for RN's NativeEventEmitter API even though we emit from a
   // separate static bus — RN will warn otherwise.
   @ReactMethod
-  fun addListener(_eventName: String?) { /* no-op */ }
+  fun addListener(_eventName: String?) { UserGistPushEventBus.addListener() }
 
   @ReactMethod
-  fun removeListeners(_count: Double) { /* no-op */ }
+  fun removeListeners(_count: Double) { UserGistPushEventBus.removeListeners(_count.toInt()) }
 
   // MARK: - Internal
 
@@ -287,10 +312,12 @@ internal object UserGistPushEventBus {
   @Volatile private var reactContext: ReactApplicationContext? = null
   private val pending: MutableList<Pair<String, WritableMap>> = mutableListOf()
   private var initialNotification: WritableMap? = null
+  private var listenerCount = 0
 
   @Synchronized
   fun attach(ctx: ReactApplicationContext) {
     this.reactContext = ctx
+    if (listenerCount == 0) return
     val drained = pending.toList()
     pending.clear()
     for ((name, body) in drained) {
@@ -298,6 +325,20 @@ internal object UserGistPushEventBus {
     }
   }
 
+  @Synchronized
+  fun addListener() {
+    listenerCount++
+    // Drain after all JS subscriptions in this tick have been registered.
+    android.os.Handler(android.os.Looper.getMainLooper()).post {
+      synchronized(this) { if (listenerCount > 0) reactContext?.let { attach(it) } }
+    }
+  }
+  @Synchronized fun removeListeners(count: Int) { listenerCount = (listenerCount - count).coerceAtLeast(0) }
+  @Synchronized fun detach(ctx: ReactApplicationContext) { if (reactContext === ctx) { reactContext = null; listenerCount = 0 } }
+
+  fun emitNotificationDisplayed(body: WritableMap) = emit("UserGistPush:notificationDisplayed", body)
+  fun emitNotificationDismissed(body: WritableMap) = emit("UserGistPush:notificationDismissed", body)
+
   fun emitToken(token: String) {
     val map = Arguments.createMap()
     map.putString("token", token)
@@ -328,7 +369,7 @@ internal object UserGistPushEventBus {
   @Synchronized
   private fun emit(name: String, body: WritableMap) {
     val ctx = reactContext
-    if (ctx == null || !ctx.hasActiveReactInstance()) {
+    if (ctx == null || !ctx.hasActiveReactInstance() || listenerCount == 0) {
       if (pending.size >= 100) pending.removeAt(0)
       pending.add(name to body)
       return

package/android/src/main/java/studio/usergist/feedback/UserGistPushState.kt

@@ -0,0 +1,69 @@
+package studio.usergist.feedback
+
+import android.content.Context
+import android.content.pm.PackageManager
+import org.json.JSONObject
+import java.net.HttpURLConnection
+import java.net.URL
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+import java.util.UUID
+import java.util.concurrent.Executors
+
+internal object UserGistPushState {
+  private val worker = Executors.newSingleThreadExecutor()
+  private fun prefs(context: Context) = context.getSharedPreferences("usergist_push_state", Context.MODE_PRIVATE)
+  fun isExpo(context: Context): Boolean = metadata(context).getBoolean("UserGistExpo", false)
+  fun mode(context: Context): String = metadata(context).getString("UserGistPushMode") ?: "automatic"
+  private fun metadata(context: Context) = context.packageManager.getApplicationInfo(context.packageName, PackageManager.GET_META_DATA).metaData ?: android.os.Bundle()
+  fun enabled(context: Context): Boolean = !isExpo(context) || prefs(context).getBoolean("push", false)
+  fun anonymousId(context: Context): String = JSONObject(prefs(context).getString("state", "{}")!!).optString("anonymousId")
+  fun accepts(context: Context, scope: String?): Boolean = enabled(context) && (scope.isNullOrEmpty() || scope == anonymousId(context))
+  private fun receiptPrefix(state: JSONObject) = "receipt." + UUID.nameUUIDFromBytes((state.optString("writeKey") + ":" + state.optString("anonymousId")).toByteArray(Charsets.UTF_8)) + "."
+  @Synchronized fun configure(context: Context, state: JSONObject) {
+    check(prefs(context).edit().putString("state", state.toString()).putBoolean("push", state.optBoolean("push")).commit())
+    if (state.optBoolean("push")) retry(context)
+  }
+  fun disable(context: Context) { prefs(context).edit().putBoolean("push", false).commit() }
+  fun receipt(context: Context, kind: String, id: String) {
+    if (id.isEmpty() || !enabled(context)) return
+    val state = JSONObject(prefs(context).getString("state", "{}")!!)
+    if (state.optString("writeKey").isEmpty()) return
+    val now = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US).apply { timeZone = TimeZone.getTimeZone("UTC") }.format(Date())
+    val body = if (kind == "silent-ack") JSONObject().put("pingId", id).put("anonymousId", state.optString("anonymousId")).put("receivedAt", now)
+      else JSONObject().put("deliveryId", id).put("occurredAt", now)
+    val store = prefs(context)
+    val prefix = receiptPrefix(state)
+    val record = JSONObject().put("state", state).put("kind", kind).put("body", body)
+    val key = prefix + UUID.randomUUID()
+    if (store.edit().putString(key, record.toString()).commit()) worker.execute { send(context, key, record) }
+  }
+  fun retry(context: Context) {
+    worker.execute {
+      val prefix = receiptPrefix(JSONObject(prefs(context).getString("state", "{}")!!))
+      prefs(context).all.filterKeys { it.startsWith(prefix) }.entries.take(500).forEach { (key, value) ->
+        runCatching { send(context, key, JSONObject(value as String)) }
+      }
+    }
+  }
+  private fun send(context: Context, key: String, record: JSONObject) {
+    val store = prefs(context)
+    val current = JSONObject(store.getString("state", "{}")!!)
+    val state = record.getJSONObject("state")
+    if (!store.getBoolean("push", false) || current.optString("anonymousId") != state.optString("anonymousId") || current.optString("writeKey") != state.optString("writeKey")) return
+    var connection: HttpURLConnection? = null
+    try {
+      connection = URL(state.getString("apiUrl").trimEnd('/') + "/v1/sdk/push/" + record.getString("kind")).openConnection() as HttpURLConnection
+      connection.connectTimeout = 5000; connection.readTimeout = 5000
+      connection.instanceFollowRedirects = false
+      connection.requestMethod = "POST"; connection.doOutput = true
+      connection.setRequestProperty("Authorization", "Bearer " + state.getString("writeKey"))
+      connection.setRequestProperty("Content-Type", "application/json")
+      connection.outputStream.use { it.write(record.getJSONObject("body").toString().toByteArray(Charsets.UTF_8)) }
+      if (connection.responseCode in 200..299) store.edit().remove(key).commit()
+    } catch (_: Exception) { /* Retry after foregrounding; retain the original receipt scope. */ }
+    finally { connection?.disconnect() }
+  }
+}

package/app.plugin.js

@@ -0,0 +1,2 @@
+// Expo 56+ uses Node 20.19+; keep the native config entry separate from Metro.
+export { default } from './plugin/index.cjs'

package/dist/NativeUserGistPush.d.ts

@@ -14,6 +14,16 @@ export interface EnablePushResult {
 }
 export type PushPermissionStatus = 'authorized' | 'provisional' | 'denied' | 'not_determined';
 export interface Spec extends TurboModule {
+    getPushConfiguration?(): Promise<{
+        mode?: string;
+        environment?: 'sandbox' | 'production';
+    }>;
+    configurePushState?(state: {
+        writeKey: string;
+        apiUrl: string;
+        anonymousId: string;
+        push: boolean;
+    }): Promise<void>;
     enablePush(options: {
         [key: string]: unknown;
     } | null): Promise<EnablePushResult>;

package/dist/NativeUserGistPush.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativeUserGistPush.d.ts","sourceRoot":"","sources":["../src/NativeUserGistPush.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAG/C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,OAAO,CAAA;IAChD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,CAAA;IAC/C,qFAAqF;IACrF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,oBAAoB,GAC5B,YAAY,GACZ,aAAa,GACb,QAAQ,GACR,gBAAgB,CAAA;AAEpB,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC,UAAU,CAAC,OAAO,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACjF,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,uBAAuB,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACxD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,sBAAsB,IAAI,OAAO,CAAC;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;IACpE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAClD,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7D,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrC;;AAED,wBAA4D"}
+{"version":3,"file":"NativeUserGistPush.d.ts","sourceRoot":"","sources":["../src/NativeUserGistPush.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAG/C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,OAAO,CAAA;IAChD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,CAAA;IAC/C,qFAAqF;IACrF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,oBAAoB,GAC5B,YAAY,GACZ,aAAa,GACb,QAAQ,GACR,gBAAgB,CAAA;AAEpB,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC,oBAAoB,CAAC,IAAI,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,CAAA;KAAE,CAAC,CAAA;IAC3F,kBAAkB,CAAC,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnH,UAAU,CAAC,OAAO,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACjF,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,uBAAuB,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACxD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,sBAAsB,IAAI,OAAO,CAAC;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;IACpE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAClD,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7D,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrC;;AAED,wBAA4D"}

package/dist/NativeUserGistPush.js.map

@@ -1 +1 @@
-{"version":3,"file":"NativeUserGistPush.js","sourceRoot":"","sources":["../src/NativeUserGistPush.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,4EAA4E;AAC5E,uEAAuE;AACvE,wEAAwE;AACxE,4EAA4E;AAC5E,yDAAyD;AAGzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAsClD,eAAe,mBAAmB,CAAC,GAAG,CAAO,cAAc,CAAC,CAAA"}
+{"version":3,"file":"NativeUserGistPush.js","sourceRoot":"","sources":["../src/NativeUserGistPush.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,4EAA4E;AAC5E,uEAAuE;AACvE,wEAAwE;AACxE,4EAA4E;AAC5E,yDAAyD;AAGzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAwClD,eAAe,mBAAmB,CAAC,GAAG,CAAO,cAAc,CAAC,CAAA"}