@cap-kit/people 8.0.0

package/ios/Sources/PeoplePlugin/Utils/PeopleUtils.swift

@@ -0,0 +1,120 @@
+import Foundation
+import Contacts
+
+/**
+ * A utility struct providing helper methods for data mapping.
+ * Architectural rules:
+ * - Pure helper functions only.
+ * - No Capacitor dependencies.
+ */
+struct PeopleUtils {
+
+    /// Supported projection fields constant.
+    static let supportedProjections: Set<String> = [
+        "name", "organization", "birthday", "phones", "emails", "addresses", "urls", "image", "note"
+    ]
+
+    /// Normalizes native iOS contact labels into standardized strings.
+    static func normalizeLabel(_ label: String?) -> String {
+        guard let label = label else { return "other" }
+
+        // Use the localized string from the framework to clean internal identifiers like _$!<Mobile>!$_
+        let localizedLabel = CNLabeledValue<NSString>.localizedString(forLabel: label).lowercased()
+
+        if localizedLabel.contains("mobile") || localizedLabel.contains("cell") { return "mobile" }
+        if localizedLabel.contains("home") { return "home" }
+        if localizedLabel.contains("work") { return "work" }
+        if localizedLabel.contains("main") { return "main" }
+        if localizedLabel.contains("fax") { return "fax" }
+        return "other"
+    }
+
+    /// Validates that all requested projection fields are supported.
+    /// - Parameter projection: The array of strings to validate.
+    /// - Throws: PeopleError.unknownType if a field is invalid.
+    static func validateProjection(_ projection: [String]) throws {
+        for field in projection {
+            if !supportedProjections.contains(field) {
+                throw PeopleError.unknownType("Unsupported projection field: \(field)")
+            }
+        }
+    }
+
+    /// Maps a native CNContact to the nominal ContactData model.
+    static func mapToContactData(_ contact: CNContact, projection: [String]) -> ContactData {
+        let nameAvailable =
+            contact.isKeyAvailable(CNContactGivenNameKey) &&
+            contact.isKeyAvailable(CNContactFamilyNameKey)
+        let organizationAvailable =
+            contact.isKeyAvailable(CNContactOrganizationNameKey) &&
+            contact.isKeyAvailable(CNContactJobTitleKey) &&
+            contact.isKeyAvailable(CNContactDepartmentNameKey)
+        let birthdayAvailable = contact.isKeyAvailable(CNContactBirthdayKey)
+        let phonesAvailable = contact.isKeyAvailable(CNContactPhoneNumbersKey)
+        let emailsAvailable = contact.isKeyAvailable(CNContactEmailAddressesKey)
+        let addressesAvailable = contact.isKeyAvailable(CNContactPostalAddressesKey)
+        let urlsAvailable = contact.isKeyAvailable(CNContactUrlAddressesKey)
+        let noteAvailable = contact.isKeyAvailable(CNContactNoteKey)
+        let imageAvailable = contact.isKeyAvailable(CNContactThumbnailImageDataKey)
+
+        let displayName: String? = {
+            guard nameAvailable else { return nil }
+            let parts = [contact.givenName, contact.familyName].filter { !$0.isEmpty }
+            return parts.isEmpty ? nil : parts.joined(separator: " ")
+        }()
+
+        let organization: ContactOrganization? = {
+            guard projection.contains("organization"), organizationAvailable else { return nil }
+            return ContactOrganization(
+                company: contact.organizationName.isEmpty ? nil : contact.organizationName,
+                title: contact.jobTitle.isEmpty ? nil : contact.jobTitle,
+                department: contact.departmentName.isEmpty ? nil : contact.departmentName
+            )
+        }()
+
+        return ContactData(
+            id: contact.identifier,
+            displayName: displayName,
+            firstName: projection.contains("name") && nameAvailable ? contact.givenName : nil,
+            lastName: projection.contains("name") && nameAvailable ? contact.familyName : nil,
+            organization: organization,
+            birthday: projection.contains("birthday") && birthdayAvailable ? contact.birthday : nil,
+            phones: projection.contains("phones") && phonesAvailable ? contact.phoneNumbers.map {
+                ContactPhone(
+                    label: normalizeLabel($0.label),
+                    number: $0.value.stringValue
+                )
+            } : nil,
+            emails: projection.contains("emails") && emailsAvailable ? contact.emailAddresses.map {
+                ContactEmail(
+                    label: normalizeLabel($0.label),
+                    address: $0.value as String
+                )
+            } : nil,
+            addresses: projection.contains("addresses") && addressesAvailable ? contact.postalAddresses.map {
+                ContactAddress(
+                    label: normalizeLabel($0.label),
+                    formatted: CNPostalAddressFormatter.string(from: $0.value, style: .mailingAddress),
+                    street: $0.value.street.isEmpty ? nil : $0.value.street,
+                    city: $0.value.city.isEmpty ? nil : $0.value.city,
+                    region: $0.value.state.isEmpty ? nil : $0.value.state,
+                    postcode: $0.value.postalCode.isEmpty ? nil : $0.value.postalCode,
+                    country: $0.value.country.isEmpty ? nil : $0.value.country
+                )
+            } : nil,
+            urls: projection.contains("urls") && urlsAvailable ? contact.urlAddresses.map { $0.value as String } : nil,
+            note: projection.contains("note") && noteAvailable ? contact.note : nil,
+            image: (projection.contains("image") && imageAvailable && contact.thumbnailImageData != nil) ? contact.thumbnailImageData?.base64EncodedString() : nil
+        )
+    }
+
+    /// Maps a native CNGroup to the nominal GroupData model.
+    static func mapToGroupData(_ group: CNGroup) -> GroupData {
+        return GroupData(
+            id: group.identifier,
+            name: group.name,
+            source: "local",
+            readOnly: false
+        )
+    }
+}

