feat: add entitlements support to the React Native SDK

Wire the native entitlements APIs through the RN bridge and JS API. The feature
already ships in the native SDKs this package bundles (frontegg-ios-swift 1.3.10
and frontegg-android-kotlin 1.3.34), so no native version bump is needed — this
just exposes them to JS.

- Android (FronteggRNModule.kt): loadEntitlements / getFeatureEntitlement /
  getPermissionEntitlement @ReactMethods calling FronteggAuth, serializing
  Entitlement -> { isEntitled, justification }.
- iOS (FronteggRN.swift + .m): matching @objc bridge methods.
- JS (FronteggNative.ts + index.tsx): loadEntitlements(forceRefresh?),
  getFeatureEntitlement(key), getPermissionEntitlement(key), and the Entitlement type.
- docs/usage.md: Entitlements usage section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dianaKhortiuk-frontegg

android/src/main/java/com/frontegg/reactnative/FronteggRNModule.kt

@@ -12,6 +12,7 @@ import com.facebook.react.common.LifecycleState
 import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.frontegg.android.AdminPortalActivity
 import com.frontegg.android.fronteggAuth
+import com.frontegg.android.models.Entitlement
 import io.reactivex.rxjava3.core.Observable
 import io.reactivex.rxjava3.disposables.Disposable
 import kotlin.time.DurationUnit
@@ -229,6 +230,29 @@ class FronteggRNModule(val reactContext: ReactApplicationContext) :
     promise.resolve(null)
   }
 
