@ankhorage/permissions 0.1.0

package/src/react/index.tsx

@@ -0,0 +1,170 @@
+import {
+  createContext,
+  createElement,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+
+import type { PermissionClient } from '../client/types';
+import {
+  createPermissionManager,
+  type PermissionManager,
+} from '../manager/createPermissionManager';
+import type { Permission } from '../registry/permissions';
+import {
+  createPermissionState,
+  normalizePermissionState,
+  type PermissionState,
+  type PermissionStatus,
+} from '../state/permissionState';
+
+const PermissionsContext = createContext<PermissionManager | undefined>(undefined);
+
+/***
+ * Props accepted by `PermissionsProvider`.
+ */
+export interface PermissionsProviderProps {
+  readonly children: ReactNode;
+  readonly client?: PermissionClient;
+  readonly manager?: PermissionManager;
+}
+
+/***
+ * Options for `usePermission`.
+ */
+export interface UsePermissionOptions {
+  readonly initialState?: PermissionState;
+  readonly refreshOnMount?: boolean;
+}
+
+/***
+ * Result returned by `usePermission`.
+ */
+export interface PermissionHookResult {
+  readonly permission: Permission;
+  readonly status: PermissionStatus;
+  readonly canAskAgain?: boolean;
+  readonly granted: boolean;
+  readonly requestedAt?: Date;
+  readonly reason?: string;
+  readonly state: PermissionState;
+  readonly refresh: () => Promise<PermissionState>;
+  readonly request: () => Promise<PermissionState>;
+  readonly openSettings?: () => Promise<void>;
+}
+
+/***
+ * Provides a permission manager to React hooks.
+ *
+ * @readme
+ * React helpers are framework-neutral. They depend on React only and do not
+ * import browser, Expo, or React Native permission APIs.
+ */
+export function PermissionsProvider({
+  children,
+  client,
+  manager,
+}: PermissionsProviderProps): ReactNode {
+  const resolvedManager = useMemo(() => {
+    if (manager !== undefined) {
+      return manager;
+    }
+
+    if (client !== undefined) {
+      return createPermissionManager(client);
+    }
+
+    throw new Error('PermissionsProvider requires a client or manager.');
+  }, [client, manager]);
+
+  return createElement(PermissionsContext.Provider, { value: resolvedManager }, children);
+}
+
+/***
+ * Reads the current permission manager from context.
+ */
+export function usePermissions(): PermissionManager {
+  const manager = useContext(PermissionsContext);
+
+  if (manager === undefined) {
+    throw new Error('usePermissions must be used within PermissionsProvider.');
+  }
+
+  return manager;
+}
+
+/***
+ * Tracks a single permission and exposes explicit refresh/request actions.
+ *
+ * @usage
+ * ```tsx
+ * const camera = usePermission(Permission.Camera, { refreshOnMount: true });
+ *
+ * return (
+ *   <Button
+ *     disabled={camera.granted}
+ *     onPress={() => {
+ *       void camera.request();
+ *     }}
+ *   />
+ * );
+ * ```
+ */
+export function usePermission(
+  permission: Permission,
+  options: UsePermissionOptions = {},
+): PermissionHookResult {
+  const manager = usePermissions();
+  const [state, setState] = useState<PermissionState>(
+    () =>
+      (options.initialState === undefined
+        ? undefined
+        : normalizePermissionState(permission, options.initialState)) ??
+      createPermissionState({
+        permission,
+        status: 'unknown',
+      }),
+  );
+
+  const refresh = useCallback(async () => {
+    const nextState = await manager.getStatus(permission);
+    setState(nextState);
+
+    return nextState;
+  }, [manager, permission]);
+
+  const request = useCallback(async () => {
+    const nextState = await manager.request(permission);
+    setState(nextState);
+
+    return nextState;
+  }, [manager, permission]);
+
+  useEffect(() => {
+    if (options.refreshOnMount === true) {
+      void refresh();
+    }
+  }, [options.refreshOnMount, refresh]);
+
+  const openSettings =
+    manager.openSettings === undefined
+      ? undefined
+      : () => manager.openSettings?.() ?? Promise.resolve();
+
+  return {
+    permission: state.permission,
+    status: state.status,
+    canAskAgain: state.canAskAgain,
+    granted: state.granted,
+    requestedAt: state.requestedAt,
+    reason: state.reason,
+    state,
+    refresh,
+    request,
+    openSettings,
+  };
+}

package/src/registry/permissions.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  getPermissionDefinition,
+  isPermission,
+  Permission,
+  PERMISSION_REGISTRY,
+  PERMISSIONS,
+} from './permissions';
+
+describe('permission registry', () => {
+  test('contains the initial stable permissions', () => {
+    expect(PERMISSIONS).toEqual([
+      Permission.Camera,
+      Permission.Microphone,
+      Permission.MediaLibrary,
+      Permission.MediaLibraryWrite,
+      Permission.LocationForeground,
+      Permission.LocationBackground,
+      Permission.Notifications,
+      Permission.Clipboard,
+    ]);
+  });
+
+  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]);
+    }
+  });
+
+  test('validates permission strings', () => {
+    expect(isPermission('camera')).toBe(true);
+    expect(isPermission('not-a-permission')).toBe(false);
+  });
+});

