@flighthq/permissions 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './permission';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './permission';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/permission.d.ts

@@ -0,0 +1,7 @@
+import type { PermissionBackend, PermissionName, PermissionState } from '@flighthq/types';
+export declare function createWebPermissionBackend(): PermissionBackend;
+export declare function getPermissionBackend(): PermissionBackend;
+export declare function getPermissionState(name: PermissionName): Promise<PermissionState>;
+export declare function requestPermission(name: PermissionName): Promise<PermissionState>;
+export declare function setPermissionBackend(backend: PermissionBackend | null): void;
+//# sourceMappingURL=permission.d.ts.map

package/dist/permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAO1F,wBAAgB,0BAA0B,IAAI,iBAAiB,CAS9D;AAGD,wBAAgB,oBAAoB,IAAI,iBAAiB,CAGxD;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAEjF;AAKD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAEhF;AAGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAE5E"}

package/dist/permission.js

@@ -0,0 +1,190 @@
+// Builds the default web backend. Query goes through navigator.permissions.query where supported;
+// request routes each name to its concrete web trigger (Notification.requestPermission, getUserMedia,
+// a one-shot geolocation read, navigator.storage.persist). Created lazily by getPermissionBackend —
+// nothing binds to the DOM at import time, so importing the package has no side effect. An absent
+// API, an unqueryable name, or a denied request resolves to a three-state sentinel, never a throw.
+export function createWebPermissionBackend() {
+    return {
+        getState(name) {
+            return readWebPermissionState(name);
+        },
+        request(name) {
+            return requestWebPermission(name);
+        },
+    };
+}
+// The active permission backend, lazily defaulting to the web backend. There is always a backend.
+export function getPermissionBackend() {
+    if (_backend === null)
+        _backend = createWebPermissionBackend();
+    return _backend;
+}
+// Resolves the current state of a named permission without prompting. Returns 'granted', 'denied',
+// or 'prompt' (not yet decided); 'prompt' is also the sentinel for an unqueryable name.
+export function getPermissionState(name) {
+    return getPermissionBackend().getState(name);
+}
+// Requests a named permission, triggering the OS prompt where the platform supports it. Resolves to
+// the resulting state; a name with no request path falls back to a plain state query, and a missing
+// API resolves to a sentinel rather than throwing.
+export function requestPermission(name) {
+    return getPermissionBackend().request(name);
+}
+// Installs a native host permission backend; pass null to fall back to a fresh lazy web default.
+export function setPermissionBackend(backend) {
+    _backend = backend;
+}
+let _backend = null;
+// Maps a PermissionName to its Permissions-API query descriptor name. The built-in names are already
+// valid descriptor names, so this is identity for them; an unlisted name is queried under itself.
+function getPermissionQueryDescriptorName(name) {
+    return _permissionQueryDescriptors[name] ?? name;
+}
+// The per-name fallback state when the Permissions API is absent or the name is unqueryable.
+// notifications is still readable synchronously via Notification.permission ('default' → 'prompt');
+// every other name resolves to the 'prompt' sentinel.
+function readWebFallbackPermissionState(name) {
+    if (name === 'notifications') {
+        const permission = getWebNotificationPermission();
+        if (permission !== null)
+            return permission === 'default' ? 'prompt' : permission;
+    }
+    return 'prompt';
+}
+async function readWebPermissionState(name) {
+    const permissions = getWebPermissions();
+    if (permissions !== null) {
+        try {
+            const status = await permissions.query({
+                name: getPermissionQueryDescriptorName(name),
+            });
+            return status.state;
+        }
+        catch {
+            // Unqueryable name or a rejected query — fall through to the per-name fallback.
+        }
+    }
+    return readWebFallbackPermissionState(name);
+}
+// Drives a one-shot geolocation read purely to observe grant/denial; the position itself is discarded.
+function requestWebGeolocationPermission() {
+    return new Promise((resolve) => {
+        const geolocation = getWebGeolocation();
+        if (geolocation === null || typeof geolocation.getCurrentPosition !== 'function') {
+            resolve('prompt');
+            return;
+        }
+        try {
+            geolocation.getCurrentPosition(() => resolve('granted'), () => resolve('denied'));
+        }
+        catch {
+            resolve('prompt');
+        }
+    });
+}
+// Prompts for camera ('video') or microphone ('audio') via getUserMedia, then stops the granted
+// tracks immediately — the prompt is the only thing wanted, not an open capture stream.
+async function requestWebMediaPermission(kind) {
+    const mediaDevices = getWebMediaDevices();
+    if (mediaDevices === null || typeof mediaDevices.getUserMedia !== 'function')
+        return 'prompt';
+    try {
+        const stream = await mediaDevices.getUserMedia(kind === 'video' ? { video: true } : { audio: true });
+        stopMediaStreamTracks(stream);
+        return 'granted';
+    }
+    catch {
+        return 'denied';
+    }
+}
+async function requestWebNotificationPermission() {
+    const notification = getWebNotification();
+    if (notification === null || typeof notification.requestPermission !== 'function')
+        return 'prompt';
+    try {
+        const result = await notification.requestPermission();
+        return result === 'default' ? 'prompt' : result;
+    }
+    catch {
+        return 'prompt';
+    }
+}
+async function requestWebPersistentStoragePermission() {
+    const storage = getWebStorageManager();
+    if (storage === null || typeof storage.persist !== 'function')
+        return 'prompt';
+    try {
+        return (await storage.persist()) ? 'granted' : 'prompt';
+    }
+    catch {
+        return 'prompt';
+    }
+}
+async function requestWebPermission(name) {
+    const router = _permissionRequestRouters[name];
+    if (router !== undefined)
+        return await router();
+    return await readWebPermissionState(name);
+}
+// Stops every track of a granted media stream, releasing the device. Guards a missing getTracks so a
+// stubbed or partial stream never throws.
+function stopMediaStreamTracks(stream) {
+    if (typeof stream.getTracks !== 'function')
+        return;
+    for (const track of stream.getTracks()) {
+        if (typeof track.stop === 'function')
+            track.stop();
+    }
+}
+function getWebGeolocation() {
+    if (typeof navigator === 'undefined')
+        return null;
+    return navigator.geolocation ?? null;
+}
+function getWebMediaDevices() {
+    if (typeof navigator === 'undefined')
+        return null;
+    return navigator.mediaDevices ?? null;
+}
+function getWebNotification() {
+    return typeof Notification !== 'undefined' ? Notification : null;
+}
+function getWebNotificationPermission() {
+    const notification = getWebNotification();
+    if (notification === null)
+        return null;
+    return notification.permission ?? null;
+}
+function getWebPermissions() {
+    if (typeof navigator === 'undefined')
+        return null;
+    const permissions = navigator.permissions ?? null;
+    if (permissions === null || typeof permissions.query !== 'function')
+        return null;
+    return permissions;
+}
+function getWebStorageManager() {
+    if (typeof navigator === 'undefined')
+        return null;
+    return navigator.storage ?? null;
+}
+const _permissionQueryDescriptors = {
+    camera: 'camera',
+    microphone: 'microphone',
+    geolocation: 'geolocation',
+    notifications: 'notifications',
+    'clipboard-read': 'clipboard-read',
+    'clipboard-write': 'clipboard-write',
+    'persistent-storage': 'persistent-storage',
+    push: 'push',
+    midi: 'midi',
+    'screen-wake-lock': 'screen-wake-lock',
+};
+const _permissionRequestRouters = {
+    camera: () => requestWebMediaPermission('video'),
+    microphone: () => requestWebMediaPermission('audio'),
+    geolocation: requestWebGeolocationPermission,
+    notifications: requestWebNotificationPermission,
+    'persistent-storage': requestWebPersistentStoragePermission,
+};
+//# sourceMappingURL=permission.js.map

