@rejaul/react-native-printer-kit 0.3.4 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # react-native-printer-kit
 
-A professional-grade React Native module for printing directly to Bluetooth POS/thermal (ESC/POS) printers on **Android devices only** — no third-party printer app, no OS print dialog. Print raw text, images, PDFs, and full HTML/CSS content, including **Bangla and other non-Latin scripts** that ESC/POS printer fonts don't support natively.
+A professional-grade React Native module for printing directly to Bluetooth, Wi-Fi/LAN and USB POS/thermal (ESC/POS) printers on **Android devices only** — no third-party printer app, no OS print dialog. Print raw text, images, PDFs, and full HTML/CSS content, including **Bangla and other non-Latin scripts** that ESC/POS printer fonts don't support natively.
 
-> **Important:** This library is **exclusively for Android**. Bluetooth Classic SPP + ESC/POS is an Android-specific integration; iOS does not expose the APIs this relies on.
+> **Important:** This library is **exclusively for Android**. Bluetooth Classic SPP, USB host and ESC/POS are Android-specific integrations; iOS does not expose the APIs this relies on.
 
 [![npm version](https://img.shields.io/npm/v/@rejaul/react-native-printer-kit.svg)](https://www.npmjs.com/package/@rejaul/react-native-printer-kit)
 [![license](https://img.shields.io/npm/l/@rejaul/react-native-printer-kit.svg)](LICENSE)
@@ -18,7 +18,11 @@ It's a thin React Native bridge over [`android-printer-kit`](https://github.com/
 
 ## Features
 
-- **Direct Bluetooth Classic (SPP) connection** to any paired ESC/POS printer.
+- **Three connection types** behind one API: Bluetooth Classic (SPP), Wi-Fi/LAN (raw TCP) and USB (OTG). Every print function is the same for all three.
+- **Printer-only device list**: `getBondedBluetoothPrinters({ filter: 'LIKELY_PRINTERS' })` hides headphones, watches and other non-printers.
+- **Printer checks**: `isPrinterReady()`, `getPrinterStatus()` (online / paper out / cover / error) and `printTestPage()`.
+- **Save files** (e.g. the PDF from `htmlToPdf`) to Downloads, Documents, app storage or a chosen folder with `saveFile()`.
+- **Honest connection notification**: if the printer drops (switched off, out of range, Bluetooth off, USB unplugged) the ongoing "connected" notification is replaced by a dismissible "disconnected" one.
 - **HTML → PDF → print** pipeline, so you can print an actual styled receipt/report.
 - **PDF → image → print** pipeline via Android's built-in `PdfRenderer`.
 - **Non-Latin text support** (Bangla and others) via image-based rendering.
@@ -36,7 +40,15 @@ It's a thin React Native bridge over [`android-printer-kit`](https://github.com/
 
 ## Scope
 
-This library speaks **Bluetooth Classic SPP + ESC/POS** — the standard used by virtually all budget Bluetooth receipt/thermal printers. It does not support Bluetooth LE printers, WiFi/network printers, USB-connected printers, or non-ESC/POS protocols (PCL/PostScript inkjet & laser printers).
+This library speaks **ESC/POS** — the standard used by virtually all receipt/thermal POS printers — over:
+
+| Connection | Notes |
+|---|---|
+| Bluetooth Classic (SPP) | The printer must be paired in Android's Bluetooth settings first. |
+| Wi-Fi / LAN | Raw TCP, usually port 9100. Phone and printer must be on the same network; there is no discovery, so you supply the IP. |
+| USB | Needs a phone with USB host (OTG) and the user's per-device permission (`requestUsbPermission`). |
+
+Not supported: Bluetooth LE-only printers, label printers that use TSPL/ZPL/CPCL (Zebra, TSC, ...), and non-ESC/POS protocols (PCL/PostScript inkjet & laser printers).
 
 ## Minimum Requirements
 
@@ -52,7 +64,7 @@ npm install @rejaul/react-native-printer-kit
 yarn add @rejaul/react-native-printer-kit
 ```
 
-Nothing to configure manually — all required Bluetooth and foreground-service permissions are declared by the underlying native library's manifest and merge in automatically. You still need to request the runtime `BLUETOOTH_CONNECT` (Android 12+) and `POST_NOTIFICATIONS` (Android 13+) permissions at runtime — `requestBluetoothPermission()` handles both in one call; see [Permissions](#permissions) below.
+Nothing to configure manually — all required Bluetooth, internet, USB-host and foreground-service permissions are declared by the underlying native library's manifest and merge in automatically. You still need to request the runtime `BLUETOOTH_CONNECT` (Android 12+) and `POST_NOTIFICATIONS` (Android 13+) permissions at runtime — `requestBluetoothPermission()` handles both in one call; see [Permissions](#permissions) below.
 
 ## Quick Start
 
@@ -117,11 +129,39 @@ Every function that takes data (anything beyond a bare callback) takes a single
 
 ### Connection
 
-#### `getBondedBluetoothPrinters(): BluetoothPrinterDevice[]`
-Lists Bluetooth devices already paired with the phone via Android's own Bluetooth settings.
+#### `getBondedBluetoothPrinters(params?: GetBondedPrintersParams): BluetoothPrinterDevice[]`
+Lists Bluetooth devices already paired with the phone via Android's own Bluetooth settings, best printer matches first. Each device has a `confidence` (`CONFIDENT` / `LIKELY` / `UNKNOWN`). Pass `{ filter: 'LIKELY_PRINTERS' }` to hide devices that do not look like printers (`'STRICT'` keeps only certain ones), or `extraNameKeywords: ['part-of-its-name']` if a real printer has an unusual name and gets hidden. With no argument every paired device is returned, as before.
+
+#### `getUsbPrinters(): UsbPrinterDevice[]`
+USB printers currently plugged in (devices exposing the USB *printer* class). Needs a phone with USB host (OTG).
+
+#### `hasUsbPermission(params: UsbDeviceParams): boolean`
+Whether the user already granted this app access to that USB printer.
+
+#### `requestUsbPermission(params: UsbDeviceParams): Promise<boolean>`
+Shows the system USB permission dialog and resolves with the user's answer. Call it before connecting. The grant is lost when the app is reinstalled.
 
 #### `connectPrinter(params: ConnectPrinterParams): Promise<boolean>`
-Opens an RFCOMM/SPP connection to the paired printer. Closes any existing connection first, and remembers the address for auto-reconnect on the next app launch.
+Connects over Bluetooth (default), Wi-Fi/LAN or USB depending on `params.type`. Closes any existing connection first, and remembers the printer for auto-reconnect on the next app launch. Resolves `false` (does not reject) if it could not connect; for USB that includes a missing permission.
+
+```typescript
+// Bluetooth (default) - the printer must be paired first
+await connectPrinter({ address: 'AA:BB:CC:DD:EE:FF' });
+
+// Wi-Fi / LAN
+await connectPrinter({ address: '192.168.1.50', type: 'NETWORK', port: 9100 });
+
+// USB - ask for permission first (system dialog), then connect
+const usb = getUsbPrinters()[0];
+if (usb && (await requestUsbPermission(usb))) {
+  await connectPrinter({
+    address: '',
+    type: 'USB',
+    vendorId: usb.vendorId,
+    productId: usb.productId,
+  });
+}
+```
 
 #### `disconnectPrinter(): Promise<void>`
 Closes the current connection and forgets it for auto-reconnect.
@@ -132,6 +172,35 @@ Whether a printer connection is currently open.
 #### `getConnectedPrinter(): Promise<BluetoothPrinterDevice | null>`
 The currently connected printer, if any.
 
+### Printer checks
+
+#### `isPrinterReady(): Promise<boolean>`
+Connected **and** the printer accepts data right now (it may be switched off or out of range). It does not check paper or the cover.
+
+#### `getPrinterStatus(params?: PrinterStatusParams): Promise<PrinterStatus>`
+Asks the printer for its state. Many printers ignore the request: then `responded` is `false` and every other field is `null` (unknown, **not** "ok"). Things to know:
+
+- Right after connecting, the first request can time out (`responded: false`); asking again a moment later works.
+- What a printer reports depends on its firmware. On the USB receipt printer used for testing, an open cover was reported as `online: false, paperOut: true` and never as `coverOpen: true`. So read `paperOut: true` as "no paper *or* cover open", and do not rely on `coverOpen` unless you verified it on your printer model.
+- `online: false` is the most reliable "do not print now" signal.
+- A print call that resolves only means the bytes were sent. An offline or out-of-paper printer may still accept them, so check the status first when it matters.
+
+#### `printTestPage(): Promise<void>`
+Prints a short ASCII test page (connection type, printer, address, time).
+
+### Saving and opening files
+
+#### `saveFile(params: SaveFileParams): Promise<SaveFileResult>`
+Copies a finished file (for example the PDF from `htmlToPdf`) to `CACHE`, `APP_FILES`, public `DOWNLOADS` / `DOCUMENTS` or a `CUSTOM_FOLDER`. Never rejects: check `result.success` and `result.error`. On Android 10+ Downloads/Documents use MediaStore (no permission needed); on Android 9 and below you need `WRITE_EXTERNAL_STORAGE`. `overwrite: true` can only replace files this app created.
+
+#### `openFile(params: OpenFileParams): boolean`
+Opens a file with whatever installed app can handle its type (shows the "Open with" chooser if several match). Returns `false` if the file does not exist or no app can open it.
+
+### Bluetooth state
+
+#### `isBluetoothEnabled(): boolean`
+Whether the Bluetooth adapter itself is on. Needs no runtime permission, so check it before asking for the permission.
+
 ### Printing
 
 #### `printText(params: PrintTextParams): Promise<void>`
@@ -155,17 +224,105 @@ Renders HTML to a PDF file using an off-screen `WebView` and returns its path, o
 #### `printHtml(params: PrintHtmlParams): Promise<boolean>`
 Full pipeline: `htmlToPdf` → `printPdf`. This is how you print Bangla (or other non-Latin) text or any real HTML/CSS layout. Retries once (reconnect + resend) if the underlying write fails, e.g. from a "Broken pipe" when a cheap board drops the link mid-print.
 
+## Enums
+
+The string options are also exported as constants, so you can write `PrinterFilter.LIKELY_PRINTERS` instead of a bare string (plain strings keep working too). Each name is both a runtime value and a type:
+
+```typescript
+import {
+  PrinterFilter, // ALL | LIKELY_PRINTERS | STRICT
+  PrinterConfidence, // CONFIDENT | LIKELY | UNKNOWN
+  PrinterConnectionType, // BLUETOOTH | NETWORK | USB
+  PrinterImageType, // PNG | JPEG
+  FileLocation, // CACHE | APP_FILES | DOWNLOADS | DOCUMENTS | CUSTOM_FOLDER
+} from '@rejaul/react-native-printer-kit';
+
+getBondedBluetoothPrinters({ filter: PrinterFilter.LIKELY_PRINTERS });
+connectPrinter({ address: '192.168.1.50', type: PrinterConnectionType.NETWORK });
+saveFile({ sourcePath, location: FileLocation.DOWNLOADS });
+```
+
 ## Type Definitions
 
 ```typescript
+type PrinterConfidence = 'CONFIDENT' | 'LIKELY' | 'UNKNOWN';
+type PrinterFilter = 'ALL' | 'LIKELY_PRINTERS' | 'STRICT';
+type PrinterConnectionType = 'BLUETOOTH' | 'NETWORK' | 'USB';
+
 type BluetoothPrinterDevice = {
+  name: string | null; // null for a Wi-Fi/LAN printer
+  address: string; // MAC, host, or "vendorId:productId" for USB
+  confidence: PrinterConfidence;
+  reason: string | null;
+};
+
+type GetBondedPrintersParams = {
+  filter?: PrinterFilter; // default 'ALL'
+  extraNameKeywords?: string[];
+};
+
+type UsbPrinterDevice = {
   name: string | null;
-  address: string;
+  vendorId: number;
+  productId: number;
+  deviceName: string;
 };
 
+type UsbDeviceParams = { vendorId: number; productId: number };
+
 type PrinterImageType = 'PNG' | 'JPEG';
 
-type ConnectPrinterParams = { address: string };
+type ConnectPrinterParams = {
+  address: string; // Bluetooth MAC, or IP/host for NETWORK; '' for USB
+  type?: PrinterConnectionType; // default 'BLUETOOTH'
+  port?: number; // NETWORK only, default 9100
+  timeoutMs?: number; // NETWORK connect timeout, default 5000
+  vendorId?: number; // USB only
+  productId?: number; // USB only
+  notificationTitle?: string; // default 'Printer connected'
+  disconnectedNotificationTitle?: string; // default 'Printer disconnected'
+};
+
+type PrinterStatusParams = { timeoutMs?: number }; // default 800
+
+// null = unknown (the printer did not report it), NOT "ok"
+type PrinterStatus = {
+  connected: boolean;
+  responded: boolean;
+  online: boolean | null;
+  paperOut: boolean | null;
+  paperNearEnd: boolean | null;
+  coverOpen: boolean | null;
+  hasError: boolean | null;
+};
+
+type FileLocation =
+  | 'CACHE'
+  | 'APP_FILES'
+  | 'DOWNLOADS'
+  | 'DOCUMENTS'
+  | 'CUSTOM_FOLDER';
+
+type SaveFileParams = {
+  sourcePath: string;
+  fileName?: string; // defaults to the source file's name
+  location?: FileLocation; // default 'DOWNLOADS'
+  customFolder?: string; // required for CUSTOM_FOLDER
+  subFolder?: string;
+  mimeType?: string; // guessed from the extension
+  overwrite?: boolean;
+  deleteSource?: boolean;
+};
+
+type SaveFileResult = {
+  success: boolean;
+  path: string | null;
+  uri: string | null;
+  fileName: string | null;
+  error: string | null;
+};
+
+type OpenFileParams = { path: string; mimeType?: string };
 
 type PrintTextParams = { text: string; feedLines?: number };
 
@@ -221,9 +378,13 @@ type PrintHtmlParams = {
 
 ## Persistent connection & auto-reconnect
 
-Connecting through this library keeps the printer connected even if the app is swiped away from Recents — the native side runs a foreground service that outlives the Activity/JS runtime. Every successful `connectPrinter()` call also remembers the device, so the next time the app is opened (even after being fully killed) it reconnects automatically without the user having to pick the printer again.
+Connecting through this library keeps the printer connected even if the app is swiped away from Recents — the native side runs a foreground service that outlives the Activity/JS runtime. Every successful `connectPrinter()` call also remembers the printer (connection type, address/IP, port and USB ids), so the next time the app is opened (even after being fully killed) it reconnects automatically without the user having to pick the printer again.
+
+`connectPrinter()` falls back to a direct RFCOMM channel if the standard SDP-based socket fails (common on printers with a broken SDP record). `isConnectedPrinter()` reflects a real disconnect for Bluetooth (Android's ACL-disconnect and Bluetooth-off events) and USB (unplugging) instead of a stale flag; a dropped Wi-Fi/LAN link is only noticed on the next write, which reconnects once automatically.
+
+## Connection lost notification
 
-`connectPrinter()` falls back to a direct RFCOMM channel if the standard SDP-based socket fails (common on printers with a broken SDP record), and `isConnectedPrinter()` reflects a real physical disconnect immediately (via Android's ACL-disconnect broadcast) instead of a stale flag that stays `true` after the printer silently drops the link.
+When a connected printer drops on its own, the ongoing **"Printer connected"** notification is removed and a normal, dismissible **"Printer disconnected — \<printer name\>"** notification is posted. Reconnecting removes it again. Calling `disconnectPrinter()` yourself shows no notification. Change the wording with `notificationTitle` / `disconnectedNotificationTitle` in `connectPrinter()`.
 
 ## Printing Bangla / other non-Latin text
 
@@ -231,7 +392,7 @@ ESC/POS printer firmware fonts only cover ASCII, so `printText()` can't render B
 
 ## Example Application
 
-See the [`example`](./example) directory for a complete React Native application demonstrating permission handling, printer pairing/connection, and every print function above.
+See the [`example`](./example) directory for a complete React Native application demonstrating permission handling, Bluetooth and USB connection, printer status, the test page, and the print functions above.
 
 ```bash
 cd example

package/android/build.gradle

@@ -61,5 +61,5 @@ repositories {
 
 dependencies {
   implementation "com.facebook.react:react-android"
-  implementation("com.github.DeveloperRejaul:android-printer-kit:v0.0.14")
+  implementation("com.github.DeveloperRejaul:android-printer-kit:v0.1.0")
 }

package/android/src/main/java/com/rejaul/reactnativeprinterkit/ReactNativePrinterKitModule.kt

@@ -15,18 +15,23 @@ import com.facebook.react.bridge.WritableArray
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.modules.core.PermissionAwareActivity
 import com.rezaul.printerkit.BluetoothPermissions
-import com.rezaul.printerkit.BluetoothPrinter
-import com.rezaul.printerkit.BluetoothPrinterDevice
-import com.rezaul.printerkit.BluetoothPrinterService
-import com.rezaul.printerkit.ConnectPrinterParams
-import com.rezaul.printerkit.HtmlToPdfParams
-import com.rezaul.printerkit.PdfToImageParams
-import com.rezaul.printerkit.PrintHtmlParams
-import com.rezaul.printerkit.PrintImageBase64Params
-import com.rezaul.printerkit.PrintImageFileParams
-import com.rezaul.printerkit.PrintPdfParams
-import com.rezaul.printerkit.PrinterImageType
-import com.rezaul.printerkit.PrintTextParams
+import com.rezaul.printerkit.PosPrinter
+import com.rezaul.printerkit.PrinterService
+import com.rezaul.printerkit.model.BluetoothPrinterDevice
+import com.rezaul.printerkit.model.ConnectPrinterParams
+import com.rezaul.printerkit.model.FileLocation
+import com.rezaul.printerkit.model.HtmlToPdfParams
+import com.rezaul.printerkit.model.PdfToImageParams
+import com.rezaul.printerkit.model.PrintHtmlParams
+import com.rezaul.printerkit.model.PrintImageBase64Params
+import com.rezaul.printerkit.model.PrintImageFileParams
+import com.rezaul.printerkit.model.PrintPdfParams
+import com.rezaul.printerkit.model.PrintTextParams
+import com.rezaul.printerkit.model.PrinterConnectionType
+import com.rezaul.printerkit.model.PrinterFilter
+import com.rezaul.printerkit.model.PrinterImageType
+import com.rezaul.printerkit.model.SaveFileParams
+import com.rezaul.printerkit.model.UsbPrinterDevice
 import java.util.concurrent.Executors
 
 /** Reads an optional numeric field, falling back to [default] if absent/null. */
@@ -41,21 +46,33 @@ private fun ReadableMap.optIntOrNull(key: String): Int? =
 private fun ReadableMap.optLong(key: String, default: Long): Long =
   if (hasKey(key) && !isNull(key)) getDouble(key).toLong() else default
 
+/** Reads an optional string field, or null if absent/null. */
+private fun ReadableMap.optString(key: String): String? =
+  if (hasKey(key) && !isNull(key)) getString(key) else null
+
+/** Reads an optional boolean field, falling back to [default] if absent/null. */
+private fun ReadableMap.optBoolean(key: String, default: Boolean): Boolean =
+  if (hasKey(key) && !isNull(key)) getBoolean(key) else default
+
+/** Parses an enum by name, falling back to [default] for a missing or unknown value. */
+private inline fun <reified T : Enum<T>> enumOrDefault(name: String?, default: T): T =
+  name?.let { runCatching { enumValueOf<T>(it) }.getOrNull() } ?: default
+
 /**
- * Bridges [com.rezaul.printerkit.BluetoothPrinter] to React Native.
+ * Bridges [com.rezaul.printerkit.PosPrinter] to React Native.
  *
- * Connect/print calls run through a bound [BluetoothPrinterService] (started once,
- * on module init) instead of a bare [BluetoothPrinter], so the connection survives
- * the app being swiped away from Recents - see [BluetoothPrinterService]. Calls made
+ * Connect/print calls run through a bound [PrinterService] (started once,
+ * on module init) instead of a bare [PosPrinter], so the connection survives
+ * the app being swiped away from Recents - see [PrinterService]. Calls made
  * before the service finishes binding (essentially instant, but not synchronous) are
  * queued and run once it connects.
  *
- * All blocking Bluetooth/PDF/image I/O runs on a single background executor, off the
+ * All blocking Bluetooth/USB/network/PDF/image I/O runs on a single background executor, off the
  * calling (JS) thread - also serializing printer writes, since concurrent writes to
  * the same socket from two overlapping calls would corrupt the output.
  *
  * Every JS-facing method that takes data receives a single [ReadableMap] (the object
- * param the TS Spec declares), matching [com.rezaul.printerkit.BluetoothPrinter]'s own
+ * param the TS Spec declares), matching [com.rezaul.printerkit.PosPrinter]'s own
  * single-params-object functions on the native side.
  */
 class ReactNativePrinterKitModule(reactContext: ReactApplicationContext) :
@@ -63,17 +80,17 @@ class ReactNativePrinterKitModule(reactContext: ReactApplicationContext) :
 
   private val executor = Executors.newSingleThreadExecutor()
 
-  // getBondedBluetoothPrinters() is synchronous (no connection involved) and must
-  // answer immediately, so it uses its own plain BluetoothPrinter rather than
-  // waiting on the service to bind.
-  private val standalonePrinter by lazy { BluetoothPrinter(reactApplicationContext) }
+  // getBondedBluetoothPrinters(), getUsbPrinters() and the USB permission calls need no
+  // connection and must answer immediately, so they use their own plain PosPrinter
+  // rather than waiting on the service to bind.
+  private val standalonePrinter by lazy { PosPrinter(reactApplicationContext) }
 
-  private var printerService: BluetoothPrinterService? = null
-  private val pendingActions = mutableListOf<(BluetoothPrinterService) -> Unit>()
+  private var printerService: PrinterService? = null
+  private val pendingActions = mutableListOf<(PrinterService) -> Unit>()
 
   private val serviceConnection = object : ServiceConnection {
     override fun onServiceConnected(name: ComponentName?, binder: IBinder?) {
-      val service = (binder as BluetoothPrinterService.LocalBinder).getService()
+      val service = (binder as PrinterService.LocalBinder).getService()
       printerService = service
       val queued = synchronized(pendingActions) {
         val copy = pendingActions.toList()
@@ -89,13 +106,13 @@ class ReactNativePrinterKitModule(reactContext: ReactApplicationContext) :
   }
 
   init {
-    val intent = Intent(reactApplicationContext, BluetoothPrinterService::class.java)
+    val intent = Intent(reactApplicationContext, PrinterService::class.java)
     reactApplicationContext.startService(intent)
     reactApplicationContext.bindService(intent, serviceConnection, Context.BIND_AUTO_CREATE)
   }
 
   /** Runs [action] with the bound service, once available (queued if not yet bound). */
-  private fun withService(action: (BluetoothPrinterService) -> Unit) {
+  private fun withService(action: (PrinterService) -> Unit) {
     val service = printerService
     if (service != null) {
       action(service)
@@ -108,6 +125,17 @@ class ReactNativePrinterKitModule(reactContext: ReactApplicationContext) :
     val map = Arguments.createMap()
     map.putString("name", device.name)
     map.putString("address", device.address)
+    map.putString("confidence", device.confidence.name)
+    map.putString("reason", device.reason)
+    return map
+  }
+
+  private fun usbToMap(device: UsbPrinterDevice): WritableMap {
+    val map = Arguments.createMap()
+    map.putString("name", device.name)
+    map.putInt("vendorId", device.vendorId)
+    map.putInt("productId", device.productId)
+    map.putString("deviceName", device.deviceName)
     return map
   }
 
@@ -155,24 +183,74 @@ class ReactNativePrinterKitModule(reactContext: ReactApplicationContext) :
     }
   }
 
-  override fun getBondedBluetoothPrinters(): WritableArray {
+  override fun getBondedBluetoothPrinters(params: ReadableMap): WritableArray {
+    val filter = enumOrDefault(params.optString("filter"), PrinterFilter.ALL)
+    val keywords = params.getArray("extraNameKeywords")?.let { array ->
+      (0 until array.size()).mapNotNull { array.getString(it) }
+    } ?: emptyList()
     val result: WritableArray = Arguments.createArray()
-    standalonePrinter.getBondedBluetoothPrinters().forEach { device ->
+    standalonePrinter.getBondedBluetoothPrinters(filter, keywords).forEach { device ->
       result.pushMap(deviceToMap(device))
     }
     return result
   }
 
+  override fun getUsbPrinters(): WritableArray {
+    val result: WritableArray = Arguments.createArray()
+    standalonePrinter.getUsbPrinters().forEach { device ->
+      result.pushMap(usbToMap(device))
+    }
+    return result
+  }
+
+  override fun hasUsbPermission(params: ReadableMap): Boolean {
+    if (!params.hasKey("vendorId") || !params.hasKey("productId")) return false
+    return standalonePrinter.hasUsbPermission(
+      params.getDouble("vendorId").toInt(),
+      params.getDouble("productId").toInt()
+    )
+  }
+
+  override fun requestUsbPermission(params: ReadableMap, promise: Promise) {
+    if (!params.hasKey("vendorId") || !params.hasKey("productId")) {
+      promise.reject("ERROR", "vendorId and productId are required")
+      return
+    }
+    try {
+      // The result arrives on the main thread once the user answers the system dialog.
+      standalonePrinter.requestUsbPermission(
+        params.getDouble("vendorId").toInt(),
+        params.getDouble("productId").toInt()
+      ) { granted -> promise.resolve(granted) }
+    } catch (e: Exception) {
+      promise.reject("ERROR", e.message)
+    }
+  }
+
   override fun connectPrinter(params: ReadableMap, promise: Promise) {
-    val address = params.getString("address")
+    val type = enumOrDefault(params.optString("type"), PrinterConnectionType.BLUETOOTH)
+    // USB printers are identified by vendorId/productId, so address may be empty for them.
+    val address = params.optString("address") ?: if (type == PrinterConnectionType.USB) "" else null
     if (address == null) {
       promise.reject("ERROR", "address is required")
       return
     }
+    val defaults = ConnectPrinterParams(address)
+    val connectParams = ConnectPrinterParams(
+      address = address,
+      notificationTitle = params.optString("notificationTitle") ?: defaults.notificationTitle,
+      type = type,
+      port = params.optInt("port", defaults.port),
+      timeoutMs = params.optInt("timeoutMs", defaults.timeoutMs),
+      vendorId = params.optIntOrNull("vendorId"),
+      productId = params.optIntOrNull("productId"),
+      disconnectedNotificationTitle =
+        params.optString("disconnectedNotificationTitle") ?: defaults.disconnectedNotificationTitle
+    )
     withService { service ->
       executor.execute {
         try {
-          promise.resolve(service.connectAndKeepAlive(ConnectPrinterParams(address)))
+          promise.resolve(service.connectAndKeepAlive(connectParams))
         } catch (e: Exception) {
           promise.reject("ERROR", e.message)
         }
@@ -218,6 +296,72 @@ class ReactNativePrinterKitModule(reactContext: ReactApplicationContext) :
     }
   }
 
+  override fun isPrinterReady(promise: Promise) {
+    withService { service ->
+      executor.execute {
+        try {
+          promise.resolve(service.printer.isPrinterReady())
+        } catch (e: Exception) {
+          promise.reject("ERROR", e.message)
+        }
+      }
+    }
+  }
+
+  override fun getPrinterStatus(params: ReadableMap, promise: Promise) {
+    withService { service ->
+      executor.execute {
+        try {
+          val status = service.printer.getPrinterStatus(params.optInt("timeoutMs", 800))
+          // Unknown (null) fields must reach JS as null, which makeNativeMap preserves.
+          promise.resolve(Arguments.makeNativeMap(status.toMap()))
+        } catch (e: Exception) {
+          promise.reject("ERROR", e.message)
+        }
+      }
+    }
+  }
+
+  override fun printTestPage(promise: Promise) {
+    withService { service ->
+      executor.execute {
+        try {
+          service.printer.printTestPage()
+          promise.resolve(null)
+        } catch (e: Exception) {
+          promise.reject("ERROR", e.message)
+        }
+      }
+    }
+  }
+
+  override fun saveFile(params: ReadableMap, promise: Promise) {
+    val sourcePath = params.getString("sourcePath")
+    if (sourcePath == null) {
+      promise.reject("ERROR", "sourcePath is required")
+      return
+    }
+    executor.execute {
+      try {
+        val result = standalonePrinter.saveFile(
+          SaveFileParams(
+            sourcePath = sourcePath,
+            fileName = params.optString("fileName"),
+            location = enumOrDefault(params.optString("location"), FileLocation.DOWNLOADS),
+            customFolder = params.optString("customFolder"),
+            subFolder = params.optString("subFolder"),
+            mimeType = params.optString("mimeType"),
+            overwrite = params.optBoolean("overwrite", false),
+            deleteSource = params.optBoolean("deleteSource", false)
+          )
+        )
+        promise.resolve(Arguments.makeNativeMap(result.toMap()))
+      } catch (e: Exception) {
+        promise.reject("ERROR", e.message)
+      }
+    }
+  }
+
   override fun printText(params: ReadableMap, promise: Promise) {
     val text = params.getString("text")
     if (text == null) {

package/lib/module/NativeReactNativePrinterKit.js

@@ -1,6 +1,15 @@
 "use strict";
 
 import { TurboModuleRegistry, Platform } from 'react-native';
+
+/** How sure the library is that a paired Bluetooth device is a printer. */
+
+/** `ALL` lists every paired device, `LIKELY_PRINTERS` hides non-printers, `STRICT` keeps only certain ones. */
+
+/**
+ * `null` means "unknown" - the printer did not answer or does not report that condition. It is NOT "ok".
+ */
+
 function getModule() {
   return Platform.OS === 'android' ? TurboModuleRegistry.getEnforcing('ReactNativePrinterKit') : {};
 }

package/lib/module/NativeReactNativePrinterKit.js.map

@@ -1 +1 @@
-{"version":3,"names":["TurboModuleRegistry","Platform","getModule","OS","getEnforcing"],"sourceRoot":"../../src","sources":["NativeReactNativePrinterKit.ts"],"mappings":";;AAAA,SAASA,mBAAmB,EAAoBC,QAAQ,QAAQ,cAAc;AA2L9E,SAASC,SAASA,CAAA,EAAS;EACzB,OAAOD,QAAQ,CAACE,EAAE,KAAK,SAAS,GAC5BH,mBAAmB,CAACI,YAAY,CAAO,uBAAuB,CAAC,GAC9D,CAAC,CAAU;AAClB;AAEA,eAAeF,SAAS,CAAC,CAAC","ignoreList":[]}
+{"version":3,"names":["TurboModuleRegistry","Platform","getModule","OS","getEnforcing"],"sourceRoot":"../../src","sources":["NativeReactNativePrinterKit.ts"],"mappings":";;AAAA,SAASA,mBAAmB,EAAoBC,QAAQ,QAAQ,cAAc;;AAE9E;;AAGA;;AA2DA;AACA;AACA;;AA8PA,SAASC,SAASA,CAAA,EAAS;EACzB,OAAOD,QAAQ,CAACE,EAAE,KAAK,SAAS,GAC5BH,mBAAmB,CAACI,YAAY,CAAO,uBAAuB,CAAC,GAC9D,CAAC,CAAU;AAClB;AAEA,eAAeF,SAAS,CAAC,CAAC","ignoreList":[]}

package/lib/module/enums.js

@@ -0,0 +1,36 @@
+"use strict";
+
+// Runtime values for the string unions the native module uses, so callers can write
+// `PrinterFilter.LIKELY_PRINTERS` instead of a bare string. Each object is checked
+// against its union with `satisfies`, so a typo or a value the native side does not
+// know fails to compile. The plain strings keep working everywhere too.
+
+/** How sure the library is that a paired Bluetooth device is a printer. */
+export const PrinterConfidence = {
+  CONFIDENT: 'CONFIDENT',
+  LIKELY: 'LIKELY',
+  UNKNOWN: 'UNKNOWN'
+};
+/** `ALL` lists every paired device, `LIKELY_PRINTERS` hides non-printers, `STRICT` keeps only certain ones. */
+export const PrinterFilter = {
+  ALL: 'ALL',
+  LIKELY_PRINTERS: 'LIKELY_PRINTERS',
+  STRICT: 'STRICT'
+};
+export const PrinterConnectionType = {
+  BLUETOOTH: 'BLUETOOTH',
+  NETWORK: 'NETWORK',
+  USB: 'USB'
+};
+export const PrinterImageType = {
+  PNG: 'PNG',
+  JPEG: 'JPEG'
+};
+export const FileLocation = {
+  CACHE: 'CACHE',
+  APP_FILES: 'APP_FILES',
+  DOWNLOADS: 'DOWNLOADS',
+  DOCUMENTS: 'DOCUMENTS',
+  CUSTOM_FOLDER: 'CUSTOM_FOLDER'
+};
+//# sourceMappingURL=enums.js.map

package/lib/module/enums.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["PrinterConfidence","CONFIDENT","LIKELY","UNKNOWN","PrinterFilter","ALL","LIKELY_PRINTERS","STRICT","PrinterConnectionType","BLUETOOTH","NETWORK","USB","PrinterImageType","PNG","JPEG","FileLocation","CACHE","APP_FILES","DOWNLOADS","DOCUMENTS","CUSTOM_FOLDER"],"sourceRoot":"../../src","sources":["enums.ts"],"mappings":";;AAQA;AACA;AACA;AACA;;AAEA;AACA,OAAO,MAAMA,iBAAiB,GAAG;EAC/BC,SAAS,EAAE,WAAW;EACtBC,MAAM,EAAE,QAAQ;EAChBC,OAAO,EAAE;AACX,CAA2E;AAI3E;AACA,OAAO,MAAMC,aAAa,GAAG;EAC3BC,GAAG,EAAE,KAAK;EACVC,eAAe,EAAE,iBAAiB;EAClCC,MAAM,EAAE;AACV,CAAmE;AAGnE,OAAO,MAAMC,qBAAqB,GAAG;EACnCC,SAAS,EAAE,WAAW;EACtBC,OAAO,EAAE,SAAS;EAClBC,GAAG,EAAE;AACP,CAGC;AAID,OAAO,MAAMC,gBAAgB,GAAG;EAC9BC,GAAG,EAAE,KAAK;EACVC,IAAI,EAAE;AACR,CAAyE;AAIzE,OAAO,MAAMC,YAAY,GAAG;EAC1BC,KAAK,EAAE,OAAO;EACdC,SAAS,EAAE,WAAW;EACtBC,SAAS,EAAE,WAAW;EACtBC,SAAS,EAAE,WAAW;EACtBC,aAAa,EAAE;AACjB,CAAiE","ignoreList":[]}