@cap-kit/people 8.0.0

package/android/src/main/java/io/capkit/people/config/PeopleConfig.kt

@@ -0,0 +1,44 @@
+package io.capkit.people.config
+
+import com.getcapacitor.Plugin
+
+/**
+ * Plugin configuration holder for the People plugin.
+ *
+ * This class is responsible for reading and parsing static configuration values
+ * defined under the `plugins.People` key in `capacitor.config.ts`.
+ *
+ * Architectural rules:
+ * - Read once during plugin initialization in the load() phase.
+ * - Configuration values are read-only at runtime.
+ * - Consumed only by native code.
+ */
+class PeopleConfig(
+  plugin: Plugin,
+) {
+  // -----------------------------------------------------------------------------
+  // Properties
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Enables verbose native logging via PeopleLogger.
+   *
+   * When true, additional debug information and lifecycle events are printed to Logcat.
+   * This setting is read-only and applied during plugin initialization.
+   *
+   * Default: false
+   */
+  val verboseLogging: Boolean
+
+  // -----------------------------------------------------------------------------
+  // Initialization
+  // -----------------------------------------------------------------------------
+
+  init {
+    // Access the plugin-specific configuration object provided by Capacitor bridge
+    val config = plugin.getConfig()
+
+    // Extract verboseLogging flag with a safe default fallback
+    verboseLogging = config.getBoolean("verboseLogging", false)
+  }
+}

package/android/src/main/java/io/capkit/people/error/PeopleError.kt

@@ -0,0 +1,90 @@
+package io.capkit.people.error
+
+/**
+ * Native error model for the People plugin (Android).
+ *
+ * Architectural rules:
+ * - Must NOT reference Capacitor APIs.
+ * - Must NOT reference JavaScript directly.
+ * - Must be throwable from the Implementation (Impl) layer.
+ * - Mapping to JS-facing error codes happens ONLY in the Plugin layer.
+ */
+sealed class PeopleError(
+  message: String,
+) : Throwable(message) {
+  // -----------------------------------------------------------------------------
+  // Specific Error Types
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Feature or capability is not available due to device or configuration limitations.
+   * Maps to the 'UNAVAILABLE' error code in JavaScript.
+   */
+  class Unavailable(
+    message: String,
+  ) : PeopleError(message)
+
+  /**
+   * The user cancelled an interactive flow (e.g., contact picker).
+   * Maps to the 'CANCELLED' error code in JavaScript.
+   */
+  class Cancelled(
+    message: String,
+  ) : PeopleError(message)
+
+  /**
+   * Required permission was denied or not granted by the user.
+   * Maps to the 'PERMISSION_DENIED' error code in JavaScript.
+   */
+  class PermissionDenied(
+    message: String,
+  ) : PeopleError(message)
+
+  /**
+   * Plugin failed to initialize or perform a required native operation.
+   * Maps to the 'INIT_FAILED' error code in JavaScript.
+   */
+  class InitFailed(
+    message: String,
+  ) : PeopleError(message)
+
+  /**
+   * Invalid or malformed input was provided by the caller.
+   * Maps to the 'INVALID_INPUT' error code in JavaScript.
+   */
+  class InvalidInput(
+    message: String,
+  ) : PeopleError(message)
+
+  /**
+   * Invalid or unsupported input type was provided to the native implementation.
+   * Maps to the 'UNKNOWN_TYPE' error code in JavaScript.
+   */
+  class UnknownType(
+    message: String,
+  ) : PeopleError(message)
+
+  /**
+   * The requested resource does not exist (e.g., contact or group not found).
+   * Maps to the 'NOT_FOUND' error code in JavaScript.
+   */
+  class NotFound(
+    message: String,
+  ) : PeopleError(message)
+
+  /**
+   * The operation conflicts with the current state (e.g., read-only group).
+   * Maps to the 'CONFLICT' error code in JavaScript.
+   */
+  class Conflict(
+    message: String,
+  ) : PeopleError(message)
+
+  /**
+   * The operation did not complete within the expected time.
+   * Maps to the 'TIMEOUT' error code in JavaScript.
+   */
+  class Timeout(
+    message: String,
+  ) : PeopleError(message)
+}

package/android/src/main/java/io/capkit/people/error/PeopleErrorMessages.kt

