@cap-kit/settings 8.0.0-next.0

package/android/src/main/java/io/capkit/settings/SettingsImpl.kt

@@ -0,0 +1,95 @@
+package io.capkit.settings
+
+import android.content.Context
+import android.content.Intent
+import io.capkit.settings.utils.SettingsLogger
+import io.capkit.settings.utils.SettingsUtils
+
+/**
+ * Platform-specific native implementation for the Settings plugin (Android).
+ *
+ * This class contains ONLY Android platform logic and MUST NOT:
+ * - depend on Capacitor APIs
+ * - reference PluginCall
+ * - perform JS-related validation
+ *
+ * The Capacitor plugin (SettingsPlugin) is responsible for:
+ * - reading configuration
+ * - extracting call parameters
+ * - resolving results to JavaScript
+ */
+class SettingsImpl(
+  private val context: Context,
+) {
+  /**
+   * Cached plugin configuration.
+   * Injected once during plugin initialization.
+   */
+  private lateinit var config: SettingsConfig
+
+  /**
+   * Applies plugin configuration.
+   *
+   * This method MUST be called exactly once from the plugin's load() method.
+   * It translates static configuration into runtime behavior
+   * (e.g. enabling verbose logging).
+   */
+  fun updateConfig(newConfig: SettingsConfig) {
+    this.config = newConfig
+    SettingsLogger.verbose = newConfig.verboseLogging
+    SettingsLogger.debug(
+      "Configuration applied. Verbose logging:",
+      newConfig.verboseLogging.toString(),
+    )
+  }
+
+  /**
+   * Opens an Android system settings screen.
+   *
+   * The operation is considered successful if:
+   * - the option maps to a valid Intent
+   * - an Activity exists to handle the Intent
+   *
+   * No Activity result is awaited, by design.
+   *
+   * @param option JavaScript-facing settings key
+   * @return standardized Result object (state-based)
+   */
+  fun open(option: String): Result {
+    SettingsLogger.debug("Requested Android settings option:", option)
+
+    val intent =
+      SettingsUtils.resolveIntent(option, context.packageName)
+        ?: return Result(
+          success = false,
+          error = "Requested setting is not available on Android",
+          code = "UNAVAILABLE",
+        )
+
+    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+
+    return if (intent.resolveActivity(context.packageManager) != null) {
+      context.startActivity(intent)
+      SettingsLogger.debug("Android settings activity started:", intent.action ?: "unknown")
+      Result(success = true)
+    } else {
+      SettingsLogger.error("No activity found to handle intent for option: $option")
+      Result(
+        success = false,
+        error = "Cannot open settings URL",
+        code = "UNAVAILABLE",
+      )
+    }
+  }
+
+  /**
+   * Standardized result returned by Settings operations.
+   *
+   * This mirrors the iOS result model and the public TypeScript API.
+   */
+  data class Result(
+    val success: Boolean,
+    val error: String? = null,
+    val code: String? = null,
+  )
+}

package/android/src/main/java/io/capkit/settings/SettingsPlugin.kt

@@ -0,0 +1,91 @@
+package io.capkit.settings
+
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+
+/**
+ * Capacitor bridge for the Settings plugin (Android).
+ *
+ * Responsibilities:
+ * - read configuration
+ * - extract PluginCall input
+ * - delegate logic to SettingsImpl
+ * - resolve calls with standardized results
+ *
+ * This class MUST NOT contain platform logic.
+ */
+@CapacitorPlugin(
+  name = "Settings",
+)
+class SettingsPlugin : Plugin() {
+  /**
+   * Plugin configuration parsed from capacitor.config.ts.
+   */
+  private lateinit var config: SettingsConfig
+
+  /**
+   * Native implementation containing Android-specific logic.
+   */
+  private lateinit var implementation: SettingsImpl
+
+  /**
+   * Plugin lifecycle entry point.
+   *
+   * Called exactly once when the plugin is loaded.
+   */
+  override fun load() {
+    super.load()
+
+    config = SettingsConfig(this)
+    implementation = SettingsImpl(context)
+    implementation.updateConfig(config)
+  }
+
+  // --- Open Settings ---
+
+  /**
+   * Opens a platform-specific settings screen (legacy key).
+   */
+  @PluginMethod
+  fun open(call: PluginCall) {
+    val option = call.getString("optionAndroid") ?: ""
+    val result = implementation.open(option)
+    call.resolve(result.toJS())
+  }
+
+  /**
+   * Opens an Android settings screen.
+   */
+  @PluginMethod
+  fun openAndroid(call: PluginCall) {
+    val option = call.getString("option") ?: ""
+    val result = implementation.open(option)
+    call.resolve(result.toJS())
+  }
+
+  // --- Version ---
+
+  /**
+   * Returns the native plugin version.
+   */
+  @PluginMethod
+  fun getPluginVersion(call: PluginCall) {
+    val ret = JSObject()
+    ret.put("version", BuildConfig.PLUGIN_VERSION)
+    call.resolve(ret)
+  }
+
+  /**
+   * Converts a native Result into a JSObject.
+   */
+  private fun SettingsImpl.Result.toJS(): JSObject {
+    val obj = JSObject()
+    obj.put("success", success)
+    if (error != null) obj.put("error", error)
+    if (code != null) obj.put("code", code)
+    return obj
+  }
+}

