@ankhorage/permissions 0.2.2 → 0.2.4

package/src/expo/client.ts

@@ -8,25 +8,41 @@ import { microphoneAdapter } from './adapters/microphone';
 import { notificationsAdapter } from './adapters/notifications';
 import { EXPO_PERMISSION_SUPPORT } from './manifest';
 
+const OPEN_SETTINGS_ERROR_MESSAGE = 'Unable to open application settings.';
+
 export interface ExpoPermissionAdapter {
   getStatus(permission: Permission): Promise<PermissionState>;
   request(permission: Permission): Promise<PermissionState>;
 }
 
-const adapters: Partial<Record<Permission, ExpoPermissionAdapter>> = {
-  [Permission.Camera]: cameraAdapter,
-  [Permission.MediaLibrary]: mediaLibraryAdapter,
-  [Permission.MediaLibraryWrite]: mediaLibraryAdapter,
-  [Permission.Microphone]: microphoneAdapter,
-  [Permission.LocationForeground]: locationAdapter,
-  [Permission.LocationBackground]: locationAdapter,
-  [Permission.Notifications]: notificationsAdapter,
-};
+const adapters = new Map<Permission, ExpoPermissionAdapter>([
+  [Permission.Camera, cameraAdapter],
+  [Permission.MediaLibrary, mediaLibraryAdapter],
+  [Permission.MediaLibraryWrite, mediaLibraryAdapter],
+  [Permission.Microphone, microphoneAdapter],
+  [Permission.LocationForeground, locationAdapter],
+  [Permission.LocationBackground, locationAdapter],
+  [Permission.Notifications, notificationsAdapter],
+]);
 
