node-mac-permissions - npm Package Compare versions

Comparing version 2.2.1 to 2.3.0

index.d.ts

 // Type definitions for node-mac-permissions
 // Project: node-mac-permissions
 
-export function askForCalendarAccess(): Promise<'authorized' | 'denied'>
-export function askForContactsAccess(): Promise<'authorized' | 'denied'>
-export function askForFoldersAccess(): Promise<'authorized' | 'denied'>
+export function askForAccessibilityAccess(): undefined
+export function askForCalendarAccess(): Promise<Omit<PermissionType, 'restricted'>>
+export function askForCameraAccess(): Promise<PermissionType>
+export function askForContactsAccess(): Promise<Omit<PermissionType, 'restricted'>>
+export function askForFoldersAccess(): Promise<Omit<PermissionType, 'restricted'>>
 export function askForFullDiskAccess(): undefined
-export function askForRemindersAccess(): Promise<'authorized' | 'denied'>
-export function askForCameraAccess(): Promise<'authorized' | 'denied' | 'restricted'>
-export function askForMicrophoneAccess(): Promise<'authorized' | 'denied' | 'restricted'>
-export function askForPhotosAccess(): Promise<'authorized' | 'denied' | 'restricted'>
-export function askForSpeechRecognitionAccess(): Promise<'authorized' | 'denied'>
+export function askForInputMonitoringAccess(): Promise<Omit<PermissionType, 'restricted'>>
+export function askForMicrophoneAccess(): Promise<PermissionType>
+export function askForPhotosAccess(accessType?: 'add-only' | 'read-write'): Promise<PermissionType>
+export function askForRemindersAccess(): Promise<Omit<PermissionType, 'restricted'>>
+export function askForSpeechRecognitionAccess(): Promise<Omit<PermissionType, 'restricted'>>
 export function askForScreenCaptureAccess(): undefined
-export function askForAccessibilityAccess(): undefined
-export function getAuthStatus(authType: AuthType): PermissionType
+export function getAuthStatus(authType: AuthType): PermissionType | 'not determined'
 
 export type AuthType =
+  | 'accessibility'
+  | 'bluetooth'
+  | 'calendar'
+  | 'camera'
   | 'contacts'
-  | 'calendar'
+  | 'full-disk-access'
+  | 'input-monitoring'
+  | 'location'
+  | 'microphone'
+  | 'music-library'
+  | 'photos-add-only'
+  | 'photos-read-write'
   | 'reminders'
-  | 'full-disk-access'
-  | 'camera'
-  | 'photos'
   | 'speech-recognition'
-  | 'microphone'
-  | 'accessibility'
-  | 'location'
   | 'screen'
 
-export type PermissionType = 'not determined' | 'denied' | 'authorized' | 'restricted'
+export type PermissionType =  'authorized' | 'denied' | 'restricted'

index.js

@@ -5,15 +5,17 @@ const permissions = require('bindings')('permissions.node')
   const validTypes = [
+    'accessibility',
+    'bluetooth',
+    'calendar',
+    'camera',
     'contacts',
-    'calendar',
-    'reminders',
     'full-disk-access',
-    'camera',
-    'photos',
-    'speech-recognition',
+    'input-monitoring',
+    'location',
     'microphone',
     'music-library',
-    'accessibility',
-    'location',
+    'photos-add-only',
+    'photos-read-write',
+    'reminders',
+    'speech-recognition',
     'screen',
-    'bluetooth',
   ]
@@ -38,16 +40,25 @@
 
+function askForPhotosAccess(accessLevel = 'add-only') {
+  if (!['add-only', 'read-write'].includes(accessLevel)) {
+    throw new TypeError(`${accessLevel} must be one of either 'add-only' or 'read-write'`)
+  }
+
+  return permissions.askForPhotosAccess.call(this, accessLevel)
+}
+
 module.exports = {
+  askForAccessibilityAccess: permissions.askForAccessibilityAccess,
   askForCalendarAccess: permissions.askForCalendarAccess,
+  askForCameraAccess: permissions.askForCameraAccess,
   askForContactsAccess: permissions.askForContactsAccess,
   askForFoldersAccess,
   askForFullDiskAccess: permissions.askForFullDiskAccess,
+  askForInputMonitoringAccess: permissions.askForInputMonitoringAccess,
   askForRemindersAccess: permissions.askForRemindersAccess,
-  askForCameraAccess: permissions.askForCameraAccess,
   askForMicrophoneAccess: permissions.askForMicrophoneAccess,
   askForMusicLibraryAccess: permissions.askForMusicLibraryAccess,
-  askForPhotosAccess: permissions.askForPhotosAccess,
+  askForPhotosAccess,
   askForSpeechRecognitionAccess: permissions.askForSpeechRecognitionAccess,
   askForScreenCaptureAccess: permissions.askForScreenCaptureAccess,
-  askForAccessibilityAccess: permissions.askForAccessibilityAccess,
   getAuthStatus,
 }

