@pushmesh/sdk 0.7.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PushMesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# @pushmesh/sdk
+
+SDK React Native do **PushMesh** — push próprio com recibo real de entrega,
+reativação de permissão (módulo Reativa) e banners in-app.
+
+- TypeScript, build CJS único e **minificado com nomes preservados** (stack
+  trace legível no app, sem source map), `sideEffects: false`
+- Compatível com New Architecture (Fabric) — testado contra RN 0.83
+- Runtime: **fetch nativo** (sem axios) + `@notifee/react-native` + AsyncStorage
+- **Dois modos**: zero-config (Android via FCM por código; iOS via APNs direto —
+  ambos **sem Firebase no app**) ou modo host (o token vem do app)
+- Inclui **API clássica** (`/compat`), compatível com o formato de SDK de push
+  mais difundido do mercado — migração sem reescrever o app
+
+> **Guia completo** (zero-config em detalhe, modo host, API clássica, rotas,
+> imagem no iOS, permissões, caminho nativo): <https://docs.pushmesh.io> — o
+> mesmo guia mora no repositório, em `sdk/docs/GUIA-INTEGRACAO.md`.
+> · A doc de cada método vive no hover do editor (JSDoc embarcado nos tipos).
+
+## Instalação
+
+```bash
+npm install @pushmesh/sdk @notifee/react-native @react-native-async-storage/async-storage
+cd ios && bundle exec pod install   # iOS
+```
+
+## Começo rápido (zero-config — recomendado)
+
+Sem Firebase no app: cadastre o app no painel PushMesh (Android: cole o
+`google-services.json` em Configurações → FCM; iOS: suba a chave `.p8` em
+Configurações → APNs e habilite Push Notifications + Background Modes →
+Remote notifications no Xcode). No app:
+
+```js
+import PushMesh from '@pushmesh/sdk';
+
+await PushMesh.init({
+  appId: 'UUID_DO_APP_NO_PUSHMESH', // SÓ ISSO é obrigatório
+  appVersion: '1.0.3',
+  // baseUrl é OPCIONAL — sem ela vale o servidor oficial
+  // (https://push.pushmesh.io). Passe uma URL só para self-host.
+});
+// no login do app: PushMesh.login(idDoUsuario);
+```
+
+Banners in-app: uma linha — monte `<PushMeshInAppHost />` (exportado pelo
+pacote) uma vez na raiz da sua árvore. Para o SDK se pendurar sozinho na raiz,
+`init({ ..., inAppAutoMontar: true })` — automático é **opt-in**, porque ele
+mexe no provedor de wrapper do React Native.
+
+Registro, token, display, recibo real e clique funcionam sem mais nenhuma
+linha. Imagem no push do iOS exige a Notification Service Extension — código
+pronto e guia de 5 min em `ios/NotificationService/LEIA-ME.md`.
+
+## Modo host (app com Firebase próprio)
+
+Quem já tem Firebase passa `getToken` e nada muda (o zero-config nem é acionado):
+
+```js
+await PushMesh.init({
+  appId: 'UUID_DO_APP_NO_PUSHMESH',
+  getToken: () => messaging().getToken(),
+});
+messaging().onTokenRefresh(t => PushMesh.setToken(t));
+messaging().onMessage(m => PushMesh.receipts.handlePushData(m.data));
+messaging().setBackgroundMessageHandler(async m => { PushMesh.receipts.handlePushData(m.data); });
+messaging().onNotificationOpenedApp(m => PushMesh.notifications.handleClick(m.data));
+```
+
+## API
+
+`PushMesh.init` · `setToken` · `login` · `logout` · `getPlayerId` ·
+`receipts.handlePushData` · `notifications.{handleClick,addEventListener,removeEventListener}` ·
+`permissions.{checkAndReport,openNotificationSettings,canRequestNatively}` ·
+`user.{addTag,addTags,removeTag,removeTags}` · `inapp.{pending,track}` ·
+`definirGatilho`/`removerGatilho`/`limparGatilhos` (gatilho no aplicativo) ·
+`triggers.*` · `doctor()`.
+
+Cada método tem JSDoc completo no hover do editor; assinaturas e semântica no
+[guia](https://docs.pushmesh.io). A **API clássica**
+(initialize/Notifications/User/InAppMessages) vem no entry `@pushmesh/sdk/compat`.
+
+## Leve por contrato
+
+O SDK roda no celular do cliente final — cada request e cada kB são orçados:
+
+- **Zero polling** — rede só no init, no `AppState → active` e no push recebido;
+- **Registro idempotente** — re-init com o mesmo payload = 1 request (provado em teste);
+- **Fila offline educada** — backoff com jitter, `Retry-After` honrado, máx.
+  10 tentativas e 5 requests concorrentes no flush (provado em teste);
+- **Orçamento de pacote** — `npm run size` falha o build se o payload JS do
+  tarball passar do teto (o código nativo Android/iOS não conta — vira código
+  compilado, não bundle JS).
+
+## Diagnóstico
+
+```bash
+npx pushmesh-doctor --base-url https://push.pushmesh.io \
+  --app-id <uuid> [--player-id <uuid>] [--api-key pm_live_...]
+```
+
+Exit code `0` = tudo verde; cada falha sai com "como corrigir". Dentro do app,
+`PushMesh.doctor()` imprime o equivalente on-device. Para testar sem push
+real, use o device sandbox: `getToken: async () => 'test:ok'` (detalhes no guia).
+
+## Requisitos
+
+| Item | Mínimo |
+|---|---|
+| React Native | 0.71 (New Architecture testada em 0.83) |
+| React | 17 |
+| Node (build/CLI) | 18 |
+| iOS | 15.1 (alinhado ao mínimo do RN do app) |
+| Android | conforme o `minSdk` do app |
+
+Peer dependencies: `@notifee/react-native` ≥ 7 e
+`@react-native-async-storage/async-storage` ≥ 1.17.
+
+## Desenvolvimento do SDK
+
+```bash
+npm install
+npm run typecheck    # tsc --noEmit
+npm test             # jest com mocks (sem device)
+npm run build        # CJS minificado (nomes preservados) em dist/cjs
+npm run test:types   # tsd — contrato dos exports (roda DEPOIS do build)
+npm run size         # orçamento: payload JS ≤ 40 kB (nativo não conta)
+```
+
+## Licença
+
+MIT — PushMesh 2026. Ver [LICENSE](LICENSE).
+
+---
+
+## English summary
+
+React Native SDK for **PushMesh** — self-hosted-capable push with real delivery
+receipts, permission re-activation and in-app banners.
+
+```bash
+npm install @pushmesh/sdk @notifee/react-native @react-native-async-storage/async-storage
+cd ios && bundle exec pod install
+```
+
+```js
+import PushMesh from '@pushmesh/sdk';
+
+await PushMesh.init({ appId: 'YOUR_APP_UUID' }); // App ID is the only required field
+PushMesh.login(userId);                          // when your app logs the user in
+```
+
+Zero-config mode needs **no Firebase SDK in your app**: Android gets FCM
+credentials at runtime, iOS talks APNs directly with the `.p8` key you upload in
+the dashboard. Already using Firebase? Pass `getToken` and keep your setup
+(host mode). A drop-in **classic API** lives in `@pushmesh/sdk/compat` for
+migrating from the most widespread push SDK format without rewriting your app.
+Full documentation: <https://docs.pushmesh.io> — the same guide lives in this
+repository at `sdk/docs/GUIA-INTEGRACAO.md` (Portuguese, with an English
+summary at the end). MIT licensed.

package/android/build.gradle

@@ -0,0 +1,82 @@
+/**
+ * Módulo nativo Android do modo ZERO-CONFIG do PUSHMESH.
+ *
+ * Inicializa o Firebase por código (política default-first: FirebaseApp
+ * DEFAULT no caminho principal; secundário "pushmesh" só como fallback
+ * multi-projeto), com os parâmetros públicos vindos do servidor — SEM
+ * google-services.json e SEM o plugin com.google.gms.google-services no app
+ * do cliente (é justamente essa exigência que o modo zero-config elimina).
+ *
+ * compileSdk/minSdk/kotlin seguem o rootProject do app host, com fallbacks.
+ */
+buildscript {
+    def kotlin_version = rootProject.ext.has('kotlinVersion') ? rootProject.ext.get('kotlinVersion') : '1.9.24'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+def safeExtGet(String prop, Object fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace "io.pushmesh.sdk"
+    compileSdkVersion safeExtGet('compileSdkVersion', 35)
+
+    defaultConfig {
+        minSdkVersion safeExtGet('minSdkVersion', 24)
+        targetSdkVersion safeExtGet('targetSdkVersion', 35)
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+}
+
+tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    // React Native vem do app host (autolinking).
+    implementation "com.facebook.react:react-android"
+
+    // NotificationCompat (display data-only): garantida em qualquer app RN.
+    implementation "androidx.core:core:1.13.1"
+
+    // Firebase Cloud Messaging via BoM.
+    //
+    // PIN PROPOSITAL: BoM 34.14.1 → firebase-messaging 25.0.2, a última linha
+    // ANTES da transição token→FID (a 25.1.0, no BoM 34.15.0, deprecou
+    // getToken/onNewToken e o suporte multi-projeto do FCM — PR
+    // firebase-android-sdk#8087). A migração para o modelo FID é planejada no
+    // backend — ver HANDOFF seção 2026-07-28. Não subir o BoM sem essa migração.
+    // Mapeamento confirmado nos POMs dos BoMs (dl.google.com/dl/android/maven2).
+    //
+    // SEM o plugin google-services: o FirebaseApp é inicializado por código
+    // (default-first, ver PushMeshFirebaseModule).
+    implementation platform("com.google.firebase:firebase-bom:34.14.1")
+    implementation "com.google.firebase:firebase-messaging"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,69 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <!--
+    Android 13+ (API 33): sem esta permissão o sistema NÃO exibe notificação
+    nenhuma — e a falha é silenciosa. Declarada AQUI para o app do cliente não
+    precisar saber disso (é a promessa do zero-config). Em app que já usa outro
+    SDK de push a declaração é idêntica e o manifest merger apenas funde as duas.
+    Pedir a permissão ao usuário continua sendo do app host (ou do SDK legado no
+    dual-run) — o SDK só lê e reporta o estado (PushMesh.permissions).
+  -->
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+  <application>
+    <!--
+      DUAL-RUN (migração do provedor legado): receiver de alta prioridade que
+      captura SÓ as mensagens nossas (marcador pmx_* — abortBroadcast) e deixa
+      as demais seguirem a cadeia para o SDK do provedor legado.
+      Ver PushMeshMessagingReceiver.kt.
+    -->
+    <receiver
+      android:name="io.pushmesh.sdk.PushMeshMessagingReceiver"
+      android:exported="true"
+      android:permission="com.google.android.c2dm.permission.SEND">
+      <intent-filter android:priority="999">
+        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
+      </intent-filter>
+    </receiver>
+
+    <!--
+      Toque na notificação: trampolim INVISÍVEL.
+
+      Tem de ser Activity, não BroadcastReceiver: desde o Android 10 app em
+      segundo plano não pode abrir tela, então um PendingIntent de broadcast
+      teria o startActivity BLOQUEADO EM SILÊNCIO e o toque não faria nada
+      (sintoma real do piloto, 2026-07-30). PendingIntent de Activity é
+      iniciado pelo sistema e pode abrir o destino.
+
+      Ela registra o clique e abre a `pm_url` (ou o app, quando não há URL).
+      Translucent + excludeFromRecents + taskAffinity vazio: nunca aparece na
+      tela nem na lista de recentes, e não se mistura à task do app.
+      Não exportada: só o nosso PendingIntent a dispara.
+    -->
+    <activity
+      android:name="io.pushmesh.sdk.PushMeshClickActivity"
+      android:exported="false"
+      android:excludeFromRecents="true"
+      android:noHistory="true"
+      android:taskAffinity=""
+      android:theme="@android:style/Theme.Translucent.NoTitleBar" />
+
+    <!--
+      Caminho fallback de entrega (ver PushMeshMessagingService.kt — o
+      receiver acima é o principal). Se o app host já tem o PRÓPRIO
+      FirebaseMessagingService (modo host), apenas um service recebe
+      MESSAGING_EVENT — nesse caso o host pode remover este via manifest merger:
+        <service android:name="io.pushmesh.sdk.PushMeshMessagingService"
+                 tools:node="remove" />
+      O modo host não usa nada deste módulo nativo.
+    -->
+    <service
+      android:name="io.pushmesh.sdk.PushMeshMessagingService"
+      android:exported="false">
+      <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+      </intent-filter>
+    </service>
+  </application>
+
+</manifest>

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

@@ -0,0 +1,124 @@
+package io.pushmesh.sdk
+
+import android.app.Activity
+import android.app.NotificationManager
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.os.Bundle
+
+/**
+ * Trampolim do toque na notificação — Activity invisível.
+ *
+ * POR QUE UMA ACTIVITY, e não um BroadcastReceiver:
+ * desde o Android 10 um app em segundo plano **não pode abrir tela**. Um
+ * `PendingIntent` de broadcast roda com o app em background, então o
+ * `startActivity` dele é bloqueado EM SILÊNCIO — o usuário toca na notificação
+ * e nada acontece (foi exatamente o sintoma no piloto, 2026-07-30). Já um
+ * `PendingIntent` de ACTIVITY é iniciado pelo próprio sistema e, estando em
+ * primeiro plano, pode abrir o que quiser. É por isso que os SDKs do mercado
+ * abrem o app e só então redirecionam.
+ *
+ * Sequência: registra o clique (Kotlin, sem depender de JS vivo) → abre o
+ * destino → se apaga. Nunca aparece na tela nem na lista de recentes.
+ *
+ * Destino:
+ * 1. `pm_url` → abre a URL (http/https no navegador; esquema próprio cai no
+ *    deep link do app, se ele declarar o intent-filter);
+ * 2. sem `pm_url` → abre o app com os dados como extras (o JS recebe em
+ *    `getInitialNotification`/`onNewIntent`).
+ */
+class PushMeshClickActivity : Activity() {
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    // LEI do SDK: push nunca derruba o app do cliente.
+    try {
+      val data = HashMap<String, String>()
+      intent?.extras?.let { extras ->
+        for (k in extras.keySet()) {
+          (extras.get(k) as? String)?.let { data[k] = it }
+        }
+      }
+
+      // 1) o clique é contado ANTES de qualquer navegação
+      PushMeshMessageRouter.postarRecibo(applicationContext, data, "clique")
+
+      // 2) tira a notificação da bandeja
+      runCatching {
+        data["pm_msg_id"]?.hashCode()?.let { id ->
+          (getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager)?.cancel(id)
+        }
+      }
+
+      // 3) destino
+      val url = data["pm_url"]?.trim().orEmpty()
+      val abriu = if (url.isNotEmpty()) abrirUrl(url, data) else false
+      if (!abriu) abrirApp(data)
+    } catch (t: Throwable) {
+      android.util.Log.w("PushMesh", "falha ao tratar clique", t)
+      runCatching { abrirApp(emptyMap()) }
+    } finally {
+      // Sem transição visual: o usuário não vê tela intermediária nenhuma.
+      finish()
+      overridePendingTransition(0, 0)
+    }
+  }
+
+  /** true = alguém aceitou a URL; false = cai para o app. */
+  private fun abrirUrl(url: String, data: Map<String, String>): Boolean = try {
+    val i = Intent(Intent.ACTION_VIEW, Uri.parse(url)).apply {
+      addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+    }
+    // LEI (privacidade do payload): os extras do push só viajam quando quem
+    // abre a URL é o PRÓPRIO app. O payload carrega `pm_rcpt` — a prova do
+    // recibo daquela mensagem —, `pm_msg_id` e todo bloco `pm_*`; anexá-los a
+    // um ACTION_VIEW implícito entrega o pacote inteiro a QUEM resolver a URL:
+    // o navegador ou qualquer app que declare intent-filter para o
+    // esquema/host (registrar esquema alheio é trivial no Android). Dado do
+    // nosso contrato não entra em processo de terceiro de graça — e cada campo
+    // novo do payload herda esta regra sem ninguém precisar lembrar.
+    // Degradação combinada: em destino externo o JS não recebe os extras, mas
+    // o clique JÁ foi contado acima (postarRecibo) e a navegação acontece
+    // igual — perde-se contexto, nunca a função.
+    if (ehDoProprioApp(i)) {
+      for ((k, v) in data) i.putExtra(k, v)
+    }
+    startActivity(i)
+    true
+  } catch (_: Throwable) {
+    // sem navegador ou esquema que ninguém trata: melhor abrir o app do que
+    // deixar o toque sem efeito
+    false
+  }
+
+  /**
+   * O destino da URL é o PRÓPRIO app (deep link nosso)?
+   *
+   * Resolve o intent como o sistema resolveria e compara o vencedor com o
+   * nosso `packageName`. O intent segue IMPLÍCITO de propósito: com
+   * `setPackage` forçaríamos o app mesmo quando o sistema mandaria para o
+   * navegador (App Link não verificado), mudando o destino do toque — aqui só
+   * decidimos o que ANEXAR, nunca para onde ir.
+   *
+   * Filtro de visibilidade de pacotes (Android 11+) joga a favor: o próprio
+   * pacote é SEMPRE visível, então deep link nosso resolve certo; navegador de
+   * terceiro pode voltar `null` sem `<queries>` e cai no ramo seguro (sem
+   * extras). Chooser do sistema (vários candidatos) também não é o nosso
+   * pacote ⇒ sem extras. Na dúvida, o intent vai limpo.
+   */
+  private fun ehDoProprioApp(intent: Intent): Boolean = runCatching {
+    packageManager.resolveActivity(intent, 0)?.activityInfo?.packageName == packageName
+  }.getOrDefault(false)
+
+  private fun abrirApp(data: Map<String, String>) {
+    val launch = packageManager.getLaunchIntentForPackage(packageName) ?: return
+    for ((k, v) in data) launch.putExtra(k, v)
+    launch.addFlags(
+      Intent.FLAG_ACTIVITY_NEW_TASK or
+        Intent.FLAG_ACTIVITY_SINGLE_TOP or
+        Intent.FLAG_ACTIVITY_CLEAR_TOP,
+    )
+    runCatching { startActivity(launch) }
+  }
+}