package/src/registry/permissions.ts

@@ -0,0 +1,128 @@
+/***
+ * Common runtime permissions supported by the registry.
+ *
+ * @readme
+ * The registry is intentionally platform-neutral. Adapters translate each
+ * permission into whatever a browser, React Native app, Expo app, or test
+ * environment can actually check or request.
+ */
+export enum Permission {
+  Camera = 'camera',
+  Microphone = 'microphone',
+  MediaLibrary = 'mediaLibrary',
+  MediaLibraryWrite = 'mediaLibraryWrite',
+  LocationForeground = 'locationForeground',
+  LocationBackground = 'locationBackground',
+  Notifications = 'notifications',
+  Clipboard = 'clipboard',
+}
+
+/***
+ * Broad environment categories where a permission can be meaningful.
+ */
+export type PermissionEnvironment = 'web' | 'native' | 'test';
+
+/***
+ * Describes a known permission without coupling the registry to a platform SDK.
+ */
+export interface PermissionDefinition {
+  readonly permission: Permission;
+  readonly label: string;
+  readonly description: string;
+  readonly environments: readonly PermissionEnvironment[];
+}
+
+/***
+ * Stable ordered list of known permissions.
+ */
+export const PERMISSIONS = [
+  Permission.Camera,
+  Permission.Microphone,
+  Permission.MediaLibrary,
+  Permission.MediaLibraryWrite,
+  Permission.LocationForeground,
+  Permission.LocationBackground,
+  Permission.Notifications,
+  Permission.Clipboard,
+] as const;
+
+const PERMISSION_SET = new Set<string>(PERMISSIONS);
+
+/***
+ * Metadata for known permissions.
+ */
+export const PERMISSION_REGISTRY: Readonly<Record<Permission, PermissionDefinition>> = {
+  [Permission.Camera]: {
+    permission: Permission.Camera,
+    label: 'Camera',
+    description: 'Access to a device camera for capture or scanning workflows.',
+    environments: ['web', 'native', 'test'],
+  },
+  [Permission.Microphone]: {
+    permission: Permission.Microphone,
+    label: 'Microphone',
+    description: 'Access to a device microphone for audio recording or calls.',
+    environments: ['web', 'native', 'test'],
+  },
+  [Permission.MediaLibrary]: {
+    permission: Permission.MediaLibrary,
+    label: 'Media library',
+    description: 'Read access to photos, videos, or other local media assets.',
+    environments: ['native', 'test'],
+  },
+  [Permission.MediaLibraryWrite]: {
+    permission: Permission.MediaLibraryWrite,
+    label: 'Media library write',
+    description: 'Write access for saving media to a local library.',
+    environments: ['native', 'test'],
+  },
+  [Permission.LocationForeground]: {
+    permission: Permission.LocationForeground,
+    label: 'Foreground location',
+    description: 'Location access while the app or page is actively in use.',
+    environments: ['web', 'native', 'test'],
+  },
+  [Permission.LocationBackground]: {
+    permission: Permission.LocationBackground,
+    label: 'Background location',
+    description: 'Location access while the app is not actively in use.',
+    environments: ['native', 'test'],
+  },
+  [Permission.Notifications]: {
+    permission: Permission.Notifications,
+    label: 'Notifications',
+    description: 'Permission to show user-visible notifications.',
+    environments: ['web', 'native', 'test'],
+  },
+  [Permission.Clipboard]: {
+    permission: Permission.Clipboard,
+    label: 'Clipboard',
+    description: 'Read or write access to clipboard contents.',
+    environments: ['web', 'native', 'test'],
+  },
+};
+
+/***
+ * Returns true when a string is a registered permission identifier.
+ */
+export function isPermission(value: string): value is Permission {
+  return PERMISSION_SET.has(value);
+}
+
+/***
+ * Throws for programmer errors where an invalid permission reaches runtime.
+ */
+export function assertKnownPermission(permission: string): Permission {
+  if (!isPermission(permission)) {
+    throw new TypeError(`Unknown permission: ${permission}`);
+  }
+
+  return permission;
+}
+
+/***
+ * Reads registry metadata for a known permission.
+ */
+export function getPermissionDefinition(permission: Permission): PermissionDefinition {
+  return PERMISSION_REGISTRY[assertKnownPermission(permission)];
+}

