@simplysm/capacitor-plugin-intent 12.16.52 → 14.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @simplysm/capacitor-plugin-intent
 
-Capacitor Intent Plugin -- Android intent send/receive for industrial devices (barcode scanners, PDA, etc.). Provides subscription-based intent receiving, intent sending with extras, launch intent retrieval, and startActivityForResult support.
+Capacitor Intent plugin for Android broadcast communication and activity results.
 
 ## Installation
 
@@ -8,196 +8,126 @@ Capacitor Intent Plugin -- Android intent send/receive for industrial devices (b
 npm install @simplysm/capacitor-plugin-intent
 ```
 
-**Peer dependencies:**
-
-- `@capacitor/core` ^7.4.4
-
 ## API Overview
 
+### Intent
+
 | API | Type | Description |
 |-----|------|-------------|
-| `Intent` | Abstract class | Static methods for subscribing to, sending, and managing Android intents |
-| `IIntentResult` | Interface | Intent result containing action and extras |
-| `IStartActivityForResultOptions` | Interface | Options for starting an activity for result |
-| `IActivityResult` | Interface | Activity result containing resultCode, data, and extras |
-| `IIntentPlugin` | Interface | Low-level Capacitor plugin interface for intent operations |
+| `IntentResult` | Interface | Data received from a broadcast or launch intent |
+| `StartActivityForResultOptions` | Interface | Options for starting an Android activity and awaiting its result |
+| `StartActivityForResultResult` | Interface | Result returned from a started activity |
+| `IntentPlugin` | Interface | Native plugin interface for intent operations |
+| `Intent` | Class | Static API for broadcast send/receive, launch intents, and activity results |
 
-## API Reference
+## Interfaces
 
-### `IIntentResult`
+### IntentResult
 
-Result object received from an intent or launch intent.
-
-```typescript
-export interface IIntentResult {
-  /** Intent action */
-  action?: string;
-  /** Extra data */
-  extras?: Record<string, unknown>;
-}
-```
+Data received from a broadcast or launch intent.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `action` | `string \| undefined` | The intent action string |
-| `extras` | `Record<string, unknown> \| undefined` | Extra data attached to the intent |
-
-### `IStartActivityForResultOptions`
-
-Options for starting an activity and receiving its result.
-
-```typescript
-export interface IStartActivityForResultOptions {
-  /** Intent action */
-  action: string;
-  /** Data URI */
-  uri?: string;
-  /** Extra data */
-  extras?: Record<string, unknown>;
-  /** Target package name */
-  package?: string;
-  /** Target component class name */
-  component?: string;
-  /** MIME type */
-  type?: string;
-}
-```
+| `action` | `string \| undefined` | The intent action string (e.g. `"com.example.SCAN_RESULT"`) |
+| `extras` | `Record<string, unknown> \| undefined` | Key-value map of intent extras |
+
+### StartActivityForResultOptions
+
+Options for launching an Android activity and awaiting its result.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `action` | `string` | Intent action (required) |
-| `uri` | `string \| undefined` | Data URI |
-| `extras` | `Record<string, unknown> \| undefined` | Extra data to include in the intent |
-| `package` | `string \| undefined` | Target package name |
-| `component` | `string \| undefined` | Target component class name (requires `package`) |
-| `type` | `string \| undefined` | MIME type |
-
-### `IActivityResult`
-
-Result returned from a started activity.
-
-```typescript
-export interface IActivityResult {
-  /** Activity result code (RESULT_OK = -1, RESULT_CANCELED = 0) */
-  resultCode: number;
-  /** Result data URI */
-  data?: string;
-  /** Result extras */
-  extras?: Record<string, unknown>;
-}
-```
+| `action` | `string \| undefined` | Intent action (e.g. `"android.intent.action.VIEW"`) |
+| `uri` | `string \| undefined` | Data URI to pass to the intent |
+| `extras` | `Record<string, unknown> \| undefined` | Extra key-value pairs to include |
+| `type` | `string \| undefined` | MIME type (e.g. `"image/*"`) |
+| `packageName` | `string \| undefined` | Target package name for an explicit intent |
+| `className` | `string \| undefined` | Target class name for an explicit intent |
+| `flags` | `number \| undefined` | Intent flags bitmask |
+
+### StartActivityForResultResult
+
+Result returned when a launched activity finishes.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `resultCode` | `number` | Activity result code (`RESULT_OK = -1`, `RESULT_CANCELED = 0`) |
-| `data` | `string \| undefined` | Result data URI |
-| `extras` | `Record<string, unknown> \| undefined` | Result extras |
-
-### `IIntentPlugin`
-
-Low-level Capacitor plugin interface. Use `Intent` instead for a simplified API.
-
-```typescript
-export interface IIntentPlugin {
-  subscribe(
-    options: { filters: string[] },
-    callback: (result: IIntentResult) => void,
-  ): Promise<{ id: string }>;
-  unsubscribe(options: { id: string }): Promise<void>;
-  unsubscribeAll(): Promise<void>;
-  send(options: { action: string; extras?: Record<string, unknown> }): Promise<void>;
-  getLaunchIntent(): Promise<IIntentResult>;
-  startActivityForResult(options: IStartActivityForResultOptions): Promise<IActivityResult>;
-}
-```
+| `resultCode` | `number` | Android result code (`RESULT_OK = -1`, `RESULT_CANCELED = 0`) |
+| `data` | `{ action?: string; uri?: string; extras?: Record<string, unknown> } \| undefined` | Optional data returned by the activity, including its action, URI, and extras |
 
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `subscribe` | `options: { filters: string[] }, callback` | `Promise<{ id: string }>` | Register an intent receiver with action filters |
-| `unsubscribe` | `options: { id: string }` | `Promise<void>` | Remove a specific intent receiver by ID |
-| `unsubscribeAll` | -- | `Promise<void>` | Remove all intent receivers |
-| `send` | `options: { action, extras? }` | `Promise<void>` | Send an intent with action and optional extras |
-| `getLaunchIntent` | -- | `Promise<IIntentResult>` | Get the intent that launched the app |
-| `startActivityForResult` | `options: IStartActivityForResultOptions` | `Promise<IActivityResult>` | Start an activity and receive its result |
+### IntentPlugin
 
-### `Intent`
+Native plugin interface for intent operations.
 
-Abstract class with static methods for Android intent send/receive. Designed for industrial device integration (barcode scanners, PDA, etc.).
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `subscribe` | `(options: { filters: string[] }, callback: (result: IntentResult) => void) => Promise<{ id: string }>` | Register a broadcast receiver for the given action filters |
+| `unsubscribe` | `(options: { id: string }) => Promise<void>` | Unregister a broadcast receiver by subscription ID |
+| `unsubscribeAll` | `() => Promise<void>` | Unregister all broadcast receivers |
+| `send` | `(options: { action: string; extras?: Record<string, unknown> }) => Promise<void>` | Send a broadcast intent |
+| `getLaunchIntent` | `() => Promise<IntentResult>` | Get the intent that launched the current activity |
+| `addListener` | `(eventName: "newIntent", listenerFunc: (data: IntentResult) => void) => Promise<PluginListenerHandle>` | Listen for new intents delivered to the activity |
+| `removeAllListeners` | `() => Promise<void>` | Remove all event listeners |
+| `startActivityForResult` | `(options: StartActivityForResultOptions) => Promise<StartActivityForResultResult>` | Start an activity and await its result |
 
-```typescript
-export abstract class Intent {
-  static async subscribe(
-    filters: string[],
-    callback: (result: IIntentResult) => void,
-  ): Promise<() => Promise<void>>;
+## Classes
 
-  static async unsubscribeAll(): Promise<void>;
+### Intent
 
-  static async send(options: {
-    action: string;
-    extras?: Record<string, unknown>;
-  }): Promise<void>;
+Android Intent plugin for broadcast send/receive and launch intent handling. Designed for industrial devices such as barcode scanners and PDAs.
 
-  static async getLaunchIntent(): Promise<IIntentResult>;
+All methods are static.
 
-  static async startActivityForResult(
-    options: IStartActivityForResultOptions,
-  ): Promise<IActivityResult>;
-}
-```
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `subscribe` | `filters: string[], callback: (result: IIntentResult) => void` | `Promise<() => Promise<void>>` | Register an intent receiver; returns an unsubscribe function |
-| `unsubscribeAll` | -- | `Promise<void>` | Remove all registered intent receivers |
-| `send` | `options: { action: string; extras?: Record<string, unknown> }` | `Promise<void>` | Send an intent with action and optional extras |
-| `getLaunchIntent` | -- | `Promise<IIntentResult>` | Retrieve the intent that launched the application |
-| `startActivityForResult` | `options: IStartActivityForResultOptions` | `Promise<IActivityResult>` | Start an activity and receive its result |
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `subscribe` | `static async subscribe(filters: string[], callback: (result: IntentResult) => void): Promise<() => Promise<void>>` | Register a broadcast receiver for the given action filters. Returns an async unsubscribe function. |
+| `unsubscribeAll` | `static async unsubscribeAll(): Promise<void>` | Unregister all active broadcast receivers |
+| `send` | `static async send(options: { action: string; extras?: Record<string, unknown> }): Promise<void>` | Send a broadcast intent with the specified action and optional extras |
+| `getLaunchIntent` | `static async getLaunchIntent(): Promise<IntentResult>` | Retrieve the intent that launched the current activity |
+| `addListener` | `static async addListener(eventName: "newIntent", callback: (result: IntentResult) => void): Promise<PluginListenerHandle>` | Add a listener for new intents delivered to the activity via `onNewIntent` |
+| `removeAllListeners` | `static async removeAllListeners(): Promise<void>` | Remove all registered event listeners |
+| `startActivityForResult` | `static async startActivityForResult(options: StartActivityForResultOptions): Promise<StartActivityForResultResult>` | Start an Android activity and return its result when it finishes |
 
 ## Usage Examples
 
-### Subscribe to intents from a barcode scanner
+### Subscribe to barcode scanner broadcasts
 
-```typescript
+```ts
 import { Intent } from "@simplysm/capacitor-plugin-intent";
 
 const unsubscribe = await Intent.subscribe(
-  ["com.symbol.datawedge.api.RESULT_ACTION"],
+  ["com.example.scanner.BARCODE_RESULT"],
   (result) => {
-    console.log("Action:", result.action);
-    console.log("Extras:", result.extras);
+    const barcode = result.extras?.["barcode"] as string;
+    handleBarcode(barcode);
   },
 );
 
-// Later, unsubscribe
+// Later, stop listening
 await unsubscribe();
 ```
 
-### Send an intent to trigger a scan
+### Send a broadcast
 
-```typescript
+```ts
 import { Intent } from "@simplysm/capacitor-plugin-intent";
 
 await Intent.send({
-  action: "com.symbol.datawedge.api.ACTION",
-  extras: {
-    "com.symbol.datawedge.api.SOFT_SCAN_TRIGGER": "TOGGLE_SCANNING",
-  },
+  action: "com.example.ACTION_TRIGGER_SCAN",
+  extras: { mode: "continuous" },
 });
 ```
 
 ### Start an activity for result
 
-```typescript
+```ts
 import { Intent } from "@simplysm/capacitor-plugin-intent";
 
 const result = await Intent.startActivityForResult({
-  action: "android.intent.action.GET_CONTENT",
+  action: "android.intent.action.PICK",
   type: "image/*",
 });
 
-if (result.resultCode === -1) {
-  // RESULT_OK
-  console.log("Selected:", result.data);
+if (result.resultCode === -1 && result.data?.uri) {
+  loadImage(result.data.uri);
 }
 ```

package/android/build.gradle

@@ -1,4 +1,5 @@
 apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
 
 android {
     namespace "kr.co.simplysm.capacitor.intent"

package/android/src/main/kotlin/kr/co/simplysm/capacitor/intent/IntentPlugin.kt

@@ -0,0 +1,365 @@
+package kr.co.simplysm.capacitor.intent
+
+import android.content.BroadcastReceiver
+import android.content.ComponentName
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.net.Uri
+import android.os.Build
+import android.os.Bundle
+import android.os.Parcelable
+import android.util.Log
+import androidx.activity.result.ActivityResult
+import com.getcapacitor.JSArray
+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 org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+import java.util.UUID
+
+@CapacitorPlugin(name = "Intent")
+class IntentPlugin : Plugin() {
+
+    companion object {
+        private const val TAG = "IntentPlugin"
+    }
+
+    private val receivers = mutableMapOf<String, BroadcastReceiver>()
+
+    override fun handleOnNewIntent(intent: Intent) {
+        super.handleOnNewIntent(intent)
+        notifyListeners("newIntent", intentToJson(intent))
+    }
+
+    @PluginMethod(returnType = PluginMethod.RETURN_CALLBACK)
+    fun subscribe(call: PluginCall) {
+        try {
+            val filters = call.getArray("filters")
+
+            if (filters == null || filters.length() == 0) {
+                call.reject("filters is required")
+                return
+            }
+
+            call.setKeepAlive(true)
+
+            val receiverId = UUID.randomUUID().toString()
+
+            val intentFilter = IntentFilter()
+            for (i in 0 until filters.length()) {
+                intentFilter.addAction(filters.getString(i))
+            }
+
+            val receiver = object : BroadcastReceiver() {
+                override fun onReceive(context: Context, intent: Intent) {
+                    val result = intentToJson(intent)
+                    result.put("id", receiverId)
+                    call.resolve(result)
+                }
+            }
+
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                context.registerReceiver(receiver, intentFilter, Context.RECEIVER_EXPORTED)
+            } else {
+                context.registerReceiver(receiver, intentFilter)
+            }
+
+            receivers[receiverId] = receiver
+
+            val ret = JSObject()
+            ret.put("id", receiverId)
+            call.resolve(ret)
+        } catch (e: Exception) {
+            Log.e(TAG, "subscribe failed", e)
+            call.reject("subscribe failed: " + e.message)
+        }
+    }
+
+    @PluginMethod
+    fun unsubscribe(call: PluginCall) {
+        try {
+            val id = call.getString("id")
+            if (id == null) {
+                call.reject("id is required")
+                return
+            }
+
+            val receiver = receivers.remove(id)
+            if (receiver != null) {
+                context.unregisterReceiver(receiver)
+            }
+
+            call.resolve()
+        } catch (e: Exception) {
+            Log.e(TAG, "unsubscribe failed", e)
+            call.reject("unsubscribe failed: " + e.message)
+        }
+    }
+
+    @PluginMethod
+    fun unsubscribeAll(call: PluginCall) {
+        try {
+            for (receiver in receivers.values) {
+                try {
+                    context.unregisterReceiver(receiver)
+                } catch (ignored: Exception) {
+                }
+            }
+            receivers.clear()
+            call.resolve()
+        } catch (e: Exception) {
+            Log.e(TAG, "unsubscribeAll failed", e)
+            call.reject("unsubscribeAll failed: " + e.message)
+        }
+    }
+
+    @PluginMethod
+    fun send(call: PluginCall) {
+        try {
+            val action = call.getString("action")
+            if (action == null) {
+                call.reject("action is required")
+                return
+            }
+
+            val intent = Intent(action)
+
+            val extras = call.getObject("extras")
+            if (extras != null) {
+                populateExtras(intent, extras)
+            }
+
+            context.sendBroadcast(intent)
+            call.resolve()
+        } catch (e: Exception) {
+            Log.e(TAG, "send failed", e)
+            call.reject("send failed: " + e.message)
+        }
+    }
+
+    @PluginMethod
+    fun getLaunchIntent(call: PluginCall) {
+        try {
+            val intent = activity.intent
+            call.resolve(intentToJson(intent))
+        } catch (e: Exception) {
+            Log.e(TAG, "getLaunchIntent failed", e)
+            call.reject("getLaunchIntent failed: " + e.message)
+        }
+    }
+
+    @PluginMethod
+    fun startActivityForResult(call: PluginCall) {
+        try {
+            val intent = buildIntent(call)
+            startActivityForResult(call, intent, "handleActivityResult")
+        } catch (e: Exception) {
+            Log.e(TAG, "startActivityForResult failed", e)
+            call.reject("startActivityForResult failed: " + e.message)
+        }
+    }
+
+    @ActivityCallback
+    private fun handleActivityResult(call: PluginCall?, result: ActivityResult) {
+        if (call == null) {
+            return
+        }
+
+        val json = JSObject()
+        json.put("resultCode", result.resultCode)
+
+        val data = result.data
+        if (data != null) {
+            val dataJson = JSObject()
+            if (data.action != null) {
+                dataJson.put("action", data.action)
+            }
+            if (data.data != null) {
+                dataJson.put("uri", data.data.toString())
+            }
+            val extras = data.extras
+            if (extras != null) {
+                dataJson.put("extras", bundleToJson(extras))
+            }
+            json.put("data", dataJson)
+        }
+
+        call.resolve(json)
+    }
+
+    private fun buildIntent(call: PluginCall): Intent {
+        val intent = Intent()
+
+        val action = call.getString("action")
+        if (action != null) {
+            intent.action = action
+        }
+
+        val uri = call.getString("uri")
+        val type = call.getString("type")
+        when {
+            uri != null && type != null -> intent.setDataAndType(Uri.parse(uri), type)
+            uri != null -> intent.data = Uri.parse(uri)
+            type != null -> intent.type = type
+        }
+
+        val extras = call.getObject("extras")
+        if (extras != null) {
+            populateExtras(intent, extras)
+        }
+
+        val packageName = call.getString("packageName")
+        val className = call.getString("className")
+        when {
+            packageName != null && className != null ->
+                intent.component = ComponentName(packageName, className)
+            packageName != null -> intent.setPackage(packageName)
+        }
+
+        val flags = call.getInt("flags")
+        if (flags != null) {
+            intent.addFlags(flags)
+        }
+
+        return intent
+    }
+
+    @Throws(JSONException::class)
+    private fun populateExtras(intent: Intent, extras: JSObject) {
+        val keys = extras.keys()
+        while (keys.hasNext()) {
+            val key = keys.next()
+            val value = extras.get(key)
+
+            when (value) {
+                is String -> intent.putExtra(key, value)
+                is Int -> intent.putExtra(key, value)
+                is Long -> intent.putExtra(key, value)
+                is Double -> intent.putExtra(key, value)
+                is Boolean -> intent.putExtra(key, value)
+                is JSONArray -> {
+                    val strArr = Array(value.length()) { i -> value.getString(i) }
+                    intent.putExtra(key, strArr)
+                }
+                is JSONObject -> {
+                    val bundle = jsonToBundle(value)
+                    intent.putExtra(key, bundle)
+                }
+            }
+        }
+    }
+
+    @Throws(JSONException::class)
+    private fun jsonToBundle(json: JSONObject): Bundle {
+        val bundle = Bundle()
+        val keys = json.keys()
+        while (keys.hasNext()) {
+            val key = keys.next()
+            val value = json.get(key)
+
+            when (value) {
+                is String -> bundle.putString(key, value)
+                is Int -> bundle.putInt(key, value)
+                is Long -> bundle.putLong(key, value)
+                is Double -> bundle.putDouble(key, value)
+                is Boolean -> bundle.putBoolean(key, value)
+            }
+        }
+        return bundle
+    }
+
+    private fun intentToJson(intent: Intent?): JSObject {
+        val json = JSObject()
+
+        if (intent == null) {
+            return json
+        }
+
+        try {
+            json.put("action", intent.action)
+
+            val extras = intent.extras
+            if (extras != null) {
+                json.put("extras", bundleToJson(extras))
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "intentToJson failed", e)
+        }
+
+        return json
+    }
+
+    private fun bundleToJson(bundle: Bundle?): JSObject {
+        val json = JSObject()
+
+        if (bundle == null) {
+            return json
+        }
+
+        for (key in bundle.keySet()) {
+            try {
+                val value = bundle.get(key)
+
+                when (value) {
+                    null -> json.put(key, JSONObject.NULL)
+                    is String -> json.put(key, value)
+                    is Int -> json.put(key, value)
+                    is Long -> json.put(key, value)
+                    is Double -> json.put(key, value)
+                    is Float -> json.put(key, value.toDouble())
+                    is Boolean -> json.put(key, value)
+                    is Bundle -> json.put(key, bundleToJson(value))
+                    is Array<*> -> {
+                        if (value.isArrayOf<String>()) {
+                            val arr = JSArray()
+                            @Suppress("UNCHECKED_CAST")
+                            for (s in value as Array<String>) {
+                                arr.put(s)
+                            }
+                            json.put(key, arr)
+                        } else if (value.isArrayOf<Parcelable>()) {
+                            val arr = JSArray()
+                            @Suppress("UNCHECKED_CAST")
+                            for (p in value as Array<Parcelable>) {
+                                arr.put(p.toString())
+                            }
+                            json.put(key, arr)
+                        } else {
+                            json.put(key, value.toString())
+                        }
+                    }
+                    is IntArray -> {
+                        val arr = JSArray()
+                        for (i in value) {
+                            arr.put(i)
+                        }
+                        json.put(key, arr)
+                    }
+                    is Parcelable -> json.put(key, value.toString())
+                    else -> json.put(key, value.toString())
+                }
+            } catch (e: Exception) {
+                Log.w(TAG, "bundleToJson key failed: $key", e)
+            }
+        }
+
+        return json
+    }
+
+    override fun handleOnDestroy() {
+        for (receiver in receivers.values) {
+            try {
+                context.unregisterReceiver(receiver)
+            } catch (ignored: Exception) {
+            }
+        }
+        receivers.clear()
+        super.handleOnDestroy()
+    }
+}