react-native-permission-gate 0.1.0

package/lib/typescript/src/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The OS-level truth about a permission, normalized across platforms.
+ *
+ * - `granted`      - access is allowed.
+ * - `limited`      - partial access (iOS: e.g. selected photos / contacts).
+ * - `requestable`  - not granted yet, but the OS prompt can still be shown.
+ * - `blocked`      - denied and the OS will no longer prompt; only Settings helps.
+ * - `unavailable`  - the capability does not exist on this device/build.
+ */
+export type PermissionStatus = 'granted' | 'limited' | 'requestable' | 'blocked' | 'unavailable';
+/**
+ * Where the request flow currently sits. Independent from {@link PermissionStatus}:
+ * `status` is the OS truth, `phase` is the position in the UX state machine.
+ *
+ * - `idle`        - nothing in flight.
+ * - `rationale`   - pre-prompt is shown, awaiting the user's decision.
+ * - `requesting`  - the native OS dialog is up.
+ * - `settled`     - the flow finished; read `status` for the outcome.
+ */
+export type FlowPhase = 'idle' | 'rationale' | 'requesting' | 'settled';
+/**
+ * Cross-platform permission aliases. Each maps to the correct native permission
+ * per platform inside the adapter. Aliases with no meaning on the current
+ * platform resolve to `unavailable`.
+ */
+export type PermissionName = 'camera' | 'microphone' | 'photoLibrary' | 'photoLibraryAddOnly' | 'mediaLibrary' | 'contacts' | 'calendar' | 'calendarWriteOnly' | 'reminders' | 'locationWhenInUse' | 'locationAlways' | 'notifications' | 'bluetooth' | 'motion' | 'speechRecognition' | 'appTrackingTransparency' | 'bodySensors' | 'storageReadAudio' | 'storageReadVideo' | 'faceId';
+/**
+ * Backend that performs the actual native permission calls. The core state
+ * machine is adapter-agnostic, which keeps it fully unit-testable without any
+ * native module. The default adapter is built on `react-native-permissions`.
+ */
+export interface PermissionAdapter {
+    /** Whether the alias is meaningful on the current platform. */
+    isSupported(name: PermissionName): boolean;
+    /** Read current status without prompting. */
+    check(name: PermissionName): Promise<PermissionStatus>;
+    /** Trigger the native OS prompt and resolve with the resulting status. */
+    request(name: PermissionName): Promise<PermissionStatus>;
+    /** Open the OS settings screen for this app. */
+    openSettings(): Promise<void>;
+}
+export interface UsePermissionOptions {
+    /**
+     * Gate the native prompt behind a `rationale` phase so you can show a
+     * pre-prompt explanation first. When `true`, `request()` moves to
+     * `phase: 'rationale'` and waits for `confirmRationale()` / `cancelRationale()`.
+     * @default false
+     */
+    rationale?: boolean;
+    /**
+     * Re-check status when the app returns to the foreground - catches changes the
+     * user made in the OS Settings screen.
+     * @default true
+     */
+    revalidateOnFocus?: boolean;
+    /**
+     * Run the full request flow automatically on mount.
+     * @default false
+     */
+    requestOnMount?: boolean;
+    /** Called whenever the resolved {@link PermissionStatus} changes. */
+    onStatusChange?: (status: PermissionStatus) => void;
+    /** Override the backend. Defaults to the `react-native-permissions` adapter. */
+    adapter?: PermissionAdapter;
+}
+/** The headless controller returned by {@link usePermission}. */
+export interface PermissionController {
+    status: PermissionStatus;
+    phase: FlowPhase;
+    /** Convenience: `status === 'granted'`. */
+    isGranted: boolean;
+    /** Convenience: `status === 'blocked'`. */
+    isBlocked: boolean;
+    /**
+     * Run the flow: check → (rationale gate) → native prompt → settle. The promise
+     * resolves with the final status once the whole flow finishes, so it works
+     * both imperatively (`await request()`) and declaratively (render on `phase`).
+     */
+    request: () => Promise<PermissionStatus>;
+    /** Proceed from the `rationale` phase to the native prompt. */
+    confirmRationale: () => void;
+    /** Abort the `rationale` phase and return to `idle`. */
+    cancelRationale: () => void;
+    /** Open the OS settings screen for this app. */
+    openSettings: () => Promise<void>;
+    /** Re-check status on demand (also happens automatically on focus). */
+    refresh: () => Promise<PermissionStatus>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAC1B,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,aAAa,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,YAAY,GACZ,cAAc,GACd,qBAAqB,GACrB,cAAc,GACd,UAAU,GACV,UAAU,GACV,mBAAmB,GACnB,WAAW,GACX,mBAAmB,GACnB,gBAAgB,GAChB,eAAe,GACf,WAAW,GACX,QAAQ,GACR,mBAAmB,GACnB,yBAAyB,GACzB,aAAa,GACb,kBAAkB,GAClB,kBAAkB,GAClB,QAAQ,CAAC;AAEb;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC;IAC3C,6CAA6C;IAC7C,KAAK,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACvD,0EAA0E;IAC1E,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACzD,gDAAgD;IAChD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACpD,gFAAgF;IAChF,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,2CAA2C;IAC3C,SAAS,EAAE,OAAO,CAAC;IACnB,2CAA2C;IAC3C,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACzC,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,wDAAwD;IACxD,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B,gDAAgD;IAChD,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,uEAAuE;IACvE,OAAO,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC1C"}

package/package.json

@@ -0,0 +1,145 @@
+{
+  "name": "react-native-permission-gate",
+  "version": "0.1.0",
+  "description": "Headless permission flow orchestration for React Native. A state-machine hook, rationale gating, and a PermissionGate component. Bring your own UI.",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "react-native-permission-gate-source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-permission-gate-example",
+    "test": "jest",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\""
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "permissions",
+    "permission",
+    "hooks",
+    "headless",
+    "rationale",
+    "permission-flow",
+    "react-native-permissions",
+    "expo"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cengizemre/react-native-permission-gate.git"
+  },
+  "author": "Emre Cengiz <34921701+cengizemre@users.noreply.github.com> (https://github.com/cengizemre)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/cengizemre/react-native-permission-gate/issues"
+  },
+  "homepage": "https://github.com/cengizemre/react-native-permission-gate#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@react-native/babel-preset": "0.85.0",
+    "@react-native/eslint-config": "0.85.0",
+    "@react-native/jest-preset": "0.85.0",
+    "@testing-library/react-native": "^13.2.0",
+    "@types/jest": "^29.5.12",
+    "@types/react": "^19.2.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.6",
+    "jest": "^29.7.0",
+    "prettier": "^3.8.3",
+    "react": "19.2.3",
+    "react-native": "0.85.0",
+    "react-native-builder-bob": "^0.43.0",
+    "react-native-permissions": "^5.6.0",
+    "react-test-renderer": "19.2.3",
+    "turbo": "^2.9.16",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-permissions": ">=4.1.5"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "jest": {
+    "preset": "@react-native/jest-preset",
+    "setupFiles": [
+      "<rootDir>/jest.setup.js"
+    ],
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "create-react-native-library": {
+    "type": "library",
+    "languages": "js",
+    "tools": [
+      "eslint"
+    ],
+    "version": "0.63.0"
+  }
+}