+  @ReactMethod
+  fun loadEntitlements(forceRefresh: Boolean, promise: Promise) {
+    auth.loadEntitlements(forceRefresh) { success ->
+      promise.resolve(success)
+    }
+  }
+
+  @ReactMethod
+  fun getFeatureEntitlement(key: String, promise: Promise) {
+    promise.resolve(entitlementToMap(auth.getFeatureEntitlements(key)))
+  }
+
+  @ReactMethod
+  fun getPermissionEntitlement(key: String, promise: Promise) {
+    promise.resolve(entitlementToMap(auth.getPermissionEntitlements(key)))
+  }
+
+  private fun entitlementToMap(entitlement: Entitlement): WritableMap =
+    Arguments.createMap().apply {
+      putBoolean("isEntitled", entitlement.isEntitled)
+      putString("justification", entitlement.justification)
+    }
+
   override fun getConstants(): MutableMap<String, Any?> = fronteggConstants.toMap()
 
   companion object {

docs/usage.md

@@ -123,6 +123,35 @@ export function MyScreen() {
 }
 ```
 
+## Entitlements
+
+Gate features and permissions on-device. Call `loadEntitlements()` once the user is authenticated, then read feature/permission entitlements from the cache:
+
+```tsx
+import {
+  loadEntitlements,
+  getFeatureEntitlement,
+  getPermissionEntitlement,
+} from '@frontegg/react-native';
+
+// Load (or refresh) the current user's entitlements into the SDK cache.
+await loadEntitlements();
+
+// Check a feature-flag entitlement.
+const feature = await getFeatureEntitlement('my-feature-key');
+if (feature.isEntitled) {
+  // show the gated feature
+} else {
+  console.log('Not entitled:', feature.justification);
+}
+
+// Check a permission entitlement.
+const permission = await getPermissionEntitlement('fe.secure.read.users');
+console.log(permission.isEntitled, permission.justification);
+```
+
+Each call resolves to an `Entitlement` — `{ isEntitled: boolean; justification?: string | null }`. When `isEntitled` is `false`, `justification` explains why (e.g. `"NOT_AUTHENTICATED"`, `"ENTITLEMENTS_NOT_LOADED"`, `"MISSING_FEATURE"`, `"MISSING_PERMISSION"`).
+
 ## Check user authentication state
 
 Use the `useAuth` hook with `showLoader` and `isLoading` to conditionally display your app:

ios/FronteggRN.m

@@ -58,4 +58,19 @@ @interface RCT_EXTERN_MODULE(FronteggRN, RCTEventEmitter)
                   openAdminPortal: (RCTPromiseResolveBlock)resolve
                   rejecter: (RCTPromiseRejectBlock)reject
                   )
+RCT_EXTERN_METHOD(
+                  loadEntitlements: (BOOL)forceRefresh
+                  resolver: (RCTPromiseResolveBlock)resolve
+                  rejecter: (RCTPromiseRejectBlock)reject
+                  )
+RCT_EXTERN_METHOD(
+                  getFeatureEntitlement: (NSString *)key
+                  resolver: (RCTPromiseResolveBlock)resolve
+                  rejecter: (RCTPromiseRejectBlock)reject
+                  )
+RCT_EXTERN_METHOD(
+                  getPermissionEntitlement: (NSString *)key
+                  resolver: (RCTPromiseResolveBlock)resolve
+                  rejecter: (RCTPromiseRejectBlock)reject
+                  )
 @end

ios/FronteggRN.swift

@@ -294,6 +294,42 @@ class FronteggRN: RCTEventEmitter {
         }
     }
 
+    @objc
+    func loadEntitlements(
+        _ forceRefresh: Bool,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        fronteggApp.auth.loadEntitlements(forceRefresh: forceRefresh) { success in
+            resolver(success)
+        }
+    }
+
+    @objc
+    func getFeatureEntitlement(
+        _ key: String,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        resolver(Self.entitlementToDict(fronteggApp.auth.getFeatureEntitlements(featureKey: key)))
+    }
+
+    @objc
+    func getPermissionEntitlement(
+        _ key: String,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        resolver(Self.entitlementToDict(fronteggApp.auth.getPermissionEntitlements(permissionKey: key)))
+    }
+
+    private static func entitlementToDict(_ entitlement: Entitlement) -> [String: Any] {
+        return [
+            "isEntitled": entitlement.isEntitled,
+            "justification": entitlement.justification ?? NSNull(),
+        ]
+    }
+
     private static func topViewController() -> UIViewController? {
         let keyWindow = UIApplication.shared.connectedScenes
             .compactMap { $0 as? UIWindowScene }

src/FronteggNative.ts

@@ -89,6 +89,39 @@ export async function openAdminPortal(): Promise<void> {
   return FronteggRN.openAdminPortal();
 }
 
+export interface Entitlement {
+  /** Whether the user is entitled to the requested feature/permission. */
+  isEntitled: boolean;
+  /**
+   * Optional reason when `isEntitled` is false — e.g. `"NOT_AUTHENTICATED"`,
+   * `"ENTITLEMENTS_NOT_LOADED"`, `"MISSING_FEATURE"`, `"MISSING_PERMISSION"`.
+   */
+  justification?: string | null;
+}
+
+/**
+ * Loads the current user's entitlements into the SDK cache. Call this after
+ * authentication (and again with `forceRefresh` to refetch) before reading
+ * feature/permission entitlements. Resolves to `true` when entitlements loaded.
+ */
+export async function loadEntitlements(
+  forceRefresh: boolean = false
+): Promise<boolean> {
+  return FronteggRN.loadEntitlements(forceRefresh);
+}
+
+/** Returns the on-device entitlement for a feature-flag key. */
+export async function getFeatureEntitlement(key: string): Promise<Entitlement> {
+  return FronteggRN.getFeatureEntitlement(key);
+}
+
+/** Returns the on-device entitlement for a permission key. */
+export async function getPermissionEntitlement(
+  key: string
+): Promise<Entitlement> {
+  return FronteggRN.getPermissionEntitlement(key);
+}
+
 function debounce<T extends (...args: any[]) => any>(func: T, waitFor: number) {
   let timeout: any;
 

src/index.tsx

@@ -14,4 +14,8 @@ export {
   isSteppedUp,
   stepUp,
   openAdminPortal,
+  loadEntitlements,
+  getFeatureEntitlement,
+  getPermissionEntitlement,
 } from './FronteggNative';
+export type { Entitlement } from './FronteggNative';