@capgo/capacitor-contacts 8.1.0 → 8.1.2

package/README.md

@@ -69,11 +69,13 @@ Use `ContactProperty.EmailAddress` or `ContactProperty.PostalAddress` the same w
 
 **When you still need `READ_CONTACTS`:**
 
+- `pickContacts()` / `pickContact()` without `property` (full contact record)
 - `getContacts()`, `getContactById()`, `countContacts()`, `getGroups()`, `getAccounts()`
-- Picking a full contact without `property` on Android 16 and below
 - Syncing, backing up, or matching the whole address book
 
-If those are core features, add the permission and file the Play Console declaration before pre-review checks start on 27 October 2026:
+Those APIs keep working as before once `READ_CONTACTS` is in the app manifest and granted. Pass `property` only if you want to drop the permission.
+
+If full-address-book access is a core feature, add the permission and file the Play Console declaration before pre-review checks start on 27 October 2026:
 
 ```xml
 <uses-permission android:name="android.permission.READ_CONTACTS" />
@@ -81,7 +83,7 @@ If those are core features, add the permission and file the Play Console declara
 
 `WRITE_CONTACTS` is unchanged by this policy. Add it only if you create or update contacts in code.
 
-On Android 17 and later, picking a full contact without `property` also works without `READ_CONTACTS` because the system picker returns a session URI. Keep using `property` if you still support older Android versions and want the permission out of the manifest entirely.
+Without `READ_CONTACTS`, `pickContacts()` without `property` can still return `id` and `displayName` (and, on Android 17+, picker-granted fields). Use `property` to get a phone, email, or address with no permission on every Android version.
 
 ## iOS
 
@@ -402,8 +404,8 @@ pickContact(options?: PickContactsOptions | undefined) => Promise<PickContactRes
 
 <a href="#pick">Pick</a> a single contact using the native contact picker.
 
-Same options as {@link pickContacts}. Pass `property` to select one phone
-number, email address, or postal address without `READ_CONTACTS` on Android.
+Same options as {@link pickContacts}. Without `property`, Android still
+returns the full contact when `READ_CONTACTS` is granted.
 
 | Param         | Type                                                                | Description                                            |
 | ------------- | ------------------------------------------------------------------- | ------------------------------------------------------ |
@@ -426,15 +428,11 @@ pickContacts(options?: PickContactsOptions | undefined) => Promise<PickContactsR
 
 On iOS this never requires a contacts permission.
 
-On Android, pass `property` to select a single phone number, email address,
-or postal address with no `READ_CONTACTS` permission. That works on every
-Android version and is the way to ship without declaring the permission
-when targeting Android 17 (API 37) or later.
-
-Picking a full contact without `property` still needs `READ_CONTACTS` below
-Android 17, because the picker URI exposes no phone, email, or structured
-name. On Android 17 and later the system contact picker returns a session
-URI the plugin reads without that permission.
+On Android, `pickContacts()` without `property` still returns the full
+contact when the app has `READ_CONTACTS`. Pass `property` only when you
+want a single phone number, email address, or postal address and can omit
+that permission (required to target Android 17 / API 37 without a Play
+Console contacts declaration).
 
 | Param         | Type                                                                | Description                                            |
 | ------------- | ------------------------------------------------------------------- | ------------------------------------------------------ |

package/android/src/main/java/app/capgo/contacts/CapacitorContactsPlugin.java

@@ -40,7 +40,7 @@ import java.util.Set;
 )
 public class CapacitorContactsPlugin extends Plugin {
 
-    private final String pluginVersion = "8.1.0";
+    private final String pluginVersion = "8.1.2";
     private static final int BATCH_SIZE = 50;
 
     // MARK: - Implemented API surface
@@ -469,13 +469,6 @@ public class CapacitorContactsPlugin extends Plugin {
     private PluginCall currentPickerCall;
     private String currentPickerProperty;
 
-    // Android 17 (API 37) system contact picker. Constants are inlined so the
-    // plugin still compiles against compileSdk 36.
-    private static final int ANDROID_API_17 = 37;
-    private static final String ACTION_PICK_CONTACTS = "android.provider.action.PICK_CONTACTS";
-    private static final String EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS = "android.provider.extra.PICK_CONTACTS_REQUESTED_DATA_FIELDS";
-    private static final String EXTRA_PICK_CONTACTS_SELECTION_LIMIT = "android.provider.extra.PICK_CONTACTS_SELECTION_LIMIT";
-
     @PluginMethod
     public void pickContact(PluginCall call) {
         launchContactPicker(call);
@@ -495,28 +488,13 @@ public class CapacitorContactsPlugin extends Plugin {
 
         currentPickerCall = call;
         currentPickerProperty = property;
-        startActivityForResult(call, createPickIntent(call, property), PICK_CONTACT_REQUEST);
+        startActivityForResult(call, createPickIntent(property), PICK_CONTACT_REQUEST);
     }
 
-    private Intent createPickIntent(PluginCall call, String property) {
+    private Intent createPickIntent(String property) {
         if (property != null) {
             return new Intent(Intent.ACTION_PICK, contentUriForProperty(property));
         }
-
-        if (android.os.Build.VERSION.SDK_INT >= ANDROID_API_17) {
-            Intent intent = new Intent(ACTION_PICK_CONTACTS);
-            intent.putStringArrayListExtra(EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS, requestedMimeTypes(call));
-            boolean multiple = Boolean.TRUE.equals(call.getBoolean("multiple", false));
-            if (!multiple) {
-                intent.putExtra(EXTRA_PICK_CONTACTS_SELECTION_LIMIT, 1);
-            } else {
-                intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true);
-            }
-            if (intent.resolveActivity(getContext().getPackageManager()) != null) {
-                return intent;
-            }
-        }
-
         return new Intent(Intent.ACTION_PICK, ContactsContract.Contacts.CONTENT_URI);
     }
 
@@ -533,23 +511,6 @@ public class CapacitorContactsPlugin extends Plugin {
         return null;
     }
 
-    private ArrayList<String> requestedMimeTypes(PluginCall call) {
-        Set<String> fields = parseFieldsArray(call);
-        if (fields != null) {
-            return new ArrayList<>(getMimeTypesForFields(fields));
-        }
-        ArrayList<String> mimeTypes = new ArrayList<>();
-        mimeTypes.add(ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE);
-        mimeTypes.add(ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE);
-        mimeTypes.add(ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE);
-        mimeTypes.add(ContactsContract.CommonDataKinds.StructuredPostal.CONTENT_ITEM_TYPE);
-        mimeTypes.add(ContactsContract.CommonDataKinds.Organization.CONTENT_ITEM_TYPE);
-        mimeTypes.add(ContactsContract.CommonDataKinds.Note.CONTENT_ITEM_TYPE);
-        mimeTypes.add(ContactsContract.CommonDataKinds.Event.CONTENT_ITEM_TYPE);
-        mimeTypes.add(ContactsContract.CommonDataKinds.Website.CONTENT_ITEM_TYPE);
-        return mimeTypes;
-    }
-
     @PluginMethod
     public void displayContactById(PluginCall call) {
         String contactId = call.getString("id");
@@ -652,12 +613,7 @@ public class CapacitorContactsPlugin extends Plugin {
         String property = currentPickerProperty;
         currentPickerProperty = null;
 
-        if (isSessionUri(uri)) {
-            call.resolve(new JSObject().put("contacts", contactsFromSessionUri(uri, fieldsForPickedContact(call))));
-            return;
-        }
-
-        if (property != null || isDataRowUri(uri)) {
+        if (property != null) {
             JSObject contact = contactFromDataRowUri(uri, property);
             JSArray contacts = new JSArray();
             if (contact != null) {
@@ -667,7 +623,7 @@ public class CapacitorContactsPlugin extends Plugin {
             return;
         }
 
-        call.resolve(new JSObject().put("contacts", contactsFromContactUri(uri, fieldsForPickedContact(call))));
+        call.resolve(new JSObject().put("contacts", contactsFromFullPick(uri, fieldsForPickedContact(call))));
     }
 
     private Set<String> fieldsForPickedContact(PluginCall call) {
@@ -686,9 +642,72 @@ public class CapacitorContactsPlugin extends Plugin {
         return authority != null && authority.contains("picker");
     }
 
-    private boolean isDataRowUri(Uri uri) {
-        List<String> segments = uri.getPathSegments();
-        return segments != null && !segments.isEmpty() && "data".equals(segments.get(0));
+    private JSArray contactsFromFullPick(Uri uri, Set<String> fields) {
+        JSArray contacts = new JSArray();
+        List<String> ids = contactIdsFromPickerUri(uri);
+
+        if (hasReadPermission()) {
+            for (String contactId : ids) {
+                try {
+                    ContactBuilder builder = fetchContact(contactId, fields);
+                    if (builder != null) {
+                        if (builder.displayName == null) {
+                            builder.displayName = builder.fullName;
+                        }
+                        contacts.put(builder.toJSObject(fields));
+                    }
+                } catch (Exception ex) {
+                    android.util.Log.w("CapacitorContacts", "Failed to fetch picked contact", ex);
+                }
+            }
+        }
+
+        if (contacts.length() > 0) {
+            return contacts;
+        }
+
+        if (isSessionUri(uri)) {
+            return contactsFromSessionUri(uri, fields);
+        }
+
+        if (!ids.isEmpty()) {
+            ContactBuilder builder = new ContactBuilder(ids.get(0));
+            String displayName = resolveDisplayNameFromUri(uri);
+            builder.displayName = displayName;
+            builder.fullName = displayName;
+            Set<String> thinFields = new HashSet<>();
+            thinFields.add("id");
+            thinFields.add("displayName");
+            contacts.put(builder.toJSObject(thinFields));
+        }
+        return contacts;
+    }
+
+    private List<String> contactIdsFromPickerUri(Uri uri) {
+        List<String> ids = new ArrayList<>();
+        if (isSessionUri(uri)) {
+            Set<String> seen = new HashSet<>();
+            ContentResolver resolver = getContext().getContentResolver();
+            try (Cursor cursor = resolver.query(uri, null, null, null, null)) {
+                if (cursor != null) {
+                    while (cursor.moveToNext()) {
+                        String contactId = getStringColumn(cursor, ContactsContract.Data.CONTACT_ID);
+                        if (contactId != null && seen.add(contactId)) {
+                            ids.add(contactId);
+                        }
+                    }
+                }
+            } catch (Exception ex) {
+                android.util.Log.w("CapacitorContacts", "Failed to read picker session contact ids", ex);
+            }
+            return ids;
+        }
+
+        String contactId = getContactIdFromUri(uri);
+        if (contactId != null) {
+            ids.add(contactId);
+        }
+        return ids;
     }
 
     private JSArray contactsFromSessionUri(Uri sessionUri, Set<String> fields) {
@@ -754,40 +773,6 @@ public class CapacitorContactsPlugin extends Plugin {
         }
     }
 
-    private JSArray contactsFromContactUri(Uri contactUri, Set<String> fields) {
-        JSArray contacts = new JSArray();
-        String contactId = getContactIdFromUri(contactUri);
-        if (contactId == null) {
-            return contacts;
-        }
-
-        if (hasReadPermission()) {
-            try {
-                ContactBuilder builder = fetchContact(contactId, fields);
-                if (builder != null) {
-                    if (builder.displayName == null) {
-                        builder.displayName = builder.fullName;
-                    }
-                    contacts.put(builder.toJSObject(fields));
-                }
-                return contacts;
-            } catch (Exception ex) {
-                android.util.Log.w("CapacitorContacts", "Failed to fetch picked contact", ex);
-            }
-        }
-
-        ContactBuilder builder = new ContactBuilder(contactId);
-        String displayName = resolveDisplayNameFromUri(contactUri);
-        builder.displayName = displayName;
-        builder.fullName = displayName;
-        Set<String> thinFields = new HashSet<>();
-        thinFields.add("id");
-        thinFields.add("displayName");
-        thinFields.add("fullName");
-        contacts.put(builder.toJSObject(thinFields));
-        return contacts;
-    }
-
     private String resolveDisplayNameFromUri(Uri contactUri) {
         ContentResolver resolver = getContext().getContentResolver();
         try (

package/dist/docs.json

@@ -475,7 +475,7 @@
             "text": "1.0.0"
           }
         ],
-        "docs": "Pick a single contact using the native contact picker.\n\nSame options as {@link pickContacts}. Pass `property` to select one phone\nnumber, email address, or postal address without `READ_CONTACTS` on Android.",
+        "docs": "Pick a single contact using the native contact picker.\n\nSame options as {@link pickContacts}. Without `property`, Android still\nreturns the full contact when `READ_CONTACTS` is granted.",
         "complexTypes": [
           "PickContactsResult",
           "PickContactOptions",
@@ -508,7 +508,7 @@
             "text": "1.0.0"
           }
         ],
-        "docs": "Pick one or more contacts using the native contact picker.\n\nOn iOS this never requires a contacts permission.\n\nOn Android, pass `property` to select a single phone number, email address,\nor postal address with no `READ_CONTACTS` permission. That works on every\nAndroid version and is the way to ship without declaring the permission\nwhen targeting Android 17 (API 37) or later.\n\nPicking a full contact without `property` still needs `READ_CONTACTS` below\nAndroid 17, because the picker URI exposes no phone, email, or structured\nname. On Android 17 and later the system contact picker returns a session\nURI the plugin reads without that permission.",
+        "docs": "Pick one or more contacts using the native contact picker.\n\nOn iOS this never requires a contacts permission.\n\nOn Android, `pickContacts()` without `property` still returns the full\ncontact when the app has `READ_CONTACTS`. Pass `property` only when you\nwant a single phone number, email address, or postal address and can omit\nthat permission (required to target Android 17 / API 37 without a Play\nConsole contacts declaration).",
         "complexTypes": [
           "PickContactsResult",
           "PickContactsOptions"

package/dist/esm/definitions.d.ts

@@ -955,8 +955,8 @@ export interface CapacitorContactsPlugin {
     /**
      * Pick a single contact using the native contact picker.
      *
-     * Same options as {@link pickContacts}. Pass `property` to select one phone
-     * number, email address, or postal address without `READ_CONTACTS` on Android.
+     * Same options as {@link pickContacts}. Without `property`, Android still
+     * returns the full contact when `READ_CONTACTS` is granted.
      *
      * @param options - Optional fields to retrieve and picker configuration
      * @returns Promise that resolves with the selected contact(s)
@@ -968,15 +968,11 @@ export interface CapacitorContactsPlugin {
      *
      * On iOS this never requires a contacts permission.
      *
-     * On Android, pass `property` to select a single phone number, email address,
-     * or postal address with no `READ_CONTACTS` permission. That works on every
-     * Android version and is the way to ship without declaring the permission
-     * when targeting Android 17 (API 37) or later.
-     *
-     * Picking a full contact without `property` still needs `READ_CONTACTS` below
-     * Android 17, because the picker URI exposes no phone, email, or structured
-     * name. On Android 17 and later the system contact picker returns a session
-     * URI the plugin reads without that permission.
+     * On Android, `pickContacts()` without `property` still returns the full
+     * contact when the app has `READ_CONTACTS`. Pass `property` only when you
+     * want a single phone number, email address, or postal address and can omit
+     * that permission (required to target Android 17 / API 37 without a Play
+     * Console contacts declaration).
      *
      * @param options - Optional fields to retrieve and picker configuration
      * @returns Promise that resolves with the selected contacts

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAuxBA;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,eAqBX;AArBD,WAAY,eAAe;IACzB;;;;OAIG;IACH,8CAA2B,CAAA;IAE3B;;;;OAIG;IACH,gDAA6B,CAAA;IAE7B;;;;OAIG;IACH,kDAA+B,CAAA;AACjC,CAAC,EArBW,eAAe,KAAf,eAAe,QAqB1B","sourcesContent":["import type { PermissionState } from '@capacitor/core';\n\n/**\n * Permission state for contacts access, including the 'limited' state for iOS 18+.\n *\n * @since 1.0.0\n */\nexport type ContactsPermissionState = PermissionState | 'limited';\n\n/**\n * Type of contacts permission to request.\n *\n * @since 1.0.0\n */\nexport type ContactsPermissionType = 'readContacts' | 'writeContacts';\n\n/**\n * Status of contacts permissions.\n *\n * @since 1.0.0\n */\nexport interface PermissionStatus {\n  /**\n   * Permission state for reading contacts.\n   *\n   * @since 1.0.0\n   */\n  readContacts: ContactsPermissionState;\n\n  /**\n   * Permission state for writing contacts.\n   *\n   * @since 1.0.0\n   */\n  writeContacts: ContactsPermissionState;\n}\n\n/**\n * Options for requesting contacts permissions.\n *\n * @since 1.0.0\n */\nexport interface RequestPermissionsOptions {\n  /**\n   * Specific permissions to request. If not provided, all permissions will be requested.\n   *\n   * @since 1.0.0\n   */\n  permissions?: ContactsPermissionType[];\n}\n\n/**\n * Account information for a contact.\n *\n * @since 1.0.0\n */\nexport interface Account {\n  /**\n   * The name of the account.\n   *\n   * @since 1.0.0\n   */\n  name: string;\n\n  /**\n   * The type of the account.\n   *\n   * @since 1.0.0\n   */\n  type?: string;\n}\n\n/**\n * Birthday information for a contact.\n *\n * @since 1.0.0\n */\nexport interface Birthday {\n  /**\n   * The day of the month (1-31).\n   *\n   * @since 1.0.0\n   */\n  day?: number;\n\n  /**\n   * The month (1-12).\n   *\n   * @since 1.0.0\n   */\n  month?: number;\n\n  /**\n   * The year.\n   *\n   * @since 1.0.0\n   */\n  year?: number;\n}\n\n/**\n * Type of email address.\n *\n * @since 1.0.0\n */\nexport type EmailAddressType = 'CUSTOM' | 'HOME' | 'ICLOUD' | 'OTHER' | 'WORK';\n\n/**\n * Email address information for a contact.\n *\n * @since 1.0.0\n */\nexport interface EmailAddress {\n  /**\n   * The email address value.\n   *\n   * @since 1.0.0\n   */\n  value: string;\n\n  /**\n   * The type of email address.\n   *\n   * @since 1.0.0\n   */\n  type?: EmailAddressType;\n\n  /**\n   * Custom label for the email address.\n   *\n   * @since 1.0.0\n   */\n  label?: string;\n\n  /**\n   * Whether this is the primary email address.\n   *\n   * @since 1.0.0\n   */\n  isPrimary?: boolean;\n}\n\n/**\n * Type of phone number.\n *\n * @since 1.0.0\n */\nexport type PhoneNumberType =\n  | 'ASSISTANT'\n  | 'CALLBACK'\n  | 'CAR'\n  | 'COMPANY_MAIN'\n  | 'CUSTOM'\n  | 'FAX_HOME'\n  | 'FAX_WORK'\n  | 'HOME'\n  | 'HOME_FAX'\n  | 'ISDN'\n  | 'MAIN'\n  | 'MMS'\n  | 'MOBILE'\n  | 'OTHER'\n  | 'OTHER_FAX'\n  | 'PAGER'\n  | 'RADIO'\n  | 'TELEX'\n  | 'TTY_TDD'\n  | 'WORK'\n  | 'WORK_MOBILE'\n  | 'WORK_PAGER';\n\n/**\n * Phone number information for a contact.\n *\n * @since 1.0.0\n */\nexport interface PhoneNumber {\n  /**\n   * The phone number value.\n   *\n   * @since 1.0.0\n   */\n  value: string;\n\n  /**\n   * The type of phone number.\n   *\n   * @since 1.0.0\n   */\n  type?: PhoneNumberType;\n\n  /**\n   * Custom label for the phone number.\n   *\n   * @since 1.0.0\n   */\n  label?: string;\n\n  /**\n   * Whether this is the primary phone number.\n   *\n   * @since 1.0.0\n   */\n  isPrimary?: boolean;\n}\n\n/**\n * Type of postal address.\n *\n * @since 1.0.0\n */\nexport type PostalAddressType = 'CUSTOM' | 'HOME' | 'OTHER' | 'WORK';\n\n/**\n * Postal address information for a contact.\n *\n * @since 1.0.0\n */\nexport interface PostalAddress {\n  /**\n   * The city name.\n   *\n   * @since 1.0.0\n   */\n  city?: string;\n\n  /**\n   * The country name.\n   *\n   * @since 1.0.0\n   */\n  country?: string;\n\n  /**\n   * The formatted address string.\n   *\n   * @since 1.0.0\n   */\n  formatted?: string;\n\n  /**\n   * The ISO country code.\n   *\n   * @since 1.0.0\n   */\n  isoCountryCode?: string;\n\n  /**\n   * Whether this is the primary postal address.\n   *\n   * @since 1.0.0\n   */\n  isPrimary?: boolean;\n\n  /**\n   * Custom label for the postal address.\n   *\n   * @since 1.0.0\n   */\n  label?: string;\n\n  /**\n   * The neighborhood name.\n   *\n   * @since 1.0.0\n   */\n  neighborhood?: string;\n\n  /**\n   * The postal code.\n   *\n   * @since 1.0.0\n   */\n  postalCode?: string;\n\n  /**\n   * The state or province name.\n   *\n   * @since 1.0.0\n   */\n  state?: string;\n\n  /**\n   * The street address.\n   *\n   * @since 1.0.0\n   */\n  street?: string;\n\n  /**\n   * The type of postal address.\n   *\n   * @since 1.0.0\n   */\n  type?: PostalAddressType;\n}\n\n/**\n * Type of URL address.\n *\n * @since 1.0.0\n */\nexport type UrlAddressType = 'BLOG' | 'CUSTOM' | 'FTP' | 'HOME' | 'HOMEPAGE' | 'OTHER' | 'PROFILE' | 'SCHOOL' | 'WORK';\n\n/**\n * URL address information for a contact.\n *\n * @since 1.0.0\n */\nexport interface UrlAddress {\n  /**\n   * The URL value.\n   *\n   * @since 1.0.0\n   */\n  value: string;\n\n  /**\n   * The type of URL.\n   *\n   * @since 1.0.0\n   */\n  type?: UrlAddressType;\n\n  /**\n   * Custom label for the URL.\n   *\n   * @since 1.0.0\n   */\n  label?: string;\n}\n\n/**\n * Contact information.\n *\n * @since 1.0.0\n */\nexport interface Contact {\n  /**\n   * Unique identifier for the contact.\n   *\n   * @since 1.0.0\n   */\n  id?: string;\n\n  /**\n   * Formatted name shown by the device for this contact.\n   *\n   * Derived from `CNContactFormatter` on iOS and `DISPLAY_NAME` on Android.\n   * Read-only: setting this when creating or updating a contact has no effect.\n   * Use `givenName` and `familyName` to write a name.\n   *\n   * @since 8.1.0\n   */\n  displayName?: string;\n\n  /**\n   * Account information for the contact.\n   *\n   * @since 1.0.0\n   */\n  account?: Account;\n\n  /**\n   * Birthday information for the contact.\n   *\n   * @since 1.0.0\n   */\n  birthday?: Birthday;\n\n  /**\n   * Email addresses for the contact.\n   *\n   * @since 1.0.0\n   */\n  emailAddresses?: EmailAddress[];\n\n  /**\n   * Family name (last name) of the contact.\n   *\n   * @since 1.0.0\n   */\n  familyName?: string;\n\n  /**\n   * Full name of the contact.\n   *\n   * @since 1.0.0\n   */\n  fullName?: string;\n\n  /**\n   * Given name (first name) of the contact.\n   *\n   * @since 1.0.0\n   */\n  givenName?: string;\n\n  /**\n   * Group IDs the contact belongs to.\n   *\n   * @since 1.0.0\n   */\n  groupIds?: string[];\n\n  /**\n   * Job title of the contact.\n   *\n   * @since 1.0.0\n   */\n  jobTitle?: string;\n\n  /**\n   * Middle name of the contact.\n   *\n   * @since 1.0.0\n   */\n  middleName?: string;\n\n  /**\n   * Name prefix (e.g., \"Dr.\", \"Mr.\", \"Ms.\") of the contact.\n   *\n   * @since 1.0.0\n   */\n  namePrefix?: string;\n\n  /**\n   * Name suffix (e.g., \"Jr.\", \"Sr.\", \"III\") of the contact.\n   *\n   * @since 1.0.0\n   */\n  nameSuffix?: string;\n\n  /**\n   * Notes about the contact.\n   *\n   * @since 1.0.0\n   */\n  note?: string;\n\n  /**\n   * Organization name of the contact.\n   *\n   * @since 1.0.0\n   */\n  organizationName?: string;\n\n  /**\n   * Phone numbers for the contact.\n   *\n   * @since 1.0.0\n   */\n  phoneNumbers?: PhoneNumber[];\n\n  /**\n   * Base64-encoded photo of the contact.\n   *\n   * @since 1.0.0\n   */\n  photo?: string;\n\n  /**\n   * Postal addresses for the contact.\n   *\n   * @since 1.0.0\n   */\n  postalAddresses?: PostalAddress[];\n\n  /**\n   * URL addresses for the contact.\n   *\n   * @since 1.0.0\n   */\n  urlAddresses?: UrlAddress[];\n}\n\n/**\n * Field names available in a Contact object.\n *\n * @since 1.0.0\n */\nexport type ContactField = keyof Contact;\n\n/**\n * Result from counting contacts.\n *\n * @since 1.0.0\n */\nexport interface CountContactsResult {\n  /**\n   * Total number of contacts.\n   *\n   * @since 1.0.0\n   */\n  count: number;\n}\n\n/**\n * Options for creating a contact.\n *\n * @since 1.0.0\n */\nexport interface CreateContactOptions {\n  /**\n   * Contact information to create. The 'id' field will be generated automatically.\n   *\n   * @since 1.0.0\n   */\n  contact: Omit<Contact, 'id'>;\n}\n\n/**\n * Result from creating a contact.\n *\n * @since 1.0.0\n */\nexport interface CreateContactResult {\n  /**\n   * The ID of the newly created contact.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Options for displaying the native create contact UI.\n *\n * @since 1.0.0\n */\nexport interface DisplayCreateContactOptions {\n  /**\n   * Optional pre-filled contact information for the create UI.\n   *\n   * @since 1.0.0\n   */\n  contact?: Omit<Contact, 'id'>;\n}\n\n/**\n * Result from displaying the native create contact UI.\n *\n * @since 1.0.0\n */\nexport interface DisplayCreateContactResult {\n  /**\n   * The ID of the created contact, if one was created. Undefined if the user cancelled.\n   *\n   * @since 1.0.0\n   */\n  id?: string;\n}\n\n/**\n * Options for displaying a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface DisplayContactByIdOptions {\n  /**\n   * The ID of the contact to display.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Options for displaying the native update contact UI.\n *\n * @since 1.0.0\n */\nexport interface DisplayUpdateContactByIdOptions {\n  /**\n   * The ID of the contact to update.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Result from getting accounts.\n *\n * @since 1.0.0\n */\nexport interface GetAccountsResult {\n  /**\n   * List of accounts available on the device.\n   *\n   * @since 1.0.0\n   */\n  accounts: Account[];\n}\n\n/**\n * Options for getting a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface GetContactByIdOptions {\n  /**\n   * The ID of the contact to retrieve.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n\n  /**\n   * Optional list of specific fields to retrieve. If not specified, all fields are returned.\n   *\n   * @since 1.0.0\n   */\n  fields?: ContactField[];\n}\n\n/**\n * Result from getting a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface GetContactByIdResult {\n  /**\n   * The contact, or null if not found.\n   *\n   * @since 1.0.0\n   */\n  contact: Contact | null;\n}\n\n/**\n * Options for getting contacts.\n *\n * @since 1.0.0\n */\nexport interface GetContactsOptions {\n  /**\n   * Optional list of specific fields to retrieve. If not specified, all fields are returned.\n   *\n   * @since 1.0.0\n   */\n  fields?: ContactField[];\n\n  /**\n   * Maximum number of contacts to return.\n   *\n   * @since 1.0.0\n   */\n  limit?: number;\n\n  /**\n   * Number of contacts to skip before starting to return results.\n   *\n   * @since 1.0.0\n   */\n  offset?: number;\n}\n\n/**\n * Result from getting contacts.\n *\n * @since 1.0.0\n */\nexport interface GetContactsResult {\n  /**\n   * List of contacts.\n   *\n   * @since 1.0.0\n   */\n  contacts: Contact[];\n}\n\n/**\n * Options for getting a group by ID.\n *\n * @since 1.0.0\n */\nexport interface GetGroupByIdOptions {\n  /**\n   * The ID of the group to retrieve.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Result from getting a group by ID.\n *\n * @since 1.0.0\n */\nexport interface GetGroupByIdResult {\n  /**\n   * The group, or null if not found.\n   *\n   * @since 1.0.0\n   */\n  group: Group | null;\n}\n\n/**\n * Result from getting groups.\n *\n * @since 1.0.0\n */\nexport interface GetGroupsResult {\n  /**\n   * List of groups.\n   *\n   * @since 1.0.0\n   */\n  groups: Group[];\n}\n\n/**\n * Contact group information.\n *\n * @since 1.0.0\n */\nexport interface Group {\n  /**\n   * Unique identifier for the group.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n\n  /**\n   * Name of the group.\n   *\n   * @since 1.0.0\n   */\n  name: string;\n}\n\n/**\n * Options for creating a group.\n *\n * @since 1.0.0\n */\nexport interface CreateGroupOptions {\n  /**\n   * Group information to create. The 'id' field will be generated automatically.\n   *\n   * @since 1.0.0\n   */\n  group: Omit<Group, 'id'>;\n}\n\n/**\n * Result from creating a group.\n *\n * @since 1.0.0\n */\nexport interface CreateGroupResult {\n  /**\n   * The ID of the newly created group.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Options for deleting a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface DeleteContactByIdOptions {\n  /**\n   * The ID of the contact to delete.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Options for deleting a group by ID.\n *\n * @since 1.0.0\n */\nexport interface DeleteGroupByIdOptions {\n  /**\n   * The ID of the group to delete.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Contact property that the native picker can select without `READ_CONTACTS`.\n *\n * Use with {@link PickContactsOptions.property} so the user picks one phone\n * number, email address, or postal address instead of a full contact record.\n *\n * @since 8.1.0\n */\nexport enum ContactProperty {\n  /**\n   * A single phone number.\n   *\n   * @since 8.1.0\n   */\n  PhoneNumber = 'phoneNumber',\n\n  /**\n   * A single email address.\n   *\n   * @since 8.1.0\n   */\n  EmailAddress = 'emailAddress',\n\n  /**\n   * A single postal address.\n   *\n   * @since 8.1.0\n   */\n  PostalAddress = 'postalAddress',\n}\n\n/**\n * Options for picking contacts using the native contact picker.\n *\n * @since 1.0.0\n */\nexport interface PickContactsOptions {\n  /**\n   * Optional list of specific fields to retrieve. If not specified, all fields are returned.\n   *\n   * Ignored when {@link PickContactsOptions.property} is set. The result then\n   * contains only `id`, `displayName`, and the selected property.\n   *\n   * @since 1.0.0\n   */\n  fields?: ContactField[];\n\n  /**\n   * Whether to allow selecting multiple contacts. Default is false.\n   *\n   * Ignored when {@link PickContactsOptions.property} is set. Property picking\n   * always returns a single value.\n   *\n   * @since 1.0.0\n   */\n  multiple?: boolean;\n\n  /**\n   * Restrict the picker to a single contact property.\n   *\n   * On Android this launches the picker against the phone, email, or postal\n   * address table and reads the granted data row. That requires no\n   * `READ_CONTACTS` permission on any Android version, which is required for\n   * apps that only pick a contact detail and target Android 17 (API 37) or\n   * later under the Google Play Contacts Permissions policy.\n   *\n   * On iOS the picker lets the user choose one phone number, email address,\n   * or postal address. It never requires a contacts permission.\n   *\n   * @since 8.1.0\n   */\n  property?: ContactProperty;\n}\n\n/**\n * Result from picking contacts.\n *\n * @since 1.0.0\n */\nexport interface PickContactsResult {\n  /**\n   * List of selected contacts.\n   *\n   * @since 1.0.0\n   */\n  contacts: Contact[];\n}\n\n/**\n * Alias for PickContactsOptions.\n *\n * @since 1.0.0\n */\nexport type PickContactOptions = PickContactsOptions;\n\n/**\n * Alias for PickContactsResult.\n *\n * @since 1.0.0\n */\nexport type PickContactResult = PickContactsResult;\n\n/**\n * Options for updating a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface UpdateContactByIdOptions {\n  /**\n   * The ID of the contact to update.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n\n  /**\n   * Updated contact information.\n   *\n   * @since 1.0.0\n   */\n  contact: Omit<Contact, 'id'>;\n}\n\n/**\n * Result from checking if the plugin is supported on the platform.\n *\n * @since 1.0.0\n */\nexport interface IsSupportedResult {\n  /**\n   * Whether the plugin is supported on this platform.\n   *\n   * @since 1.0.0\n   */\n  isSupported: boolean;\n}\n\n/**\n * Result from checking if contacts are available on the device.\n *\n * @since 1.0.0\n */\nexport interface IsAvailableResult {\n  /**\n   * Whether contacts are available on this device.\n   *\n   * @since 1.0.0\n   */\n  isAvailable: boolean;\n}\n\n/**\n * Capacitor Contacts Plugin interface for managing device contacts.\n *\n * @since 1.0.0\n */\nexport interface CapacitorContactsPlugin {\n  /**\n   * Count the total number of contacts on the device.\n   *\n   * @returns Promise that resolves with the total count of contacts\n   * @since 1.0.0\n   */\n  countContacts(): Promise<CountContactsResult>;\n\n  /**\n   * Create a new contact programmatically.\n   *\n   * @param options - The contact information to create\n   * @returns Promise that resolves with the ID of the newly created contact\n   * @since 1.0.0\n   */\n  createContact(options: CreateContactOptions): Promise<CreateContactResult>;\n\n  /**\n   * Create a new contact group.\n   *\n   * @param options - The group information to create\n   * @returns Promise that resolves with the ID of the newly created group\n   * @since 1.0.0\n   */\n  createGroup(options: CreateGroupOptions): Promise<CreateGroupResult>;\n\n  /**\n   * Delete a contact by ID.\n   *\n   * @param options - The ID of the contact to delete\n   * @returns Promise that resolves when the contact is deleted\n   * @since 1.0.0\n   */\n  deleteContactById(options: DeleteContactByIdOptions): Promise<void>;\n\n  /**\n   * Delete a group by ID.\n   *\n   * @param options - The ID of the group to delete\n   * @returns Promise that resolves when the group is deleted\n   * @since 1.0.0\n   */\n  deleteGroupById(options: DeleteGroupByIdOptions): Promise<void>;\n\n  /**\n   * Display a contact using the native contact viewer.\n   *\n   * @param options - The ID of the contact to display\n   * @returns Promise that resolves when the viewer is closed\n   * @since 1.0.0\n   */\n  displayContactById(options: DisplayContactByIdOptions): Promise<void>;\n\n  /**\n   * Display the native create contact UI.\n   *\n   * @param options - Optional pre-filled contact information\n   * @returns Promise that resolves with the ID of the created contact, or undefined if cancelled\n   * @since 1.0.0\n   */\n  displayCreateContact(options?: DisplayCreateContactOptions): Promise<DisplayCreateContactResult>;\n\n  /**\n   * Display the native update contact UI for a specific contact.\n   *\n   * @param options - The ID of the contact to update\n   * @returns Promise that resolves when the update UI is closed\n   * @since 1.0.0\n   */\n  displayUpdateContactById(options: DisplayUpdateContactByIdOptions): Promise<void>;\n\n  /**\n   * Get all accounts available on the device.\n   *\n   * @returns Promise that resolves with the list of accounts\n   * @since 1.0.0\n   */\n  getAccounts(): Promise<GetAccountsResult>;\n\n  /**\n   * Get a specific contact by ID.\n   *\n   * @param options - The ID and optional fields to retrieve\n   * @returns Promise that resolves with the contact, or null if not found\n   * @since 1.0.0\n   */\n  getContactById(options: GetContactByIdOptions): Promise<GetContactByIdResult>;\n\n  /**\n   * Get all contacts from the device.\n   *\n   * @param options - Optional filters and pagination options\n   * @returns Promise that resolves with the list of contacts\n   * @since 1.0.0\n   */\n  getContacts(options?: GetContactsOptions): Promise<GetContactsResult>;\n\n  /**\n   * Get a specific group by ID.\n   *\n   * @param options - The ID of the group to retrieve\n   * @returns Promise that resolves with the group, or null if not found\n   * @since 1.0.0\n   */\n  getGroupById(options: GetGroupByIdOptions): Promise<GetGroupByIdResult>;\n\n  /**\n   * Get all contact groups.\n   *\n   * @returns Promise that resolves with the list of groups\n   * @since 1.0.0\n   */\n  getGroups(): Promise<GetGroupsResult>;\n\n  /**\n   * Check if contacts are available on the device.\n   *\n   * @returns Promise that resolves with availability status\n   * @since 1.0.0\n   */\n  isAvailable(): Promise<IsAvailableResult>;\n\n  /**\n   * Check if the plugin is supported on the current platform.\n   *\n   * @returns Promise that resolves with support status\n   * @since 1.0.0\n   */\n  isSupported(): Promise<IsSupportedResult>;\n\n  /**\n   * Open the device's contacts settings.\n   *\n   * @returns Promise that resolves when the settings are opened\n   * @since 1.0.0\n   */\n  openSettings(): Promise<void>;\n\n  /**\n   * Pick a single contact using the native contact picker.\n   *\n   * Same options as {@link pickContacts}. Pass `property` to select one phone\n   * number, email address, or postal address without `READ_CONTACTS` on Android.\n   *\n   * @param options - Optional fields to retrieve and picker configuration\n   * @returns Promise that resolves with the selected contact(s)\n   * @since 1.0.0\n   */\n  pickContact(options?: PickContactOptions): Promise<PickContactResult>;\n\n  /**\n   * Pick one or more contacts using the native contact picker.\n   *\n   * On iOS this never requires a contacts permission.\n   *\n   * On Android, pass `property` to select a single phone number, email address,\n   * or postal address with no `READ_CONTACTS` permission. That works on every\n   * Android version and is the way to ship without declaring the permission\n   * when targeting Android 17 (API 37) or later.\n   *\n   * Picking a full contact without `property` still needs `READ_CONTACTS` below\n   * Android 17, because the picker URI exposes no phone, email, or structured\n   * name. On Android 17 and later the system contact picker returns a session\n   * URI the plugin reads without that permission.\n   *\n   * @param options - Optional fields to retrieve and picker configuration\n   * @returns Promise that resolves with the selected contacts\n   * @since 1.0.0\n   */\n  pickContacts(options?: PickContactsOptions): Promise<PickContactsResult>;\n\n  /**\n   * Update an existing contact by ID.\n   *\n   * @param options - The ID and updated contact information\n   * @returns Promise that resolves when the contact is updated\n   * @since 1.0.0\n   */\n  updateContactById(options: UpdateContactByIdOptions): Promise<void>;\n\n  /**\n   * Check the current permission status for contacts.\n   *\n   * @returns Promise that resolves with the current permission status\n   * @since 1.0.0\n   */\n  checkPermissions(): Promise<PermissionStatus>;\n\n  /**\n   * Request permissions to access contacts.\n   *\n   * @param options - Optional specific permissions to request\n   * @returns Promise that resolves with the updated permission status\n   * @since 1.0.0\n   */\n  requestPermissions(options?: RequestPermissionsOptions): Promise<PermissionStatus>;\n\n  /**\n   * Get the native Capacitor plugin version.\n   *\n   * @returns Promise that resolves with the plugin version\n   * @since 1.0.0\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAuxBA;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,eAqBX;AArBD,WAAY,eAAe;IACzB;;;;OAIG;IACH,8CAA2B,CAAA;IAE3B;;;;OAIG;IACH,gDAA6B,CAAA;IAE7B;;;;OAIG;IACH,kDAA+B,CAAA;AACjC,CAAC,EArBW,eAAe,KAAf,eAAe,QAqB1B","sourcesContent":["import type { PermissionState } from '@capacitor/core';\n\n/**\n * Permission state for contacts access, including the 'limited' state for iOS 18+.\n *\n * @since 1.0.0\n */\nexport type ContactsPermissionState = PermissionState | 'limited';\n\n/**\n * Type of contacts permission to request.\n *\n * @since 1.0.0\n */\nexport type ContactsPermissionType = 'readContacts' | 'writeContacts';\n\n/**\n * Status of contacts permissions.\n *\n * @since 1.0.0\n */\nexport interface PermissionStatus {\n  /**\n   * Permission state for reading contacts.\n   *\n   * @since 1.0.0\n   */\n  readContacts: ContactsPermissionState;\n\n  /**\n   * Permission state for writing contacts.\n   *\n   * @since 1.0.0\n   */\n  writeContacts: ContactsPermissionState;\n}\n\n/**\n * Options for requesting contacts permissions.\n *\n * @since 1.0.0\n */\nexport interface RequestPermissionsOptions {\n  /**\n   * Specific permissions to request. If not provided, all permissions will be requested.\n   *\n   * @since 1.0.0\n   */\n  permissions?: ContactsPermissionType[];\n}\n\n/**\n * Account information for a contact.\n *\n * @since 1.0.0\n */\nexport interface Account {\n  /**\n   * The name of the account.\n   *\n   * @since 1.0.0\n   */\n  name: string;\n\n  /**\n   * The type of the account.\n   *\n   * @since 1.0.0\n   */\n  type?: string;\n}\n\n/**\n * Birthday information for a contact.\n *\n * @since 1.0.0\n */\nexport interface Birthday {\n  /**\n   * The day of the month (1-31).\n   *\n   * @since 1.0.0\n   */\n  day?: number;\n\n  /**\n   * The month (1-12).\n   *\n   * @since 1.0.0\n   */\n  month?: number;\n\n  /**\n   * The year.\n   *\n   * @since 1.0.0\n   */\n  year?: number;\n}\n\n/**\n * Type of email address.\n *\n * @since 1.0.0\n */\nexport type EmailAddressType = 'CUSTOM' | 'HOME' | 'ICLOUD' | 'OTHER' | 'WORK';\n\n/**\n * Email address information for a contact.\n *\n * @since 1.0.0\n */\nexport interface EmailAddress {\n  /**\n   * The email address value.\n   *\n   * @since 1.0.0\n   */\n  value: string;\n\n  /**\n   * The type of email address.\n   *\n   * @since 1.0.0\n   */\n  type?: EmailAddressType;\n\n  /**\n   * Custom label for the email address.\n   *\n   * @since 1.0.0\n   */\n  label?: string;\n\n  /**\n   * Whether this is the primary email address.\n   *\n   * @since 1.0.0\n   */\n  isPrimary?: boolean;\n}\n\n/**\n * Type of phone number.\n *\n * @since 1.0.0\n */\nexport type PhoneNumberType =\n  | 'ASSISTANT'\n  | 'CALLBACK'\n  | 'CAR'\n  | 'COMPANY_MAIN'\n  | 'CUSTOM'\n  | 'FAX_HOME'\n  | 'FAX_WORK'\n  | 'HOME'\n  | 'HOME_FAX'\n  | 'ISDN'\n  | 'MAIN'\n  | 'MMS'\n  | 'MOBILE'\n  | 'OTHER'\n  | 'OTHER_FAX'\n  | 'PAGER'\n  | 'RADIO'\n  | 'TELEX'\n  | 'TTY_TDD'\n  | 'WORK'\n  | 'WORK_MOBILE'\n  | 'WORK_PAGER';\n\n/**\n * Phone number information for a contact.\n *\n * @since 1.0.0\n */\nexport interface PhoneNumber {\n  /**\n   * The phone number value.\n   *\n   * @since 1.0.0\n   */\n  value: string;\n\n  /**\n   * The type of phone number.\n   *\n   * @since 1.0.0\n   */\n  type?: PhoneNumberType;\n\n  /**\n   * Custom label for the phone number.\n   *\n   * @since 1.0.0\n   */\n  label?: string;\n\n  /**\n   * Whether this is the primary phone number.\n   *\n   * @since 1.0.0\n   */\n  isPrimary?: boolean;\n}\n\n/**\n * Type of postal address.\n *\n * @since 1.0.0\n */\nexport type PostalAddressType = 'CUSTOM' | 'HOME' | 'OTHER' | 'WORK';\n\n/**\n * Postal address information for a contact.\n *\n * @since 1.0.0\n */\nexport interface PostalAddress {\n  /**\n   * The city name.\n   *\n   * @since 1.0.0\n   */\n  city?: string;\n\n  /**\n   * The country name.\n   *\n   * @since 1.0.0\n   */\n  country?: string;\n\n  /**\n   * The formatted address string.\n   *\n   * @since 1.0.0\n   */\n  formatted?: string;\n\n  /**\n   * The ISO country code.\n   *\n   * @since 1.0.0\n   */\n  isoCountryCode?: string;\n\n  /**\n   * Whether this is the primary postal address.\n   *\n   * @since 1.0.0\n   */\n  isPrimary?: boolean;\n\n  /**\n   * Custom label for the postal address.\n   *\n   * @since 1.0.0\n   */\n  label?: string;\n\n  /**\n   * The neighborhood name.\n   *\n   * @since 1.0.0\n   */\n  neighborhood?: string;\n\n  /**\n   * The postal code.\n   *\n   * @since 1.0.0\n   */\n  postalCode?: string;\n\n  /**\n   * The state or province name.\n   *\n   * @since 1.0.0\n   */\n  state?: string;\n\n  /**\n   * The street address.\n   *\n   * @since 1.0.0\n   */\n  street?: string;\n\n  /**\n   * The type of postal address.\n   *\n   * @since 1.0.0\n   */\n  type?: PostalAddressType;\n}\n\n/**\n * Type of URL address.\n *\n * @since 1.0.0\n */\nexport type UrlAddressType = 'BLOG' | 'CUSTOM' | 'FTP' | 'HOME' | 'HOMEPAGE' | 'OTHER' | 'PROFILE' | 'SCHOOL' | 'WORK';\n\n/**\n * URL address information for a contact.\n *\n * @since 1.0.0\n */\nexport interface UrlAddress {\n  /**\n   * The URL value.\n   *\n   * @since 1.0.0\n   */\n  value: string;\n\n  /**\n   * The type of URL.\n   *\n   * @since 1.0.0\n   */\n  type?: UrlAddressType;\n\n  /**\n   * Custom label for the URL.\n   *\n   * @since 1.0.0\n   */\n  label?: string;\n}\n\n/**\n * Contact information.\n *\n * @since 1.0.0\n */\nexport interface Contact {\n  /**\n   * Unique identifier for the contact.\n   *\n   * @since 1.0.0\n   */\n  id?: string;\n\n  /**\n   * Formatted name shown by the device for this contact.\n   *\n   * Derived from `CNContactFormatter` on iOS and `DISPLAY_NAME` on Android.\n   * Read-only: setting this when creating or updating a contact has no effect.\n   * Use `givenName` and `familyName` to write a name.\n   *\n   * @since 8.1.0\n   */\n  displayName?: string;\n\n  /**\n   * Account information for the contact.\n   *\n   * @since 1.0.0\n   */\n  account?: Account;\n\n  /**\n   * Birthday information for the contact.\n   *\n   * @since 1.0.0\n   */\n  birthday?: Birthday;\n\n  /**\n   * Email addresses for the contact.\n   *\n   * @since 1.0.0\n   */\n  emailAddresses?: EmailAddress[];\n\n  /**\n   * Family name (last name) of the contact.\n   *\n   * @since 1.0.0\n   */\n  familyName?: string;\n\n  /**\n   * Full name of the contact.\n   *\n   * @since 1.0.0\n   */\n  fullName?: string;\n\n  /**\n   * Given name (first name) of the contact.\n   *\n   * @since 1.0.0\n   */\n  givenName?: string;\n\n  /**\n   * Group IDs the contact belongs to.\n   *\n   * @since 1.0.0\n   */\n  groupIds?: string[];\n\n  /**\n   * Job title of the contact.\n   *\n   * @since 1.0.0\n   */\n  jobTitle?: string;\n\n  /**\n   * Middle name of the contact.\n   *\n   * @since 1.0.0\n   */\n  middleName?: string;\n\n  /**\n   * Name prefix (e.g., \"Dr.\", \"Mr.\", \"Ms.\") of the contact.\n   *\n   * @since 1.0.0\n   */\n  namePrefix?: string;\n\n  /**\n   * Name suffix (e.g., \"Jr.\", \"Sr.\", \"III\") of the contact.\n   *\n   * @since 1.0.0\n   */\n  nameSuffix?: string;\n\n  /**\n   * Notes about the contact.\n   *\n   * @since 1.0.0\n   */\n  note?: string;\n\n  /**\n   * Organization name of the contact.\n   *\n   * @since 1.0.0\n   */\n  organizationName?: string;\n\n  /**\n   * Phone numbers for the contact.\n   *\n   * @since 1.0.0\n   */\n  phoneNumbers?: PhoneNumber[];\n\n  /**\n   * Base64-encoded photo of the contact.\n   *\n   * @since 1.0.0\n   */\n  photo?: string;\n\n  /**\n   * Postal addresses for the contact.\n   *\n   * @since 1.0.0\n   */\n  postalAddresses?: PostalAddress[];\n\n  /**\n   * URL addresses for the contact.\n   *\n   * @since 1.0.0\n   */\n  urlAddresses?: UrlAddress[];\n}\n\n/**\n * Field names available in a Contact object.\n *\n * @since 1.0.0\n */\nexport type ContactField = keyof Contact;\n\n/**\n * Result from counting contacts.\n *\n * @since 1.0.0\n */\nexport interface CountContactsResult {\n  /**\n   * Total number of contacts.\n   *\n   * @since 1.0.0\n   */\n  count: number;\n}\n\n/**\n * Options for creating a contact.\n *\n * @since 1.0.0\n */\nexport interface CreateContactOptions {\n  /**\n   * Contact information to create. The 'id' field will be generated automatically.\n   *\n   * @since 1.0.0\n   */\n  contact: Omit<Contact, 'id'>;\n}\n\n/**\n * Result from creating a contact.\n *\n * @since 1.0.0\n */\nexport interface CreateContactResult {\n  /**\n   * The ID of the newly created contact.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Options for displaying the native create contact UI.\n *\n * @since 1.0.0\n */\nexport interface DisplayCreateContactOptions {\n  /**\n   * Optional pre-filled contact information for the create UI.\n   *\n   * @since 1.0.0\n   */\n  contact?: Omit<Contact, 'id'>;\n}\n\n/**\n * Result from displaying the native create contact UI.\n *\n * @since 1.0.0\n */\nexport interface DisplayCreateContactResult {\n  /**\n   * The ID of the created contact, if one was created. Undefined if the user cancelled.\n   *\n   * @since 1.0.0\n   */\n  id?: string;\n}\n\n/**\n * Options for displaying a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface DisplayContactByIdOptions {\n  /**\n   * The ID of the contact to display.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Options for displaying the native update contact UI.\n *\n * @since 1.0.0\n */\nexport interface DisplayUpdateContactByIdOptions {\n  /**\n   * The ID of the contact to update.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Result from getting accounts.\n *\n * @since 1.0.0\n */\nexport interface GetAccountsResult {\n  /**\n   * List of accounts available on the device.\n   *\n   * @since 1.0.0\n   */\n  accounts: Account[];\n}\n\n/**\n * Options for getting a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface GetContactByIdOptions {\n  /**\n   * The ID of the contact to retrieve.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n\n  /**\n   * Optional list of specific fields to retrieve. If not specified, all fields are returned.\n   *\n   * @since 1.0.0\n   */\n  fields?: ContactField[];\n}\n\n/**\n * Result from getting a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface GetContactByIdResult {\n  /**\n   * The contact, or null if not found.\n   *\n   * @since 1.0.0\n   */\n  contact: Contact | null;\n}\n\n/**\n * Options for getting contacts.\n *\n * @since 1.0.0\n */\nexport interface GetContactsOptions {\n  /**\n   * Optional list of specific fields to retrieve. If not specified, all fields are returned.\n   *\n   * @since 1.0.0\n   */\n  fields?: ContactField[];\n\n  /**\n   * Maximum number of contacts to return.\n   *\n   * @since 1.0.0\n   */\n  limit?: number;\n\n  /**\n   * Number of contacts to skip before starting to return results.\n   *\n   * @since 1.0.0\n   */\n  offset?: number;\n}\n\n/**\n * Result from getting contacts.\n *\n * @since 1.0.0\n */\nexport interface GetContactsResult {\n  /**\n   * List of contacts.\n   *\n   * @since 1.0.0\n   */\n  contacts: Contact[];\n}\n\n/**\n * Options for getting a group by ID.\n *\n * @since 1.0.0\n */\nexport interface GetGroupByIdOptions {\n  /**\n   * The ID of the group to retrieve.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Result from getting a group by ID.\n *\n * @since 1.0.0\n */\nexport interface GetGroupByIdResult {\n  /**\n   * The group, or null if not found.\n   *\n   * @since 1.0.0\n   */\n  group: Group | null;\n}\n\n/**\n * Result from getting groups.\n *\n * @since 1.0.0\n */\nexport interface GetGroupsResult {\n  /**\n   * List of groups.\n   *\n   * @since 1.0.0\n   */\n  groups: Group[];\n}\n\n/**\n * Contact group information.\n *\n * @since 1.0.0\n */\nexport interface Group {\n  /**\n   * Unique identifier for the group.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n\n  /**\n   * Name of the group.\n   *\n   * @since 1.0.0\n   */\n  name: string;\n}\n\n/**\n * Options for creating a group.\n *\n * @since 1.0.0\n */\nexport interface CreateGroupOptions {\n  /**\n   * Group information to create. The 'id' field will be generated automatically.\n   *\n   * @since 1.0.0\n   */\n  group: Omit<Group, 'id'>;\n}\n\n/**\n * Result from creating a group.\n *\n * @since 1.0.0\n */\nexport interface CreateGroupResult {\n  /**\n   * The ID of the newly created group.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Options for deleting a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface DeleteContactByIdOptions {\n  /**\n   * The ID of the contact to delete.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Options for deleting a group by ID.\n *\n * @since 1.0.0\n */\nexport interface DeleteGroupByIdOptions {\n  /**\n   * The ID of the group to delete.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n}\n\n/**\n * Contact property that the native picker can select without `READ_CONTACTS`.\n *\n * Use with {@link PickContactsOptions.property} so the user picks one phone\n * number, email address, or postal address instead of a full contact record.\n *\n * @since 8.1.0\n */\nexport enum ContactProperty {\n  /**\n   * A single phone number.\n   *\n   * @since 8.1.0\n   */\n  PhoneNumber = 'phoneNumber',\n\n  /**\n   * A single email address.\n   *\n   * @since 8.1.0\n   */\n  EmailAddress = 'emailAddress',\n\n  /**\n   * A single postal address.\n   *\n   * @since 8.1.0\n   */\n  PostalAddress = 'postalAddress',\n}\n\n/**\n * Options for picking contacts using the native contact picker.\n *\n * @since 1.0.0\n */\nexport interface PickContactsOptions {\n  /**\n   * Optional list of specific fields to retrieve. If not specified, all fields are returned.\n   *\n   * Ignored when {@link PickContactsOptions.property} is set. The result then\n   * contains only `id`, `displayName`, and the selected property.\n   *\n   * @since 1.0.0\n   */\n  fields?: ContactField[];\n\n  /**\n   * Whether to allow selecting multiple contacts. Default is false.\n   *\n   * Ignored when {@link PickContactsOptions.property} is set. Property picking\n   * always returns a single value.\n   *\n   * @since 1.0.0\n   */\n  multiple?: boolean;\n\n  /**\n   * Restrict the picker to a single contact property.\n   *\n   * On Android this launches the picker against the phone, email, or postal\n   * address table and reads the granted data row. That requires no\n   * `READ_CONTACTS` permission on any Android version, which is required for\n   * apps that only pick a contact detail and target Android 17 (API 37) or\n   * later under the Google Play Contacts Permissions policy.\n   *\n   * On iOS the picker lets the user choose one phone number, email address,\n   * or postal address. It never requires a contacts permission.\n   *\n   * @since 8.1.0\n   */\n  property?: ContactProperty;\n}\n\n/**\n * Result from picking contacts.\n *\n * @since 1.0.0\n */\nexport interface PickContactsResult {\n  /**\n   * List of selected contacts.\n   *\n   * @since 1.0.0\n   */\n  contacts: Contact[];\n}\n\n/**\n * Alias for PickContactsOptions.\n *\n * @since 1.0.0\n */\nexport type PickContactOptions = PickContactsOptions;\n\n/**\n * Alias for PickContactsResult.\n *\n * @since 1.0.0\n */\nexport type PickContactResult = PickContactsResult;\n\n/**\n * Options for updating a contact by ID.\n *\n * @since 1.0.0\n */\nexport interface UpdateContactByIdOptions {\n  /**\n   * The ID of the contact to update.\n   *\n   * @since 1.0.0\n   */\n  id: string;\n\n  /**\n   * Updated contact information.\n   *\n   * @since 1.0.0\n   */\n  contact: Omit<Contact, 'id'>;\n}\n\n/**\n * Result from checking if the plugin is supported on the platform.\n *\n * @since 1.0.0\n */\nexport interface IsSupportedResult {\n  /**\n   * Whether the plugin is supported on this platform.\n   *\n   * @since 1.0.0\n   */\n  isSupported: boolean;\n}\n\n/**\n * Result from checking if contacts are available on the device.\n *\n * @since 1.0.0\n */\nexport interface IsAvailableResult {\n  /**\n   * Whether contacts are available on this device.\n   *\n   * @since 1.0.0\n   */\n  isAvailable: boolean;\n}\n\n/**\n * Capacitor Contacts Plugin interface for managing device contacts.\n *\n * @since 1.0.0\n */\nexport interface CapacitorContactsPlugin {\n  /**\n   * Count the total number of contacts on the device.\n   *\n   * @returns Promise that resolves with the total count of contacts\n   * @since 1.0.0\n   */\n  countContacts(): Promise<CountContactsResult>;\n\n  /**\n   * Create a new contact programmatically.\n   *\n   * @param options - The contact information to create\n   * @returns Promise that resolves with the ID of the newly created contact\n   * @since 1.0.0\n   */\n  createContact(options: CreateContactOptions): Promise<CreateContactResult>;\n\n  /**\n   * Create a new contact group.\n   *\n   * @param options - The group information to create\n   * @returns Promise that resolves with the ID of the newly created group\n   * @since 1.0.0\n   */\n  createGroup(options: CreateGroupOptions): Promise<CreateGroupResult>;\n\n  /**\n   * Delete a contact by ID.\n   *\n   * @param options - The ID of the contact to delete\n   * @returns Promise that resolves when the contact is deleted\n   * @since 1.0.0\n   */\n  deleteContactById(options: DeleteContactByIdOptions): Promise<void>;\n\n  /**\n   * Delete a group by ID.\n   *\n   * @param options - The ID of the group to delete\n   * @returns Promise that resolves when the group is deleted\n   * @since 1.0.0\n   */\n  deleteGroupById(options: DeleteGroupByIdOptions): Promise<void>;\n\n  /**\n   * Display a contact using the native contact viewer.\n   *\n   * @param options - The ID of the contact to display\n   * @returns Promise that resolves when the viewer is closed\n   * @since 1.0.0\n   */\n  displayContactById(options: DisplayContactByIdOptions): Promise<void>;\n\n  /**\n   * Display the native create contact UI.\n   *\n   * @param options - Optional pre-filled contact information\n   * @returns Promise that resolves with the ID of the created contact, or undefined if cancelled\n   * @since 1.0.0\n   */\n  displayCreateContact(options?: DisplayCreateContactOptions): Promise<DisplayCreateContactResult>;\n\n  /**\n   * Display the native update contact UI for a specific contact.\n   *\n   * @param options - The ID of the contact to update\n   * @returns Promise that resolves when the update UI is closed\n   * @since 1.0.0\n   */\n  displayUpdateContactById(options: DisplayUpdateContactByIdOptions): Promise<void>;\n\n  /**\n   * Get all accounts available on the device.\n   *\n   * @returns Promise that resolves with the list of accounts\n   * @since 1.0.0\n   */\n  getAccounts(): Promise<GetAccountsResult>;\n\n  /**\n   * Get a specific contact by ID.\n   *\n   * @param options - The ID and optional fields to retrieve\n   * @returns Promise that resolves with the contact, or null if not found\n   * @since 1.0.0\n   */\n  getContactById(options: GetContactByIdOptions): Promise<GetContactByIdResult>;\n\n  /**\n   * Get all contacts from the device.\n   *\n   * @param options - Optional filters and pagination options\n   * @returns Promise that resolves with the list of contacts\n   * @since 1.0.0\n   */\n  getContacts(options?: GetContactsOptions): Promise<GetContactsResult>;\n\n  /**\n   * Get a specific group by ID.\n   *\n   * @param options - The ID of the group to retrieve\n   * @returns Promise that resolves with the group, or null if not found\n   * @since 1.0.0\n   */\n  getGroupById(options: GetGroupByIdOptions): Promise<GetGroupByIdResult>;\n\n  /**\n   * Get all contact groups.\n   *\n   * @returns Promise that resolves with the list of groups\n   * @since 1.0.0\n   */\n  getGroups(): Promise<GetGroupsResult>;\n\n  /**\n   * Check if contacts are available on the device.\n   *\n   * @returns Promise that resolves with availability status\n   * @since 1.0.0\n   */\n  isAvailable(): Promise<IsAvailableResult>;\n\n  /**\n   * Check if the plugin is supported on the current platform.\n   *\n   * @returns Promise that resolves with support status\n   * @since 1.0.0\n   */\n  isSupported(): Promise<IsSupportedResult>;\n\n  /**\n   * Open the device's contacts settings.\n   *\n   * @returns Promise that resolves when the settings are opened\n   * @since 1.0.0\n   */\n  openSettings(): Promise<void>;\n\n  /**\n   * Pick a single contact using the native contact picker.\n   *\n   * Same options as {@link pickContacts}. Without `property`, Android still\n   * returns the full contact when `READ_CONTACTS` is granted.\n   *\n   * @param options - Optional fields to retrieve and picker configuration\n   * @returns Promise that resolves with the selected contact(s)\n   * @since 1.0.0\n   */\n  pickContact(options?: PickContactOptions): Promise<PickContactResult>;\n\n  /**\n   * Pick one or more contacts using the native contact picker.\n   *\n   * On iOS this never requires a contacts permission.\n   *\n   * On Android, `pickContacts()` without `property` still returns the full\n   * contact when the app has `READ_CONTACTS`. Pass `property` only when you\n   * want a single phone number, email address, or postal address and can omit\n   * that permission (required to target Android 17 / API 37 without a Play\n   * Console contacts declaration).\n   *\n   * @param options - Optional fields to retrieve and picker configuration\n   * @returns Promise that resolves with the selected contacts\n   * @since 1.0.0\n   */\n  pickContacts(options?: PickContactsOptions): Promise<PickContactsResult>;\n\n  /**\n   * Update an existing contact by ID.\n   *\n   * @param options - The ID and updated contact information\n   * @returns Promise that resolves when the contact is updated\n   * @since 1.0.0\n   */\n  updateContactById(options: UpdateContactByIdOptions): Promise<void>;\n\n  /**\n   * Check the current permission status for contacts.\n   *\n   * @returns Promise that resolves with the current permission status\n   * @since 1.0.0\n   */\n  checkPermissions(): Promise<PermissionStatus>;\n\n  /**\n   * Request permissions to access contacts.\n   *\n   * @param options - Optional specific permissions to request\n   * @returns Promise that resolves with the updated permission status\n   * @since 1.0.0\n   */\n  requestPermissions(options?: RequestPermissionsOptions): Promise<PermissionStatus>;\n\n  /**\n   * Get the native Capacitor plugin version.\n   *\n   * @returns Promise that resolves with the plugin version\n   * @since 1.0.0\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}

package/ios/Sources/CapacitorContactsPlugin/CapacitorContactsPlugin.swift

@@ -5,7 +5,7 @@ import UIKit
 
 @objc(CapacitorContactsPlugin)
 public class CapacitorContactsPlugin: CAPPlugin, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.1.0"
+    private let pluginVersion: String = "8.1.2"
     public let identifier = "CapacitorContactsPlugin"
     public let jsName = "CapacitorContacts"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-contacts",
-  "version": "8.1.0",
+  "version": "8.1.2",
   "description": "Work with device contacts using Capacitor APIs",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",