package/src/adapters/reactNativePermissions.ts

@@ -0,0 +1,119 @@
+import { Platform } from 'react-native';
+import {
+  PERMISSIONS,
+  RESULTS,
+  check,
+  request,
+  checkNotifications,
+  requestNotifications,
+  openSettings,
+  type Permission,
+  type PermissionStatus as RNPermissionStatus,
+} from 'react-native-permissions';
+import type {
+  PermissionAdapter,
+  PermissionName,
+  PermissionStatus,
+} from '../types';
+
+type NativeMap = Partial<Record<PermissionName, Permission>>;
+
+const IOS: NativeMap = {
+  camera: PERMISSIONS.IOS.CAMERA,
+  microphone: PERMISSIONS.IOS.MICROPHONE,
+  photoLibrary: PERMISSIONS.IOS.PHOTO_LIBRARY,
+  photoLibraryAddOnly: PERMISSIONS.IOS.PHOTO_LIBRARY_ADD_ONLY,
+  mediaLibrary: PERMISSIONS.IOS.MEDIA_LIBRARY,
+  contacts: PERMISSIONS.IOS.CONTACTS,
+  calendar: PERMISSIONS.IOS.CALENDARS,
+  calendarWriteOnly: PERMISSIONS.IOS.CALENDARS_WRITE_ONLY,
+  reminders: PERMISSIONS.IOS.REMINDERS,
+  locationWhenInUse: PERMISSIONS.IOS.LOCATION_WHEN_IN_USE,
+  locationAlways: PERMISSIONS.IOS.LOCATION_ALWAYS,
+  bluetooth: PERMISSIONS.IOS.BLUETOOTH,
+  motion: PERMISSIONS.IOS.MOTION,
+  speechRecognition: PERMISSIONS.IOS.SPEECH_RECOGNITION,
+  appTrackingTransparency: PERMISSIONS.IOS.APP_TRACKING_TRANSPARENCY,
+  faceId: PERMISSIONS.IOS.FACE_ID,
+  // Android-only aliases (storageReadAudio, storageReadVideo, bodySensors)
+  // resolve to unavailable here.
+};
+
+const ANDROID: NativeMap = {
+  camera: PERMISSIONS.ANDROID.CAMERA,
+  microphone: PERMISSIONS.ANDROID.RECORD_AUDIO,
+  photoLibrary: PERMISSIONS.ANDROID.READ_MEDIA_IMAGES,
+  storageReadAudio: PERMISSIONS.ANDROID.READ_MEDIA_AUDIO,
+  storageReadVideo: PERMISSIONS.ANDROID.READ_MEDIA_VIDEO,
+  contacts: PERMISSIONS.ANDROID.READ_CONTACTS,
+  calendar: PERMISSIONS.ANDROID.READ_CALENDAR,
+  calendarWriteOnly: PERMISSIONS.ANDROID.WRITE_CALENDAR,
+  locationWhenInUse: PERMISSIONS.ANDROID.ACCESS_FINE_LOCATION,
+  locationAlways: PERMISSIONS.ANDROID.ACCESS_BACKGROUND_LOCATION,
+  bluetooth: PERMISSIONS.ANDROID.BLUETOOTH_CONNECT,
+  motion: PERMISSIONS.ANDROID.ACTIVITY_RECOGNITION,
+  bodySensors: PERMISSIONS.ANDROID.BODY_SENSORS,
+  // iOS-only aliases (photoLibraryAddOnly, mediaLibrary, reminders,
+  // speechRecognition, appTrackingTransparency, faceId) → unavailable here.
+};
+
+const TABLE: NativeMap =
+  Platform.OS === 'ios' ? IOS : Platform.OS === 'android' ? ANDROID : {};
+
+function toStatus(result: RNPermissionStatus): PermissionStatus {
+  switch (result) {
+    case RESULTS.GRANTED:
+      return 'granted';
+    case RESULTS.LIMITED:
+      return 'limited';
+    case RESULTS.BLOCKED:
+      return 'blocked';
+    case RESULTS.DENIED:
+      return 'requestable';
+    case RESULTS.UNAVAILABLE:
+    default:
+      return 'unavailable';
+  }
+}
+
+/**
+ * Default adapter, backed by `react-native-permissions`. Notifications are a
+ * special case in the native library (a dedicated check/request API) and are
+ * routed accordingly.
+ */
+export const reactNativePermissionsAdapter: PermissionAdapter = {
+  isSupported(name) {
+    if (name === 'notifications') {
+      return Platform.OS === 'ios' || Platform.OS === 'android';
+    }
+    return TABLE[name] !== undefined;
+  },
+
+  async check(name) {
+    if (name === 'notifications') {
+      const { status } = await checkNotifications();
+      return toStatus(status);
+    }
+    const native = TABLE[name];
+    if (!native) return 'unavailable';
+    return toStatus(await check(native));
+  },
+
+  async request(name) {
+    if (name === 'notifications') {
+      const { status } = await requestNotifications([
+        'alert',
+        'sound',
+        'badge',
+      ]);
+      return toStatus(status);
+    }
+    const native = TABLE[name];
+    if (!native) return 'unavailable';
+    return toStatus(await request(native));
+  },
+
+  async openSettings() {
+    await openSettings();
+  },
+};

