@codeleap/permissions 7.0.0 → 7.0.1

package/dist/Permission.js

@@ -0,0 +1,133 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { globalState } from '@codeleap/store';
+import { TypeGuards } from '@codeleap/types';
+import { logger } from '@codeleap/logger';
+/**
+ * Represents a single named permission with persistent reactive state.
+ *
+ * State is backed by `globalState` and persisted under the key
+ * `"permissions-<name>"`, so the last-known status survives page reloads or
+ * app restarts without an extra async check.
+ *
+ * The status machine has one sticky transition: once a permission reaches
+ * `"blocked"` it will never regress to `"denied"` via {@link check} — because
+ * on most platforms a blocked permission can only be cleared through the OS
+ * settings screen, not by a subsequent API call.
+ */
+export class Permission {
+    /**
+     * Converts a raw status string into a structured descriptor object.
+     * Prefer this over equality checks scattered across call sites so that
+     * adding a new status variant only requires updating this method.
+     */
+    static is(status) {
+        return {
+            value: status,
+            isGranted: status === 'granted',
+            isLimited: status === 'limited',
+            isDenied: status === 'denied',
+            isBlocked: status === 'blocked',
+        };
+    }
+    /**
+     * Snapshot of the persisted status.  Returns `null` until the first
+     * `check()` or `request()` resolves.
+     */
+    get value() {
+        return this.state.get();
+    }
+    get isGranted() {
+        return Permission.is(this.value).isGranted;
+    }
+    get isLimited() {
+        return Permission.is(this.value).isLimited;
+    }
+    get isDenied() {
+        return Permission.is(this.value).isDenied;
+    }
+    get isBlocked() {
+        return Permission.is(this.value).isBlocked;
+    }
+    constructor(options) {
+        const { name, config, check, request } = options;
+        this.state = globalState(null, { persistKey: 'permissions-' + name });
+        this.name = name;
+        this.config = config;
+        this.checkStatus = check;
+        this.requestStatus = request;
+    }
+    log(msg, obj) {
+        if (!Permission.logsEnabled)
+            return;
+        logger.log(`(Permission) ${this.name} -> ${msg}`, obj);
+    }
+    /**
+     * Directly overwrites the stored status without going through the native
+     * check or request flow.  Useful when the status is already known from an
+     * external source (e.g. a push-notification token registration callback).
+     */
+    set(newStatus) {
+        this.state.set(newStatus);
+    }
+    /**
+     * React hook that subscribes a component to this permission's reactive
+     * state.  Re-renders whenever the status changes.
+     */
+    use() {
+        return this.state.use();
+    }
+    /**
+     * Queries the native status without showing a user-facing prompt.
+     *
+     * If the platform returns `"denied"` but the stored value is already
+     * `"blocked"`, the `"blocked"` value is preserved.  This guards against
+     * platforms that report a previously-blocked permission as merely denied on
+     * subsequent queries, which would incorrectly allow a re-request attempt.
+     */
+    check() {
+        return __awaiter(this, void 0, void 0, function* () {
+            let status = yield this.checkStatus();
+            if (status === 'denied' && this.value === 'blocked') {
+                status = this.value;
+            }
+            const update = status != this.value;
+            if (update && TypeGuards.isString(status)) {
+                this.set(status);
+            }
+            this.log('check', { status, update });
+            return status;
+        });
+    }
+    /**
+     * Triggers an interactive permission prompt (may show a system dialog) and
+     * updates stored state when the result differs from the current value.
+     * Only call this in direct response to a user action; invoking it
+     * speculatively or on mount will fail silently on most platforms.
+     */
+    request() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const status = yield this.requestStatus();
+            const update = status != this.value;
+            if (update && TypeGuards.isString(status)) {
+                this.set(status);
+            }
+            this.log('request', { status, update });
+            return status;
+        });
+    }
+}
+/**
+ * Set to `true` to enable verbose permission logs via `@codeleap/logger`.
+ * Applies to every `Permission` instance; toggling at runtime takes effect
+ * immediately.
+ */
+Permission.logsEnabled = false;
+//# 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/dist/PermissionsManager.js