package/src/state/permissionState.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Permission } from '../registry/permissions';
+import {
+  createPermissionState,
+  isPermissionStatus,
+  normalizePermissionState,
+  PERMISSION_STATUSES,
+} from './permissionState';
+
+describe('permission state', () => {
+  test('recognizes normalized statuses', () => {
+    for (const status of PERMISSION_STATUSES) {
+      expect(isPermissionStatus(status)).toBe(true);
+    }
+
+    expect(isPermissionStatus('prompt')).toBe(false);
+  });
+
+  test('derives granted from status', () => {
+    expect(
+      createPermissionState({
+        permission: Permission.Camera,
+        status: 'granted',
+      }).granted,
+    ).toBe(true);
+
+    expect(
+      createPermissionState({
+        permission: Permission.Camera,
+        status: 'denied',
+      }).granted,
+    ).toBe(false);
+  });
+
+  test('normalizes adapter results to the requested permission', () => {
+    const state = normalizePermissionState(Permission.Camera, {
+      permission: Permission.Microphone,
+      status: 'limited',
+      granted: false,
+      canAskAgain: true,
+      reason: 'library-limited',
+    });
+
+    expect(state).toEqual({
+      permission: Permission.Camera,
+      status: 'limited',
+      granted: false,
+      canAskAgain: true,
+      requestedAt: undefined,
+      reason: 'library-limited',
+    });
+  });
+});

package/src/state/permissionState.ts

