@munchi_oy/react-native-epson-printer 1.0.0

package/README.md

@@ -0,0 +1,223 @@
+# @munchi_oy/printer
+
+Epson printer SDK bridge for React Native.
+
+## Overview
+
+This package provides:
+- Epson discovery (`discoverPrinters`)
+- Epson connection lifecycle (`connect`, `disconnect`, connection events)
+- Epson print queueing and hardware-recovery retries
+- Receipt printing with generic `PrintJob` commands and embedded payload support
+
+This package does not include Star or Sunmi drivers.
+
+## Installation
+
+```bash
+npm install @munchi_oy/printer
+# or
+pnpm add @munchi_oy/printer
+```
+
+## iOS Setup
+
+1. Add the package.
+2. Run CocoaPods install in your iOS project:
+
+```bash
+cd ios && pod install
+```
+
+3. Ensure Bluetooth/network permissions are configured in `Info.plist` for your transport mode.
+
+## Android Setup
+
+1. Add the package and sync Gradle.
+2. Ensure runtime permissions are requested in your app before discovery/connection:
+- Android 12+ (`API 31+`): `BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT`
+- Android 11 and below: location permission for Bluetooth discovery (`ACCESS_FINE_LOCATION`)
+3. Rebuild the Android app after installation.
+
+## Quick Start
+
+```ts
+import { EpsonModel, getPrinter } from '@munchi_oy/printer';
+
+const printer = getPrinter({
+  target: 'BT:00:01:90:7B:5A:11',
+  model: EpsonModel.TM_M30III,
+});
+
+await printer.connect();
+await printer.print({
+  commands: [
+    { type: 'text', text: 'Hello\n', align: 'center', bold: true },
+    { type: 'feed', lines: 2 },
+    { type: 'cut' },
+  ],
+});
+await printer.disconnect();
+```
+
+## Config
+
+`getPrinter(config)` requires `EpsonPrinterConfig`.
+
+| Field | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `model` | `EpsonModel` | Yes | Epson printer series passed to native init |
+| `target` | `string` | No | Default target (for `connect()` without args) |
+| `lang` | `Epos2Lang` | No | Language enum used by native printer object |
+| `logger` | `PrinterLogger` | No | SDK logger hook (`error`, optional `info`) |
+
+## Discovery
+
+Use discovery as a standalone API:
+
+```ts
+import { discoverPrinters } from '@munchi_oy/printer';
+
+const printers = await discoverPrinters({ timeout: 5000, connectionType: 'bluetooth' });
+```
+
+`discoverPrinters` filters out Epson sub-device targets like `[local_display]`.
+
+## Connection Lifecycle
+
+- `connect(target?, timeout?)`
+- `disconnect()`
+- `onConnectionChange(callback)`
+
+Examples:
+
+```ts
+await printer.connect(); // uses config.target
+await printer.connect('TCP:192.168.1.50', 7000); // override target
+
+const unsubscribe = printer.onConnectionChange((status) => {
+  console.log('status', status);
+});
+```
+
+## Printing
+
+### PrintJob
+
+```ts
+await printer.print({
+  commands: [
+    { type: 'align', align: 'left' },
+    { type: 'text', text: 'Order #123\n' },
+    { type: 'separator' },
+    { type: 'cut' },
+  ],
+});
+```
+
+### Embedded Payload
+
+```ts
+await printer.printEmbedded({
+  id: 'Ord-123',
+  ts: '12:00 PM',
+  lines: [{ t: '1x Burger' }],
+});
+```
+
+### Cash Drawer
+
+```ts
+await printer.openDrawer();
+```
+
+## Multi-Instance And Session Behavior
+
+Each `getPrinter(...)` instance has its own native `sessionId`.
+
+This ensures:
+- native calls are isolated per JS instance
+- native events are routed by session
+- instance A does not consume instance B events
+
+If two instances connect to the same target at the same time, native returns `TARGET_IN_USE`.
+
+## Logging
+
+You can inject logger per instance or set a global logger.
+
+```ts
+import { setGlobalLogger } from '@munchi_oy/printer';
+
+setGlobalLogger({
+  info: (message) => console.log(message),
+  error: (message, error) => console.error(message, error),
+});
+```
+
+## What We Support
+
+### Vendor Support
+
+| Vendor | Support |
+| :--- | :--- |
+| Epson | Yes |
+| Star | No |
+| Sunmi | No |
+
+### Platform Focus
+
+| Platform | Status |
+| :--- | :--- |
+| iOS | Supported |
+| Android | Supported |
+
+### Connection Types
+
+- Bluetooth (`BT:`)
+- TCP (`TCP:`, `TCPS:`)
+- USB (`USB:`)
+
+## Known Issues
+
+- If printer hardware state is bad (cover open/paper out), jobs pause until recovery is detected.
+- Discovery quality depends on OS radio/network state and Epson SDK behavior.
+- Connecting to the same target from multiple active sessions returns `TARGET_IN_USE`.
+
+## Limitations
+
+- Epson-only package scope.
+- `model` must be known at instance creation time.
+- No direct API to change model/lang after instance creation; create a new printer instance instead.
+- Bridge behavior depends on Epson ePOS2 SDK constraints.
+
+## Troubleshooting
+
+1. `Native module not found`
+- iOS: reinstall pods and rebuild.
+- Android: clean/sync Gradle and rebuild.
+
+2. `Printer target is required`
+- Pass `target` in config or in `connect(target)`.
+
+3. Frequent busy/connect retries
+- Ensure only one active session per target and stable transport.
+
+## Migration Guide (Breaking Changes)
+
+If you are upgrading from older versions:
+
+1. Epson-only
+- Removed `PrinterType`, Star/Sunmi drivers, and adapter-style vendor factory.
+
+2. Config changes
+- `model` is now required in `getPrinter({ ... })`.
+
+3. Connect signature changes
+- Before: `connect(target, timeout, model, lang)`
+- Now: `connect(target?, timeout?)`
+- Model/lang come from instance config.
+
+4. Paths and exports
+- Epson internals moved from `src/vendors/epson/*` to `src/epson/*`.
+- Public imports remain from `@munchi_oy/printer`.

package/android/build.gradle

@@ -0,0 +1,34 @@
+def safeExtGet(prop, fallback) {
+    return rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace 'com.munchiepsonprinter'
+    compileSdkVersion safeExtGet('compileSdkVersion', 35)
+
+    defaultConfig {
+        minSdkVersion safeExtGet('minSdkVersion', 24)
+        targetSdkVersion safeExtGet('targetSdkVersion', 35)
+        consumerProguardFiles 'consumer-rules.pro'
+    }
+
+    sourceSets {
+        main {
+            java.srcDirs = ['src/main/java']
+            manifest.srcFile 'src/main/AndroidManifest.xml'
+            jniLibs.srcDirs = ['src/main/jniLibs']
+        }
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-native:+'
+    implementation files('libs/ePOS2.jar')
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,17 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.munchiepsonprinter">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <uses-permission
+        android:name="android.permission.BLUETOOTH_SCAN"
+        android:usesPermissionFlags="neverForLocation" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+
+    <uses-permission
+        android:name="android.permission.BLUETOOTH"
+        android:maxSdkVersion="30" />
+    <uses-permission
+        android:name="android.permission.BLUETOOTH_ADMIN"
+        android:maxSdkVersion="30" />
+</manifest>