@cap-kit/test-plugin 0.1.2 → 1.0.1

package/README.md

@@ -45,9 +45,10 @@ npx cap sync
 
 Configuration options for the Test plugin.
 
-| Prop                | Type                | Description                                                                                                                   | Default                       | Since |
-| ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ----- |
-| **`customMessage`** | <code>string</code> | A custom message to append to the echo response. This demonstrates how to pass data from `capacitor.config.ts` to the plugin. | <code>" (from config)"</code> | 0.0.1 |
+| Prop                 | Type                 | Description                                                                                                                                                                                                                              | Default                       | Since |
+| -------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ----- |
+| **`customMessage`**  | <code>string</code>  | Custom message appended to the echoed value. This option exists mainly as an example showing how to pass static configuration data from JavaScript to native platforms.                                                                  | <code>" (from config)"</code> | 0.0.1 |
+| **`verboseLogging`** | <code>boolean</code> | Enables verbose native logging. When enabled, additional debug information is printed to the native console (Logcat on Android, Xcode on iOS). This option affects native logging behavior only and has no impact on the JavaScript API. | <code>false</code>            | 1.0.0 |
 
 ### Examples
 
@@ -57,7 +58,8 @@ In `capacitor.config.json`:
 {
   "plugins": {
     "Test": {
-      "customMessage": " - Hello from Config!"
+      "customMessage": " - Hello from Config!",
+      "verboseLogging": true
     }
   }
 }
@@ -74,6 +76,7 @@ const config: CapacitorConfig = {
   plugins: {
     Test: {
       customMessage: ' - Hello from Config!',
+      verboseLogging: true,
     },
   },
 };
