node-thermal-printer-js 1.2.1 → 1.2.3

package/README.md

@@ -2,78 +2,68 @@
 
 Public npm package for sending ESC/POS print jobs to a PSF588 printer over BLE or classic Bluetooth COM port.
 
-## ⚠️ Installation Requirements (READ FIRST)
+## Installation
 
-### Required Software
-- **Node.js**: 16.0.0 or higher
-- **Python**: 3.9 or higher (downloads: https://www.python.org/downloads/)
-- **pip**: Python package manager (usually included with Python)
+```bash
+npm install node-thermal-printer-js
+```
 
-### Required Python Library
-- **bleak**: BLE client library for Python
-  - Auto-installed during `npm install` (see postinstall)
-  - Or manually: `pip install bleak`
+That's it! No validation, no postinstall hooks. Just a clean package.
 
-### Platform-Specific Requirements
+---
 
-#### Windows
-- Python 3.9+ with pip
-- Bluetooth drivers (usually included with Windows 10+)
-- No special permissions needed
+## Runtime Requirements
 
-#### macOS
-- Python 3.9+ with pip
-- Ensure Bluetooth is enabled in System Preferences
-- May require granting Terminal/Node.js permission to use Bluetooth
+To use this package, your environment needs:
 
-#### Linux
-- Python 3.9+ with pip
-- **Required group permissions**:
-  ```bash
-  sudo usermod -a -G dialout,plugdev $USER
-  ```
-  Then log out and back in for changes to take effect.
-  Without this, BLE operations will fail with permission errors.
+- **Node.js**: 16.0.0 or higher
+- **Python**: 3.9 or higher
+- **Python package**: `bleak` (BLE client library)
 
-## Quick Start
+### For End Users (.exe Applications)
+
+If you're distributing this as an `.exe`, include the `setup-runtime.bat` script:
 
-### 1. Install Package
 ```bash
-npm install node-thermal-printer-js
+setup-runtime.bat
 ```
 
-The postinstall script will:
-- ✅ Check for Python 3.9+
-- ✅ Verify/install bleak library
-- ✅ Display platform-specific setup instructions
+This script automatically:
+1. ✅ Checks and installs Node.js (if missing)
+2. ✅ Checks and installs Python 3.11 (if missing)
+3. ✅ Installs the `bleak` library
+4. ✅ Shows timing for each step
 
-### 2. Create `.env` Configuration (Optional)
-```env
-# Transport: "ble-server" (recommended), "ble", or "com"
-PRINTER_TRANSPORT=ble-server
+**Usage:**
+- Unzip your application
+- Double-click `setup-runtime.bat`
+- Wait for completion
+- Run your `.exe`
 
-# BLE Configuration
-PRINTER_BLE_NAME=PSF588
-PRINTER_BLE_ADDRESS=C8:47:8C:1F:72:34
-PRINTER_BLE_CHAR_UUID=49535343-8841-43f4-a8d4-ecbe34729bb3
+---
 
-# Server Configuration
-PRINTER_BLE_SERVER_HOST=127.0.0.1
-PRINTER_BLE_SERVER_PORT=5555
-PRINTER_BLE_REQUEST_TIMEOUT_MS=40000
+## Quick Start (Development)
 
-# COM Port (for Windows COM transport)
-PRINTER_COM_PORT=COM3
+### 1. Install Package
 
-# Python Command (if auto-detection fails)
-PRINTER_PYTHON_CMD=python3
+```bash
+npm install node-thermal-printer-js
+```
+
+### 2. Ensure Python & Bleak are Available
+
+```bash
+python -m pip install bleak
+# or
+python3 -m pip install bleak
 ```
 
-### 3. Use in Code
+### 3. Use in Your Code
+
 ```js
 import { printData, startPrinterServer, stopPrinterServer } from "node-thermal-printer-js";
 
-// Option 1: Fast persistent server (recommended)
+// Option 1: Fast persistent server (recommended for multiple prints)
 await startPrinterServer({ bleName: "PSF588" });
 await printData("Hello World");
 await printData("Second print (faster)");
@@ -87,31 +77,61 @@ await printData("Hello World", {
   connectTimeout: 15
 });
 
-// Option 3: COM port (Windows)
+// Option 3: Windows COM port
 await printData("Hello World", { 
   transport: "com",
   portPath: "COM3"
 });
 ```
 
+---
+
+## Configuration (.env)
+
+Create a `.env` file to customize behavior:
+
+```env
+# Transport: "ble-server" (recommended), "ble", or "com"
+PRINTER_TRANSPORT=ble-server
+
+# BLE Configuration
+PRINTER_BLE_NAME=PSF588
+PRINTER_BLE_ADDRESS=C8:47:8C:1F:72:34
+PRINTER_BLE_CHAR_UUID=49535343-8841-43f4-a8d4-ecbe34729bb3
+
+# Server Configuration
+PRINTER_BLE_SERVER_HOST=127.0.0.1
+PRINTER_BLE_SERVER_PORT=5555
+PRINTER_BLE_REQUEST_TIMEOUT_MS=40000
+
+# COM Port (for Windows COM transport)
+PRINTER_COM_PORT=COM3
+
+# Python Command (if auto-detection fails)
+PRINTER_PYTHON_CMD=python3
+```
+
+---
+
 ## API Reference
 
 ### `printData(data, options?)`
+
 Print ESC/POS data to thermal printer.
 
 **Parameters:**
 - `data` (string): ESC/POS data to print
 - `options` (object, optional):
-  - `transport` (string): "ble-server", "ble", or "com" - default: "ble-server"
-  - `bleName` (string): Printer name for BLE discovery
-  - `bleAddress` (string): MAC address (e.g., "C8:47:8C:1F:72:34")
-  - `charUUID` (string): BLE characteristic UUID for write operations
-  - `portPath` (string): COM port path (e.g., "COM3") for COM transport
+  - `transport` (string): `"ble-server"`, `"ble"`, or `"com"` — default: `"ble-server"`
+  - `bleName` (string): Printer BLE device name
+  - `bleAddress` (string): BLE MAC address (e.g., `"C8:47:8C:1F:72:34"`)
+  - `charUUID` (string): BLE characteristic UUID
+  - `portPath` (string): COM port path for Windows (e.g., `"COM3"`)
   - `scanTimeout` (number): BLE scan timeout in seconds (default: 10)
   - `connectTimeout` (number): BLE connection timeout in seconds (default: 15)
-  - `requestTimeoutMs` (number): Server request timeout in ms (default: 40000)
+  - `requestTimeoutMs` (number): Server request timeout in milliseconds (default: 40000)
 
-**Returns:** Promise<{ok: boolean, bytes_sent: number}>
+**Returns:** `Promise<{ok: boolean, bytes_sent: number}>`
 
 **Example:**
 ```js
@@ -126,12 +146,15 @@ try {
 }
 ```
 
+---
+
 ### `startPrinterServer(options?)`
-Start persistent BLE server for faster multi-print performance. The server stays running to eliminate connection overhead.
+
+Start persistent BLE server for faster multi-print performance.
 
 **Parameters:** Same as `printData` options
 
-**Returns:** Promise<void>
+**Returns:** `Promise<void>`
 
 **Example:**
 ```js
@@ -142,13 +165,19 @@ await startPrinterServer({
 console.log("Server ready for fast printing");
 ```
 
+---
+
 ### `stopPrinterServer()`
+
 Stop the running BLE server and clean up resources.
 
-**Returns:** Promise<void>
+**Returns:** `Promise<void>`
+
+---
 
 ### `getPrinterServerStatus()`
-Get status of running BLE server.
+
+Get status of the running BLE server.
 
 **Returns:**
 ```js
@@ -160,164 +189,141 @@ Get status of running BLE server.
 }
 ```
 
+---
+
+## Transport Modes
+
+| Mode | Speed | Best For |
+|------|-------|----------|
+| `ble-server` | 100-200ms | Multiple prints, APIs, production |
+| `ble` | 1-2s | Single prints, testing, fallback |
+| `com` | Variable | Windows paired COM port, fallback |
+
+**Recommendation:** Use `ble-server` (default) for best performance.
+
+---
+
 ## Troubleshooting
 
-### "Python 3.9+ not found"
-**Solution:**
-1. Install Python from https://www.python.org/downloads/
-2. Ensure Python is in system PATH:
-   - Windows: Check "Add Python to PATH" during installation
-   - Mac/Linux: Verify `python3` works in terminal
-3. Set environment variable:
-   ```bash
-   export PRINTER_PYTHON_CMD=python3  # or python, py.exe, etc.
-   ```
-4. Run: `npm install` again
+### Python or Bleak Not Found
 
-### "bleak module not found"
-**Solution:**
+**For Developers:**
 ```bash
+# Install Python from: https://www.python.org/downloads/ (3.9+)
+# Then install bleak:
 pip install bleak
-# or with Python 3 explicitly:
-python3 -m pip install bleak
 ```
 
-### "Address already in use" (Port 5555)
-**Solution:**
-This happens if a previous BLE server crashed. The package auto-detects and cleans up stale processes, but manual cleanup:
-```bash
-# Windows
-netstat -ano | findstr :5555
-taskkill /PID <PID> /F
+**For End Users (.exe):**
+- Run `setup-runtime.bat` to auto-install everything
 
-# Mac/Linux
-lsof -ti:5555 | xargs kill -9
-```
+### "Device not found" or Connection Timeouts
 
-### "Device not found" or connection timeouts
-**Solutions:**
 1. Ensure printer is powered on and in BLE discoverable mode
 2. Increase timeouts:
    ```js
    await printData(data, { scanTimeout: 20, connectTimeout: 25 });
    ```
-3. Try specifying MAC address (faster than name discovery):
+3. Try specifying MAC address (faster than discovery):
    ```js
    await printData(data, { bleAddress: "C8:47:8C:1F:72:34" });
    ```
-4. On Linux, verify group permissions: `id $USER` should show `dialout` and `plugdev` groups
 
-### "Permission denied" (Linux)
-**Solution:**
+### "Address already in use" (Port 5555)
+
+This happens if a previous BLE server crashed. Restart your terminal or kill the process:
+
+**Windows:**
 ```bash
-# Add user to required groups
-sudo usermod -a -G dialout,plugdev $USER
+netstat -ano | findstr :5555
+taskkill /PID <PID> /F
+```
 
-# Apply immediately (or log out/in)
-su - $USER
+**Mac/Linux:**
+```bash
+lsof -ti:5555 | xargs kill -9
 ```
 
-### Print job times out
-**Solutions:**
+### Print Job Times Out
+
 1. Increase timeout:
    ```js
    await printData(data, { requestTimeoutMs: 60000 });
    ```
-2. Check printer is still connected and responsive
-3. Try legacy BLE transport:
+2. Check printer is still connected
+3. Try fallback transport:
    ```js
-   await printData(data, { transport: "ble" });  // No persistent server
+   await printData(data, { transport: "ble" });
    ```
 
-## Performance
-
-### Transport Modes Comparison
-
-| Mode | Speed | Resource Use | Recommended For |
-|------|-------|--------------|-----------------|
-| `ble-server` | **100-200ms** ✓ | Low (persistent) | Multiple prints, APIs |
-| `ble` | 1-2s | Medium (spawn/connect each time) | Single prints, testing |
-| `com` | Variable | Low | Windows paired COM port |
-
-### Why `ble-server` is Fast
-- Reuses single BLE connection for multiple prints
-- Eliminates per-print connection overhead (1s)
-- Persistent Python daemon handles I/O
-
-## Development
-
-### Local Development
-```bash
-# Clone and setup
-git clone <repo>
-cd Printer
-npm install
-
-# Run tests
-npm test
-
-# Watch mode
-npm run dev
-```
-
-### Requirements for development
-```bash
-# Install Python dev dependencies
-pip install -r requirements.txt
-```
+---
 
 ## Architecture
 
 ### Components
-1. **app.js** (Node.js): Express-compatible export module, socket IPC client
-2. **ble_server.py** (Python): Long-running BLE daemon, accepts print requests over TCP
-3. **ble_print.py** (Python): Fallback legacy BLE bridge (process per print)
-4. **scripts/install-deps.js** (Node.js): Postinstall hook for dependency verification
 
-### Data Flow
+1. **app.js** — Main Node.js module with BLE client logic
+2. **ble_server.py** — Persistent Python BLE daemon (optional, for ble-server mode)
+3. **ble_print.py** — Legacy BLE bridge (one process per print)
+4. **ble_scan.py** — Device discovery utility
+
+### Data Flow (ble-server mode - Recommended)
+
 ```
-printData(data)
+printData(data, options)
+  ↓
+startBleServer() [if not running]
   ↓
-[ble-server mode]
+Node.js spawns ble_server.py (persistent)
   ↓
-sendToBleServer() → TCP socket to ble_server.py
+Send TCP request to server with ESC/POS data
   ↓
-ble_server.py connects to PSF588 printer (reused)
+ble_server.py connects to PSF588 via BLE
   ↓
-Writes ESC/POS data via BLE characteristic write
+Writes data via BLE characteristic
   ↓
-Response sent back over socket
+Response returned to Node.js
+```
+
+### Data Flow (ble mode - Fallback)
 
-[ble mode - fallback]
+```
+printData(data, options)
+  ↓
+Spawn ble_print.py process
   ↓
-Spawn new ble_print.py process
+Connect to printer, send data, exit
   ↓
-Process connects to printer, prints, exits (slower)
+Response returned to Node.js
 ```
 
-## License
+---
 
-ISC
+## Development
+
+### Local Setup
 
+```bash
+git clone <repo>
+cd Printer
+npm install
 
-If you plan to use `transport: "ble"`, you need a Python 3.11+ environment with the `bleak` library (the repo includes `ble_print.py` and `ble_scan.py`). Follow the steps for your platform.
+# Install Python dependencies
+pip install bleak
 
-- Windows (recommended using the Python launcher):
+# Run tests
+npm test
 
-```powershell
-py -3.11 -m venv .venv
-.\.venv\Scripts\activate
-pip install -r requirements.txt
-# or: pip install bleak
+# Watch mode
+npm run dev
 ```
 
-- macOS / Linux:
+---
+
+## License
+
+ISC
 
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-# or: pip install bleak
 ```
 
 Verify the Python BLE dependency is available:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-thermal-printer-js",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "ESC/POS printer helper for PSF588 Bluetooth and COM printing.",
   "main": "app.js",
   "exports": {
@@ -11,18 +11,13 @@
     "ble_print.py",
     "ble_scan.py",
     "ble_server.py",
-    "scripts/install-deps.js",
     "README.md"
   ],
   "scripts": {
-    "postinstall": "node scripts/install-deps.js",
     "test": "node test-api.js",
     "dev": "node --watch app.js",
     "pack:dry": "npm pack --dry-run"
   },
-  "engines": {
-    "node": ">=16.0.0"
-  },
   "keywords": [
     "printer",
     "escpos",

package/scripts/install-deps.js

@@ -1,177 +0,0 @@
-#!/usr/bin/env node
-/**
- * Postinstall script to verify and auto-install Python dependencies
- * Runs: npm install --> postinstall hook
- */
-
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import path from "node:path";
-
-const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-
-const findPythonCmd = () => {
-  const localVenvCandidates =
-    process.platform === "win32"
-      ? [
-          {
-            cmd: path.join(scriptDir, ".venv", "Scripts", "python.exe"),
-            args: [],
-          },
-          { cmd: path.join(scriptDir, ".venv", "Scripts", "python"), args: [] },
-        ]
-      : [
-          { cmd: path.join(scriptDir, ".venv", "bin", "python"), args: [] },
-          { cmd: path.join(scriptDir, ".venv", "bin", "python3"), args: [] },
-        ];
-
-  const systemCandidates =
-    process.platform === "win32"
-      ? [
-          { cmd: "py", args: ["-3.11"] },
-          { cmd: "py", args: ["-3"] },
-          { cmd: "py", args: [] },
-          { cmd: "python3", args: [] },
-          { cmd: "python", args: [] },
-        ]
-      : [
-          { cmd: "python3", args: [] },
-          { cmd: "python", args: [] },
-          { cmd: "py", args: [] },
-        ];
-
-  const candidates = [
-    ...localVenvCandidates.filter((candidate) => existsSync(candidate.cmd)),
-    ...systemCandidates,
-  ];
-
-  for (const candidate of candidates) {
-    try {
-      const result = spawnSync(
-        candidate.cmd,
-        [...candidate.args, "--version"],
-        {
-          encoding: "utf8",
-          stdio: "pipe",
-          timeout: 2000,
-          shell: false,
-        },
-      );
-
-      // Skip if command failed or timed out
-      if (result.status !== 0 || result.error) {
-        continue;
-      }
-
-      const version = `${result.stdout || ""}${result.stderr || ""}`.trim();
-      // Check if Python 3.9+
-      const match = version.match(/Python (\d+)\.(\d+)/);
-      if (match) {
-        const major = parseInt(match[1], 10);
-        const minor = parseInt(match[2], 10);
-        if (major > 3 || (major === 3 && minor >= 9)) {
-          console.log(
-            `✓ Found ${candidate.cmd} ${candidate.args.join(" ")} (${version})`,
-          );
-          return candidate;
-        }
-      }
-    } catch {
-      // Continue to next candidate
-    }
-  }
-
-  return null;
-};
-
-const installBleak = (pythonCmd) => {
-  console.log(`\n📦 Installing bleak Python package...`);
-  try {
-    const result = spawnSync(
-      pythonCmd.cmd,
-      [...pythonCmd.args, "-m", "pip", "install", "bleak"],
-      {
-        encoding: "utf8",
-        stdio: "inherit",
-        timeout: 120000,
-        shell: false,
-      },
-    );
-    if (result.status !== 0) {
-      throw new Error(`pip exited with code ${result.status ?? "unknown"}`);
-    }
-    console.log("✓ bleak installed successfully");
-    return true;
-  } catch (err) {
-    console.warn("⚠ Could not auto-install bleak");
-    return false;
-  }
-};
-
-const main = async () => {
-  console.log("\n🔧 node-thermal-printer postinstall setup\n");
-
-  // Step 1: Find Python
-  console.log("1️⃣  Checking Python installation...");
-  const pythonCmd = findPythonCmd();
-
-  if (!pythonCmd) {
-    console.error("\n❌ ERROR: Python 3.9+ not found!");
-    console.error(
-      "\nPlease install Python from https://www.python.org/downloads/",
-    );
-    console.error("After installing Python, run: npm install again\n");
-    process.exit(1);
-  }
-
-  console.log(`   Using: ${pythonCmd}\n`);
-
-  // Step 2: Install bleak
-  console.log("2️⃣  Checking bleak dependency...");
-  try {
-    const importCheck = spawnSync(
-      pythonCmd.cmd,
-      [...pythonCmd.args, "-c", "import bleak"],
-      {
-        stdio: "pipe",
-        timeout: 2000,
-        shell: false,
-      },
-    );
-    if (importCheck.status !== 0) {
-      throw new Error("bleak import check failed");
-    }
-    console.log("✓ bleak already installed\n");
-  } catch {
-    const installed = installBleak(pythonCmd);
-    if (!installed) {
-      console.error("\n⚠ Manual installation required:");
-      console.error(
-        `   ${pythonCmd.cmd} ${pythonCmd.args.join(" ")} -m pip install bleak\n`,
-      );
-    }
-  }
-
-  // Step 3: Platform-specific notes
-  console.log("3️⃣  Platform-specific requirements:");
-  const platform = process.platform;
-  if (platform === "linux") {
-    console.log("   📋 Linux detected - BLE requires group permissions:");
-    console.log("      sudo usermod -a -G dialout,plugdev $USER");
-    console.log("      (Log out and back in for changes to take effect)\n");
-  } else if (platform === "darwin") {
-    console.log("   📋 macOS detected - Ensure Bluetooth is enabled\n");
-  } else if (platform === "win32") {
-    console.log(
-      "   📋 Windows detected - Ensure Bluetooth drivers are installed\n",
-    );
-  }
-
-  console.log("✅ Setup complete! You can now use node-thermal-printer-js\n");
-};
-
-main().catch((err) => {
-  console.error("Error during setup:", err.message);
-  process.exit(1);
-});