@capgo/capacitor-zebra-datawedge 8.2.3 → 8.2.5

package/README.md

@@ -155,10 +155,20 @@ console.log(result);
 - `softRfidTrigger()` uses the first registered scan intent action. Register a scan action first if you need RFID reads.
 - Web and iOS return "not available" errors for all DataWedge operations.
 
+## Broadcast compatibility and security
+
+DataWedge can return query results without `COMMAND_IDENTIFIER`. The plugin accepts such a result only when its payload type matches exactly one pending query that expects that payload shape. Avoid overlapping pending calls that share the same result payload shape: replies without identifiers cannot reliably distinguish their owners. For example, `getAssociatedApps()` and `getConfig()` both send `CMD_GET_CONFIG` and expect `CONFIG_RESULTS`, so one pending call to each still overlaps. If a query times out, a delayed identifier-free reply to the timed-out query can still match a later sequential call that expects the same payload shape and resolve it with stale data. Replies with unknown nonempty identifiers are not assigned to another query.
+
+On Android 14/API 34 and later, identifier-free replies that share platform sender identity must identify the DataWedge package. A sender can withhold its identity on API 34 and later, and the plugin then accepts matching identifier-free results. Identity is also unavailable on Android API 24 to 33, where the plugin accepts matching identifier-free results for compatibility with DataWedge.
+
+Query correlation and payload validation do not guarantee sender authenticity. Any installed app can inject a matching identifier-free query result on every Android version, including by withholding its identity on API 34 and later. Replies with matching command identifiers, scan data and notification broadcasts also lack complete sender authentication. See the [known sender-authentication limitations](https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25) for details.
+
 ## API
 
 <docgen-index>
 
