@aalzehla/capacitor-contacts 0.0.5 → 8.0.0

package/{AalzehlaCapacitorContacts.podspec → CapacitorCommunityContacts.podspec}

@@ -3,15 +3,15 @@ require 'json'
 package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
 
 Pod::Spec.new do |s|
-  s.name = 'AalzehlaCapacitorContacts'
+  s.name = 'CapacitorCommunityContacts'
   s.version = package['version']
   s.summary = package['description']
   s.license = package['license']
   s.homepage = package['repository']['url']
   s.author = package['author']
   s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
-  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
-  s.ios.deployment_target  = '14.0'
+  s.source_files = 'ios/Plugin/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
   s.dependency 'Capacitor'
   s.swift_version = '5.1'
 end

package/README.md

@@ -1,67 +1,91 @@
-# capacitor-contacts
+<p align="center">
+  <img
+    src="https://user-images.githubusercontent.com/236501/85893648-1c92e880-b7a8-11ea-926d-95355b8175c7.png"
+    width="128"
+    height="128"
+  />
+</p>
 
-This capacitor plugin allows you to use the native contact picker UI on Android or iOS for single contact selection. Both platforms will return the same payload structure, where the data exists.
+<h3 id="home" align="center">
+  Contacts
+</h3>
 
-## Install
+<p align="center">
+  <strong>
+    <code>@capacitor-community/contacts</code>
+  </strong>
+</p>
 
-```bash
-npm install @aalzehla/capacitor-contacts
-npx cap sync
-```
+<p align="center">Capacitor Plugin for accessing Contacts.</p>
 
-## API
+<p align="center">
+  <img src="https://img.shields.io/badge/supported%20capacitor%20versions-v3,%20v4,%20v5,%20v6%20and%20v7-blue?logo=Capacitor&style=flat-square" />
+  <img src="https://img.shields.io/maintenance/yes/2026?style=flat-square" />
+  <a href="https://www.npmjs.com/package/@capacitor-community/contacts">
+    <img src="https://img.shields.io/npm/l/@capacitor-community/contacts?style=flat-square" />
+  </a>
+  <br>
+  <a href="https://www.npmjs.com/package/@capacitor-community/contacts">
+    <img src="https://img.shields.io/npm/dw/@capacitor-community/contacts?style=flat-square" />
+  </a>
+  <a href="https://www.npmjs.com/package/@capacitor-community/contacts">
+    <img src="https://img.shields.io/npm/v/@capacitor-community/contacts?style=flat-square" />
+  </a>
+</p>
 
-<docgen-index>
+## Purpose
 