@@ -0,0 +1,86 @@
+import type { Permission } from '../registry/permissions';
+
+/***
+ * Normalized permission statuses shared by adapters and UI code.
+ *
+ * Denial is normal control flow. Unexpected adapter failures may still throw,
+ * but user denial should be represented as a permission state.
+ */
+export type PermissionStatus =
+  | 'unknown'
+  | 'granted'
+  | 'denied'
+  | 'blocked'
+  | 'limited'
+  | 'unavailable';
+
+/***
+ * Stable ordered list of normalized statuses.
+ */
+export const PERMISSION_STATUSES = [
+  'unknown',
+  'granted',
+  'denied',
+  'blocked',
+  'limited',
+  'unavailable',
+] as const satisfies readonly PermissionStatus[];
+
+const PERMISSION_STATUS_SET = new Set<string>(PERMISSION_STATUSES);
+
+/***
+ * Normalized result returned by permission clients and managers.
+ */
+export interface PermissionState {
+  readonly permission: Permission;
+  readonly status: PermissionStatus;
+  readonly canAskAgain?: boolean;
+  readonly granted: boolean;
+  readonly requestedAt?: Date;
+  readonly reason?: string;
+}
+
+export interface CreatePermissionStateInput {
+  readonly permission: Permission;
+  readonly status: PermissionStatus;
+  readonly canAskAgain?: boolean;
+  readonly requestedAt?: Date;
+  readonly reason?: string;
+}
+
+/***
+ * Returns true when a string is one of the normalized statuses.
+ */
+export function isPermissionStatus(value: string): value is PermissionStatus {
+  return PERMISSION_STATUS_SET.has(value);
+}
+
+/***
+ * Creates a normalized state and derives the `granted` convenience flag.
+ */
+export function createPermissionState(input: CreatePermissionStateInput): PermissionState {
+  return {
+    permission: input.permission,
+    status: input.status,
+    canAskAgain: input.canAskAgain,
+    granted: input.status === 'granted',
+    requestedAt: input.requestedAt,
+    reason: input.reason,
+  };
+}
+
+/***
+ * Normalizes an adapter result to the requested permission and status shape.
+ */
+export function normalizePermissionState(
+  permission: Permission,
+  state: PermissionState,
+): PermissionState {
+  return createPermissionState({
+    permission,
+    status: state.status,
+    canAskAgain: state.canAskAgain,
+    requestedAt: state.requestedAt,
+    reason: state.reason,
+  });
+}

package/src/testing/index.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Permission, PERMISSIONS } from '../registry/permissions';
+import { createFakePermissionClient } from './index';
+
+describe('createFakePermissionClient', () => {
+  test('defaults every permission to unknown', async () => {
+    const client = createFakePermissionClient();
+
+    expect(client.getSnapshot()).toHaveLength(PERMISSIONS.length);
+    const state = await client.getStatus(Permission.Camera);
+
+    expect(state).toMatchObject({
+      status: 'unknown',
+      granted: false,
+      canAskAgain: true,
+    });
+  });
+
+  test('stores status updates', async () => {
+    const client = createFakePermissionClient();
+
+    client.setStatus(Permission.Clipboard, 'blocked', {
+      canAskAgain: false,
+      reason: 'policy',
+    });
+
+    const state = await client.getStatus(Permission.Clipboard);
+
+    expect(state).toMatchObject({
+      status: 'blocked',
+      canAskAgain: false,
+      reason: 'policy',
+    });
+  });
+
+  test('uses deterministic request results and clock', async () => {
+    const requestedAt = new Date('2026-06-08T12:00:00.000Z');
+    const client = createFakePermissionClient({
+      now: () => requestedAt,
+      requestStates: [
+        {
+          permission: Permission.Camera,
+          status: 'granted',
+        },
+      ],
+    });
+
+    const result = await client.request(Permission.Camera);
+
+    expect(result).toMatchObject({
+      status: 'granted',
+      granted: true,
+      requestedAt,
+    });
+  });
+});

package/src/testing/index.ts

