@ankhorage/permissions 0.1.1 → 0.2.0

package/src/expo/client.test.ts

@@ -0,0 +1,372 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test';
+
+import { Permission, PERMISSIONS } from '../registry/permissions';
+import { createPermissionClient } from './client';
+
+interface MockPermissionResponse {
+  readonly status: string;
+  readonly canAskAgain?: boolean;
+}
+
+type CameraMockMode = 'topLevel' | 'cameraNamespace' | 'missingExports';
+type AudioMockMode = 'topLevel' | 'audioModule' | 'missingExports';
+
+function permissionResponse(status: string, canAskAgain = true): MockPermissionResponse {
+  return { status, canAskAgain };
+}
+
+const cameraMock = {
+  mode: 'topLevel' as CameraMockMode,
+  getResponse: permissionResponse('granted'),
+  requestResponse: permissionResponse('granted'),
+  getError: undefined as string | undefined,
+  requestError: undefined as string | undefined,
+};
+
+const audioMock = {
+  mode: 'topLevel' as AudioMockMode,
+  getResponse: permissionResponse('granted'),
+  requestResponse: permissionResponse('granted'),
+  getError: undefined as string | undefined,
+  requestError: undefined as string | undefined,
+};
+
+const mediaLibraryMock = {
+  getResponse: permissionResponse('granted'),
+  requestResponse: permissionResponse('granted'),
+  getError: undefined as string | undefined,
+  requestError: undefined as string | undefined,
+  getCalls: [] as boolean[],
+  requestCalls: [] as boolean[],
+};
+
+const locationMock = {
+  foregroundGetResponse: permissionResponse('granted'),
+  foregroundRequestResponse: permissionResponse('granted'),
+  backgroundGetResponse: permissionResponse('granted'),
+  backgroundRequestResponse: permissionResponse('granted'),
+  getCalls: [] as string[],
+  requestCalls: [] as string[],
+};
+
+const notificationsMock = {
+  getResponse: permissionResponse('granted'),
+  requestResponse: permissionResponse('granted'),
+  getError: undefined as string | undefined,
+  requestError: undefined as string | undefined,
+};
+
+void mock.module('expo-camera', () => ({
+  get getCameraPermissionsAsync() {
+    if (cameraMock.mode !== 'topLevel') {
+      return undefined;
+    }
+
+    return () => {
+      if (cameraMock.getError !== undefined) {
+        throw new Error(cameraMock.getError);
+      }
+
+      return Promise.resolve(cameraMock.getResponse);
+    };
+  },
+  get requestCameraPermissionsAsync() {
+    if (cameraMock.mode !== 'topLevel') {
+      return undefined;
+    }
+
+    return () => {
+      if (cameraMock.requestError !== undefined) {
+        throw new Error(cameraMock.requestError);
+      }
+
+      return Promise.resolve(cameraMock.requestResponse);
+    };
+  },
+  get Camera() {
+    if (cameraMock.mode !== 'cameraNamespace') {
+      return undefined;
+    }
+
+    return {
+      getCameraPermissionsAsync: () => Promise.resolve(cameraMock.getResponse),
+      requestCameraPermissionsAsync: () => Promise.resolve(cameraMock.requestResponse),
+    };
+  },
+}));
+
+void mock.module('expo-audio', () => ({
+  get getRecordingPermissionsAsync() {
+    if (audioMock.mode !== 'topLevel') {
+      return undefined;
+    }
+
+    return () => {
+      if (audioMock.getError !== undefined) {
+        throw new Error(audioMock.getError);
+      }
+
+      return Promise.resolve(audioMock.getResponse);
+    };
+  },
+  get requestRecordingPermissionsAsync() {
+    if (audioMock.mode !== 'topLevel') {
+      return undefined;
+    }
+
+    return () => {
+      if (audioMock.requestError !== undefined) {
+        throw new Error(audioMock.requestError);
+      }
+
+      return Promise.resolve(audioMock.requestResponse);
+    };
+  },
+  get AudioModule() {
+    if (audioMock.mode !== 'audioModule') {
+      return undefined;
+    }
+
+    return {
+      getRecordingPermissionsAsync: () => Promise.resolve(audioMock.getResponse),
+      requestRecordingPermissionsAsync: () => Promise.resolve(audioMock.requestResponse),
+    };
+  },
+}));
+
+void mock.module('expo-media-library', () => ({
+  getPermissionsAsync: (writeOnly?: boolean) => {
+    mediaLibraryMock.getCalls.push(writeOnly === true);
+
+    if (mediaLibraryMock.getError !== undefined) {
+      throw new Error(mediaLibraryMock.getError);
+    }
+
+    return Promise.resolve(mediaLibraryMock.getResponse);
+  },
+  requestPermissionsAsync: (writeOnly?: boolean) => {
+    mediaLibraryMock.requestCalls.push(writeOnly === true);
+
+    if (mediaLibraryMock.requestError !== undefined) {
+      throw new Error(mediaLibraryMock.requestError);
+    }
+
+    return Promise.resolve(mediaLibraryMock.requestResponse);
+  },
+}));
+
+void mock.module('expo-location', () => ({
+  getForegroundPermissionsAsync: () => {
+    locationMock.getCalls.push('foreground');
+
+    return Promise.resolve(locationMock.foregroundGetResponse);
+  },
+  requestForegroundPermissionsAsync: () => {
+    locationMock.requestCalls.push('foreground');
+
+    return Promise.resolve(locationMock.foregroundRequestResponse);
+  },
+  getBackgroundPermissionsAsync: () => {
+    locationMock.getCalls.push('background');
+
+    return Promise.resolve(locationMock.backgroundGetResponse);
+  },
+  requestBackgroundPermissionsAsync: () => {
+    locationMock.requestCalls.push('background');
+
+    return Promise.resolve(locationMock.backgroundRequestResponse);
+  },
+}));
+
+void mock.module('expo-notifications', () => ({
+  getPermissionsAsync: () => {
+    if (notificationsMock.getError !== undefined) {
+      throw new Error(notificationsMock.getError);
+    }
+
+    return Promise.resolve(notificationsMock.getResponse);
+  },
+  requestPermissionsAsync: () => {
+    if (notificationsMock.requestError !== undefined) {
+      throw new Error(notificationsMock.requestError);
+    }
+
+    return Promise.resolve(notificationsMock.requestResponse);
+  },
+}));
+
+describe('createPermissionClient', () => {
+  beforeEach(() => {
+    resetExpoMocks();
+  });
+
+  test('covers getStatus and request for every known permission', async () => {
+    const client = createPermissionClient();
+
+    for (const permission of PERMISSIONS) {
+      const statusState = await client.getStatus(permission);
+      const requestState = await client.request(permission);
+
+      expect(statusState.permission).toBe(permission);
+      expect(statusState.status).toBe('granted');
+      expect(statusState.granted).toBe(true);
+
+      expect(requestState.permission).toBe(permission);
+      expect(requestState.status).toBe('granted');
+      expect(requestState.granted).toBe(true);
+    }
+
+    expect(mediaLibraryMock.getCalls).toEqual([false, true]);
+    expect(mediaLibraryMock.requestCalls).toEqual([false, true]);
+    expect(locationMock.getCalls).toEqual(['foreground', 'background']);
+    expect(locationMock.requestCalls).toEqual(['foreground', 'background']);
+  });
+
+  test('treats clipboard as not requiring a native Expo permission module', async () => {
+    const client = createPermissionClient();
+
+    const statusState = await client.getStatus(Permission.Clipboard);
+    const requestState = await client.request(Permission.Clipboard);
+
+    expect(statusState).toMatchObject({
+      permission: Permission.Clipboard,
+      status: 'granted',
+      granted: true,
+    });
+    expect(requestState).toMatchObject({
+      permission: Permission.Clipboard,
+      status: 'granted',
+      granted: true,
+    });
+  });
+
+  test('falls back to the Camera namespace when camera permission functions are nested', async () => {
+    cameraMock.mode = 'cameraNamespace';
+    cameraMock.getResponse = permissionResponse('denied', false);
+    cameraMock.requestResponse = permissionResponse('granted');
+
+    const client = createPermissionClient();
+
+    expect(await client.getStatus(Permission.Camera)).toMatchObject({
+      permission: Permission.Camera,
+      status: 'denied',
+      granted: false,
+      canAskAgain: false,
+    });
+    expect(await client.request(Permission.Camera)).toMatchObject({
+      permission: Permission.Camera,
+      status: 'granted',
+      granted: true,
+    });
+  });
+
+  test('falls back to AudioModule recording permission functions when top-level exports are absent', async () => {
+    audioMock.mode = 'audioModule';
+    audioMock.getResponse = permissionResponse('denied', false);
+    audioMock.requestResponse = permissionResponse('granted');
+
+    const client = createPermissionClient();
+
+    expect(await client.getStatus(Permission.Microphone)).toMatchObject({
+      permission: Permission.Microphone,
+      status: 'denied',
+      granted: false,
+      canAskAgain: false,
+    });
+    expect(await client.request(Permission.Microphone)).toMatchObject({
+      permission: Permission.Microphone,
+      status: 'granted',
+      granted: true,
+    });
+  });
+
+  test('normalizes unknown adapter statuses to unknown', async () => {
+    notificationsMock.getResponse = permissionResponse('mystery-status', false);
+    notificationsMock.requestResponse = permissionResponse('denied', false);
+
+    const client = createPermissionClient();
+    const state = await client.getStatus(Permission.Notifications);
+
+    expect(state).toMatchObject({
+      permission: Permission.Notifications,
+      status: 'unknown',
+      granted: false,
+      canAskAgain: false,
+    });
+  });
+
+  test('preserves denied request responses', async () => {
+    notificationsMock.requestResponse = permissionResponse('denied', false);
+
+    const client = createPermissionClient();
+    const state = await client.request(Permission.Notifications);
+
+    expect(state).toMatchObject({
+      permission: Permission.Notifications,
+      status: 'denied',
+      granted: false,
+      canAskAgain: false,
+    });
+  });
+
+  test('returns unavailable when a camera permission call fails at runtime', async () => {
+    cameraMock.getError = 'camera bridge unavailable';
+
+    const client = createPermissionClient();
+    const state = await client.getStatus(Permission.Camera);
+
+    expect(state).toMatchObject({
+      permission: Permission.Camera,
+      status: 'unavailable',
+      granted: false,
+      reason: 'camera bridge unavailable',
+    });
+  });
+
+  test('returns unavailable when a request call throws at runtime', async () => {
+    audioMock.requestError = 'microphone bridge unavailable';
+
+    const client = createPermissionClient();
+    const state = await client.request(Permission.Microphone);
+
+    expect(state).toMatchObject({
+      permission: Permission.Microphone,
+      status: 'unavailable',
+      granted: false,
+      reason: 'microphone bridge unavailable',
+    });
+  });
+});
+
+function resetExpoMocks(): void {
+  cameraMock.mode = 'topLevel';
+  cameraMock.getResponse = permissionResponse('granted');
+  cameraMock.requestResponse = permissionResponse('granted');
+  cameraMock.getError = undefined;
+  cameraMock.requestError = undefined;
+
+  audioMock.mode = 'topLevel';
+  audioMock.getResponse = permissionResponse('granted');
+  audioMock.requestResponse = permissionResponse('granted');
+  audioMock.getError = undefined;
+  audioMock.requestError = undefined;
+
+  mediaLibraryMock.getResponse = permissionResponse('granted');
+  mediaLibraryMock.requestResponse = permissionResponse('granted');
+  mediaLibraryMock.getError = undefined;
+  mediaLibraryMock.requestError = undefined;
+  mediaLibraryMock.getCalls.length = 0;
+  mediaLibraryMock.requestCalls.length = 0;
+
+  locationMock.foregroundGetResponse = permissionResponse('granted');
+  locationMock.foregroundRequestResponse = permissionResponse('granted');
+  locationMock.backgroundGetResponse = permissionResponse('granted');
+  locationMock.backgroundRequestResponse = permissionResponse('granted');
+  locationMock.getCalls.length = 0;
+  locationMock.requestCalls.length = 0;
+
+  notificationsMock.getResponse = permissionResponse('granted');
+  notificationsMock.requestResponse = permissionResponse('granted');
+  notificationsMock.getError = undefined;
+  notificationsMock.requestError = undefined;
+}