package/src/components/PermissionGate.tsx

@@ -0,0 +1,81 @@
+import { type ReactNode } from 'react';
+import { usePermission } from '../hooks/usePermission';
+import type {
+  PermissionController,
+  PermissionName,
+  PermissionStatus,
+  UsePermissionOptions,
+} from '../types';
+
+export interface RationaleControls {
+  confirm: () => void;
+  cancel: () => void;
+  status: PermissionStatus;
+}
+
+export interface BlockedControls {
+  openSettings: () => Promise<void>;
+  status: PermissionStatus;
+}
+
+export interface PermissionGateProps {
+  name: PermissionName;
+  /** Forwarded to the underlying `usePermission`. `requestOnMount` defaults to true here. */
+  options?: UsePermissionOptions;
+  /**
+   * Rendered once access is granted (or limited). Pass a function to take full
+   * control and render for every state yourself.
+   */
+  children: ReactNode | ((controller: PermissionController) => ReactNode);
+  /** Your pre-prompt UI, shown while `phase === 'rationale'`. */
+  rationale?: (controls: RationaleControls) => ReactNode;
+  /** Your "go to Settings" UI, shown while the permission is blocked. */
+  blocked?: (controls: BlockedControls) => ReactNode;
+  /** Shown while not yet granted and no rationale/blocked UI applies. */
+  fallback?: ReactNode;
+}
+
+/**
+ * Declarative convenience over {@link usePermission}. Gates its children behind
+ * a granted permission and lets you plug in your own rationale / blocked UI.
+ * Auto-runs the request flow on mount unless you override `requestOnMount`.
+ */
+export function PermissionGate({
+  name,
+  options,
+  children,
+  rationale,
+  blocked,
+  fallback = null,
+}: PermissionGateProps) {
+  const controller = usePermission(name, { requestOnMount: true, ...options });
+
+  // Render-prop mode: hand over full control regardless of status.
+  if (typeof children === 'function') {
+    return <>{children(controller)}</>;
+  }
+
+  const { status, phase, isBlocked } = controller;
+
+  if (status === 'granted' || status === 'limited') {
+    return <>{children}</>;
+  }
+
+  if (phase === 'rationale' && rationale) {
+    return (
+      <>
+        {rationale({
+          confirm: controller.confirmRationale,
+          cancel: controller.cancelRationale,
+          status,
+        })}
+      </>
+    );
+  }
+
+  if (isBlocked && blocked) {
+    return <>{blocked({ openSettings: controller.openSettings, status })}</>;
+  }
+
+  return <>{fallback}</>;
+}