package/dist/permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/permissions",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "OS-permission query/request over a swappable web/native backend (Permissions API + per-permission web triggers by default)",
+  "sideEffects": false
+}

package/src/permission.test.ts

@@ -0,0 +1,200 @@
+import type { PermissionBackend, PermissionName, PermissionState } from '@flighthq/types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createWebPermissionBackend,
+  getPermissionBackend,
+  getPermissionState,
+  requestPermission,
+  setPermissionBackend,
+} from './permission';
+
+// A recording mock backend: relays a fixed state and captures the last name each method saw.
+function fakeBackend(
+  state: PermissionState,
+): PermissionBackend & { lastGetState: PermissionName | null; lastRequest: PermissionName | null } {
+  const backend = {
+    lastGetState: null as PermissionName | null,
+    lastRequest: null as PermissionName | null,
+    async getState(name: PermissionName) {
+      backend.lastGetState = name;
+      return state;
+    },
+    async request(name: PermissionName) {
+      backend.lastRequest = name;
+      return state;
+    },
+  };
+  return backend;
+}
+
+function fakeStream(trackCount = 1): { stream: MediaStream; stopped: () => number } {
+  let stopped = 0;
+  const tracks = Array.from({ length: trackCount }, () => ({ stop: () => (stopped += 1) }));
+  const stream = { getTracks: () => tracks } as unknown as MediaStream;
+  return { stream, stopped: () => stopped };
+}
+
+afterEach(() => {
+  setPermissionBackend(null);
+  vi.unstubAllGlobals();
+});
+
+describe('createWebPermissionBackend', () => {
+  it('returns a backend with getState and request methods', () => {
+    const backend = createWebPermissionBackend();
+    expect(typeof backend.getState).toBe('function');
+    expect(typeof backend.request).toBe('function');
+  });
+
+  it('getState resolves the queried Permissions API state', async () => {
+    const query = vi.fn(async () => ({ state: 'granted' }));
+    vi.stubGlobal('navigator', { permissions: { query } });
+    const backend = createWebPermissionBackend();
+    expect(await backend.getState('camera')).toBe('granted');
+    expect(query).toHaveBeenCalledWith({ name: 'camera' });
+  });
+
+  it('getState maps clipboard names to their clipboard descriptor', async () => {
+    const query = vi.fn(async () => ({ state: 'prompt' }));
+    vi.stubGlobal('navigator', { permissions: { query } });
+    await createWebPermissionBackend().getState('clipboard-read');
+    expect(query).toHaveBeenCalledWith({ name: 'clipboard-read' });
+  });
+
+  it('getState falls back to Notification.permission when the Permissions API is absent', async () => {
+    vi.stubGlobal('navigator', {});
+    vi.stubGlobal('Notification', { permission: 'granted' });
+    expect(await createWebPermissionBackend().getState('notifications')).toBe('granted');
+  });
+
+  it('getState maps a default Notification permission to the prompt sentinel', async () => {
+    vi.stubGlobal('navigator', {});
+    vi.stubGlobal('Notification', { permission: 'default' });
+    expect(await createWebPermissionBackend().getState('notifications')).toBe('prompt');
+  });
+
+  it('getState returns the prompt sentinel for a non-notification name with no queryable state', async () => {
+    vi.stubGlobal('navigator', {});
+    expect(await createWebPermissionBackend().getState('geolocation')).toBe('prompt');
+  });
+
+  it('getState falls back when the query rejects', async () => {
+    const query = vi.fn(async () => {
+      throw new TypeError('unsupported');
+    });
+    vi.stubGlobal('navigator', { permissions: { query } });
+    vi.stubGlobal('Notification', { permission: 'denied' });
+    expect(await createWebPermissionBackend().getState('notifications')).toBe('denied');
+    expect(await createWebPermissionBackend().getState('midi')).toBe('prompt');
+  });
+
+  it('request(notifications) maps a granted result through', async () => {
+    vi.stubGlobal('Notification', { requestPermission: async () => 'granted' });
+    expect(await createWebPermissionBackend().request('notifications')).toBe('granted');
+  });
+
+  it('request(notifications) maps a default result to the prompt sentinel', async () => {
+    vi.stubGlobal('Notification', { requestPermission: async () => 'default' });
+    expect(await createWebPermissionBackend().request('notifications')).toBe('prompt');
+  });
+
+  it('request(camera) grants and stops the granted tracks immediately', async () => {
+    const { stream, stopped } = fakeStream(2);
+    const getUserMedia = vi.fn(async () => stream);
+    vi.stubGlobal('navigator', { mediaDevices: { getUserMedia } });
+    expect(await createWebPermissionBackend().request('camera')).toBe('granted');
+    expect(getUserMedia).toHaveBeenCalledWith({ video: true });
+    expect(stopped()).toBe(2);
+  });
+
+  it('request(microphone) requests an audio stream', async () => {
+    const { stream } = fakeStream();
+    const getUserMedia = vi.fn(async () => stream);
+    vi.stubGlobal('navigator', { mediaDevices: { getUserMedia } });
+    expect(await createWebPermissionBackend().request('microphone')).toBe('granted');
+    expect(getUserMedia).toHaveBeenCalledWith({ audio: true });
+  });
+
+  it('request(camera) denies when getUserMedia rejects', async () => {
+    const getUserMedia = vi.fn(async () => {
+      throw new DOMException('denied', 'NotAllowedError');
+    });
+    vi.stubGlobal('navigator', { mediaDevices: { getUserMedia } });
+    expect(await createWebPermissionBackend().request('camera')).toBe('denied');
+  });
+
+  it('request(camera) returns the prompt sentinel with no throw when the API is absent', async () => {
+    vi.stubGlobal('navigator', {});
+    expect(await createWebPermissionBackend().request('camera')).toBe('prompt');
+  });
+
+  it('request(geolocation) grants on a successful one-shot position read', async () => {
+    const getCurrentPosition = (success: () => void) => success();
+    vi.stubGlobal('navigator', { geolocation: { getCurrentPosition } });
+    expect(await createWebPermissionBackend().request('geolocation')).toBe('granted');
+  });
+
+  it('request(geolocation) denies when the position read errors', async () => {
+    const getCurrentPosition = (_success: () => void, error: () => void) => error();
+    vi.stubGlobal('navigator', { geolocation: { getCurrentPosition } });
+    expect(await createWebPermissionBackend().request('geolocation')).toBe('denied');
+  });
+
+  it('request(persistent-storage) grants when persist resolves true, prompts when false', async () => {
+    vi.stubGlobal('navigator', { storage: { persist: async () => true } });
+    expect(await createWebPermissionBackend().request('persistent-storage')).toBe('granted');
+    vi.stubGlobal('navigator', { storage: { persist: async () => false } });
+    expect(await createWebPermissionBackend().request('persistent-storage')).toBe('prompt');
+  });
+
+  it('request falls back to a state query for a name with no request path', async () => {
+    const query = vi.fn(async () => ({ state: 'granted' }));
+    vi.stubGlobal('navigator', { permissions: { query } });
+    expect(await createWebPermissionBackend().request('midi')).toBe('granted');
+    expect(query).toHaveBeenCalledWith({ name: 'midi' });
+  });
+});
+
+describe('getPermissionBackend', () => {
+  it('returns a lazily-created web default', () => {
+    expect(getPermissionBackend()).not.toBeNull();
+    expect(getPermissionBackend()).toBe(getPermissionBackend());
+  });
+
+  it('returns an installed backend', () => {
+    const backend = fakeBackend('granted');
+    setPermissionBackend(backend);
+    expect(getPermissionBackend()).toBe(backend);
+  });
+});
+
+describe('getPermissionState', () => {
+  it('dispatches to the active backend and relays the resolved state', async () => {
+    const backend = fakeBackend('denied');
+    setPermissionBackend(backend);
+    expect(await getPermissionState('camera')).toBe('denied');
+    expect(backend.lastGetState).toBe('camera');
+  });
+});
+
+describe('requestPermission', () => {
+  it('dispatches to the active backend and relays the resolved state', async () => {
+    const backend = fakeBackend('granted');
+    setPermissionBackend(backend);
+    expect(await requestPermission('microphone')).toBe('granted');
+    expect(backend.lastRequest).toBe('microphone');
+  });
+});
+
+describe('setPermissionBackend', () => {
+  it('installs a backend and restores a fresh distinct web default on null', () => {
+    const backend = fakeBackend('prompt');
+    setPermissionBackend(backend);
+    expect(getPermissionBackend()).toBe(backend);
+    setPermissionBackend(null);
+    const restored = getPermissionBackend();
+    expect(restored).not.toBe(backend);
+    expect(restored.getState).toBeInstanceOf(Function);
+  });
+});