@ankhorage/permissions 0.1.0

package/dist/web/index.js

@@ -0,0 +1,234 @@
+import { assertKnownPermission, Permission } from '../registry/permissions';
+import { createPermissionState, } from '../state/permissionState';
+/***
+ * Creates a browser permission client using guarded structural globals.
+ *
+ * @readme
+ * Unsupported web APIs resolve to `status: 'unavailable'`. The adapter does not
+ * import DOM types and does not assume it is running in a browser.
+ */
+export function createWebPermissionClient(options = {}) {
+    const global = options.global ?? getDefaultGlobal();
+    return {
+        async getStatus(permission) {
+            const knownPermission = assertKnownPermission(permission);
+            switch (knownPermission) {
+                case Permission.Notifications:
+                    return getNotificationStatus(knownPermission, global);
+                case Permission.LocationForeground:
+                    return getPermissionApiStatus(knownPermission, global, 'geolocation', 'Geolocation is unavailable in this environment.');
+                case Permission.Camera:
+                    return getMediaStatus(knownPermission, global, 'camera');
+                case Permission.Microphone:
+                    return getMediaStatus(knownPermission, global, 'microphone');
+                default:
+                    return unavailable(knownPermission, 'This permission is not supported by the web adapter.');
+            }
+        },
+        async request(permission) {
+            const knownPermission = assertKnownPermission(permission);
+            switch (knownPermission) {
+                case Permission.Notifications:
+                    return requestNotifications(knownPermission, global);
+                case Permission.LocationForeground:
+                    return requestGeolocation(knownPermission, global);
+                case Permission.Camera:
+                    return requestMedia(knownPermission, global, { video: true });
+                case Permission.Microphone:
+                    return requestMedia(knownPermission, global, { audio: true });
+                default:
+                    return unavailable(knownPermission, 'This permission is not supported by the web adapter.');
+            }
+        },
+    };
+}
+function getDefaultGlobal() {
+    return globalThis;
+}
+function getNotificationStatus(permission, global) {
+    if (global.Notification === undefined) {
+        return unavailable(permission, 'Notification API is unavailable.');
+    }
+    return stateFromNotificationPermission(permission, global.Notification.permission);
+}
+async function requestNotifications(permission, global) {
+    if (global.Notification === undefined) {
+        return unavailable(permission, 'Notification API is unavailable.');
+    }
+    try {
+        const result = await global.Notification.requestPermission();
+        return stateFromNotificationPermission(permission, result);
+    }
+    catch (error) {
+        return unavailable(permission, `Notification permission request failed${formatErrorName(error)}.`);
+    }
+}
+async function getPermissionApiStatus(permission, global, name, unavailableReason) {
+    if (global.navigator?.permissions === undefined) {
+        return unavailable(permission, unavailableReason);
+    }
+    try {
+        const status = await global.navigator.permissions.query({ name });
+        return stateFromBrowserPermission(permission, status.state);
+    }
+    catch {
+        return unavailable(permission, unavailableReason);
+    }
+}
+async function getMediaStatus(permission, global, name) {
+    if (global.navigator?.permissions !== undefined) {
+        try {
+            const status = await global.navigator.permissions.query({ name });
+            return stateFromBrowserPermission(permission, status.state);
+        }
+        catch {
+            return getMediaAvailability(permission, global);
+        }
+    }
+    return getMediaAvailability(permission, global);
+}
+function getMediaAvailability(permission, global) {
+    if (global.isSecureContext === false) {
+        return createPermissionState({
+            permission,
+            status: 'blocked',
+            canAskAgain: false,
+            reason: 'Media permissions require a secure context.',
+        });
+    }
+    if (global.navigator?.mediaDevices?.getUserMedia === undefined) {
+        return unavailable(permission, 'Media devices API is unavailable.');
+    }
+    return createPermissionState({
+        permission,
+        status: 'unknown',
+        canAskAgain: true,
+    });
+}
+async function requestGeolocation(permission, global) {
+    if (global.isSecureContext === false) {
+        return createPermissionState({
+            permission,
+            status: 'blocked',
+            canAskAgain: false,
+            reason: 'Geolocation requires a secure context.',
+        });
+    }
+    if (global.navigator?.geolocation === undefined) {
+        return unavailable(permission, 'Geolocation API is unavailable.');
+    }
+    return new Promise((resolve) => {
+        global.navigator?.geolocation?.getCurrentPosition(() => {
+            resolve(createPermissionState({
+                permission,
+                status: 'granted',
+                canAskAgain: true,
+                requestedAt: new Date(),
+            }));
+        }, () => {
+            resolve(createPermissionState({
+                permission,
+                status: 'denied',
+                canAskAgain: false,
+                requestedAt: new Date(),
+            }));
+        }, { maximumAge: 0 });
+    });
+}
+async function requestMedia(permission, global, constraints) {
+    const availability = getMediaAvailability(permission, global);
+    if (availability.status !== 'unknown') {
+        return availability;
+    }
+    try {
+        const stream = await global.navigator?.mediaDevices?.getUserMedia(constraints);
+        for (const track of stream?.getTracks() ?? []) {
+            track.stop();
+        }
+        return createPermissionState({
+            permission,
+            status: 'granted',
+            canAskAgain: true,
+            requestedAt: new Date(),
+        });
+    }
+    catch (error) {
+        return stateFromMediaError(permission, error);
+    }
+}
+function stateFromMediaError(permission, error) {
+    const errorName = getErrorName(error);
+    const unavailableErrorNames = new Set([
+        'AbortError',
+        'NotFoundError',
+        'NotReadableError',
+        'OverconstrainedError',
+        'SecurityError',
+    ]);
+    if (errorName !== undefined && unavailableErrorNames.has(errorName)) {
+        return createPermissionState({
+            permission,
+            status: 'unavailable',
+            canAskAgain: false,
+            requestedAt: new Date(),
+            reason: `Media permission request failed: ${errorName}.`,
+        });
+    }
+    return createPermissionState({
+        permission,
+        status: 'denied',
+        canAskAgain: false,
+        requestedAt: new Date(),
+        reason: errorName === undefined
+            ? 'Media permission request was denied.'
+            : `Media permission request was denied: ${errorName}.`,
+    });
+}
+function stateFromNotificationPermission(permission, status) {
+    if (status === 'granted') {
+        return createPermissionState({
+            permission,
+            status: 'granted',
+            canAskAgain: true,
+        });
+    }
+    if (status === 'denied') {
+        return createPermissionState({
+            permission,
+            status: 'denied',
+            canAskAgain: false,
+        });
+    }
+    return createPermissionState({
+        permission,
+        status: 'unknown',
+        canAskAgain: true,
+    });
+}
+function stateFromBrowserPermission(permission, status) {
+    const normalizedStatus = status === 'prompt' ? 'unknown' : status;
+    return createPermissionState({
+        permission,
+        status: normalizedStatus,
+        canAskAgain: status === 'prompt' || status === 'granted',
+    });
+}
+function unavailable(permission, reason) {
+    return createPermissionState({
+        permission,
+        status: 'unavailable',
+        canAskAgain: false,
+        reason,
+    });
+}
+function formatErrorName(error) {
+    const errorName = getErrorName(error);
+    return errorName === undefined ? '' : `: ${errorName}`;
+}
+function getErrorName(error) {
+    if (typeof error !== 'object' || error === null || !('name' in error)) {
+        return undefined;
+    }
+    return typeof error.name === 'string' && error.name.length > 0 ? error.name : undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/web/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PermissionClient } from '../client/types';\nimport { assertKnownPermission, Permission } from '../registry/permissions';\nimport {\n  createPermissionState,\n  type PermissionState,\n  type PermissionStatus,\n} from '../state/permissionState';\n\ntype BrowserPermissionName = 'camera' | 'microphone' | 'geolocation' | 'notifications';\ntype BrowserPermissionState = 'granted' | 'denied' | 'prompt';\ntype NotificationPermissionState = 'default' | 'denied' | 'granted';\n\ninterface BrowserPermissionStatus {\n  readonly state: BrowserPermissionState;\n}\n\ninterface BrowserPermissions {\n  query(descriptor: { readonly name: BrowserPermissionName }): Promise<BrowserPermissionStatus>;\n}\n\ninterface MediaStreamTrackLike {\n  stop(): void;\n}\n\ninterface MediaStreamLike {\n  getTracks(): readonly MediaStreamTrackLike[];\n}\n\ninterface MediaDevicesLike {\n  getUserMedia(constraints: {\n    readonly audio?: boolean;\n    readonly video?: boolean;\n  }): Promise<MediaStreamLike>;\n}\n\ninterface GeolocationLike {\n  getCurrentPosition(\n    success: () => void,\n    error: () => void,\n    options?: {\n      readonly maximumAge?: number;\n      readonly timeout?: number;\n    },\n  ): void;\n}\n\ninterface NavigatorLike {\n  readonly permissions?: BrowserPermissions;\n  readonly mediaDevices?: MediaDevicesLike;\n  readonly geolocation?: GeolocationLike;\n}\n\ninterface NotificationLike {\n  readonly permission: NotificationPermissionState;\n  requestPermission(): Promise<NotificationPermissionState> | NotificationPermissionState;\n}\n\ninterface WebGlobalLike {\n  readonly isSecureContext?: boolean;\n  readonly navigator?: NavigatorLike;\n  readonly Notification?: NotificationLike;\n}\n\n/***\n * Options for the browser permission adapter.\n */\nexport interface WebPermissionClientOptions {\n  readonly global?: WebGlobalLike;\n}\n\n/***\n * Creates a browser permission client using guarded structural globals.\n *\n * @readme\n * Unsupported web APIs resolve to `status: 'unavailable'`. The adapter does not\n * import DOM types and does not assume it is running in a browser.\n */\nexport function createWebPermissionClient(\n  options: WebPermissionClientOptions = {},\n): PermissionClient {\n  const global = options.global ?? getDefaultGlobal();\n\n  return {\n    async getStatus(permission) {\n      const knownPermission = assertKnownPermission(permission);\n\n      switch (knownPermission) {\n        case Permission.Notifications:\n          return getNotificationStatus(knownPermission, global);\n        case Permission.LocationForeground:\n          return getPermissionApiStatus(\n            knownPermission,\n            global,\n            'geolocation',\n            'Geolocation is unavailable in this environment.',\n          );\n        case Permission.Camera:\n          return getMediaStatus(knownPermission, global, 'camera');\n        case Permission.Microphone:\n          return getMediaStatus(knownPermission, global, 'microphone');\n        default:\n          return unavailable(\n            knownPermission,\n            'This permission is not supported by the web adapter.',\n          );\n      }\n    },\n\n    async request(permission) {\n      const knownPermission = assertKnownPermission(permission);\n\n      switch (knownPermission) {\n        case Permission.Notifications:\n          return requestNotifications(knownPermission, global);\n        case Permission.LocationForeground:\n          return requestGeolocation(knownPermission, global);\n        case Permission.Camera:\n          return requestMedia(knownPermission, global, { video: true });\n        case Permission.Microphone:\n          return requestMedia(knownPermission, global, { audio: true });\n        default:\n          return unavailable(\n            knownPermission,\n            'This permission is not supported by the web adapter.',\n          );\n      }\n    },\n  };\n}\n\nfunction getDefaultGlobal(): WebGlobalLike {\n  return globalThis as WebGlobalLike;\n}\n\nfunction getNotificationStatus(permission: Permission, global: WebGlobalLike): PermissionState {\n  if (global.Notification === undefined) {\n    return unavailable(permission, 'Notification API is unavailable.');\n  }\n\n  return stateFromNotificationPermission(permission, global.Notification.permission);\n}\n\nasync function requestNotifications(\n  permission: Permission,\n  global: WebGlobalLike,\n): Promise<PermissionState> {\n  if (global.Notification === undefined) {\n    return unavailable(permission, 'Notification API is unavailable.');\n  }\n\n  try {\n    const result = await global.Notification.requestPermission();\n\n    return stateFromNotificationPermission(permission, result);\n  } catch (error) {\n    return unavailable(\n      permission,\n      `Notification permission request failed${formatErrorName(error)}.`,\n    );\n  }\n}\n\nasync function getPermissionApiStatus(\n  permission: Permission,\n  global: WebGlobalLike,\n  name: BrowserPermissionName,\n  unavailableReason: string,\n): Promise<PermissionState> {\n  if (global.navigator?.permissions === undefined) {\n    return unavailable(permission, unavailableReason);\n  }\n\n  try {\n    const status = await global.navigator.permissions.query({ name });\n\n    return stateFromBrowserPermission(permission, status.state);\n  } catch {\n    return unavailable(permission, unavailableReason);\n  }\n}\n\nasync function getMediaStatus(\n  permission: Permission,\n  global: WebGlobalLike,\n  name: BrowserPermissionName,\n): Promise<PermissionState> {\n  if (global.navigator?.permissions !== undefined) {\n    try {\n      const status = await global.navigator.permissions.query({ name });\n\n      return stateFromBrowserPermission(permission, status.state);\n    } catch {\n      return getMediaAvailability(permission, global);\n    }\n  }\n\n  return getMediaAvailability(permission, global);\n}\n\nfunction getMediaAvailability(permission: Permission, global: WebGlobalLike): PermissionState {\n  if (global.isSecureContext === false) {\n    return createPermissionState({\n      permission,\n      status: 'blocked',\n      canAskAgain: false,\n      reason: 'Media permissions require a secure context.',\n    });\n  }\n\n  if (global.navigator?.mediaDevices?.getUserMedia === undefined) {\n    return unavailable(permission, 'Media devices API is unavailable.');\n  }\n\n  return createPermissionState({\n    permission,\n    status: 'unknown',\n    canAskAgain: true,\n  });\n}\n\nasync function requestGeolocation(\n  permission: Permission,\n  global: WebGlobalLike,\n): Promise<PermissionState> {\n  if (global.isSecureContext === false) {\n    return createPermissionState({\n      permission,\n      status: 'blocked',\n      canAskAgain: false,\n      reason: 'Geolocation requires a secure context.',\n    });\n  }\n\n  if (global.navigator?.geolocation === undefined) {\n    return unavailable(permission, 'Geolocation API is unavailable.');\n  }\n\n  return new Promise((resolve) => {\n    global.navigator?.geolocation?.getCurrentPosition(\n      () => {\n        resolve(\n          createPermissionState({\n            permission,\n            status: 'granted',\n            canAskAgain: true,\n            requestedAt: new Date(),\n          }),\n        );\n      },\n      () => {\n        resolve(\n          createPermissionState({\n            permission,\n            status: 'denied',\n            canAskAgain: false,\n            requestedAt: new Date(),\n          }),\n        );\n      },\n      { maximumAge: 0 },\n    );\n  });\n}\n\nasync function requestMedia(\n  permission: Permission,\n  global: WebGlobalLike,\n  constraints: {\n    readonly audio?: boolean;\n    readonly video?: boolean;\n  },\n): Promise<PermissionState> {\n  const availability = getMediaAvailability(permission, global);\n\n  if (availability.status !== 'unknown') {\n    return availability;\n  }\n\n  try {\n    const stream = await global.navigator?.mediaDevices?.getUserMedia(constraints);\n\n    for (const track of stream?.getTracks() ?? []) {\n      track.stop();\n    }\n\n    return createPermissionState({\n      permission,\n      status: 'granted',\n      canAskAgain: true,\n      requestedAt: new Date(),\n    });\n  } catch (error) {\n    return stateFromMediaError(permission, error);\n  }\n}\n\nfunction stateFromMediaError(permission: Permission, error: unknown): PermissionState {\n  const errorName = getErrorName(error);\n  const unavailableErrorNames = new Set([\n    'AbortError',\n    'NotFoundError',\n    'NotReadableError',\n    'OverconstrainedError',\n    'SecurityError',\n  ]);\n\n  if (errorName !== undefined && unavailableErrorNames.has(errorName)) {\n    return createPermissionState({\n      permission,\n      status: 'unavailable',\n      canAskAgain: false,\n      requestedAt: new Date(),\n      reason: `Media permission request failed: ${errorName}.`,\n    });\n  }\n\n  return createPermissionState({\n    permission,\n    status: 'denied',\n    canAskAgain: false,\n    requestedAt: new Date(),\n    reason:\n      errorName === undefined\n        ? 'Media permission request was denied.'\n        : `Media permission request was denied: ${errorName}.`,\n  });\n}\n\nfunction stateFromNotificationPermission(\n  permission: Permission,\n  status: NotificationPermissionState,\n): PermissionState {\n  if (status === 'granted') {\n    return createPermissionState({\n      permission,\n      status: 'granted',\n      canAskAgain: true,\n    });\n  }\n\n  if (status === 'denied') {\n    return createPermissionState({\n      permission,\n      status: 'denied',\n      canAskAgain: false,\n    });\n  }\n\n  return createPermissionState({\n    permission,\n    status: 'unknown',\n    canAskAgain: true,\n  });\n}\n\nfunction stateFromBrowserPermission(\n  permission: Permission,\n  status: BrowserPermissionState,\n): PermissionState {\n  const normalizedStatus: PermissionStatus = status === 'prompt' ? 'unknown' : status;\n\n  return createPermissionState({\n    permission,\n    status: normalizedStatus,\n    canAskAgain: status === 'prompt' || status === 'granted',\n  });\n}\n\nfunction unavailable(permission: Permission, reason: string): PermissionState {\n  return createPermissionState({\n    permission,\n    status: 'unavailable',\n    canAskAgain: false,\n    reason,\n  });\n}\n\nfunction formatErrorName(error: unknown): string {\n  const errorName = getErrorName(error);\n\n  return errorName === undefined ? '' : `: ${errorName}`;\n}\n\nfunction getErrorName(error: unknown): string | undefined {\n  if (typeof error !== 'object' || error === null || !('name' in error)) {\n    return undefined;\n  }\n\n  return typeof error.name === 'string' && error.name.length > 0 ? error.name : undefined;\n}\n"]}

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@ankhorage/permissions",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Cross-platform permission registry and runtime helpers for TypeScript apps, with unified request/check APIs for camera, media, location, notifications, microphone, etc. and web/native capabilities.",
+  "homepage": "https://github.com/ankhorage/permissions#readme",
+  "bugs": {
+    "url": "https://github.com/ankhorage/permissions/issues"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankhorage/permissions.git"
+  },
+  "keywords": [
+    "permissions",
+    "permission-management",
+    "capabilities",
+    "typescript",
+    "react",
+    "react-native",
+    "react-native-web",
+    "expo",
+    "web",
+    "camera",
+    "notifications",
+    "location",
+    "media-library",
+    "microphone",
+    "privacy",
+    "cross-platform"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "react": ">=18.2.0 || >=19.0.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "package.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "react-native": "./dist/index.js",
+      "browser": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "react-native": "./dist/react/index.js",
+      "browser": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    },
+    "./testing": {
+      "react-native": "./dist/testing/index.js",
+      "browser": "./dist/testing/index.js",
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./web": {
+      "browser": "./dist/web/index.js",
+      "types": "./dist/web/index.d.ts",
+      "import": "./dist/web/index.js",
+      "default": "./dist/web/index.js"
+    },
+    "./metadata": {
+      "react-native": "./dist/metadata/index.js",
+      "browser": "./dist/metadata/index.js",
+      "types": "./dist/metadata/index.d.ts",
+      "import": "./dist/metadata/index.js",
+      "default": "./dist/metadata/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.tsbuildinfo && bun x tsc -p tsconfig.json",
+    "changeset": "changeset",
+    "changeset:status": "changeset status --since=origin/main",
+    "docs": "paradox",
+    "knip": "ankhorage-knip",
+    "lint": "ankhorage-eslint . --max-warnings=0",
+    "lint:fix": "ankhorage-eslint . --fix --max-warnings=0",
+    "format": "ankhorage-prettier --write .",
+    "format:check": "ankhorage-prettier --check .",
+    "prepack": "bun run build",
+    "test": "bun test src",
+    "typecheck": "bun x tsc --noEmit -p tsconfig.json",
+    "version-packages": "changeset version"
+  },
+  "devDependencies": {
+    "@ankhorage/devtools": "^1.0.6",
+    "@ankhorage/paradox": "^0.1.10",
+    "@changesets/cli": "^2.31.0",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.7",
+    "react": "^19.2.1",
+    "typescript": "^5.9.3"
+  },
+  "packageManager": "bun@1.3.13"
+}