package/android/src/main/java/io/capkit/settings/utils/SettingsLogger.kt

@@ -0,0 +1,85 @@
+package io.capkit.settings.utils
+
+import android.util.Log
+
+/**
+ * Centralized logging utility for the Settings 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 SettingsLogger {
+  /**
+   * Logcat tag used for all plugin logs.
+   * Helps filtering logs during debugging.
+   */
+  private const val TAG = "⚡️ Settings"
+
+  /**
+   * 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/settings/utils/SettingsUtils.kt

@@ -0,0 +1,75 @@
+package io.capkit.settings.utils
+
+import android.content.Intent
+import android.net.Uri
+import android.provider.Settings
+
+/**
+ * Utility helpers for resolving Android system settings Intents.
+ *
+ * This object contains ONLY mapping logic and MUST NOT:
+ * - start activities
+ * - access Context or PackageManager
+ * - depend on Capacitor APIs
+ *
+ * It maps JavaScript-facing option strings to Android Intent instances.
+ */
+object SettingsUtils {
+  /**
+   * Resolves a JavaScript settings option into an Android Intent.
+   *
+   * @param option JavaScript-facing option key
+   * @param packageName Application package name (used where required)
+   * @return A configured Intent, or null if the option is unsupported
+   */
+  fun resolveIntent(
+    option: String,
+    packageName: String,
+  ): Intent? {
+    return when (option) {
+      // --- App-specific ---
+      "application_details" ->
+        Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS).apply {
+          data = Uri.parse("package:$packageName")
+        }
+
+      "app_notification" ->
+        Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS).apply {
+          putExtra(Settings.EXTRA_APP_PACKAGE, packageName)
+        }
+
+      // --- Core system settings ---
+      "accessibility" -> Intent(Settings.ACTION_ACCESSIBILITY_SETTINGS)
+      "airplane_mode" -> Intent(Settings.ACTION_AIRPLANE_MODE_SETTINGS)
+      "apn" -> Intent(Settings.ACTION_APN_SETTINGS)
+      "application" -> Intent(Settings.ACTION_APPLICATION_SETTINGS)
+      "battery_optimization" -> Intent(Settings.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS)
+      "bluetooth" -> Intent(Settings.ACTION_BLUETOOTH_SETTINGS)
+      "cast" -> Intent(Settings.ACTION_CAST_SETTINGS)
+      "data_roaming" -> Intent(Settings.ACTION_DATA_ROAMING_SETTINGS)
+      "date" -> Intent(Settings.ACTION_DATE_SETTINGS)
+      "display" -> Intent(Settings.ACTION_DISPLAY_SETTINGS)
+      "home" -> Intent(Settings.ACTION_HOME_SETTINGS)
+      "location" -> Intent(Settings.ACTION_LOCATION_SOURCE_SETTINGS)
+      "nfc" -> Intent(Settings.ACTION_NFC_SETTINGS)
+      "nfcsharing" -> Intent(Settings.ACTION_NFCSHARING_SETTINGS)
+      "nfc_payment" -> Intent(Settings.ACTION_NFC_PAYMENT_SETTINGS)
+      "print" -> Intent(Settings.ACTION_PRINT_SETTINGS)
+      "security" -> Intent(Settings.ACTION_SECURITY_SETTINGS)
+      "settings" -> Intent(Settings.ACTION_SETTINGS)
+      "sound" -> Intent(Settings.ACTION_SOUND_SETTINGS)
+      "storage" -> Intent(Settings.ACTION_INTERNAL_STORAGE_SETTINGS)
+      "usage" -> Intent(Settings.ACTION_USAGE_ACCESS_SETTINGS)
+      "vpn" -> Intent(Settings.ACTION_VPN_SETTINGS)
+      "wifi" -> Intent(Settings.ACTION_WIFI_SETTINGS)
+
+      // --- Advanced / device-dependent ---
+      "zen_mode" -> Intent("android.settings.ZEN_MODE_SETTINGS")
+      "zen_mode_priority" -> Intent(Settings.ACTION_ZEN_MODE_PRIORITY_SETTINGS)
+      "zen_mode_blocked_effects" -> Intent("android.settings.ZEN_MODE_BLOCKED_EFFECTS_SETTINGS")
+      "text_to_speech" -> Intent("com.android.settings.TTS_SETTINGS")
+
+      else -> null
+    }
+  }
+}