@@ -0,0 +1,168 @@
+import type { PermissionClient } from '../client/types';
+import type { Permission } from '../registry/permissions';
+import { assertKnownPermission, PERMISSIONS } from '../registry/permissions';
+import {
+  createPermissionState,
+  type PermissionState,
+  type PermissionStatus,
+} from '../state/permissionState';
+
+/***
+ * Seed format accepted by the fake client.
+ */
+export type FakePermissionStateSeed =
+  | PermissionState
+  | {
+      readonly permission: Permission;
+      readonly status: PermissionStatus;
+      readonly canAskAgain?: boolean;
+      readonly reason?: string;
+    };
+
+/***
+ * Options for deterministic fake clients.
+ */
+export interface FakePermissionClientOptions {
+  readonly initialStates?: readonly FakePermissionStateSeed[];
+  readonly requestStates?: readonly FakePermissionStateSeed[];
+  readonly now?: () => Date;
+  readonly openSettings?: () => Promise<void>;
+}
+
+/***
+ * Test client that stores permission states in memory.
+ */
+export interface FakePermissionClient extends PermissionClient {
+  setState(state: FakePermissionStateSeed): void;
+  setStatus(
+    permission: Permission,
+    status: PermissionStatus,
+    options?: {
+      readonly canAskAgain?: boolean;
+      readonly reason?: string;
+    },
+  ): void;
+  getSnapshot(): readonly PermissionState[];
+}
+
+/***
+ * Creates a deterministic in-memory client for tests and examples.
+ *
+ * @readme
+ * Fake clients make permission flows testable without native devices, browser
+ * prompts, simulators, or network access.
+ *
+ * @usage
+ * ```ts
+ * const client = createFakePermissionClient({
+ *   initialStates: [{ permission: Permission.Camera, status: 'denied' }],
+ * });
+ * await client.request(Permission.Camera);
+ * ```
+ */
+export function createFakePermissionClient(
+  options: FakePermissionClientOptions = {},
+): FakePermissionClient {
+  const now = options.now ?? (() => new Date());
+  const states = new Map<Permission, PermissionState>();
+  const requestStates = new Map<Permission, PermissionState>();
+
+  for (const permission of PERMISSIONS) {
+    states.set(
+      permission,
+      createPermissionState({
+        permission,
+        status: 'unknown',
+        canAskAgain: true,
+      }),
+    );
+  }
+
+  for (const state of options.initialStates ?? []) {
+    states.set(state.permission, normalizeSeed(state));
+  }
+
+  for (const state of options.requestStates ?? []) {
+    requestStates.set(state.permission, normalizeSeed(state));
+  }
+
+  const client: FakePermissionClient = {
+    getStatus(permission) {
+      return Promise.resolve(getStoredState(states, assertKnownPermission(permission)));
+    },
+
+    request(permission) {
+      const knownPermission = assertKnownPermission(permission);
+      const requestState =
+        requestStates.get(knownPermission) ?? getStoredState(states, knownPermission);
+      const nextState = createPermissionState({
+        permission: knownPermission,
+        status: requestState.status,
+        canAskAgain: requestState.canAskAgain,
+        requestedAt: now(),
+        reason: requestState.reason,
+      });
+
+      states.set(knownPermission, nextState);
+
+      return Promise.resolve(nextState);
+    },
+
+    openSettings: options.openSettings,
+
+    setState(state) {
+      const normalizedState = normalizeSeed(state);
+      states.set(normalizedState.permission, normalizedState);
+    },
+
+    setStatus(permission, status, statusOptions = {}) {
+      const knownPermission = assertKnownPermission(permission);
+      states.set(
+        knownPermission,
+        createPermissionState({
+          permission: knownPermission,
+          status,
+          canAskAgain: statusOptions.canAskAgain,
+          reason: statusOptions.reason,
+        }),
+      );
+    },
+
+    getSnapshot() {
+      return PERMISSIONS.map((permission) => getStoredState(states, permission));
+    },
+  };
+
+  if (options.openSettings === undefined) {
+    delete client.openSettings;
+  }
+
+  return client;
+}
+
+function normalizeSeed(seed: FakePermissionStateSeed): PermissionState {
+  return createPermissionState({
+    permission: assertKnownPermission(seed.permission),
+    status: seed.status,
+    canAskAgain: seed.canAskAgain,
+    requestedAt: 'requestedAt' in seed ? seed.requestedAt : undefined,
+    reason: seed.reason,
+  });
+}
+
+function getStoredState(
+  states: ReadonlyMap<Permission, PermissionState>,
+  permission: Permission,
+): PermissionState {
+  const state = states.get(permission);
+
+  if (state === undefined) {
+    return createPermissionState({
+      permission,
+      status: 'unknown',
+      canAskAgain: true,
+    });
+  }
+
+  return state;
+}