package/src/client/types.ts

@@ -0,0 +1,19 @@
+import type { Permission } from '../registry/permissions';
+import type { PermissionState } from '../state/permissionState';
+
+/***
+ * Adapter-neutral interface for runtime permission checks and requests.
+ *
+ * @usage
+ * ```ts
+ * const state = await client.getStatus(Permission.Camera);
+ * if (!state.granted) {
+ *   await client.request(Permission.Camera);
+ * }
+ * ```
+ */
+export interface PermissionClient {
+  getStatus(permission: Permission): Promise<PermissionState>;
+  request(permission: Permission): Promise<PermissionState>;
+  openSettings?(): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export type { PermissionClient } from './client/types';
+export type { PermissionManager } from './manager/createPermissionManager';
+export { createPermissionManager } from './manager/createPermissionManager';
+export type {
+  PermissionHookResult,
+  PermissionsProviderProps,
+  UsePermissionOptions,
+} from './react/index';
+export { PermissionsProvider, usePermission, usePermissions } from './react/index';
+export type { PermissionDefinition, PermissionEnvironment } from './registry/permissions';
+export {
+  assertKnownPermission,
+  getPermissionDefinition,
+  isPermission,
+  Permission,
+  PERMISSION_REGISTRY,
+  PERMISSIONS,
+} from './registry/permissions';
+export type { PermissionState, PermissionStatus } from './state/permissionState';
+export {
+  createPermissionState,
+  isPermissionStatus,
+  normalizePermissionState,
+  PERMISSION_STATUSES,
+} from './state/permissionState';
+export type {
+  FakePermissionClient,
+  FakePermissionClientOptions,
+  FakePermissionStateSeed,
+} from './testing/index';
+export { createFakePermissionClient } from './testing/index';

package/src/manager/createPermissionManager.test.ts

@@ -0,0 +1,67 @@
+import { describe, 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',
+          },
+        ],
+      }),
+    );
+
+    const state = await manager.getStatus(Permission.Camera);
+
+    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,
+          },
+        ],
+      }),
+    );
+
+    const state = await manager.request(Permission.Notifications);
+
+    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;
+
+          return Promise.resolve();
+        },
+      }),
+    );
+
+    await manager.openSettings?.();
+
+    expect(opened).toBe(true);
+  });
+});

