react-native-push-signal 0.1.8 → 0.1.10

package/PushSignal.podspec

@@ -11,7 +11,7 @@ Pod::Spec.new do |s|
   s.authors      = package["author"]
 
   s.platforms    = { :ios => min_ios_version_supported }
-  s.source       = { :git => "https://antonseagull.com.git", :tag => "#{s.version}" }
+  s.source       = { :git => "https://github.com/AntonSeagull/react-native-push-signal.git", :tag => "#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,cpp}"
   s.private_header_files = "ios/**/*.h"

package/README.md

@@ -108,6 +108,70 @@ Without `initialize(...)` or that file, `getCredentials()` throws.
 
 If the host app already declares its own `FirebaseMessagingService`, only one service can handle `com.google.firebase.MESSAGING_EVENT`. Prefer this library’s service or forward events into it.
 
+### When it fails on Xiaomi: `SERVICE_NOT_AVAILABLE`
+
+If `getCredentials()` throws `Failed to get an FCM token: SERVICE_NOT_AVAILABLE`, the FCM token could not be obtained. Your server never receives a token, so there is nowhere to send pushes — delivery itself is not the problem.
+
+Before requesting the token the library checks Google Play services and retries a few times with backoff, but some causes can only be fixed on the device:
+
+- **Google account.** The device must be signed into a Google account. FCM does not issue a token without one.
+- **Google Play services.** They must be installed, enabled and up to date. On a China-only ROM without GMS, FCM cannot work at all — you need another push provider; see [Detecting a non-Google device](#detecting-a-non-google-device-getdiagnostics-and-pushsignalerror).
+- **Network.** Check connectivity and disable VPN and private DNS.
+- **MIUI / HyperOS.** Enable autostart and remove battery restrictions: Settings → Apps → your app → Autostart; Battery → No restrictions. Allow background data for the app.
+
+What to look for in the logs:
+
+```sh
+adb logcat | grep -iE "SERVICE_NOT_AVAILABLE|FirebaseMessaging|PushSignal"
+```
+
+### Detecting a non-Google device: `getDiagnostics()` and `PushSignalError`
+
+When Google Play services cannot serve FCM, the library detects it and tells you which service to use instead — both in the error message and as structured data, so the cause is visible in React Native logs.
+
+`initialize()` and `getCredentials()` reject with `PushSignalError`:
+
+```ts
+import { getCredentials, PushSignalError } from 'react-native-push-signal';
+
+try {
+  const credentials = await getCredentials();
+} catch (error) {
+  if (error instanceof PushSignalError) {
+    console.warn(error.code); // E_GMS_MISSING, E_FCM_TOKEN, ...
+    console.warn(error.message); // "... Use HMS Push Kit (Huawei Push) instead of the standard Google service."
+    console.warn(error.provider); // 'hms'
+    console.warn(error.hint); // actionable sentence
+    console.warn(error.diagnostics); // full device/provider snapshot
+  }
+}
+```
+
+You can also inspect diagnostics without requesting a token:
+
+```ts
+import { getDiagnostics } from 'react-native-push-signal';
+
+const diagnostics = await getDiagnostics();
+// { platform, gmsAvailable, gmsStatus, manufacturer, brand, model,
+//   provider, providerName, providerInstalled?, hint? }
+```
+
+Provider suggested when GMS is unavailable:
+
+| Manufacturer                | `provider`   | Service                                 |
+| --------------------------- | ------------ | --------------------------------------- |
+| HUAWEI / HONOR              | `hms`        | HMS Push Kit (Huawei Push)              |
+| Xiaomi / Redmi / POCO       | `mi_push`    | Mi Push (Xiaomi Push)                   |
+| OPPO / OnePlus / realme     | `oppo_push`  | OPPO Push (HeyTap)                      |
+| vivo / iQOO                 | `vivo_push`  | vivo Push                               |
+| Meizu                       | `meizu_push` | Meizu Push                              |
+| anything else               | `unknown`    | generic “use another provider”          |
+
+`providerInstalled` is `true` only when the provider service app was positively found on the device (`com.huawei.hwid`, `com.xiaomi.xmsf`); otherwise it is omitted. iOS always reports `provider: 'apns'`. The library never logs for you — pass the data wherever you need.
+
+Error codes: `E_GMS_MISSING`, `E_GMS_DISABLED`, `E_GMS_UPDATE_REQUIRED`, `E_GMS_INVALID`, `E_GMS_UNAVAILABLE`, `E_FCM_TOKEN`, `E_FIREBASE_CONFIG`, `E_NOT_INITIALIZED`.
+
 ## Incoming messages vs taps
 
 | App state | iOS | Android (notification payload) | Android (data-only) |

package/README.ru.md

@@ -108,6 +108,70 @@ apply plugin: "com.google.gms.google-services"
 
 Если в хост-приложении уже есть свой `FirebaseMessagingService`, обработать `com.google.firebase.MESSAGING_EVENT` может только один сервис. Оставьте сервис этой библиотеки или пробрасывайте события в него.
 
+### Если не работает на Xiaomi: `SERVICE_NOT_AVAILABLE`
+
+Если `getCredentials()` бросает `Failed to get an FCM token: SERVICE_NOT_AVAILABLE`, значит не удалось получить FCM-токен. Сервер не получает токен и слать пуши некуда — сама доставка здесь ни при чём.
+
+Перед запросом токена библиотека проверяет Google Play services и делает несколько попыток с паузами, но часть причин лечится только на устройстве:
+
+- **Google-аккаунт.** На устройстве должен быть выполнен вход в Google-аккаунт. Без него FCM токен не выдаёт.
+- **Google Play services.** Должны быть установлены, включены и обновлены. На китайской прошивке без GMS FCM не заработает в принципе — нужен другой провайдер пушей; см. [Определение не‑Google устройства](#определение-неgoogle-устройства-getdiagnostics-и-pushsignalerror).
+- **Сеть.** Проверьте интернет, отключите VPN и приватный DNS.
+- **MIUI / HyperOS.** Включите автозапуск и снимите ограничения батареи: Настройки → Приложения → «ваше приложение» → Автозапуск; Батарея → Без ограничений. Разрешите приложению фоновые данные.
+
+Что смотреть в логах:
+
+```sh
+adb logcat | grep -iE "SERVICE_NOT_AVAILABLE|FirebaseMessaging|PushSignal"
+```
+
+### Определение не‑Google устройства: `getDiagnostics()` и `PushSignalError`
+
+Когда Google Play services не могут обслуживать FCM, библиотека это определяет и подсказывает, какой сервис использовать вместо стандартного — в тексте ошибки и в структурированном виде, чтобы причина была видна в логах React Native.
+
+`initialize()` и `getCredentials()` отклоняются с `PushSignalError`:
+
+```ts
+import { getCredentials, PushSignalError } from 'react-native-push-signal';
+
+try {
+  const credentials = await getCredentials();
+} catch (error) {
+  if (error instanceof PushSignalError) {
+    console.warn(error.code); // E_GMS_MISSING, E_FCM_TOKEN, ...
+    console.warn(error.message); // "... Use HMS Push Kit (Huawei Push) instead of the standard Google service."
+    console.warn(error.provider); // 'hms'
+    console.warn(error.hint); // готовая подсказка
+    console.warn(error.diagnostics); // полный снимок устройства и провайдера
+  }
+}
+```
+
+Диагностику можно получить и без запроса токена:
+
+```ts
+import { getDiagnostics } from 'react-native-push-signal';
+
+const diagnostics = await getDiagnostics();
+// { platform, gmsAvailable, gmsStatus, manufacturer, brand, model,
+//   provider, providerName, providerInstalled?, hint? }
+```
+
+Провайдер, который предлагается при недоступных GMS:
+
+| Производитель            | `provider`   | Сервис                             |
+| ------------------------ | ------------ | ---------------------------------- |
+| HUAWEI / HONOR           | `hms`        | HMS Push Kit (Huawei Push)         |
+| Xiaomi / Redmi / POCO    | `mi_push`    | Mi Push (Xiaomi Push)              |
+| OPPO / OnePlus / realme  | `oppo_push`  | OPPO Push (HeyTap)                 |
+| vivo / iQOO              | `vivo_push`  | vivo Push                          |
+| Meizu                    | `meizu_push` | Meizu Push                         |
+| остальные                | `unknown`    | общая подсказка «нужен другой»     |
+
+`providerInstalled` равно `true` только если сервис-приложение провайдера действительно найдено на устройстве (`com.huawei.hwid`, `com.xiaomi.xmsf`), иначе поле отсутствует. iOS всегда сообщает `provider: 'apns'`. Библиотека сама ничего не логирует — передавайте данные туда, куда нужно.
+
+Коды ошибок: `E_GMS_MISSING`, `E_GMS_DISABLED`, `E_GMS_UPDATE_REQUIRED`, `E_GMS_INVALID`, `E_GMS_UNAVAILABLE`, `E_FCM_TOKEN`, `E_FIREBASE_CONFIG`, `E_NOT_INITIALIZED`.
+
 ## Входящее сообщение и тап
 
 | Состояние | iOS | Android (notification payload) | Android (data-only) |

package/android/build.gradle

@@ -51,5 +51,6 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation "androidx.activity:activity-ktx:1.10.1"
   implementation "androidx.core:core-ktx:1.16.0"
+  implementation "com.google.android.gms:play-services-base:18.5.0"
   implementation "com.google.firebase:firebase-messaging:24.1.2"
 }

package/android/src/main/AndroidManifest.xml

@@ -1,6 +1,13 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
   <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
+  <!-- Android 11+ package visibility: lets isPackageInstalled() confirm an
+       alternative push provider on the device. -->
+  <queries>
+    <package android:name="com.huawei.hwid" />
+    <package android:name="com.xiaomi.xmsf" />
+  </queries>
+
   <application>
     <provider
       android:name="com.pushsignal.PushSignalInitProvider"

package/android/src/main/java/com/pushsignal/PushModels.kt

@@ -13,3 +13,26 @@ data class AndroidFirebaseConfig(
   val current_key: String?,
   val project_number: String?,
 )
+
+data class PushDiagnostics(
+  val platform: String,
+  val gmsAvailable: Boolean,
+  val gmsStatus: Int,
+  val manufacturer: String,
+  val brand: String,
+  val model: String,
+  val provider: String,
+  val providerName: String,
+  val providerInstalled: Boolean?,
+  val hint: String?,
+)
+
+/**
+ * Carries a machine-readable [code] to JavaScript, so the host app can branch on
+ * the exact reason (missing GMS, disabled GMS, FCM token failure, ...).
+ */
+class PushSignalException(
+  val code: String,
+  message: String,
+  cause: Throwable? = null,
+) : IllegalStateException(message, cause)

package/android/src/main/java/com/pushsignal/PushSignalCenter.kt

@@ -7,12 +7,16 @@ import android.app.NotificationManager
 import android.app.PendingIntent
 import android.content.Context
 import android.content.Intent
+import android.content.pm.PackageManager
 import android.os.Build
 import android.os.Bundle
 import android.os.Handler
 import android.os.Looper
+import android.util.Log
 import androidx.activity.ComponentActivity
 import androidx.core.app.NotificationCompat
+import com.google.android.gms.common.ConnectionResult
+import com.google.android.gms.common.GoogleApiAvailability
 import com.google.android.gms.tasks.Tasks
 import com.google.firebase.FirebaseApp
 import com.google.firebase.FirebaseOptions
@@ -22,10 +26,28 @@ import java.util.Collections
 import java.util.UUID
 import java.util.WeakHashMap
 import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.TimeUnit
 
 internal object PushSignalCenter : Application.ActivityLifecycleCallbacks {
+  private const val TAG = "PushSignal"
   private const val EXTRA_HANDLED = "pushsignal.handled"
   private const val CHANNEL_ID = "push_signal_default"
+  private const val TOKEN_TIMEOUT_SECONDS = 10L
+  private const val TOKEN_MAX_ATTEMPTS = 5
+  private const val TOKEN_INITIAL_RETRY_DELAY_MS = 1_000L
+  private const val TOKEN_MAX_RETRY_DELAY_MS = 8_000L
+
+  private const val PROVIDER_FCM = "fcm"
+  private const val PROVIDER_HMS = "hms"
+  private const val PROVIDER_MI_PUSH = "mi_push"
+  private const val PROVIDER_OPPO_PUSH = "oppo_push"
+  private const val PROVIDER_VIVO_PUSH = "vivo_push"
+  private const val PROVIDER_MEIZU_PUSH = "meizu_push"
+  private const val PROVIDER_UNKNOWN = "unknown"
+
+  /** Service apps used to positively confirm an alternative provider on the device. */
+  private const val PACKAGE_HMS = "com.huawei.hwid"
+  private const val PACKAGE_MI_PUSH = "com.xiaomi.xmsf"
 
   private val lock = Any()
   private val mainHandler = Handler(Looper.getMainLooper())
@@ -98,7 +120,9 @@ internal object PushSignalCenter : Application.ActivityLifecycleCallbacks {
 
   fun fetchToken(): String {
     val context = application
-      ?: throw IllegalStateException("PushSignal is not initialized")
+      ?: throw PushSignalException("E_NOT_INITIALIZED", "PushSignal is not initialized")
+
+    ensurePlayServices(context)
 
     try {
       if (FirebaseApp.getApps(context).isEmpty()) {
@@ -106,29 +130,229 @@ internal object PushSignalCenter : Application.ActivityLifecycleCallbacks {
       }
       FirebaseApp.getInstance()
     } catch (error: IllegalStateException) {
-      throw IllegalStateException(
+      throw PushSignalException(
+        "E_FIREBASE_CONFIG",
         "Firebase is not configured. Call initialize({ project_id, mobilesdk_app_id, current_key, project_number }) or add google-services.json.",
         error
       )
     }
 
-    val task = FirebaseMessaging.getInstance().token
-    val token = try {
-      Tasks.await(task)
-    } catch (error: Exception) {
-      throw IllegalStateException(
-        "Failed to get an FCM token. Call initialize({ project_id, mobilesdk_app_id, current_key, project_number }) or add google-services.json.",
-        error
-      )
-    }
+    val token = awaitTokenWithRetry(context)
 
     if (token.isNullOrEmpty()) {
-      throw IllegalStateException("Firebase returned an empty FCM token")
+      throw PushSignalException("E_FCM_TOKEN", "Firebase returned an empty FCM token")
     }
 
     return token
   }
 
+  /**
+   * Fails fast with an actionable message when Google Play services cannot serve FCM
+   * (for example a China-only ROM without GMS). The message names the provider the
+   * device should use instead, so the cause is obvious in React Native logs.
+   */
+  private fun ensurePlayServices(context: Context) {
+    val status = GoogleApiAvailability.getInstance().isGooglePlayServicesAvailable(context)
+    if (status == ConnectionResult.SUCCESS) {
+      return
+    }
+
+    val code = when (status) {
+      ConnectionResult.SERVICE_MISSING -> "E_GMS_MISSING"
+      ConnectionResult.SERVICE_VERSION_UPDATE_REQUIRED -> "E_GMS_UPDATE_REQUIRED"
+      ConnectionResult.SERVICE_DISABLED -> "E_GMS_DISABLED"
+      ConnectionResult.SERVICE_INVALID -> "E_GMS_INVALID"
+      else -> "E_GMS_UNAVAILABLE"
+    }
+
+    val reason = when (status) {
+      ConnectionResult.SERVICE_MISSING ->
+        "Google Play services are missing on this device, so the standard Google push service (FCM) cannot be used."
+      ConnectionResult.SERVICE_VERSION_UPDATE_REQUIRED ->
+        "Google Play services are outdated. Update them in the Play Store and try again."
+      ConnectionResult.SERVICE_DISABLED ->
+        "Google Play services are disabled. Enable them in the device settings and try again."
+      ConnectionResult.SERVICE_INVALID ->
+        "Google Play services are invalid or corrupted on this device. Reinstalling them usually helps."
+      else ->
+        "Google Play services are unavailable (code $status), so the standard Google push service (FCM) cannot be used."
+    }
+
+    val diagnostics = diagnose(context)
+    val message = listOfNotNull(reason, diagnostics.hint).joinToString(" ")
+    Log.w(TAG, "Play services check failed ($code): $message")
+    throw PushSignalException(code, message)
+  }
+
+  /**
+   * Collects device and provider diagnostics without throwing. Used both by the
+   * `getDiagnostics` API and to enrich errors with a concrete replacement service.
+   */
+  fun diagnose(context: Context): PushDiagnostics {
+    val status = GoogleApiAvailability.getInstance().isGooglePlayServicesAvailable(context)
+    val gmsAvailable = status == ConnectionResult.SUCCESS
+    val provider = resolveProvider(context, gmsAvailable)
+    val hint = providerHint(provider, gmsAvailable)
+
+    return PushDiagnostics(
+      platform = "android_os",
+      gmsAvailable = gmsAvailable,
+      gmsStatus = status,
+      manufacturer = Build.MANUFACTURER ?: "",
+      brand = Build.BRAND ?: "",
+      model = Build.MODEL ?: "",
+      provider = provider.id,
+      providerName = provider.name,
+      providerInstalled = provider.installed,
+      hint = hint,
+    )
+  }
+
+  private data class ProviderInfo(
+    val id: String,
+    val name: String,
+    val installed: Boolean?,
+  )
+
+  /**
+   * Picks the push provider this device should use. Checks the standard Google
+   * service first, then positively confirms an installed alternative, then falls
+   * back to the manufacturer mapping. Class reflection cannot see another
+   * provider's SDK unless the host bundles it, so package checks and the
+   * manufacturer are the reliable signals.
+   */
+  private fun resolveProvider(context: Context, gmsAvailable: Boolean): ProviderInfo {
+    if (gmsAvailable) {
+      return ProviderInfo(PROVIDER_FCM, "Firebase Cloud Messaging (FCM)", true)
+    }
+
+    if (isPackageInstalled(context, PACKAGE_HMS)) {
+      return ProviderInfo(PROVIDER_HMS, "HMS Push Kit (Huawei Push)", true)
+    }
+    if (isPackageInstalled(context, PACKAGE_MI_PUSH)) {
+      return ProviderInfo(PROVIDER_MI_PUSH, "Mi Push (Xiaomi Push)", true)
+    }
+
+    val keys = setOf(Build.MANUFACTURER, Build.BRAND)
+      .filterNotNull()
+      .map { it.uppercase() }
+
+    return when {
+      keys.any { it.contains("HUAWEI") || it.contains("HONOR") } ->
+        ProviderInfo(PROVIDER_HMS, "HMS Push Kit (Huawei Push)", false)
+      keys.any { it.contains("XIAOMI") || it.contains("REDMI") || it.contains("POCO") } ->
+        ProviderInfo(PROVIDER_MI_PUSH, "Mi Push (Xiaomi Push)", false)
+      keys.any { it.contains("OPPO") || it.contains("ONEPLUS") || it.contains("REALME") } ->
+        ProviderInfo(PROVIDER_OPPO_PUSH, "OPPO Push (HeyTap)", false)
+      keys.any { it.contains("VIVO") || it.contains("IQOO") } ->
+        ProviderInfo(PROVIDER_VIVO_PUSH, "vivo Push", false)
+      keys.any { it.contains("MEIZU") } ->
+        ProviderInfo(PROVIDER_MEIZU_PUSH, "Meizu Push", false)
+      else ->
+        ProviderInfo(PROVIDER_UNKNOWN, "unknown", null)
+    }
+  }
+
+  private fun providerHint(provider: ProviderInfo, gmsAvailable: Boolean): String? {
+    if (gmsAvailable) {
+      return null
+    }
+    val device = listOfNotNull(Build.MANUFACTURER, Build.BRAND)
+      .filter { it.isNotBlank() }
+      .distinct()
+      .joinToString("/")
+
+    return when (provider.id) {
+      PROVIDER_HMS ->
+        "This device ($device) has no usable Google Play services, so FCM will not issue a token. Use HMS Push Kit (Huawei Push) instead of the standard Google service."
+      PROVIDER_MI_PUSH ->
+        "This device ($device) has no usable Google Play services, so FCM will not issue a token. Use Mi Push (Xiaomi Push) instead of the standard Google service."
+      PROVIDER_OPPO_PUSH ->
+        "This device ($device) has no usable Google Play services, so FCM will not issue a token. Use OPPO Push (HeyTap) instead of the standard Google service."
+      PROVIDER_VIVO_PUSH ->
+        "This device ($device) has no usable Google Play services, so FCM will not issue a token. Use vivo Push instead of the standard Google service."
+      PROVIDER_MEIZU_PUSH ->
+        "This device ($device) has no usable Google Play services, so FCM will not issue a token. Use Meizu Push instead of the standard Google service."
+      else ->
+        "No usable Google Play services were found and no known push provider was detected on this ROM, so FCM cannot be used. Integrate another push provider (HMS, Mi Push, OPPO/vivo/Meizu Push)."
+    }
+  }
+
+  private fun isPackageInstalled(context: Context, packageName: String): Boolean {
+    return try {
+      context.packageManager.getPackageInfo(packageName, 0)
+      true
+    } catch (_: PackageManager.NameNotFoundException) {
+      false
+    } catch (_: Exception) {
+      false
+    }
+  }
+
+  /**
+   * FCM returns SERVICE_NOT_AVAILABLE for transient conditions (no Google account yet,
+   * Play services still starting, flaky network). Xiaomi/MIUI devices hit this often,
+   * so retry with backoff before surfacing the failure.
+   */
+  private fun awaitTokenWithRetry(context: Context): String? {
+    var delayMs = TOKEN_INITIAL_RETRY_DELAY_MS
+    var lastError: Exception? = null
+
+    for (attempt in 1..TOKEN_MAX_ATTEMPTS) {
+      try {
+        return Tasks.await(
+          FirebaseMessaging.getInstance().token,
+          TOKEN_TIMEOUT_SECONDS,
+          TimeUnit.SECONDS
+        )
+      } catch (error: Exception) {
+        lastError = error
+        if (attempt == TOKEN_MAX_ATTEMPTS || !isRetryableTokenError(error)) {
+          break
+        }
+        Log.w(TAG, "FCM token attempt $attempt/$TOKEN_MAX_ATTEMPTS failed: ${error.message}. Retrying in ${delayMs}ms")
+        try {
+          Thread.sleep(delayMs)
+        } catch (_: InterruptedException) {
+          Thread.currentThread().interrupt()
+          break
+        }
+        delayMs = (delayMs * 2).coerceAtMost(TOKEN_MAX_RETRY_DELAY_MS)
+      }
+    }
+
+    val cause = lastError
+    val diagnostics = diagnose(context)
+    val message = listOfNotNull(
+      "Failed to get an FCM token: ${cause?.message ?: "unknown error"}.",
+      "Make sure the device is signed into a Google account, Google Play services are up to date, " +
+        "and the app is allowed to use background data.",
+      "Call initialize({ project_id, mobilesdk_app_id, current_key, project_number }) or add google-services.json.",
+      diagnostics.hint,
+    ).joinToString(" ")
+    Log.w(TAG, "Failed to get an FCM token: $message")
+    throw PushSignalException("E_FCM_TOKEN", message, cause)
+  }
+
+  private fun isRetryableTokenError(error: Throwable): Boolean {
+    var current: Throwable? = error
+    while (current != null) {
+      if (current is java.io.IOException || current is java.util.concurrent.TimeoutException) {
+        return true
+      }
+      val message = current.message?.uppercase() ?: ""
+      if (
+        message.contains("SERVICE_NOT_AVAILABLE") ||
+        message.contains("TIMEOUT") ||
+        message.contains("INTERNAL_SERVER_ERROR")
+      ) {
+        return true
+      }
+      current = current.cause
+    }
+    return false
+  }
+
   fun emitMessage(remoteMessage: RemoteMessage) {
     val message = remoteMessage.toPushMessage()
     runOnMain { deliverMessage(message) }

package/android/src/main/java/com/pushsignal/PushSignalModule.kt

@@ -26,7 +26,8 @@ class PushSignalModule(reactContext: ReactApplicationContext) :
       if (error == null) {
         promise.resolve(null)
       } else {
-        promise.reject("E_INIT", error.message, error)
+        val code = (error as? PushSignalException)?.code ?: "E_INIT"
+        promise.reject(code, error.message, error)
       }
     }
   }
@@ -42,7 +43,19 @@ class PushSignalModule(reactContext: ReactApplicationContext) :
         }
         promise.resolve(result)
       } catch (error: Exception) {
-        promise.reject("E_CREDENTIALS", error.message, error)
+        val code = (error as? PushSignalException)?.code ?: "E_CREDENTIALS"
+        promise.reject(code, error.message, error)
+      }
+    }
+  }
+
+  override fun getDiagnostics(promise: Promise) {
+    executor.execute {
+      try {
+        PushSignalCenter.attach(reactApplicationContext)
+        promise.resolve(PushSignalCenter.diagnose(reactApplicationContext).toWritableMap())
+      } catch (error: Exception) {
+        promise.reject("E_DIAGNOSTICS", error.message, error)
       }
     }
   }
@@ -86,3 +99,18 @@ private fun PushMessage.toWritableMap(): WritableMap {
   map.putMap("data", dataMap)
   return map
 }
+
+private fun PushDiagnostics.toWritableMap(): WritableMap {
+  val map = Arguments.createMap()
+  map.putString("platform", platform)
+  map.putBoolean("gmsAvailable", gmsAvailable)
+  map.putInt("gmsStatus", gmsStatus)
+  map.putString("manufacturer", manufacturer)
+  map.putString("brand", brand)
+  map.putString("model", model)
+  map.putString("provider", provider)
+  map.putString("providerName", providerName)
+  providerInstalled?.let { map.putBoolean("providerInstalled", it) }
+  hint?.let { map.putString("hint", it) }
+  return map
+}

package/ios/PushSignal.mm

@@ -1,5 +1,6 @@
 #import "PushSignal.h"
 #import "PushSignalCenter.h"
+#import <UIKit/UIKit.h>
 
 @implementation PushSignal {
   BOOL _listening;
@@ -22,6 +23,23 @@
                                                  }];
 }
 
