feat: add optional keys to contacts (#6)

Author: codebytere

README.md

@@ -46,7 +46,9 @@ console.log(`Authorization access to contacts is: ${authStatus}`)
 */
 ```
 
-### contacts.getAllContacts()
+### 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`, or `contactThumbnailImage`.
 
 Returns `Array<Object>` - Returns an array of contact objects.
 
@@ -59,7 +61,13 @@ The returned objects will take the following format:
 * `phoneNumbers` String[] - An array of phone numbers as strings in [E.164 format](https://en.wikipedia.org/wiki/E.164).
 * `emailAddresses` String[] - An array of email addresses as strings.
 * `postalAddresses` String[] - An array of postal as strings.
-* `contactImage` Buffer (optional) - a Buffer representation of the contact's image, if one has been set.
+* `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.
+* `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.
 
 This method will return an empty array (`[]`) if access to Contacts has not been granted.
 
@@ -77,17 +85,16 @@ console.log(allContacts[0])
     nickname: 'Johnny',
     birthday: '1970-01-01',
     phoneNumbers: [ +11234566789' ],
-    emailAddresses: [ 'johnny@appleseed.com' ] 
-    postalAddresses: [ '123 Pine Tree Way\nBlack Oak, Arkansas 72414\nUnited States' ],
-    contactImage: <Buffer ff d8 ff e0 00 10 4a 46 49 46 00 01 01 00 00 48 00 48 00 00 ff e1 00 4c 45 78 69 66 00 00 4d 4d 00 2a 00 00 00 08 00 01 87 69 00 04 00 00 00 01 00 00 ... 139493 more bytes>
+    emailAddresses: [ 'johnny@appleseed.com' ],
+    postalAddresses: [ '123 Pine Tree Way\nBlack Oak, Arkansas 72414\nUnited States' ]
   }
 ]
 */
 ```
 
-### contacts.getContactsByName(name)
+### contacts.getContactsByName(name[, extraProperties])
 
-* `name` String (required) - The first, 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`, or `contactThumbnailImage`.
 
 Returns `Array<Object>` - Returns an array of contact objects where either the first or last name of the contact matches `name`.
 
@@ -102,7 +109,13 @@ The returned object will take the following format:
 * `phoneNumbers` String[] - An array of phone numbers as strings in [E.164 format](https://en.wikipedia.org/wiki/E.164).
 * `emailAddresses` String[] - An array of email addresses as strings.
 * `postalAddresses` String[] - An array of postal as strings.
-* `contactImage` Buffer (optional) - a Buffer representation of the contact's image, if one has been set.
+* `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.
+* `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.
 
 This method will return an empty array (`[]`) if access to Contacts has not been granted.
 
@@ -120,9 +133,8 @@ console.log(contacts)
     nickname: 'Johnny',
     birthday: '1970-01-01',
     phoneNumbers: [ +11234566789' ],
-    emailAddresses: [ 'johnny@appleseed.com' ] 
+    emailAddresses: [ 'johnny@appleseed.com' ],
     postalAddresses: [ '123 Pine Tree Way\nBlack Oak, Arkansas 72414\nUnited States' ]
-    contactImage: <Buffer ff d8 ff e0 00 10 4a 46 49 46 00 01 01 00 00 48 00 48 00 00 ff e1 00 4c 45 78 69 66 00 00 4d 4d 00 2a 00 00 00 08 00 01 87 69 00 04 00 00 00 01 00 00 ... 139493 more bytes>
   }
 ]
 */

contacts.mm

@@ -67,10 +67,12 @@
   return result;
 }
 