+- [`configureDiagnostics(...)`](#configurediagnostics)
+- [`getDiagnostics()`](#getdiagnostics)
 - [`cloneProfile(...)`](#cloneprofile)
 - [`createProfile(...)`](#createprofile)
 - [`deleteProfile(...)`](#deleteprofile)
@@ -207,6 +217,34 @@ console.log(result);
 <docgen-api>
 <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
 
+### configureDiagnostics(...)
+
+```typescript
+configureDiagnostics(options: DiagnosticsOptions) => Promise<void>
+```
+
+Configure opt-in native command metadata tracing. Never enables DataWedge or scanner input.
+
+| Param         | Type                                                              |
+| ------------- | ----------------------------------------------------------------- |
+| **`options`** | <code><a href="#diagnosticsoptions">DiagnosticsOptions</a></code> |
+
+---
+
+### getDiagnostics()
+
+```typescript
+getDiagnostics() => Promise<DataWedgeDiagnosticsSnapshot>
+```
+
+Return a read-only native environment and trace snapshot. Does not send any DataWedge commands.
+Barcode values, intent bodies and arbitrary exception text are excluded. The application decides
+which device information to include when sharing this snapshot. Android only.
+
+**Returns:** <code>Promise&lt;<a href="#datawedgediagnosticssnapshot">DataWedgeDiagnosticsSnapshot</a>&gt;</code>
+
+---
+
 ### cloneProfile(...)
 
 ```typescript
@@ -365,6 +403,15 @@ Dispose of local listeners separately when using the low-level API.
 enumerateScanners() => Promise<{ scanners: ZebraDeviceScanner[]; }>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. When sender
+identity is unavailable (Android API 24 to 33, or API 34+ when the platform withholds it),
+matching identifier-free replies are accepted for compatibility. If a call times out, a delayed
+identifier-free reply can still match a later sequential call that expects the same shape and
+resolve it with stale data. This default may change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 **Returns:** <code>Promise&lt;{ scanners: ZebraDeviceScanner[]; }&gt;</code>
 
 ---
@@ -375,6 +422,15 @@ enumerateScanners() => Promise<{ scanners: ZebraDeviceScanner[]; }>
 getActiveProfile() => Promise<{ profileName: string; }>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. When sender
+identity is unavailable (Android API 24 to 33, or API 34+ when the platform withholds it),
+matching identifier-free replies are accepted for compatibility. If a call times out, a delayed
+identifier-free reply can still match a later sequential call that expects the same shape and
+resolve it with stale data. This default may change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 **Returns:** <code>Promise&lt;{ profileName: string; }&gt;</code>
 
 ---
@@ -385,6 +441,17 @@ getActiveProfile() => Promise<{ profileName: string; }>
 getAssociatedApps(options: { profileName: string; }) => Promise<{ appList: DataWedgeAppConfig[]; }>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. For example,
+`getAssociatedApps()` and `getConfig()` both send `CMD_GET_CONFIG` and expect `CONFIG_RESULTS`, so one
+pending call to each overlaps. When sender identity is unavailable (Android API 24 to 33, or API
+34+ when the platform withholds it), matching identifier-free replies are accepted for
+compatibility. If a call times out, a delayed identifier-free reply can still match a later
+sequential call that expects the same shape and resolve it with stale data. This default may
+change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 | Param         | Type                                  |
 | ------------- | ------------------------------------- |
 | **`options`** | <code>{ profileName: string; }</code> |
@@ -399,6 +466,17 @@ getAssociatedApps(options: { profileName: string; }) => Promise<{ appList: DataW
 getConfig(options: GetConfigOptions) => Promise<ZebraProfileConfiguration>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. For example,
+`getAssociatedApps()` and `getConfig()` both send `CMD_GET_CONFIG` and expect `CONFIG_RESULTS`, so one
+pending call to each overlaps. When sender identity is unavailable (Android API 24 to 33, or API
+34+ when the platform withholds it), matching identifier-free replies are accepted for
+compatibility. If a call times out, a delayed identifier-free reply can still match a later
+sequential call that expects the same shape and resolve it with stale data. This default may
+change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 | Param         | Type                                                          |
 | ------------- | ------------------------------------------------------------- |
 | **`options`** | <code><a href="#getconfigoptions">GetConfigOptions</a></code> |
@@ -413,6 +491,15 @@ getConfig(options: GetConfigOptions) => Promise<ZebraProfileConfiguration>
 getDatawedgeStatus() => Promise<DataWedgeStatusResult>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. When sender
+identity is unavailable (Android API 24 to 33, or API 34+ when the platform withholds it),
+matching identifier-free replies are accepted for compatibility. If a call times out, a delayed
+identifier-free reply can still match a later sequential call that expects the same shape and
+resolve it with stale data. This default may change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 **Returns:** <code>Promise&lt;<a href="#datawedgestatusresult">DataWedgeStatusResult</a>&gt;</code>
 
 ---
@@ -423,6 +510,15 @@ getDatawedgeStatus() => Promise<DataWedgeStatusResult>
 getDisabledAppList() => Promise<{ appList: DataWedgeAppConfig[]; }>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. When sender
+identity is unavailable (Android API 24 to 33, or API 34+ when the platform withholds it),
+matching identifier-free replies are accepted for compatibility. If a call times out, a delayed
+identifier-free reply can still match a later sequential call that expects the same shape and
+resolve it with stale data. This default may change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 **Returns:** <code>Promise&lt;{ appList: DataWedgeAppConfig[]; }&gt;</code>
 
 ---
@@ -433,6 +529,15 @@ getDisabledAppList() => Promise<{ appList: DataWedgeAppConfig[]; }>
 getIgnoreDisabledProfiles() => Promise<IgnoreDisabledProfilesResult>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. When sender
+identity is unavailable (Android API 24 to 33, or API 34+ when the platform withholds it),
+matching identifier-free replies are accepted for compatibility. If a call times out, a delayed
+identifier-free reply can still match a later sequential call that expects the same shape and
+resolve it with stale data. This default may change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 **Returns:** <code>Promise&lt;<a href="#ignoredisabledprofilesresult">IgnoreDisabledProfilesResult</a>&gt;</code>
 
 ---
@@ -443,6 +548,15 @@ getIgnoreDisabledProfiles() => Promise<IgnoreDisabledProfilesResult>
 getProfilesList() => Promise<{ profiles: string[]; }>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. When sender
+identity is unavailable (Android API 24 to 33, or API 34+ when the platform withholds it),
+matching identifier-free replies are accepted for compatibility. If a call times out, a delayed
+identifier-free reply can still match a later sequential call that expects the same shape and
+resolve it with stale data. This default may change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 **Returns:** <code>Promise&lt;{ profiles: string[]; }&gt;</code>
 
 ---
@@ -453,6 +567,15 @@ getProfilesList() => Promise<{ profiles: string[]; }>
 getScannerStatus() => Promise<{ status: ScannerStatus | string; }>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. When sender
+identity is unavailable (Android API 24 to 33, or API 34+ when the platform withholds it),
+matching identifier-free replies are accepted for compatibility. If a call times out, a delayed
+identifier-free reply can still match a later sequential call that expects the same shape and
+resolve it with stale data. This default may change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 **Returns:** <code>Promise&lt;{ status: string; }&gt;</code>
 
 ---
@@ -463,6 +586,15 @@ getScannerStatus() => Promise<{ status: ScannerStatus | string; }>
 getVersionInfo() => Promise<ZebraDeviceVersionInfo>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. When sender
+identity is unavailable (Android API 24 to 33, or API 34+ when the platform withholds it),
+matching identifier-free replies are accepted for compatibility. If a call times out, a delayed
+identifier-free reply can still match a later sequential call that expects the same shape and
+resolve it with stale data. This default may change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 **Returns:** <code>Promise&lt;<a href="#zebradeviceversioninfo">ZebraDeviceVersionInfo</a>&gt;</code>
 
 ---
@@ -505,6 +637,15 @@ enableScannerInput() => Promise<void>
 enumerateTriggers() => Promise<{ triggers: string[]; }>
 ```
 
+Android only. DataWedge may omit `COMMAND_IDENTIFIER` on query replies. The plugin accepts
+identifier-free replies only when the payload matches exactly one pending call that expects the
+same result payload shape. Avoid overlapping pending calls that share that shape. When sender
+identity is unavailable (Android API 24 to 33, or API 34+ when the platform withholds it),
+matching identifier-free replies are accepted for compatibility. If a call times out, a delayed
+identifier-free reply can still match a later sequential call that expects the same shape and
+resolve it with stale data. This default may change in the next Capacitor major version; see
+https://github.com/Cap-go/capacitor-zebra-datawedge/issues/25/.
+
 **Returns:** <code>Promise&lt;{ triggers: string[]; }&gt;</code>
 
 ---
@@ -655,6 +796,28 @@ addListener(eventName: 'notification', listenerFunc: (event: ZebraNotificationEv
 
 ### Interfaces
 
+#### DiagnosticsOptions
+
+| Prop             | Type                 | Description                                                                                                     |
+| ---------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **`enabled`**    | <code>boolean</code> | Enable metadata tracing. Disabled by default; disabling does not erase previous entries.                        |
+| **`maxEntries`** | <code>number</code>  | Number of recent entries retained, from 1 to 1000. Initially 100; omitted values preserve the current capacity. |
+| **`reset`**      | <code>boolean</code> | Clear retained entries and reset elapsed time and dropped count. Default: false.                                |
+
+#### DataWedgeDiagnosticsSnapshot
+
+| Prop                     | Type                                                                                                                                                                               | Description                                                                              |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **`diagnosticsVersion`** | <code>number</code>                                                                                                                                                                |                                                                                          |
+| **`enabled`**            | <code>boolean</code>                                                                                                                                                               |                                                                                          |
+| **`maxEntries`**         | <code>number</code>                                                                                                                                                                |                                                                                          |
+| **`droppedEntries`**     | <code>number</code>                                                                                                                                                                |                                                                                          |
+| **`manufacturer`**       | <code>string</code>                                                                                                                                                                |                                                                                          |
+| **`model`**              | <code>string</code>                                                                                                                                                                |                                                                                          |
+| **`androidVersion`**     | <code>string</code>                                                                                                                                                                |                                                                                          |
+| **`dataWedgePackage`**   | <code>{ status: 'installed' \| 'notFound' \| 'unavailable'; version?: string; }</code>                                                                                             | notFound means Android could not find the package; it is not a service-permission check. |
+| **`commands`**           | <code>{ commandIdentifier: string; outcome: 'SENT' \| 'SUCCESS' \| 'FAILURE' \| 'TIMEOUT' \| 'TRANSPORT_ERROR' \| 'CANCELLED' \| 'INVALID_RESPONSE'; elapsedMs: number; }[]</code> |                                                                                          |
+
 #### CloneProfileOptions
 
 | Prop                    | Type                |

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,5 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <queries>
+        <package android:name="com.symbol.datawedge" />
+    </queries>
 </manifest>

package/android/src/main/java/app/capgo/zebradatawedge/DataWedgeDiagnostics.java

@@ -0,0 +1,85 @@
+package app.capgo.zebradatawedge;
+
+import android.content.Context;
+import android.content.pm.PackageInfo;
+import android.content.pm.PackageManager;
+import android.os.Build;
+import android.os.SystemClock;
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import java.util.ArrayDeque;
+
+/** Opt-in metadata only: no barcode values, intent bodies, or arbitrary exception text. */
+final class DataWedgeDiagnostics {
+
+    private final ArrayDeque<JSObject> events = new ArrayDeque<>();
+    private boolean enabled;
+    private int capacity = 100;
+    private int dropped;
+    private long startedAt;
+
+    synchronized void configure(boolean enabled, Integer capacity, boolean reset) {
+        this.enabled = enabled;
+        if (capacity != null) this.capacity = capacity;
+        if (reset) {
+            events.clear();
+            dropped = 0;
+            startedAt = SystemClock.elapsedRealtime();
+        }
+        while (events.size() > this.capacity) {
+            events.removeFirst();
+            dropped++;
+        }
+        if (enabled && startedAt == 0) startedAt = SystemClock.elapsedRealtime();
+    }
+
+    synchronized void record(String identifier, String outcome) {
+        if (!enabled) return;
+        if (events.size() == capacity) {
+            events.removeFirst();
+            dropped++;
+        }
+        JSObject event = new JSObject();
+        event.put("commandIdentifier", identifier);
+        event.put("outcome", outcome);
+        event.put("elapsedMs", SystemClock.elapsedRealtime() - startedAt);
+        events.addLast(event);
+    }
+
+    synchronized JSObject snapshot(Context context) {
+        JSArray commands = new JSArray();
+        for (JSObject event : events) {
+            // Copy every value so callers cannot mutate the ring through a previous snapshot.
+            JSObject copy = new JSObject();
+            copy.put("commandIdentifier", event.getString("commandIdentifier"));
+            copy.put("outcome", event.getString("outcome"));
+            copy.put("elapsedMs", event.optLong("elapsedMs"));
+            commands.put(copy);
+        }
+        JSObject result = new JSObject();
+        result.put("diagnosticsVersion", 1);
+        result.put("enabled", enabled);
+        result.put("maxEntries", capacity);
+        result.put("droppedEntries", dropped);
+        result.put("manufacturer", Build.MANUFACTURER);
+        result.put("model", Build.MODEL);
+        result.put("androidVersion", Build.VERSION.RELEASE);
+        result.put("dataWedgePackage", describePackage(context));
+        result.put("commands", commands);
+        return result;
+    }
+
+    private JSObject describePackage(Context context) {
+        JSObject result = new JSObject();
+        try {
+            PackageInfo info = context.getPackageManager().getPackageInfo("com.symbol.datawedge", 0);
+            result.put("status", "installed");
+            if (info.versionName != null) result.put("version", info.versionName);
+        } catch (PackageManager.NameNotFoundException exception) {
+            result.put("status", "notFound");
+        } catch (Exception exception) {
+            result.put("status", "unavailable");
+        }
+        return result;
+    }
+}

package/android/src/main/java/app/capgo/zebradatawedge/ZebraDataWedge.java

@@ -79,7 +79,7 @@ public final class ZebraDataWedge {
     public static final String RESULT_GET_DATAWEDGE_STATUS = "com.symbol.datawedge.api.RESULT_GET_DATAWEDGE_STATUS";
     public static final String RESULT_GET_DISABLED_APP_LIST = "com.symbol.datawedge.api.RESULT_GET_DISABLED_APP_LIST";
     public static final String RESULT_GET_IGNORE_DISABLED_PROFILES = "com.symbol.datawedge.api.RESULT_GET_IGNORE_DISABLED_PROFILES";
-    public static final String RESULT_GET_SCANNER_STATUS = "com.symbol.datawedge.api.RESULT_GET_SCANNER_STATUS";
+    public static final String RESULT_GET_SCANNER_STATUS = "com.symbol.datawedge.api.RESULT_SCANNER_STATUS";
     public static final String RESULT_ENUMERATE_SCANNERS = "com.symbol.datawedge.api.RESULT_ENUMERATE_SCANNERS";
     public static final String RESULT_ENUMERATED_SCANNER_LIST = "DWAPI_KEY_ENUMERATEDSCANNERLIST";
     public static final String RESULT_ENUMERATE_TRIGGERS = "com.symbol.datawedge.api.RESULT_ENUMERATE_TRIGGERS";