@milkinteractive/react-native-age-range 1.0.4 → 1.0.6

package/README.md

@@ -191,6 +191,86 @@ async function checkEligibility() {
 }
 ```
 
+## 🛡️ PermissionKit Integration (iOS 26+)
+
+This package also supports Apple's **PermissionKit** framework for apps that need parental consent flows. Use these APIs when the `parentalControls` flags from `requestIOSDeclaredAgeRange()` indicate they're needed.
+
+### When to Use PermissionKit
+
+After calling `requestIOSDeclaredAgeRange()`, check the `parentalControls` object:
+
+```typescript
+const ageResult = await requestIOSDeclaredAgeRange(13, 17, 21);
+
+if (ageResult.parentalControls?.significantAppChangeApprovalRequired) {
+  // App updates require parental approval → use requestIOSSignificantChangeApproval()
+}
+
+if (ageResult.parentalControls?.communicationLimits) {
+  // Communication with unknown contacts requires approval → use requestIOSCommunicationPermission()
+}
+```
+
+### Significant Change Approval
+
+When your app has significant updates that require parental consent:
+
+```typescript
+import { requestIOSSignificantChangeApproval } from '@milkinteractive/react-native-age-range';
+
+const result = await requestIOSSignificantChangeApproval();
+
+if (result.status === 'pending') {
+  // Request sent to parent/guardian via Messages
+  // Show "waiting for approval" UI
+} else if (result.error) {
+  console.error('Significant change request failed:', result.error);
+}
+```
+
+### Communication Permissions
+
+For apps with chat/messaging features, request permission to communicate with unknown contacts:
+
+```typescript
+import {
+  getIOSKnownCommunicationHandles,
+  requestIOSCommunicationPermission,
+} from '@milkinteractive/react-native-age-range';
+
+// 1. Check which contacts are already known (approved)
+const knownResult = await getIOSKnownCommunicationHandles([
+  { handle: 'user@example.com', handleKind: 'email' },
+  { handle: 'gamer123', handleKind: 'custom' },
+]);
+
+// 2. Request permission for unknown contacts
+const unknownContacts = contacts.filter(
+  c => !knownResult.knownHandles.includes(c.handle)
+);
+
+if (unknownContacts.length > 0) {
+  const permResult = await requestIOSCommunicationPermission(
+    unknownContacts.map(c => ({
+      handle: c.handle,
+      handleKind: 'custom',
+      displayName: c.displayName, // Shown to parent in approval request
+    })),
+    ['message', 'call'] // Requested communication actions
+  );
+}
+```
+
+### PermissionKit Requirements
+
+- **iOS 26.0+** for Significant Change API
+- **iOS 26.2+** for Communication Limits API
+- **Family Sharing** must be enabled on the device
+- **Communication Limits** must be enabled by parent/guardian
+- No additional entitlements required (uses system permissions)
+
+> **Note**: PermissionKit features require a real device with Family Sharing configured. Simulator testing has limited functionality.
+
 ## 🧪 Developer Mock Mode
 
 Testing store APIs usually requires signed production builds. This library includes a powerful **Mock Mode** for development.
@@ -271,6 +351,49 @@ Check if the current Android user is subject to age verification requirements.
 
 **Note**: Makes a lightweight API call to determine eligibility.
 
+### `requestIOSSignificantChangeApproval()`
+Request parental approval for significant app changes (iOS PermissionKit).
+
+**Requirements**: iOS 26.0+
+
+**Returns**: `Promise<SignificantChangeResult>`
+- `status`: `'approved' | 'denied' | 'pending' | null` - Current approval status
+- `error`: `string | null` - Error message if request failed
+
+**Usage**: Call when `parentalControls.significantAppChangeApprovalRequired` is `true`.
+
+### `requestIOSCommunicationPermission(contacts, actions?)`
+Request permission for a child to communicate with specified contacts (iOS PermissionKit).
+
+**Requirements**: iOS 26.2+
+
+| Parameter | Type | Description |
+|---|---|---|
+| `contacts` | `CommunicationContact[]` | Contacts to request permission for |
+| `actions` | `CommunicationAction[]` | Optional: `['message']`, `['call']`, `['video']` (default: `['message']`) |
+
+**CommunicationContact**:
+- `handle`: `string` - Unique identifier (phone, email, username)
+- `handleKind`: `'phoneNumber' | 'email' | 'custom'`
+- `displayName`: `string` (optional) - Shown to parent in approval request
+
+**Returns**: `Promise<CommunicationPermissionResult>`
+- `granted`: `boolean` - Whether the permission dialog was shown successfully
+- `error`: `string | null` - Error message if request failed
+
+### `getIOSKnownCommunicationHandles(handles)`
+Check which handles are recognized by the system (known contacts).
+
+**Requirements**: iOS 26.2+
+
+| Parameter | Type | Description |
+|---|---|---|
+| `handles` | `CommunicationContact[]` | Handles to check |
+
+**Returns**: `Promise<KnownHandlesResult>`
+- `knownHandles`: `string[]` - Array of handle values that are known/approved
+- `error`: `string | null` - Error message if check failed
+
 ## 🚨 Troubleshooting
 
 ### iOS Errors
@@ -303,6 +426,8 @@ Check if the current Android user is subject to age verification requirements.
 **Apple iOS:**
 - [Declared Age Range Framework](https://developer.apple.com/documentation/declaredagerange) - Official Apple Developer Documentation
 - [WWDC25: Deliver age-appropriate experiences in your app](https://developer.apple.com/videos/play/wwdc2025/299/) - Session video explaining implementation
+- [PermissionKit Framework](https://developer.apple.com/documentation/PermissionKit) - Official PermissionKit Documentation
+- [WWDC25: Enhance child safety with PermissionKit](https://developer.apple.com/videos/play/wwdc2025/293/) - PermissionKit session video
 
 **Google Android:**
 - [Play Age Signals Overview](https://developer.android.com/google/play/age-signals/overview) - Introduction and concepts

package/ios/StoreAgeSignalsNativeModules.mm

@@ -39,17 +39,17 @@ RCT_EXPORT_METHOD(getAndroidPlayAgeRangeStatus : (RCTPromiseResolveBlock)
   resolve(result);
 }
 
-RCT_EXPORT_METHOD(requestIOSDeclaredAgeRange : (
-    double)firstThresholdAge secondThresholdAge : (double)
-                      secondThresholdAge thirdThresholdAge : (double)
-                          thirdThresholdAge resolve : (RCTPromiseResolveBlock)
-                              resolve reject : (RCTPromiseRejectBlock)reject) {
-  // Assuming _swiftImpl has a method named
-  // requestIOSDeclaredAgeRangeWithFirstThresholdAge that matches the signature.
+RCT_EXPORT_METHOD(requestIOSDeclaredAgeRange : (nonnull NSNumber *)firstThresholdAge
+                      secondThresholdAge : (NSNumber *)secondThresholdAge
+                      thirdThresholdAge : (NSNumber *)thirdThresholdAge
+                      resolve : (RCTPromiseResolveBlock)resolve
+                      reject : (RCTPromiseRejectBlock)reject) {
+  // Convert NSNumber to NSNumber (handling nil for optional params)
+  // Swift side expects NSNumber which can represent nil via NSNull
   [_swiftImpl
-      requestIOSDeclaredAgeRangeWithFirstThresholdAge:@(firstThresholdAge)
-                                   secondThresholdAge:@(secondThresholdAge)
-                                    thirdThresholdAge:@(thirdThresholdAge)
+      requestIOSDeclaredAgeRangeWithFirstThresholdAge:firstThresholdAge
+                                   secondThresholdAge:secondThresholdAge
+                                    thirdThresholdAge:thirdThresholdAge
                                               resolve:resolve
                                                reject:reject];
 }
@@ -59,6 +59,33 @@ RCT_EXPORT_METHOD(isEligibleForAgeFeatures : (RCTPromiseResolveBlock)
   [_swiftImpl isEligibleForAgeFeaturesWithResolve:resolve reject:reject];
 }
 
+// MARK: - PermissionKit: Significant Change API
+
+RCT_EXPORT_METHOD(requestSignificantChangeApproval : (RCTPromiseResolveBlock)
+                      resolve reject : (RCTPromiseRejectBlock)reject) {
+  [_swiftImpl requestSignificantChangeApprovalWithResolve:resolve reject:reject];
+}
+
+// MARK: - PermissionKit: Communication Limits API
+
+RCT_EXPORT_METHOD(requestCommunicationPermission : (NSArray *)contacts
+                      actions : (NSArray *)actions
+                      resolve : (RCTPromiseResolveBlock)resolve
+                      reject : (RCTPromiseRejectBlock)reject) {
+  [_swiftImpl requestCommunicationPermissionWithContacts:contacts
+                                                 actions:actions
+                                                 resolve:resolve
+                                                  reject:reject];
+}
+
+RCT_EXPORT_METHOD(getKnownCommunicationHandles : (NSArray *)handles
+                      resolve : (RCTPromiseResolveBlock)resolve
+                      reject : (RCTPromiseRejectBlock)reject) {
+  [_swiftImpl getKnownCommunicationHandlesWithHandles:handles
+                                              resolve:resolve
+                                               reject:reject];
+}
+
 // Don't compile this code when we build for the old architecture.
 // Don't compile this code when we build for the old architecture.
 #ifdef RCT_NEW_ARCH_ENABLED

package/ios/StoreAgeSignalsNativeModules.swift

@@ -5,6 +5,11 @@ import StoreKit
 #if canImport(DeclaredAgeRange)
 import DeclaredAgeRange
 #endif
+
+#if canImport(PermissionKit)
+import PermissionKit
+#endif
+
 import UIKit
 
 // Check if DeclaredAgeRange type exists (iOS 18+) or handled via availability checks
@@ -21,8 +26,8 @@ public class StoreAgeSignalsNativeModulesSwift: NSObject {
   @objc
   public func requestIOSDeclaredAgeRange(
     firstThresholdAge: NSNumber,
-    secondThresholdAge: NSNumber,
-    thirdThresholdAge: NSNumber,
+    secondThresholdAge: NSNumber?,
+    thirdThresholdAge: NSNumber?,
     resolve: @escaping RCTPromiseResolveBlock,
     reject: @escaping RCTPromiseRejectBlock
   ) {
@@ -36,16 +41,21 @@ public class StoreAgeSignalsNativeModulesSwift: NSObject {
                        reject("VIEW_CONTROLLER_ERROR", "Could not find top view controller", nil)
                        return
                   }
-                  
+
+                  // Convert NSNumber to Int, handling optional parameters
                   let t1 = Int(truncating: firstThresholdAge)
-                  let t2 = Int(truncating: secondThresholdAge)
-                  let t3 = Int(truncating: thirdThresholdAge)
-                  
-                  // Use AgeRangeService as per reference
-                  let response = try await AgeRangeService.shared.requestAgeRange(
-                      ageGates: t1, t2, t3,
-                      in: viewController
-                  )
+                  let t2 = secondThresholdAge.map { Int(truncating: $0) }
+                  let t3 = thirdThresholdAge.map { Int(truncating: $0) }
+
+                  // Call API with provided thresholds (variadic params require separate calls)
+                  let response: AgeRangeService.Response
+                  if let t2, let t3 {
+                      response = try await AgeRangeService.shared.requestAgeRange(ageGates: t1, t2, t3, in: viewController)
+                  } else if let t2 {
+                      response = try await AgeRangeService.shared.requestAgeRange(ageGates: t1, t2, in: viewController)
+                  } else {
+                      response = try await AgeRangeService.shared.requestAgeRange(ageGates: t1, in: viewController)
+                  }
                   
                   var statusString = "declined"
                   var lowerBound: NSNumber? = nil
@@ -160,6 +170,222 @@ public class StoreAgeSignalsNativeModulesSwift: NSObject {
       #endif
   }
 
+  // MARK: - PermissionKit: Significant Change API
+
+  @objc
+  public func requestSignificantChangeApproval(
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+      #if compiler(>=6.0) && canImport(PermissionKit)
+      if #available(iOS 26.0, *) {
+          Task { @MainActor in
+              do {
+                  guard let viewController = self.topViewController() else {
+                      reject("VIEW_CONTROLLER_ERROR", "Could not find top view controller", nil)
+                      return
+                  }
+
+                  var topic = SignificantAppUpdateTopic()
+                  var question = PermissionQuestion(significantAppUpdateTopic: topic)
+
+                  try await AskCenter.current.ask(question: question, in: viewController)
+
+                  // If we get here without error, the request was shown successfully
+                  // The actual approval status is delivered asynchronously via updates
+                  let resultMap: [String: Any?] = [
+                      "status": "pending",
+                      "error": nil
+                  ]
+                  resolve(resultMap)
+
+              } catch {
+                  var errorMsg = error.localizedDescription
+                  if errorMsg.contains("region") {
+                      errorMsg += ". (Hint: User may be in a region that does not support this feature.)"
+                  }
+                  reject("ERR_IOS_SIGNIFICANT_CHANGE", errorMsg, error)
+              }
+          }
+      } else {
+          resolve(["status": nil, "error": "Requires iOS 26.0+"])
+      }
+      #else
+      resolve(["status": nil, "error": "PermissionKit SDK not available"])
+      #endif
+  }
+
+  // MARK: - PermissionKit: Communication Limits API
+
+  @objc
+  public func requestCommunicationPermission(
+    contacts: NSArray,
+    actions: NSArray,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+      #if compiler(>=6.0) && canImport(PermissionKit)
+      if #available(iOS 26.2, *) {
+          Task { @MainActor in
+              do {
+                  guard let viewController = self.topViewController() else {
+                      reject("VIEW_CONTROLLER_ERROR", "Could not find top view controller", nil)
+                      return
+                  }
+
+                  // Parse contacts from JS
+                  var personInfoList: [PersonInformation] = []
+                  for contact in contacts {
+                      guard let contactDict = contact as? [String: Any],
+                            let handleValue = contactDict["handle"] as? String,
+                            let handleKindStr = contactDict["handleKind"] as? String else {
+                          continue
+                      }
+
+                      let handleKind: CommunicationHandle.Kind
+                      switch handleKindStr {
+                      case "phoneNumber":
+                          handleKind = .phoneNumber
+                      case "email":
+                          handleKind = .email
+                      default:
+                          handleKind = .custom
+                      }
+
+                      let handle = CommunicationHandle(value: handleValue, kind: handleKind)
+
+                      // Optional display name
+                      var nameComponents: PersonNameComponents? = nil
+                      if let displayName = contactDict["displayName"] as? String {
+                          var components = PersonNameComponents()
+                          components.nickname = displayName
+                          nameComponents = components
+                      }
+
+                      let personInfo = PersonInformation(handle: handle, nameComponents: nameComponents)
+                      personInfoList.append(personInfo)
+                  }
+
+                  guard !personInfoList.isEmpty else {
+                      reject("ERR_IOS_COMM_PERMISSION", "No valid contacts provided", nil)
+                      return
+                  }
+
+                  // Parse actions
+                  var communicationActions: Set<CommunicationTopic.Action> = []
+                  for action in actions {
+                      if let actionStr = action as? String {
+                          switch actionStr {
+                          case "message":
+                              communicationActions.insert(.message)
+                          case "call":
+                              communicationActions.insert(.call)
+                          case "video":
+                              communicationActions.insert(.video)
+                          default:
+                              break
+                          }
+                      }
+                  }
+
+                  // Default to message if no actions specified
+                  if communicationActions.isEmpty {
+                      communicationActions.insert(.message)
+                  }
+
+                  var topic = CommunicationTopic(personInformation: personInfoList)
+                  topic.actions = communicationActions
+
+                  var question = PermissionQuestion(communicationTopic: topic)
+
+                  try await CommunicationLimits.current.ask(question, in: viewController)
+
+                  // If we get here without error, the request was shown successfully
+                  let resultMap: [String: Any?] = [
+                      "granted": true,
+                      "error": nil
+                  ]
+                  resolve(resultMap)
+
+              } catch {
+                  var errorMsg = error.localizedDescription
+                  if errorMsg.contains("region") {
+                      errorMsg += ". (Hint: User may be in a region that does not support this feature.)"
+                  } else if errorMsg.contains("Family Sharing") || errorMsg.contains("Communication Limits") {
+                      errorMsg += ". (Hint: Family Sharing and Communication Limits must be enabled.)"
+                  }
+                  reject("ERR_IOS_COMM_PERMISSION", errorMsg, error)
+              }
+          }
+      } else {
+          resolve(["granted": false, "error": "Requires iOS 26.2+"])
+      }
+      #else
+      resolve(["granted": false, "error": "PermissionKit SDK not available"])
+      #endif
+  }
+
+  @objc
+  public func getKnownCommunicationHandles(
+    handles: NSArray,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+      #if compiler(>=6.0) && canImport(PermissionKit)
+      if #available(iOS 26.2, *) {
+          Task {
+              do {
+                  // Parse handles from JS
+                  var communicationHandles: Set<CommunicationHandle> = []
+                  for handle in handles {
+                      guard let handleDict = handle as? [String: Any],
+                            let handleValue = handleDict["handle"] as? String,
+                            let handleKindStr = handleDict["handleKind"] as? String else {
+                          continue
+                      }
+
+                      let handleKind: CommunicationHandle.Kind
+                      switch handleKindStr {
+                      case "phoneNumber":
+                          handleKind = .phoneNumber
+                      case "email":
+                          handleKind = .email
+                      default:
+                          handleKind = .custom
+                      }
+
+                      let commHandle = CommunicationHandle(value: handleValue, kind: handleKind)
+                      communicationHandles.insert(commHandle)
+                  }
+
+                  guard !communicationHandles.isEmpty else {
+                      reject("ERR_IOS_KNOWN_HANDLES", "No valid handles provided", nil)
+                      return
+                  }
+
+                  let knownHandles = await CommunicationLimits.current.knownHandles(in: communicationHandles)
+
+                  // Convert back to string array for JS
+                  let knownHandleValues = knownHandles.map { $0.value }
+
+                  let resultMap: [String: Any?] = [
+                      "knownHandles": knownHandleValues,
+                      "error": nil
+                  ]
+                  resolve(resultMap)
+
+              } catch {
+                  reject("ERR_IOS_KNOWN_HANDLES", error.localizedDescription, error)
+              }
+          }
+      } else {
+          resolve(["knownHandles": [], "error": "Requires iOS 26.2+"])
+      }
+      #else
+      resolve(["knownHandles": [], "error": "PermissionKit SDK not available"])
+      #endif
+  }
+
   // Helper to get top view controller
   private func topViewController() -> UIViewController? {
     guard let windowScene = UIApplication.shared.connectedScenes