package/ios/Sources/PeoplePlugin/Version.swift

@@ -0,0 +1,16 @@
+// This file is automatically generated. Do not modify manually.
+import Foundation
+
+/**
+  Container for the plugin's version information.
+  This enum provides a centralized, single source of truth for the native 
+  version string, synchronized directly from the project's 'package.json'.
+  It ensures parity across JavaScript, Android, and iOS platforms.
+ */
+public enum PluginVersion {
+    /**
+      The semantic version string of the plugin.
+      Value synchronized from package.json: "8.0.0"
+     */
+    public static let number = "8.0.0"
+}

package/ios/Sources/PeoplePlugin/config/PeopleConfig.swift

@@ -0,0 +1,56 @@
+import Foundation
+import Capacitor
+
+/**
+ * Plugin configuration container for the People plugin.
+ *
+ * This struct is responsible for reading and exposing static configuration
+ * values defined under the `People` key in `capacitor.config.ts`.
+ *
+ * Architectural rules:
+ * - Read once during plugin initialization (`load()`).
+ * - Treated as immutable runtime input.
+ * - Consumed only by native code (never by JavaScript).
+ */
+public struct PeopleConfig {
+
+    // MARK: - Configuration Keys
+
+    /**
+     * Internal structure to maintain consistent configuration keys.
+     */
+    private struct Keys {
+        static let verboseLogging = "verboseLogging"
+    }
+
+    // MARK: - Public Properties
+
+    /**
+     * Enables verbose native logging via PeopleLogger.
+     *
+     * When enabled, additional debug information is printed to the Xcode console.
+     * Default: false
+     */
+    public let verboseLogging: Bool
+
+    // MARK: - Private Defaults
+
+    private static let defaultVerboseLogging: Bool = false
+
+    // MARK: - Initialization
+
+    /**
+     * Initializes the configuration by reading values from the Capacitor bridge.
+     *
+     * - Parameter plugin: The CAPPlugin instance used to access typed configuration via `getConfig()`.
+     */
+    init(plugin: CAPPlugin) {
+        let config = plugin.getConfig()
+
+        // Extract verboseLogging with fallback to default
+        self.verboseLogging = config.getBoolean(
+            Keys.verboseLogging,
+            Self.defaultVerboseLogging
+        )
+    }
+}

package/ios/Sources/PeoplePlugin/error/PeopleError.swift