package/src/context.tsx

@@ -0,0 +1,43 @@
+import { createContext, type ReactNode } from 'react';
+import { reactNativePermissionsAdapter } from './adapters/reactNativePermissions';
+import type { PermissionAdapter, UsePermissionOptions } from './types';
+
+/** Options that can be defaulted for every hook/component under a provider. */
+export type PermissionDefaults = Pick<
+  UsePermissionOptions,
+  'rationale' | 'revalidateOnFocus' | 'requestOnMount'
+>;
+
+export interface PermissionContextValue {
+  adapter: PermissionAdapter;
+  defaults: PermissionDefaults;
+}
+
+export const PermissionContext = createContext<PermissionContextValue>({
+  adapter: reactNativePermissionsAdapter,
+  defaults: {},
+});
+
+export interface PermissionProviderProps {
+  /** Override the backend for the whole tree. */
+  adapter?: PermissionAdapter;
+  /** Default options applied to every `usePermission` / `PermissionGate`. */
+  defaults?: PermissionDefaults;
+  children: ReactNode;
+}
+
+/**
+ * Optional. Sets a shared adapter and default options for the subtree so you
+ * don't repeat them at every call site. `usePermission` works without it.
+ */
+export function PermissionProvider({
+  adapter = reactNativePermissionsAdapter,
+  defaults = {},
+  children,
+}: PermissionProviderProps) {
+  return (
+    <PermissionContext.Provider value={{ adapter, defaults }}>
+      {children}
+    </PermissionContext.Provider>
+  );
+}