+- (void)getDiagnostics:(RCTPromiseResolveBlock)resolve
+                reject:(RCTPromiseRejectBlock)reject {
+  (void)reject;
+  UIDevice *device = [UIDevice currentDevice];
+  resolve(@{
+    @"platform": @"ios",
+    @"gmsAvailable": @YES,
+    @"gmsStatus": @0,
+    @"manufacturer": @"Apple",
+    @"brand": @"Apple",
+    @"model": device.model ?: @"iOS device",
+    @"provider": @"apns",
+    @"providerName": @"Apple Push Notification service (APNs)",
+    @"providerInstalled": @YES,
+  });
+}
+
 - (void)startListening {
   if (_listening) {
     return;

package/lib/module/NativePushSignal.js.map

@@ -1 +1 @@
-{"version":3,"names":["TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativePushSignal.ts"],"mappings":";;AACA,SAASA,mBAAmB,QAAQ,cAAc;AAuBlD,eAAeA,mBAAmB,CAACC,YAAY,CAAO,YAAY,CAAC","ignoreList":[]}
+{"version":3,"names":["TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativePushSignal.ts"],"mappings":";;AACA,SAASA,mBAAmB,QAAQ,cAAc;AA2ClD,eAAeA,mBAAmB,CAACC,YAAY,CAAO,YAAY,CAAC","ignoreList":[]}

package/lib/module/PushSignalError.js

@@ -0,0 +1,29 @@
+"use strict";
+
+/**
+ * Error thrown by `initialize` and `getCredentials`.
+ *
+ * The message already contains a human-readable, actionable hint when the
+ * standard Google service (FCM/GMS) cannot be used. Structured details are
+ * available on the instance so the host app can decide how to log or report them.
+ */
+export class PushSignalError extends Error {
+  /** Machine-readable code, e.g. `E_GMS_MISSING` or `E_FCM_TOKEN`. */
+
+  /** Suggested alternative push provider, when the standard service is unusable. */
+
+  /** Actionable sentence: which service to use instead of the standard one. */
+
+  /** Full device/provider diagnostics if they could be collected. */
+
+  /** Original error from the native layer. */
+
+  constructor(code, message, cause) {
+    super(message);
+    this.name = 'PushSignalError';
+    this.code = code;
+    this.cause = cause;
+    Object.setPrototypeOf(this, PushSignalError.prototype);
+  }
+}
+//# sourceMappingURL=PushSignalError.js.map

package/lib/module/PushSignalError.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["PushSignalError","Error","constructor","code","message","cause","name","Object","setPrototypeOf","prototype"],"sourceRoot":"../../src","sources":["PushSignalError.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,eAAe,SAASC,KAAK,CAAC;EACzC;;EAEA;;EAEA;;EAEA;;EAEA;;EAGAC,WAAWA,CAACC,IAAY,EAAEC,OAAe,EAAEC,KAAe,EAAE;IAC1D,KAAK,CAACD,OAAO,CAAC;IACd,IAAI,CAACE,IAAI,GAAG,iBAAiB;IAC7B,IAAI,CAACH,IAAI,GAAGA,IAAI;IAChB,IAAI,CAACE,KAAK,GAAGA,KAAK;IAClBE,MAAM,CAACC,cAAc,CAAC,IAAI,EAAER,eAAe,CAACS,SAAS,CAAC;EACxD;AACF","ignoreList":[]}

package/lib/module/index.js

@@ -1,4 +1,5 @@
 "use strict";
 
-export { getCredentials, initialize, onMessage, onNotificationPress } from './pushSignal';
+export { PushSignalError } from "./PushSignalError.js";
+export { getCredentials, getDiagnostics, initialize, onMessage, onNotificationPress } from './pushSignal';
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["getCredentials","initialize","onMessage","onNotificationPress"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAQA,SACEA,cAAc,EACdC,UAAU,EACVC,SAAS,EACTC,mBAAmB,QACd,cAAc","ignoreList":[]}
+{"version":3,"names":["PushSignalError","getCredentials","getDiagnostics","initialize","onMessage","onNotificationPress"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAUA,SAASA,eAAe,QAAQ,sBAAmB;AACnD,SACEC,cAAc,EACdC,cAAc,EACdC,UAAU,EACVC,SAAS,EACTC,mBAAmB,QACd,cAAc","ignoreList":[]}

package/lib/module/pushSignal.js

@@ -4,6 +4,9 @@ export async function initialize(_config = {}) {}
 export async function getCredentials() {
   throw new Error('Push credentials are not supported on web');
 }
+export async function getDiagnostics() {
+  throw new Error('Push diagnostics are not supported on web');
+}
 export function onMessage(_listener) {
   return () => {};
 }

package/lib/module/pushSignal.js.map

@@ -1 +1 @@
-{"version":3,"names":["initialize","_config","getCredentials","Error","onMessage","_listener","onNotificationPress"],"sourceRoot":"../../src","sources":["pushSignal.tsx"],"mappings":";;AAOA,OAAO,eAAeA,UAAUA,CAC9BC,OAA8B,GAAG,CAAC,CAAC,EACpB,CAAC;AAElB,OAAO,eAAeC,cAAcA,CAAA,EAA6B;EAC/D,MAAM,IAAIC,KAAK,CAAC,2CAA2C,CAAC;AAC9D;AAEA,OAAO,SAASC,SAASA,CAACC,SAA4B,EAAc;EAClE,OAAO,MAAM,CAAC,CAAC;AACjB;AAEA,OAAO,SAASC,mBAAmBA,CACjCD,SAAyC,EAC7B;EACZ,OAAO,MAAM,CAAC,CAAC;AACjB","ignoreList":[]}
+{"version":3,"names":["initialize","_config","getCredentials","Error","getDiagnostics","onMessage","_listener","onNotificationPress"],"sourceRoot":"../../src","sources":["pushSignal.tsx"],"mappings":";;AAQA,OAAO,eAAeA,UAAUA,CAC9BC,OAA8B,GAAG,CAAC,CAAC,EACpB,CAAC;AAElB,OAAO,eAAeC,cAAcA,CAAA,EAA6B;EAC/D,MAAM,IAAIC,KAAK,CAAC,2CAA2C,CAAC;AAC9D;AAEA,OAAO,eAAeC,cAAcA,CAAA,EAA6B;EAC/D,MAAM,IAAID,KAAK,CAAC,2CAA2C,CAAC;AAC9D;AAEA,OAAO,SAASE,SAASA,CAACC,SAA4B,EAAc;EAClE,OAAO,MAAM,CAAC,CAAC;AACjB;AAEA,OAAO,SAASC,mBAAmBA,CACjCD,SAAyC,EAC7B;EACZ,OAAO,MAAM,CAAC,CAAC;AACjB","ignoreList":[]}

package/lib/module/pushSignal.native.js

@@ -1,6 +1,7 @@
 "use strict";
 
 import NativePushSignal from "./NativePushSignal.js";
+import { PushSignalError } from "./PushSignalError.js";
 const messageListeners = new Set();
 const pressListeners = new Set();
 let nativeCallbacksBound = false;
@@ -28,6 +29,40 @@ function normalizeCredentials(raw) {
     environment: raw.environment
   };
 }
+function normalizeDiagnostics(raw) {
+  return {
+    platform: raw.platform,
+    gmsAvailable: raw.gmsAvailable,
+    gmsStatus: raw.gmsStatus,
+    manufacturer: raw.manufacturer,
+    brand: raw.brand,
+    model: raw.model,
+    provider: raw.provider,
+    providerName: raw.providerName,
+    providerInstalled: raw.providerInstalled ?? undefined,
+    hint: raw.hint ?? undefined
+  };
+}
+function toPushSignalError(error, fallbackCode) {
+  const candidate = error;
+  return new PushSignalError(candidate?.code ?? fallbackCode, candidate?.message ?? 'PushSignal request failed', error);
+}
+
+/**
+ * Attaches structured diagnostics to an error on a best-effort basis. Failing to
+ * collect them must never hide the original, already actionable error.
+ */
+async function enrichError(error) {
+  try {
+    const diagnostics = normalizeDiagnostics(await NativePushSignal.getDiagnostics());
+    error.diagnostics = diagnostics;
+    error.provider = diagnostics.provider;
+    error.hint = diagnostics.hint;
+  } catch {
+    // Diagnostics are optional; keep the original error.
+  }
+  return error;
+}
 function bindNativeCallbacks() {
   if (nativeCallbacksBound) {
     return;
@@ -49,11 +84,23 @@ function bindNativeCallbacks() {
   });
   NativePushSignal.startListening();
 }
-export function initialize(config = {}) {
-  return NativePushSignal.initialize(config);
+export async function initialize(config = {}) {
+  try {
+    await NativePushSignal.initialize(config);
+  } catch (error) {
+    throw await enrichError(toPushSignalError(error, 'E_INIT'));
+  }
+}
+export async function getCredentials() {
+  try {
+    const raw = await NativePushSignal.getCredentials();
+    return normalizeCredentials(raw);
+  } catch (error) {
+    throw await enrichError(toPushSignalError(error, 'E_CREDENTIALS'));
+  }
 }
-export function getCredentials() {
-  return NativePushSignal.getCredentials().then(normalizeCredentials);
+export async function getDiagnostics() {
+  return normalizeDiagnostics(await NativePushSignal.getDiagnostics());
 }
 export function onMessage(listener) {
   bindNativeCallbacks();

package/lib/module/pushSignal.native.js.map

@@ -1 +1 @@
-{"version":3,"names":["NativePushSignal","messageListeners","Set","pressListeners","nativeCallbacksBound","normalizeMessage","raw","data","key","value","Object","entries","String","id","title","body","normalizeCredentials","platform","token","environment","bindNativeCallbacks","onMessage","message","listener","Promise","resolve","then","undefined","onNotificationPress","forEach","startListening","initialize","config","getCredentials","add","delete"],"sourceRoot":"../../src","sources":["pushSignal.native.tsx"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["NativePushSignal","PushSignalError","messageListeners","Set","pressListeners","nativeCallbacksBound","normalizeMessage","raw","data","key","value","Object","entries","String","id","title","body","normalizeCredentials","platform","token","environment","normalizeDiagnostics","gmsAvailable","gmsStatus","manufacturer","brand","model","provider","providerName","providerInstalled","undefined","hint","toPushSignalError","error","fallbackCode","candidate","code","message","enrichError","diagnostics","getDiagnostics","bindNativeCallbacks","onMessage","listener","Promise","resolve","then","onNotificationPress","forEach","startListening","initialize","config","getCredentials","add","delete"],"sourceRoot":"../../src","sources":["pushSignal.native.tsx"],"mappings":"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","ignoreList":[]}

package/lib/typescript/src/NativePushSignal.d.ts

@@ -10,9 +10,28 @@ export type NativePushCredentials = {
     token: string;
     environment?: string;
 };
+export type NativePushDiagnostics = {
+    platform: string;
+    /** True when Google Play services can serve FCM; false on a ROM without GMS. */
+    gmsAvailable: boolean;
+    /** Raw GoogleApiAvailability status code. 0 means SUCCESS. */
+    gmsStatus: number;
+    manufacturer: string;
+    brand: string;
+    model: string;
+    /** Machine-readable provider id: fcm, hms, mi_push, oppo_push, vivo_push, meizu_push, apns, unknown. */
+    provider: string;
+    /** Human-readable provider name, e.g. "HMS Push Kit". */
+    providerName: string;
+    /** True when the provider service app was found on the device. */
+    providerInstalled: boolean;
+    /** Actionable sentence explaining which service to use instead of the standard one. */
+    hint?: string;
+};
 export interface Spec extends TurboModule {
     initialize(config: Object): Promise<void>;
     getCredentials(): Promise<NativePushCredentials>;
+    getDiagnostics(): Promise<NativePushDiagnostics>;
     startListening(): void;
     readonly onMessage: CodegenTypes.EventEmitter<NativePushMessage>;
     readonly onNotificationPress: CodegenTypes.EventEmitter<NativePushMessage>;

package/lib/typescript/src/NativePushSignal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativePushSignal.d.ts","sourceRoot":"","sources":["../../../src/NativePushSignal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG9D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,cAAc,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjD,cAAc,IAAI,IAAI,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;IACjE,QAAQ,CAAC,mBAAmB,EAAE,YAAY,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;CAC5E;;AAED,wBAAoE"}
+{"version":3,"file":"NativePushSignal.d.ts","sourceRoot":"","sources":["../../../src/NativePushSignal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG9D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,YAAY,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,wGAAwG;IACxG,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,cAAc,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjD,cAAc,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjD,cAAc,IAAI,IAAI,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;IACjE,QAAQ,CAAC,mBAAmB,EAAE,YAAY,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;CAC5E;;AAED,wBAAoE"}

package/lib/typescript/src/PushSignalError.d.ts

@@ -0,0 +1,22 @@
+import type { PushDiagnostics, PushProvider } from './types.js';
+/**
+ * Error thrown by `initialize` and `getCredentials`.
+ *
+ * The message already contains a human-readable, actionable hint when the
+ * standard Google service (FCM/GMS) cannot be used. Structured details are
+ * available on the instance so the host app can decide how to log or report them.
+ */
+export declare class PushSignalError extends Error {
+    /** Machine-readable code, e.g. `E_GMS_MISSING` or `E_FCM_TOKEN`. */
+    readonly code: string;
+    /** Suggested alternative push provider, when the standard service is unusable. */
+    provider?: PushProvider;
+    /** Actionable sentence: which service to use instead of the standard one. */
+    hint?: string;
+    /** Full device/provider diagnostics if they could be collected. */
+    diagnostics?: PushDiagnostics;
+    /** Original error from the native layer. */
+    readonly cause?: unknown;
+    constructor(code: string, message: string, cause?: unknown);
+}
+//# sourceMappingURL=PushSignalError.d.ts.map

package/lib/typescript/src/PushSignalError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PushSignalError.d.ts","sourceRoot":"","sources":["../../../src/PushSignalError.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAS,CAAC;AAE7D;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,4CAA4C;IAC5C,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAO3D"}

package/lib/typescript/src/index.d.ts

@@ -1,3 +1,4 @@
-export type { AndroidFirebaseConfig, OnMessageListener, PushCredentials, PushEnvironment, PushMessage, PushPlatform, } from './types.js';
-export { getCredentials, initialize, onMessage, onNotificationPress, } from './pushSignal';
+export type { AndroidFirebaseConfig, OnMessageListener, PushCredentials, PushDiagnostics, PushEnvironment, PushMessage, PushPlatform, PushProvider, } from './types.js';
+export { PushSignalError } from './PushSignalError.js';
+export { getCredentials, getDiagnostics, initialize, onMessage, onNotificationPress, } from './pushSignal';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,YAAS,CAAC;AACjB,OAAO,EACL,cAAc,EACd,UAAU,EACV,SAAS,EACT,mBAAmB,GACpB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,YAAS,CAAC;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAmB,CAAC;AACpD,OAAO,EACL,cAAc,EACd,cAAc,EACd,UAAU,EACV,SAAS,EACT,mBAAmB,GACpB,MAAM,cAAc,CAAC"}

package/lib/typescript/src/pushSignal.d.ts

@@ -1,6 +1,7 @@
-import type { AndroidFirebaseConfig, OnMessageListener, PushCredentials, PushMessage } from './types.js';
+import type { AndroidFirebaseConfig, OnMessageListener, PushCredentials, PushDiagnostics, PushMessage } from './types.js';
 export declare function initialize(_config?: AndroidFirebaseConfig): Promise<void>;
 export declare function getCredentials(): Promise<PushCredentials>;
+export declare function getDiagnostics(): Promise<PushDiagnostics>;
 export declare function onMessage(_listener: OnMessageListener): () => void;
 export declare function onNotificationPress(_listener: (message: PushMessage) => void): () => void;
 //# sourceMappingURL=pushSignal.d.ts.map

package/lib/typescript/src/pushSignal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pushSignal.d.ts","sourceRoot":"","sources":["../../../src/pushSignal.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,WAAW,EACZ,MAAM,YAAS,CAAC;AAEjB,wBAAsB,UAAU,CAC9B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAAG;AAEnB,wBAAsB,cAAc,IAAI,OAAO,CAAC,eAAe,CAAC,CAE/D;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAElE;AAED,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GACxC,MAAM,IAAI,CAEZ"}
+{"version":3,"file":"pushSignal.d.ts","sourceRoot":"","sources":["../../../src/pushSignal.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,WAAW,EACZ,MAAM,YAAS,CAAC;AAEjB,wBAAsB,UAAU,CAC9B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAAG;AAEnB,wBAAsB,cAAc,IAAI,OAAO,CAAC,eAAe,CAAC,CAE/D;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,eAAe,CAAC,CAE/D;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAElE;AAED,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GACxC,MAAM,IAAI,CAEZ"}

package/lib/typescript/src/pushSignal.native.d.ts

@@ -1,6 +1,7 @@
-import type { AndroidFirebaseConfig, OnMessageListener, PushCredentials, PushMessage } from './types.js';
+import type { AndroidFirebaseConfig, OnMessageListener, PushCredentials, PushDiagnostics, PushMessage } from './types.js';
 export declare function initialize(config?: AndroidFirebaseConfig): Promise<void>;
 export declare function getCredentials(): Promise<PushCredentials>;
+export declare function getDiagnostics(): Promise<PushDiagnostics>;
 export declare function onMessage(listener: OnMessageListener): () => void;
 export declare function onNotificationPress(listener: (message: PushMessage) => void): () => void;
 //# sourceMappingURL=pushSignal.native.d.ts.map

package/lib/typescript/src/pushSignal.native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pushSignal.native.d.ts","sourceRoot":"","sources":["../../../src/pushSignal.native.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EAEf,WAAW,EAEZ,MAAM,YAAS,CAAC;AAyEjB,wBAAgB,UAAU,CAAC,MAAM,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E;AAED,wBAAgB,cAAc,IAAI,OAAO,CAAC,eAAe,CAAC,CAEzD;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAMjE;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GACvC,MAAM,IAAI,CAMZ"}
+{"version":3,"file":"pushSignal.native.d.ts","sourceRoot":"","sources":["../../../src/pushSignal.native.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,eAAe,EAEf,WAAW,EAGZ,MAAM,YAAS,CAAC;AAsHjB,wBAAsB,UAAU,CAC9B,MAAM,GAAE,qBAA0B,GACjC,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,eAAe,CAAC,CAO/D;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,eAAe,CAAC,CAE/D;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAMjE;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GACvC,MAAM,IAAI,CAMZ"}

package/lib/typescript/src/types.d.ts

@@ -13,6 +13,24 @@ export interface PushMessage {
     data: Record<string, string>;
 }
 export type OnMessageListener = (message: PushMessage) => void | Promise<void>;
+export type PushProvider = 'fcm' | 'hms' | 'mi_push' | 'oppo_push' | 'vivo_push' | 'meizu_push' | 'apns' | 'unknown';
+export interface PushDiagnostics {
+    platform: PushPlatform;
+    /** True when Google Play services can serve FCM; false on a ROM without GMS. */
+    gmsAvailable: boolean;
+    /** Raw GoogleApiAvailability status code. 0 means SUCCESS. */
+    gmsStatus: number;
+    manufacturer: string;
+    brand: string;
+    model: string;
+    provider: PushProvider;
+    /** Human-readable provider name, e.g. "HMS Push Kit". */
+    providerName: string;
+    /** True only when the provider service app was positively found on the device. */
+    providerInstalled?: boolean;
+    /** Actionable sentence explaining which service to use instead of the standard one. */
+    hint?: string;
+}
 export interface AndroidFirebaseConfig {
     project_id?: string;
     mobilesdk_app_id?: string;

package/lib/typescript/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,YAAY,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,YAAY,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/E,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,YAAY,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,YAAY,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/E,MAAM,MAAM,YAAY,GACpB,KAAK,GACL,KAAK,GACL,SAAS,GACT,WAAW,GACX,WAAW,GACX,YAAY,GACZ,MAAM,GACN,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,YAAY,CAAC;IACvB,gFAAgF;IAChF,YAAY,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-native-push-signal",
-  "version": "0.1.8",
-  "description": "Push",
+  "version": "0.1.10",
+  "description": "React Native push notifications with direct APNs and FCM integration — get device tokens for your server and listen for incoming messages and taps",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
   "exports": {
@@ -45,18 +45,28 @@
   "keywords": [
     "react-native",
     "ios",
-    "android"
+    "android",
+    "push",
+    "push-notifications",
+    "notifications",
+    "apns",
+    "fcm",
+    "firebase",
+    "firebase-cloud-messaging",
+    "device-token",
+    "push-token",
+    "remote-notifications"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://antonseagull.com.git"
+    "url": "git+https://github.com/AntonSeagull/react-native-push-signal.git"
   },
   "author": "AntonSeagull <hi@antonseagull.com> (https://antonseagull.com)",
   "license": "MIT",
   "bugs": {
-    "url": "https://antonseagull.com/issues"
+    "url": "https://github.com/AntonSeagull/react-native-push-signal/issues"
   },
-  "homepage": "https://antonseagull.com#readme",
+  "homepage": "https://github.com/AntonSeagull/react-native-push-signal#readme",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },

package/src/NativePushSignal.ts

@@ -14,9 +14,29 @@ export type NativePushCredentials = {
   environment?: string;
 };
 
+export type NativePushDiagnostics = {
+  platform: string;
+  /** True when Google Play services can serve FCM; false on a ROM without GMS. */
+  gmsAvailable: boolean;
+  /** Raw GoogleApiAvailability status code. 0 means SUCCESS. */
+  gmsStatus: number;
+  manufacturer: string;
+  brand: string;
+  model: string;
+  /** Machine-readable provider id: fcm, hms, mi_push, oppo_push, vivo_push, meizu_push, apns, unknown. */
+  provider: string;
+  /** Human-readable provider name, e.g. "HMS Push Kit". */
+  providerName: string;
+  /** True when the provider service app was found on the device. */
+  providerInstalled: boolean;
+  /** Actionable sentence explaining which service to use instead of the standard one. */
+  hint?: string;
+};
+
 export interface Spec extends TurboModule {
   initialize(config: Object): Promise<void>;
   getCredentials(): Promise<NativePushCredentials>;
+  getDiagnostics(): Promise<NativePushDiagnostics>;
   startListening(): void;
   readonly onMessage: CodegenTypes.EventEmitter<NativePushMessage>;
   readonly onNotificationPress: CodegenTypes.EventEmitter<NativePushMessage>;

package/src/PushSignalError.ts

@@ -0,0 +1,29 @@
+import type { PushDiagnostics, PushProvider } from './types';
+
+/**
+ * Error thrown by `initialize` and `getCredentials`.
+ *
+ * The message already contains a human-readable, actionable hint when the
+ * standard Google service (FCM/GMS) cannot be used. Structured details are
+ * available on the instance so the host app can decide how to log or report them.
+ */
+export class PushSignalError extends Error {
+  /** Machine-readable code, e.g. `E_GMS_MISSING` or `E_FCM_TOKEN`. */
+  readonly code: string;
+  /** Suggested alternative push provider, when the standard service is unusable. */
+  provider?: PushProvider;
+  /** Actionable sentence: which service to use instead of the standard one. */
+  hint?: string;
+  /** Full device/provider diagnostics if they could be collected. */
+  diagnostics?: PushDiagnostics;
+  /** Original error from the native layer. */
+  override readonly cause?: unknown;
+
+  constructor(code: string, message: string, cause?: unknown) {
+    super(message);
+    this.name = 'PushSignalError';
+    this.code = code;
+    this.cause = cause;
+    Object.setPrototypeOf(this, PushSignalError.prototype);
+  }
+}

package/src/index.tsx

@@ -2,12 +2,16 @@ export type {
   AndroidFirebaseConfig,
   OnMessageListener,
   PushCredentials,
+  PushDiagnostics,
   PushEnvironment,
   PushMessage,
   PushPlatform,
+  PushProvider,
 } from './types';
+export { PushSignalError } from './PushSignalError';
 export {
   getCredentials,
+  getDiagnostics,
   initialize,
   onMessage,
   onNotificationPress,

package/src/pushSignal.native.tsx

@@ -1,11 +1,15 @@
 import NativePushSignal from './NativePushSignal';
+import type { NativePushDiagnostics } from './NativePushSignal';
+import { PushSignalError } from './PushSignalError';
 import type {
   AndroidFirebaseConfig,
   OnMessageListener,
   PushCredentials,
+  PushDiagnostics,
   PushEnvironment,
   PushMessage,
   PushPlatform,
+  PushProvider,
 } from './types';
 
 const messageListeners = new Set<OnMessageListener>();
@@ -50,6 +54,51 @@ function normalizeCredentials(raw: {
   };
 }
 
+function normalizeDiagnostics(raw: NativePushDiagnostics): PushDiagnostics {
+  return {
+    platform: raw.platform as PushPlatform,
+    gmsAvailable: raw.gmsAvailable,
+    gmsStatus: raw.gmsStatus,
+    manufacturer: raw.manufacturer,
+    brand: raw.brand,
+    model: raw.model,
+    provider: raw.provider as PushProvider,
+    providerName: raw.providerName,
+    providerInstalled: raw.providerInstalled ?? undefined,
+    hint: raw.hint ?? undefined,
+  };
+}
+
+function toPushSignalError(
+  error: unknown,
+  fallbackCode: string
+): PushSignalError {
+  const candidate = error as { code?: string; message?: string } | undefined;
+  return new PushSignalError(
+    candidate?.code ?? fallbackCode,
+    candidate?.message ?? 'PushSignal request failed',
+    error
+  );
+}
+
+/**
+ * Attaches structured diagnostics to an error on a best-effort basis. Failing to
+ * collect them must never hide the original, already actionable error.
+ */
+async function enrichError(error: PushSignalError): Promise<PushSignalError> {
+  try {
+    const diagnostics = normalizeDiagnostics(
+      await NativePushSignal.getDiagnostics()
+    );
+    error.diagnostics = diagnostics;
+    error.provider = diagnostics.provider;
+    error.hint = diagnostics.hint;
+  } catch {
+    // Diagnostics are optional; keep the original error.
+  }
+  return error;
+}
+
 function bindNativeCallbacks() {
   if (nativeCallbacksBound) {
     return;
@@ -79,12 +128,27 @@ function bindNativeCallbacks() {
   NativePushSignal.startListening();
 }
 
-export function initialize(config: AndroidFirebaseConfig = {}): Promise<void> {
-  return NativePushSignal.initialize(config);
+export async function initialize(
+  config: AndroidFirebaseConfig = {}
+): Promise<void> {
+  try {
+    await NativePushSignal.initialize(config);
+  } catch (error) {
+    throw await enrichError(toPushSignalError(error, 'E_INIT'));
+  }
+}
+
+export async function getCredentials(): Promise<PushCredentials> {
+  try {
+    const raw = await NativePushSignal.getCredentials();
+    return normalizeCredentials(raw);
+  } catch (error) {
+    throw await enrichError(toPushSignalError(error, 'E_CREDENTIALS'));
+  }
 }
 
-export function getCredentials(): Promise<PushCredentials> {
-  return NativePushSignal.getCredentials().then(normalizeCredentials);
+export async function getDiagnostics(): Promise<PushDiagnostics> {
+  return normalizeDiagnostics(await NativePushSignal.getDiagnostics());
 }
 
 export function onMessage(listener: OnMessageListener): () => void {

package/src/pushSignal.tsx

@@ -2,6 +2,7 @@ import type {
   AndroidFirebaseConfig,
   OnMessageListener,
   PushCredentials,
+  PushDiagnostics,
   PushMessage,
 } from './types';
 
@@ -13,6 +14,10 @@ export async function getCredentials(): Promise<PushCredentials> {
   throw new Error('Push credentials are not supported on web');
 }
 
+export async function getDiagnostics(): Promise<PushDiagnostics> {
+  throw new Error('Push diagnostics are not supported on web');
+}
+
 export function onMessage(_listener: OnMessageListener): () => void {
   return () => {};
 }

package/src/types.ts

@@ -17,6 +17,34 @@ export interface PushMessage {
 
 export type OnMessageListener = (message: PushMessage) => void | Promise<void>;
 
+export type PushProvider =
+  | 'fcm'
+  | 'hms'
+  | 'mi_push'
+  | 'oppo_push'
+  | 'vivo_push'
+  | 'meizu_push'
+  | 'apns'
+  | 'unknown';
+
+export interface PushDiagnostics {
+  platform: PushPlatform;
+  /** True when Google Play services can serve FCM; false on a ROM without GMS. */
+  gmsAvailable: boolean;
+  /** Raw GoogleApiAvailability status code. 0 means SUCCESS. */
+  gmsStatus: number;
+  manufacturer: string;
+  brand: string;
+  model: string;
+  provider: PushProvider;
+  /** Human-readable provider name, e.g. "HMS Push Kit". */
+  providerName: string;
+  /** True only when the provider service app was positively found on the device. */
+  providerInstalled?: boolean;
+  /** Actionable sentence explaining which service to use instead of the standard one. */
+  hint?: string;
+}
+
 export interface AndroidFirebaseConfig {
   project_id?: string;
   mobilesdk_app_id?: string;