react-native-permission-handler 0.1.0 → 0.2.1

package/dist/types-QXyq8VnD.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Permission status values owned by this library.
+ * Engines must map their native statuses to these values.
+ */
+type PermissionStatus = "granted" | "denied" | "blocked" | "limited" | "unavailable";
+/**
+ * The pluggable permission engine interface.
+ * Implement this to use a custom permissions backend.
+ */
+interface PermissionEngine {
+    check(permission: string): Promise<PermissionStatus>;
+    request(permission: string): Promise<PermissionStatus>;
+    openSettings(): Promise<void>;
+}
+/**
+ * States of the permission flow state machine.
+ */
+type PermissionFlowState = "idle" | "checking" | "prePrompt" | "requesting" | "granted" | "denied" | "blocked" | "blockedPrompt" | "openingSettings" | "recheckingAfterSettings" | "unavailable";
+/**
+ * Events that drive state transitions.
+ */
+type PermissionFlowEvent = {
+    type: "CHECK";
+} | {
+    type: "CHECK_RESULT";
+    status: PermissionStatus;
+} | {
+    type: "PRE_PROMPT_CONFIRM";
+} | {
+    type: "PRE_PROMPT_DISMISS";
+} | {
+    type: "REQUEST_RESULT";
+    status: PermissionStatus;
+} | {
+    type: "OPEN_SETTINGS";
+} | {
+    type: "SETTINGS_RETURN";
+} | {
+    type: "RECHECK_RESULT";
+    status: PermissionStatus;
+};
+/**
+ * Configuration for the pre-prompt modal.
+ */
+interface PrePromptConfig {
+    title: string;
+    message: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+}
+/**
+ * Configuration for the blocked-prompt modal.
+ */
+interface BlockedPromptConfig {
+    title: string;
+    message: string;
+    settingsLabel?: string;
+}
+/**
+ * Callbacks for analytics and side effects.
+ */
+interface PermissionCallbacks {
+    onGrant?: () => void;
+    onDeny?: () => void;
+    onBlock?: () => void;
+    onSettingsReturn?: (granted: boolean) => void;
+}
+/**
+ * Configuration for usePermissionHandler.
+ */
+interface PermissionHandlerConfig extends PermissionCallbacks {
+    permission: string;
+    engine?: PermissionEngine;
+    prePrompt: PrePromptConfig;
+    blockedPrompt: BlockedPromptConfig;
+    autoCheck?: boolean;
+    recheckOnForeground?: boolean;
+}
+/**
+ * Return type of usePermissionHandler.
+ */
+interface PermissionHandlerResult {
+    state: PermissionFlowState;
+    nativeStatus: PermissionStatus | null;
+    isGranted: boolean;
+    isDenied: boolean;
+    isBlocked: boolean;
+    isChecking: boolean;
+    isUnavailable: boolean;
+    request: () => void;
+    check: () => void;
+    dismiss: () => void;
+    openSettings: () => void;
+}
+/**
+ * Configuration for a single permission within useMultiplePermissions.
+ */
+interface MultiPermissionEntry extends PermissionCallbacks {
+    permission: string;
+    prePrompt: PrePromptConfig;
+    blockedPrompt: BlockedPromptConfig;
+}
+/**
+ * Configuration for useMultiplePermissions.
+ */
+interface MultiplePermissionsConfig {
+    permissions: MultiPermissionEntry[];
+    strategy: "sequential" | "parallel";
+    engine?: PermissionEngine;
+    autoCheck?: boolean;
+    onAllGranted?: () => void;
+}
+/**
+ * Return type of useMultiplePermissions.
+ */
+interface MultiplePermissionsResult {
+    statuses: Record<string, PermissionFlowState>;
+    allGranted: boolean;
+    request: () => void;
+}
+
+export type { BlockedPromptConfig as B, MultiplePermissionsConfig as M, PermissionEngine as P, PermissionFlowState as a, PermissionFlowEvent as b, PermissionHandlerConfig as c, PermissionHandlerResult as d, MultiplePermissionsResult as e, PermissionCallbacks as f, PrePromptConfig as g, MultiPermissionEntry as h, PermissionStatus as i };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-native-permission-handler",
-  "version": "0.1.0",
-  "description": "Smart permission UX flows for React Native — pre-prompts, blocked handling, settings redirect & foreground re-check. Built on react-native-permissions.",
+  "version": "0.2.1",
+  "description": "Smart permission UX flows for React Native — pre-prompts, blocked handling, settings redirect & foreground re-check. Pluggable engine: works with react-native-permissions, Expo, or your own.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -15,6 +15,26 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./rnp": {
+      "import": {
+        "types": "./dist/engines/rnp.d.mts",
+        "default": "./dist/engines/rnp.mjs"
+      },
+      "require": {
+        "types": "./dist/engines/rnp.d.ts",
+        "default": "./dist/engines/rnp.js"
+      }
+    },
+    "./expo": {
+      "import": {
+        "types": "./dist/engines/expo.d.mts",
+        "default": "./dist/engines/expo.mjs"
+      },
+      "require": {
+        "types": "./dist/engines/expo.d.ts",
+        "default": "./dist/engines/expo.js"
+      }
     }
   },
   "files": [
@@ -60,6 +80,11 @@
     "react-native": ">=0.76.0",
     "react-native-permissions": ">=4.0.0"
   },