@@ -0,0 +1,89 @@
+import Foundation
+
+/**
+ Native error model for the People plugin (iOS).
+
+ This enum represents all error categories that can be
+ produced by the native implementation layer.
+
+ Architectural rules:
+ - Must NOT reference Capacitor
+ - Must NOT reference JavaScript
+ - Must be throwable from the Impl layer
+ - Mapping to JS-facing error codes happens ONLY in the Plugin layer
+ */
+enum PeopleError: Error {
+
+    /// Feature or capability is not available on this device or configuration
+    case unavailable(String)
+
+    /// The user cancelled an interactive flow (e.g., contact picker)
+    case cancelled(String)
+
+    /// Required permission was denied or not granted
+    case permissionDenied(String)
+
+    /// Plugin failed to initialize or perform a required operation
+    case initFailed(String)
+
+    /// The input provided to the plugin method is invalid or malformed
+    case invalidInput(String)
+
+    /// Invalid or unsupported input was provided
+    case unknownType(String)
+
+    /// The requested resource does not exist (e.g., contact or group not found)
+    case notFound(String)
+
+    /// The operation conflicts with the current state (e.g., read-only group)
+    case conflict(String)
+
+    /// The operation did not complete within the expected time
+    case timeout(String)
+
+    // MARK: - Human-readable message
+
+    /**
+     Human-readable error message.
+
+     This message is intended to be passed verbatim
+     to JavaScript via `call.reject(message, code)`.
+     */
+    var message: String {
+        switch self {
+        case .unavailable(let message):
+            return message
+        case .cancelled(let message):
+            return message
+        case .permissionDenied(let message):
+            return message
+        case .initFailed(let message):
+            return message
+        case .invalidInput(let message):
+            return message
+        case .unknownType(let message):
+            return message
+        case .notFound(let message):
+            return message
+        case .conflict(let message):
+            return message
+        case .timeout(let message):
+            return message
+        }
+    }
+
+    /// Standardized error code string for JS rejection.
+    var errorCode: String {
+        switch self {
+        case .unavailable: return "UNAVAILABLE"
+        case .cancelled: return "CANCELLED"
+        case .permissionDenied: return "PERMISSION_DENIED"
+        case .initFailed: return "INIT_FAILED"
+        case .invalidInput: return "INVALID_INPUT"
+        case .unknownType: return "UNKNOWN_TYPE"
+        case .notFound: return "NOT_FOUND"
+        case .conflict: return "CONFLICT"
+        case .timeout: return "TIMEOUT"
+        }
+    }
+}

package/ios/Sources/PeoplePlugin/error/PeopleErrorMessages.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+/// Canonical error messages shared across platforms.
+/// Keep these strings identical on iOS and Android.
+enum PeopleErrorMessages {
+    static let idRequired = "id is required"
+    static let queryRequired = "query is required"
+    static let eventNameRequired = "eventName is required"
+
+    static func unsupportedEventName(_ value: String) -> String {
+        "Unsupported eventName: \(value)"
+    }
+
+    static let missingContactsUsageDescription = "Missing NSContactsUsageDescription in Info.plist"
+    static let noContactUriReturned = "No contact URI returned"
+    static let userCancelledSelection = "User cancelled selection"
+    static let failedToParseContactFromUri = "Failed to parse contact from URI"
+
+    static func unsupportedProjectionField(_ value: String) -> String {
+        "Unsupported projection field: \(value)"
+    }
+
+    static let contactNotFound = "Contact not found"
+    static let atLeastOneWritableFieldRequired = "At least one writable contact field is required"
+}

package/ios/Sources/PeoplePlugin/logger/PeopleLogging.swift

@@ -0,0 +1,69 @@
+import Capacitor
+
+/**
+ Centralized native logger for the People plugin.
+
+ Responsibilities:
+ - Provide a single logging entry point
+ - Support runtime-controlled verbose logging
+ - Keep logging behavior consistent across files
+
+ Forbidden:
+ - Controlling application logic
+ - Being queried for flow decisions
+ */
+enum PeopleLogger {
+
+    /**
+     Controls whether debug logs are printed.
+
+     This value MUST be set once during plugin initialization
+     based on static configuration.
+     */
+    static var verbose: Bool = false
+
+    /**
+     Prints a verbose / debug log message.
+
+     Debug logs are automatically silenced
+     when `verbose` is false.
+     */
+    static func debug(_ items: Any...) {
+        guard verbose else { return }
+        log(items)
+    }
+
+    /**
+     Prints an error log message.
+
+     Error logs are always printed regardless
+     of the verbose flag.
+     */
+    static func error(_ items: Any...) {
+        log(items)
+    }
+}
+
+// MARK: - Internal log printer
+
+/**
+ Low-level log printer with a consistent prefix.
+
+ This function MUST NOT be used outside this file.
+ */
+private func log(
+    _ items: [Any],
+    separator: String = " ",
+    terminator: String = "\n"
+) {
+    CAPLog.print("⚡️ People -", terminator: separator)
+
+    for (index, item) in items.enumerated() {
+        CAPLog.print(
+            item,
+            terminator: index == items.count - 1
+                ? terminator
+                : separator
+        )
+    }
+}

package/ios/Sources/PeoplePlugin/models/ContactModels.swift