package.json

 {
   "name": "node-mac-permissions",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "A native node module to manage system permissions on macOS",
@@ -12,3 +12,4 @@ "main": "index.js",
     "format": "clang-format -i permissions.mm && prettier --write index.js",
-    "test": "./node_modules/.bin/mocha --reporter spec"
+    "test": "./node_modules/.bin/mocha --reporter spec",
+    "prepare": "husky install"
   },
@@ -37,15 +38,10 @@ "repository": {
   "devDependencies": {
-    "chai": "^4.2.0",
-    "clang-format": "^1.4.0",
-    "husky": "^4.3.0",
-    "lint-staged": "^10.5.3",
-    "mocha": "^8.2.1",
-    "node-gyp": "^7.1.2",
-    "prettier": "^2.2.1"
+    "chai": "^4.3.6",
+    "clang-format": "1.8.0",
+    "husky": "^8.0.1",
+    "lint-staged": "^12.4.1",
+    "mocha": "^10.0.0",
+    "node-gyp": "^9.0.0",
+    "prettier": "^2.6.2"
   },
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged"
-    }
-  },
   "lint-staged": {
@@ -59,3 +55,5 @@ "*.js": [
   },
-  "os": ["darwin"]
+  "os": [
+    "darwin"
+  ]
 }

README.md

