react-native-permission-handler 0.1.0 → 0.2.0

package/src/hooks/use-permission-handler.test.ts

@@ -1,9 +1,9 @@
 import { createElement } from "react";
 import { type ReactTestRenderer, act, create } from "react-test-renderer";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { PermissionHandlerConfig, PermissionHandlerResult } from "../types";
+import type { PermissionEngine, PermissionHandlerConfig, PermissionHandlerResult } from "../types";
 
-// Mocks must be before imports that use them
+// Mock react-native AppState
 vi.mock("react-native", () => ({
   AppState: {
     currentState: "active",
@@ -11,17 +11,24 @@ vi.mock("react-native", () => ({
   },
 }));
 
-vi.mock("react-native-permissions", () => ({
-  check: vi.fn(),
-  request: vi.fn(),
-  openSettings: vi.fn(),
-  checkNotifications: vi.fn(),
-  requestNotifications: vi.fn(),
+// Mock the RNP fallback so hooks don't try to require react-native-permissions
+vi.mock("../engines/rnp-fallback", () => ({
+  getRNPFallbackEngine: vi.fn(() => {
+    throw new Error("No engine configured");
+  }),
 }));
 
-import { check, checkNotifications, request, requestNotifications } from "react-native-permissions";
 import { usePermissionHandler } from "./use-permission-handler";
 
+function createMockEngine(overrides?: Partial<PermissionEngine>): PermissionEngine {
+  return {
+    check: vi.fn().mockResolvedValue("granted"),
+    request: vi.fn().mockResolvedValue("granted"),
+    openSettings: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
 // Minimal renderHook using react-test-renderer
 function renderHook(hookFn: () => PermissionHandlerResult) {
   const results: { current: PermissionHandlerResult } = {} as {
@@ -41,32 +48,36 @@ function renderHook(hookFn: () => PermissionHandlerResult) {
   };
 }
 
-const baseConfig: PermissionHandlerConfig = {
-  permission: "ios.permission.CAMERA" as PermissionHandlerConfig["permission"],
-  prePrompt: { title: "Camera", message: "We need camera access" },
-  blockedPrompt: { title: "Blocked", message: "Camera is blocked" },
-};
-
 describe("usePermissionHandler", () => {
+  let engine: PermissionEngine;
+
+  const baseConfig = (overrides?: Partial<PermissionHandlerConfig>): PermissionHandlerConfig => ({
+    permission: "camera",
+    engine,
+    prePrompt: { title: "Camera", message: "We need camera access" },
+    blockedPrompt: { title: "Blocked", message: "Camera is blocked" },
+    ...overrides,
+  });
+
   beforeEach(() => {
     vi.clearAllMocks();
+    engine = createMockEngine();
   });
 
   it("auto-checks on mount and transitions to granted", async () => {
-    vi.mocked(check).mockResolvedValue("granted");
-    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+    vi.mocked(engine.check).mockResolvedValue("granted");
+    const { result } = renderHook(() => usePermissionHandler(baseConfig()));
 
-    // After mount, should be checking
     await act(async () => {});
 
     expect(result.current.isGranted).toBe(true);
     expect(result.current.state).toBe("granted");
-    expect(check).toHaveBeenCalledWith(baseConfig.permission);
+    expect(engine.check).toHaveBeenCalledWith("camera");
   });
 
   it("transitions to prePrompt when permission is denied", async () => {
-    vi.mocked(check).mockResolvedValue("denied");
-    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+    vi.mocked(engine.check).mockResolvedValue("denied");
+    const { result } = renderHook(() => usePermissionHandler(baseConfig()));
 
     await act(async () => {});
 
@@ -74,8 +85,8 @@ describe("usePermissionHandler", () => {
   });
 
   it("transitions to blockedPrompt when permission is blocked", async () => {
-    vi.mocked(check).mockResolvedValue("blocked");
-    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+    vi.mocked(engine.check).mockResolvedValue("blocked");
+    const { result } = renderHook(() => usePermissionHandler(baseConfig()));
 
     await act(async () => {});
 
@@ -84,8 +95,8 @@ describe("usePermissionHandler", () => {
   });
 
   it("transitions to unavailable", async () => {
-    vi.mocked(check).mockResolvedValue("unavailable");
-    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+    vi.mocked(engine.check).mockResolvedValue("unavailable");
+    const { result } = renderHook(() => usePermissionHandler(baseConfig()));
 
     await act(async () => {});
 
@@ -94,20 +105,20 @@ describe("usePermissionHandler", () => {
   });
 
   it("skips auto-check when autoCheck is false", async () => {
-    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, autoCheck: false }));
+    const { result } = renderHook(() => usePermissionHandler(baseConfig({ autoCheck: false })));
 
     await act(async () => {});
 
     expect(result.current.state).toBe("idle");
-    expect(check).not.toHaveBeenCalled();
+    expect(engine.check).not.toHaveBeenCalled();
   });
 
   it("requests permission and fires onGrant", async () => {
-    vi.mocked(check).mockResolvedValue("denied");
-    vi.mocked(request).mockResolvedValue("granted");
+    vi.mocked(engine.check).mockResolvedValue("denied");
+    vi.mocked(engine.request).mockResolvedValue("granted");
     const onGrant = vi.fn();
 
-    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, onGrant }));
+    const { result } = renderHook(() => usePermissionHandler(baseConfig({ onGrant })));
 
     await act(async () => {});
     expect(result.current.state).toBe("prePrompt");
@@ -121,11 +132,11 @@ describe("usePermissionHandler", () => {
   });
 
   it("fires onDeny when request is denied", async () => {
-    vi.mocked(check).mockResolvedValue("denied");
-    vi.mocked(request).mockResolvedValue("denied");
+    vi.mocked(engine.check).mockResolvedValue("denied");
+    vi.mocked(engine.request).mockResolvedValue("denied");
     const onDeny = vi.fn();
 
-    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, onDeny }));
+    const { result } = renderHook(() => usePermissionHandler(baseConfig({ onDeny })));
 
     await act(async () => {});
     await act(async () => {
@@ -137,11 +148,11 @@ describe("usePermissionHandler", () => {
   });
 
   it("fires onBlock when request results in blocked", async () => {
-    vi.mocked(check).mockResolvedValue("denied");
-    vi.mocked(request).mockResolvedValue("blocked");
+    vi.mocked(engine.check).mockResolvedValue("denied");
+    vi.mocked(engine.request).mockResolvedValue("blocked");
     const onBlock = vi.fn();
 
-    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, onBlock }));
+    const { result } = renderHook(() => usePermissionHandler(baseConfig({ onBlock })));
 
     await act(async () => {});
     await act(async () => {
@@ -152,33 +163,32 @@ describe("usePermissionHandler", () => {
     expect(onBlock).toHaveBeenCalled();
   });
 
-  it("uses notification API when permission is 'notifications'", async () => {
-    vi.mocked(checkNotifications).mockResolvedValue({ status: "denied", settings: {} });
-    vi.mocked(requestNotifications).mockResolvedValue({ status: "granted", settings: {} });
+  it("passes permission string to engine (notification routing is engine's job)", async () => {
+    vi.mocked(engine.check).mockResolvedValue("denied");
+    vi.mocked(engine.request).mockResolvedValue("granted");
 
     const { result } = renderHook(() =>
-      usePermissionHandler({ ...baseConfig, permission: "notifications" }),
+      usePermissionHandler(baseConfig({ permission: "notifications" })),
     );
 
     await act(async () => {});
-    expect(checkNotifications).toHaveBeenCalled();
-    expect(check).not.toHaveBeenCalled();
+    expect(engine.check).toHaveBeenCalledWith("notifications");
 
     await act(async () => {
       result.current.request();
     });
 
-    expect(requestNotifications).toHaveBeenCalledWith(["alert", "badge", "sound"]);
+    expect(engine.request).toHaveBeenCalledWith("notifications");
     expect(result.current.isGranted).toBe(true);
   });
 
   it("guards against double-tap race condition", async () => {
-    vi.mocked(check).mockResolvedValue("denied");
-    vi.mocked(request).mockImplementation(
+    vi.mocked(engine.check).mockResolvedValue("denied");
+    vi.mocked(engine.request).mockImplementation(
       () => new Promise((resolve) => setTimeout(() => resolve("granted"), 50)),
     );
 
-    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+    const { result } = renderHook(() => usePermissionHandler(baseConfig()));
 
     await act(async () => {});
     expect(result.current.state).toBe("prePrompt");
@@ -188,14 +198,14 @@ describe("usePermissionHandler", () => {
       result.current.request(); // double-tap
     });
 
-    expect(request).toHaveBeenCalledTimes(1);
+    expect(engine.request).toHaveBeenCalledTimes(1);
   });
 
   it("dismiss fires onDeny and transitions to denied", async () => {
-    vi.mocked(check).mockResolvedValue("denied");
+    vi.mocked(engine.check).mockResolvedValue("denied");
     const onDeny = vi.fn();
 
-    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, onDeny }));
+    const { result } = renderHook(() => usePermissionHandler(baseConfig({ onDeny })));
 
     await act(async () => {});
     expect(result.current.state).toBe("prePrompt");

package/src/hooks/use-permission-handler.ts

@@ -1,27 +1,16 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { AppState } from "react-native";
-import {
-  type PermissionStatus,
-  check,
-  checkNotifications,
-  openSettings,
-  request,
-  requestNotifications,
-} from "react-native-permissions";
 import { transition } from "../core/state-machine";
+import { resolveEngine } from "../engines/use-engine";
 import type {
   PermissionFlowState,
   PermissionHandlerConfig,
   PermissionHandlerResult,
+  PermissionStatus,
 } from "../types";
 
-function isNotifications(
-  permission: PermissionHandlerConfig["permission"],
-): permission is "notifications" {
-  return permission === "notifications";
-}
-
 export function usePermissionHandler(config: PermissionHandlerConfig): PermissionHandlerResult {
+  const engine = resolveEngine(config.engine);
   const [flowState, setFlowState] = useState<PermissionFlowState>("idle");
   const [nativeStatus, setNativeStatus] = useState<PermissionStatus | null>(null);
   const isRequesting = useRef(false);
@@ -33,13 +22,7 @@ export function usePermissionHandler(config: PermissionHandlerConfig): Permissio
   const checkPermission = useCallback(async () => {
     setFlowState((s) => transition(s, { type: "CHECK" }));
     try {
-      let status: PermissionStatus;
-      if (isNotifications(permission)) {
-        const result = await checkNotifications();
-        status = result.status;
-      } else {
-        status = await check(permission);
-      }
+      const status = await engine.check(permission);
       setNativeStatus(status);
       setFlowState((s) => {
         const next = transition(s, { type: "CHECK_RESULT", status });
@@ -49,7 +32,7 @@ export function usePermissionHandler(config: PermissionHandlerConfig): Permissio
     } catch {
       setFlowState("idle");
     }
-  }, [permission, onGrant]);
+  }, [engine, permission, onGrant]);
 
   const requestPermission = useCallback(async () => {
     if (isRequesting.current) return;
@@ -57,13 +40,7 @@ export function usePermissionHandler(config: PermissionHandlerConfig): Permissio
 
     setFlowState((s) => transition(s, { type: "PRE_PROMPT_CONFIRM" }));
     try {
-      let status: PermissionStatus;
-      if (isNotifications(permission)) {
-        const result = await requestNotifications(["alert", "badge", "sound"]);
-        status = result.status;
-      } else {
-        status = await request(permission);
-      }
+      const status = await engine.request(permission);
       setNativeStatus(status);
       setFlowState((s) => {
         const next = transition(s, { type: "REQUEST_RESULT", status });
@@ -77,7 +54,7 @@ export function usePermissionHandler(config: PermissionHandlerConfig): Permissio
     } finally {
       isRequesting.current = false;
     }
-  }, [permission, onGrant, onDeny, onBlock]);
+  }, [engine, permission, onGrant, onDeny, onBlock]);
 
   const dismiss = useCallback(() => {
     setFlowState((s) => transition(s, { type: "PRE_PROMPT_DISMISS" }));
@@ -88,23 +65,17 @@ export function usePermissionHandler(config: PermissionHandlerConfig): Permissio
     setFlowState((s) => transition(s, { type: "OPEN_SETTINGS" }));
     waitingForSettings.current = true;
     try {
-      await openSettings();
+      await engine.openSettings();
     } catch {
       waitingForSettings.current = false;
       setFlowState("blockedPrompt");
     }
-  }, []);
+  }, [engine]);
 
   const recheckAfterSettings = useCallback(async () => {
     setFlowState((s) => transition(s, { type: "SETTINGS_RETURN" }));
     try {
-      let status: PermissionStatus;
-      if (isNotifications(permission)) {
-        const result = await checkNotifications();
-        status = result.status;
-      } else {
-        status = await check(permission);
-      }
+      const status = await engine.check(permission);
       setNativeStatus(status);
       setFlowState((s) => {
         const next = transition(s, { type: "RECHECK_RESULT", status });
@@ -115,7 +86,7 @@ export function usePermissionHandler(config: PermissionHandlerConfig): Permissio
     } catch {
       setFlowState("blockedPrompt");
     }
-  }, [permission, onGrant, onSettingsReturn]);
+  }, [engine, permission, onGrant, onSettingsReturn]);
 
   // Auto-check on mount
   // biome-ignore lint/correctness/useExhaustiveDependencies: intentional mount-only effect

package/src/index.ts

@@ -4,13 +4,16 @@ export type {
   MultiplePermissionsConfig,
   MultiplePermissionsResult,
   PermissionCallbacks,
+  PermissionEngine,
   PermissionFlowEvent,
   PermissionFlowState,
   PermissionHandlerConfig,
   PermissionHandlerResult,
+  PermissionStatus,
   PrePromptConfig,
 } from "./types";
 
+export { setDefaultEngine } from "./engines/resolve";
 export { transition } from "./core/state-machine";
 export { usePermissionHandler } from "./hooks/use-permission-handler";
 export { useMultiplePermissions } from "./hooks/use-multiple-permissions";

package/src/types.ts

@@ -1,4 +1,18 @@
-import type { Permission, PermissionStatus } from "react-native-permissions";
+/**
+ * Permission status values owned by this library.
+ * Engines must map their native statuses to these values.
+ */
+export type PermissionStatus = "granted" | "denied" | "blocked" | "limited" | "unavailable";
+
+/**
+ * The pluggable permission engine interface.
+ * Implement this to use a custom permissions backend.
+ */
+export interface PermissionEngine {
+  check(permission: string): Promise<PermissionStatus>;
+  request(permission: string): Promise<PermissionStatus>;
+  openSettings(): Promise<void>;
+}
 
 /**
  * States of the permission flow state machine.
@@ -62,7 +76,8 @@ export interface PermissionCallbacks {
  * Configuration for usePermissionHandler.
  */
 export interface PermissionHandlerConfig extends PermissionCallbacks {
-  permission: Permission | "notifications";
+  permission: string;
+  engine?: PermissionEngine;
   prePrompt: PrePromptConfig;
   blockedPrompt: BlockedPromptConfig;
   autoCheck?: boolean;
@@ -90,7 +105,7 @@ export interface PermissionHandlerResult {
  * Configuration for a single permission within useMultiplePermissions.
  */
 export interface MultiPermissionEntry extends PermissionCallbacks {
-  permission: Permission | "notifications";
+  permission: string;
   prePrompt: PrePromptConfig;
   blockedPrompt: BlockedPromptConfig;
 }
@@ -101,6 +116,8 @@ export interface MultiPermissionEntry extends PermissionCallbacks {
 export interface MultiplePermissionsConfig {
   permissions: MultiPermissionEntry[];
   strategy: "sequential" | "parallel";
+  engine?: PermissionEngine;
+  autoCheck?: boolean;
   onAllGranted?: () => void;
 }