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

package/src/enums.ts

@@ -0,0 +1,56 @@
+import type {
+  FileLocation as FileLocationValue,
+  PrinterConfidence as PrinterConfidenceValue,
+  PrinterConnectionType as PrinterConnectionTypeValue,
+  PrinterFilter as PrinterFilterValue,
+  PrinterImageType as PrinterImageTypeValue,
+} from './NativeReactNativePrinterKit';
+
+// 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',
+} as const satisfies Record<PrinterConfidenceValue, PrinterConfidenceValue>;
+export type PrinterConfidence =
+  (typeof PrinterConfidence)[keyof typeof PrinterConfidence];
+
+/** `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',
+} as const satisfies Record<PrinterFilterValue, PrinterFilterValue>;
+export type PrinterFilter = (typeof PrinterFilter)[keyof typeof PrinterFilter];
+
+export const PrinterConnectionType = {
+  BLUETOOTH: 'BLUETOOTH',
+  NETWORK: 'NETWORK',
+  USB: 'USB',
+} as const satisfies Record<
+  PrinterConnectionTypeValue,
+  PrinterConnectionTypeValue
+>;
+export type PrinterConnectionType =
+  (typeof PrinterConnectionType)[keyof typeof PrinterConnectionType];
+
+export const PrinterImageType = {
+  PNG: 'PNG',
+  JPEG: 'JPEG',
+} as const satisfies Record<PrinterImageTypeValue, PrinterImageTypeValue>;
+export type PrinterImageType =
+  (typeof PrinterImageType)[keyof typeof PrinterImageType];
+
+export const FileLocation = {
+  CACHE: 'CACHE',
+  APP_FILES: 'APP_FILES',
+  DOWNLOADS: 'DOWNLOADS',
+  DOCUMENTS: 'DOCUMENTS',
+  CUSTOM_FOLDER: 'CUSTOM_FOLDER',
+} as const satisfies Record<FileLocationValue, FileLocationValue>;
+export type FileLocation = (typeof FileLocation)[keyof typeof FileLocation];

package/src/index.tsx

@@ -1,15 +1,21 @@
 import ReactNativePrinterKit, {
   type BluetoothPrinterDevice,
   type ConnectPrinterParams,
+  type GetBondedPrintersParams,
   type HtmlToPdfParams,
   type OpenFileParams,
   type PdfToImageParams,
-  type PrinterImageType,
+  type PrinterStatus,
+  type PrinterStatusParams,
   type PrintHtmlParams,
   type PrintImageBase64Params,
   type PrintImageParams,
   type PrintPdfParams,
   type PrintTextParams,
+  type SaveFileParams,
+  type SaveFileResult,
+  type UsbDeviceParams,
+  type UsbPrinterDevice,
 } from './NativeReactNativePrinterKit';
 
 /**
@@ -35,16 +41,47 @@ export function requestBluetoothPermission(): Promise<boolean> {
 }
 
 /**
- * Get all Bluetooth devices already paired (bonded) with this device.
+ * Get the Bluetooth devices already paired (bonded) with this device, best printer
+ * matches first. Every device carries a `confidence`. Pass
+ * `{ filter: 'LIKELY_PRINTERS' }` to hide devices that do not look like printers
+ * (headphones, watches...), or `extraNameKeywords` for a printer with an unusual name.
  */