package/src/expo/client.ts

@@ -0,0 +1,79 @@
+import type { PermissionClient } from '../client/types';
+import { Permission } from '../registry/permissions';
+import { createPermissionState, type PermissionState } from '../state/permissionState';
+import { cameraAdapter } from './adapters/camera';
+import { locationAdapter } from './adapters/location';
+import { mediaLibraryAdapter } from './adapters/mediaLibrary';
+import { microphoneAdapter } from './adapters/microphone';
+import { notificationsAdapter } from './adapters/notifications';
+import { EXPO_PERMISSION_SUPPORT } from './manifest';
+
+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,
+};
+
+export function createPermissionClient(): PermissionClient {
+  return {
+    async getStatus(permission: Permission): Promise<PermissionState> {
+      const metadata = EXPO_PERMISSION_SUPPORT[permission];
+      if (metadata.support === 'unsupported' || metadata.support === 'notImplemented') {
+        return createUnavailableSupportState(permission);
+      }
+
+      if (metadata.support === 'notRequired') {
+        return createNotRequiredState(permission);
+      }
+
+      const adapter = adapters[permission];
+      if (!adapter) {
+        throw new Error(`No adapter registered for permission: ${permission}`);
+      }
+
+      return adapter.getStatus(permission);
+    },
+
+    async request(permission: Permission): Promise<PermissionState> {
+      const metadata = EXPO_PERMISSION_SUPPORT[permission];
+      if (metadata.support === 'unsupported' || metadata.support === 'notImplemented') {
+        return createUnavailableSupportState(permission);
+      }
+
+      if (metadata.support === 'notRequired') {
+        return createNotRequiredState(permission);
+      }
+
+      const adapter = adapters[permission];
+      if (!adapter) {
+        throw new Error(`No adapter registered for permission: ${permission}`);
+      }
+
+      return adapter.request(permission);
+    },
+  };
+}
+
+function createUnavailableSupportState(permission: Permission): PermissionState {
+  return createPermissionState({
+    permission,
+    status: 'unavailable',
+    reason: `Permission ${permission} is not implemented or supported on Expo.`,
+  });
+}
+
+function createNotRequiredState(permission: Permission): PermissionState {
+  return createPermissionState({
+    permission,
+    status: 'granted',
+  });
+}