package/src/manager/createPermissionManager.ts

@@ -0,0 +1,54 @@
+import type { PermissionClient } from '../client/types';
+import { assertKnownPermission, type Permission } from '../registry/permissions';
+import { normalizePermissionState, type PermissionState } from '../state/permissionState';
+
+/***
+ * Public manager returned by `createPermissionManager`.
+ */
+export interface PermissionManager {
+  getStatus(permission: Permission): Promise<PermissionState>;
+  request(permission: Permission): Promise<PermissionState>;
+  openSettings?(): Promise<void>;
+}
+
+/***
+ * Wraps a client with registry validation and normalized results.
+ *
+ * @readme
+ * Runtime permissions and build-time native configuration are separate concerns.
+ * This manager checks or requests permissions through a client, but it does not
+ * generate iOS usage descriptions, Android manifest entries, or Expo config
+ * plugins.
+ *
+ * @usage
+ * ```ts
+ * const permissions = createPermissionManager(client);
+ * const camera = await permissions.getStatus(Permission.Camera);
+ * const requested = camera.granted
+ *   ? camera
+ *   : await permissions.request(Permission.Camera);
+ * ```
+ */
+export function createPermissionManager(client: PermissionClient): PermissionManager {
+  const manager: PermissionManager = {
+    async getStatus(permission) {
+      const knownPermission = assertKnownPermission(permission);
+      const state = await client.getStatus(knownPermission);
+
+      return normalizePermissionState(knownPermission, state);
+    },
+
+    async request(permission) {
+      const knownPermission = assertKnownPermission(permission);
+      const state = await client.request(knownPermission);
+
+      return normalizePermissionState(knownPermission, state);
+    },
+  };
+
+  if (client.openSettings !== undefined) {
+    manager.openSettings = () => client.openSettings?.() ?? Promise.resolve();
+  }
+
+  return manager;
+}

package/src/metadata/index.ts

@@ -0,0 +1,7 @@
+/***
+ * Public package metadata used by generated documentation and tooling.
+ */
+export const permissionsPackageMetadata = {
+  name: '@ankhorage/permissions',
+  description: 'Cross-platform permission registry and runtime helpers for TypeScript apps.',
+} as const;

package/src/react/index.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, test } from 'bun:test';
+
+import { PermissionsProvider, usePermission, usePermissions } from './index';
+
+describe('react exports', () => {
+  test('exposes provider and hooks without rendering dependencies', () => {
+    expect(typeof PermissionsProvider).toBe('function');
+    expect(typeof usePermissions).toBe('function');
+    expect(typeof usePermission).toBe('function');
+  });
+});