feat: add explicit contact request function

Author: codebytere

README.md

@@ -11,7 +11,7 @@ $ npm i node-mac-contacts
 
 This Native Node Module allows you to create, read, update, and delete contact from users' contacts databases on macOS.
 
-All methods invoking the [CNContactStore](https://developer.apple.com/documentation/contacts/cncontactstore) will require authorization, which will be requested the first time the functions themselves are invoked. You can verify authorization status with `contacts.getAuthStatus()` as outlined below.
+All methods invoking the [CNContactStore](https://developer.apple.com/documentation/contacts/cncontactstore) will require authorization, which you can request from users with the `requestAccess` method. You can verify authorization status with `contacts.getAuthStatus()` as outlined below.
 
 In your app, you should put the reason you're requesting to manipulate user's contacts database in your `Info.plist` like so:
 
@@ -22,6 +22,14 @@ In your app, you should put the reason you're requesting to manipulate user's co
 
 ## API
 
+### `contacts.requestAccess()`
+
+Returns `Promise<String>` - Can be one of 'Denied', 'Authorized'.
+
+Requests access to the [CNContactStore](https://developer.apple.com/documentation/contacts/cncontactstore) via a dialog presented to the user.
+
+If the user has previously denied the request, this method will open the Contacts pane within the Privacy section of System Preferences.
+
 ### `contacts.getAuthStatus()`
 
 Returns `String` - Can be one of 'Not Determined', 'Denied', 'Authorized', or 'Restricted'.

contacts.mm

@@ -1,3 +1,4 @@
+#import <AppKit/AppKit.h>
 #import <Contacts/Contacts.h>
 #include <napi.h>
 
@@ -6,6 +7,11 @@
 
 /***** HELPERS *****/
 
+// Dummy value to pass into function parameter for ThreadSafeFunction.
+Napi::Value NoOp(const Napi::CallbackInfo &info) {
+  return info.Env().Undefined();
+}
+
 // Parses and returns an array of email addresses as strings.
 Napi::Array GetEmailAddresses(Napi::Env env, CNContact *cncontact) {
   int num_email_addresses = [[cncontact emailAddresses] count];
@@ -263,6 +269,22 @@ CNAuthorizationStatus AuthStatus() {
   return [CNContactStore authorizationStatusForEntityType:entityType];
 }
 
+// Returns the authorization status as a string.
+std::string AuthStatusString() {
+  std::string auth_status = "Not Determined";
+
+  CNAuthorizationStatus status_for_entity = AuthStatus();
+
+  if (status_for_entity == CNAuthorizationStatusAuthorized)
+    auth_status = "Authorized";
+  else if (status_for_entity == CNAuthorizationStatusDenied)
+    auth_status = "Denied";
+  else if (status_for_entity == CNAuthorizationStatusRestricted)
+    auth_status = "Restricted";
+
+  return auth_status;
+}
+
 // Returns the set of Contacts properties to retrieve from the CNContactStore.
 NSArray *GetContactKeys(Napi::Array requested_keys) {
   NSMutableArray *keys = [NSMutableArray arrayWithArray:@[
@@ -392,21 +414,54 @@ CNAuthorizationStatus AuthStatus() {
 
 /***** EXPORTED FUNCTIONS *****/
 
-// Returns the user's Contacts access consent status as a string.
-Napi::Value GetAuthStatus(const Napi::CallbackInfo &info) {
+// Request Contacts access.
+Napi::Promise RequestAccess(const Napi::CallbackInfo &info) {
   Napi::Env env = info.Env();
-  std::string auth_status = "Not Determined";
-
-  CNAuthorizationStatus status_for_entity = AuthStatus();
+  Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(env);
+  Napi::ThreadSafeFunction ts_fn = Napi::ThreadSafeFunction::New(
+      env, Napi::Function::New(env, NoOp), "contactsCallback", 0, 1);
+
+  if (@available(macOS 10.11, *)) {
+    std::string status = AuthStatusString();
+
+    if (status == "Not Determined") {
+      __block Napi::ThreadSafeFunction tsfn = ts_fn;
+      CNContactStore *store = [CNContactStore new];
+      [store requestAccessForEntityType:CNEntityTypeContacts
+                      completionHandler:^(BOOL granted, NSError *error) {
+                        auto callback = [=](Napi::Env env, Napi::Function js_cb,
+                                            const char *granted) {
+                          deferred.Resolve(Napi::String::New(env, granted));
+                        };
+                        tsfn.BlockingCall(granted ? "Authorized" : "Denied",
+                                          callback);
+                        tsfn.Release();
+                      }];
+    } else if (status == "Denied") {
+      NSWorkspace *workspace = [[NSWorkspace alloc] init];
+      NSString *pref_string = @"x-apple.systempreferences:com.apple.preference."
+                              @"security?Contacts";
+
+      [workspace openURL:[NSURL URLWithString:pref_string]];
+
+      ts_fn.Release();
+      deferred.Resolve(Napi::String::New(env, "Denied"));
+    } else {
+      ts_fn.Release();
+      deferred.Resolve(Napi::String::New(env, "Authorized"));
+    }
+  } else {
+    ts_fn.Release();
+    deferred.Resolve(Napi::String::New(env, "Authorized"));
+  }
 
-  if (status_for_entity == CNAuthorizationStatusAuthorized)
-    auth_status = "Authorized";
-  else if (status_for_entity == CNAuthorizationStatusDenied)
-    auth_status = "Denied";
-  else if (status_for_entity == CNAuthorizationStatusRestricted)
-    auth_status = "Restricted";
+  return deferred.Promise();
+}
 
-  return Napi::Value::From(env, auth_status);
+// Returns the user's Contacts access consent status as a string.
+Napi::Value GetAuthStatus(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+  return Napi::Value::From(env, AuthStatusString());
 }
 
 // Returns an array of all a user's Contacts as objects.
@@ -606,6 +661,8 @@ CNAuthorizationStatus AuthStatus() {
               Napi::Function::New(env, RemoveListener));
   exports.Set(Napi::String::New(env, "isListening"),
               Napi::Function::New(env, IsListening));
+  exports.Set(Napi::String::New(env, "requestAccess"),
+              Napi::Function::New(env, RequestAccess));
   exports.Set(Napi::String::New(env, "getAuthStatus"),
               Napi::Function::New(env, GetAuthStatus));
   exports.Set(Napi::String::New(env, "getAllContacts"),

index.js

@@ -171,6 +171,7 @@ function deleteContact(contact) {
 
 module.exports = {
   listener,
+  requestAccess: contacts.requestAccess,
   getAuthStatus: contacts.getAuthStatus,
   getAllContacts,
   getContactsByName,

test/module.spec.js

@@ -7,12 +7,22 @@ const {
   deleteContact,
   updateContact,
   listener,
+  requestAccess,
 } = require('../index')
 
 const isCI = require('is-ci')
 const ifit = (condition) => (condition ? it : it.skip)
 const ifdescribe = (condition) => (condition ? describe : describe.skip)
 
+if (!isCI) {
+  requestAccess().then((status) => {
+    if (status !== 'Authorized') {
+      console.error('Access to Contacts not authorized - cannot proceed.')
+      process.exit(1)
+    }
+  })
+}
+
 describe('node-mac-contacts', () => {
   describe('getAuthStatus()', () => {
     it('should not throw', () => {