-Napi::Buffer<uint8_t> GetContactImage(Napi::Env env, CNContact *cncontact) {
+Napi::Buffer<uint8_t> GetContactImage(Napi::Env env, CNContact *cncontact,
+                                      bool thumbnail) {
   std::vector<uint8_t> data;
 
-  NSData *image_data = [cncontact imageData];
+  NSData *image_data =
+      thumbnail ? [cncontact thumbnailImageData] : [cncontact imageData];
   const uint8 *bytes = (uint8 *)[image_data bytes];
   data.assign(bytes, bytes + [image_data length]);
 
@@ -83,31 +85,58 @@
 Napi::Object CreateContact(Napi::Env env, CNContact *cncontact) {
   Napi::Object contact = Napi::Object::New(env);
 
+  // Default contact properties.
+
   contact.Set("firstName", std::string([[cncontact givenName] UTF8String]));
   contact.Set("lastName", std::string([[cncontact familyName] UTF8String]));
   contact.Set("nickname", std::string([[cncontact nickname] UTF8String]));
 
   std::string birthday = GetBirthday(cncontact);
   contact.Set("birthday", birthday.empty() ? "" : birthday);
 
-  // Populate phone number array
   Napi::Array phone_numbers = GetPhoneNumbers(env, cncontact);
   contact.Set("phoneNumbers", phone_numbers);
 
-  // Populate email address array
   Napi::Array email_addresses = GetEmailAddresses(env, cncontact);
   contact.Set("emailAddresses", email_addresses);
 
-  // Populate postal address array
   Napi::Array postal_addresses = GetPostalAddresses(env, cncontact);
   contact.Set("postalAddresses", postal_addresses);
 
-  // Populate contact image if one exists.
-  Napi::Buffer<uint8_t> image_buffer = GetContactImage(env, cncontact);
-  if (image_buffer.Length() > 0) {
+  // Optional contact properties.
+
+  if ([cncontact isKeyAvailable:CNContactImageDataKey]) {
+    Napi::Buffer<uint8_t> image_buffer = GetContactImage(env, cncontact, false);
     contact.Set("contactImage", image_buffer);
   }
 
+  if ([cncontact isKeyAvailable:CNContactThumbnailImageDataKey]) {
+    Napi::Buffer<uint8_t> image_buffer = GetContactImage(env, cncontact, true);
+    contact.Set("contactThumbnailImage", image_buffer);
+  }
+
+  if ([cncontact isKeyAvailable:CNContactJobTitleKey]) {
+    contact.Set("jobTitle", std::string([[cncontact jobTitle] UTF8String]));
+  }
+
+  if ([cncontact isKeyAvailable:CNContactDepartmentNameKey]) {
+    contact.Set("departmentName",
+                std::string([[cncontact departmentName] UTF8String]));
+  }
+
+  if ([cncontact isKeyAvailable:CNContactOrganizationNameKey]) {
+    contact.Set("organizationName",
+                std::string([[cncontact organizationName] UTF8String]));
+  }
+
+  if ([cncontact isKeyAvailable:CNContactNoteKey]) {
+    contact.Set("note", std::string([[cncontact note] UTF8String]));
+  }
+
+  if ([cncontact isKeyAvailable:CNContactMiddleNameKey]) {
+    contact.Set("middleName", std::string([[cncontact middleName] UTF8String]));
+  }
+
   return contact;
 }
 
@@ -174,28 +203,54 @@ CNAuthorizationStatus AuthStatus() {
   return [CNContactStore authorizationStatusForEntityType:entityType];
 }
 
-// Returns the set of Contacts properties to retrieve from the CNContactStore
-NSArray *GetContactKeys() {
-  NSArray *keys = @[
+// Returns the set of Contacts properties to retrieve from the CNContactStore.
+NSArray *GetContactKeys(Napi::Array requested_keys) {
+  NSMutableArray *keys = [NSMutableArray arrayWithArray:@[
     CNContactGivenNameKey, CNContactFamilyNameKey, CNContactPhoneNumbersKey,
     CNContactEmailAddressesKey, CNContactNicknameKey,
-    CNContactPostalAddressesKey, CNContactBirthdayKey, CNContactImageDataKey
-  ];
+    CNContactPostalAddressesKey, CNContactBirthdayKey
+  ]];
+
+  // Iterate through requested keys and add each to the default set.
+  int num_keys = requested_keys.Length();
+  if (num_keys > 0) {
+    for (int i = 0; i < num_keys; i++) {
+      Napi::Value val = requested_keys[i];
+      std::string key = val.As<Napi::String>().Utf8Value();
+
+      if (key == "contactImage") {
+        [keys addObject:CNContactImageDataKey];
+      } else if (key == "contactThumbnailImage") {
+        [keys addObject:CNContactThumbnailImageDataKey];
+      } else if (key == "jobTitle") {
+        [keys addObject:CNContactJobTitleKey];
+      } else if (key == "departmentName") {
+        [keys addObject:CNContactDepartmentNameKey];
+      } else if (key == "organizationName") {
+        [keys addObject:CNContactOrganizationNameKey];
+      } else if (key == "note") {
+        [keys addObject:CNContactNoteKey];
+      } else if (key == "middleName") {
+        [keys addObject:CNContactMiddleNameKey];
+      }
+    }
+  }
 
   return keys;
 }
 
 // Returns all contacts in the CNContactStore matching a specified name string
 // predicate.
-NSArray *FindContacts(const std::string &name_string) {
+NSArray *FindContacts(const std::string &name_string, Napi::Array extra_keys) {
   CNContactStore *addressBook = [[CNContactStore alloc] init];
 
   NSString *name = [NSString stringWithUTF8String:name_string.c_str()];
   NSPredicate *predicate = [CNContact predicateForContactsMatchingName:name];
 
-  return [addressBook unifiedContactsMatchingPredicate:predicate
-                                           keysToFetch:GetContactKeys()
-                                                 error:nil];
+  return
+      [addressBook unifiedContactsMatchingPredicate:predicate
+                                        keysToFetch:GetContactKeys(extra_keys)
+                                              error:nil];
 }
 
 // Creates a new CNContact in order to update, delete, or add it to the
@@ -267,9 +322,11 @@ CNAuthorizationStatus AuthStatus() {
 // Returns an array of all a user's Contacts as objects.
 Napi::Array GetAllContacts(const Napi::CallbackInfo &info) {
   Napi::Env env = info.Env();
+
   Napi::Array contacts = Napi::Array::New(env);
   CNContactStore *addressBook = [[CNContactStore alloc] init];
   NSMutableArray *cncontacts = [[NSMutableArray alloc] init];
+  Napi::Array extra_keys = info[0].As<Napi::Array>();
 
   if (AuthStatus() != CNAuthorizationStatusAuthorized)
     return contacts;
@@ -283,7 +340,7 @@ CNAuthorizationStatus AuthStatus() {
         predicateForContactsInContainerWithIdentifier:[container identifier]];
     NSArray *container_contacts =
         [addressBook unifiedContactsMatchingPredicate:predicate
-                                          keysToFetch:GetContactKeys()
+                                          keysToFetch:GetContactKeys(extra_keys)
                                                 error:nil];
 
     [cncontacts addObjectsFromArray:container_contacts];
@@ -307,7 +364,8 @@ CNAuthorizationStatus AuthStatus() {
     return contacts;
 
   const std::string name_string = info[0].As<Napi::String>().Utf8Value();
-  NSArray *cncontacts = FindContacts(name_string);
+  Napi::Array extra_keys = info[1].As<Napi::Array>();
+  NSArray *cncontacts = FindContacts(name_string, extra_keys);
 
   int num_contacts = [cncontacts count];
   for (int i = 0; i < num_contacts; i++) {
@@ -344,7 +402,7 @@ CNAuthorizationStatus AuthStatus() {
     return Napi::Boolean::New(env, false);
 
   const std::string name_string = info[0].As<Napi::String>().Utf8Value();
-  NSArray *cncontacts = FindContacts(name_string);
+  NSArray *cncontacts = FindContacts(name_string, Napi::Array::New(env));
 
   CNContact *contact = (CNContact *)[cncontacts objectAtIndex:0];
   CNSaveRequest *request = [[CNSaveRequest alloc] init];

index.js

@@ -1,9 +1,23 @@
 const contacts = require('bindings')('contacts.node')
 
-function getContactsByName(name) {
-  if (typeof name !== 'string') throw new TypeError('name must be a string')
+function getAllContacts(extraProperties = []) {
+  if (Array.isArray(extraProperties)) {
+    throw new TypeError('extraProperties must be an array')
+  }
+
+  return contacts.getAllContacts.call(this, extraProperties)
+}
+
+function getContactsByName(name, extraProperties = []) {
+  if (typeof name !== 'string') {
+    throw new TypeError('name must be a string')
+  }
+
+  if (Array.isArray(extraProperties)) {
+    throw new TypeError('extraProperties must be an array')
+  }
 
-  return contacts.getContactsByName.call(this, name)
+  return contacts.getContactsByName.call(this, name, extraProperties)
 }
 
 function addNewContact(contact) {
@@ -17,16 +31,25 @@ function addNewContact(contact) {
     const hasPhoneNumbers = contact.hasOwnProperty('phoneNumbers')
     const hasEmailAddresses = contact.hasOwnProperty('emailAddresses')
 
-    if (hasFirstName && typeof contact.firstName !== 'string')
+    if (hasFirstName && typeof contact.firstName !== 'string') {
       throw new TypeError('firstName must be a string')
-    if (hasLastName && typeof contact.lastName !== 'string')
+    }
+
+    if (hasLastName && typeof contact.lastName !== 'string') {
       throw new TypeError('lastName must be a string')
-    if (hasNickname && typeof contact.nickname !== 'string')
+    }
+
+    if (hasNickname && typeof contact.nickname !== 'string') {
       throw new TypeError('nickname must be a string')
-    if (hasPhoneNumbers && !Array.isArray(contact.phoneNumbers))
+    }
+
+    if (hasPhoneNumbers && !Array.isArray(contact.phoneNumbers)) {
       throw new TypeError('phoneNumbers must be an array')
-    if (hasEmailAddresses && !Array.isArray(contact.emailAddresses))
+    }
+
+    if (hasEmailAddresses && !Array.isArray(contact.emailAddresses)) {
       throw new TypeError('emailAddresses must be an array')
+    }
 
     if (hasBirthday) {
       const datePattern = /^\d{4}\-(0[1-9]|1[012])\-(0[1-9]|[12][0-9]|3[01])$/
@@ -52,16 +75,25 @@ function updateContact(contact) {
     const hasPhoneNumbers = contact.hasOwnProperty('phoneNumbers')
     const hasEmailAddresses = contact.hasOwnProperty('emailAddresses')
 
-    if (hasFirstName && typeof contact.firstName !== 'string')
+    if (hasFirstName && typeof contact.firstName !== 'string') {
       throw new TypeError('firstName must be a string')
-    if (hasLastName && typeof contact.lastName !== 'string')
+    }
+
+    if (hasLastName && typeof contact.lastName !== 'string') {
       throw new TypeError('lastName must be a string')
-    if (hasNickname && typeof contact.nickname !== 'string')
+    }
+
+    if (hasNickname && typeof contact.nickname !== 'string') {
       throw new TypeError('nickname must be a string')
-    if (hasPhoneNumbers && !Array.isArray(contact.phoneNumbers))
+    }
+
+    if (hasPhoneNumbers && !Array.isArray(contact.phoneNumbers)) {
       throw new TypeError('phoneNumbers must be an array')
-    if (hasEmailAddresses && !Array.isArray(contact.emailAddresses))
+    }
+
+    if (hasEmailAddresses && !Array.isArray(contact.emailAddresses)) {
       throw new TypeError('emailAddresses must be an array')
+    }
 
     if (hasBirthday) {
       const datePattern = /^\d{4}\-(0[1-9]|1[012])\-(0[1-9]|[12][0-9]|3[01])$/
@@ -77,14 +109,16 @@ function updateContact(contact) {
 }
 
 function deleteContact(name) {
-  if (typeof name !== 'string') throw new TypeError('name must be a string')
+  if (typeof name !== 'string') {
+    throw new TypeError('name must be a string')
+  }
 
   return contacts.deleteContact.call(this, name)
 }
 
 module.exports = {
   getAuthStatus: contacts.getAuthStatus,
-  getAllContacts: contacts.getAllContacts,
+  getAllContacts,
   getContactsByName,
   addNewContact,
   deleteContact,