package/src/core/machine.ts

@@ -0,0 +1,98 @@
+import type { FlowPhase, PermissionStatus } from '../types';
+
+/**
+ * Pure, framework-free state machine that drives the permission UX flow.
+ *
+ * It has zero React and zero native dependencies: given the current state and an
+ * event, it returns the next state plus a list of side effects for the caller to
+ * interpret. This is what makes the whole flow unit-testable without a device.
+ */
+export interface MachineState {
+  status: PermissionStatus;
+  phase: FlowPhase;
+}
+
+export type MachineEvent =
+  | { type: 'REQUEST' }
+  | { type: 'CONFIRM_RATIONALE' }
+  | { type: 'CANCEL_RATIONALE' }
+  | { type: 'REQUEST_RESULT'; status: PermissionStatus }
+  | { type: 'CHECK_RESULT'; status: PermissionStatus }
+  | { type: 'REFRESH_RESULT'; status: PermissionStatus };
+
+export type MachineEffect =
+  /** Fire the adapter's native `request()`. */
+  | { type: 'runRequest' }
+  /** Resolve the pending `request()` promise with a final status. */
+  | { type: 'resolve'; status: PermissionStatus };
+
+export interface MachineContext {
+  rationale: boolean;
+}
+
+export interface Transition {
+  state: MachineState;
+  effects: MachineEffect[];
+}
+
+const noop = (state: MachineState): Transition => ({ state, effects: [] });
+
+export function reduce(
+  state: MachineState,
+  event: MachineEvent,
+  ctx: MachineContext
+): Transition {
+  switch (event.type) {
+    case 'REQUEST': {
+      // Only `requestable` can produce an OS prompt. Every other status is
+      // terminal for a request (granted/limited/blocked/unavailable): settle
+      // immediately so callers can react (e.g. show a "go to Settings" UI when
+      // blocked) without a dead-end.
+      if (state.status !== 'requestable') {
+        return {
+          state: { ...state, phase: 'settled' },
+          effects: [{ type: 'resolve', status: state.status }],
+        };
+      }
+      if (ctx.rationale) {
+        return { state: { ...state, phase: 'rationale' }, effects: [] };
+      }
+      return {
+        state: { ...state, phase: 'requesting' },
+        effects: [{ type: 'runRequest' }],
+      };
+    }
+
+    case 'CONFIRM_RATIONALE': {
+      if (state.phase !== 'rationale') return noop(state);
+      return {
+        state: { ...state, phase: 'requesting' },
+        effects: [{ type: 'runRequest' }],
+      };
+    }
+
+    case 'CANCEL_RATIONALE': {
+      if (state.phase !== 'rationale') return noop(state);
+      return {
+        state: { ...state, phase: 'idle' },
+        effects: [{ type: 'resolve', status: state.status }],
+      };
+    }
+
+    case 'REQUEST_RESULT': {
+      return {
+        state: { status: event.status, phase: 'settled' },
+        effects: [{ type: 'resolve', status: event.status }],
+      };
+    }
+
+    case 'CHECK_RESULT':
+    case 'REFRESH_RESULT': {
+      // Update the known status without disturbing an in-flight phase.
+      return noop({ ...state, status: event.status });
+    }
+
+    default:
+      return noop(state);
+  }
+}