+/***
+ * Creates a permission client backed by Expo SDK modules.
+ *
+ * Denials that Expo cannot request again are normalized to `blocked`. Limited
+ * media-library access and provisional or ephemeral iOS notification access
+ * are normalized to usable `limited` states, where `granted` remains true.
+ * The client requires `expo-linking` for settings recovery and rejects with a
+ * stable error when the operating-system settings page cannot be opened.
+ *
+ * Expo modules are loaded only when a client operation uses them. The package
+ * root and Expo manifest metadata remain free of native module imports.
+ *
+ * @readme
+ */
 export function createPermissionClient(): PermissionClient {
   return {
     async getStatus(permission: Permission): Promise<PermissionState> {
-      const metadata = EXPO_PERMISSION_SUPPORT[permission];
+      const metadata = getPermissionSupport(permission);
       if (metadata.support === 'unsupported' || metadata.support === 'notImplemented') {
         return createUnavailableSupportState(permission);
       }
@@ -35,7 +51,7 @@ export function createPermissionClient(): PermissionClient {
         return createNotRequiredState(permission);
       }
 
-      const adapter = adapters[permission];
+      const adapter = adapters.get(permission);
       if (!adapter) {
         throw new Error(`No adapter registered for permission: ${permission}`);
       }
@@ -44,7 +60,7 @@ export function createPermissionClient(): PermissionClient {
     },
 
     async request(permission: Permission): Promise<PermissionState> {
-      const metadata = EXPO_PERMISSION_SUPPORT[permission];
+      const metadata = getPermissionSupport(permission);
       if (metadata.support === 'unsupported' || metadata.support === 'notImplemented') {
         return createUnavailableSupportState(permission);
       }
@@ -53,16 +69,32 @@ export function createPermissionClient(): PermissionClient {
         return createNotRequiredState(permission);
       }
 
-      const adapter = adapters[permission];
+      const adapter = adapters.get(permission);
       if (!adapter) {
         throw new Error(`No adapter registered for permission: ${permission}`);
       }
 
       return adapter.request(permission);
     },
+
+    async openSettings(): Promise<void> {
+      try {
+        const linking = await import('expo-linking');
+
+        await linking.openSettings();
+      } catch (error) {
+        throw new Error(OPEN_SETTINGS_ERROR_MESSAGE, {
+          cause: error,
+        });
+      }
+    },
   };
 }
 
+function getPermissionSupport(permission: Permission) {
+  return Reflect.get(EXPO_PERMISSION_SUPPORT, permission);
+}
+
 function createUnavailableSupportState(permission: Permission): PermissionState {
   return createPermissionState({
     permission,

package/src/expo/manifest.test.ts

@@ -1,65 +1,67 @@
 import { readFileSync } from 'node:fs';
 
-import { describe, expect, test } from 'bun:test';
+import { expect, test } from 'bun:test';
 
 import { Permission, PERMISSIONS } from '../registry/permissions';
-import { EXPO_PERMISSION_SUPPORT } from './manifest';
+import { EXPO_PERMISSION_CLIENT_REQUIRED_PACKAGES, EXPO_PERMISSION_SUPPORT } from './manifest';
 
-describe('EXPO_PERMISSION_SUPPORT', () => {
-  test('defines metadata for every known permission', () => {
-    expect(Object.keys(EXPO_PERMISSION_SUPPORT).sort()).toEqual([...PERMISSIONS].sort());
-  });
+test('defines metadata for every known permission', () => {
+  expect(Object.keys(EXPO_PERMISSION_SUPPORT).sort()).toEqual([...PERMISSIONS].sort());
+});
 
-  test('stays metadata-only and does not import Expo runtime modules', () => {
-    const source = readFileSync(new URL('./manifest.ts', import.meta.url), 'utf8');
+test('stays metadata-only and does not import Expo runtime modules', () => {
+  const source = readFileSync(new URL('./manifest.ts', import.meta.url), 'utf8');
 
-    expect(source).not.toContain("from 'expo-");
-    expect(source).not.toContain('await import(');
-  });
+  expect(source).not.toContain("from 'expo-");
+  expect(source).not.toContain('await import(');
+});
 
-  test('includes package and config hints for camera, microphone, and location permissions', () => {
-    expect(EXPO_PERMISSION_SUPPORT[Permission.Camera]).toEqual({
-      support: 'supported',
-      requiredPackages: ['expo-camera'],
-      configHints: ['cameraPermission'],
-    });
+test('projects client-level settings recovery dependencies', () => {
+  expect(EXPO_PERMISSION_CLIENT_REQUIRED_PACKAGES).toEqual(['expo-linking']);
+});
 
-    expect(EXPO_PERMISSION_SUPPORT[Permission.Microphone]).toEqual({
-      support: 'supported',
-      requiredPackages: ['expo-audio'],
-      configHints: ['microphonePermission', 'recordAudioAndroid'],
-    });
+test('includes package and config hints for camera, microphone, and location permissions', () => {
+  expect(EXPO_PERMISSION_SUPPORT[Permission.Camera]).toEqual({
+    support: 'supported',
+    requiredPackages: ['expo-camera'],
+    configHints: ['cameraPermission'],
+  });
 
-    expect(EXPO_PERMISSION_SUPPORT[Permission.LocationForeground]).toEqual({
-      support: 'supported',
-      requiredPackages: ['expo-location'],
-      configHints: ['locationWhenInUsePermission'],
-    });
+  expect(EXPO_PERMISSION_SUPPORT[Permission.Microphone]).toEqual({
+    support: 'supported',
+    requiredPackages: ['expo-audio'],
+    configHints: ['microphonePermission', 'recordAudioAndroid'],
+  });
 
-    expect(EXPO_PERMISSION_SUPPORT[Permission.LocationBackground]).toEqual({
-      support: 'supported',
-      requiredPackages: ['expo-location'],
-      configHints: ['locationAlwaysAndWhenInUsePermission'],
-    });
+  expect(EXPO_PERMISSION_SUPPORT[Permission.LocationForeground]).toEqual({
+    support: 'supported',
+    requiredPackages: ['expo-location'],
+    configHints: ['locationWhenInUsePermission'],
   });
 
-  test('treats clipboard as a not-required permission without runtime package requirements', () => {
-    expect(EXPO_PERMISSION_SUPPORT[Permission.Clipboard]).toEqual({
-      support: 'notRequired',
-      requiredPackages: [],
-      configHints: [],
-    });
+  expect(EXPO_PERMISSION_SUPPORT[Permission.LocationBackground]).toEqual({
+    support: 'supported',
+    requiredPackages: ['expo-location'],
+    configHints: ['locationAlwaysAndWhenInUsePermission'],
   });
+});
 
-  test('keeps MediaLibraryWrite aligned with MediaLibrary metadata', () => {
-    expect(EXPO_PERMISSION_SUPPORT[Permission.MediaLibraryWrite]).toEqual({
-      support: 'supported',
-      requiredPackages: ['expo-media-library'],
-      configHints: ['mediaLibraryPermission'],
-    });
+test('treats clipboard as a not-required permission without runtime package requirements', () => {
+  expect(EXPO_PERMISSION_SUPPORT[Permission.Clipboard]).toEqual({
+    support: 'notRequired',
+    requiredPackages: [],
+    configHints: [],
+  });
+});
 
-    expect(EXPO_PERMISSION_SUPPORT[Permission.MediaLibraryWrite]).toEqual(
-      EXPO_PERMISSION_SUPPORT[Permission.MediaLibrary],
-    );
+test('keeps MediaLibraryWrite aligned with MediaLibrary metadata', () => {
+  expect(EXPO_PERMISSION_SUPPORT[Permission.MediaLibraryWrite]).toEqual({
+    support: 'supported',
+    requiredPackages: ['expo-media-library'],
+    configHints: ['mediaLibraryPermission'],
   });
+
+  expect(EXPO_PERMISSION_SUPPORT[Permission.MediaLibraryWrite]).toEqual(
+    EXPO_PERMISSION_SUPPORT[Permission.MediaLibrary],
+  );
 });

package/src/expo/manifest.ts

@@ -1,11 +1,7 @@
 import { Permission } from '../registry/permissions';
 
 export type PermissionSupport =
-  | 'supported'
-  | 'notRequired'
-  | 'limited'
-  | 'notImplemented'
-  | 'unsupported';
+  'supported' | 'notRequired' | 'limited' | 'notImplemented' | 'unsupported';
 
 export interface ExpoPermissionMetadata {
   readonly support: PermissionSupport;
@@ -13,6 +9,12 @@ export interface ExpoPermissionMetadata {
   readonly configHints: readonly string[];
 }
 
+/***
+ * Expo packages required by the permission client independently of a specific
+ * permission capability.
+ */
+export const EXPO_PERMISSION_CLIENT_REQUIRED_PACKAGES = ['expo-linking'] as const;
+
 export const EXPO_PERMISSION_SUPPORT: Readonly<Record<Permission, ExpoPermissionMetadata>> = {
   [Permission.Camera]: {
     support: 'supported',

package/src/expo/modules.d.ts

@@ -3,6 +3,20 @@ interface ExpoPermissionResult {
   canAskAgain?: boolean;
 }
 
+interface ExpoMediaLibraryPermissionResult extends ExpoPermissionResult {
+  accessPrivileges?: 'all' | 'limited' | 'none';
+}
+
+interface ExpoNotificationPermissionResult extends ExpoPermissionResult {
+  ios?: {
+    status?: number;
+  };
+}
+
+declare module 'expo-linking' {
+  export function openSettings(): Promise<void>;
+}
+
 declare module 'expo-camera' {
   export function getCameraPermissionsAsync(): Promise<ExpoPermissionResult>;
   export function requestCameraPermissionsAsync(): Promise<ExpoPermissionResult>;
@@ -27,11 +41,11 @@ declare module 'expo-media-library' {
   export function getPermissionsAsync(
     writeOnly?: boolean,
     granularPermissions?: readonly string[],
-  ): Promise<ExpoPermissionResult>;
+  ): Promise<ExpoMediaLibraryPermissionResult>;
   export function requestPermissionsAsync(
     writeOnly?: boolean,
     granularPermissions?: readonly string[],
-  ): Promise<ExpoPermissionResult>;
+  ): Promise<ExpoMediaLibraryPermissionResult>;
 }
 
 declare module 'expo-audio' {
@@ -48,6 +62,6 @@ declare module 'expo-audio' {
 }
 
 declare module 'expo-notifications' {
-  export function getPermissionsAsync(): Promise<ExpoPermissionResult>;
-  export function requestPermissionsAsync(): Promise<ExpoPermissionResult>;
+  export function getPermissionsAsync(): Promise<ExpoNotificationPermissionResult>;
+  export function requestPermissionsAsync(): Promise<ExpoNotificationPermissionResult>;
 }

package/src/expo/permissionResponse.ts

@@ -3,6 +3,7 @@ import {
   createPermissionState,
   isPermissionStatus,
   type PermissionState,
+  type PermissionStatus,
 } from '../state/permissionState';
 
 export interface ExpoPermissionResponse {
@@ -18,11 +19,7 @@ export function createExpoPermissionState(
 ): PermissionState {
   const status = isPermissionStatus(response.status) ? response.status : 'unknown';
 
-  return createPermissionState({
-    permission,
-    status,
-    canAskAgain: response.canAskAgain,
-  });
+  return createNormalizedExpoPermissionState(permission, response, status);
 }
 
 export function createExpoUnavailableState(
@@ -42,7 +39,7 @@ export function findExpoPermissionMethod(
   containerNames: readonly string[] = [],
 ): ExpoPermissionMethod | undefined {
   if (hasExpoPermissionMethod(source, methodName)) {
-    return source[methodName];
+    return Reflect.get(source, methodName);
   }
 
   if (!isRecord(source)) {
@@ -50,10 +47,10 @@ export function findExpoPermissionMethod(
   }
 
   for (const containerName of containerNames) {
-    const container = source[containerName];
+    const container = Reflect.get(source, containerName);
 
     if (hasExpoPermissionMethod(container, methodName)) {
-      return container[methodName];
+      return Reflect.get(container, methodName);
     }
   }
 
@@ -72,11 +69,31 @@ function getExpoPermissionErrorMessage(error: unknown): string {
   return 'Expo permission operation failed.';
 }
 
+function createNormalizedExpoPermissionState(
+  permission: Permission,
+  response: ExpoPermissionResponse,
+  status: PermissionStatus,
+  reason?: string,
+): PermissionState {
+  const normalizedStatus =
+    status === 'denied' && response.canAskAgain === false ? 'blocked' : status;
+
+  return createPermissionState({
+    permission,
+    status: normalizedStatus,
+    canAskAgain: response.canAskAgain,
+    reason:
+      normalizedStatus === 'blocked'
+        ? 'Permission is blocked. Open system settings to change it.'
+        : reason,
+  });
+}
+
 function hasExpoPermissionMethod(
   value: unknown,
   methodName: string,
 ): value is Record<string, ExpoPermissionMethod> {
-  return isRecord(value) && typeof value[methodName] === 'function';
+  return isRecord(value) && typeof Reflect.get(value, methodName) === 'function';
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {

package/src/manager/createPermissionManager.test.ts

@@ -1,67 +1,65 @@
-import { describe, expect, test } from 'bun:test';
+import { expect, test } from 'bun:test';
 
 import { Permission } from '../registry/permissions';
 import { createFakePermissionClient } from '../testing/index';
 import { createPermissionManager } from './createPermissionManager';
 
-describe('createPermissionManager', () => {
-  test('normalizes getStatus results', async () => {
-    const manager = createPermissionManager(
-      createFakePermissionClient({
-        initialStates: [
-          {
-            permission: Permission.Camera,
-            status: 'granted',
-          },
-        ],
-      }),
-    );
+test('normalizes getStatus results', async () => {
+  const manager = createPermissionManager(
+    createFakePermissionClient({
+      initialStates: [
+        {
+          permission: Permission.Camera,
+          status: 'granted',
+        },
+      ],
+    }),
+  );
 
-    const state = await manager.getStatus(Permission.Camera);
+  const state = await manager.getStatus(Permission.Camera);
 
-    expect(state).toMatchObject({
-      permission: Permission.Camera,
-      status: 'granted',
-      granted: true,
-    });
+  expect(state).toMatchObject({
+    permission: Permission.Camera,
+    status: 'granted',
+    granted: true,
   });
+});
 
-  test('does not throw for normal denial', async () => {
-    const manager = createPermissionManager(
-      createFakePermissionClient({
-        requestStates: [
-          {
-            permission: Permission.Notifications,
-            status: 'denied',
-            canAskAgain: false,
-          },
-        ],
-      }),
-    );
+test('does not throw for normal denial', async () => {
+  const manager = createPermissionManager(
+    createFakePermissionClient({
+      requestStates: [
+        {
+          permission: Permission.Notifications,
+          status: 'denied',
+          canAskAgain: false,
+        },
+      ],
+    }),
+  );
 
-    const state = await manager.request(Permission.Notifications);
+  const state = await manager.request(Permission.Notifications);
 
-    expect(state).toMatchObject({
-      status: 'denied',
-      granted: false,
-      canAskAgain: false,
-    });
+  expect(state).toMatchObject({
+    status: 'denied',
+    granted: false,
+    canAskAgain: false,
   });
+});
 
-  test('exposes openSettings only when the client supports it', async () => {
-    let opened = false;
-    const manager = createPermissionManager(
-      createFakePermissionClient({
-        openSettings: () => {
-          opened = true;
+test('exposes openSettings only when the client supports it', async () => {
+  let opened = false;
+  const manager = createPermissionManager(
+    createFakePermissionClient({
+      openSettings: () => {
+        opened = true;
 
-          return Promise.resolve();
-        },
-      }),
-    );
+        return Promise.resolve();
+      },
+    }),
+  );
 
-    await manager.openSettings?.();
+  await manager.openSettings?.();
 
-    expect(opened).toBe(true);
-  });
+  expect(opened).toBe(true);
 });

package/src/react/index.tsx

@@ -105,15 +105,8 @@ export function usePermission(
   options: UsePermissionOptions = {},
 ): PermissionHookResult {
   const manager = usePermissions();
-  const [state, setState] = useState<PermissionState>(
-    () =>
-      (options.initialState === undefined
-        ? undefined
-        : normalizePermissionState(permission, options.initialState)) ??
-      createPermissionState({
-        permission,
-        status: 'unknown',
-      }),
+  const [state, setState] = useState<PermissionState>(() =>
+    createInitialPermissionState(permission, options.initialState),
   );
 
   const refresh = useCallback(async () => {
@@ -131,10 +124,15 @@ export function usePermission(
   }, [manager, permission]);
 
   useEffect(() => {
-    if (options.refreshOnMount === true) {
-      void refresh();
-    }
-  }, [options.refreshOnMount, refresh]);
+    if (options.refreshOnMount !== true) return;
+    let active = true;
+    void manager.getStatus(permission).then((nextState) => {
+      if (active) setState(nextState);
+    });
+    return () => {
+      active = false;
+    };
+  }, [manager, options.refreshOnMount, permission]);
 
   const openSettings =
     manager.openSettings === undefined
@@ -154,3 +152,13 @@ export function usePermission(
     openSettings,
   };
 }
+
+function createInitialPermissionState(
+  permission: Permission,
+  initialState: PermissionState | undefined,
+): PermissionState {
+  return (
+    (initialState === undefined ? undefined : normalizePermissionState(permission, initialState)) ??
+    createPermissionState({ permission, status: 'unknown' })
+  );
+}

package/src/registry/permissions.test.ts

@@ -24,9 +24,10 @@ describe('permission registry', () => {
 
   test('exposes metadata for every permission', () => {
     for (const permission of PERMISSIONS) {
-      expect(PERMISSION_REGISTRY[permission].permission).toBe(permission);
-      expect(PERMISSION_REGISTRY[permission].label.length).toBeGreaterThan(0);
-      expect(getPermissionDefinition(permission)).toEqual(PERMISSION_REGISTRY[permission]);
+      const definition = Reflect.get(PERMISSION_REGISTRY, permission);
+      expect(definition.permission).toBe(permission);
+      expect(definition.label.length).toBeGreaterThan(0);
+      expect(getPermissionDefinition(permission)).toEqual(definition);
     }
   });
 

package/src/state/permissionState.test.ts

@@ -25,6 +25,13 @@ describe('permission state', () => {
       }).granted,
     ).toBe(true);
 
+    expect(
+      createPermissionState({
+        permission: Permission.MediaLibrary,
+        status: 'limited',
+      }).granted,
+    ).toBe(true);
+
     expect(
       createPermissionState({
         permission: Permission.Camera,
@@ -45,7 +52,7 @@ describe('permission state', () => {
     expect(state).toEqual({
       permission: Permission.Camera,
       status: 'limited',
-      granted: false,
+      granted: true,
       canAskAgain: true,
       requestedAt: undefined,
       reason: 'library-limited',

package/src/state/permissionState.ts

@@ -7,12 +7,7 @@ import type { Permission } from '../registry/permissions';
  * but user denial should be represented as a permission state.
  */
 export type PermissionStatus =
-  | 'unknown'
-  | 'granted'
-  | 'denied'
-  | 'blocked'
-  | 'limited'
-  | 'unavailable';
+  'unknown' | 'granted' | 'denied' | 'blocked' | 'limited' | 'unavailable';
 
 /***
  * Stable ordered list of normalized statuses.
@@ -57,13 +52,15 @@ export function isPermissionStatus(value: string): value is PermissionStatus {
 
 /***
  * Creates a normalized state and derives the `granted` convenience flag.
+ * Limited access is usable partial authorization, so both `granted` and
+ * `limited` states set `granted` to true.
  */
 export function createPermissionState(input: CreatePermissionStateInput): PermissionState {
   return {
     permission: input.permission,
     status: input.status,
     canAskAgain: input.canAskAgain,
-    granted: input.status === 'granted',
+    granted: input.status === 'granted' || input.status === 'limited',
     requestedAt: input.requestedAt,
     reason: input.reason,
   };