@pushmesh/sdk 0.7.2

package/android/src/main/java/io/pushmesh/sdk/PushMeshFirebaseModule.kt

@@ -0,0 +1,512 @@
+package io.pushmesh.sdk
+
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.app.NotificationManager
+import android.app.usage.UsageStatsManager
+import android.net.ConnectivityManager
+import android.net.NetworkCapabilities
+import android.os.Build
+import android.os.PowerManager
+import android.provider.Settings
+import java.security.MessageDigest
+import android.telephony.TelephonyManager
+import android.util.Log
+import androidx.core.app.NotificationManagerCompat
+import java.io.File
+import com.facebook.react.bridge.ActivityEventListener
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.google.firebase.FirebaseApp
+import com.google.firebase.FirebaseOptions
+import com.google.firebase.messaging.FirebaseMessaging
+
+/**
+ * Módulo nativo do modo ZERO-CONFIG (Android).
+ *
+ * Inicializa o Firebase por código, com os parâmetros públicos (api_key,
+ * sender_id, app_id, project_id) que o JS buscou no servidor PUSHMESH
+ * (GET /api/v1/apps/:appId/firebase_params) — sem google-services.json e sem
+ * o plugin google-services no app do cliente.
+ *
+ * POLÍTICA DE INICIALIZAÇÃO (default-first):
+ * - Caminho principal: o app do cliente NÃO tem Firebase → inicializamos o
+ *   FirebaseApp DEFAULT (sem nome). É o caso-alvo do zero-config.
+ * - Fallback raro: o host JÁ tem um FirebaseApp default (tem Firebase, mas não
+ *   passou getToken no init) → caímos para o app secundário nomeado
+ *   "pushmesh". Esse suporte multi-projeto do FCM foi DEPRECADO pelo Google
+ *   no firebase-messaging 25.1.0 (PR firebase-android-sdk#8087) — por isso
+ *   logamos um aviso orientando o host a passar getToken, e por isso o pin
+ *   de versão no build.gradle fica FORA da linha 25.1.x.
+ *
+ * Também carrega as pontes de runtime do zero-config: setReceiptConfig (o
+ * recibo direto do PushMeshMessageRouter), token pendente (rotação sem JS),
+ * e clique na notificação (getInitialNotification + onNewIntent).
+ *
+ * Módulo old-arch (NativeModule): funciona na New Architecture (Fabric) via
+ * interop layer do React Native. A migração para TurboModule/codegen é uma
+ * fase posterior.
+ */
+class PushMeshFirebaseModule(private val reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext), ActivityEventListener {
+
+  /** App escolhido pelo configure() (default OU secundário) — usado pelo getToken. */
+  private var appEscolhido: FirebaseApp? = null
+
+  override fun getName(): String = NAME
+
+  override fun initialize() {
+    reactContext.addActivityEventListener(this)
+  }
+
+  override fun invalidate() {
+    reactContext.removeActivityEventListener(this)
+  }
+
+  /**
+   * Configura o Firebase por código (ver a política default-first no KDoc da classe).
+   *
+   * Idempotente, nesta ordem de decisão:
+   * - não há FirebaseApp default → criamos o DEFAULT (caminho principal) e
+   *   guardamos a AUTORIA dele;
+   * - o default existe com as MESMAS options → reutiliza (no-op);
+   * - o default existe com options DIFERENTES **e é NOSSO** (cliente trocou as
+   *   credenciais no painel) → destrói e recria o DEFAULT com as options novas;
+   * - o default existe com options diferentes e é do HOST → app secundário
+   *   'pushmesh' (fallback deprecado).
+   *
+   * O terceiro caso faltava (corrigido em 2026-08-01) e o efeito era mudo: a
+   * troca de credenciais no painel caía no braço do secundário, logava um aviso
+   * MENTIROSO ("o host tem Firebase") e deixava o PushMeshMessagingService
+   * amarrado ao default com as credenciais VELHAS — getToken devolvia o token
+   * do projeto novo enquanto o onNewToken entregava o do antigo.
+   */
+  @ReactMethod
+  fun configure(params: ReadableMap, promise: Promise) {
+    try {
+      val appId = params.getString("app_id")
+      val apiKey = params.getString("api_key")
+      val senderId = params.getString("sender_id")
+      val projectId =
+        if (params.hasKey("project_id") && !params.isNull("project_id")) params.getString("project_id")
+        else null
+
+      if (appId.isNullOrBlank() || apiKey.isNullOrBlank() || senderId.isNullOrBlank()) {
+        promise.reject(ERROR_CONFIGURE, "params incompletos: app_id, api_key e sender_id são obrigatórios")
+        return
+      }
+
+      val builder = FirebaseOptions.Builder()
+        .setApplicationId(appId)
+        .setApiKey(apiKey)
+        .setGcmSenderId(senderId)
+      if (projectId != null) builder.setProjectId(projectId)
+      val options = builder.build()
+
+      val context = reactContext.applicationContext
+      val defaultApp = FirebaseApp.getApps(context).firstOrNull { it.name == FirebaseApp.DEFAULT_APP_NAME }
+
+      val escolhido = when {
+        // Caminho principal: nenhum FirebaseApp default → o app do cliente não
+        // tem Firebase. Inicializamos o DEFAULT (imune à deprecação de
+        // multi-projeto do firebase-messaging 25.1.x).
+        defaultApp == null -> criarDefaultNosso(context, options)
+
+        // O default já está com as options que queremos (re-configure no mesmo
+        // processo, ou o host usa exatamente o mesmo projeto): reutiliza.
+        // FirebaseOptions implementa equals() comparando os campos públicos.
+        // NÃO reivindicamos autoria aqui: pode ser o default do host.
+        defaultApp.options == options -> defaultApp
+
+        // Credenciais NOVAS no painel e o default é comprovadamente NOSSO:
+        // derruba e recria como DEFAULT. É o único jeito de o
+        // PushMeshMessagingService (que é sempre do default) passar a falar
+        // com o projeto novo; delete() é permitido inclusive no default e um
+        // initializeApp com o mesmo nome depois dele funciona.
+        defaultENosso(context, defaultApp) -> {
+          Log.w(TAG, "PushMesh: credenciais do FCM mudaram — recriando o FirebaseApp default.")
+          defaultApp.delete()
+          criarDefaultNosso(context, options)
+        }
+
+        // Fallback raro: o host tem Firebase próprio e mesmo assim não passou
+        // getToken. Mantemos o app secundário nomeado — mas avisamos: o
+        // suporte multi-projeto do FCM está deprecado (25.1.0, PR #8087).
+        else -> {
+          Log.w(
+            TAG,
+            "PushMesh: FirebaseApp default já existe (o host tem Firebase). " +
+              "Caindo para o app secundário '$APP_NAME' — o suporte multi-projeto do FCM " +
+              "está deprecado pelo Google (firebase-messaging 25.1.0). " +
+              "Recomendado: passe getToken no PushMesh.init (modo host).",
+          )
+          val secundario = FirebaseApp.getApps(context).firstOrNull { it.name == APP_NAME }
+          if (secundario != null && secundario.options == options) {
+            secundario
+          } else {
+            secundario?.delete()
+            FirebaseApp.initializeApp(context, options, APP_NAME)
+          }
+        }
+      }
+      appEscolhido = escolhido
+
+      // MODO persistido para quem roda SEM JS: o onNewToken só recebe token do
+      // FirebaseApp DEFAULT, então no modo secundário aquele token é do HOST e
+      // precisa ser ignorado (ver PushMeshMessagingService.onNewToken).
+      // Derivado do app escolhido, nunca duplicado em cada braço acima.
+      PushMeshMessageRouter.salvarModoFcm(
+        context,
+        if (escolhido.name == FirebaseApp.DEFAULT_APP_NAME) PushMeshMessageRouter.MODO_DEFAULT
+        else PushMeshMessageRouter.MODO_SECUNDARIO,
+      )
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject(ERROR_CONFIGURE, e.message, e)
+    }
+  }
+
+  /**
+   * Cria o FirebaseApp DEFAULT e ASSINA a autoria: guardamos o applicationId
+   * das options usadas. É esse registro que autoriza um `delete()` futuro.
+   */
+  private fun criarDefaultNosso(context: Context, options: FirebaseOptions): FirebaseApp {
+    val app = FirebaseApp.initializeApp(context, options)
+    PushMeshMessageRouter.prefs(context).edit()
+      .putString(PREF_DEFAULT_NOSSO, options.applicationId)
+      .apply()
+    return app
+  }
+
+  /**
+   * O FirebaseApp default é obra NOSSA?
+   *
+   * A prova é o applicationId com que NÓS o criamos ([criarDefaultNosso]) —
+   * e não um simples booleano "já criei um default alguma vez". A diferença é
+   * o cenário que estraga o app do cliente: se ele publicar uma versão com
+   * Firebase próprio (google-services.json), o default passa a nascer sozinho,
+   * pelo ContentProvider do Firebase, ANTES de qualquer código nosso. Com um
+   * booleano velho no disco nós deletaríamos o Firebase DO HOST — levando
+   * junto o Analytics/Crashlytics dele. Comparando o applicationId, o default
+   * do host (outro projeto ⇒ outro id) simplesmente não bate, e caímos no
+   * fallback secundário como manda a política.
+   */
+  private fun defaultENosso(context: Context, defaultApp: FirebaseApp): Boolean {
+    val nossoId = PushMeshMessageRouter.prefs(context).getString(PREF_DEFAULT_NOSSO, null)
+    return !nossoId.isNullOrBlank() && nossoId == defaultApp.options.applicationId
+  }
+
+  /** Token FCM do app escolhido no configure(). Exige configure() antes. */
+  @ReactMethod
+  fun getToken(promise: Promise) {
+    try {
+      val app = appEscolhido
+        ?: throw IllegalStateException("configure() precisa rodar antes de getToken()")
+      app.get(FirebaseMessaging::class.java).token
+        .addOnSuccessListener { token -> promise.resolve(token) }
+        .addOnFailureListener { e -> promise.reject(ERROR_TOKEN, e.message, e) }
+    } catch (e: Exception) {
+      promise.reject(ERROR_TOKEN, e.message, e)
+    }
+  }
+
+  /**
+   * Drena as mensagens recebidas sem JS ativo (buffer em SharedPreferences).
+   * O JS chama no init e processa cada uma (recibo + display).
+   */
+  @ReactMethod
+  fun getPendingMessages(promise: Promise) {
+    try {
+      promise.resolve(PushMeshMessageBuffer.drain(reactContext.applicationContext))
+    } catch (e: Exception) {
+      promise.reject(ERROR_PENDING, e.message, e)
+    }
+  }
+
+  /**
+   * Config do recibo DIRETO nativo (PushMeshMessageRouter.postarRecibo):
+   * base_url/app_id/player_id persistidos — o POST sai mesmo com o JS morto.
+   * Chamado pelo JS após cada registro bem-sucedido.
+   */
+  @ReactMethod
+  fun setReceiptConfig(params: ReadableMap, promise: Promise) {
+    try {
+      PushMeshMessageRouter.prefs(reactContext.applicationContext).edit()
+        .putString("pmx_base_url", params.getString("base_url")?.trimEnd('/'))
+        .putString("pmx_app_id", params.getString("app_id"))
+        .putString("pmx_player_id", params.getString("player_id"))
+        .apply()
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject(ERROR_RECEIPT, e.message, e)
+    }
+  }
+
+  /** Token FCM persistido pelo onNewToken (rotação sem JS vivo) — o boot reconcilia. */
+  @ReactMethod
+  fun getPendingToken(promise: Promise) {
+    try {
+      promise.resolve(PushMeshMessageRouter.tokenPendente(reactContext.applicationContext))
+    } catch (e: Exception) {
+      promise.reject(ERROR_TOKEN, e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun clearPendingToken(promise: Promise) {
+    try {
+      PushMeshMessageRouter.limparTokenPendente(reactContext.applicationContext)
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject(ERROR_TOKEN, e.message, e)
+    }
+  }
+
+  /**
+   * Clique com o app MORTO: a MainActivity nasce com os extras do push no
+   * intent. Lê e LIMPA (recreate/rotate não entrega 2x). null quando o app
+   * não foi aberto por notificação.
+   */
+  @ReactMethod
+  fun getInitialNotification(promise: Promise) {
+    try {
+      val intent = reactContext.currentActivity?.intent
+      val data = extrairPushExtras(intent)
+      if (data != null && intent != null) {
+        for (k in data.keys) intent.removeExtra(k)
+      }
+      promise.resolve(data?.let { paraWritable(it) })
+    } catch (e: Exception) {
+      promise.reject(ERROR_CLICK, e.message, e)
+    }
+  }
+
+  /**
+   * PERFIL DO APARELHO — nível GRATUITO de rastreamento.
+   *
+   * Só o que NÃO pede permissão ao usuário e NÃO altera a ficha de
+   * privacidade do app do cliente na Play (id de publicidade e localização
+   * ficam de fora por decisão de produto).
+   *
+   * Cada leitura é isolada: aparelho de OEM exótico que quebre uma delas
+   * registra igual, só com aquele campo vazio. NUNCA rejeita a promise —
+   * perfil ausente não pode impedir o aparelho de receber push.
+   */
+  @ReactMethod
+  fun perfilDispositivo(promise: Promise) {
+    val map = Arguments.createMap()
+    // Build.* nunca lança e não pede permissão.
+    map.putString("device_os", Build.VERSION.RELEASE)
+    map.putString("fabricante", Build.MANUFACTURER)
+    map.putString("modelo", Build.MODEL)
+
+    // Operadora: getNetworkOperatorName NÃO exige permissão. Vazio em tablet
+    // sem chip — melhor ausente que "".
+    runCatching {
+      val tm = reactContext.getSystemService(Context.TELEPHONY_SERVICE) as? TelephonyManager
+      tm?.networkOperatorName?.takeIf { it.isNotBlank() }?.let { map.putString("carrier", it) }
+    }
+
+    // Rede: ACCESS_NETWORK_STATE é permissão NORMAL (concedida na instalação,
+    // sem diálogo) e está declarada no manifest do SDK.
+    runCatching {
+      val cm = reactContext.getSystemService(Context.CONNECTIVITY_SERVICE) as? ConnectivityManager
+      val caps = cm?.getNetworkCapabilities(cm.activeNetwork)
+      val tipo = when {
+        caps == null -> null
+        caps.hasTransport(NetworkCapabilities.TRANSPORT_WIFI) -> "wifi"
+        caps.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) -> "celular"
+        else -> "outro"
+      }
+      tipo?.let { map.putString("net_type", it) }
+    }
+
+    map.putBoolean("rooted", indicioDeRoot())
+
+    // --- Diagnóstico de ENTREGA (migration 0013) ---
+
+    // Fila de standby: É o throttling de push data-only dito pelo próprio
+    // sistema. App em 'rare'/'restricted' tem a entrega ADIADA pelo Android.
+    runCatching {
+      if (Build.VERSION.SDK_INT >= 28) {
+        val usm = reactContext.getSystemService(Context.USAGE_STATS_SERVICE) as? UsageStatsManager
+        usm?.appStandbyBucket?.let { b ->
+          val nome = when (b) {
+            5 -> "exempted"
+            UsageStatsManager.STANDBY_BUCKET_ACTIVE -> "active"
+            UsageStatsManager.STANDBY_BUCKET_WORKING_SET -> "working_set"
+            UsageStatsManager.STANDBY_BUCKET_FREQUENT -> "frequent"
+            UsageStatsManager.STANDBY_BUCKET_RARE -> "rare"
+            45 -> "restricted" // constante só na API 30+; o valor é estável
+            else -> "b$b"
+          }
+          map.putString("standby_bucket", nome)
+        }
+      }
+    }
+
+    // Isenção da otimização de bateria: sem ela, OEMs agressivos (Xiaomi/
+    // Samsung/Huawei) matam o processo e o push data-only nem acorda o app.
+    // LER não pede permissão nenhuma (só PEDIR a isenção pediria).
+    runCatching {
+      val pm = reactContext.getSystemService(Context.POWER_SERVICE) as? PowerManager
+      pm?.let { map.putBoolean("bateria_irrestrita", it.isIgnoringBatteryOptimizations(reactContext.packageName)) }
+    }
+
+    runCatching { map.putInt("notif_permissoes", bitmaskNotificacoes()) }
+    runCatching { idDaInstalacao()?.let { map.putString("instalacao_id", it) } }
+    promise.resolve(map)
+  }
+
+  /**
+   * Identificador estável do APARELHO — em HASH, nunca cru.
+   *
+   * Fonte: `Settings.Secure.ANDROID_ID`. Não pede permissão e é escopado por
+   * (chave de assinatura do app + usuário + aparelho): não serve para
+   * correlacionar entre apps, e SOBREVIVE À REINSTALAÇÃO. É isso que permite
+   * ao servidor saber que o token novo é o MESMO aparelho e derrubar o
+   * fantasma na hora, em vez de esperar um envio falhar.
+   *
+   * Devolvemos SHA-256 truncado: para comparar igualdade o hash basta, e o
+   * identificador cru nunca sai do aparelho (privacidade por desenho).
+   */
+  private fun idDaInstalacao(): String? {
+    val cru = Settings.Secure.getString(reactContext.contentResolver, Settings.Secure.ANDROID_ID)
+    if (cru.isNullOrBlank()) return null
+    val digest = MessageDigest.getInstance("SHA-256")
+      // sal fixo do SDK: hash sem sal de um espaço pequeno é reversível
+      .digest("pushmesh:$cru".toByteArray(Charsets.UTF_8))
+    return digest.take(16).joinToString("") { "%02x".format(it) }
+  }
+
+  /**
+   * BITMASK granular da permissão de notificação (contrato da migration 0013):
+   * 1=habilitadas · 2=alerta/banner · 4=som · 8=badge · 16=tela de bloqueio ·
+   * 32=canal padrão não bloqueado. Bitmask por decisão de produto: 6 sinais
+   * num INT — filtrar "quem tem permissão mas não vê banner" vira operação
+   * de bits.
+   *
+   * O detalhe vem do NOSSO canal (`pushmesh_default`). Antes do 1º push o
+   * canal ainda não existe — aí os bits refletem os defaults com que ele
+   * NASCERÁ (IMPORTANCE_HIGH): reportar só a chave-mestra pareceria "sem
+   * alerta", o que seria mentira.
+   */
+  private fun bitmaskNotificacoes(): Int {
+    val ctx = reactContext.applicationContext
+    var bits = 0
+    val master = runCatching { NotificationManagerCompat.from(ctx).areNotificationsEnabled() }
+      .getOrDefault(false)
+    if (!master) return 0
+    bits = bits or 1
+    val canal = runCatching {
+      (ctx.getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager)
+        ?.getNotificationChannel(PushMeshMessageRouter.CANAL_PADRAO)
+    }.getOrNull()
+    if (canal == null) {
+      // canal ainda não criado: nascerá HIGH com som/badge/lockscreen default
+      return bits or 2 or 4 or 8 or 16 or 32
+    }
+    val importancia = canal.importance
+    if (importancia == NotificationManager.IMPORTANCE_NONE) return bits // canal bloqueado
+    bits = bits or 32
+    if (importancia >= NotificationManager.IMPORTANCE_HIGH) bits = bits or 2 // banner/heads-up
+    if (importancia >= NotificationManager.IMPORTANCE_DEFAULT && canal.sound != null) bits = bits or 4
+    if (canal.canShowBadge()) bits = bits or 8
+    // -1000 = sem override (mostra); só VISIBILITY_SECRET esconde do bloqueio
+    if (canal.lockscreenVisibility != android.app.Notification.VISIBILITY_SECRET) bits = bits or 16
+    return bits
+  }
+
+  /**
+   * Heurística de root — SINAL, não prova (um root bem feito se esconde).
+   * Serve como insumo antifraude, e por isso `false` significa "a heurística
+   * não achou indício", nunca "o aparelho é confiável".
+   */
+  private fun indicioDeRoot(): Boolean {
+    val caminhos = listOf(
+      "/system/app/Superuser.apk",
+      "/sbin/su",
+      "/system/bin/su",
+      "/system/xbin/su",
+      "/data/local/xbin/su",
+      "/data/local/bin/su",
+      "/system/sd/xbin/su",
+      "/system/bin/failsafe/su",
+      "/data/local/su",
+      "/su/bin/su",
+    )
+    if (caminhos.any { runCatching { File(it).exists() }.getOrDefault(false) }) return true
+    // build de teste/engenharia: assinado com chaves de dev, não de fábrica
+    return Build.TAGS?.contains("test-keys") == true
+  }
+
+  /**
+   * Clique com o app ABERTO (singleTop → onNewIntent): emite para o JS.
+   *
+   * Parâmetro NÃO-NULO de propósito: desde a conversão do RN para Kotlin
+   * (`ActivityEventListener.onNewIntent(intent: Intent)`, RN 0.8x) um
+   * `Intent?` aqui NÃO sobrescreve nada e a compilação do app quebra. Contra
+   * as versões antigas (interface em Java) o tipo é plataforma, então a
+   * assinatura não-nula compila igual — vale para toda a faixa suportada.
+   */
+  override fun onNewIntent(intent: Intent) {
+    val data = extrairPushExtras(intent) ?: return
+    if (reactContext.hasActiveReactInstance()) {
+      val payload = Arguments.createMap()
+      payload.putMap("data", paraWritable(data))
+      reactContext
+        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+        .emit(EVENT_CLICK, payload)
+    }
+  }
+
+  override fun onActivityResult(activity: Activity, requestCode: Int, resultCode: Int, data: Intent?) {
+    // nada — a interface exige (não usamos startActivityForResult)
+  }
+
+  /** Extras string do intent de clique (o PendingIntent carrega o data inteiro do push). */
+  private fun extrairPushExtras(intent: Intent?): Map<String, String>? {
+    val extras = intent?.extras ?: return null
+    val data = HashMap<String, String>()
+    for (k in extras.keySet()) {
+      (extras.get(k) as? String)?.let { data[k] = it }
+    }
+    // só é "clique de push" se carrega o marcador do nosso payload
+    return if (data.keys.any { it.startsWith("pmx_") || it.startsWith("pm_") }) data else null
+  }
+
+  private fun paraWritable(data: Map<String, String>): WritableMap {
+    val map = Arguments.createMap()
+    for ((k, v) in data) map.putString(k, v)
+    return map
+  }
+
+  companion object {
+    const val NAME = "PushMeshFirebase"
+    const val APP_NAME = "pushmesh"
+    const val EVENT_MESSAGE = "PushMeshMessage"
+    const val EVENT_TOKEN_REFRESH = "PushMeshTokenRefresh"
+    const val EVENT_CLICK = "PushMeshNotificationClick"
+    private const val TAG = "PushMeshFirebase"
+
+    /**
+     * applicationId do FirebaseApp DEFAULT que NÓS criamos — a assinatura de
+     * autoria que autoriza recriá-lo quando as credenciais mudam no painel
+     * (ver [defaultENosso]).
+     */
+    private const val PREF_DEFAULT_NOSSO = "pmx_default_nosso_app_id"
+
+    private const val ERROR_CONFIGURE = "pushmesh_configure"
+    private const val ERROR_TOKEN = "pushmesh_token"
+    private const val ERROR_PENDING = "pushmesh_pending"
+    private const val ERROR_RECEIPT = "pushmesh_receipt"
+    private const val ERROR_CLICK = "pushmesh_click"
+  }
+}

package/android/src/main/java/io/pushmesh/sdk/PushMeshFirebasePackage.kt

@@ -0,0 +1,20 @@
+package io.pushmesh.sdk
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * Package do módulo zero-config (autolinking do RN).
+ * Módulo old-arch (NativeModule) — funciona na New Architecture via interop
+ * layer do RN; a migração para TurboModule é uma fase posterior.
+ */
+class PushMeshFirebasePackage : ReactPackage {
+
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
+    listOf(PushMeshFirebaseModule(reactContext))
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
+    emptyList()
+}

package/android/src/main/java/io/pushmesh/sdk/PushMeshMessageBuffer.kt

@@ -0,0 +1,53 @@
+package io.pushmesh.sdk
+
+import android.content.Context
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableArray
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Buffer de mensagens recebidas SEM JS ativo (app em background/morto, push
+ * data-only). Persiste em SharedPreferences; o JS drena no init via
+ * getPendingMessages() — o recibo de entrega nunca se perde.
+ *
+ * Cap de 20 mensagens (descarta a mais antiga): o buffer existe para o
+ * recibo, não para histórico.
+ */
+object PushMeshMessageBuffer {
+
+  private const val PREFS = "pushmesh_pending"
+  private const val KEY = "messages"
+  private const val MAX = 20
+
+  @Synchronized
+  fun add(context: Context, data: Map<String, String>) {
+    val prefs = context.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+    val atual = JSONArray(prefs.getString(KEY, "[]"))
+    val item = JSONObject()
+    for ((k, v) in data) item.put(k, v)
+    atual.put(item)
+    while (atual.length() > MAX) atual.remove(0)
+    prefs.edit().putString(KEY, atual.toString()).apply()
+  }
+
+  /** Lê e limpa o buffer. Retorna um WritableArray de mapas {chave: valor}. */
+  @Synchronized
+  fun drain(context: Context): WritableArray {
+    val prefs = context.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+    val bruto = JSONArray(prefs.getString(KEY, "[]"))
+    prefs.edit().remove(KEY).apply()
+    val out = Arguments.createArray()
+    for (i in 0 until bruto.length()) {
+      val obj = bruto.optJSONObject(i) ?: continue
+      val map = Arguments.createMap()
+      val keys = obj.keys()
+      while (keys.hasNext()) {
+        val k = keys.next()
+        map.putString(k, obj.optString(k))
+      }
+      out.pushMap(map)
+    }
+    return out
+  }
+}