@@ -0,0 +1,68 @@
+import Foundation
+import Contacts
+
+/// Nominal model for organization data to ensure cross-platform parity.
+public struct ContactOrganization {
+    public let company: String?
+    public let title: String?
+    public let department: String?
+}
+
+/// Nominal model for a phone field.
+public struct ContactPhone {
+    public let label: String?
+    public let number: String
+}
+
+/// Nominal model for an email field.
+public struct ContactEmail {
+    public let label: String?
+    public let address: String
+}
+
+/// Nominal model for a postal address field.
+public struct ContactAddress {
+    public let label: String?
+    public let formatted: String?
+    public let street: String?
+    public let city: String?
+    public let region: String?
+    public let postcode: String?
+    public let country: String?
+}
+
+/// Nominal model representing contact data, independent of Capacitor.
+/// This ensures type safety within the Implementation layer.
+public struct ContactData {
+    public let id: String
+    public let displayName: String?
+    public let firstName: String?
+    public let lastName: String?
+    public let organization: ContactOrganization? // Updated from String? to struct
+    public let birthday: DateComponents?
+    public let phones: [ContactPhone]?
+    public let emails: [ContactEmail]?
+    public let addresses: [ContactAddress]?
+    public let urls: [String]?
+    public let note: String?
+    public let image: String? // Base64 string
+}
+
+/// Nominal model for Group data to replace raw dictionaries.
+public struct GroupData {
+    public let id: String
+    public let name: String
+    public let source: String
+    public let readOnly: Bool
+}
+
+/// Result model for paginated contact fetches.
+public struct GetContactsResultData {
+    public let contacts: [ContactData]
+    public let totalCount: Int
+}
+
+/// Result model for group listings.
+public struct ListGroupsResultData {
+    public let groups: [GroupData]
+}

package/ios/Tests/PeoplePluginTests/PeoplePluginTests.swift

@@ -0,0 +1,10 @@
+import XCTest
+@testable import People
+
+/**
+ Basic functional tests for the People plugin native implementation.
+
+ These tests validate the core behavior of the implementation
+ independently from the Capacitor bridge.
+ */
+class PeoplePluginTests: XCTestCase {}

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@cap-kit/people",
+  "version": "8.0.0",
+  "description": "Unified, high-performance contact management for Capacitor with zero-permission picking and capability-based access.",
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0",
+    "pnpm": ">=10.0.0"
+  },
+  "main": "dist/plugin.cjs",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "unpkg": "dist/plugin.js",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/plugin.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "android/src/main/",
+    "android/build.gradle",
+    "dist/",
+    "ios/Sources",
+    "ios/Tests",
+    "Package.swift",
+    "CapKitPeople.podspec",
+    "LICENSE",
+    "README.md"
+  ],
+  "author": "CapKit Team",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/cap-kit"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cap-kit/capacitor-plugins.git",
+    "directory": "packages/people"
+  },
+  "bugs": {
+    "url": "https://github.com/cap-kit/capacitor-plugins/issues"
+  },
+  "homepage": "https://github.com/cap-kit/capacitor-plugins/tree/main/packages/people#readme",
+  "keywords": [
+    "capacitor",
+    "capacitor-plugin",
+    "cap-kit",
+    "mobile",
+    "native",
+    "ios",
+    "android",
+    "contact",
+    "address-book",
+    "directory",
+    "contact-picker",
+    "privacy",
+    "performance"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@capacitor/android": "^8.1.0",
+    "@capacitor/cli": "^8.1.0",
+    "@capacitor/core": "^8.1.0",
+    "@capacitor/docgen": "^0.3.1",
+    "@capacitor/ios": "^8.1.0",
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "globals": "^17.3.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-java": "^2.8.1",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.57.1",
+    "swiftlint": "^2.0.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": ">=8.1.0"
+  },
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    },
+    "android": {
+      "src": "android"
+    }
+  },
+  "scripts": {
+    "verify": "pnpm run verify:ios && pnpm run verify:android && pnpm run verify:web",
+    "verify:ios": "node ./scripts/sync-version.mjs && xcodebuild -scheme CapKitPeople -destination generic/platform=iOS",
+    "verify:android": "cd android && ./gradlew clean build test && cd ..",
+    "verify:web": "pnpm run build",
+    "lint:android": "cd android && ./gradlew ktlintCheck",
+    "fmt:android": "cd android && ./gradlew ktlintFormat",
+    "lint": "pnpm run eslint . && pnpm run swiftlint lint --strict || true && pnpm run lint:android || true",
+    "format:check": "prettier --check \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java",
+    "format": "eslint --fix . && prettier --write \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java && pnpm run swiftlint --fix --format && pnpm run fmt:android",
+    "eslint": "eslint",
+    "prettier": "prettier \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java",
+    "swiftlint": "node-swiftlint lint ios/Sources",
+    "docgen": "docgen --api PeoplePlugin --output-readme README.md --output-json dist/docs.json",
+    "build": "node ./scripts/sync-version.mjs && pnpm run clean && pnpm run docgen && tsc && rollup -c rollup.config.mjs",
+    "clean": "rimraf ./dist",
+    "watch": "tsc --watch",
+    "test": "pnpm run verify",
+    "removePacked": "rimraf -g cap-kit-people-*.tgz",
+    "publish:locally": "pnpm run removePacked && pnpm run build && pnpm pack"
+  }
+}