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

package/src/NativeReactNativePrinterKit.ts

@@ -1,14 +1,105 @@
 import { TurboModuleRegistry, type TurboModule, Platform } from 'react-native';
 
+/** How sure the library is that a paired Bluetooth device is a printer. */
+export type PrinterConfidence = 'CONFIDENT' | 'LIKELY' | 'UNKNOWN';
+
+/** `ALL` lists every paired device, `LIKELY_PRINTERS` hides non-printers, `STRICT` keeps only certain ones. */
+export type PrinterFilter = 'ALL' | 'LIKELY_PRINTERS' | 'STRICT';
+
+export type PrinterConnectionType = 'BLUETOOTH' | 'NETWORK' | 'USB';
+
 export type BluetoothPrinterDevice = {
+  /** `null` for a Wi-Fi/LAN printer. */
   name: string | null;
+  /** Bluetooth MAC, the host for a Wi-Fi/LAN printer, or `"vendorId:productId"` for a USB printer. */
   address: string;
+  confidence: PrinterConfidence;
+  /** Why it got that confidence, e.g. "Printer-like name + SPP service". May be `null`. */
+  reason: string | null;
+};
+
+export type GetBondedPrintersParams = {
+  filter?: PrinterFilter;
+  /** Extra name fragments to treat as printers, for printers with unusual names. */
+  extraNameKeywords?: string[];
+};
+
+export type UsbPrinterDevice = {
+  name: string | null;
+  vendorId: number;
+  productId: number;
+  deviceName: string;
+};
+
+export type UsbDeviceParams = {
+  vendorId: number;
+  productId: number;
 };
 
 export type PrinterImageType = 'PNG' | 'JPEG';
 
 export type ConnectPrinterParams = {
+  /** Bluetooth MAC address, or the IP/host for `NETWORK`. Ignored (use `""`) for `USB`. */
   address: string;
+  /** Default `BLUETOOTH`. */
+  type?: PrinterConnectionType;
+  /** `NETWORK` only. Default 9100. */
+  port?: number;
+  /** `NETWORK` connect timeout in ms. Default 5000. */
+  timeoutMs?: number;
+  /** `USB` only, from `getUsbPrinters()`. */
+  vendorId?: number;
+  /** `USB` only, from `getUsbPrinters()`. */
+  productId?: number;
+  /** Title of the ongoing "connected" notification. Default "Printer connected". */
+  notificationTitle?: string;
+  /** Title of the notification shown if the printer drops later. Default "Printer disconnected". */
+  disconnectedNotificationTitle?: string;
+};
+
+export type PrinterStatusParams = {
+  /** How long to wait for the printer to answer, in ms. Default 800. */
+  timeoutMs?: number;
+};
+
+/**
+ * `null` means "unknown" - the printer did not answer or does not report that condition. It is NOT "ok".
+ */
+export type PrinterStatus = {
+  connected: boolean;
+  /** `false` means the printer ignored the status request and every field below is `null`. */
+  responded: boolean;
+  online: boolean | null;
+  paperOut: boolean | null;
+  paperNearEnd: boolean | null;
+  coverOpen: boolean | null;
+  hasError: boolean | null;
+};
+
+export type FileLocation =
+  'CACHE' | 'APP_FILES' | 'DOWNLOADS' | 'DOCUMENTS' | 'CUSTOM_FOLDER';
+
+export type SaveFileParams = {
+  sourcePath: string;
+  /** Defaults to the source file's name. */
+  fileName?: string;
+  /** Default `DOWNLOADS`. */
+  location?: FileLocation;
+  /** Required for `CUSTOM_FOLDER`: a `content://` tree Uri string or a directory path. */
+  customFolder?: string;
+  subFolder?: string;
+  /** Guessed from the file extension when not given. */
+  mimeType?: string;
+  overwrite?: boolean;
+  deleteSource?: boolean;
+};
+
+export type SaveFileResult = {
+  success: boolean;
+  path: string | null;
+  uri: string | null;
+  fileName: string | null;
+  error: string | null;
 };
 
 export type PrintTextParams = {
@@ -73,6 +164,12 @@ export type PrintHtmlParams = {
   bandDelayMs?: number;
 };
 
+export type OpenFileParams = {
+  path: string;
+  /** Inferred from the file extension if not given. */
+  mimeType?: string;
+};
+
 export interface Spec extends TurboModule {
   /**
    * Whether the device's Bluetooth adapter itself is turned on. Needs no runtime
@@ -94,16 +191,35 @@ export interface Spec extends TurboModule {
   requestBluetoothPermission(): Promise<boolean>;
 
   /**
-   * Returns all Bluetooth devices already paired (bonded) with this device.
+   * Returns the Bluetooth devices already paired (bonded) with this device, best printer matches first.
    * On Android 12+ this requires the BLUETOOTH_CONNECT permission to be granted.
+   * Pass `{}` for every paired device, or `{ filter: 'LIKELY_PRINTERS' }` to hide non-printers.
    */
-  getBondedBluetoothPrinters(): BluetoothPrinterDevice[];
+  getBondedBluetoothPrinters(
+    params: GetBondedPrintersParams
+  ): BluetoothPrinterDevice[];
 
   /**
-   * Opens a Bluetooth SPP connection to the paired printer at the given address.
-   * Closes any existing printer connection first. Remembers the address so the
+   * USB printers currently plugged in (USB printer class). Needs a phone with USB host (OTG).
+   */
+  getUsbPrinters(): UsbPrinterDevice[];
+
+  /**
+   * Whether the user already granted this app access to that USB printer.
+   */
+  hasUsbPermission(params: UsbDeviceParams): boolean;
+
+  /**
+   * Shows the system USB permission dialog and resolves with the user's answer.
+   * Call this before `connectPrinter` with `type: 'USB'`. The grant is lost when the app is reinstalled.
+   */
+  requestUsbPermission(params: UsbDeviceParams): Promise<boolean>;
+
+  /**
+   * Connects over Bluetooth (default), Wi-Fi/LAN or USB depending on `params.type`.
+   * Closes any existing printer connection first. Remembers the printer so the
    * app reconnects automatically next time it's opened (see the README's
-   * "Persistent connection" section).
+   * "Persistent connection" section). Resolves `false` (does not reject) if it could not connect.
    */
   connectPrinter(params: ConnectPrinterParams): Promise<boolean>;
 
@@ -122,6 +238,29 @@ export interface Spec extends TurboModule {
    */
   getConnectedPrinter(): Promise<BluetoothPrinterDevice | null>;
 
+  /**
+   * Whether a printer is connected AND currently accepts data (it may be switched off or out of range).
+   * Does not check paper or the cover - use `getPrinterStatus` for that.
+   */
+  isPrinterReady(): Promise<boolean>;
+
+  /**
+   * Asks the printer for its state (online, paper, cover, error). Many cheap printers do not answer:
+   * then `responded` is `false` and every other field is `null` (unknown, NOT ok).
+   */
+  getPrinterStatus(params: PrinterStatusParams): Promise<PrinterStatus>;
+
+  /**
+   * Prints a short ASCII test page (connection type, printer, address, time).
+   */
+  printTestPage(): Promise<void>;
+
+  /**
+   * Copies a finished file (e.g. the PDF from `htmlToPdf`) to cache, app storage, public
+   * Downloads/Documents or a chosen folder. Never rejects: check `result.success`.
+   */
+  saveFile(params: SaveFileParams): Promise<SaveFileResult>;
+
   /**
    * Print raw text using the printer's built-in font. ASCII only - not
    * suitable for Bangla or other non-Latin scripts, use printHtml() instead.
@@ -169,6 +308,14 @@ export interface Spec extends TurboModule {
    * content with Bangla or other non-Latin text, or any real HTML/CSS layout.
    */
   printHtml(params: PrintHtmlParams): Promise<boolean>;
+
+  /**
+   * Opens a file with whatever app the user has installed that can handle its
+   * type (e.g. a PDF viewer) - shows the system's "Open with" chooser if more
+   * than one app matches. `mimeType` is inferred from the file extension if
+   * not given. Returns false if the file doesn't exist or no app can open it.
+   */
+  openFile(params: OpenFileParams): boolean;
 }
 
 function getModule(): Spec {

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,14 +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';
 
 /**
@@ -34,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);
@@ -70,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).
@@ -89,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);
 }
 
@@ -123,18 +198,44 @@ export function printHtml(params: PrintHtmlParams): Promise<boolean> {
   return ReactNativePrinterKit.printHtml(params);
 }
 
+/**
+ * Opens a file with whatever app the user has installed that can handle its
+ * type (e.g. a PDF viewer) - shows the system's "Open with" chooser if more
+ * than one app matches. Returns false if the file doesn't exist or no app
+ * can open it.
+ */
+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