Add support for optional CNContactUrlAddressesKey field. (#36)

Author: kitschpatrol

README.md

@@ -34,6 +34,8 @@ Requests access to the [CNContactStore](https://developer.apple.com/documentatio
 
 If the user has previously denied the request, this method will open the Contacts pane within the Privacy section of System Preferences.
 
+*Note that access permission request prompts will not appear when `requestAccess()` is invoked in embedded terminals such as those found in Visual Studio Code. Run your code from an external terminal such as Terminal.app instead.*
+
 ### `contacts.getAuthStatus()`
 
 Returns `String` - Can be one of 'Not Determined', 'Denied', 'Authorized', or 'Restricted'.
@@ -62,7 +64,7 @@ console.log(`Authorization access to contacts is: ${authStatus}`)
 
 ### `contacts.getAllContacts([extraProperties])`
 
-* `extraProperties` string[] (optional) - an array of extra contact properties to fetch that can be any of: `jobTitle`, `departmentName`, `organizationName`, `middleName`, `note`, `contactImage`, `contactThumbnailImage`, `instantMessageAddresses`, or `socialProfiles`.
+* `extraProperties` string[] (optional) - an array of extra contact properties to fetch that can be any of: `jobTitle`, `departmentName`, `organizationName`, `middleName`, `note`, `contactImage`, `contactThumbnailImage`, `instantMessageAddresses`, `socialProfiles`, or `urlAddresses`.
 
 Returns `Array<Object>` - Returns an array of contact objects.
 
@@ -78,13 +80,14 @@ The returned objects will take the following format:
 * `postalAddresses` String[] - An array of postal as strings.
 * `jobTitle` String (optional) - The contact's job title.
 * `departmentName` String (optional) - The name of the department associated with the contact.
-* `organizationName`  String (optional) - The name of the organization associated with the contact.
+* `organizationName` String (optional) - The name of the organization associated with the contact.
 * `middleName` String (optional) - The contact's middle name.
 * `note` String (optional) - The note associated with the contact.
 * `contactImage` Buffer (optional) - a Buffer representation of the contact's profile picture.
 * `contactThumbnailImage` Buffer (optional) - a Buffer representation of The thumbnail version of the contact’s profile picture.
 * `socialProfiles` Object[] (optional) - An array of labeled social profiles for a contact.
-* `instantMessageAddresses` Object[]  (optional) - An array of labeled IM addresses for the contact.
+* `instantMessageAddresses` Object[] (optional) - An array of labeled IM addresses for the contact.
+* `urlAddresses` String[] (optional) - An array of url addresses as strings.
 
 This method will return an empty array (`[]`) if access to Contacts has not been granted.
 
@@ -112,7 +115,7 @@ console.log(allContacts[0])
 ### `contacts.getContactsByName(name[, extraProperties])`
 
 * `name` String (required) - The first, middle, last, or full name of a contact.
-* `extraProperties` String[] (optional) - an array of extra contact properties to fetch that can be any of: `jobTitle`, `departmentName`, `organizationName`, `middleName`, `note`, `contactImage`, `contactThumbnailImage`, `instantMessageAddresses`, or `socialProfiles`.
+* `extraProperties` String[] (optional) - an array of extra contact properties to fetch that can be any of: `jobTitle`, `departmentName`, `organizationName`, `middleName`, `note`, `contactImage`, `contactThumbnailImage`, `instantMessageAddresses`, `socialProfiles`, or `urlAddresses`.
 
 Returns `Array<Object>` - Returns an array of contact objects where either the first or last name of the contact matches `name`.
 
@@ -130,13 +133,14 @@ The returned object will take the following format:
 * `postalAddresses` String[] - An array of postal as strings.
 * `jobTitle` String (optional) - The contact's job title.
 * `departmentName` String (optional) - The name of the department associated with the contact.
-* `organizationName`  String (optional) - The name of the organization associated with the contact.
+* `organizationName` String (optional) - The name of the organization associated with the contact.
 * `middleName` String (optional) - The contact's middle name.
 * `note` String (optional) - The note associated with the contact.
 * `contactImage` Buffer (optional) - a Buffer representation of the contact's profile picture.
 * `contactThumbnailImage` Buffer (optional) - a Buffer representation of The thumbnail version of the contact’s profile picture.
 * `socialProfiles` Object[] (optional) - An array of labeled social profiles for a contact.
-* `instantMessageAddresses` Object[]  (optional) - An array of labeled IM addresses for the contact.
+* `instantMessageAddresses` Object[] (optional) - An array of labeled IM addresses for the contact.
+* `urlAddresses` String[] (optional) - An array of url addresses as strings.
 
 This method will return an empty array (`[]`) if access to Contacts has not been granted.
 
@@ -169,15 +173,16 @@ console.log(contacts)
   * `nickname` String (optional) - The nickname for the contact.
   * `jobTitle` String (optional) - The contact's job title.
   * `departmentName` String (optional) - The name of the department associated with the contact.
-  * `organizationName`  String (optional) - The name of the organization associated with the contact.
+  * `organizationName` String (optional) - The name of the organization associated with the contact.
   * `middleName` String (optional) - The contact's middle name.
   * `birthday` String (optional) - The birthday for the contact in `YYYY-MM-DD` format.
   * `phoneNumbers` Array\<String\> (optional) - The phone numbers for the contact, as strings in [E.164 format](https://en.wikipedia.org/wiki/E.164): `+14155552671` or `+442071838750`.
   * `emailAddresses` Array\<String\> (optional) - The email addresses for the contact, as strings.
+  * `urlAddresses` Array\<String\> (optional) - The url addresses for the contact, as strings.
 
 Returns `Boolean` - whether the contact information was created successfully.
 
-Creates and save a new contact to the user's contacts database. 
+Creates and save a new contact to the user's contacts database.
 
 This method will return `false` if access to Contacts has not been granted.
 
@@ -189,8 +194,8 @@ const success = contacts.addNewContact({
   lastName: 'Grapeseed',
   nickname: 'Billy',
   birthday: '1990-09-09',
-  phoneNumbers: [ '+1234567890' ],
-  emailAddresses: ['billy@grapeseed.com' ]
+  phoneNumbers: ['+1234567890'],
+  emailAddresses: ['billy@grapeseed.com'],
 })
 
 console.log(`New contact was ${success ? 'saved' : 'not saved'}.`)
@@ -227,11 +232,12 @@ console.log(`Contact ${name} was ${deleted ? 'deleted' : 'not deleted'}.`)
   * `nickname` String (optional) - The nickname for the contact.
   * `jobTitle` String (optional) - The contact's job title.
   * `departmentName` String (optional) - The name of the department associated with the contact.
-  * `organizationName`  String (optional) - The name of the organization associated with the contact.
+  * `organizationName` String (optional) - The name of the organization associated with the contact.
   * `middleName` String (optional) - The contact's middle name.
   * `birthday` String (optional) - The birthday for the contact in `YYYY-MM-DD` format.
   * `phoneNumbers` Array\<String\> (optional) - The phone numbers for the contact, as strings in [E.164 format](https://en.wikipedia.org/wiki/E.164): `+14155552671` or `+442071838750`.
   * `emailAddresses` Array\<String\> (optional) - The email addresses for the contact, as strings.
+  * `urlAddresses` Array\<String\> (optional) - The url addresses for the contact, as strings.
 
 Returns `Boolean` - whether the contact was updated successfully.
 
@@ -248,7 +254,7 @@ Example Usage:
 const updated = contacts.updateContact({
   firstName: 'William',
   lastName: 'Grapeseed',
-  nickname: 'Will'
+  nickname: 'Will',
 })
 
 console.log(`Contact was ${updated ? 'updated' : 'not updated'}.`)

contacts.mm

@@ -141,6 +141,21 @@
   return Napi::Buffer<uint8_t>::Copy(env, &data[0], data.size());
 }
 
+// Parses and returns an array of URL addresses as strings.
+Napi::Array GetUrlAddresses(Napi::Env env, CNContact *cncontact) {
+  int num_url_addresses = [[cncontact urlAddresses] count];
+
+  Napi::Array url_addresses = Napi::Array::New(env, num_url_addresses);
+  NSArray<CNLabeledValue<NSString *> *> *urlAddresses =
+      [cncontact urlAddresses];
+  for (int i = 0; i < num_url_addresses; i++) {
+    CNLabeledValue<NSString *> *url_address = [urlAddresses objectAtIndex:i];
+    url_addresses[i] = std::string([[url_address value] UTF8String]);
+  }
+
+  return url_addresses;
+}
+
 // Creates an object containing all properties of a macOS contact.
 Napi::Object CreateContact(Napi::Env env, CNContact *cncontact) {
   Napi::Object contact = Napi::Object::New(env);
@@ -201,6 +216,11 @@
   if ([cncontact isKeyAvailable:CNContactSocialProfilesKey])
     contact.Set("socialProfiles", GetSocialProfiles(env, cncontact));
 
+  if ([cncontact isKeyAvailable:CNContactUrlAddressesKey]) {
+    Napi::Array url_addresses = GetUrlAddresses(env, cncontact);
+    contact.Set("urlAddresses", url_addresses);
+  }
+
   return contact;
 }
 
@@ -261,6 +281,24 @@
   return birthday_components;
 }
 
+// Parses an array of url address strings and converts them to an NSArray of
+// NSStrings.
+NSArray *ParseUrlAddresses(Napi::Array url_address_data) {
+  NSMutableArray *url_addresses = [[NSMutableArray alloc] init];
+
+  int data_length = static_cast<int>(url_address_data.Length());
+  for (int i = 0; i < data_length; i++) {
+    std::string url_str =
+        url_address_data.Get(i).As<Napi::String>().Utf8Value();
+    NSString *url = [NSString stringWithUTF8String:url_str.c_str()];
+    CNLabeledValue *labeled_value =
+        [CNLabeledValue labeledValueWithLabel:CNLabelHome value:url];
+    [url_addresses addObject:labeled_value];
+  }
+
+  return url_addresses;
+}
+
 // Returns a status indicating whether or not the user has authorized Contacts
 // access.
 CNAuthorizationStatus AuthStatus() {
@@ -322,6 +360,8 @@ CNAuthorizationStatus AuthStatus() {
           CNSocialProfileURLStringKey, CNSocialProfileUsernameKey,
           CNSocialProfileUserIdentifierKey
         ]];
+      } else if (key == "urlAddresses") {
+        [keys addObject:CNContactUrlAddressesKey];
       }
     }
   }
