react-native-earl-thermal-printer 1.0.0

package/README.md

@@ -0,0 +1,441 @@
+# react-native-earl-thermal-printer
+
+A React Native library for USB, Bluetooth (BLE), and Network (TCP/IP) thermal receipt printers.
+
+A modern, high-performance thermal printer library for React Native. Built with the New Architecture (TurboModules) for synchronous communication, zero legacy bridge overhead, and Android 12+ Bluetooth compliance.
+
+Built for the **React Native New Architecture** (TurboModules / Codegen). Supports Android and iOS.
+
+---
+
+## Requirements
+
+| Platform     | Minimum Version    |
+| ------------ | ------------------ |
+| React Native | >= 0.73            |
+| React        | >= 18              |
+| Android SDK  | 23 (compileSdk 34) |
+| iOS          | 13.4+              |
+
+## Installation
+
+```bash
+npm install react-native-earl-thermal-printer
+# or
+yarn add react-native-earl-thermal-printer
+```
+
+### iOS
+
+```bash
+cd ios && pod install
+```
+
+### Android
+
+No additional steps — the library auto-links via the React Native Gradle plugin.
+
+---
+
+## Printer Support Matrix
+
+| Feature              | Android |              iOS               |
+| -------------------- | :-----: | :----------------------------: |
+| USB Printer          |   Yes   | No (returns `ERR_UNSUPPORTED`) |
+| BLE Printer          |   Yes   |              Yes               |
+| Net Printer          |   Yes   |              Yes               |
+| Print Text (ESC/POS) |   Yes   |              Yes               |
+| Print Image          |   Yes   |              Yes               |
+| Print QR Code        |   Yes   |              Yes               |
+
+---
+
+## Quick Start
+
+```tsx
+import {
+	USBPrinter,
+	BLEPrinter,
+	NetPrinter,
+	NetPrinterEventEmitter,
+	RN_THERMAL_RECEIPT_PRINTER_EVENTS,
+} from "react-native-earl-thermal-printer";
+```
+
+### USB Printer (Android only)
+
+```tsx
+await USBPrinter.init();
+const devices = await USBPrinter.getDeviceList();
+await USBPrinter.connectPrinter(devices[0].vendor_id, devices[0].product_id);
+await USBPrinter.printText("Hello from USB!\n");
+await USBPrinter.printBill("Receipt line\n");
+USBPrinter.closeConn();
+```
+
+### BLE Printer
+
+```tsx
+await BLEPrinter.init();
+const devices = await BLEPrinter.getDeviceList();
+await BLEPrinter.connectPrinter(devices[0].inner_mac_address);
+await BLEPrinter.printText("Hello from BLE!\n");
+await BLEPrinter.printBill("Receipt line\n");
+BLEPrinter.closeConn();
+```
+
+### Net Printer
+
+```tsx
+await NetPrinter.init();
+
+// Listen for discovered printers on the local subnet
+NetPrinterEventEmitter.addListener(
+	RN_THERMAL_RECEIPT_PRINTER_EVENTS.EVENT_NET_PRINTER_SCANNED_SUCCESS,
+	(printers) => console.log("Found:", printers),
+);
+
+const devices = await NetPrinter.getDeviceList();
+await NetPrinter.connectPrinter("192.168.1.100", 9100);
+await NetPrinter.printText("Hello from Network!\n");
+await NetPrinter.printBill("Receipt line\n");
+NetPrinter.closeConn();
+```
+
+---
+
+## API Reference
+
+All three printer objects (`USBPrinter`, `BLEPrinter`, `NetPrinter`) share the same high-level interface:
+
+### `init(): Promise<string>`
+
+Initialize the printer module. **Must be called before any other method.**
+
+### `getDeviceList(): Promise<IUSBPrinter[] | IBLEPrinter[] | INetPrinter[]>`
+
+Scan for available printers and return a list of discovered devices.
+
+### `connectPrinter(...): Promise<object>`
+
+Connect to a printer.
+
+| Printer | Parameters                            |
+| ------- | ------------------------------------- |
+| USB     | `vendorId: number, productId: number` |
+| BLE     | `innerMacAddress: string`             |
+| Net     | `host: string, port: number`          |
+
+### `printText(text: string, opts?: PrinterOptions): Promise<void>`
+
+Print a text string using ESC/POS encoding. Supports formatting tags (see below).
+
+### `printBill(text: string, opts?: PrinterOptions): Promise<void>`
+
+Same as `printText` but defaults `beep`, `cut`, and `tailingLine` to `true`.
+
+### `printImage(imageUrl: string): Promise<void>`
+
+Print an image from a URL.
+
+### `printQrCode(qrCode: string): Promise<void>`
+
+Print a QR code.
+
+### `closeConn(): void`
+
+Disconnect from the printer.
+
+---
+
+## PrinterOptions
+
+```ts
+interface PrinterOptions {
+	beep?: boolean; // Beep after printing (default: false)
+	cut?: boolean; // Cut paper after printing (default: false)
+	tailingLine?: boolean; // Add trailing blank lines (default: false)
+	encoding?: string; // Text encoding (default: "UTF8")
+}
+```
+
+---
+
+## ESC/POS Formatting Tags
+
+The text helpers (`printText`, `printBill`) support inline formatting tags:
+
+| Tag            | Description            |
+| -------------- | ---------------------- |
+| `<B>...</B>`   | **Bold**               |
+| `<C>...</C>`   | Center-aligned         |
+| `<D>...</D>`   | Double-width           |
+| `<DB>...</DB>` | Double-width bold      |
+| `<M>...</M>`   | Medium (double-height) |
+
+Example:
+
+```tsx
+await NetPrinter.printBill(
+	"<C><B>MY STORE</B></C>\n" +
+		"================================\n" +
+		"Item 1            $5.00\n" +
+		"Item 2            $3.50\n" +
+		"================================\n" +
+		"<B>TOTAL             $8.50</B>\n",
+);
+```
+
+---
+
+## Interfaces
+
+```ts
+interface IUSBPrinter {
+	device_name: string;
+	device_id: number;
+	vendor_id: number;
+	product_id: number;
+}
+
+interface IBLEPrinter {
+	device_name: string;
+	inner_mac_address: string;
+}
+
+interface INetPrinter {
+	device_name: string;
+	host: string;
+	port: number;
+}
+```
+
+---
+
+## Events
+
+Net printer scanning emits events via `NetPrinterEventEmitter`:
+
+| Event             | Enum                                | Payload         |
+| ----------------- | ----------------------------------- | --------------- |
+| `scannerResolved` | `EVENT_NET_PRINTER_SCANNED_SUCCESS` | `INetPrinter[]` |
+| `scannerRunning`  | `EVENT_NET_PRINTER_SCANNING`        | `boolean`       |
+
+```tsx
+import {
+	NetPrinterEventEmitter,
+	RN_THERMAL_RECEIPT_PRINTER_EVENTS,
+} from "react-native-earl-thermal-printer";
+
+NetPrinterEventEmitter.addListener(
+	RN_THERMAL_RECEIPT_PRINTER_EVENTS.EVENT_NET_PRINTER_SCANNED_SUCCESS,
+	(printers) => {
+		console.log("Discovered printers:", printers);
+	},
+);
+
+NetPrinterEventEmitter.addListener(
+	RN_THERMAL_RECEIPT_PRINTER_EVENTS.EVENT_NET_PRINTER_SCANNING,
+	(isScanning) => {
+		console.log("Scanning:", isScanning);
+	},
+);
+```
+
+---
+
+## Android Permissions
+
+Add these permissions to your `AndroidManifest.xml`:
+
+```xml
+<!-- USB -->
+<uses-feature android:name="android.hardware.usb.host" android:required="false" />
+
+<!-- Bluetooth -->
+<uses-permission android:name="android.permission.BLUETOOTH" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+
+<!-- Network -->
+<uses-permission android:name="android.permission.INTERNET" />
+```
+
+---
+
+## Example
+
+```tsx
+import React, { useEffect, useState } from "react";
+import {
+	Alert,
+	Button,
+	FlatList,
+	PermissionsAndroid,
+	Platform,
+	StyleSheet,
+	Text,
+	TouchableOpacity,
+	View,
+} from "react-native";
+import { BLEPrinter, IBLEPrinter } from "react-native-earl-thermal-printer";
+
+export default function ThermalPrinterTest() {
+	const [printers, setPrinters] = useState<IBLEPrinter[]>([]);
+	const [currentPrinter, setCurrentPrinter] = useState<IBLEPrinter | null>(
+		null,
+	);
+
+	useEffect(() => {
+		BLEPrinter.init()
+			.then(() => {
+				console.log("Printer initialized");
+			})
+			.catch((err) => {
+				console.warn("Init failed:", err);
+			});
+	}, []);
+
+	const requestPermissions = async () => {
+		if (Platform.OS === "android") {
+			try {
+				const granted = await PermissionsAndroid.requestMultiple([
+					PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
+					PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
+					PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
+				]);
+				if (
+					granted["android.permission.BLUETOOTH_CONNECT"] ===
+					PermissionsAndroid.RESULTS.GRANTED
+				) {
+					scanDevices();
+				} else {
+					Alert.alert("Permission denied");
+				}
+			} catch (err) {
+				console.warn(err);
+			}
+		} else {
+			scanDevices();
+		}
+	};
+
+	const scanDevices = () => {
+		BLEPrinter.getDeviceList()
+			.then(setPrinters)
+			.catch((err) => Alert.alert("Scan Failed", String(err)));
+	};
+
+	const connectPrinter = (printer: IBLEPrinter) => {
+		BLEPrinter.connectPrinter(printer.inner_mac_address)
+			.then((connected) => {
+				setCurrentPrinter(connected);
+				Alert.alert(
+					"Connected",
+					`Connected to ${connected.device_name}`,
+				);
+			})
+			.catch((err) => Alert.alert("Connection Failed", String(err)));
+	};
+
+	const printTicket = async () => {
+		if (!currentPrinter) {
+			Alert.alert("No Printer", "Please connect to a printer first.");
+			return;
+		}
+
+		try {
+			// To print a QR code:
+			await BLEPrinter.printQrCode("ZAM-OC-0001");
+			// Print formatted receipt text (beeps + cuts automatically)
+			const bill =
+				"--------------------------------\n" +
+				"Item 1               $10.00\n" +
+				"Item 2               $20.00\n" +
+				"--------------------------------\n" +
+				"<B>TOTAL              $30.00</B>\n\n\n";
+
+			await BLEPrinter.printBill(bill);
+
+			// To print an image from URL:
+			// await BLEPrinter.printImage(
+			// 	"https://images.unsplash.com/photo-1771258052747-52e19364185f?q=80&w=765&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
+			// );
+		} catch (err) {
+			console.warn("Print error:", err);
+			Alert.alert("Print Error", String(err));
+		}
+	};
+
+	return (
+		<View style={styles.container}>
+			<Button title="Scan for Printers" onPress={requestPermissions} />
+
+			<FlatList
+				data={printers}
+				keyExtractor={(item) => item.inner_mac_address}
+				renderItem={({ item }) => (
+					<TouchableOpacity
+						style={styles.deviceItem}
+						onPress={() => connectPrinter(item)}
+					>
+						<Text>{item.device_name || "Unknown Device"}</Text>
+						<Text style={styles.subText}>
+							{item.inner_mac_address}
+						</Text>
+					</TouchableOpacity>
+				)}
+				style={{ maxHeight: 200, marginVertical: 20 }}
+			/>
+
+			<View style={styles.printArea}>
+				<Text style={{ marginBottom: 10 }}>
+					Status:{" "}
+					{currentPrinter
+						? `Connected to ${currentPrinter.device_name}`
+						: "Disconnected"}
+				</Text>
+				<Button
+					title="Print Test Receipt"
+					onPress={printTicket}
+					disabled={!currentPrinter}
+				/>
+			</View>
+		</View>
+	);
+}
+
+const styles = StyleSheet.create({
+	container: { flex: 1, padding: 40, paddingTop: 60 },
+	deviceItem: { padding: 10, borderBottomWidth: 1, borderColor: "#ccc" },
+	subText: { fontSize: 10, color: "#666" },
+	printArea: { marginTop: 20, alignItems: "center" },
+});
+```
+
+---
+
+## New Architecture
+
+This library is built for the React Native **New Architecture** using TurboModules and Codegen. It requires:
+
+- React Native **>= 0.73**
+- New Architecture **enabled** in your app
+
+The library ships codegen specs in `src/Native*.ts`. The native code is generated automatically during the build.
+
+---
+
+## Author
+
+**Ordovez, Earl Romeo**
+
+## License
+
+ISC
+
+## Funding
+
+If you find this library useful, consider [sponsoring on GitHub](https://github.com/sponsors/Swif7ify).

package/android/build/.transforms/9bdecbc31aaf57a08a337d36d73153ec/results.bin

@@ -0,0 +1 @@
+o/classes

package/android/build/.transforms/bc167481fd58833142c92ba32b0fc3e3/results.bin

@@ -0,0 +1 @@
+o/classes

package/android/build/generated/source/buildConfig/debug/com/pinmi/react/printer/BuildConfig.java

@@ -0,0 +1,10 @@
+/**
+ * Automatically generated file. DO NOT MODIFY
+ */
+package com.pinmi.react.printer;
+
+public final class BuildConfig {
+  public static final boolean DEBUG = Boolean.parseBoolean("true");
+  public static final String LIBRARY_PACKAGE_NAME = "com.pinmi.react.printer";
+  public static final String BUILD_TYPE = "debug";
+}

package/android/build/generated/source/codegen/java/com/pinmi/react/printer/NativeBLEPrinterSpec.java

@@ -0,0 +1,70 @@
+
+/**
+ * This code was generated by [react-native-codegen](https://www.npmjs.com/package/react-native-codegen).
+ *
+ * Do not edit this file as changes may cause incorrect behavior and will be lost
+ * once the code is regenerated.
+ *
+ * @generated by codegen project: GenerateModuleJavaSpec.js
+ *
+ * @nolint
+ */
+
+package com.pinmi.react.printer;
+
+import com.facebook.proguard.annotations.DoNotStrip;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.turbomodule.core.interfaces.TurboModule;
+import javax.annotation.Nonnull;
+
+public abstract class NativeBLEPrinterSpec extends ReactContextBaseJavaModule implements TurboModule {
+  public static final String NAME = "RNBLEPrinter";
+
+  public NativeBLEPrinterSpec(ReactApplicationContext reactContext) {
+    super(reactContext);
+  }
+
+  @Override
+  public @Nonnull String getName() {
+    return NAME;
+  }
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void init(Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void getDeviceList(Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void connectPrinter(String innerAddress, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void closeConn();
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void printRawData(String base64Data, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void printImageData(String imageUrl, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void printQrCode(String qrCode, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void addListener(String eventName);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void removeListeners(double count);
+}

package/android/build/generated/source/codegen/java/com/pinmi/react/printer/NativeNetPrinterSpec.java

@@ -0,0 +1,70 @@
+
+/**
+ * This code was generated by [react-native-codegen](https://www.npmjs.com/package/react-native-codegen).
+ *
+ * Do not edit this file as changes may cause incorrect behavior and will be lost
+ * once the code is regenerated.
+ *
+ * @generated by codegen project: GenerateModuleJavaSpec.js
+ *
+ * @nolint
+ */
+
+package com.pinmi.react.printer;
+
+import com.facebook.proguard.annotations.DoNotStrip;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.turbomodule.core.interfaces.TurboModule;
+import javax.annotation.Nonnull;
+
+public abstract class NativeNetPrinterSpec extends ReactContextBaseJavaModule implements TurboModule {
+  public static final String NAME = "RNNetPrinter";
+
+  public NativeNetPrinterSpec(ReactApplicationContext reactContext) {
+    super(reactContext);
+  }
+
+  @Override
+  public @Nonnull String getName() {
+    return NAME;
+  }
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void init(Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void getDeviceList(Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void connectPrinter(String host, double port, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void closeConn();
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void printRawData(String base64Data, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void printImageData(String imageUrl, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void printQrCode(String qrCode, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void addListener(String eventName);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void removeListeners(double count);
+}

package/android/build/generated/source/codegen/java/com/pinmi/react/printer/NativeUSBPrinterSpec.java

@@ -0,0 +1,62 @@
+
+/**
+ * This code was generated by [react-native-codegen](https://www.npmjs.com/package/react-native-codegen).
+ *
+ * Do not edit this file as changes may cause incorrect behavior and will be lost
+ * once the code is regenerated.
+ *
+ * @generated by codegen project: GenerateModuleJavaSpec.js
+ *
+ * @nolint
+ */
+
+package com.pinmi.react.printer;
+
+import com.facebook.proguard.annotations.DoNotStrip;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.turbomodule.core.interfaces.TurboModule;
+import javax.annotation.Nonnull;
+
+public abstract class NativeUSBPrinterSpec extends ReactContextBaseJavaModule implements TurboModule {
+  public static final String NAME = "RNUSBPrinter";
+
+  public NativeUSBPrinterSpec(ReactApplicationContext reactContext) {
+    super(reactContext);
+  }
+
+  @Override
+  public @Nonnull String getName() {
+    return NAME;
+  }
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void init(Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void getDeviceList(Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void connectPrinter(double vendorId, double productId, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void closeConn();
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void printRawData(String base64Data, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void printImageData(String imageUrl, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void printQrCode(String qrCode, Promise promise);
+}

package/android/build/generated/source/codegen/jni/CMakeLists.txt

@@ -0,0 +1,46 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+cmake_minimum_required(VERSION 3.13)
+set(CMAKE_VERBOSE_MAKEFILE on)
+
+file(GLOB react_codegen_SRCS CONFIGURE_DEPENDS *.cpp react/renderer/components/RNThermalReceiptPrinterSpec/*.cpp)
+
+add_library(
+  react_codegen_RNThermalReceiptPrinterSpec
+  SHARED
+  ${react_codegen_SRCS}
+)
+
+target_include_directories(react_codegen_RNThermalReceiptPrinterSpec PUBLIC . react/renderer/components/RNThermalReceiptPrinterSpec)
+
+target_link_libraries(
+  react_codegen_RNThermalReceiptPrinterSpec
+  fbjni
+  folly_runtime
+  glog
+  jsi
+  react_codegen_rncore
+  react_debug
+  react_nativemodule_core
+  react_render_core
+  react_render_debug
+  react_render_graphics
+  react_render_imagemanager
+  rrc_image
+  rrc_view
+  turbomodulejsijni
+  yoga
+)
+
+target_compile_options(
+  react_codegen_RNThermalReceiptPrinterSpec
+  PRIVATE
+  -DLOG_TAG=\"ReactNative\"
+  -fexceptions
+  -frtti
+  -std=c++20
+  -Wall
+)