@@ -0,0 +1,133 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Permission } from './Permission';
+import { logger } from '@codeleap/logger';
+/**
+ * Registry and coordinator for a fixed set of named permissions.
+ *
+ * Instantiating this class immediately calls `checkAll()` in the background so
+ * that every permission's cached status is refreshed before the first render.
+ * The `requester` callback is the single authoritative place to implement any
+ * pre-prompt logic (e.g. showing an educational interstitial before the OS
+ * dialog appears).
+ */
+export class PermissionsManager {
+    get keys() {
+        return Object.keys(this.permissions);
+    }
+    /**
+     * Snapshot of all registered permissions' current statuses.  Values reflect
+     * whatever is in persistent state at the moment of access — call
+     * `checkAll()` first if you need fresh data from the platform.
+     */
+    get values() {
+        const values = {};
+        this.forEach(permission => {
+            values[permission.name] = permission.value;
+        });
+        return values;
+    }
+    forEach(callbackFn) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const permissionName in this.permissions) {
+                const permission = this.permissions[permissionName];
+                callbackFn(permission);
+            }
+        });
+    }
+    constructor(requester, permissions) {
+        this.permissions = {};
+        for (const permission in permissions) {
+            const permissionConfig = permissions[permission];
+            const permissionClass = new Permission(Object.assign(Object.assign({}, permissionConfig), { name: permission }));
+            this.permissions[permission] = permissionClass;
+        }
+        this.requester = requester;
+        this.checkAll();
+    }
+    log(msg, ...args) {
+        if (!Permission.logsEnabled)
+            return;
+        logger.log(`(Permissions) -> ${msg}`, ...(args !== null && args !== void 0 ? args : ''));
+    }
+    /**
+     * React hook that subscribes a component to the reactive state of a single
+     * named permission.  Re-renders whenever that permission's status changes.
+     */
+    use(permissionName) {
+        return this.permissions[permissionName].use();
+    }
+    /**
+     * Requests a single permission through the manager's `requester` callback.
+     * The result passes through {@link Permission.is} so callers get a
+     * structured descriptor rather than a raw string.
+     *
+     * Note: this bypasses `Permission.request()` on the individual instance —
+     * the `requester` callback owns the full flow, including any pre-prompt UI.
+     */
+    request(permissionName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const permission = this.permissions[permissionName];
+            const status = yield this.requester(permission);
+            return Permission.is(status);
+        });
+    }
+    /**
+     * Silently queries a single permission's current status (no system dialog).
+     * Returns a structured descriptor via {@link Permission.is}.
+     */
+    check(permissionName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const permission = this.permissions[permissionName];
+            const status = yield permission.check();
+            return Permission.is(status);
+        });
+    }
+    /**
+     * Requests multiple permissions sequentially.  Requests are serial, not
+     * parallel, to avoid triggering concurrent system dialogs which may be
+     * rejected or silently dropped on some platforms.
+     */
+    requestMany(permissionsNames) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const status = {};
+            for (const permissionName of permissionsNames) {
+                status[permissionName] = yield this.request(permissionName);
+            }
+            return status;
+        });
+    }
+    /**
+     * Silently queries multiple permissions sequentially.  Serial execution
+     * ensures consistent ordering and avoids race conditions in the underlying
+     * state store.
+     */
+    checkMany(permissionsNames) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const status = {};
+            for (const permissionName of permissionsNames) {
+                status[permissionName] = yield this.check(permissionName);
+            }
+            return status;
+        });
+    }
+    /**
+     * Silently refreshes every registered permission.  Called automatically
+     * during construction so that cached statuses are up to date before the
+     * first render without requiring the caller to await initialization.
+     */
+    checkAll() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.log('checkAll');
+            return yield this.checkMany(this.keys);
+        });
+    }
+}
+//# sourceMappingURL=PermissionsManager.js.map

package/dist/PermissionsManager.js.map

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

package/dist/globals.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=globals.js.map

package/dist/globals.js.map

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

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './PermissionsManager';
+export * from './Permission';
+export * from './types';
+export * from './globals';
+//# 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,sBAAsB,CAAA;AACpC,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codeleap/permissions",
-  "version": "7.0.0",
-  "main": "src/index.ts",
+  "version": "7.0.1",
+  "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
@@ -22,10 +22,10 @@
     "directory": "packages/permissions"
   },
   "devDependencies": {
-    "@codeleap/config": "7.0.0",
-    "@codeleap/logger": "7.0.0",
-    "@codeleap/store": "7.0.0",
-    "@codeleap/types": "7.0.0",
+    "@codeleap/config": "7.0.1",
+    "@codeleap/logger": "7.0.1",
+    "@codeleap/store": "7.0.1",
+    "@codeleap/types": "7.0.1",
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
@@ -33,9 +33,9 @@
     "typecheck": "bun tsc --noEmit -p ./tsconfig.json"
   },
   "peerDependencies": {
-    "@codeleap/store": "7.0.0",
-    "@codeleap/types": "7.0.0",
-    "@codeleap/logger": "7.0.0",
+    "@codeleap/store": "7.0.1",
+    "@codeleap/types": "7.0.1",
+    "@codeleap/logger": "7.0.1",
     "typescript": "5.5.2"
   }
 }