# escpos-proxy

Minimal ESC/POS print proxy written as a Node.js ESM app.

It listens for incoming ESC/POS print jobs on a TCP port, **forwards the raw bytes straight to a target printer**, and **automatically parses and renders every job** to disk as both a structured `.log` file and a high-fidelity `.png` receipt image.

A *job* is delimited by either:
- a **cut command** ("bladecut") in the stream — ESC/POS `GS V` = `0x1D 0x56`, or
- a **connection drop** (the client closes / resets the connection).

## Features

- **Transparent Proxying**: Forwards bytes losslessly to a physical ESC/POS printer.
- **Advanced Parsing**: Decomposes the raw byte stream into ESC/POS commands, tracking formatting states (bold, underline, double-height, alignment).
- **Native PNG Rendering**: Automatically generates a 1-bit style grayscale PNG image of the exact receipt that was printed.
- **Embedded Graphics**: Supports rendering custom embedded `IMAGE` payloads and generates actual QR codes from `ESC Z` (2D symbol setup) commands.

## Usage

Configuration lives in `.env` (copy `.env.example` to `.env` and edit). It is loaded via [dotenv](https://www.npmjs.com/package/dotenv).

```bash
cp .env.example .env   # first time only
npm install
npm start
```

### Environment variables (`.env`)

| Variable         | Default          | Description                          |
|------------------|------------------|--------------------------------------|
| `LISTEN_HOST`    | `0.0.0.0`        | Host the proxy listens on            |
| `LISTEN_PORT`    | `9100`           | Port the proxy listens on            |
| `TARGET_HOST`    | `10.10.10.24`    | Printer to forward raw bytes to      |
| `TARGET_PORT`    | `9100`           | Printer port                         |
| `LOG_DIR`        | `./logs`         | Directory for job logs               |
| `CUT_PREFIX`     | `1d 56`          | ESC/POS cut command prefix, hex space-separated (`GS V`) |
| `KEEP_AFTER_CUT` | `true`           | Treat bytes after a cut as the next job |

Real environment variables always take precedence over `.env`.

## Logs and Output

For each completed job, two files are written into `LOG_DIR`:

- `job-<timestamp>-<seq>.log` — The parsed, human-readable token stream containing command opcodes, parameters, and decoded text.
- `job-<timestamp>-<seq>.png` — A rendered visual receipt using the exact fonts (Font A / Font B) and layout applied by the software.

## Testing

The `test-send.mjs` script sends a sample ESC/POS receipt (with a `GS V` cut) to the listener so you can verify logging, forwarding, and PNG generation:

```bash
# terminal 1
npm start

# terminal 2
npm run test:send
```

## Architecture

The source code resides in the `src/` directory:
- `server.js` — The core TCP proxy server and chunk delimiter.
- `parser.js` — The ESC/POS grammar parser.
- `renderer.js` — The PNG generator leveraging the `sharp` and `qrcode` libraries to draw the parsed receipt instructions to an image buffer.
- `font-12x24.js` / `font-9x16.js` — Exported native JS arrays containing the dot-matrix character maps used by the renderer.