@@ -0,0 +1,39 @@
+package io.capkit.people.error
+
+/**
+ * Canonical error messages shared across platforms.
+ * Keep these strings identical on iOS and Android.
+ */
+object PeopleErrorMessages {
+  const val PERMISSION_DENIED = "Permission denied"
+  const val ID_REQUIRED = "id is required"
+  const val QUERY_REQUIRED = "query is required"
+  const val EVENT_NAME_REQUIRED = "eventName is required"
+  const val GROUP_NAME_REQUIRED = "Group name is required"
+  const val GROUP_ID_REQUIRED = "Group ID is required"
+  const val CONTACT_IDS_REQUIRED = "Contact IDs required"
+  const val CONTACT_DATA_REQUIRED = "Contact data required"
+  const val AT_LEAST_ONE_WRITABLE_FIELD_REQUIRED = "At least one writable contact field is required"
+  const val CONTACT_ID_REQUIRED = "Contact ID is required"
+  const val REQUIRED_FIELDS_MISSING = "Required fields missing"
+  const val IDS_REQUIRED = "IDs required"
+
+  fun unsupportedEventName(value: String) = "Unsupported eventName: $value"
+
+  const val MISSING_CONTACTS_USAGE_DESCRIPTION = "Missing NSContactsUsageDescription in Info.plist"
+  const val NO_CONTACT_URI_RETURNED = "No contact URI returned"
+  const val USER_CANCELLED_SELECTION = "User cancelled selection"
+  const val FAILED_TO_PARSE_CONTACT_FROM_URI = "Failed to parse contact from URI"
+  const val ERROR_PROCESSING_CONTACT = "Error processing contact"
+
+  fun unsupportedProjectionField(value: String) = "Unsupported projection field: $value"
+
+  const val CONTACT_NOT_FOUND = "Contact not found"
+  const val FAILED = "Failed"
+  const val FAILED_TO_CREATE_GROUP = "Failed to create group"
+  const val FAILED_TO_DELETE_GROUP = "Failed to delete group"
+  const val FAILED_TO_RETRIEVE_CONTACT = "Failed to retrieve contact"
+  const val FAILED_TO_CREATE_CONTACT = "Failed to create contact"
+  const val UPDATE_FAILED = "Update failed"
+  const val MERGE_FAILED = "Merge failed"
+}

package/android/src/main/java/io/capkit/people/logger/PeopleLogger.kt

@@ -0,0 +1,85 @@
+package io.capkit.people.logger
+
+import android.util.Log
+
+/**
+ * Centralized logging utility for the People plugin.
+ *
+ * This logging provides a single entry point for all native logs
+ * and supports runtime-controlled verbose logging.
+ *
+ * The goal is to avoid scattering `if (verbose)` checks across
+ * business logic and keep logging behavior consistent.
+ */
+object PeopleLogger {
+  /**
+   * Logcat tag used for all plugin logs.
+   * Helps filtering logs during debugging.
+   */
+  private const val TAG = "⚡️ People"
+
+  /**
+   * Controls whether debug logs are printed.
+   *
+   * This flag should be set once during plugin initialization
+   * based on configuration values.
+   */
+  var verbose: Boolean = false
+
+  /**
+   * Prints a debug / verbose log message.
+   *
+   * This method should be used for development-time diagnostics
+   * and is automatically silenced when [verbose] is false.
+   *
+   * @param messages One or more message fragments to be concatenated.
+   */
+  fun debug(vararg messages: String) {
+    if (verbose) {
+      log(TAG, Log.DEBUG, *messages)
+    }
+  }
+
+  /**
+   * Prints an error log message.
+   *
+   * Error logs are always printed regardless of [verbose] state.
+   *
+   * @param message Human-readable error description.
+   * @param e Optional exception for stack trace logging.
+   */
+  fun error(
+    message: String,
+    e: Throwable? = null,
+  ) {
+    val sb = StringBuilder(message)
+    if (e != null) {
+      sb.append(" | Error: ").append(e.message)
+    }
+    Log.e(TAG, sb.toString(), e)
+  }
+
+  /**
+   * Internal low-level log dispatcher.
+   *
+   * Joins message fragments and forwards them to Android's Log API
+   * using the specified priority.
+   */
+  fun log(
+    tag: String,
+    level: Int,
+    vararg messages: String,
+  ) {
+    val sb = StringBuilder()
+    for (msg in messages) {
+      sb.append(msg).append(" ")
+    }
+    when (level) {
+      Log.DEBUG -> Log.d(tag, sb.toString())
+      Log.INFO -> Log.i(tag, sb.toString())
+      Log.WARN -> Log.w(tag, sb.toString())
+      Log.ERROR -> Log.e(tag, sb.toString())
+      else -> Log.v(tag, sb.toString())
+    }
+  }
+}

package/android/src/main/java/io/capkit/people/models/ContactModels.kt

@@ -0,0 +1,64 @@
+package io.capkit.people.models
+
+/**
+ * Native representation of a Contact.
+ *
+ * Architectural rules:
+ * - This class MUST remain agnostic to Capacitor JSObjects.
+ * - Used exclusively by the Impl layer to orchestrate native data.
+ * - Mapped to JS payloads only within the Utility or Plugin layer.
+ */
+data class ContactData(
+  val id: String,
+  val lookupKey: String? = null,
+  val displayName: String? = null,
+  val organization: ContactOrganization? = null, // Added for parity
+  val phones: List<ContactField> = emptyList(),
+  val emails: List<ContactField> = emptyList(),
+  val addresses: List<PostalAddress> = emptyList(), // Extraction logic needed
+)
+
+/**
+ * Native representation of a contact's organization.
+ */
+data class ContactOrganization(
+  val company: String?,
+  val title: String?,
+  val department: String?,
+)
+
+// -----------------------------------------------------------------------------
+// Support Models
+// -----------------------------------------------------------------------------
+
+/**
+ * Represents a generic contact field (e.g., Phone or Email).
+ * Includes a label (type) and the actual value.
+ */
+data class ContactField(
+  val label: String?,
+  val value: String?,
+)
+
+/**
+ * Native representation of a physical postal address.
+ * Maps to structured postal data from the Android Contacts provider.
+ */
+data class PostalAddress(
+  val label: String?,
+  val street: String?,
+  val city: String?,
+  val region: String?,
+  val postcode: String?,
+  val country: String?,
+)
+
+/**
+ * Native representation of a contact group.
+ */
+data class GroupData(
+  val id: String,
+  val name: String,
+  val source: String,
+  val readOnly: Boolean,
+)