@@ -6,2 +6,24 @@ [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
 
+### Table of Contents
+
+- [Overview](#overview)
+- [API](#api)
+  - [`permissions.getAuthStatus(type)`](#permissionsgetauthstatustype)
+  - [`permissions.askForContactsAccess()`](#permissionsaskforcontactsaccess)
+  - [`permissions.askForCalendarAccess()`](#permissionsaskforcalendaraccess)
+  - [`permissions.askForSpeechRecognitionAccess()`](#permissionsaskforspeechrecognitionaccess)
+  - [`permissions.askForRemindersAccess()`](#permissionsaskforremindersaccess)
+  - [`permissions.askForFoldersAccess(folder)`](#permissionsaskforfoldersaccessfolder)
+  - [`permissions.askForFullDiskAccess()`](#permissionsaskforfulldiskaccess)
+  - [`permissions.askForCameraAccess()`](#permissionsaskforcameraaccess)
+  - [`permissions.askForInputMonitoringAccess()`](#permissionsaskforinputmonitoringaccess)
+  - [`permissions.askForMicrophoneAccess()`](#permissionsaskformicrophoneaccess)
+  - [`permissions.askForMusicLibraryAccess()`](#permissionsaskformusiclibraryaccess)
+  - [`permissions.askForPhotosAccess()`](#permissionsaskforphotosaccess)
+  - [`permissions.askForScreenCaptureAccess()`](#permissionsaskforscreencaptureaccess)
+  - [`permissions.askForAccessibilityAccess()`](#permissionsaskforaccessibilityaccess)
+- [FAQ](#faq)
+
+## Overview
+
 ```js
@@ -13,14 +35,15 @@ $ npm i node-mac-permissions
 
+* Accessibility
+* Calendar
+* Camera
 * Contacts
 * Full Disk Access
-* Calendar
-* Reminders
-* Camera
+* Input Monitoring
+* Location
 * Microphone
 * Photos
-* Accessibility
-* Location
+* Protected Folders
+* Reminders
 * Screen Capture
 * Speech Recognition
-* Protected Folders
 
@@ -36,5 +59,5 @@ If you need to ask for permissions, your app must be allowed to ask for permission :
 
-## `permissions.getAuthStatus(type)`
+### `permissions.getAuthStatus(type)`
 
-* `type` String - The type of system component to which you are requesting access. Can be one of `accessibility`, `bluetooth`, `calendar`, `camera`, `contacts`, `full-disk-access`, `speech-recognition`, `location`, `microphone`, `photos`, `screen`, or `reminders`.
+* `type` String - The type of system component to which you are requesting access. Can be one of `accessibility`, `bluetooth`, `calendar`, `camera`, `contacts`, `full-disk-access`, `input-monitoring`, `location`, `microphone`,`photos`, `reminders`, `screen`, or `speech-recognition`.
 
@@ -50,11 +73,11 @@ Returns `String` - Can be one of `not determined`, `denied`, `authorized`, or `restricted`.
 * `authorized` - The application is authorized to access `type` data.
+* `limited` - The application is authorized for limited access to `type` data. Currently only applicable to the `photos` type.
 
 **Notes:**
-  * Access to `contacts` will always return a status of `authorized` prior to macOS 10.11, as the underlying API was not introduced until that version.
+  * Access to `bluetooth` will always return a status of `authorized` prior to macOS 10.15, as the underlying API was not introduced until that version.
   * Access to `camera` and `microphone` will always return a status of `authorized` prior to macOS 10.14, as the underlying API was not introduced until that version.
+  * Access to `input-monitoring` will always return a status of `authorized` prior to macOS 10.15, as the underlying API was not introduced until that version.
+  * Access to `music-library` will always return a status of `authorized` prior to macOS 11.0, as the underlying API was not introduced until that version.
   * Access to `screen` will always return a status of `authorized` prior to macOS 10.15, as the underlying API was not introduced until that version.
-  * Access to `photos` will always return a status of `authorized` prior to macOS 10.13, as the underlying API was not introduced until that version.
   * Access to `speech-recognition` will always return a status of `authorized` prior to macOS 10.15, as the underlying API was not introduced until that version.
-  * Access to `bluetooth` will always return a status of `authorized` prior to macOS 10.15, as the underlying API was not introduced until that version.
-  * Access to `music-library` will always return a status of `authorized` prior to macOS 11.0, as the underlying API was not introduced until that version.
 
@@ -69,10 +92,12 @@ Example:
   'contacts',
-  'reminders',
   'full-disk-access',
+  'input-monitoring',
   'location',
   'microphone',
   'music-library',
-  'photos',
+  'photos-add-only',
+  'photos-read-write',
+  'reminders',
+  'speech-recognition',
   'screen',
-  'speech-recognition'
 ]
@@ -86,3 +111,3 @@
 
-## `permissions.askForContactsAccess()`
+### `permissions.askForContactsAccess()`
 
@@ -98,4 +123,2 @@ Returns `Promise<String>` - Whether or not the request succeeded or failed; can be `authorized` or `denied`.
 
-**Note:** `status` will be resolved back as `authorized` prior to macOS 10.11, as the underlying API was not introduced until that version.
-
 Example:
@@ -110,3 +133,3 @@ ```js
 
-## `permissions.askForCalendarAccess()`
+### `permissions.askForCalendarAccess()`
 
@@ -124,5 +147,5 @@ Returns `Promise<String>` - Whether or not the request succeeded or failed; can be `authorized` or `denied`.
 
-## `permissions.askForSpeechRecognitionAccess()`
+### `permissions.askForSpeechRecognitionAccess()`
 
-Returns `Promise<String>` - Whether or not the request succeeded or failed; can be `authorized` or `denied`.
+Returns `Promise<String>` - Whether or not the request succeeded or failed; can be `authorized`, `denied`, or `restricted`.
 
@@ -133,2 +156,3 @@ Checks the authorization status for Speech Recognition access. If the status check returns:
 * `denied` - The `Security & Privacy` System Preferences window is opened with the Speech Recognition privacy key highlighted. On open of the `Security & Privacy` window, the Promise is resolved as `denied`.
+* `restricted` - The Promise is resolved as `restricted`.
 
@@ -153,3 +177,3 @@ Your app must provide an explanation for its use of Speech Recognition using the `NSSpeechRecognitionUsageDescription` `Info.plist` key;
 
-## `permissions.askForRemindersAccess()`
+### `permissions.askForRemindersAccess()`
 
@@ -167,3 +191,3 @@ Returns `Promise<String>` - Whether or not the request succeeded or failed; can be `authorized` or `denied`.
 
-## `permissions.askForFoldersAccess(folder)`
+### `permissions.askForFoldersAccess(folder)`
 
@@ -199,3 +223,3 @@ * `type` String - The folder to which you are requesting access. Can be one of `desktop`, `documents`, or `downloads`.
 
-## `permissions.askForFullDiskAccess()`
+### `permissions.askForFullDiskAccess()`
 
@@ -212,4 +236,11 @@ There is no API for programmatically requesting Full Disk Access on macOS at this time, and so calling this method will trigger opening of System Preferences at the Full Disk pane of Security and Privacy.
 
-## `permissions.askForCameraAccess()`
+If you would like your app to pop up a dialog requesting full disk access when your app attempts to access protected resources, you should add the `NSSystemAdministrationUsageDescription` key to your `Info.plist`:
 
+```
+<key>NSSystemAdministrationUsageDescription</key>
+<string>Your reason for wanting Full Disk Access</string>
+```
+
+### `permissions.askForCameraAccess()`
+
 Returns `Promise<String>` - Current permission status; can be `authorized`, `denied`, or `restricted`.
@@ -244,4 +275,26 @@
 
-## `permissions.askForMicrophoneAccess()`
+### `permissions.askForInputMonitoringAccess()`
 
+Returns `Promise<String>` - Current permission status; can be `authorized` or `denied`.
+
+Checks the authorization status for input monitoring access. If the status check returns:
+
+* `not determined` - A dialog will be displayed directing the user to the `Security & Privacy` System Preferences window , where the user can approve your app to monitor keyboard events in the background. The Promise is resolved as `denied`.
+* `denied` - The `Security & Privacy` System Preferences window is opened with the Input Monitoring privacy key highlighted. On open of the `Security & Privacy` window, the Promise is resolved as `denied`.
+
+**Note:**
+
+- `status` will be resolved back as `authorized` prior to macOS 10.15, as the underlying API was not introduced until that version.
+
+Example:
+```js
+const { askForInputMonitoringAccess } = require('node-mac-permissions')
+
+askForInputMonitoringAccess().then(status => {
+  console.log(`Access to Input Monitoring is ${status}`)
+})
+```
+
+### `permissions.askForMicrophoneAccess()`
+
 Returns `Promise<String>` - Current permission status; can be `authorized`, `denied`, or `restricted`.
@@ -276,5 +329,5 @@
 
-## `permissions.askForMusicLibraryAccess()`
+### `permissions.askForMusicLibraryAccess()`
 
-Returns `Promise<String>` - Whether or not the request succeeded or failed; can be `authorized` or `denied`.
+Returns `Promise<String>` - Whether or not the request succeeded or failed; can be `authorized`, `denied`, or `restricted`.
 
@@ -305,4 +358,6 @@ * `not determined` - The Music Library access authorization will prompt the user to authorize or deny. The Promise is resolved after the user selection with either `authorized` or `denied`.
 
-## `permissions.askForPhotosAccess()`
+### `permissions.askForPhotosAccess([accessLevel])`
 
+* `accessLevel` String (optional) - The access level being requested of Photos. Can be either `add-only` or `read-write`. Only available on macOS 11 or higher.
+
 Returns `Promise<String>` - Current permission status; can be `authorized`, `denied`, or `restricted`.
@@ -316,5 +371,12 @@
 
-Your app must provide an explanation for its use of the photo library using the `NSPhotoLibraryUsageDescription` `Info.plist` key.
+Your app must provide an explanation for its use of the photo library using either the `NSPhotoLibraryUsageDescription` or the `NSPhotoLibraryAddUsageDescription` `Info.plist` key.
 
+For requesting add-only access to the user’s photo library:
 ```
+<key>NSPhotoLibraryAddUsageDescription</key>
+<string>Your reason for wanting to access Photos</string>
+```
+
+For requesting read/write access to the user’s photo library:
+```
 <key>NSPhotoLibraryUsageDescription</key>
@@ -326,4 +388,5 @@ <string>Your reason for wanting to access Photos</string>
 
-- `status` will be resolved back as `authorized` prior to macOS 10.13, as the underlying API was not introduced until that version.
+You should add the `PHPhotoLibraryPreventAutomaticLimitedAccessAlert` key with a Boolean value of `YES` to your app’s `Info.plist` file to prevent the system from automatically presenting the limited library selection prompt. See [`PHAuthorizationStatusLimited`](https://developer.apple.com/documentation/photokit/phauthorizationstatus/phauthorizationstatuslimited?language=objc) for more information.
 
+
 Example:
@@ -339,3 +402,3 @@
 
-## `permissions.askForScreenCaptureAccess()`
+### `permissions.askForScreenCaptureAccess()`
 
@@ -352,3 +415,3 @@ There is no API for programmatically requesting Screen Capture on macOS at this time, and so calling this method will trigger opening of System Preferences at the Screen Capture pane of Security and Privacy.
 
-## `permissions.askForAccessibilityAccess()`
+### `permissions.askForAccessibilityAccess()`
 
@@ -355,0 +418,0 @@ There is no API for programmatically requesting Accessibility access on macOS at this time, and so calling this method will trigger opening of System Preferences at the Accessibility pane of Security and Privacy.

test/module.spec.js

@@ -14,13 +14,16 @@ const { expect } = require('chai')
       const types = [
+        'accessibility',
+        'bluetooth',
+        'calendar',
+        'camera',
         'contacts',
-        'calendar',
-        'reminders',
         'full-disk-access',
-        'camera',
-        'photos',
-        'speech-recognition',
+        'input-monitoring',
+        'location',
         'microphone',
         'music-library',
-        'accessibility',
-        'location',
+        'photos-add-only',
+        'photos-read-write',
+        'reminders',
+        'speech-recognition',
         'screen',
@@ -27,0 +30,0 @@ ]

No alert changes

Improved metrics

Total package byte prevSize

57489

increased by12.71%

Number of package files

12

increased by9.09%

Lines of code

127

increased by15.45%

Number of lines in readme file

469

increased by15.52%

No dependency changes