+  "peerDependenciesMeta": {
+    "react-native-permissions": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",
     "@testing-library/react-native": "^12.0.0",

package/src/components/permission-gate.tsx

@@ -1,13 +1,18 @@
 import React from "react";
 import type { ReactNode } from "react";
-import type { Permission } from "react-native-permissions";
 import { usePermissionHandler } from "../hooks/use-permission-handler";
-import type { BlockedPromptConfig, PermissionCallbacks, PrePromptConfig } from "../types";
+import type {
+  BlockedPromptConfig,
+  PermissionCallbacks,
+  PermissionEngine,
+  PrePromptConfig,
+} from "../types";
 import { DefaultBlockedPrompt } from "./default-blocked-prompt";
 import { DefaultPrePrompt } from "./default-pre-prompt";
 
 export interface PermissionGateProps extends PermissionCallbacks {
-  permission: Permission | "notifications";
+  permission: string;
+  engine?: PermissionEngine;
   prePrompt: PrePromptConfig;
   blockedPrompt: BlockedPromptConfig;
   children: ReactNode;
@@ -25,6 +30,7 @@ export interface PermissionGateProps extends PermissionCallbacks {
 
 export function PermissionGate({
   permission,
+  engine,
   prePrompt,
   blockedPrompt,
   children,
@@ -38,6 +44,7 @@ export function PermissionGate({
 }: PermissionGateProps) {
   const handler = usePermissionHandler({
     permission,
+    engine,
     prePrompt,
     blockedPrompt,
     onGrant,

package/src/engines/expo.test.ts

@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ExpoPermissionModule } from "./expo";
+
+vi.mock("react-native", () => ({
+  Linking: {
+    openSettings: vi.fn().mockResolvedValue(undefined),
+  },
+}));
+
+import { Linking } from "react-native";
+import { createExpoEngine } from "./expo";
+
+function createMockModule(overrides?: Partial<ExpoPermissionModule>): ExpoPermissionModule {
+  return {
+    getPermissionsAsync: vi.fn().mockResolvedValue({ status: "granted", canAskAgain: true }),
+    requestPermissionsAsync: vi.fn().mockResolvedValue({ status: "granted", canAskAgain: true }),
+    ...overrides,
+  };
+}
+
+describe("createExpoEngine", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("status mapping", () => {
+    it("maps 'granted' to 'granted'", async () => {
+      const camera = createMockModule({
+        getPermissionsAsync: vi.fn().mockResolvedValue({ status: "granted", canAskAgain: true }),
+      });
+      const engine = createExpoEngine({ permissions: { camera } });
+
+      expect(await engine.check("camera")).toBe("granted");
+    });
+
+    it("maps 'undetermined' to 'denied'", async () => {
+      const camera = createMockModule({
+        getPermissionsAsync: vi
+          .fn()
+          .mockResolvedValue({ status: "undetermined", canAskAgain: true }),
+      });
+      const engine = createExpoEngine({ permissions: { camera } });
+
+      expect(await engine.check("camera")).toBe("denied");
+    });
+
+    it("maps 'denied' + canAskAgain:true to 'denied'", async () => {
+      const camera = createMockModule({
+        getPermissionsAsync: vi.fn().mockResolvedValue({ status: "denied", canAskAgain: true }),
+      });
+      const engine = createExpoEngine({ permissions: { camera } });
+
+      expect(await engine.check("camera")).toBe("denied");
+    });
+
+    it("maps 'denied' + canAskAgain:false to 'blocked'", async () => {
+      const camera = createMockModule({
+        getPermissionsAsync: vi.fn().mockResolvedValue({ status: "denied", canAskAgain: false }),
+      });
+      const engine = createExpoEngine({ permissions: { camera } });
+
+      expect(await engine.check("camera")).toBe("blocked");
+    });
+
+    it("maps unknown status to 'unavailable'", async () => {
+      const camera = createMockModule({
+        getPermissionsAsync: vi
+          .fn()
+          .mockResolvedValue({ status: "something_else", canAskAgain: true }),
+      });
+      const engine = createExpoEngine({ permissions: { camera } });
+
+      expect(await engine.check("camera")).toBe("unavailable");
+    });
+  });
+
+  describe("check", () => {
+    it("calls getPermissionsAsync on the correct module", async () => {
+      const camera = createMockModule();
+      const location = createMockModule();
+      const engine = createExpoEngine({ permissions: { camera, location } });
+
+      await engine.check("camera");
+
+      expect(camera.getPermissionsAsync).toHaveBeenCalled();
+      expect(location.getPermissionsAsync).not.toHaveBeenCalled();
+    });
+
+    it("returns 'unavailable' for unknown permissions", async () => {
+      const engine = createExpoEngine({ permissions: {} });
+
+      expect(await engine.check("unknown")).toBe("unavailable");
+    });
+  });
+
+  describe("request", () => {
+    it("calls requestPermissionsAsync on the correct module", async () => {
+      const camera = createMockModule();
+      const engine = createExpoEngine({ permissions: { camera } });
+
+      await engine.request("camera");
+
+      expect(camera.requestPermissionsAsync).toHaveBeenCalled();
+    });
+
+    it("returns 'unavailable' for unknown permissions", async () => {
+      const engine = createExpoEngine({ permissions: {} });
+
+      expect(await engine.request("unknown")).toBe("unavailable");
+    });
+  });
+
+  describe("openSettings", () => {
+    it("calls Linking.openSettings()", async () => {
+      const engine = createExpoEngine({ permissions: {} });
+
+      await engine.openSettings();
+
+      expect(Linking.openSettings).toHaveBeenCalled();
+    });
+  });
+});

package/src/engines/expo.ts

@@ -0,0 +1,45 @@
+import { Linking } from "react-native";
+import type { PermissionEngine, PermissionStatus } from "../types";
+
+export interface ExpoPermissionModule {
+  getPermissionsAsync: () => Promise<{ status: string; canAskAgain: boolean }>;
+  requestPermissionsAsync: () => Promise<{ status: string; canAskAgain: boolean }>;
+}
+
+export interface ExpoEngineConfig {
+  permissions: Record<string, ExpoPermissionModule>;
+}
+
+function mapExpoStatus(result: {
+  status: string;
+  canAskAgain: boolean;
+}): PermissionStatus {
+  if (result.status === "granted") return "granted";
+  if (result.status === "undetermined") return "denied";
+  if (result.status === "denied") {
+    return result.canAskAgain ? "denied" : "blocked";
+  }
+  return "unavailable";
+}
+
+export function createExpoEngine(config: ExpoEngineConfig): PermissionEngine {
+  return {
+    async check(permission: string): Promise<PermissionStatus> {
+      const mod = config.permissions[permission];
+      if (!mod) return "unavailable";
+      const result = await mod.getPermissionsAsync();
+      return mapExpoStatus(result);
+    },
+
+    async request(permission: string): Promise<PermissionStatus> {
+      const mod = config.permissions[permission];
+      if (!mod) return "unavailable";
+      const result = await mod.requestPermissionsAsync();
+      return mapExpoStatus(result);
+    },
+
+    async openSettings(): Promise<void> {
+      await Linking.openSettings();
+    },
+  };
+}

package/src/engines/resolve.test.ts

@@ -0,0 +1,85 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { PermissionEngine } from "../types";
+
+// Mock the RNP fallback
+const mockFallbackEngine: PermissionEngine = {
+  check: vi.fn().mockResolvedValue("granted"),
+  request: vi.fn().mockResolvedValue("granted"),
+  openSettings: vi.fn().mockResolvedValue(undefined),
+};
+
+vi.mock("./rnp-fallback", () => ({
+  getRNPFallbackEngine: vi.fn(() => mockFallbackEngine),
+}));
+
+import { getDefaultEngine, setDefaultEngine } from "./resolve";
+import { resolveEngine } from "./use-engine";
+
+describe("resolveEngine", () => {
+  afterEach(() => {
+    // Reset global default by setting it to a known state
+    // We can't truly reset since there's no clearDefaultEngine, but tests
+    // run in order so we test the cascade explicitly
+  });
+
+  it("uses config engine when provided", () => {
+    const configEngine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+
+    expect(resolveEngine(configEngine)).toBe(configEngine);
+  });
+
+  it("falls back to RNP fallback when no config or global engine", () => {
+    // getDefaultEngine() returns null by default (no setDefaultEngine called yet in fresh module)
+    // But since we can't guarantee module state across tests, we test the cascade
+    const result = resolveEngine(undefined);
+    // Should either be the global default or the fallback
+    expect(result).toBeDefined();
+    expect(result.check).toBeDefined();
+    expect(result.request).toBeDefined();
+    expect(result.openSettings).toBeDefined();
+  });
+});
+
+describe("setDefaultEngine / getDefaultEngine", () => {
+  it("stores and retrieves a default engine", () => {
+    const engine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+
+    setDefaultEngine(engine);
+    expect(getDefaultEngine()).toBe(engine);
+  });
+
+  it("resolveEngine uses global default over fallback", () => {
+    const globalEngine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+
+    setDefaultEngine(globalEngine);
+    expect(resolveEngine(undefined)).toBe(globalEngine);
+  });
+
+  it("config engine takes priority over global default", () => {
+    const globalEngine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+    const configEngine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+
+    setDefaultEngine(globalEngine);
+    expect(resolveEngine(configEngine)).toBe(configEngine);
+  });
+});

package/src/engines/resolve.ts

@@ -0,0 +1,11 @@
+import type { PermissionEngine } from "../types";
+
+let defaultEngine: PermissionEngine | null = null;
+
+export function setDefaultEngine(engine: PermissionEngine): void {
+  defaultEngine = engine;
+}
+
+export function getDefaultEngine(): PermissionEngine | null {
+  return defaultEngine;
+}

package/src/engines/rnp-fallback.ts

@@ -0,0 +1,23 @@
+import type { PermissionEngine } from "../types";
+
+let cachedFallback: PermissionEngine | null = null;
+
+export function getRNPFallbackEngine(): PermissionEngine {
+  if (cachedFallback) return cachedFallback;
+
+  try {
+    // Dynamic require to avoid hard dependency — only resolves if
+    // react-native-permissions is installed by the consumer.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require("./rnp") as { createRNPEngine: () => PermissionEngine };
+    const { createRNPEngine } = mod;
+    cachedFallback = createRNPEngine();
+    return cachedFallback;
+  } catch {
+    throw new Error(
+      "react-native-permission-handler: No permission engine configured. " +
+        "Either pass an `engine` in your hook config, call setDefaultEngine(), " +
+        "or install react-native-permissions as a peer dependency.",
+    );
+  }
+}

package/src/engines/rnp.test.ts

@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("react-native", () => ({
+  Platform: { select: (opts: Record<string, string>) => opts.ios ?? opts.default },
+}));
+
+vi.mock("react-native-permissions", () => ({
+  check: vi.fn(),
+  request: vi.fn(),
+  openSettings: vi.fn(),
+  checkNotifications: vi.fn(),
+  requestNotifications: vi.fn(),
+}));
+
+import {
+  check,
+  checkNotifications,
+  openSettings,
+  request,
+  requestNotifications,
+} from "react-native-permissions";
+import { Permissions, createRNPEngine } from "./rnp";
+
+describe("createRNPEngine", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("check", () => {
+    it("delegates to check() for regular permissions", async () => {
+      vi.mocked(check).mockResolvedValue("granted");
+      const engine = createRNPEngine();
+
+      const result = await engine.check("ios.permission.CAMERA");
+
+      expect(check).toHaveBeenCalledWith("ios.permission.CAMERA");
+      expect(result).toBe("granted");
+    });
+
+    it("delegates to checkNotifications() for 'notifications'", async () => {
+      vi.mocked(checkNotifications).mockResolvedValue({
+        status: "denied",
+        settings: {},
+      });
+      const engine = createRNPEngine();
+
+      const result = await engine.check("notifications");
+
+      expect(checkNotifications).toHaveBeenCalled();
+      expect(check).not.toHaveBeenCalled();
+      expect(result).toBe("denied");
+    });
+
+    it("returns all status values correctly", async () => {
+      const engine = createRNPEngine();
+
+      for (const status of ["granted", "denied", "blocked", "limited", "unavailable"] as const) {
+        vi.mocked(check).mockResolvedValue(status);
+        expect(await engine.check("some.permission")).toBe(status);
+      }
+    });
+  });
+
+  describe("request", () => {
+    it("delegates to request() for regular permissions", async () => {
+      vi.mocked(request).mockResolvedValue("granted");
+      const engine = createRNPEngine();
+
+      const result = await engine.request("ios.permission.CAMERA");
+
+      expect(request).toHaveBeenCalledWith("ios.permission.CAMERA");
+      expect(result).toBe("granted");
+    });
+
+    it("delegates to requestNotifications() for 'notifications'", async () => {
+      vi.mocked(requestNotifications).mockResolvedValue({
+        status: "granted",
+        settings: {},
+      });
+      const engine = createRNPEngine();
+
+      const result = await engine.request("notifications");
+
+      expect(requestNotifications).toHaveBeenCalledWith(["alert", "badge", "sound"]);
+      expect(request).not.toHaveBeenCalled();
+      expect(result).toBe("granted");
+    });
+  });
+
+  describe("openSettings", () => {
+    it("delegates to openSettings()", async () => {
+      vi.mocked(openSettings).mockResolvedValue(undefined as never);
+      const engine = createRNPEngine();
+
+      await engine.openSettings();
+
+      expect(openSettings).toHaveBeenCalled();
+    });
+  });
+});
+
+describe("Permissions constants", () => {
+  it("resolves to iOS strings (mocked platform)", () => {
+    expect(Permissions.CAMERA).toBe("ios.permission.CAMERA");
+    expect(Permissions.MICROPHONE).toBe("ios.permission.MICROPHONE");
+    expect(Permissions.LOCATION_WHEN_IN_USE).toBe("ios.permission.LOCATION_WHEN_IN_USE");
+    expect(Permissions.NOTIFICATIONS).toBe("notifications");
+  });
+
+  it("includes all expected cross-platform permissions", () => {
+    const keys = Object.keys(Permissions);
+    expect(keys).toContain("CAMERA");
+    expect(keys).toContain("MICROPHONE");
+    expect(keys).toContain("CONTACTS");
+    expect(keys).toContain("CALENDARS");
+    expect(keys).toContain("LOCATION_WHEN_IN_USE");
+    expect(keys).toContain("LOCATION_ALWAYS");
+    expect(keys).toContain("PHOTO_LIBRARY");
+    expect(keys).toContain("BLUETOOTH");
+    expect(keys).toContain("NOTIFICATIONS");
+  });
+});

package/src/engines/rnp.ts

@@ -0,0 +1,68 @@
+import { Platform } from "react-native";
+import {
+  type Permission,
+  check,
+  checkNotifications,
+  openSettings,
+  request,
+  requestNotifications,
+} from "react-native-permissions";
+import type { PermissionEngine, PermissionStatus } from "../types";
+
+function p(ios: string, android: string): string {
+  return Platform.select({ ios, android, default: ios }) ?? ios;
+}
+
+/**
+ * Cross-platform permission constants for use with the RNP engine.
+ * Each resolves to the correct platform-specific string at runtime.
+ */
+export const Permissions = {
+  CAMERA: p("ios.permission.CAMERA", "android.permission.CAMERA"),
+  MICROPHONE: p("ios.permission.MICROPHONE", "android.permission.RECORD_AUDIO"),
+  CONTACTS: p("ios.permission.CONTACTS", "android.permission.READ_CONTACTS"),
+  CALENDARS: p("ios.permission.CALENDARS", "android.permission.READ_CALENDAR"),
+  CALENDARS_WRITE_ONLY: p(
+    "ios.permission.CALENDARS_WRITE_ONLY",
+    "android.permission.WRITE_CALENDAR",
+  ),
+  LOCATION_WHEN_IN_USE: p(
+    "ios.permission.LOCATION_WHEN_IN_USE",
+    "android.permission.ACCESS_FINE_LOCATION",
+  ),
+  LOCATION_ALWAYS: p(
+    "ios.permission.LOCATION_ALWAYS",
+    "android.permission.ACCESS_BACKGROUND_LOCATION",
+  ),
+  PHOTO_LIBRARY: p("ios.permission.PHOTO_LIBRARY", "android.permission.READ_MEDIA_IMAGES"),
+  PHOTO_LIBRARY_ADD_ONLY: p(
+    "ios.permission.PHOTO_LIBRARY_ADD_ONLY",
+    "android.permission.WRITE_EXTERNAL_STORAGE",
+  ),
+  BLUETOOTH: p("ios.permission.BLUETOOTH", "android.permission.BLUETOOTH_CONNECT"),
+  NOTIFICATIONS: "notifications",
+} as const;
+
+export function createRNPEngine(): PermissionEngine {
+  return {
+    async check(permission: string): Promise<PermissionStatus> {
+      if (permission === "notifications") {
+        const result = await checkNotifications();
+        return result.status as PermissionStatus;
+      }
+      return (await check(permission as Permission)) as PermissionStatus;
+    },
+
+    async request(permission: string): Promise<PermissionStatus> {
+      if (permission === "notifications") {
+        const result = await requestNotifications(["alert", "badge", "sound"]);
+        return result.status as PermissionStatus;
+      }
+      return (await request(permission as Permission)) as PermissionStatus;
+    },
+
+    async openSettings(): Promise<void> {
+      await openSettings();
+    },
+  };
+}