@@ -434,6 +474,13 @@ CNAuthorizationStatus AuthStatus() {
     [contact setEmailAddresses:[NSArray arrayWithArray:email_addresses]];
   }
 
+  if (contact_data.Has("urlAddresses")) {
+    Napi::Array url_address_data =
+        contact_data.Get("urlAddresses").As<Napi::Array>();
+    NSArray *url_addresses = ParseUrlAddresses(url_address_data);
+    [contact setUrlAddresses:[NSArray arrayWithArray:url_addresses]];
+  }
+
   return contact;
 }
 

index.js

@@ -24,6 +24,7 @@ const optionalProperties = [
   'contactThumbnailImage',
   'instantMessageAddresses',
   'socialProfiles',
+  'urlAddresses',
 ]
 
 function getAllContacts(extraProperties = []) {
@@ -81,7 +82,7 @@ function validateContactArg(contact) {
       throw new TypeError(`${prop} must be a string`)
     }
   }
-  for (const prop of ['phoneNumbers', 'emailAddresses']) {
+  for (const prop of ['phoneNumbers', 'emailAddresses', 'urlAddresses']) {
     const hasProp = contact.hasOwnProperty(prop)
     if (hasProp && !Array.isArray(contact[prop])) {
       throw new TypeError(`${prop} must be an array`)

package.json

@@ -9,7 +9,7 @@
     "clean": "node-gyp clean",
     "lint": "prettier --check '**/*.js'",
     "format": "clang-format -i contacts.mm && prettier --write '**/*.js'",
-    "rebuild": "node-gyp 2ebuild",
+    "rebuild": "node-gyp rebuild",
     "rebuild:dev": "node-gyp rebuild --debug",
     "test": "./node_modules/.bin/mocha --reporter spec",
     "prepare": "husky install"

test/module.spec.js

@@ -51,7 +51,7 @@ describe('node-mac-contacts', () => {
 
     it('should throw if extraProperties contains invalid properties', () => {
       const errorMessage =
-        'properties in extraProperties must be one of jobTitle, departmentName, organizationName, middleName, note, contactImage, contactThumbnailImage, instantMessageAddresses, socialProfiles'
+        'properties in extraProperties must be one of jobTitle, departmentName, organizationName, middleName, note, contactImage, contactThumbnailImage, instantMessageAddresses, socialProfiles, urlAddresses'
 
       expect(() => {
         getAllContacts(['bad-property'])
@@ -135,7 +135,7 @@ describe('node-mac-contacts', () => {
 
     it('should throw if extraProperties contains invalid properties', () => {
       const errorMessage =
-        'properties in extraProperties must be one of jobTitle, departmentName, organizationName, middleName, note, contactImage, contactThumbnailImage, instantMessageAddresses, socialProfiles'
+        'properties in extraProperties must be one of jobTitle, departmentName, organizationName, middleName, note, contactImage, contactThumbnailImage, instantMessageAddresses, socialProfiles, urlAddresses'
 
       expect(() => {
         getContactsByName('jim-bob', ['bad-property'])