-* [`open()`](#open)
-* [`close()`](#close)
-* [Interfaces](#interfaces)
+This plugin enables you to access the native contacts APIs of iOS and Android. It allows you to retrieve, create and delete contacts.
 
-</docgen-index>
+## Versions
 
-<docgen-api>
-<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+Currently there are three actively maintained versions of this plugin. The API of these versions is identical. The only difference between these versions is the supported Capacitor versions.
 
-### open()
+| Plugin | Capacitor | Status | Documentation                                           |
+| ------ | --------- | ------ | ------------------------------------------------------- |
+| v7.x   | v7.x      | LTS    | [Link](https://capacitor-community.github.io/contacts/) |
+| v6.x   | v6.x      | LTS    | [Link](https://capacitor-community.github.io/contacts/) |
+| v5.x   | v5.x      | LTS    | [Link](https://capacitor-community.github.io/contacts/) |
+| v4.x   | v4.x      | LTS    | [Link](https://capacitor-community.github.io/contacts/) |
+| v3.x   | v3.x      | LTS    | [Link](https://capacitor-community.github.io/contacts/) |
 
-```typescript
-open() => Promise<Contact[]>
-```
+If you are installing this plugin into a new project, you can ignore the following explanation.
 
-**Returns:** <code>Promise&lt;Contact[]&gt;</code>
+In the past a few other versions of this plugin were released, also targeting different versions of Capacitor:
 
---------------------
+| Plugin        | Capacitor | Status     | Documentation                                                                                                   |
+| ------------- | --------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
+| v2.x          | v4.x      | Deprecated | [Link](https://github.com/capacitor-community/contacts/blob/v2.0.0/README.md)                                   |
+| v1.0.9 and up | v3.x      | Deprecated | [Link](https://github.com/capacitor-community/contacts/blob/1.1.3/README.md)                                    |
+| v1.0.0 and up | v2.x      | Deprecated | [Link](https://github.com/capacitor-community/contacts/blob/0cb99be68dc8ee4547c75f932872bd065f5509d2/README.md) |
+| v0.x          | v2.x      | Deprecated | [Link](https://github.com/capacitor-community/contacts/blob/0.1.1/README.md)                                    |
 
+Admittedly, this wasn't the most consistent versioning strategy, and we'll keep it more coherent in the future.
 
-### close()
+It's highly recommended to upgrade to either v3, v4, v5, v6 or v7 if you are using an old version!
 
-```typescript
-close() => Promise<void>
-```
+<p class="hide-next-element"></p>
 
---------------------
+## Documentation
 
+<p class="hide-next-element"></p>
 
-### Interfaces
+Extensive documentation is available [here](https://capacitor-community.github.io/contacts/).
 
+<p class="hide-next-element"></p>
 
-#### Contact
+## Shortcuts
 
-| Prop                          | Type                |
-| ----------------------------- | ------------------- |
-| **`identifier`**              | <code>string</code> |
-| **`androidContactLookupKey`** | <code>string</code> |
-| **`contactId`**               | <code>string</code> |
-| **`givenName`**               | <code>string</code> |
-| **`familyName`**              | <code>string</code> |
-| **`nickname`**                | <code>string</code> |
-| **`fullName`**                | <code>string</code> |
-| **`jobTitle`**                | <code>string</code> |
-| **`departmentName`**          | <code>string</code> |
-| **`organizationName`**        | <code>string</code> |
-| **`note`**                    | <code>string</code> |
-| **`phoneNumbers`**            | <code>any[]</code>  |
-| **`emailAddresses`**          | <code>any[]</code>  |
-| **`postalAddresses`**         | <code>any[]</code>  |
+<p class="hide-next-element"></p>
 
-</docgen-api>
+- [Documentation homepage](https://capacitor-community.github.io/contacts/)
+
+- [Installation](https://capacitor-community.github.io/contacts/#/getting-started-installation)
+
+- [API reference](https://capacitor-community.github.io/contacts/#/api)
+
+<!-- - [Examples](https://github.com/capacitor-community/contacts-examples) -->
+
+## Limitations
+
+This plugins only adds support for using the native iOS and Android APIs. If you want to make use of the JavaScript API as well (for a possible webapp) you should implement that separately. Of course it should be possible to integrate this into the plugin in the future. If you want to help out with this, please start a PR.

package/android/build.gradle

@@ -1,8 +1,8 @@
 ext {
     junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
-    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.6.1'
-    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.1.5'
-    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.5.1'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
 }
 
 buildscript {
@@ -11,34 +11,38 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.2.1'
+        classpath 'com.android.tools.build:gradle:8.13.0'
     }
 }
 
 apply plugin: 'com.android.library'
 
 android {
-    namespace "com.aalzehla.capacitor.contacts"
-    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+    namespace = "getcapacitor.community.contacts"
+    compileSdkVersion(project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35)
+    
     defaultConfig {
-        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 22
-        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+        minSdkVersion(project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23)
+        targetSdkVersion(project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35)
         versionCode 1
         versionName "1.0"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
     }
+
     buildTypes {
         release {
             minifyEnabled false
             proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
         }
     }
+
     lintOptions {
-        abortOnError false
+        abortOnError = false
     }
+
     compileOptions {
-        sourceCompatibility JavaVersion.VERSION_17
-        targetCompatibility JavaVersion.VERSION_17
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
     }
 }
 
@@ -47,7 +51,6 @@ repositories {
     mavenCentral()
 }
 
-
 dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')

package/android/src/main/java/getcapacitor/community/contacts/BiMap.java

@@ -0,0 +1,45 @@
+package getcapacitor.community.contacts;
+
+import java.util.HashMap;
+
+// Helper to enable bidirectional mapping.
+public class BiMap<K, V> {
+
+    // The following map can be used for retrieving the key belonging to a certain value.
+    // This map is essentially the inverted version of `mapForValues`
+    private final HashMap<V, K> mapForKeys = new HashMap<>();
+    // The following map can be used for retrieving the value belonging to a certain key.
+    private final HashMap<K, V> mapForValues;
+
+    private final K defaultKey;
+    private final V defaultValue;
+
+    BiMap(HashMap<K, V> map, K defaultKey, V defaultValue) {
+        this.mapForValues = map;
+
+        for (HashMap.Entry<K, V> entry : map.entrySet()) {
+            K key = entry.getKey();
+            V value = entry.getValue();
+            this.mapForKeys.put(value, key);
+        }
+
+        this.defaultKey = defaultKey;
+        this.defaultValue = defaultValue;
+    }
+
+    K getKey(V v) {
+        K k = this.mapForKeys.get(v);
+        if (k == null) {
+            return this.defaultKey;
+        }
+        return k;
+    }
+
+    V getValue(K k) {
+        V v = this.mapForValues.get(k);
+        if (v == null) {
+            return this.defaultValue;
+        }
+        return v;
+    }
+}

package/android/src/main/java/getcapacitor/community/contacts/ContactPayload.java

@@ -0,0 +1,286 @@
+package getcapacitor.community.contacts;
+
+import android.database.Cursor;
+import android.provider.ContactsContract;
+import android.provider.ContactsContract.CommonDataKinds.Email;
+import android.provider.ContactsContract.CommonDataKinds.Event;
+import android.provider.ContactsContract.CommonDataKinds.Note;
+import android.provider.ContactsContract.CommonDataKinds.Organization;
+import android.provider.ContactsContract.CommonDataKinds.Phone;
+import android.provider.ContactsContract.CommonDataKinds.Photo;
+import android.provider.ContactsContract.CommonDataKinds.StructuredName;
+import android.provider.ContactsContract.CommonDataKinds.StructuredPostal;
+import android.provider.ContactsContract.CommonDataKinds.Website;
+import android.util.Base64;
+import androidx.annotation.NonNull;
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import java.io.BufferedInputStream;
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.net.URLConnection;
+
+public class ContactPayload {
+
+    // Id
+    private String contactId;
+
+    // Name
+    private JSObject name = new JSObject();
+
+    // Organization
+    private JSObject organization = new JSObject();
+
+    // Birthday
+    private JSObject birthday = new JSObject();
+
+    // Note
+    private String note;
+
+    // Phones
+    private JSArray phones = new JSArray();
+
+    // Emails
+    private JSArray emails = new JSArray();
+
+    // URLs
+    private JSArray urls = new JSArray();
+
+    // Postal Addresses
+    private JSArray postalAddresses = new JSArray();
+
+    // Image
+    private JSObject image = new JSObject();
+
+    ContactPayload(String contactId) {
+        this.contactId = contactId;
+    }
+
+    private static @NonNull String getMimetype(byte[] blob) {
+        try {
+            InputStream is = new BufferedInputStream(new ByteArrayInputStream(blob));
+            String mimeType = URLConnection.guessContentTypeFromStream(is);
+            if (mimeType == null) {
+                return "image/png";
+            }
+            return mimeType;
+        } catch (Exception e) {
+            return "image/png";
+        }
+    }
+
+    private Integer parseStrToIntSafe(String str) {
+        try {
+            return Integer.parseInt(str);
+        } catch (NumberFormatException e) {
+            return null;
+        }
+    }
+
+    private Boolean getBooleanByColumnName(Cursor cursor, String columnName) {
+        int index = cursor.getColumnIndex(columnName);
+        if (index >= 0) {
+            int result = cursor.getInt(index);
+            return result == 1;
+        }
+        return null;
+    }
+
+    private String getStringByColumnName(Cursor cursor, String columnName) {
+        int index = cursor.getColumnIndex(columnName);
+        if (index >= 0) {
+            return cursor.getString(index);
+        }
+        return null;
+    }
+
+    private Integer getIntByColumnName(Cursor cursor, String columnName) {
+        int index = cursor.getColumnIndex(columnName);
+        if (index >= 0) {
+            return cursor.getInt(index);
+        }
+        return null;
+    }
+
+    private String getBase64ByColumnName(Cursor cursor, String columnName) {
+        int index = cursor.getColumnIndex(columnName);
+        if (index >= 0) {
+            byte[] blob = cursor.getBlob(index);
+            if (blob != null) {
+                String mimeType = getMimetype(blob);
+                String encodedImage = Base64.encodeToString(blob, Base64.NO_WRAP);
+                return "data:" + mimeType + ";base64," + encodedImage;
+            }
+        }
+        return null;
+    }
+
+    public void fillDataByCursor(@NonNull Cursor cursor) {
+        String mimeType = getStringByColumnName(cursor, ContactsContract.Data.MIMETYPE);
+
+        if (mimeType == null) {
+            return;
+        }
+
+        switch (mimeType) {
+            // Name
+            case StructuredName.CONTENT_ITEM_TYPE:
+                name.put("display", getStringByColumnName(cursor, StructuredName.DISPLAY_NAME));
+                name.put("given", getStringByColumnName(cursor, StructuredName.GIVEN_NAME));
+                name.put("middle", getStringByColumnName(cursor, StructuredName.MIDDLE_NAME));
+                name.put("family", getStringByColumnName(cursor, StructuredName.FAMILY_NAME));
+                name.put("prefix", getStringByColumnName(cursor, StructuredName.PREFIX));
+                name.put("suffix", getStringByColumnName(cursor, StructuredName.SUFFIX));
+                break;
+            // Organization
+            case Organization.CONTENT_ITEM_TYPE:
+                organization.put("company", getStringByColumnName(cursor, Organization.COMPANY));
+                organization.put("jobTitle", getStringByColumnName(cursor, Organization.TITLE));
+                organization.put("department", getStringByColumnName(cursor, Organization.DEPARTMENT));
+                break;
+            // Birthday
+            case Event.CONTENT_ITEM_TYPE:
+                Integer eventType = getIntByColumnName(cursor, Event.TYPE);
+                if (eventType != null && eventType == Event.TYPE_BIRTHDAY) {
+                    String birthdayString = getStringByColumnName(cursor, Event.START_DATE);
+
+                    if (birthdayString != null) {
+                        // Normally the date is formatted as "yyyy-mm-dd"
+                        // But it's possible to not have a year saved to the birthday,
+                        // then it's formatted like "--mm-dd".
+                        // So we'll have to rectify that:
+                        birthdayString = birthdayString.replace("--", "");
+
+                        // Next we'll split the string into pieces:
+                        String[] splittedBirthdayString = birthdayString.split("-");
+
+                        if (splittedBirthdayString.length == 2) {
+                            // Birthday is formatted like "mm-dd"
+                            birthday.put("month", parseStrToIntSafe(splittedBirthdayString[0]));
+                            birthday.put("day", parseStrToIntSafe(splittedBirthdayString[1]));
+                        } else if (splittedBirthdayString.length == 3) {
+                            // Birthday is formatted like "yyyy-mm-dd"
+                            birthday.put("year", parseStrToIntSafe(splittedBirthdayString[0]));
+                            birthday.put("month", parseStrToIntSafe(splittedBirthdayString[1]));
+                            birthday.put("day", parseStrToIntSafe(splittedBirthdayString[2]));
+                        }
+                    }
+                }
+                break;
+            // Note
+            case Note.CONTENT_ITEM_TYPE:
+                note = getStringByColumnName(cursor, Note.NOTE);
+                break;
+            // Phones
+            case Phone.CONTENT_ITEM_TYPE:
+                String number = getStringByColumnName(cursor, Phone.NUMBER);
+                Integer phoneType = getIntByColumnName(cursor, Phone.TYPE);
+                if (number != null && phoneType != null) {
+                    JSObject phoneObject = new JSObject();
+                    phoneObject.put("type", Contacts.phoneTypeMap.getKey(phoneType));
+                    phoneObject.put("label", getStringByColumnName(cursor, Phone.LABEL));
+                    phoneObject.put("isPrimary", getBooleanByColumnName(cursor, Phone.IS_PRIMARY));
+                    phoneObject.put("number", number);
+                    phones.put(phoneObject);
+                }
+                break;
+            // Emails
+            case Email.CONTENT_ITEM_TYPE:
+                String address = getStringByColumnName(cursor, Email.ADDRESS);
+                Integer emailType = getIntByColumnName(cursor, Email.TYPE);
+                if (address != null && emailType != null) {
+                    JSObject emailObject = new JSObject();
+                    emailObject.put("type", Contacts.emailTypeMap.getKey(emailType));
+                    emailObject.put("label", getStringByColumnName(cursor, Email.LABEL));
+                    emailObject.put("isPrimary", getBooleanByColumnName(cursor, Email.IS_PRIMARY));
+                    emailObject.put("address", address);
+                    emails.put(emailObject);
+                }
+                break;
+            // URLs
+            case Website.CONTENT_ITEM_TYPE:
+                String url = getStringByColumnName(cursor, Website.URL);
+                urls.put(url);
+                break;
+            // Postal Addresses
+            case StructuredPostal.CONTENT_ITEM_TYPE:
+                Integer postalAddressType = getIntByColumnName(cursor, StructuredPostal.TYPE);
+                if (postalAddressType != null) {
+                    JSObject postalAddressObject = new JSObject();
+                    postalAddressObject.put("type", Contacts.postalAddressTypeMap.getKey(postalAddressType));
+                    postalAddressObject.put("label", getStringByColumnName(cursor, StructuredPostal.LABEL));
+                    postalAddressObject.put("isPrimary", getBooleanByColumnName(cursor, StructuredPostal.IS_PRIMARY));
+                    postalAddressObject.put("formatted", getStringByColumnName(cursor, StructuredPostal.FORMATTED_ADDRESS));
+                    postalAddressObject.put("street", getStringByColumnName(cursor, StructuredPostal.STREET));
+                    postalAddressObject.put("neighborhood", getStringByColumnName(cursor, StructuredPostal.NEIGHBORHOOD));
+                    postalAddressObject.put("city", getStringByColumnName(cursor, StructuredPostal.CITY));
+                    postalAddressObject.put("region", getStringByColumnName(cursor, StructuredPostal.REGION));
+                    postalAddressObject.put("postcode", getStringByColumnName(cursor, StructuredPostal.POSTCODE));
+                    postalAddressObject.put("country", getStringByColumnName(cursor, StructuredPostal.COUNTRY));
+                    postalAddresses.put(postalAddressObject);
+                }
+                break;
+            // Image
+            case Photo.CONTENT_ITEM_TYPE:
+                String base64String = getBase64ByColumnName(cursor, Photo.PHOTO);
+                if (base64String != null) {
+                    image.put("base64String", base64String);
+                }
+                break;
+        }
+    }
+
+    public JSObject getJSObject() {
+        JSObject contact = new JSObject();
+
+        // Id
+        contact.put("contactId", contactId);
+
+        // Name
+        if (name.length() > 0) {
+            contact.put("name", name);
+        }
+
+        // Organization
+        if (organization.length() > 0) {
+            contact.put("organization", organization);
+        }
+
+        // Birthday
+        if (birthday.length() > 0) {
+            contact.put("birthday", birthday);
+        }
+
+        // Note
+        if (note != null) {
+            contact.put("note", note);
+        }
+
+        // Phones
+        if (phones.length() > 0) {
+            contact.put("phones", phones);
+        }
+
+        // Emails
+        if (emails.length() > 0) {
+            contact.put("emails", emails);
+        }
+
+        // URLs
+        if (urls.length() > 0) {
+            contact.put("urls", urls);
+        }
+
+        // Postal Addresses
+        if (postalAddresses.length() > 0) {
+            contact.put("postalAddresses", postalAddresses);
+        }
+
+        // Image
+        if (image.length() > 0) {
+            contact.put("image", image);
+        }
+
+        return contact;
+    }
+}