feat: implement iOS Declared Age Range API and docs

- Add required entitlements and configuration
- Update documentation with iOS specifics and error codes
- Enhance example app result display and fix lint issues

Author: nagasaicharan

README.md

@@ -21,7 +21,13 @@ yarn add react-native-store-age-signals-native-modules
    ```sh
    cd ios && pod install
    ```
-2. **Requirements**: This library uses the `DeclaredAgeRange` framework which is available on **iOS 18.0+**. On older iOS versions, the API will return a fallback response.
+3. **Entitlements**: You must enable the "Declared Age Range" capability for your app.
+    - Open your project in Xcode.
+    - Select your App target -> "Signing & Capabilities".
+    - Click "+ Capability" and add **Declared Age Range**.
+    - This adds the `com.apple.developer.declared-age-range` entitlement key to your `.entitlements` file.
+    *(Without this, the API will fail with "Error 0")*
+    > **Note**: This capability may not be available for "Personal Team" (free) provisioning profiles. You likely need a paid Apple Developer Program membership to sign apps with this entitlement.
 
 ### Android Setup
 
@@ -126,9 +132,8 @@ Returns `Promise<DeclaredAgeRangeResult>`:
 - `upperBound`: `number | null`
 
 
-### Error Codes
-
-If `errorCode` is present, it corresponds to one of the following Play Age Signals API error codes:
+### Android Error Codes
+*(Returned in `errorCode` for `getAndroidPlayAgeRangeStatus`)*
 
 | Code | Error | Description | Retryable |
 |---|---|---|---|
@@ -143,6 +148,13 @@ If `errorCode` is present, it corresponds to one of the following Play Age Signa
 | -9 | APP_NOT_OWNED | App not installed by Google Play. | No |
 | -100 | INTERNAL_ERROR | Unknown internal error. | No |
 
+### iOS Error Codes
+*(Returned in promise rejection for `requestIOSDeclaredAgeRange`)*
+
+| Code | Error | Description |
+|---|---|---|
+| 0 | IOS_ENTITLEMENT_ERROR | Missing Entitlement OR Feature unavailable on Simulator. Test on real device. |
+
 ## Contributing
 
 See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

example/ios/StoreAgeSignalsNativeModulesExample.xcodeproj/project.pbxproj

@@ -24,6 +24,7 @@
 		5DCACB8F33CDC322A6C60F78 /* libPods-StoreAgeSignalsNativeModulesExample.a */ = {isa = PBXFileReference; explicitFileType = archive.ar; includeInIndex = 0; path = "libPods-StoreAgeSignalsNativeModulesExample.a"; sourceTree = BUILT_PRODUCTS_DIR; };
 		761780EC2CA45674006654EE /* AppDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; name = AppDelegate.swift; path = StoreAgeSignalsNativeModulesExample/AppDelegate.swift; sourceTree = "<group>"; };
 		81AB9BB72411601600AC10FF /* LaunchScreen.storyboard */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = file.storyboard; name = LaunchScreen.storyboard; path = StoreAgeSignalsNativeModulesExample/LaunchScreen.storyboard; sourceTree = "<group>"; };
+		B51E33A92EE4F25D00DEA8CA /* StoreAgeSignalsNativeModulesExample.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; name = StoreAgeSignalsNativeModulesExample.entitlements; path = StoreAgeSignalsNativeModulesExample/StoreAgeSignalsNativeModulesExample.entitlements; sourceTree = "<group>"; };
 		ED297162215061F000B7C4FE /* JavaScriptCore.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = JavaScriptCore.framework; path = System/Library/Frameworks/JavaScriptCore.framework; sourceTree = SDKROOT; };
 /* End PBXFileReference section */
 
@@ -42,6 +43,7 @@
 		13B07FAE1A68108700A75B9A /* StoreAgeSignalsNativeModulesExample */ = {
 			isa = PBXGroup;
 			children = (
+				B51E33A92EE4F25D00DEA8CA /* StoreAgeSignalsNativeModulesExample.entitlements */,
 				13B07FB51A68108700A75B9A /* Images.xcassets */,
 				761780EC2CA45674006654EE /* AppDelegate.swift */,
 				13B07FB61A68108700A75B9A /* Info.plist */,
@@ -191,10 +193,14 @@
 			inputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-StoreAgeSignalsNativeModulesExample/Pods-StoreAgeSignalsNativeModulesExample-frameworks-${CONFIGURATION}-input-files.xcfilelist",
 			);
+			inputPaths = (
+			);
 			name = "[CP] Embed Pods Frameworks";
 			outputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-StoreAgeSignalsNativeModulesExample/Pods-StoreAgeSignalsNativeModulesExample-frameworks-${CONFIGURATION}-output-files.xcfilelist",
 			);
