feat: add entitlements support to the React Native SDK (#82)

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';