feat: add carrier information (#56)

* feat: add carrier related apis

* feat: add native impl

* docs: carrier apis

* docs: changeset

Author: l2hyunwoo

.changeset/hungry-cups-hear.md

@@ -0,0 +1,5 @@
+---
+'react-native-nitro-device-info': patch
+---
+
+feat: add carrier informations

docs/docs/api/device-info.md

@@ -482,6 +482,87 @@ const carrier = await DeviceInfoModule.getCarrier();
 const carrierSync = DeviceInfoModule.getCarrierSync();
 ```
 
+### Carrier Information Properties
+
+Detailed carrier information for telecom apps, analytics, and geo-detection.
+
+#### `carrierAllowsVOIP: boolean`
+
+Check if carrier allows VoIP calls on its network.
+
+```typescript
+const allowsVOIP = DeviceInfoModule.carrierAllowsVOIP;
+// iOS: true/false based on carrier policy
+// Android: always true (no equivalent API)
+```
+
+**Platform**: iOS only (always returns `true` on Android)
+
+#### `carrierIsoCountryCode: string`
+
+Get ISO 3166-1 alpha-2 country code for the carrier.
+
+```typescript
+const countryCode = DeviceInfoModule.carrierIsoCountryCode;
+// Example: "US", "KR", "JP", "DE"
+// Returns "" if no SIM card
+```
+
+**Platform**: iOS, Android
+
+#### `mobileCountryCode: string`
+
+Get Mobile Country Code (MCC) per ITU-T Recommendation E.212.
+
+```typescript
+const mcc = DeviceInfoModule.mobileCountryCode;
+// Example: "310" (USA), "450" (Korea), "440" (Japan)
+// Returns "" if no carrier
+```
+
+**Platform**: iOS, Android
+
+**Common MCC values**:
+
+| Country | MCC |
+|---------|-----|
+| USA | 310-316 |
+| Korea | 450 |
+| Japan | 440-441 |
+| China | 460 |
+| Germany | 262 |
+
+#### `mobileNetworkCode: string`
+
+Get Mobile Network Code (MNC) that identifies the carrier within a country.
+
+```typescript
+const mnc = DeviceInfoModule.mobileNetworkCode;
+// Example: "260" (T-Mobile US), "05" (SKT Korea)
+// Returns "" if no carrier
+```
+
+**Platform**: iOS, Android
+
+#### `mobileNetworkOperator: string`
+
+Get combined MCC + MNC string.
+
+```typescript
+const operator = DeviceInfoModule.mobileNetworkOperator;
+// Example: "310260" (T-Mobile US), "45005" (SKT Korea)
+// Equivalent to: mobileCountryCode + mobileNetworkCode
+// Returns "" if no carrier
+```
+
+**Platform**: iOS, Android
+
+**Use cases**:
+- Carrier-specific feature toggling
+- Regional content delivery
+- Telecom analytics
+- Fraud detection (geo-location verification)
+
 ### `isLocationEnabled(): Promise<boolean>`
 
 Check if location services are enabled.
@@ -1066,6 +1147,8 @@ This provides fast access while keeping data reasonably fresh.
 | deviceYearClass         | ✅  | ✅      | Extended 2025 algorithm             |
 | isSideLoadingEnabled    | ❌  | ✅      | Android only (per-app on 8.0+)      |
 | Network info            | ✅  | ✅      | MAC hardcoded on iOS 7+             |
+| Carrier info (MCC/MNC)  | ✅  | ✅      | Empty string if no SIM              |
+| carrierAllowsVOIP       | ✅  | ⚠️      | Android always returns true         |
 | System language         | ✅  | ✅      | BCP 47 format                       |
 | Navigation mode         | ❌  | ✅      | Android only (API 29+)              |
 | Android Build info      | ❌  | ✅      | Android only                        |

docs/docs/api/migration.md

@@ -553,6 +553,72 @@ Both libraries use the same Facebook algorithm for calculating device year class
   - Android: Checks su binaries, root apps, system properties, test-keys
   - iOS: Checks Cydia, jailbreak files, sandbox escape, suspicious paths
 
+---
+
+## Migrating from react-native-carrier-info
+
+If you're using `react-native-carrier-info` for carrier information, you can consolidate into `react-native-nitro-device-info`.
+
+### API Migration Reference
+
+| react-native-carrier-info | react-native-nitro-device-info | Notes |
+|---------------------------|-------------------------------|-------|
+| `await CarrierInfo.allowsVOIP()` | `DeviceInfoModule.carrierAllowsVOIP` | Now sync property |
+| `await CarrierInfo.carrierName()` | `DeviceInfoModule.getCarrierSync()` | Now sync method |
+| `await CarrierInfo.isoCountryCode()` | `DeviceInfoModule.carrierIsoCountryCode` | Now sync property |
+| `await CarrierInfo.mobileCountryCode()` | `DeviceInfoModule.mobileCountryCode` | Now sync property |
+| `await CarrierInfo.mobileNetworkCode()` | `DeviceInfoModule.mobileNetworkCode` | Now sync property |
+| `await CarrierInfo.mobileNetworkOperator()` | `DeviceInfoModule.mobileNetworkOperator` | Now sync property |
+
+### Migration Example
+
+**Before** (`react-native-carrier-info`):
+```typescript
+import CarrierInfo from 'react-native-carrier-info';
+
+async function getCarrierDetails() {
+  const carrierName = await CarrierInfo.carrierName();
+  const allowsVOIP = await CarrierInfo.allowsVOIP();
+  const isoCountryCode = await CarrierInfo.isoCountryCode();
+  const mcc = await CarrierInfo.mobileCountryCode();
+  const mnc = await CarrierInfo.mobileNetworkCode();
+  const operator = await CarrierInfo.mobileNetworkOperator();
+
+  return { carrierName, allowsVOIP, isoCountryCode, mcc, mnc, operator };
+}
+```
+
+**After** (`react-native-nitro-device-info`):
+```typescript
+import { DeviceInfoModule } from 'react-native-nitro-device-info';
+
+function getCarrierDetails() {
+  // All synchronous - no async/await needed!
+  return {
+    carrierName: DeviceInfoModule.getCarrierSync(),
+    allowsVOIP: DeviceInfoModule.carrierAllowsVOIP,
+    isoCountryCode: DeviceInfoModule.carrierIsoCountryCode,
+    mcc: DeviceInfoModule.mobileCountryCode,
+    mnc: DeviceInfoModule.mobileNetworkCode,
+    operator: DeviceInfoModule.mobileNetworkOperator,
+  };
+}
+```
+
+### Key Benefits
+
+1. **No async/await**: All carrier properties are synchronous
+2. **Single dependency**: No need to install separate carrier-info package
+3. **JSI performance**: Zero-overhead native access via Nitro Modules
+4. **Unified API**: Carrier info alongside 80+ other device properties
+
+### Platform Notes
+
+- **iOS**: Uses `CTTelephonyNetworkInfo` and `CTCarrier` APIs
+- **Android**: Uses `TelephonyManager` APIs
+- **carrierAllowsVOIP**: Returns actual value on iOS, always `true` on Android (no equivalent API)
+- **Empty strings**: All properties return `""` when no SIM card is present
+
 ## Need Help?
 
 - [Complete API Reference](/api/device-info)

packages/react-native-nitro-device-info/android/src/main/java/com/margelo/nitro/nitrodeviceinfo/DeviceInfo.kt

@@ -895,6 +895,73 @@ class DeviceInfo : HybridDeviceInfoSpec() {
         return cachedCarrier
     }
 
+    // MARK: - Carrier Information (react-native-carrier-info parity)
+
+    /** Cached TelephonyManager for carrier info APIs */
+    private val carrierTelephonyManager: TelephonyManager? by lazy {
+        context.getSystemService(Context.TELEPHONY_SERVICE) as? TelephonyManager
+    }
+
+    /**
+     * Check if carrier allows VoIP calls on its network
+     *
+     * Android does not have an equivalent API to iOS's CTCarrier.allowsVOIP.
+     * Always returns true per react-native-carrier-info implementation.
+     */
+    override val carrierAllowsVOIP: Boolean
+        get() = true
+
+    /**
+     * ISO 3166-1 country code for the carrier
+     *
+     * Returns the ISO country code (e.g., "US", "KR", "JP") or empty string if unavailable.
+     * Uses TelephonyManager.getSimCountryIso() for SIM-based country detection.
+     */
+    override val carrierIsoCountryCode: String
+        get() = carrierTelephonyManager?.simCountryIso?.uppercase() ?: ""
+
+    /**
+     * Mobile Country Code (MCC)
+     *
+     * Returns 3-digit MCC per ITU-T E.212 (e.g., "310" for USA, "450" for Korea).
+     * Parsed from TelephonyManager.getSimOperator() which returns MCC+MNC.
+     * Returns empty string if unavailable or invalid.
+     */
+    override val mobileCountryCode: String
+        get() {
+            val operator = carrierTelephonyManager?.simOperator
+            if (operator.isNullOrEmpty() || operator.length < 3) {
+                return ""
+            }
+            return operator.substring(0, 3)
+        }
+
+    /**
+     * Mobile Network Code (MNC)
+     *
+     * Returns 2 or 3-digit MNC (e.g., "260" for T-Mobile US).
+     * Parsed from TelephonyManager.getSimOperator() which returns MCC+MNC.
+     * Returns empty string if unavailable or invalid.
+     */
+    override val mobileNetworkCode: String
+        get() {
+            val operator = carrierTelephonyManager?.simOperator
+            if (operator.isNullOrEmpty() || operator.length < 5) {
+                return ""
+            }
+            return operator.substring(3)
+        }
+
+    /**
+     * Mobile Network Operator (MCC + MNC combined)
+     *
+     * Returns combined MCC+MNC (e.g., "310260" for T-Mobile US).
+     * Uses TelephonyManager.getSimOperator() directly.
+     * Returns empty string if unavailable.
+     */
+    override val mobileNetworkOperator: String
+        get() = carrierTelephonyManager?.simOperator ?: ""
+
     /** Check if location services are enabled */
     override fun getIsLocationEnabled(): Boolean {
         return try {

packages/react-native-nitro-device-info/ios/DeviceInfo.swift

@@ -929,6 +929,73 @@ class DeviceInfo: HybridDeviceInfoSpec {
     return cachedCarrier
   }
 
+  // MARK: - Carrier Information (react-native-carrier-info parity)
+
+  /// Cached CTCarrier for carrier info APIs
+  private var cachedCarrierObject: CTCarrier? {
+    let networkInfo = CTTelephonyNetworkInfo()
+    if let providers = networkInfo.serviceSubscriberCellularProviders {
+      return providers.values.first
+    }
+    return nil
+  }
+
+  /**
+   * Check if carrier allows VoIP calls on its network
+   *
+   * Uses CTCarrier.allowsVOIP (deprecated but still functional on iOS 16+)
+   * Returns true on Android (no equivalent API)
+   */
+  var carrierAllowsVOIP: Bool {
+    return cachedCarrierObject?.allowsVOIP ?? true
+  }
+
+  /**
+   * ISO 3166-1 country code for the carrier
+   *
+   * Returns the ISO country code (e.g., "US", "KR", "JP")
+   * Returns empty string if unavailable
+   */
+  var carrierIsoCountryCode: String {
+    return cachedCarrierObject?.isoCountryCode ?? ""
+  }
+
+  /**
+   * Mobile Country Code (MCC)
+   *
+   * Returns 3-digit MCC per ITU-T E.212 (e.g., "310" for USA, "450" for Korea)
+   * Returns empty string if unavailable
+   */
+  var mobileCountryCode: String {
+    return cachedCarrierObject?.mobileCountryCode ?? ""
+  }
+
+  /**
+   * Mobile Network Code (MNC)
+   *
+   * Returns 2 or 3-digit MNC (e.g., "260" for T-Mobile US)
+   * Returns empty string if unavailable
+   */
+  var mobileNetworkCode: String {
+    return cachedCarrierObject?.mobileNetworkCode ?? ""
+  }
+
+  /**
+   * Mobile Network Operator (MCC + MNC combined)
+   *
+   * Returns combined MCC+MNC (e.g., "310260" for T-Mobile US)
+   * Equivalent to mobileCountryCode + mobileNetworkCode
+   * Returns empty string if unavailable
+   */
+  var mobileNetworkOperator: String {
+    let mcc = mobileCountryCode
+    let mnc = mobileNetworkCode
+    if mcc.isEmpty && mnc.isEmpty {
+      return ""
+    }
+    return mcc + mnc
+  }
+
   /// Check if location services are enabled
   func getIsLocationEnabled() -> Bool {
     return CLLocationManager.locationServicesEnabled()