+			outputPaths = (
+			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
 			shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-StoreAgeSignalsNativeModulesExample/Pods-StoreAgeSignalsNativeModulesExample-frameworks.sh\"\n";
@@ -230,10 +236,14 @@
 			inputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-StoreAgeSignalsNativeModulesExample/Pods-StoreAgeSignalsNativeModulesExample-resources-${CONFIGURATION}-input-files.xcfilelist",
 			);
+			inputPaths = (
+			);
 			name = "[CP] Copy Pods Resources";
 			outputFileListPaths = (
 				"${PODS_ROOT}/Target Support Files/Pods-StoreAgeSignalsNativeModulesExample/Pods-StoreAgeSignalsNativeModulesExample-resources-${CONFIGURATION}-output-files.xcfilelist",
 			);
+			outputPaths = (
+			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
 			shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-StoreAgeSignalsNativeModulesExample/Pods-StoreAgeSignalsNativeModulesExample-resources.sh\"\n";
@@ -259,7 +269,9 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				CLANG_ENABLE_MODULES = YES;
+				CODE_SIGN_ENTITLEMENTS = StoreAgeSignalsNativeModulesExample/StoreAgeSignalsNativeModulesExample.entitlements;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = K8DUGA9V3J;
 				ENABLE_BITCODE = NO;
 				INFOPLIST_FILE = StoreAgeSignalsNativeModulesExample/Info.plist;
 				IPHONEOS_DEPLOYMENT_TARGET = 15.1;
@@ -287,7 +299,9 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				CLANG_ENABLE_MODULES = YES;
+				CODE_SIGN_ENTITLEMENTS = StoreAgeSignalsNativeModulesExample/StoreAgeSignalsNativeModulesExample.entitlements;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = K8DUGA9V3J;
 				INFOPLIST_FILE = StoreAgeSignalsNativeModulesExample/Info.plist;
 				IPHONEOS_DEPLOYMENT_TARGET = 15.1;
 				LD_RUNPATH_SEARCH_PATHS = (

example/ios/StoreAgeSignalsNativeModulesExample/StoreAgeSignalsNativeModulesExample.entitlements

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.developer.declared-age-range</key>
+	<true/>
+</dict>
+</plist>

example/src/App.tsx

@@ -2,7 +2,14 @@ import {
   getAndroidPlayAgeRangeStatus,
   requestIOSDeclaredAgeRange,
 } from 'react-native-store-age-signals-native-modules';
-import { Text, View, StyleSheet, Button, Platform } from 'react-native';
+import {
+  Text,
+  View,
+  StyleSheet,
+  Button,
+  Platform,
+  TextInput,
+} from 'react-native';
 import { useState } from 'react';
 
 export default function App() {
@@ -37,7 +44,7 @@ export default function App() {
           <Text style={styles.sectionTitle}>Real API</Text>
           <Button title="Check Live Age Status" onPress={checkAndroidAge} />
 
-          <View style={{ height: 20 }} />
+          <View style={styles.spacer20} />
           <Text style={styles.sectionTitle}>Mock Scenarios</Text>
 
           <Button
@@ -52,7 +59,7 @@ export default function App() {
               setResult(JSON.stringify(data, null, 2));
             }}
           />
-          <View style={{ height: 10 }} />
+          <View style={styles.spacer10} />
           <Button
             title="Mock: Supervised (13-17)"
             color="#f1c40f"
@@ -67,7 +74,7 @@ export default function App() {
               setResult(JSON.stringify(data, null, 2));
             }}
           />
-          <View style={{ height: 10 }} />
+          <View style={styles.spacer10} />
           <Button
             title="Mock: Error (API Unavailable -1)"
             color="#e74c3c"
@@ -80,7 +87,7 @@ export default function App() {
               setResult(JSON.stringify(data, null, 2));
             }}
           />
-          <View style={{ height: 10 }} />
+          <View style={styles.spacer10} />
           <Button
             title="Mock: Unknown"
             color="#95a5a6"
@@ -100,9 +107,12 @@ export default function App() {
         <Button title="Request iOS Declared Age" onPress={checkIOSAge} />
       )}
 
-      <Text selectable={true} style={styles.result}>
-        {result}
-      </Text>
+      <TextInput
+        style={styles.resultInput}
+        multiline
+        editable={false}
+        value={result}
+      />
     </View>
   );
 }