package/android/src/main/java/io/capkit/people/utils/PeopleUtils.kt

@@ -0,0 +1,133 @@
+package io.capkit.people.utils
+
+import android.database.Cursor
+import android.provider.ContactsContract
+import io.capkit.people.error.PeopleError
+import io.capkit.people.models.ContactData
+
+/**
+ * Utility helpers for the People plugin.
+ *
+ * This object provides centralized logic for data transformation,
+ * cursor management, and JSON marshalling between native and bridge layers.
+ */
+object PeopleUtils {
+  // -----------------------------------------------------------------------------
+  // Projection Validation
+  // -----------------------------------------------------------------------------
+
+  private val supportedProjections =
+    setOf(
+      "name",
+      "organization",
+      "phones",
+      "emails",
+      "addresses",
+    )
+  // "image" is intentionally not supported on Android and must be rejected by validation.
+
+  /**
+   * Validates that all requested projection fields are supported.
+   * Throws PeopleError.UnknownType if a field is invalid.
+   */
+  fun validateProjection(projection: List<String>) {
+    for (field in projection) {
+      if (!supportedProjections.contains(field)) {
+        throw PeopleError.UnknownType("Unsupported projection field: $field")
+      }
+    }
+  }
+
+  /**
+   * Normalizes native labels into a shared canonical set:
+   * mobile, home, work, main, fax, other.
+   */
+  fun normalizeLabel(label: String?): String {
+    val normalized = label?.trim()?.lowercase() ?: return "other"
+    if (normalized.contains("mobile") || normalized.contains("cell")) return "mobile"
+    if (normalized.contains("home")) return "home"
+    if (normalized.contains("work")) return "work"
+    if (normalized.contains("main")) return "main"
+    if (normalized.contains("fax")) return "fax"
+    return "other"
+  }
+
+  // -----------------------------------------------------------------------------
+  // MimeType Constants
+  // -----------------------------------------------------------------------------
+
+  const val MIME_NAME = ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE
+  const val MIME_PHONE = ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
+  const val MIME_EMAIL = ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE
+  const val MIME_ORG = ContactsContract.CommonDataKinds.Organization.CONTENT_ITEM_TYPE
+  const val MIME_ADDRESS = ContactsContract.CommonDataKinds.StructuredPostal.CONTENT_ITEM_TYPE
+  const val MIME_NOTE = ContactsContract.CommonDataKinds.Note.CONTENT_ITEM_TYPE
+  const val MIME_WEBSITE = ContactsContract.CommonDataKinds.Website.CONTENT_ITEM_TYPE
+
+  // -----------------------------------------------------------------------------
+  // Cursor Helpers
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Safely retrieves a String from a Cursor column.
+   * Returns null if the column is missing or data is unavailable.
+   */
+  fun Cursor.getString(columnName: String): String? {
+    val index = this.getColumnIndex(columnName)
+    if (index == -1) return null
+    return this.getString(index)
+  }
+
+  /**
+   * Safely retrieves an Int from a Cursor column.
+   * Returns null if the column is missing or data is unavailable.
+   */
+  fun Cursor.getInt(columnName: String): Int? {
+    val index = this.getColumnIndex(columnName)
+    if (index == -1) return null
+    return this.getInt(index)
+  }
+
+  // -----------------------------------------------------------------------------
+  // Native Model Factories
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Creates a native ContactData model instance.
+   * Ensures the Implementation layer remains decoupled from Capacitor types.
+   */
+  fun createEmptyContact(
+    id: String,
+    lookupKey: String?,
+  ): ContactData =
+    ContactData(
+      id = id,
+      lookupKey = lookupKey,
+    )
+
+  // -----------------------------------------------------------------------------
+  // Bridge Marshalling (JS -> Native)
+  // -----------------------------------------------------------------------------
+
+  /**
+   * Safely extracts a list of strings from a JSONArray based on a specific key.
+   * Uses optJSONObject and optString for maximum stability during data parsing.
+   */
+  fun extractStringList(
+    array: org.json.JSONArray?,
+    key: String,
+  ): List<String> {
+    val list = mutableListOf<String>()
+    if (array == null) return list
+
+    for (i in 0 until array.length()) {
+      val obj = array.optJSONObject(i)
+      obj?.optString(key)?.let { value ->
+        if (value.isNotEmpty()) {
+          list.add(value)
+        }
+      }
+    }
+    return list
+  }
+}