@@ -88,6 +91,7 @@ export default config;
 <docgen-index>
 
 * [`echo(...)`](#echo)
+* [`openAppSettings()`](#openappsettings)
 * [`getPluginVersion()`](#getpluginversion)
 * [Interfaces](#interfaces)
 
@@ -96,7 +100,10 @@ export default config;
 <docgen-api>
 <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
 
-Capacitor Test plugin interface.
+Public JavaScript API for the Test Capacitor plugin.
+
+This interface defines a stable, platform-agnostic API.
+All methods behave consistently across Android, iOS, and Web.
 
 ### echo(...)
 
@@ -106,12 +113,15 @@ echo(options: EchoOptions) => Promise<EchoResult>
 
 Echoes the provided value.
 
-If the plugin is configured with a `customMessage`, it will be appended
-to the response.
+If the plugin is configured with a `customMessage`, that value
+will be appended to the returned string.
+
+This method is primarily intended as an example demonstrating
+native ↔ JavaScript communication.
 
-| Param         | Type                                                | Description                                 |
-| ------------- | --------------------------------------------------- | ------------------------------------------- |
-| **`options`** | <code><a href="#echooptions">EchoOptions</a></code> | - The options containing the value to echo. |
+| Param         | Type                                                | Description                          |
+| ------------- | --------------------------------------------------- | ------------------------------------ |
+| **`options`** | <code><a href="#echooptions">EchoOptions</a></code> | Object containing the value to echo. |
 
 **Returns:** <code>Promise&lt;<a href="#echoresult">EchoResult</a>&gt;</code>
 
@@ -119,13 +129,29 @@ to the response.
 
 #### Example
 
-```typescript
-import { Test } from '@cap-kit/test-plugin';
+```ts
+const { value } = await Test.echo({ value: 'Hello' });
+console.log(value);
+```
 
-const result = await Test.echo({ value: 'Hello, World!' });
-console.log(result.value); // Output: 'Hello, World!'
+--------------------
+
+
+### openAppSettings()
+
+```typescript
+openAppSettings() => Promise<void>
 ```
 
+Opens the operating system's application settings page.
+
+This is typically used when a permission has been permanently
+denied and the user must enable it manually.
+
+On Web, this method is not supported.
+
+**Since:** 1.0.0
+
 --------------------
 
 
@@ -135,7 +161,10 @@ console.log(result.value); // Output: 'Hello, World!'
 getPluginVersion() => Promise<PluginVersionResult>
 ```
 
-Get the native Capacitor plugin version.
+Returns the native plugin version.
+
+The returned version corresponds to the native implementation
+bundled with the application.
 
 **Returns:** <code>Promise&lt;<a href="#pluginversionresult">PluginVersionResult</a>&gt;</code>
 
@@ -143,11 +172,8 @@ Get the native Capacitor plugin version.
 
 #### Example
 
-```typescript
-import { Test } from '@cap-kit/test-plugin';
-
+```ts
 const { version } = await Test.getPluginVersion();
-console.log('Plugin version:', version); // Output: Plugin version: 0.0.1
 ```
 
 --------------------
@@ -158,29 +184,35 @@ console.log('Plugin version:', version); // Output: Plugin version: 0.0.1
 
 #### EchoResult
 
-Result returned by the echo method.
+Result object returned by the `echo` method.
 
-| Prop        | Type                | Description       |
-| ----------- | ------------------- | ----------------- |
-| **`value`** | <code>string</code> | The echoed value. |
+This object represents the resolved value of the echo operation
+after native processing has completed.
+
+| Prop        | Type                | Description                                                                                                   |
+| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| **`value`** | <code>string</code> | The echoed string value. If a `customMessage` is configured, it will be appended to the original input value. |
 
 
 #### EchoOptions
 
-Options for the echo method.
+Options object for the `echo` method.
+
+This object defines the input payload sent from JavaScript
+to the native plugin implementation.
 
-| Prop        | Type                | Description             |
-| ----------- | ------------------- | ----------------------- |
-| **`value`** | <code>string</code> | The value to be echoed. |
+| Prop        | Type                | Description                                                                                                                                                      |
+| ----------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`value`** | <code>string</code> | The string value to be echoed back by the plugin. This value is passed to the native layer and returned unchanged, optionally with a configuration-based suffix. |
 
 
 #### PluginVersionResult
 
-Result returned by the getPluginVersion method.
+Result object returned by the `getPluginVersion()` method.
 
-| Prop          | Type                | Description                              |
-| ------------- | ------------------- | ---------------------------------------- |
-| **`version`** | <code>string</code> | The native version string of the plugin. |
+| Prop          | Type                | Description                       |
+| ------------- | ------------------- | --------------------------------- |
+| **`version`** | <code>string</code> | The native plugin version string. |
 
 </docgen-api>
 

package/android/build.gradle

@@ -46,7 +46,7 @@ def getPluginVersion() {
 def pluginVersion = getPluginVersion()
 
 android {
-    namespace = "com.capkit.test"
+    namespace = "io.capkit.test"
     compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion as Integer  : 36
 
     // AGP 8.0+ disables BuildConfig by default for libraries. 

package/android/src/main/java/io/capkit/test/Test.kt

@@ -0,0 +1,61 @@
+package io.capkit.test
+
+import android.content.Context
+import io.capkit.test.utils.Logger
+
+/**
+ * Platform-specific native implementation for the Test plugin.
+ *
+ * This class contains pure Android logic and MUST NOT depend
+ * directly on Capacitor bridge APIs.
+ *
+ * The Capacitor plugin class is responsible for:
+ * - reading configuration
+ * - handling PluginCall objects
+ * - delegating logic to this implementation
+ */
+class Test(
+  private val context: Context,
+) {
+  /**
+   * Cached plugin configuration.
+   * Provided once during initialization.
+   */
+  private lateinit var config: TestConfig
+
+  /**
+   * Applies the plugin configuration.
+   *
+   * This method should be called exactly once during plugin load
+   * and is responsible for translating configuration values into
+   * runtime behavior (e.g. logging verbosity).
+   */
+  fun updateConfig(newConfig: TestConfig) {
+    this.config = newConfig
+    Logger.verbose = this.config.verboseLogging
+    Logger.debug("Configuration updated. Verbose logging: ${this.config.verboseLogging}")
+  }
+
+  /**
+   * Echoes the provided value.
+   *
+   * This method represents a simple synchronous native operation
+   * and is intentionally side-effect free.
+   */
+  fun echo(value: String): String {
+    Logger.debug(value)
+    return value
+  }
+
+  companion object {
+    /**
+     * Account type identifier (example constant).
+     */
+    const val ACCOUNT_TYPE = "io.capkit.test"
+
+    /**
+     * Human-readable account name (example constant).
+     */
+    const val ACCOUNT_NAME = "Test"
+  }
+}

package/android/src/main/java/io/capkit/test/TestConfig.kt

@@ -0,0 +1,51 @@
+package io.capkit.test
+
+import android.content.Context
+import com.getcapacitor.Plugin
+
+/**
+ * Plugin configuration holder.
+ *
+ * This class is responsible for reading and parsing configuration values
+ * defined under the `Test` key in `capacitor.config.ts`.
+ *
+ * Configuration is read once during plugin initialization and treated as
+ * immutable runtime input.
+ */
+class TestConfig(plugin: Plugin) {
+  /**
+   * Android application context.
+   * Exposed for native components that may require it.
+   */
+  val context: Context
+
+  /**
+   * Enables verbose / debug logging for the plugin.
+   *
+   * When enabled, additional logs are printed to Logcat via [Logger.debug].
+   *
+   * Default: false
+   */
+  val verboseLogging: Boolean
+
+  /**
+   * Optional custom message appended to echoed values.
+   *
+   * This value is provided for demonstration purposes and shows how to
+   * pass static configuration from JavaScript to native code.
+   */
+  val customMessage: String
+
+  init {
+    context = plugin.context
+
+    val config = plugin.getConfig()
+
+    // Parse verboseLogging (default: false)
+    verboseLogging = config.getBoolean("verboseLogging", false)
+
+    // Parse customMessage (default fallback applied)
+    val cm = config.getString("customMessage")
+    customMessage = if (cm.isNullOrBlank()) " (from config)" else cm
+  }
+}

package/android/src/main/java/io/capkit/test/TestPlugin.kt

@@ -0,0 +1,116 @@
+package io.capkit.test
+
+import android.content.Intent
+import android.net.Uri
+import android.provider.Settings
+import androidx.activity.result.ActivityResult
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.ActivityCallback
+import com.getcapacitor.annotation.CapacitorPlugin
+import io.capkit.test.utils.Logger
+
+/**
+ * Capacitor bridge for the Test plugin.
+ *
+ * This class acts as the boundary between JavaScript and native Android code.
+ * It is responsible for:
+ * - reading configuration
+ * - validating PluginCall input
+ * - mapping JS calls to native logic
+ */
+@CapacitorPlugin(
+  name = "Test",
+)
+class TestPlugin : Plugin() {
+  /**
+   * Plugin configuration parsed from capacitor.config.ts.
+   */
+  private lateinit var config: TestConfig
+
+  /**
+   * Native implementation containing platform logic.
+   */
+  private lateinit var implementation: Test
+
+  /**
+   * Called once when the plugin is loaded by the Capacitor bridge.
+   *
+   * This is the correct place to:
+   * - read configuration
+   * - initialize native resources
+   * - inject dependencies into the implementation
+   */
+  override fun load() {
+    super.load()
+
+    config = TestConfig(this)
+    implementation = Test(context)
+    implementation.updateConfig(config)
+  }
+
+  // --- ---
+
+  /**
+   * Echoes a string back to JavaScript.
+   *
+   * @param call Capacitor plugin call containing the `value` parameter.
+   */
+  @PluginMethod
+  fun echo(call: PluginCall) {
+    var value = call.getString("value") ?: ""
+    Logger.debug("Echoing value: $value")
+
+    // Append the custom message from the configuration
+    value += config.customMessage
+
+    val ret = JSObject()
+    ret.put("value", implementation.echo(value))
+    call.resolve(ret)
+  }
+
+  // ---  Version ---
+
+  /**
+   * Returns the plugin version.
+   */
+  @PluginMethod
+  fun getPluginVersion(call: PluginCall) {
+    val ret = JSObject()
+    ret.put("version", BuildConfig.PLUGIN_VERSION)
+    call.resolve(ret)
+  }
+
+  // --- Settings ---
+
+  /**
+   * Opens the application details settings page.
+   * Allowing the user to manually enable permissions.
+   */
+  @PluginMethod
+  fun openAppSettings(call: PluginCall) {
+    try {
+      val intent = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS)
+      val uri = Uri.fromParts("package", context.packageName, null)
+      intent.data = uri
+      startActivityForResult(call, intent, "openSettingsResult")
+      call.resolve()
+    } catch (e: Exception) {
+      call.reject(
+        "Failed to open settings",
+        "UNAVAILABLE",
+      )
+    }
+  }
+
+  @ActivityCallback
+  private fun openSettingsResult(
+    call: PluginCall,
+    result: ActivityResult,
+  ) {
+    // No-op, just to satisfy the callback requirement if needed
+    call.resolve()
+  }
+}

package/android/src/main/java/io/capkit/test/utils/Logger.kt

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

@@ -0,0 +1,14 @@
+package io.capkit.test.utils
+
+/**
+ * Utility helpers for the Test plugin.
+ *
+ * This object is intentionally empty and serves as a placeholder
+ * for future shared utility functions.
+ *
+ * Keeping a dedicated utils package helps maintain a clean
+ * separation between core logic and helper code.
+ */
+object TestUtils {
+  // Utilities will be added here as the plugin evolves
+}