Skip to content

Commit a158d8a

Browse files
codebyterecodebytere
committed
feat: add permissions.askForAppleEventsAccess()
1 parent 69ef9e7 commit a158d8a

File tree

4 files changed

+139
-68
lines changed

4 files changed

+139
-68
lines changed

‎README.md‎

Lines changed: 53 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
- [Overview](#overview)
99
- [API](#api)
1010
- [`permissions.getAuthStatus(type)`](#permissionsgetauthstatustype)
11+
- [`permissions.askForAccessibilityAccess()`](#permissionsaskforaccessibilityaccess)
12+
- [`permissions.askForAppleEventsAccess()`](#permissionsaskforappleeventsaccesstargetappbundleid)
1113
- [`permissions.askForContactsAccess()`](#permissionsaskforcontactsaccess)
1214
- [`permissions.askForCalendarAccess([accessLevel])`](#permissionsaskforcalendaraccessaccesslevel)
1315
- [`permissions.askForSpeechRecognitionAccess()`](#permissionsaskforspeechrecognitionaccess)
@@ -21,7 +23,6 @@
2123
- [`permissions.askForMusicLibraryAccess()`](#permissionsaskformusiclibraryaccess)
2224
- [`permissions.askForPhotosAccess([accessLevel])`](#permissionsaskforphotosaccessaccesslevel)
2325
- [`permissions.askForScreenCaptureAccess([openPreferences])`](#permissionsaskforscreencaptureaccessopenpreferences)
24-
- [`permissions.askForAccessibilityAccess()`](#permissionsaskforaccessibilityaccess)
2526
- [FAQ](#faq)
2627

2728
## Overview
@@ -32,19 +33,20 @@ npm i node-mac-permissions
3233

3334
This native Node.js module allows you to manage an app's access to:
3435

35-
* Accessibility
36-
* Calendar
37-
* Camera
38-
* Contacts
39-
* Full Disk Access
40-
* Input Monitoring
41-
* Location
42-
* Microphone
43-
* Photos
44-
* Protected Folders
45-
* Reminders
46-
* Screen Capture
47-
* Speech Recognition
36+
- Apple Events
37+
- Accessibility
38+
- Calendar
39+
- Camera
40+
- Contacts
41+
- Full Disk Access
42+
- Input Monitoring
43+
- Location
44+
- Microphone
45+
- Photos
46+
- Protected Folders
47+
- Reminders
48+
- Screen Capture
49+
- Speech Recognition
4850

4951
If you need to ask for permissions, your app must be allowed to ask for permission :
5052

@@ -57,7 +59,7 @@ If you're using macOS 12.3 or newer, you'll need to ensure you have Python insta
5759

5860
### `permissions.getAuthStatus(type)`
5961

60-
- `type` String - The type of system component to which you are requesting access. Can be one of `accessibility`, `apple-events`, `bluetooth`, `calendar`, `camera`, `contacts`, `full-disk-access`, `input-monitoring`, `location`, `microphone`,`photos`, `reminders`, `screen`, or `speech-recognition`.
62+
- `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`.
6163

6264
Returns `String` - Can be one of `not determined`, `denied`, `authorized`, or `restricted`.
6365

@@ -107,6 +109,42 @@ for (const type of types) {
107109
}
108110
```
109111

112+
### `permissions.askForAccessibilityAccess()`
113+
114+
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.
115+
116+
Example:
117+
118+
```js
119+
const { askForAccessibilityAccess } = require('node-mac-permissions')
120+
121+
askForAccessibilityAccess()
122+
```
123+
124+
### `permissions.askForAppleEventsAccess(targetAppBundleId[, shouldPrompt])`
125+
126+
- `targetAppBundleId` String - The bundle identifier for the app you're targeting to send Apple Events to.
127+
- `shouldPrompt` Boolean (optional) - If this is `false`, the current authorization status will be returned for the provided `targetAppBundleId`. Default is true.
128+
129+
Returns `Promise<String>` - Whether or not the request succeeded or failed; can be `authorized`, `denied`, or `not determined`.
130+
131+
Your app’s `Info.plist` file must provide a value for the `NSAppleEventsUsageDescription` key that explains to the user why your app is requesting the ability to send Apple Events.
132+
133+
```plist
134+
<key>NSAppleEventsUsageDescription</key>
135+
<string>Your reason for wanting the ability to send Apple Events</string>
136+
```
137+
138+
Example:
139+
140+
```js
141+
const { askForAppleEventsAccess } = require('node-mac-permissions')
142+
143+
askForAppleEventsAccess('com.apple.finder').then(status => {
144+
console.log(`Access to send Apple Events is ${status}`)
145+
})
146+
```
147+
110148
### `permissions.askForContactsAccess()`
111149

112150
Returns `Promise<String>` - Whether or not the request succeeded or failed; can be `authorized` or `denied`.
@@ -447,18 +485,6 @@ const { askForScreenCaptureAccess } = require('node-mac-permissions')
447485
askForScreenCaptureAccess()
448486
```
449487

450-
### `permissions.askForAccessibilityAccess()`
451-
452-
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.
453-
454-
Example:
455-
456-
```js
457-
const { askForAccessibilityAccess } = require('node-mac-permissions')
458-
459-
askForAccessibilityAccess()
460-
```
461-
462488
## FAQ
463489

464490
Q. I'm seeing an error like the following when using webpack:

‎index.d.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// Type definitions for node-mac-permissions
22
// Project: node-mac-permissions
33

4+
export function askForAppleEventsAccess(): Promise<Omit<PermissionType, 'restricted'>>
45
export function askForAccessibilityAccess(): undefined
56
export function askForCalendarAccess(accessType?: 'write-only' | 'full'): Promise<Omit<PermissionType, 'restricted'>>
67
export function askForCameraAccess(): Promise<PermissionType>

‎index.js‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,20 @@ function askForInputMonitoringAccess(accessLevel = 'listen') {
7777
return permissions.askForInputMonitoringAccess.call(this, accessLevel)
7878
}
7979

80+
function askForAppleEventsAccess(targetAppBundleId, shouldPrompt = true) {
81+
if (typeof targetAppBundleId !== 'string') {
82+
throw new TypeError('targetAppBundleId must be a string')
83+
}
84+
85+
if (typeof shouldPrompt !== 'boolean') {
86+
throw new TypeError('shouldPrompt must be a boolean')
87+
}
88+
89+
return permissions.askForAppleEventsAccess.call(this, targetAppBundleId, shouldPrompt)
90+
}
91+
8092
module.exports = {
93+
askForAppleEventsAccess: askForAppleEventsAccess,
8194
askForAccessibilityAccess: permissions.askForAccessibilityAccess,
8295
askForCalendarAccess: askForCalendarAccess,
8396
askForLocationAccess: askForLocationAccess,

‎permissions.mm‎

Lines changed: 72 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,22 @@
2323
const std::string kNotDetermined{"not determined"};
2424
const std::string kLimited{"limited"};
2525

26+
// Check if a bundle ID is valid (i.e., corresponds to an installed app)
27+
bool IsValidBundleID(NSString *bundleID) {
28+
if (!bundleID)
29+
return false;
30+
31+
CFArrayRef appURLs = LSCopyApplicationURLsForBundleIdentifier(
32+
(__bridge CFStringRef)bundleID, NULL);
33+
34+
if (appURLs) {
35+
CFRelease(appURLs);
36+
return true;
37+
}
38+
39+
return false;
40+
}
41+
2642
std::string CheckFileAccessLevel(NSString *path) {
2743
int fd = open([path cStringUsingEncoding:kCFStringEncodingUTF8], O_RDONLY);
2844
if (fd != -1) {
@@ -227,30 +243,6 @@ bool HasOpenSystemPreferencesDialog() {
227243
}
228244
}
229245

230-
// Returns a status indicating whether the user has authorized Apple Events.
231-
std::string AppleEventsAuthStatus(Napi::Env env) {
232-
AEDesc target_app = {typeNull, NULL};
233-
OSStatus status = AECreateDesc(typeApplicationBundleID, "com.apple.finder",
234-
strlen("com.apple.finder"), &target_app);
235-
if (status != noErr) {
236-
std::string err_msg = "Failed to query for Apple Events access";
237-
Napi::Error::New(env, err_msg).ThrowAsJavaScriptException();
238-
return kNotDetermined;
239-
}
240-
241-
status = AEDeterminePermissionToAutomateTarget(&target_app, kCoreEventClass,
242-
kAEOpenDocuments, false);
243-
244-
AEDisposeDesc(&target_app);
245-
246-
// User prompt has not yet been shown.
247-
if (status == errAEEventWouldRequireUserConsent) {
248-
return kNotDetermined;
249-
}
250-
251-
return status == noErr ? kAuthorized : kDenied;
252-
}
253-
254246
// Returns a status indicating whether the user has authorized Apple Music
255247
// Library access.
256248
std::string MusicLibraryAuthStatus() {
@@ -452,13 +444,51 @@ bool HasOpenSystemPreferencesDialog() {
452444
auth_status = MusicLibraryAuthStatus();
453445
} else if (type == "input-monitoring") {
454446
auth_status = InputMonitoringAuthStatus();
455-
} else if (type == "apple-events") {
456-
auth_status = AppleEventsAuthStatus(env);
457447
}
458448

459449
return Napi::Value::From(env, auth_status);
460450
}
461451

452+
// Request Apple Events access.
453+
Napi::Promise AskForAppleEventsAccess(const Napi::CallbackInfo &info) {
454+
Napi::Env env = info.Env();
455+
Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(env);
456+
457+
std::string bundle_id = info[0].As<Napi::String>().Utf8Value();
458+
bool should_prompt = info[1].As<Napi::Boolean>().Value() ? true : false;
459+
460+
if (IsValidBundleID([NSString stringWithUTF8String:bundle_id.c_str()])) {
461+
std::string err_msg = "Bundle identifier: " + bundle_id + " is not valid";
462+
deferred.Reject(Napi::String::New(env, err_msg));
463+
return deferred.Promise();
464+
}
465+
466+
AEDesc target_app = {typeNull, NULL};
467+
OSStatus status = AECreateDesc(typeApplicationBundleID, bundle_id.c_str(),
468+
bundle_id.length(), &target_app);
469+
if (status != noErr) {
470+
std::string err_msg = "Failed to query for Apple Events access";
471+
deferred.Reject(Napi::String::New(env, err_msg));
472+
return deferred.Promise();
473+
}
474+
475+
status = AEDeterminePermissionToAutomateTarget(
476+
&target_app, kCoreEventClass, kAEOpenDocuments, should_prompt);
477+
478+
AEDisposeDesc(&target_app);
479+
480+
// User prompt has not yet been shown or it was cancelled.
481+
if (status == errAEEventWouldRequireUserConsent ||
482+
status == userCanceledErr) {
483+
deferred.Resolve(Napi::String::New(env, kNotDetermined));
484+
} else {
485+
deferred.Resolve(
486+
Napi::String::New(env, status == noErr ? kAuthorized : kDenied));
487+
}
488+
489+
return deferred.Promise();
490+
}
491+
462492
// Request access to various protected folders on the system.
463493
Napi::Promise AskForFoldersAccess(const Napi::CallbackInfo &info) {
464494
Napi::Env env = info.Env();
@@ -821,37 +851,38 @@ void AskForAccessibilityAccess(const Napi::CallbackInfo &info) {
821851

822852
// Initializes all functions exposed to JS
823853
Napi::Object Init(Napi::Env env, Napi::Object exports) {
824-
exports.Set(Napi::String::New(env, "getAuthStatus"),
825-
Napi::Function::New(env, GetAuthStatus));
826-
exports.Set(Napi::String::New(env, "askForContactsAccess"),
827-
Napi::Function::New(env, AskForContactsAccess));
854+
exports.Set(Napi::String::New(env, "askForAccessibilityAccess"),
855+
Napi::Function::New(env, AskForAccessibilityAccess));
856+
exports.Set(Napi::String::New(env, "askForAppleEventsAccess"),
857+
Napi::Function::New(env, AskForAppleEventsAccess));
828858
exports.Set(Napi::String::New(env, "askForCalendarAccess"),
829859
Napi::Function::New(env, AskForCalendarAccess));
830-
exports.Set(Napi::String::New(env, "askForRemindersAccess"),
831-
Napi::Function::New(env, AskForRemindersAccess));
860+
exports.Set(Napi::String::New(env, "askForCameraAccess"),
861+
Napi::Function::New(env, AskForCameraAccess));
862+
exports.Set(Napi::String::New(env, "askForContactsAccess"),
863+
Napi::Function::New(env, AskForContactsAccess));
832864
exports.Set(Napi::String::New(env, "askForFoldersAccess"),
833865
Napi::Function::New(env, AskForFoldersAccess));
834866
exports.Set(Napi::String::New(env, "askForFullDiskAccess"),
835867
Napi::Function::New(env, AskForFullDiskAccess));
836-
exports.Set(Napi::String::New(env, "askForCameraAccess"),
837-
Napi::Function::New(env, AskForCameraAccess));
868+
exports.Set(Napi::String::New(env, "askForInputMonitoringAccess"),
869+
Napi::Function::New(env, AskForInputMonitoringAccess));
838870
exports.Set(Napi::String::New(env, "askForLocationAccess"),
839871
Napi::Function::New(env, AskForLocationAccess));
840872
exports.Set(Napi::String::New(env, "askForMicrophoneAccess"),
841873
Napi::Function::New(env, AskForMicrophoneAccess));
842874
exports.Set(Napi::String::New(env, "askForMusicLibraryAccess"),
843875
Napi::Function::New(env, AskForMusicLibraryAccess));
844-
exports.Set(Napi::String::New(env, "askForSpeechRecognitionAccess"),
845-
Napi::Function::New(env, AskForSpeechRecognitionAccess));
846876
exports.Set(Napi::String::New(env, "askForPhotosAccess"),
847877
Napi::Function::New(env, AskForPhotosAccess));
878+
exports.Set(Napi::String::New(env, "askForRemindersAccess"),
879+
Napi::Function::New(env, AskForRemindersAccess));
848880
exports.Set(Napi::String::New(env, "askForScreenCaptureAccess"),
849881
Napi::Function::New(env, AskForScreenCaptureAccess));
850-
exports.Set(Napi::String::New(env, "askForAccessibilityAccess"),
851-
Napi::Function::New(env, AskForAccessibilityAccess));
852-
exports.Set(Napi::String::New(env, "askForInputMonitoringAccess"),
853-
Napi::Function::New(env, AskForInputMonitoringAccess));
854-
882+
exports.Set(Napi::String::New(env, "askForSpeechRecognitionAccess"),
883+
Napi::Function::New(env, AskForSpeechRecognitionAccess));
884+
exports.Set(Napi::String::New(env, "getAuthStatus"),
885+
Napi::Function::New(env, GetAuthStatus));
855886
return exports;
856887
}
857888

0 commit comments

Comments
 (0)