capacitor-rfid-plugin-ox 0.3.5 → 0.5.0

package/README.md

@@ -13,6 +13,10 @@ npx cap sync
 
 <docgen-index>
 
+* [`getCapabilities()`](#getcapabilities)
+* [`getConnectionState()`](#getconnectionstate)
+* [`listReaderPorts()`](#listreaderports)
+* [`selectReaderPort(...)`](#selectreaderport)
 * [`isConnected()`](#isconnected)
 * [`startScan()`](#startscan)
 * [`stopScan()`](#stopscan)
@@ -30,12 +34,97 @@ npx cap sync
 * [`writeEpcString(...)`](#writeepcstring)
 * [`startSearch(...)`](#startsearch)
 * [`stopSearch()`](#stopsearch)
+* [`addListener('onConnectionState', ...)`](#addlisteneronconnectionstate-)
+* [`addListener(string, ...)`](#addlistenerstring-)
+* [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
 
 </docgen-index>
 
 <docgen-api>
 <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
 
+### getCapabilities()
+
+```typescript
+getCapabilities() => Promise<ReaderCapabilities>
+```
+
+Capabilities of the connected Reader.
+
+Implementations that predate this method reject. That is a signal, not a
+failure: the caller treats a rejection as a handheld Mobile Reader.
+
+**Returns:** <code>Promise&lt;<a href="#readercapabilities">ReaderCapabilities</a>&gt;</code>
+
+--------------------
+
+
+### getConnectionState()
+
+```typescript
+getConnectionState() => Promise<ReaderConnectionState>
+```
+
+Connection state for the first render. The stream of later changes comes
+from the `onConnectionState` listener — "not responding" is only found out
+after a timeout, so it cannot be a return value.
+
+A reader is an exclusive resource, so its state is only knowable while it
+is held: an implementation that is not connected may start an attempt here
+and answer `connecting`, with the outcome arriving on the listener.
+
+Implementations that predate this method reject. The caller then hides the
+indicator instead of guessing.
+
+**Returns:** <code>Promise&lt;<a href="#readerconnectionstate">ReaderConnectionState</a>&gt;</code>
+
+--------------------
+
+
+### listReaderPorts()
+
+```typescript
+listReaderPorts() => Promise<{ ports: ReaderPort[]; }>
+```
+
+The readers plugged in right now, newest listing every call — a port that
+was there a minute ago may be gone.
+
+Only readers, not every serial port: what the caller does with this list
+is offer it as a choice, and a Bluetooth port is not a choice.
+
+Implementations that predate this method reject. The caller then keeps
+whatever the driver picks on its own.
+
+**Returns:** <code>Promise&lt;{ ports: ReaderPort[]; }&gt;</code>
+
+--------------------
+
+
+### selectReaderPort(...)
+
+```typescript
+selectReaderPort(options: { path: string; }) => Promise<void>
+```
+
+Use this reader from now on. Reconnects when another port is open.
+
+The choice itself is not stored here: the driver is restarted with the
+app, and where a choice belongs is the caller's question. The caller
+remembers the path and says it again on the next start.
+
+Rejects when the path is not in the current `listReaderPorts()` — a
+remembered reader that was unplugged has to be chosen again, not opened
+blindly.
+
+| Param         | Type                           |
+| ------------- | ------------------------------ |
+| **`options`** | <code>{ path: string; }</code> |
+
+--------------------
+
+
 ### isConnected()
 
 ```typescript
@@ -236,4 +325,121 @@ stopSearch() => Promise<void>
 
 --------------------
 
+
+### addListener('onConnectionState', ...)
+
+```typescript
+addListener(eventName: 'onConnectionState', listener: (state: ReaderConnectionState) => void) => Promise<PluginListenerHandle>
+```
+
+Every connection state change. Fires only on a change, not on a poll.
+
+| Param           | Type                                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------- |
+| **`eventName`** | <code>'onConnectionState'</code>                                                            |
+| **`listener`**  | <code>(state: <a href="#readerconnectionstate">ReaderConnectionState</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### addListener(string, ...)
+
+```typescript
+addListener(eventName: string, listenerFunc: (...args: any[]) => any) => Promise<PluginListenerHandle>
+```
+
+| Param              | Type                                    |
+| ------------------ | --------------------------------------- |
+| **`eventName`**    | <code>string</code>                     |
+| **`listenerFunc`** | <code>(...args: any[]) =&gt; any</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### Interfaces
+
+
+#### ReaderCapabilities
+
+What the connected Reader can do. Mode gating comes from here, not from the
+reader type — a desktop reader that can write must not be gated like one
+that cannot.
+
+| Prop             | Type                                                        | Description                                                           |
+| ---------------- | ----------------------------------------------------------- | --------------------------------------------------------------------- |
+| **`canWrite`**   | <code>boolean</code>                                        | Reader can write an EPC to a tag (Generate & Set mode depends on it). |
+| **`hasRssi`**    | <code>boolean</code>                                        | Reader reports RSSI (Find mode depends on it).                        |
+| **`isHandheld`** | <code>boolean</code>                                        | Reader is a handheld terminal rather than a desk device.              |
+| **`power`**      | <code>{ min: number; max: number; default: number; }</code> | Output power range in dBm. The power slider renders this range.       |
+
+
+#### ReaderConnectionState
+
+| Prop         | Type                                                                      | Description                                                                                                                                                                                         |
+| ------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`status`** | <code><a href="#readerconnectionstatus">ReaderConnectionStatus</a></code> |                                                                                                                                                                                                     |
+| **`reason`** | <code><a href="#readerconnectionreason">ReaderConnectionReason</a></code> |                                                                                                                                                                                                     |
+| **`detail`** | <code>string</code>                                                       | Driver text: the port list, the command code, the OS error. This is the one field allowed to talk about the wiring, because nothing branches on it — it is shown as-is for support, not translated. |
+
+
+#### ReaderPort
+
+One reader the driver could talk to.
+
+`path` is the identity — `COM3` on Windows, `/dev/cu.usbserial-110`
+elsewhere. Two identical CH340 adapters carry no serial number of their own,
+so the path is all that separates them.
+
+The caller treats it as **opaque**: it compares, stores and hands it back,
+and never reads meaning out of it. A driver for a device that is not a
+serial port puts its own identity here.
+
+| Prop            | Type                | Description                                                              |
+| --------------- | ------------------- | ------------------------------------------------------------------------ |
+| **`path`**      | <code>string</code> |                                                                          |
+| **`label`**     | <code>string</code> | What the OS calls the device. For the operator to read, not to match on. |
+| **`vendorId`**  | <code>string</code> |                                                                          |
+| **`productId`** | <code>string</code> |                                                                          |
+
+
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+### Type Aliases
+
+
+#### ReaderConnectionStatus
+
+The four states an operator can act on.
+
+`isConnected()` is too coarse for this: a reader that is plugged in but
+silent answers `false` the same way a missing one does, and the operator
+needs a different move in each case. `isConnected()` stays as it is.
+
+<code>'connecting' | 'connected' | 'not-found' | 'not-responding'</code>
+
+
+#### ReaderConnectionReason
+
+Why the reader is unusable. The status alone does not say what to do next:
+a busy reader needs another program closed, a missing one needs the
+connection checked. The UI picks its message from the reason when there is
+one.
+
+These name what happened to the *reader*, never how it is wired. A driver
+for a device with no serial port has to be able to answer in this
+vocabulary too, and the operator has to be told the truth either way —
+so nothing here says "COM port" or "USB". The device-specific sentence
+belongs in `detail`.
+
+<code>'busy' | 'not-detected' | 'disconnected' | 'no-answer' | 'not-chosen'</code>
+
 </docgen-api>

package/dist/docs.json

@@ -5,6 +5,58 @@
     "docs": "",
     "tags": [],
     "methods": [
+      {
+        "name": "getCapabilities",
+        "signature": "() => Promise<ReaderCapabilities>",
+        "parameters": [],
+        "returns": "Promise<ReaderCapabilities>",
+        "tags": [],
+        "docs": "Capabilities of the connected Reader.\n\nImplementations that predate this method reject. That is a signal, not a\nfailure: the caller treats a rejection as a handheld Mobile Reader.",
+        "complexTypes": [
+          "ReaderCapabilities"
+        ],
+        "slug": "getcapabilities"
+      },
+      {
+        "name": "getConnectionState",
+        "signature": "() => Promise<ReaderConnectionState>",
+        "parameters": [],
+        "returns": "Promise<ReaderConnectionState>",
+        "tags": [],
+        "docs": "Connection state for the first render. The stream of later changes comes\nfrom the `onConnectionState` listener — \"not responding\" is only found out\nafter a timeout, so it cannot be a return value.\n\nA reader is an exclusive resource, so its state is only knowable while it\nis held: an implementation that is not connected may start an attempt here\nand answer `connecting`, with the outcome arriving on the listener.\n\nImplementations that predate this method reject. The caller then hides the\nindicator instead of guessing.",
+        "complexTypes": [
+          "ReaderConnectionState"
+        ],
+        "slug": "getconnectionstate"
+      },
+      {
+        "name": "listReaderPorts",
+        "signature": "() => Promise<{ ports: ReaderPort[]; }>",
+        "parameters": [],
+        "returns": "Promise<{ ports: ReaderPort[]; }>",
+        "tags": [],
+        "docs": "The readers plugged in right now, newest listing every call — a port that\nwas there a minute ago may be gone.\n\nOnly readers, not every serial port: what the caller does with this list\nis offer it as a choice, and a Bluetooth port is not a choice.\n\nImplementations that predate this method reject. The caller then keeps\nwhatever the driver picks on its own.",
+        "complexTypes": [
+          "ReaderPort"
+        ],
+        "slug": "listreaderports"
+      },
+      {
+        "name": "selectReaderPort",
+        "signature": "(options: { path: string; }) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "{ path: string; }"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [],
+        "docs": "Use this reader from now on. Reconnects when another port is open.\n\nThe choice itself is not stored here: the driver is restarted with the\napp, and where a choice belongs is the caller's question. The caller\nremembers the path and says it again on the next start.\n\nRejects when the path is not in the current `listReaderPorts()` — a\nremembered reader that was unplugged has to be chosen again, not opened\nblindly.",
+        "complexTypes": [],
+        "slug": "selectreaderport"
+      },
       {
         "name": "isConnected",
         "signature": "() => Promise<{ connected: boolean; }>",
@@ -210,12 +262,235 @@
         "docs": "",
         "complexTypes": [],
         "slug": "stopsearch"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'onConnectionState', listener: (state: ReaderConnectionState) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'onConnectionState'"
+          },
+          {
+            "name": "listener",
+            "docs": "",
+            "type": "(state: ReaderConnectionState) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "Every connection state change. Fires only on a change, not on a poll.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "ReaderConnectionState"
+        ],
+        "slug": "addlisteneronconnectionstate-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: string, listenerFunc: (...args: any[]) => any) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "string"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(...args: any[]) => any"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "",
+        "complexTypes": [
+          "PluginListenerHandle"
+        ],
+        "slug": "addlistenerstring-"
       }
     ],
     "properties": []
   },
-  "interfaces": [],
+  "interfaces": [
+    {
+      "name": "ReaderCapabilities",
+      "slug": "readercapabilities",
+      "docs": "What the connected Reader can do. Mode gating comes from here, not from the\nreader type — a desktop reader that can write must not be gated like one\nthat cannot.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "canWrite",
+          "tags": [],
+          "docs": "Reader can write an EPC to a tag (Generate & Set mode depends on it).",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "hasRssi",
+          "tags": [],
+          "docs": "Reader reports RSSI (Find mode depends on it).",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "isHandheld",
+          "tags": [],
+          "docs": "Reader is a handheld terminal rather than a desk device.",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "power",
+          "tags": [],
+          "docs": "Output power range in dBm. The power slider renders this range.",
+          "complexTypes": [],
+          "type": "{ min: number; max: number; default: number; }"
+        }
+      ]
+    },
+    {
+      "name": "ReaderConnectionState",
+      "slug": "readerconnectionstate",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "status",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [
+            "ReaderConnectionStatus"
+          ],
+          "type": "ReaderConnectionStatus"
+        },
+        {
+          "name": "reason",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [
+            "ReaderConnectionReason"
+          ],
+          "type": "ReaderConnectionReason"
+        },
+        {
+          "name": "detail",
+          "tags": [],
+          "docs": "Driver text: the port list, the command code, the OS error. This is the\none field allowed to talk about the wiring, because nothing branches on\nit — it is shown as-is for support, not translated.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
+    {
+      "name": "ReaderPort",
+      "slug": "readerport",
+      "docs": "One reader the driver could talk to.\n\n`path` is the identity — `COM3` on Windows, `/dev/cu.usbserial-110`\nelsewhere. Two identical CH340 adapters carry no serial number of their own,\nso the path is all that separates them.\n\nThe caller treats it as **opaque**: it compares, stores and hands it back,\nand never reads meaning out of it. A driver for a device that is not a\nserial port puts its own identity here.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "path",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "label",
+          "tags": [],
+          "docs": "What the OS calls the device. For the operator to read, not to match on.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "vendorId",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "productId",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
+    {
+      "name": "PluginListenerHandle",
+      "slug": "pluginlistenerhandle",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "remove",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "() => Promise<void>"
+        }
+      ]
+    }
+  ],
   "enums": [],
-  "typeAliases": [],
+  "typeAliases": [
+    {
+      "name": "ReaderConnectionStatus",
+      "slug": "readerconnectionstatus",
+      "docs": "The four states an operator can act on.\n\n`isConnected()` is too coarse for this: a reader that is plugged in but\nsilent answers `false` the same way a missing one does, and the operator\nneeds a different move in each case. `isConnected()` stays as it is.",
+      "types": [
+        {
+          "text": "'connecting'",
+          "complexTypes": []
+        },
+        {
+          "text": "'connected'",
+          "complexTypes": []
+        },
+        {
+          "text": "'not-found'",
+          "complexTypes": []
+        },
+        {
+          "text": "'not-responding'",
+          "complexTypes": []
+        }
+      ]
+    },
+    {
+      "name": "ReaderConnectionReason",
+      "slug": "readerconnectionreason",
+      "docs": "Why the reader is unusable. The status alone does not say what to do next:\na busy reader needs another program closed, a missing one needs the\nconnection checked. The UI picks its message from the reason when there is\none.\n\nThese name what happened to the *reader*, never how it is wired. A driver\nfor a device with no serial port has to be able to answer in this\nvocabulary too, and the operator has to be told the truth either way —\nso nothing here says \"COM port\" or \"USB\". The device-specific sentence\nbelongs in `detail`.",
+      "types": [
+        {
+          "text": "'busy'",
+          "complexTypes": []
+        },
+        {
+          "text": "'not-detected'",
+          "complexTypes": []
+        },
+        {
+          "text": "'disconnected'",
+          "complexTypes": []
+        },
+        {
+          "text": "'no-answer'",
+          "complexTypes": []
+        },
+        {
+          "text": "'not-chosen'",
+          "complexTypes": []
+        }
+      ]
+    }
+  ],
   "pluginConfigs": []
 }

package/dist/esm/definitions.d.ts

@@ -1,5 +1,142 @@
-import type { Plugin } from '@capacitor/core';
+import type { Plugin, PluginListenerHandle } from '@capacitor/core';
+/**
+ * What the connected Reader can do. Mode gating comes from here, not from the
+ * reader type — a desktop reader that can write must not be gated like one
+ * that cannot.
+ */
+export interface ReaderCapabilities {
+    /** Reader can write an EPC to a tag (Generate & Set mode depends on it). */
+    canWrite: boolean;
+    /** Reader reports RSSI (Find mode depends on it). */
+    hasRssi: boolean;
+    /** Reader is a handheld terminal rather than a desk device. */
+    isHandheld: boolean;
+    /** Output power range in dBm. The power slider renders this range. */
+    power: {
+        min: number;
+        max: number;
+        default: number;
+    };
+}
+/**
+ * The four states an operator can act on.
+ *
+ * `isConnected()` is too coarse for this: a reader that is plugged in but
+ * silent answers `false` the same way a missing one does, and the operator
+ * needs a different move in each case. `isConnected()` stays as it is.
+ */
+export declare type ReaderConnectionStatus = 
+/** An attempt is running. */
+'connecting'
+/** The reader is open and answering. */
+ | 'connected'
+/** No reader to talk to — nothing found, or found but not openable. */
+ | 'not-found'
+/** The port opened but the reader did not answer a command. */
+ | 'not-responding';
+/**
+ * Why the reader is unusable. The status alone does not say what to do next:
+ * a busy reader needs another program closed, a missing one needs the
+ * connection checked. The UI picks its message from the reason when there is
+ * one.
+ *
+ * These name what happened to the *reader*, never how it is wired. A driver
+ * for a device with no serial port has to be able to answer in this
+ * vocabulary too, and the operator has to be told the truth either way —
+ * so nothing here says "COM port" or "USB". The device-specific sentence
+ * belongs in `detail`.
+ */
+export declare type ReaderConnectionReason = 
+/** Another program holds the reader. Only one may have it at a time. */
+'busy'
+/** No reader in sight — nothing connected, or nothing that is a reader. */
+ | 'not-detected'
+/** The reader was there and then went away. */
+ | 'disconnected'
+/** The reader is reachable but did not answer. */
+ | 'no-answer'
+/**
+ * Several readers are connected and none was picked. Guessing here would
+ * attach tags read by the wrong device, so nothing is opened until
+ * `selectReaderPort` says which one.
+ */
+ | 'not-chosen';
+export interface ReaderConnectionState {
+    status: ReaderConnectionStatus;
+    reason?: ReaderConnectionReason;
+    /**
+     * Driver text: the port list, the command code, the OS error. This is the
+     * one field allowed to talk about the wiring, because nothing branches on
+     * it — it is shown as-is for support, not translated.
+     */
+    detail?: string;
+}
+/**
+ * One reader the driver could talk to.
+ *
+ * `path` is the identity — `COM3` on Windows, `/dev/cu.usbserial-110`
+ * elsewhere. Two identical CH340 adapters carry no serial number of their own,
+ * so the path is all that separates them.
+ *
+ * The caller treats it as **opaque**: it compares, stores and hands it back,
+ * and never reads meaning out of it. A driver for a device that is not a
+ * serial port puts its own identity here.
+ */
+export interface ReaderPort {
+    path: string;
+    /** What the OS calls the device. For the operator to read, not to match on. */
+    label?: string;
+    vendorId?: string;
+    productId?: string;
+}
 export interface RFIDPlugin extends Plugin {
+    /**
+     * Capabilities of the connected Reader.
+     *
+     * Implementations that predate this method reject. That is a signal, not a
+     * failure: the caller treats a rejection as a handheld Mobile Reader.
+     */
+    getCapabilities(): Promise<ReaderCapabilities>;
+    /**
+     * Connection state for the first render. The stream of later changes comes
+     * from the `onConnectionState` listener — "not responding" is only found out
+     * after a timeout, so it cannot be a return value.
+     *
+     * A reader is an exclusive resource, so its state is only knowable while it
+     * is held: an implementation that is not connected may start an attempt here
+     * and answer `connecting`, with the outcome arriving on the listener.
+     *
+     * Implementations that predate this method reject. The caller then hides the
+     * indicator instead of guessing.
+     */
+    getConnectionState(): Promise<ReaderConnectionState>;
+    /**
+     * The readers plugged in right now, newest listing every call — a port that
+     * was there a minute ago may be gone.
+     *
+     * Only readers, not every serial port: what the caller does with this list
+     * is offer it as a choice, and a Bluetooth port is not a choice.
+     *
+     * Implementations that predate this method reject. The caller then keeps
+     * whatever the driver picks on its own.
+     */
+    listReaderPorts(): Promise<{
+        ports: ReaderPort[];
+    }>;
+    /**
+     * Use this reader from now on. Reconnects when another port is open.
+     *
+     * The choice itself is not stored here: the driver is restarted with the
+     * app, and where a choice belongs is the caller's question. The caller
+     * remembers the path and says it again on the next start.
+     *
+     * Rejects when the path is not in the current `listReaderPorts()` — a
+     * remembered reader that was unplugged has to be chosen again, not opened
+     * blindly.
+     */
+    selectReaderPort(options: {
+        path: string;
+    }): Promise<void>;
     isConnected(): Promise<{
         connected: boolean;
     }>;
@@ -54,4 +191,7 @@ export interface RFIDPlugin extends Plugin {
         playSound: boolean;
     }): Promise<void>;
     stopSearch(): Promise<void>;
+    /** Every connection state change. Fires only on a change, not on a poll. */
+    addListener(eventName: 'onConnectionState', listener: (state: ReaderConnectionState) => void): Promise<PluginListenerHandle>;
+    addListener(eventName: string, listenerFunc: (...args: any[]) => any): Promise<PluginListenerHandle>;
 }