@cap-kit/people 8.0.0

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sources":["esm/definitions.js","esm/index.js","esm/web.js"],"sourcesContent":["/// <reference types=\"@capacitor/cli\" />\n/**\n * Standardized error codes used by the People plugin.\n *\n * These codes are returned when a Promise is rejected and can be caught\n * via try/catch blocks.\n *\n * @since 8.0.0\n */\nexport var PeopleErrorCode;\n(function (PeopleErrorCode) {\n    /** The device does not have the requested hardware or the feature is not available on this platform. */\n    PeopleErrorCode[\"UNAVAILABLE\"] = \"UNAVAILABLE\";\n    /** The user cancelled an interactive flow. */\n    PeopleErrorCode[\"CANCELLED\"] = \"CANCELLED\";\n    /** The user denied the permission or the feature is disabled by the OS. */\n    PeopleErrorCode[\"PERMISSION_DENIED\"] = \"PERMISSION_DENIED\";\n    /** The plugin failed to initialize or perform an operation. */\n    PeopleErrorCode[\"INIT_FAILED\"] = \"INIT_FAILED\";\n    /** The input provided to the plugin method is invalid, missing, or malformed. */\n    PeopleErrorCode[\"INVALID_INPUT\"] = \"INVALID_INPUT\";\n    /** The requested type is not valid or supported. */\n    PeopleErrorCode[\"UNKNOWN_TYPE\"] = \"UNKNOWN_TYPE\";\n    /** The requested resource does not exist. */\n    PeopleErrorCode[\"NOT_FOUND\"] = \"NOT_FOUND\";\n    /** The operation conflicts with the current state. */\n    PeopleErrorCode[\"CONFLICT\"] = \"CONFLICT\";\n    /** The operation did not complete within the expected time. */\n    PeopleErrorCode[\"TIMEOUT\"] = \"TIMEOUT\";\n})(PeopleErrorCode || (PeopleErrorCode = {}));\n//# sourceMappingURL=definitions.js.map","/**\n * @file index.ts\n * Main entry point for the People Capacitor Plugin.\n * This file handles the registration of the plugin with the Capacitor core runtime\n * and exports all necessary types for consumers.\n */\nimport { registerPlugin } from '@capacitor/core';\n/**\n * The People plugin instance.\n * It automatically lazy-loads the web implementation if running in a browser environment.\n * Use this instance to access all people functionality.\n */\nconst People = registerPlugin('People', {\n    web: () => import('./web').then((m) => new m.PeopleWeb()),\n});\nexport * from './definitions';\nexport { People };\n//# sourceMappingURL=index.js.map","import { WebPlugin } from '@capacitor/core';\n/**\n * Class representing the web implementation of the PeoplePlugin.\n * This class extends the WebPlugin class and implements the PeoplePlugin interface.\n * It provides a base implementation for web-based functionality of the plugin.\n */\nexport class PeopleWeb extends WebPlugin {\n    constructor() {\n        super();\n    }\n    // -----------------------------------------------------------------------------\n    // Capabilities\n    // -----------------------------------------------------------------------------\n    /**\n     * Retrieves the capabilities of the People plugin on the web platform.\n     *\n     * @returns A promise resolving to the PeopleCapabilities object.\n     */\n    async getCapabilities() {\n        return {\n            canRead: false, // Web cannot bulk read the address book\n            canWrite: false,\n            canObserve: false,\n            canManageGroups: false,\n            canPickContact: true, // Only the Zero-Permission picker is supported via Contact Picker API\n        };\n    }\n    // -----------------------------------------------------------------------------\n    // Permissions\n    // -----------------------------------------------------------------------------\n    /**\n     * Checks the permission status for the plugin.\n     *\n     * @returns A promise resolving to an object containing the permission states.\n     */\n    async checkPermissions() {\n        return { contacts: 'prompt' };\n    }\n    /**\n     * Requests the necessary permissions for the plugin.\n     *\n     * @returns A promise resolving to an object containing the updated permission states.\n     */\n    async requestPermissions() {\n        return { contacts: 'prompt' };\n    }\n    // -----------------------------------------------------------------------------\n    // Contact Picking\n    // -----------------------------------------------------------------------------\n    /**\n     * Launches the OS contact picker UI.\n     * On Web this uses the Contact Picker API if available.\n     * * Architectural rules:\n     * - Rejects with CANCELLED on user cancellation to match native behavior.\n     */\n    async pickContact(options) {\n        var _a, _b, _c, _d;\n        const contactsNavigator = navigator;\n        const props = (options === null || options === void 0 ? void 0 : options.projection) || ['name', 'phones', 'emails'];\n        const supportedProjection = new Set([\n            'name',\n            'organization',\n            'birthday',\n            'phones',\n            'emails',\n            'addresses',\n            'urls',\n            'note',\n        ]);\n        for (const field of props) {\n            if (!supportedProjection.has(field)) {\n                return Promise.reject({\n                    message: `Unsupported projection field: ${field}`,\n                    code: 'UNKNOWN_TYPE',\n                });\n            }\n        }\n        // Support for the modern Web Contact Picker API\n        if ((_a = contactsNavigator.contacts) === null || _a === void 0 ? void 0 : _a.select) {\n            try {\n                // Marshalling: Map plugin projections to Web API properties\n                const webProps = props.map((p) => {\n                    if (p === 'phones')\n                        return 'tel';\n                    if (p === 'emails')\n                        return 'email';\n                    return p;\n                });\n                const contacts = await contactsNavigator.contacts.select(webProps, { multiple: false });\n                // Some browsers return an empty array instead of throwing on cancel; normalize to CANCELLED.\n                if (!contacts || contacts.length === 0) {\n                    return Promise.reject({\n                        message: 'User cancelled selection',\n                        code: 'CANCELLED',\n                    });\n                }\n                const raw = contacts[0];\n                return {\n                    contact: {\n                        id: 'web-ref',\n                        name: { display: ((_b = raw.name) === null || _b === void 0 ? void 0 : _b[0]) || 'Unknown' },\n                        phones: ((_c = raw.tel) === null || _c === void 0 ? void 0 : _c.map((t) => ({ number: t }))) || [],\n                        emails: ((_d = raw.email) === null || _d === void 0 ? void 0 : _d.map((e) => ({ address: e }))) || [],\n                    },\n                };\n            }\n            catch (e) {\n                const err = e;\n                // Map specific Web API cancellation to the standardized CANCELLED code\n                if (err.name === 'AbortError') {\n                    return Promise.reject({\n                        message: 'User cancelled selection',\n                        code: 'CANCELLED',\n                    });\n                }\n                throw this.unavailable(err.message || 'Web Contact Picker API failed');\n            }\n        }\n        throw this.unavailable('Native Contact Picker not available in this browser.');\n    }\n    // -----------------------------------------------------------------------------\n    // Directory Access (Not supported on Web)\n    // -----------------------------------------------------------------------------\n    /**\n     * Retrieves contacts from the system directory.\n     * @param _options - Options for retrieving contacts.\n     *\n     * @returns A promise resolving to the contacts result.\n     */\n    async getContacts() {\n        throw this.unimplemented('getContacts is not available on Web.');\n    }\n    /**\n     * Retrieves a single contact by ID.\n     * @param _options - Options containing the contact ID.\n     *\n     * @returns A promise resolving to the contact.\n     */\n    async getContact() {\n        throw this.unimplemented('getContact is not available on Web.');\n    }\n    /**\n     * Searches contacts in the system directory.\n     * @param _options - Options for searching contacts.\n     *\n     * @returns A promise resolving to the contacts result.\n     */\n    async searchPeople() {\n        throw this.unimplemented('searchPeople is not available on Web.');\n    }\n    // -----------------------------------------------------------------------------\n    // Group Management (Not supported on Web)\n    // -----------------------------------------------------------------------------\n    /**\n     * Lists all available contact groups.\n     * @returns A promise that is rejected because this feature is not available on Web.\n     */\n    async listGroups() {\n        throw this.unimplemented('listGroups is not available on Web.');\n    }\n    /**\n     * Creates a new contact group.\n     * @returns A promise that is rejected because this feature is not available on Web.\n     */\n    async createGroup(_options) {\n        void _options;\n        throw this.unimplemented('createGroup is not available on Web.');\n    }\n    /**\n     * Deletes a contact group.\n     * @returns A promise that is rejected because this feature is not available on Web.\n     */\n    async deleteGroup(_options) {\n        void _options;\n        throw this.unimplemented('deleteGroup is not available on Web.');\n    }\n    /**\n     * Adds contacts to a group.\n     * @returns A promise that is rejected because this feature is not available on Web.\n     */\n    async addPeopleToGroup(_options) {\n        void _options;\n        throw this.unimplemented('addPeopleToGroup is not available on Web.');\n    }\n    /**\n     * Removes contacts from a group.\n     * @returns A promise that is rejected because this feature is not available on Web.\n     */\n    async removePeopleFromGroup(_options) {\n        void _options;\n        throw this.unimplemented('removePeopleFromGroup is not available on Web.');\n    }\n    // -----------------------------------------------------------------------------\n    // CRUD (Not supported on Web)\n    // -----------------------------------------------------------------------------\n    /**\n     * Creates a new contact.\n     * @returns A promise that is rejected because this feature is not available on Web.\n     */\n    async createContact(_options) {\n        void _options;\n        throw this.unimplemented('createContact is not available on Web.');\n    }\n    /**\n     * Updates an existing contact.\n     * @returns A promise that is rejected because this feature is not available on Web.\n     */\n    async updateContact(_options) {\n        void _options;\n        throw this.unimplemented('updateContact is not available on Web.');\n    }\n    /**\n     * Deletes a contact.\n     * @returns A promise that is rejected because this feature is not available on Web.\n     */\n    async deleteContact(_options) {\n        void _options;\n        throw this.unimplemented('deleteContact is not available on Web.');\n    }\n    /**\n     * Merges two contacts.\n     * @returns A promise that is rejected because this feature is not available on Web.\n     */\n    async mergeContacts(_options) {\n        void _options;\n        throw this.unimplemented('mergeContacts is not available on Web.');\n    }\n    // -----------------------------------------------------------------------------\n    // Plugin Info\n    // -----------------------------------------------------------------------------\n    /**\n     * Returns the plugin version.\n     *\n     * On the Web, this value represents the JavaScript package version\n     * rather than a native implementation.\n     */\n    async getPluginVersion() {\n        return { version: 'web' };\n    }\n    // -----------------------------------------------------------------------------\n    // Listener Handling\n    // -----------------------------------------------------------------------------\n    /**\n     * Cleanup all listeners\n     *\n     * @returns A promise that resolves when all listeners are removed.\n     */\n    async removeAllListeners() {\n        super.removeAllListeners();\n    }\n}\n//# sourceMappingURL=web.js.map"],"names":["PeopleErrorCode","registerPlugin","WebPlugin"],"mappings":"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"}