package/src/expo/index.ts

@@ -0,0 +1,3 @@
+import { createPermissionClient } from './client';
+
+export { createPermissionClient };

package/src/expo/manifest.test.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, test } from 'bun:test';
+
+import { Permission, PERMISSIONS } from '../registry/permissions';
+import { 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('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(');
+  });
+
+  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.Microphone]).toEqual({
+      support: 'supported',
+      requiredPackages: ['expo-audio'],
+      configHints: ['microphonePermission', 'recordAudioAndroid'],
+    });
+
+    expect(EXPO_PERMISSION_SUPPORT[Permission.LocationForeground]).toEqual({
+      support: 'supported',
+      requiredPackages: ['expo-location'],
+      configHints: ['locationWhenInUsePermission'],
+    });
+
+    expect(EXPO_PERMISSION_SUPPORT[Permission.LocationBackground]).toEqual({
+      support: 'supported',
+      requiredPackages: ['expo-location'],
+      configHints: ['locationAlwaysAndWhenInUsePermission'],
+    });
+  });
+
+  test('treats clipboard as a not-required permission without runtime package requirements', () => {
+    expect(EXPO_PERMISSION_SUPPORT[Permission.Clipboard]).toEqual({
+      support: 'notRequired',
+      requiredPackages: [],
+      configHints: [],
+    });
+  });
+
+  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