-export function getBondedBluetoothPrinters(): BluetoothPrinterDevice[] {
-  return ReactNativePrinterKit.getBondedBluetoothPrinters();
+export function getBondedBluetoothPrinters(
+  params: GetBondedPrintersParams = {}
+): BluetoothPrinterDevice[] {
+  return ReactNativePrinterKit.getBondedBluetoothPrinters(params);
 }
 
 /**
- * Connect to a paired Bluetooth printer by its MAC address. The connection
- * survives the app being swiped from Recents, and is reconnected to
- * automatically the next time the app starts.
+ * USB printers currently plugged in. Needs a phone with USB host (OTG).
+ */
+export function getUsbPrinters(): UsbPrinterDevice[] {
+  return ReactNativePrinterKit.getUsbPrinters();
+}
+
+/**
+ * Whether the user already granted this app access to that USB printer.
+ */
+export function hasUsbPermission(params: UsbDeviceParams): boolean {
+  return ReactNativePrinterKit.hasUsbPermission(params);
+}
+
+/**
+ * Shows the system USB permission dialog. Call before `connectPrinter` with
+ * `type: 'USB'`. The grant is lost when the app is reinstalled.
+ */
+export function requestUsbPermission(
+  params: UsbDeviceParams
+): Promise<boolean> {
+  return ReactNativePrinterKit.requestUsbPermission(params);
+}
+
+/**
+ * Connect to a printer over Bluetooth (default; paired printer's MAC address),
+ * Wi-Fi/LAN (`type: 'NETWORK'`, `address` = IP) or USB (`type: 'USB'` with
+ * `vendorId`/`productId`). The connection survives the app being swiped from
+ * Recents, and is reconnected to automatically the next time the app starts.
+ * Resolves `false` if it could not connect.
  */
 export function connectPrinter(params: ConnectPrinterParams): Promise<boolean> {
   return ReactNativePrinterKit.connectPrinter(params);
@@ -71,6 +108,41 @@ export function getConnectedPrinter(): Promise<BluetoothPrinterDevice | null> {
   return ReactNativePrinterKit.getConnectedPrinter();
 }
 
+/**
+ * Whether a printer is connected and currently accepts data. Does not check
+ * paper or cover - use `getPrinterStatus()`.
+ */
+export function isPrinterReady(): Promise<boolean> {
+  return ReactNativePrinterKit.isPrinterReady();
+}
+
+/**
+ * Asks the printer for its state (online / paper out / cover open / error).
+ * Many printers do not answer: then `responded` is `false` and the other fields
+ * are `null` (unknown, not "ok"). Some printers report an open cover as
+ * `paperOut`, so treat `paperOut: true` as "no paper or cover open".
+ */
+export function getPrinterStatus(
+  params: PrinterStatusParams = {}
+): Promise<PrinterStatus> {
+  return ReactNativePrinterKit.getPrinterStatus(params);
+}
+
+/**
+ * Prints a short ASCII test page.
+ */
+export function printTestPage(): Promise<void> {
+  return ReactNativePrinterKit.printTestPage();
+}
+
+/**
+ * Copies a file (e.g. the PDF from `htmlToPdf`) to cache, app storage, public
+ * Downloads/Documents or a chosen folder. Never rejects: check `result.success`.
+ */
+export function saveFile(params: SaveFileParams): Promise<SaveFileResult> {
+  return ReactNativePrinterKit.saveFile(params);
+}
+
 /**
  * Print raw text using the printer's built-in font (ASCII only - use
  * printHtml() for Bangla or other non-Latin scripts).
@@ -90,7 +162,9 @@ export function printImage(params: PrintImageParams): Promise<void> {
 /**
  * Print a base64-encoded image as an ESC/POS raster image.
  */
-export function printImageBase64(params: PrintImageBase64Params): Promise<void> {
+export function printImageBase64(
+  params: PrintImageBase64Params
+): Promise<void> {
   return ReactNativePrinterKit.printImageBase64(params);
 }
 
@@ -134,19 +208,34 @@ export function openFile(params: OpenFileParams): boolean {
   return ReactNativePrinterKit.openFile(params);
 }
 
+// Export enum-like constants (usable at runtime, and as types of the same name)
+export {
+  FileLocation,
+  PrinterConfidence,
+  PrinterConnectionType,
+  PrinterFilter,
+  PrinterImageType,
+} from './enums';
+
 // Export types
 export type {
   BluetoothPrinterDevice,
   ConnectPrinterParams,
+  GetBondedPrintersParams,
   HtmlToPdfParams,
   OpenFileParams,
   PdfToImageParams,
-  PrinterImageType,
+  PrinterStatus,
+  PrinterStatusParams,
   PrintHtmlParams,
   PrintImageBase64Params,
   PrintImageParams,
   PrintPdfParams,
   PrintTextParams,
+  SaveFileParams,
+  SaveFileResult,
+  UsbDeviceParams,
+  UsbPrinterDevice,
 };
 
 // Export native module