package/ios/Sources/PeoplePlugin/PeopleImpl.swift

@@ -0,0 +1,463 @@
+import Foundation
+import Contacts
+
+/**
+ * Native iOS implementation for the People plugin.
+ *
+ * Architectural rules:
+ * - MUST NOT access CAPPluginCall.
+ * - MUST NOT depend on Capacitor bridge APIs directly.
+ * - MUST throw PeopleError for specific failures.
+ */
+@objc public final class PeopleImpl: NSObject {
+
+    // MARK: - Properties
+
+    /// Cached plugin configuration containing logging and behavioral flags.
+    private var config: PeopleConfig?
+
+    /// Shared contact store instance for performance optimization.
+    private let store = CNContactStore()
+
+    // MARK: - Initialization
+
+    /**
+     * Initializes the implementation instance.
+     */
+    override init() {
+        super.init()
+    }
+
+    // MARK: - Configuration
+
+    /**
+     * Applies static plugin configuration.
+     *
+     * This method MUST be called exactly once from the Plugin bridge layer during `load()`.
+     * It synchronizes the native logger state with the provided configuration.
+     *
+     * - Parameter config: The immutable configuration container.
+     */
+    public func applyConfig(_ config: PeopleConfig) {
+        precondition(
+            self.config == nil,
+            "PeopleImpl.applyConfig(_:) must be called exactly once"
+        )
+        self.config = config
+        PeopleLogger.verbose = config.verboseLogging
+
+        PeopleLogger.debug(
+            "Configuration applied. Verbose logging:",
+            config.verboseLogging
+        )
+    }
+
+    // MARK: - Capabilities
+
+    /**
+     * Determines the capabilities based on the current authorization status.
+     */
+    public func getCapabilities(authStatus: CNAuthorizationStatus) -> [String: Bool] {
+        let isAuthorized: Bool
+        if #available(iOS 18.0, *) {
+            isAuthorized = (authStatus == .authorized || authStatus == .limited)
+        } else {
+            isAuthorized = (authStatus == .authorized)
+        }
+
+        return [
+            "canRead": isAuthorized,
+            "canWrite": isAuthorized,
+            "canObserve": isAuthorized,
+            "canManageGroups": isAuthorized,
+            "canPickContact": true
+        ]
+    }
+
+    // MARK: - Contact Fetching
+
+    /**
+     * Fetches contacts with pagination and projection using nominal models.
+     */
+    public func fetchContacts(
+        projection: [String],
+        limit: Int,
+        offset: Int,
+        includeTotal: Bool = true
+    ) throws -> GetContactsResultData {
+
+        let safeLimit = max(0, limit)
+        let safeOffset = max(0, offset)
+        let keys = keysForProjection(projection)
+        let request = CNContactFetchRequest(keysToFetch: keys)
+
+        var results: [ContactData] = []
+        var currentIndex = 0
+        let upperBound = safeOffset + safeLimit
+
+        try store.enumerateContacts(with: request) { contact, stop in
+            if currentIndex >= safeOffset && currentIndex < upperBound {
+                results.append(PeopleUtils.mapToContactData(contact, projection: projection))
+            }
+
+            // When includeTotal is true we must continue enumerating to compute totalCount.
+            currentIndex += 1
+
+            if !includeTotal && currentIndex >= upperBound {
+                stop.pointee = true
+            }
+        }
+
+        return GetContactsResultData(
+            contacts: results,
+            totalCount: includeTotal ? currentIndex : results.count
+        )
+    }
+
+    /**
+     * Fetches a single contact by identifier using nominal models.
+     */
+    public func fetchContactById(
+        id: String,
+        projection: [String]
+    ) throws -> ContactData? {
+
+        let keys = keysForProjection(projection)
+        let contact = try store.unifiedContact(
+            withIdentifier: id,
+            keysToFetch: keys
+        )
+
+        return PeopleUtils.mapToContactData(contact, projection: projection)
+    }
+
+    /**
+     * Searches for contacts matching a query string using nominal models.
+     */
+    public func searchContacts(
+        query: String,
+        projection: [String],
+        limit: Int
+    ) throws -> GetContactsResultData {
+
+        let trimmedQuery = query.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedQuery.isEmpty else { return GetContactsResultData(contacts: [], totalCount: 0) }
+
+        let safeLimit = max(0, limit)
+        let keys = keysForProjection(projection)
+        let predicate = CNContact.predicateForContacts(matchingName: trimmedQuery)
+        let request = CNContactFetchRequest(keysToFetch: keys)
+        request.predicate = predicate
+
+        var results: [ContactData] = []
+        var totalCount = 0
+
+        try store.enumerateContacts(with: request) { contact, _ in
+            totalCount += 1
+
+            if results.count < safeLimit {
+                results.append(PeopleUtils.mapToContactData(contact, projection: projection))
+            }
+        }
+
+        return GetContactsResultData(contacts: results, totalCount: totalCount)
+    }
+
+    /**
+     * Determines the CNKeyDescriptors needed for the given projection.
+     */
+    private func keysForProjection(_ projection: [String]) -> [CNKeyDescriptor] {
+        let normalizedProjection = Set(projection)
+        var keyNames: Set<String> = [
+            CNContactIdentifierKey,
+            CNContactGivenNameKey,
+            CNContactFamilyNameKey
+        ]
+
+        let projectionMap: [String: [String]] = [
+            "name": [CNContactGivenNameKey, CNContactFamilyNameKey],
+            "phones": [CNContactPhoneNumbersKey],
+            "emails": [CNContactEmailAddressesKey],
+            "organization": [CNContactOrganizationNameKey, CNContactJobTitleKey, CNContactDepartmentNameKey],
+            "birthday": [CNContactBirthdayKey],
+            "image": [CNContactThumbnailImageDataKey],
+            "addresses": [CNContactPostalAddressesKey],
+            "urls": [CNContactUrlAddressesKey],
+            "note": [CNContactNoteKey]
+        ]
+
+        for field in normalizedProjection {
+            if let mappedKeys = projectionMap[field] {
+                keyNames.formUnion(mappedKeys)
+            }
+        }
+
+        return keyNames.map { $0 as CNKeyDescriptor }
+    }
+
+    // MARK: - Group Management
+
+    /**
+     * Fetches all contact groups from the contact store using nominal models.
+     */
+    public func listGroups() throws -> ListGroupsResultData {
+        let groups = try store.groups(matching: nil)
+        let result = groups.map { PeopleUtils.mapToGroupData($0) }
+        return ListGroupsResultData(groups: result)
+    }
+
+    /**
+     * Creates a new group with the given name.
+     */
+    public func createGroup(name: String) throws -> GroupData {
+        let saveRequest = CNSaveRequest()
+        let newGroup = CNMutableGroup()
+        newGroup.name = name
+
+        saveRequest.add(newGroup, toContainerWithIdentifier: nil)
+        try store.execute(saveRequest)
+
+        let groups = try store.groups(matching: CNGroup.predicateForGroups(withIdentifiers: [newGroup.identifier]))
+        if let createdGroup = groups.first {
+            return PeopleUtils.mapToGroupData(createdGroup)
+        } else {
+            throw PeopleError.initFailed("Failed to retrieve created group")
+        }
+    }
+
+    /**
+     * Deletes a group by its identifier.
+     */
+    public func deleteGroup(groupId: String) throws {
+        let saveRequest = CNSaveRequest()
+        let groups = try store.groups(matching: CNGroup.predicateForGroups(withIdentifiers: [groupId]))
+
+        guard let groupToDelete = groups.first else {
+            throw PeopleError.notFound("Group not found")
+        }
+
+        saveRequest.delete(groupToDelete.mutableCopy() as! CNMutableGroup)
+        try store.execute(saveRequest)
+    }
+
+    /**
+     * Adds contacts to a group.
+     */
+    public func addPeopleToGroup(groupId: String, contactIds: [String]) throws {
+        let saveRequest = CNSaveRequest()
+        let groups = try store.groups(matching: CNGroup.predicateForGroups(withIdentifiers: [groupId]))
+
+        guard let group = groups.first else {
+            throw PeopleError.unavailable("Group not found")
+        }
+
+        let contacts = try store.unifiedContacts(matching: CNContact.predicateForContacts(withIdentifiers: contactIds), keysToFetch: [])
+        for contact in contacts {
+            saveRequest.addMember(contact, to: group)
+        }
+
+        try store.execute(saveRequest)
+    }
+
+    /**
+     * Removes contacts from a group.
+     */
+    public func removePeopleFromGroup(groupId: String, contactIds: [String]) throws {
+        let saveRequest = CNSaveRequest()
+        let groups = try store.groups(matching: CNGroup.predicateForGroups(withIdentifiers: [groupId]))
+
+        guard let group = groups.first else {
+            throw PeopleError.unavailable("Group not found")
+        }
+
+        let contacts = try store.unifiedContacts(matching: CNContact.predicateForContacts(withIdentifiers: contactIds), keysToFetch: [])
+        for contact in contacts {
+            saveRequest.removeMember(contact, from: group)
+        }
+
+        try store.execute(saveRequest)
+    }
+
+    // MARK: - CRUD
+
+    /**
+     * Creates a new contact and returns a nominal model.
+     */
+    public func createContact(contactData: [String: Any]) throws -> ContactData {
+        let saveRequest = CNSaveRequest()
+        let newContact = CNMutableContact()
+
+        // Name mapping
+        if let nameDict = contactData["name"] as? [String: String] {
+            newContact.givenName = nameDict["given"] ?? ""
+            newContact.familyName = nameDict["family"] ?? ""
+        }
+
+        // Phones mapping
+        if let phonesArray = contactData["phones"] as? [[String: String]] {
+            newContact.phoneNumbers = phonesArray.map { phoneDict in
+                let number = CNPhoneNumber(stringValue: phoneDict["number"] ?? "")
+                let label = phoneDict["label"] ?? CNLabelPhoneNumberMobile
+                return CNLabeledValue(label: label, value: number)
+            }
+        }
+
+        // Emails mapping
+        if let emailsArray = contactData["emails"] as? [[String: String]] {
+            newContact.emailAddresses = emailsArray.map { emailDict in
+                let address = (emailDict["address"] ?? "") as NSString
+                let label = emailDict["label"] ?? CNLabelWork
+                return CNLabeledValue(label: label, value: address)
+            }
+        }
+
+        newContact.note = "[cap-owned]"
+        saveRequest.add(newContact, toContainerWithIdentifier: nil)
+        try store.execute(saveRequest)
+
+        return PeopleUtils.mapToContactData(newContact, projection: ["name", "phones", "emails"])
+    }
+
+    /**
+     * Deletes a contact by its identifier.
+     */
+    public func deleteContact(contactId: String) throws {
+        let saveRequest = CNSaveRequest()
+        let keysToFetch = [CNContactIdentifierKey as CNKeyDescriptor, CNContactNoteKey as CNKeyDescriptor]
+        let contact = try store.unifiedContact(withIdentifier: contactId, keysToFetch: keysToFetch)
+
+        guard isAppOwned(contact: contact) else {
+            throw PeopleError.permissionDenied("Cannot modify a contact that is not owned by the app.")
+        }
+
+        saveRequest.delete(contact.mutableCopy() as! CNMutableContact)
+        try store.execute(saveRequest)
+    }
+
+    /**
+     * Updates an existing contact and returns the updated nominal model.
+     */
+    public func updateContact(contactId: String, contactData: [String: Any]) throws -> ContactData {
+        let saveRequest = CNSaveRequest()
+        let keysToFetch = [
+            CNContactIdentifierKey as CNKeyDescriptor,
+            CNContactNoteKey as CNKeyDescriptor,
+            CNContactGivenNameKey as CNKeyDescriptor,
+            CNContactFamilyNameKey as CNKeyDescriptor,
+            CNContactPhoneNumbersKey as CNKeyDescriptor,
+            CNContactEmailAddressesKey as CNKeyDescriptor,
+            CNContactPostalAddressesKey as CNKeyDescriptor,
+            CNContactUrlAddressesKey as CNKeyDescriptor
+        ]
+        let contact = try store.unifiedContact(withIdentifier: contactId, keysToFetch: keysToFetch)
+
+        guard isAppOwned(contact: contact) else {
+            throw PeopleError.permissionDenied("Cannot update a contact that is not owned by the app.")
+        }
+
+        let mutableContact = contact.mutableCopy() as! CNMutableContact
+
+        // Patch semantics for name:
+        // - absent field: keep current value
+        // - present subfield: update that subfield only
+        if let nameDict = contactData["name"] as? [String: Any] {
+            if let given = nameDict["given"] as? String {
+                mutableContact.givenName = given
+            }
+            if let family = nameDict["family"] as? String {
+                mutableContact.familyName = family
+            }
+        }
+
+        // Patch semantics for arrays:
+        // - absent key: keep current array
+        // - present key with []: clear array
+        // - present key with values: replace with provided values
+        if contactData.keys.contains("phones"),
+           let phonesArray = contactData["phones"] as? [[String: String]] {
+            mutableContact.phoneNumbers = phonesArray.map { phoneDict in
+                let number = CNPhoneNumber(stringValue: phoneDict["number"] ?? "")
+                let label = phoneDict["label"] ?? CNLabelPhoneNumberMobile
+                return CNLabeledValue(label: label, value: number)
+            }
+        }
+
+        if contactData.keys.contains("emails"),
+           let emailsArray = contactData["emails"] as? [[String: String]] {
+            mutableContact.emailAddresses = emailsArray.map { emailDict in
+                let address = (emailDict["address"] ?? "") as NSString
+                let label = emailDict["label"] ?? CNLabelWork
+                return CNLabeledValue(label: label, value: address)
+            }
+        }
+
+        if contactData.keys.contains("addresses"),
+           let addressesArray = contactData["addresses"] as? [[String: String]] {
+            mutableContact.postalAddresses = addressesArray.map { addressDict in
+                let postal = CNMutablePostalAddress()
+                postal.street = addressDict["street"] ?? ""
+                postal.city = addressDict["city"] ?? ""
+                postal.state = addressDict["region"] ?? ""
+                postal.postalCode = addressDict["postcode"] ?? ""
+                postal.country = addressDict["country"] ?? ""
+                let label = addressDict["label"] ?? CNLabelHome
+                return CNLabeledValue(label: label, value: postal)
+            }
+        }
+
+        if contactData.keys.contains("urls"),
+           let urlsArray = contactData["urls"] as? [String] {
+            mutableContact.urlAddresses = urlsArray.map { url in
+                CNLabeledValue(label: CNLabelURLAddressHomePage, value: url as NSString)
+            }
+        }
+
+        saveRequest.update(mutableContact)
+        try store.execute(saveRequest)
+
+        return PeopleUtils.mapToContactData(mutableContact, projection: ["name", "phones", "emails"])
+    }
+
+    /**
+     * Merges two contacts and returns the final nominal model with deduplicated data.
+     */
+    public func mergeContacts(sourceContactId: String, destinationContactId: String) throws -> ContactData {
+        let saveRequest = CNSaveRequest()
+        let keysToFetch = [
+            CNContactIdentifierKey as CNKeyDescriptor,
+            CNContactNoteKey as CNKeyDescriptor,
+            CNContactPhoneNumbersKey as CNKeyDescriptor,
+            CNContactEmailAddressesKey as CNKeyDescriptor
+        ]
+
+        let sourceContact = try store.unifiedContact(withIdentifier: sourceContactId, keysToFetch: keysToFetch)
+        let destinationContact = try store.unifiedContact(withIdentifier: destinationContactId, keysToFetch: keysToFetch)
+
+        guard isAppOwned(contact: sourceContact), isAppOwned(contact: destinationContact) else {
+            throw PeopleError.permissionDenied("Cannot merge contacts that are not owned by the app.")
+        }
+
+        let mutableDestinationContact = destinationContact.mutableCopy() as! CNMutableContact
+
+        // Deduplicate Phone Numbers by string value
+        let existingPhones = destinationContact.phoneNumbers.map { $0.value.stringValue }
+        let newPhones = sourceContact.phoneNumbers.filter { !existingPhones.contains($0.value.stringValue) }
+        mutableDestinationContact.phoneNumbers = destinationContact.phoneNumbers + newPhones
+
+        // Deduplicate Email Addresses
+        let existingEmails = destinationContact.emailAddresses.map { $0.value as String }
+        let newEmails = sourceContact.emailAddresses.filter { !existingEmails.contains($0.value as String) }
+        mutableDestinationContact.emailAddresses = destinationContact.emailAddresses + newEmails
+
+        saveRequest.update(mutableDestinationContact)
+        saveRequest.delete(sourceContact.mutableCopy() as! CNMutableContact)
+
+        try store.execute(saveRequest)
+
+        return PeopleUtils.mapToContactData(mutableDestinationContact, projection: ["name", "phones", "emails"])
+    }
+
+    private func isAppOwned(contact: CNContact) -> Bool {
+        return contact.note.contains("[cap-owned]")
+    }
+}