@pushmesh/sdk 0.7.2

package/ios/PushMeshApns.swift

@@ -0,0 +1,746 @@
+import CryptoKit
+import Foundation
+import Network
+import React
+import UIKit
+import UserNotifications
+
+/**
+ * Módulo nativo iOS do modo ZERO-CONFIG: APNs DIRETO — sem Firebase e sem
+ * GoogleService-Info.plist no app do cliente (a chave .p8 fica no painel do
+ * servidor PUSHMESH).
+ *
+ * - getToken(): devolve o token APNs cru (64 hex). Se ainda não capturado,
+ *   chama registerForRemoteNotifications() e resolve quando o delegate chegar
+ *   (timeout de 10s com erro que ensina).
+ * - O token é capturado via METHOD SWIZZLING dos callbacks de APNs do
+ *   AppDelegate. Por quê: exigir código no AppDelegate do host quebraria a
+ *   premissa zero-config. É a técnica padrão de mercado para SDKs
+ *   "zero-código", e aqui é feita do jeito seguro: o IMP original (próprio ou
+ *   herdado) é SEMPRE encadeado — outro SDK que também faça swizzling convive,
+ *   porque cada camada chama a anterior. Quem lembra o original é o
+ *   `PushMeshSwizzleRegistro`, POR CLASSE: leia as leis lá (troca de classe
+ *   de delegate A→B→A e encadeamento entre SDKs já quebraram este arquivo).
+ * - Evento "PushMeshApnsToken" quando o token MUDA (o JS re-registra o
+ *   player). Vai pelo RCTEventEmitter → chega ao JS via DeviceEventEmitter.
+ *
+ * A PERMISSÃO de notificação NÃO é pedida aqui — já é responsabilidade do
+ * notifee (src/permissions.ts). registerForRemoteNotifications() com a
+ * permissão negada simplesmente não entrega token (didFail/timeout).
+ *
+ * Módulo old-arch (RCTEventEmitter/NativeModule): funciona na New
+ * Architecture (Fabric) via interop layer do RN. TurboModule/codegen fica
+ * para uma fase posterior.
+ */
+@objc(PushMeshApns)
+final class PushMeshApns: RCTEventEmitter {
+
+  // MARK: - Estado
+
+  private static weak var shared: PushMeshApns?
+  private var apnsToken: String?
+  private var hasListeners = false
+  private var pendentes: [(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock)] = []
+
+  private static let timeoutSegundos: TimeInterval = 10
+
+  override init() {
+    super.init()
+    PushMeshApns.shared = self
+    // O swizzling acontece na 1ª instanciação do módulo (boot do SDK). Em apps
+    // RN o AppDelegate já existe nesse momento; requiresMainQueueSetup = true
+    // garante que isto roda na main queue.
+    PushMeshApns.swizzleAppDelegate()
+  }
+
+  override static func requiresMainQueueSetup() -> Bool { true }
+
+  override func supportedEvents() -> [String]! {
+    ["PushMeshApnsToken", "PushMeshApnsMessage", "PushMeshApnsClick"]
+  }
+
+  override func startObserving() {
+    hasListeners = true
+    // o JS assinou os eventos: garante o swizzling do delegate de
+    // notificações (o notifee/host pode tê-lo definido DEPOIS do nosso init)
+    DispatchQueue.main.async { PushMeshApns.swizzleNotificationDelegateSePreciso() }
+  }
+  override func stopObserving() { hasListeners = false }
+
+  // MARK: - API JS
+
+  /// Garante o registro no APNs (idempotente no sistema).
+  @objc func register() {
+    DispatchQueue.main.async {
+      PushMeshApns.swizzleNotificationDelegateSePreciso()
+      UIApplication.shared.registerForRemoteNotifications()
+    }
+  }
+
+  /**
+   * Abre DIRETO a tela de Notificações do app nos Ajustes (iOS 16+).
+   *
+   * Por que existe: `Linking.openSettings()` abre a página GERAL do app — e
+   * quando o app nunca pediu permissão ele sequer TEM página lá, então o
+   * sistema abre a raiz dos Ajustes e a pessoa se perde. O
+   * `openNotificationSettingsURLString` é a API PÚBLICA da Apple
+   * para o atalho certo; `App-prefs:` seria privada e reprovaria na revisão.
+   *
+   * Resolve `false` quando não dá (iOS < 16 ou URL recusada) — aí o JS cai no
+   * caminho padrão. Nunca lança: o push jamais derruba o app do cliente.
+   */
+  @objc func abrirAjustesDeNotificacao(_ resolve: @escaping RCTPromiseResolveBlock,
+                                       rejecter reject: @escaping RCTPromiseRejectBlock) {
+    DispatchQueue.main.async {
+      guard #available(iOS 16.0, *) else { resolve(false); return }
+      guard let url = URL(string: UIApplication.openNotificationSettingsURLString) else {
+        resolve(false); return
+      }
+      // sem canOpenURL de propósito (lição da casa: ele devolve false para
+      // esquema não declarado no Info.plist do host) — o próprio `open` diz se
+      // deu certo, e o JS cai no caminho padrão quando não dá.
+      UIApplication.shared.open(url, options: [:]) { ok in resolve(ok) }
+    }
+  }
+
+  /**
+   * Token APNs em hex (64 chars). SEMPRE pede um token fresco ao sistema
+   * (registerForRemoteNotifications dispara didRegister rápido quando já há
+   * registro) — rotação nunca fica escondida atrás de cache. No timeout,
+   * resolve o token pendente persistido (UserDefaults) se houver; só rejeita
+   * quando não há NADA (ex.: simulador sem capability).
+   */
+  @objc func getToken(_ resolve: @escaping RCTPromiseResolveBlock,
+                      rejecter reject: @escaping RCTPromiseRejectBlock) {
+    DispatchQueue.main.async {
+      if let token = self.apnsToken {
+        resolve(token) // capturado NESTE processo = fresco
+        return
+      }
+      self.pendentes.append((resolve, reject))
+      PushMeshApns.swizzleNotificationDelegateSePreciso()
+      UIApplication.shared.registerForRemoteNotifications()
+      DispatchQueue.main.asyncAfter(deadline: .now() + PushMeshApns.timeoutSegundos) { [weak self] in
+        guard let self = self, !self.pendentes.isEmpty else { return }
+        if let pendente = UserDefaults.standard.string(forKey: PushMeshApns.chaveTokenPendente) {
+          let pend = self.pendentes
+          self.pendentes.removeAll()
+          pend.forEach { $0.resolve(pendente) }
+          return
+        }
+        self.rejeitarPendentes(
+          codigo: "pushmesh_apns_timeout",
+          mensagem: "[PushMesh] token APNs não chegou em 10s. Como corrigir: rode num device FÍSICO " +
+            "com a capability 'Push Notifications' habilitada no Xcode (e Background Modes → " +
+            "Remote notifications). Simuladores antigos não recebem token APNs; se o app host " +
+            "gerencia o APNs por conta própria, prefira o modo host (getToken no init).",
+          erro: nil
+        )
+      }
+    }
+  }
+
+  /**
+   * Clique em notificação com o app MORTO (iOS): o didReceive chegou sem JS
+   * e o payload ficou guardado. Lê e LIMPA. null quando não houve clique.
+   */
+  @objc func getPendingClick(_ resolve: @escaping RCTPromiseResolveBlock,
+                             rejecter reject: @escaping RCTPromiseRejectBlock) {
+    let pendente = UserDefaults.standard.dictionary(forKey: PushMeshApns.chaveClickPendente)
+    UserDefaults.standard.removeObject(forKey: PushMeshApns.chaveClickPendente)
+    resolve(pendente ?? NSNull())
+  }
+
+  /**
+   * PERFIL DO APARELHO — nível GRATUITO de rastreamento (espelha o método
+   * homônimo do módulo Android; as chaves são as mesmas).
+   *
+   * Só o que NÃO pede permissão e NÃO altera a ficha de privacidade do app do
+   * cliente na App Store. IDFA e localização ficam de fora por decisão de
+   * produto: ambos alterariam a ficha de privacidade e exigiriam consentimento.
+   *
+   * `carrier` NÃO é reportado de propósito: a Apple deprecou `CTCarrier` na
+   * iOS 16 e ele devolve "--". Preferimos campo ausente a dado inventado.
+   *
+   * Nunca rejeita: perfil ausente não pode impedir o aparelho de registrar.
+   */
+  @objc func perfilDispositivo(_ resolve: @escaping RCTPromiseResolveBlock,
+                               rejecter reject: @escaping RCTPromiseRejectBlock) {
+    var perfil: [String: Any] = [
+      "device_os": UIDevice.current.systemVersion,
+      "fabricante": "Apple",
+      "modelo": PushMeshApns.modeloHardware(),
+      "rooted": PushMeshApns.indicioDeJailbreak(),
+    ]
+    if let rede = PushMeshApns.tipoDeRede() {
+      perfil["net_type"] = rede
+    }
+    if let bits = PushMeshApns.bitmaskNotificacoes() {
+      perfil["notif_permissoes"] = bits
+    }
+    if let inst = PushMeshApns.idDaInstalacao() {
+      perfil["instalacao_id"] = inst
+    }
+    resolve(perfil)
+  }
+
+  /**
+   * Identificador estável do APARELHO — em HASH, nunca cru.
+   *
+   * Fonte: `identifierForVendor` (IDFV). Não pede permissão, não é o IDFA (não
+   * exige ATT) e é escopado ao fornecedor: não correlaciona entre empresas.
+   * Sobrevive à reinstalação enquanto houver ao menos um app do mesmo
+   * fornecedor no aparelho — é o que permite derrubar o token fantasma na
+   * hora, sem esperar um envio falhar.
+   *
+   * SHA-256 truncado: comparar igualdade basta, e o valor cru fica no aparelho.
+   *
+   * KEYCHAIN FOI CONSIDERADO E DESCARTADO (decisão de produto — não é um
+   * esquecimento a ser "melhorado" depois: trocar a fonte aqui muda o id de
+   * TODO o parque de aparelhos de uma vez). Um id gravado no Keychain
+   * sobreviveria à desinstalação de TODOS os apps do fornecedor, e é
+   * exatamente aí que ele deixa de ser "identidade da instalação" e vira
+   * RASTREAMENTO do aparelho além do consentimento — o que a política da Apple
+   * veta sem ATT/permissão explícita. O IDFV, que zera quando o último app do
+   * fornecedor sai, é o limite que aceitamos: some o aparelho, some o id.
+   * Consequência ASSUMIDA e medida: no iOS a reinstalação não derruba o token
+   * fantasma como derruba no Android.
+   */
+  static func idDaInstalacao() -> String? {
+    guard let idfv = UIDevice.current.identifierForVendor?.uuidString else { return nil }
+    // POR QUE O SAL: não é anti-reversão — IDFV é UUID com ~122 bits
+    // aleatórios, força bruta não volta dele com ou sem sal. O sal fixo do SDK
+    // serve para DESCORRELACIONAR: outro SDK que hasheie o MESMO IDFV sem esse
+    // prefixo chega a outro dígito, então ninguém cruza o nosso id com o dele.
+    // Fixo (e não aleatório) de propósito: o id precisa ser reproduzível a
+    // cada boot, senão deixa de identificar a instalação.
+    let digest = SHA256.hash(data: Data("pushmesh:\(idfv)".utf8))
+    return digest.prefix(16).map { String(format: "%02x", $0) }.joined()
+  }
+
+  /**
+   * BITMASK granular da permissão (contrato da migration 0013 — mesmo do
+   * Android): 1=habilitadas · 2=alerta/banner · 4=som · 8=badge · 16=tela de
+   * bloqueio · 32=central de notificações. É o que diagnostica "tenho
+   * permissão mas não vejo nada" (alerta ok, banner desligado).
+   *
+   * getNotificationSettings é assíncrono; espera CURTA (500 ms) — sem
+   * resposta, o campo não vai (nunca atrasar o registro por diagnóstico).
+   */
+  private static func bitmaskNotificacoes() -> Int? {
+    var bits: Int?
+    let semaforo = DispatchSemaphore(value: 0)
+    UNUserNotificationCenter.current().getNotificationSettings { st in
+      var b = 0
+      switch st.authorizationStatus {
+      case .authorized, .provisional, .ephemeral: b |= 1
+      default: break
+      }
+      if b & 1 != 0 {
+        if st.alertSetting == .enabled { b |= 2 }
+        if st.soundSetting == .enabled { b |= 4 }
+        if st.badgeSetting == .enabled { b |= 8 }
+        if st.lockScreenSetting == .enabled { b |= 16 }
+        if st.notificationCenterSetting == .enabled { b |= 32 }
+      }
+      bits = b
+      semaforo.signal()
+    }
+    _ = semaforo.wait(timeout: .now() + 0.5)
+    return bits
+  }
+
+  /**
+   * Identificador de HARDWARE ("iPhone17,3") — não o nome comercial.
+   * `UIDevice.model` devolve só "iPhone"; o que distingue os modelos é o
+   * `utsname.machine`, e é dele que sai a tradução para nome comercial (feita
+   * no painel, não aqui: tabela de nomes envelhece e o aparelho não deve
+   * carregá-la).
+   */
+  private static func modeloHardware() -> String {
+    #if targetEnvironment(simulator)
+      // No simulador o utsname devolve a arquitetura do Mac ("arm64"), não o
+      // modelo emulado — o modelo real vem desta env (verificado em bancada).
+      return ProcessInfo.processInfo.environment["SIMULATOR_MODEL_IDENTIFIER"] ?? "Simulator"
+    #else
+      var info = utsname()
+      uname(&info)
+      return withUnsafeBytes(of: &info.machine) { buf in
+        guard let base = buf.baseAddress else { return UIDevice.current.model }
+        return String(cString: base.assumingMemoryBound(to: CChar.self))
+      }
+    #endif
+  }
+
+  /**
+   * Wi-Fi × celular no instante do registro. Snapshot com espera CURTA (200 ms):
+   * o `NWPathMonitor` é assíncrono e não vale atrasar o registro por um campo
+   * de diagnóstico — sem resposta, o campo simplesmente não vai.
+   */
+  private static func tipoDeRede() -> String? {
+    let monitor = NWPathMonitor()
+    let fila = DispatchQueue(label: "pushmesh.rede")
+    let semaforo = DispatchSemaphore(value: 0)
+    var resultado: String?
+    monitor.pathUpdateHandler = { path in
+      if path.status == .satisfied {
+        if path.usesInterfaceType(.wifi) {
+          resultado = "wifi"
+        } else if path.usesInterfaceType(.cellular) {
+          resultado = "celular"
+        } else {
+          resultado = "outro"
+        }
+      }
+      semaforo.signal()
+    }
+    monitor.start(queue: fila)
+    _ = semaforo.wait(timeout: .now() + 0.2)
+    monitor.cancel()
+    return resultado
+  }
+
+  /**
+   * Heurística de jailbreak — SINAL, não prova (jailbreak moderno se esconde).
+   * Insumo antifraude; `false` significa "não achamos indício", nunca
+   * "aparelho confiável".
+   */
+  private static func indicioDeJailbreak() -> Bool {
+    #if targetEnvironment(simulator)
+      return false // simulador tem sistema de arquivos aberto: daria falso positivo
+    #else
+      let caminhos = [
+        "/Applications/Cydia.app",
+        "/Applications/Sileo.app",
+        "/private/var/lib/apt/",
+        "/private/var/lib/cydia",
+        "/usr/sbin/sshd",
+        "/bin/bash",
+        "/etc/apt",
+      ]
+      let fm = FileManager.default
+      if caminhos.contains(where: { fm.fileExists(atPath: $0) }) { return true }
+      // escrever fora do sandbox só é possível com jailbreak
+      let fora = "/private/pushmesh_teste.txt"
+      if (try? "x".write(toFile: fora, atomically: true, encoding: .utf8)) != nil {
+        try? fm.removeItem(atPath: fora)
+        return true
+      }
+      return false
+    #endif
+  }
+
+  // MARK: - Callbacks vindos do swizzling
+
+  private func handleDidRegister(deviceToken: Data) {
+    let hex = deviceToken.map { String(format: "%02x", $0) }.joined()
+    let mudou = hex != apnsToken
+    apnsToken = hex
+    // token pendente SEMPRE persistido: rotação sem JS vivo é reconciliada
+    // no próximo boot (fallback do getToken).
+    UserDefaults.standard.set(hex, forKey: PushMeshApns.chaveTokenPendente)
+    let pend = pendentes
+    pendentes.removeAll()
+    pend.forEach { $0.resolve(hex) }
+    if mudou && hasListeners {
+      sendEvent(withName: "PushMeshApnsToken", body: hex)
+    }
+  }
+
+  /// Foreground (willPresent) ou clique (didReceive) → evento JS; sem JS
+  /// vivo, o CLIQUE fica pendente (getPendingClick no boot) — o foreground
+  /// sem JS não existe (app fechado não tem willPresent).
+  private func emitirNotificacao(_ evento: String, userInfo: [AnyHashable: Any], pendenteSeSemListener: Bool) {
+    if hasListeners {
+      sendEvent(withName: evento, body: userInfo as NSDictionary)
+    } else if pendenteSeSemListener {
+      UserDefaults.standard.set(userInfo as NSDictionary, forKey: PushMeshApns.chaveClickPendente)
+    }
+  }
+
+  private func handleDidFail(error: Error) {
+    rejeitarPendentes(
+      codigo: "pushmesh_apns_falhou",
+      mensagem: "[PushMesh] didFailToRegisterRemoteNotifications: \(error.localizedDescription). " +
+        "Como corrigir: confira a capability 'Push Notifications' no Xcode e use device físico.",
+      erro: error
+    )
+  }
+
+  private func rejeitarPendentes(codigo: String, mensagem: String, erro: Error?) {
+    let pend = pendentes
+    pendentes.removeAll()
+    pend.forEach { $0.reject(codigo, mensagem, erro) }
+  }
+
+  // MARK: - Method swizzling do AppDelegate
+
+  private typealias DidRegisterIMP = @convention(c) (AnyObject, Selector, UIApplication, Data) -> Void
+  private typealias DidFailIMP = @convention(c) (AnyObject, Selector, UIApplication, NSError) -> Void
+  private typealias WillPresentIMP = @convention(c) (
+    AnyObject, Selector, UNUserNotificationCenter, UNNotification,
+    @convention(block) (UNNotificationPresentationOptions) -> Void
+  ) -> Void
+  private typealias DidReceiveIMP = @convention(c) (
+    AnyObject, Selector, UNUserNotificationCenter, UNNotificationResponse,
+    @convention(block) () -> Void
+  ) -> Void
+
+  /**
+   * Espelho do `isNossa` do Android: a mensagem é NOSSA quando carrega alguma
+   * chave `pm_*` (bloco de exibição) ou `pm_*` (recibo/url). SEPARAÇÃO TOTAL
+   * (regra do produto): notificação de outro SDK atravessa o embrulho
+   * sem que a gente emita evento, persista clique ou abra URL — só o IMP
+   * original é encadeado.
+   */
+  static func ehNossa(_ userInfo: [AnyHashable: Any]) -> Bool {
+    for chave in userInfo.keys {
+      if let k = chave as? String, k.hasPrefix("pmx_") || k.hasPrefix("pm_") { return true }
+    }
+    return false
+  }
+
+  static let chaveTokenPendente = "pmx_pending_token"
+  static let chaveClickPendente = "pmx_pending_click"
+
+  private static var ganchoSetDelegateFeito = false
+  /**
+   * Toques já processados: identifier → instante.
+   *
+   * POR QUE NÃO UM SLOT ÚNICO (era `ultimoToqueId` + `ultimoToqueEm`):
+   * guardando só o ÚLTIMO toque, duas notificações INTERCALADAS furavam o
+   * dedup. O usuário toca A e logo B; o encadeamento de delegates não é
+   * garantidamente síncrono (um SDK que despacha para o JS pode reentrar
+   * depois), então a reentrada de A chegava DEPOIS de B ter tomado o slot — A
+   * passava de novo e a `pm_url` abria DUAS vezes. O LRU do lado JS não cobre
+   * isso: ele dedupa RECIBO por `pm_msg_id`, enquanto a abertura da URL é 100%
+   * nativa (foi o sintoma real, visto em campo, que este dedup veio matar).
+   *
+   * É o espelho do LRU do JS, em miniatura: janela de 5 s, teto de 16 ids
+   * (rajada anormal não pode virar vazamento de memória) e poda a cada
+   * consulta. NSLock porque `willPresent`/`didReceive` não têm garantia
+   * DOCUMENTADA de fila única — barato e tira a dúvida.
+   */
+  private static var toquesVistos: [String: TimeInterval] = [:]
+  private static let travaToques = NSLock()
+  private static let janelaToqueSegundos: TimeInterval = 5
+  private static let tetoToquesVistos = 16
+
+  /// true na PRIMEIRA passagem de um toque; false nas repetições do
+  /// encadeamento de delegates (janela de 5 s por identifier).
+  static func primeiraVezDoToque(_ id: String) -> Bool {
+    travaToques.lock()
+    defer { travaToques.unlock() }
+    let agora = Date().timeIntervalSince1970
+    // poda o que saiu da janela: o dicionário só guarda toque "quente"
+    toquesVistos = toquesVistos.filter { agora - $0.value < janelaToqueSegundos }
+    if toquesVistos[id] != nil { return false }
+    if toquesVistos.count >= tetoToquesVistos,
+       let maisAntigo = toquesVistos.min(by: { $0.value < $1.value })?.key {
+      toquesVistos.removeValue(forKey: maisAntigo)
+    }
+    toquesVistos[id] = agora
+    return true
+  }
+  /**
+   * O IMP original NUNCA mora numa estática única aqui — mora no
+   * `PushMeshSwizzleRegistro`, indexado por (classe, seletor), e cada bloco
+   * resolve pela classe em que ELE foi instalado (capturada na instalação).
+   * Pela classe do ALVO era quase certo — e caía no terceiro loop: subclasse
+   * que SOBRESCREVE o método e chama `super` (super → nosso bloco na
+   * ancestral → resolvendo pelo alvo achava o original da PRÓPRIA subclasse →
+   * sobrescrita de novo → ciclo).
+   *
+   * A LEI (dois defeitos reais que a estática única causava):
+   * - A→B→A: delegate da classe A embrulhado, host troca para B (a estática
+   *   passava a apontar para o original de B) e depois volta para A. Ao
+   *   re-embrulhar A, o "original" devolvido pelo runtime é O NOSSO PRÓPRIO
+   *   BLOCO → o bloco chamava a si mesmo → recursão infinita → o app do
+   *   cliente morre de stack overflow no primeiro push;
+   * - encadeamento entre SDKs: quem substitui o delegate costuma guardar o
+   *   anterior e encaminhar a ele. Com a estática única, o bloco da classe A
+   *   encadeava o IMP de B (corpo de outra classe com `self` de A) e fechava o
+   *   ciclo B→A→B. Nem o ramo de dedup salvava: ele também encadeia o
+   *   original.
+   *
+   * Estes quatro atalhos tipados existem só para converter o IMP cru do
+   * registro na assinatura C certa de cada callback.
+   */
+  private static func originalDidRegister(instaladaEm classe: AnyClass) -> DidRegisterIMP? {
+    PushMeshSwizzleRegistro.original(paraClasse: classe, seletor: didRegisterSel)
+      .map { unsafeBitCast($0, to: DidRegisterIMP.self) }
+  }
+  private static func originalDidFail(instaladaEm classe: AnyClass) -> DidFailIMP? {
+    PushMeshSwizzleRegistro.original(paraClasse: classe, seletor: didFailSel)
+      .map { unsafeBitCast($0, to: DidFailIMP.self) }
+  }
+  private static func originalWillPresent(instaladaEm classe: AnyClass) -> WillPresentIMP? {
+    PushMeshSwizzleRegistro.original(paraClasse: classe, seletor: willPresentSel)
+      .map { unsafeBitCast($0, to: WillPresentIMP.self) }
+  }
+  private static func originalDidReceive(instaladaEm classe: AnyClass) -> DidReceiveIMP? {
+    PushMeshSwizzleRegistro.original(paraClasse: classe, seletor: didReceiveSel)
+      .map { unsafeBitCast($0, to: DidReceiveIMP.self) }
+  }
+
+  private static let didRegisterSel =
+    #selector(UIApplicationDelegate.application(_:didRegisterForRemoteNotificationsWithDeviceToken:))
+  // ATENÇÃO ao "For": o seletor real é
+  // `application:didFailToRegisterForRemoteNotificationsWithError:`. Sem o
+  // "For" o Swift não acha o membro no protocolo e a compilação do app do
+  // cliente quebra (não é aviso — é erro de build).
+  private static let didFailSel =
+    #selector(UIApplicationDelegate.application(_:didFailToRegisterForRemoteNotificationsWithError:))
+  private static let willPresentSel =
+    #selector(UNUserNotificationCenterDelegate.userNotificationCenter(_:willPresent:withCompletionHandler:))
+  private static let didReceiveSel =
+    #selector(UNUserNotificationCenterDelegate.userNotificationCenter(_:didReceive:withCompletionHandler:))
+
+  /**
+   * Swizzling do delegate do UNUserNotificationCenter (foreground + clique) —
+   * mesmo cuidado do swizzling de registro: o IMP original (do notifee, que
+   * costuma ser o delegate, ou do host) é SEMPRE encadeado; sem delegate/
+   * original, o willPresent exibe banner+som e o didReceive só completa.
+   * Idempotente por CLASSE do delegate: se o host trocar o delegate depois
+   * (ex.: notifee se instalando), re-swizzla a classe nova.
+   */
+  /**
+   * Ponto de entrada chamado do `+load` (PushMeshApnsModule.m) quando o app
+   * termina de abrir — ANTES de o sistema entregar o toque que abriu o app.
+   *
+   * Por que existe: o `UNUserNotificationCenter` só entrega
+   * `didReceive` a quem já é delegate quando o launch termina. Nosso swizzle
+   * acontecia na criação do módulo React (depois disso), então o TOQUE COM O
+   * APP FECHADO era perdido em silêncio — clique não contava e a `pm_url` não
+   * abria. Aqui garantimos presença desde o início.
+   */
+  /**
+   * Abre a URL do clique — esperando o app estar ATIVO.
+   *
+   * `UIApplication.open` durante o launch é descartado pelo sistema. No toque
+   * com o app fechado o estado ainda é `.inactive`, então observamos
+   * `didBecomeActive` UMA vez e abrimos aí. Se já estiver ativo (toque com o
+   * app em segundo plano), abre na hora.
+   */
+  @objc static func abrirUrlQuandoAtivo(_ endereco: String) {
+    let texto = endereco.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !texto.isEmpty, let url = URL(string: texto) else { return }
+
+    let abrir = {
+      DispatchQueue.main.async {
+        NSLog("[PushMesh] abrindo pm_url: %@", texto)
+        // SEM canOpenURL DE PROPÓSITO (lei do zero-config): desde o iOS 9 o
+        // `canOpenURL` devolve false para QUALQUER esquema custom que o app
+        // host não tenha declarado em LSApplicationQueriesSchemes — inclusive
+        // o esquema do próprio app. Como o SDK promete não pedir nada no
+        // Info.plist do cliente, o guard reprovava todo deep link
+        // (`meuapp://tela`, que é o `app_url` do contrato do servidor) e o
+        // toque "não fazia nada" — só no iOS, e em silêncio. O `open` NÃO
+        // exige declaração alguma e já reporta o fracasso no completion: é lá
+        // que o erro ENSINA, e é o mesmo desenho do trampolim do Android.
+        UIApplication.shared.open(url, options: [:]) { ok in
+          if ok {
+            NSLog("[PushMesh] pm_url aberta: %@", texto)
+          } else {
+            NSLog("[PushMesh] pm_url NÃO abriu: %@ — nenhum app instalado atende o esquema \"%@\". " +
+                  "Como corrigir: use https:// (abre no navegador/Universal Link) ou confira o " +
+                  "esquema do deep link — ele precisa estar em CFBundleURLTypes do app que deve abrir.",
+                  texto, url.scheme ?? "<sem esquema>")
+          }
+        }
+      }
+    }
+
+    DispatchQueue.main.async {
+      if UIApplication.shared.applicationState == .active {
+        abrir()
+        return
+      }
+      var token: NSObjectProtocol?
+      token = NotificationCenter.default.addObserver(
+        forName: UIApplication.didBecomeActiveNotification,
+        object: nil,
+        queue: .main
+      ) { _ in
+        if let t = token { NotificationCenter.default.removeObserver(t) }
+        abrir()
+      }
+    }
+  }
+
+  @objc static func instalarSwizzleDelegate() {
+    DispatchQueue.main.async { swizzleNotificationDelegateSePreciso() }
+  }
+
+  /**
+   * Gancho no `setDelegate:` do UNUserNotificationCenter — chamado do `+load`,
+   * antes de qualquer delegate existir.
+   *
+   * POR QUE ISTO É NECESSÁRIO: `swizzleNotificationDelegateSePreciso()` desiste
+   * quando ainda não há delegate (`guard let … else { return }`), e no arranque
+   * frio é exatamente esse o estado. O notifee/host define o delegate DEPOIS —
+   * e o toque que abriu o app já tinha se perdido. Interceptando a ATRIBUIÇÃO,
+   * embrulhamos o delegate no instante em que ele nasce, seja quem for e
+   * quando for. Foi este o defeito real de "no iOS vai direto pro app".
+   */
+  @objc static func instalarGanchoSetDelegate() {
+    guard !ganchoSetDelegateFeito else { return }
+    ganchoSetDelegateFeito = true
+
+    let cls: AnyClass = UNUserNotificationCenter.self
+    let sel = NSSelectorFromString("setDelegate:")
+    guard let metodo = class_getInstanceMethod(cls, sel) else {
+      NSLog("[PushMesh] gancho setDelegate: método não encontrado")
+      return
+    }
+    typealias SetDelegateIMP = @convention(c) (AnyObject, Selector, AnyObject?) -> Void
+    let originalFn = unsafeBitCast(method_getImplementation(metodo), to: SetDelegateIMP.self)
+
+    let bloco: @convention(block) (AnyObject, AnyObject?) -> Void = { alvo, novoDelegate in
+      originalFn(alvo, sel, novoDelegate)
+      if novoDelegate != nil {
+        // o delegate acabou de nascer: embrulha AGORA
+        swizzleNotificationDelegateSePreciso()
+      }
+    }
+    method_setImplementation(metodo, imp_implementationWithBlock(bloco))
+
+    // Caso raro: alguém já definiu o delegate antes do nosso +load.
+    swizzleNotificationDelegateSePreciso()
+  }
+
+  static func swizzleNotificationDelegateSePreciso() {
+    guard let delegate = UNUserNotificationCenter.current().delegate else {
+      NSLog("[PushMesh] delegate de notificações ainda não existe — o gancho do setDelegate pega quando nascer")
+      return
+    }
+    let cls: AnyClass = type(of: delegate)
+    // Idempotente por CLASSE (não "pela última classe vista"): no A→B→A a
+    // classe A já está embrulhada e re-embrulhar capturaria o NOSSO bloco como
+    // original — recursão infinita. Quem sabe disso é o registro.
+    guard !PushMeshSwizzleRegistro.jaEmbrulhada(cls, willPresentSel)
+      || !PushMeshSwizzleRegistro.jaEmbrulhada(cls, didReceiveSel) else { return }
+    NSLog("[PushMesh] delegate de notificações embrulhado: %@", NSStringFromClass(cls))
+
+    let blocoWill: @convention(block) (
+      AnyObject, UNUserNotificationCenter, UNNotification,
+      @convention(block) (UNNotificationPresentationOptions) -> Void
+    ) -> Void = { alvo, center, notification, completion in
+      let infoWill = notification.request.content.userInfo
+      if PushMeshApns.ehNossa(infoWill) {
+        PushMeshApns.shared?.emitirNotificacao(
+          "PushMeshApnsMessage",
+          userInfo: infoWill,
+          pendenteSeSemListener: false
+        )
+      }
+      // o original é o da classe onde ESTE bloco foi instalado (capturada no
+      // embrulho) — nunca o do último delegate embrulhado, nem o da classe do
+      // alvo (subclasse que sobrescreve e chama super entraria em ciclo).
+      if let original = PushMeshApns.originalWillPresent(instaladaEm: cls) {
+        original(alvo, PushMeshApns.willPresentSel, center, notification, completion)
+      } else {
+        completion([.banner, .list, .sound])
+      }
+    }
+    PushMeshSwizzleRegistro.instalar(classe: cls, seletor: willPresentSel, tipos: "v@:@@@",
+                                      nossoImp: imp_implementationWithBlock(blocoWill))
+
+    let blocoClick: @convention(block) (
+      AnyObject, UNUserNotificationCenter, UNNotificationResponse,
+      @convention(block) () -> Void
+    ) -> Void = { alvo, center, response, completion in
+      // SEPARAÇÃO TOTAL: toque em notificação de OUTRO SDK não é assunto nosso
+      // — nada de evento, recibo, clique pendente ou URL. Só encadeia.
+      guard PushMeshApns.ehNossa(response.notification.request.content.userInfo) else {
+        if let original = PushMeshApns.originalDidReceive(instaladaEm: cls) {
+          original(alvo, PushMeshApns.didReceiveSel, center, response, completion)
+        } else {
+          completion()
+        }
+        return
+      }
+      // DEDUP do toque: os delegates embrulhados se ENCADEIAM (um SDK de push
+      // costuma chamar o delegate anterior, e cada classe passa pelo bloco) — sem isto o
+      // mesmo toque processava DUAS vezes: duas aberturas de URL e dois
+      // recibos (visto em teste de campo). O original é SEMPRE
+      // encadeado; só o NOSSO processamento é único por toque.
+      guard PushMeshApns.primeiraVezDoToque(response.notification.request.identifier) else {
+        if let original = PushMeshApns.originalDidReceive(instaladaEm: cls) {
+          original(alvo, PushMeshApns.didReceiveSel, center, response, completion)
+        } else {
+          completion()
+        }
+        return
+      }
+      // O toque pode chegar ANTES de o módulo React existir (arranque frio:
+      // o swizzle é instalado no +load, mas `shared` só nasce quando a ponte
+      // RN cria os módulos). Sem esta guarda o clique se perdia em silêncio —
+      // era este o caso do "iOS não aponta para o link".
+      let userInfo = response.notification.request.content.userInfo
+
+      // pm_url é aberta AQUI, no nativo — não no JS. Duas razões:
+      // 1. no arranque frio o JS pode nem existir ainda quando o toque chega;
+      // 2. `Linking.openURL` durante o launch é descartado pelo iOS em
+      //    silêncio (o app abria e o link não).
+      // O nativo espera o app ficar ATIVO e abre com UIApplication.open, que é
+      // o mesmo caminho que o trampolim do Android usa.
+      NSLog("[PushMesh] TOQUE recebido no nativo (pm_url=%@)",
+            (userInfo["pm_url"] as? String) ?? "<sem url>")
+      if let url = userInfo["pm_url"] as? String {
+        PushMeshApns.abrirUrlQuandoAtivo(url)
+      }
+
+      if let instancia = PushMeshApns.shared {
+        instancia.emitirNotificacao(
+          "PushMeshApnsClick",
+          userInfo: userInfo,
+          pendenteSeSemListener: true
+        )
+      } else {
+        UserDefaults.standard.set(userInfo as NSDictionary, forKey: PushMeshApns.chaveClickPendente)
+      }
+      if let original = PushMeshApns.originalDidReceive(instaladaEm: cls) {
+        original(alvo, PushMeshApns.didReceiveSel, center, response, completion)
+      } else {
+        completion()
+      }
+    }
+    PushMeshSwizzleRegistro.instalar(classe: cls, seletor: didReceiveSel, tipos: "v@:@@@",
+                                      nossoImp: imp_implementationWithBlock(blocoClick))
+  }
+
+  static func swizzleAppDelegate() {
+    guard let delegate = UIApplication.shared.delegate else {
+      NSLog("[PushMesh] AppDelegate ausente na 1ª instanciação — swizzling APNs não instalado; " +
+            "getToken pode falhar neste boot.")
+      return
+    }
+    let cls: AnyClass = type(of: delegate)
+    // idempotência por CLASSE (era um `swizzleFeito` global): se o AppDelegate
+    // trocar de classe, a classe nova também é embrulhada — e a antiga
+    // continua com o encadeamento certo, porque o original mora por classe.
+    guard !PushMeshSwizzleRegistro.jaEmbrulhada(cls, didRegisterSel)
+      || !PushMeshSwizzleRegistro.jaEmbrulhada(cls, didFailSel) else { return }
+
+    // didRegisterForRemoteNotificationsWithDeviceToken
+    let blocoReg: @convention(block) (AnyObject, UIApplication, Data) -> Void = { alvo, app, deviceToken in
+      PushMeshApns.shared?.handleDidRegister(deviceToken: deviceToken)
+      if let original = PushMeshApns.originalDidRegister(instaladaEm: cls) {
+        original(alvo, PushMeshApns.didRegisterSel, app, deviceToken)
+      }
+    }
+    PushMeshSwizzleRegistro.instalar(classe: cls, seletor: didRegisterSel, tipos: "v@:@@",
+                                      nossoImp: imp_implementationWithBlock(blocoReg))
+
+    // didFailToRegisterRemoteNotificationsWithError
+    let blocoErro: @convention(block) (AnyObject, UIApplication, NSError) -> Void = { alvo, app, erro in
+      PushMeshApns.shared?.handleDidFail(error: erro)
+      if let original = PushMeshApns.originalDidFail(instaladaEm: cls) {
+        original(alvo, PushMeshApns.didFailSel, app, erro)
+      }
+    }
+    PushMeshSwizzleRegistro.instalar(classe: cls, seletor: didFailSel, tipos: "v@:@@",
+                                      nossoImp: imp_implementationWithBlock(blocoErro))
+  }
+}