@@ -0,0 +1,57 @@
+import { Permission } from '../registry/permissions';
+
+export type PermissionSupport =
+  | 'supported'
+  | 'notRequired'
+  | 'limited'
+  | 'notImplemented'
+  | 'unsupported';
+
+export interface ExpoPermissionMetadata {
+  readonly support: PermissionSupport;
+  readonly requiredPackages: readonly string[];
+  readonly configHints: readonly string[];
+}
+
+export const EXPO_PERMISSION_SUPPORT: Readonly<Record<Permission, ExpoPermissionMetadata>> = {
+  [Permission.Camera]: {
+    support: 'supported',
+    requiredPackages: ['expo-camera'],
+    configHints: ['cameraPermission'],
+  },
+  [Permission.Microphone]: {
+    support: 'supported',
+    requiredPackages: ['expo-audio'],
+    configHints: ['microphonePermission', 'recordAudioAndroid'],
+  },
+  [Permission.MediaLibrary]: {
+    support: 'supported',
+    requiredPackages: ['expo-media-library'],
+    configHints: ['mediaLibraryPermission'],
+  },
+  [Permission.MediaLibraryWrite]: {
+    support: 'supported',
+    requiredPackages: ['expo-media-library'],
+    configHints: ['mediaLibraryPermission'],
+  },
+  [Permission.LocationForeground]: {
+    support: 'supported',
+    requiredPackages: ['expo-location'],
+    configHints: ['locationWhenInUsePermission'],
+  },
+  [Permission.LocationBackground]: {
+    support: 'supported',
+    requiredPackages: ['expo-location'],
+    configHints: ['locationAlwaysAndWhenInUsePermission'],
+  },
+  [Permission.Notifications]: {
+    support: 'supported',
+    requiredPackages: ['expo-notifications'],
+    configHints: ['notificationsPermission'],
+  },
+  [Permission.Clipboard]: {
+    support: 'notRequired',
+    requiredPackages: [],
+    configHints: [],
+  },
+};