@@ -119,10 +129,16 @@ const styles = StyleSheet.create({
     marginBottom: 20,
     fontWeight: 'bold',
   },
-  result: {
+  resultInput: {
     marginTop: 20,
     fontSize: 14,
     color: '#333',
+    width: '100%',
+    height: 200,
+    borderColor: '#ccc',
+    borderWidth: 1,
+    padding: 10,
+    textAlignVertical: 'top',
   },
   actions: {
     width: '100%',
@@ -135,4 +151,10 @@ const styles = StyleSheet.create({
     marginBottom: 10,
     color: '#666',
   },
+  spacer10: {
+    height: 10,
+  },
+  spacer20: {
+    height: 20,
+  },
 });

ios/StoreAgeSignalsNativeModules.swift

@@ -5,6 +5,7 @@ import StoreKit
 #if canImport(DeclaredAgeRange)
 import DeclaredAgeRange
 #endif
+import UIKit
 
 // Check if DeclaredAgeRange type exists (iOS 18+) or handled via availability checks
 // Removing generic canImport because it's part of StoreKit usually
@@ -25,25 +26,96 @@ public class StoreAgeSignalsNativeModulesSwift: NSObject {
     resolve: @escaping RCTPromiseResolveBlock,
     reject: @escaping RCTPromiseRejectBlock
   ) {
-      // NOTE: Temporarily disabled due to API signature instability in current SDKs.
-      // The framework DeclaredAgeRange exists, but the request types vary by beta version.
-      // Re-enable when using a verified SDK with known signatures.
-      #if false 
-      if #available(iOS 18.0, *) {
-          // ... implementation ...
+      // NOTE: Using patterns from reference implementation
+      #if compiler(>=6.0) && canImport(DeclaredAgeRange)
+      // The SDK strictly requires iOS 26.0+ for AgeRangeService
+      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
+                  }
+                  
+                  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
+                  )
+                  
+                  var statusString = "declined"
+                  var lowerBound: NSNumber? = nil
+                  var upperBound: NSNumber? = nil
+                  var parentControls: String? = nil
+                  
+                  switch response {
+                  case .sharing(let declaration):
+                       if let declStatus = declaration.ageRangeDeclaration {
+                           statusString = String(describing: declStatus)
+                       } else {
+                           statusString = "sharing"
+                       }
+                       
+                       if let lower = declaration.lowerBound {
+                           lowerBound = NSNumber(value: lower)
+                       }
+                       if let upper = declaration.upperBound {
+                           upperBound = NSNumber(value: upper)
+                       }
+                       
+                       let controlsRaw = declaration.activeParentalControls.rawValue
+                       parentControls = "\(controlsRaw)"
+                       
+                  case .declinedSharing:
+                       statusString = "declined"
+                  @unknown default:
+                       statusString = "unknown"
+                  }
+                  
+                  let resultMap: [String: Any?] = [
+                      "status": statusString,
+                      "parentControls": parentControls,
+                      "lowerBound": lowerBound,
+                      "upperBound": upperBound
+                  ]
+                  resolve(resultMap)
+                  
+              } catch {
+                 // Enhance "Error 0" with a helpful message
+                 var errorMsg = error.localizedDescription
+                 if (error as NSError).code == 0 {
+                     errorMsg += ". (Hint: Missing Entitlement OR Feature is unavailable on Simulator. Verify on real device.)"
+                 }
+                 reject("ERR_IOS_AGE_REQUEST", errorMsg, error)
+              }
           }
       } else {
-         // ...
+          resolve(["status": nil, "error": "Requires iOS 26.0+"])
       }
       #else
-      resolve([
-          "status": nil,
-          "parentControls": nil,
-          "lowerBound": nil,
-          "upperBound": nil
-      ])
+      resolve(["status": nil, "error": "SDK not available"])
       #endif
   }
+  
+  // Helper to get top view controller
+  private func topViewController() -> UIViewController? {
+    guard let windowScene = UIApplication.shared.connectedScenes
+      .compactMap({ $0 as? UIWindowScene })
+      .first(where: { $0.activationState == .foregroundActive }),
+          let window = windowScene.windows.first(where: { $0.isKeyWindow }),
+          let rootViewController = window.rootViewController else {
+      return nil
+    }
+
+    var topController = rootViewController
+    while let presentedViewController = topController.presentedViewController {
+      topController = presentedViewController
+    }
+
+    return topController
+  }
 }