package/src/expo/modules.d.ts

@@ -0,0 +1,53 @@
+interface ExpoPermissionResult {
+  status: string;
+  canAskAgain?: boolean;
+}
+
+declare module 'expo-camera' {
+  export function getCameraPermissionsAsync(): Promise<ExpoPermissionResult>;
+  export function requestCameraPermissionsAsync(): Promise<ExpoPermissionResult>;
+  export const CameraNativeModule: {
+    getCameraPermissionsAsync(): Promise<ExpoPermissionResult>;
+    requestCameraPermissionsAsync(): Promise<ExpoPermissionResult>;
+  };
+  export const Camera: {
+    getCameraPermissionsAsync(): Promise<ExpoPermissionResult>;
+    requestCameraPermissionsAsync(): Promise<ExpoPermissionResult>;
+  };
+}
+
+declare module 'expo-location' {
+  export function getBackgroundPermissionsAsync(): Promise<ExpoPermissionResult>;
+  export function getForegroundPermissionsAsync(): Promise<ExpoPermissionResult>;
+  export function requestBackgroundPermissionsAsync(): Promise<ExpoPermissionResult>;
+  export function requestForegroundPermissionsAsync(): Promise<ExpoPermissionResult>;
+}
+
+declare module 'expo-media-library' {
+  export function getPermissionsAsync(
+    writeOnly?: boolean,
+    granularPermissions?: readonly string[],
+  ): Promise<ExpoPermissionResult>;
+  export function requestPermissionsAsync(
+    writeOnly?: boolean,
+    granularPermissions?: readonly string[],
+  ): Promise<ExpoPermissionResult>;
+}
+
+declare module 'expo-audio' {
+  export function getRecordingPermissionsAsync(): Promise<ExpoPermissionResult>;
+  export function requestRecordingPermissionsAsync(): Promise<ExpoPermissionResult>;
+  export const AudioModule: {
+    getRecordingPermissionsAsync(): Promise<ExpoPermissionResult>;
+    requestRecordingPermissionsAsync(): Promise<ExpoPermissionResult>;
+  };
+  export const Audio: {
+    getRecordingPermissionsAsync(): Promise<ExpoPermissionResult>;
+    requestRecordingPermissionsAsync(): Promise<ExpoPermissionResult>;
+  };
+}
+
+declare module 'expo-notifications' {
+  export function getPermissionsAsync(): Promise<ExpoPermissionResult>;
+  export function requestPermissionsAsync(): Promise<ExpoPermissionResult>;
+}