papermint 0.3.0

High-performance, type-safe thermal receipt printing for Rust, Node.js & Mobile
Documentation
# 🌿 `papermintd` HTTP REST API Specification

`papermintd` is a lightweight native HTTP microservice daemon built on **Tokio** and **Axum**. It allows web applications, mobile devices, local Electron POS systems, and microservices to print receipts, check real-time sensor status, and trigger cash drawers via standard JSON HTTP requests.

---

## 1. Running the Daemon

Launch the daemon locally:

```bash
# Run with default port (8080)
cargo run --package papermint-daemon

# Run on a custom port and host
PORT=9101 HOST=0.0.0.0 cargo run --package papermint-daemon
```

Output:
```text
🌿 papermintd daemon listening on http://127.0.0.1:8080
```

---

## 2. API Endpoints

### 2.1 Health Check: `GET /health`

Returns daemon health and uptime.

* **Request**: `GET /health`
* **Response (`200 OK`)**:
  ```json
  {
    "status": "ok",
    "version": "0.1.0",
    "uptime_secs": 42
  }
  ```

---

### 2.2 Enumerate Devices: `GET /api/devices`

Discovers connected USB Class 7 printers and available serial/COM ports.

* **Request**: `GET /api/devices`
* **Response (`200 OK`)**:
  ```json
  {
    "serial_ports": ["/dev/ttyUSB0", "/dev/ttyS0"],
    "usb_printers": [
      {
        "vendor_id": 1208,
        "product_id": 514,
        "serial_number": "12345678",
        "manufacturer": "EPSON",
        "product_name": "TM-T20III"
      }
    ]
  }
  ```

---

### 2.3 Print Receipt: `POST /api/print`

Prints a structured JSON ticket or raw binary wire bytes to a target printer.

#### Targets:
* **TCP**: `{"type": "tcp", "address": "192.168.1.200:9100"}`
* **USB**: `{"type": "usb", "vendor_id": 1208, "product_id": 514}`
* **Serial**: `{"type": "serial", "port": "/dev/ttyUSB0", "baud": 115200}`
* **Mock**: `{"type": "mock"}` (Returns simulated receipt preview in ASCII)

#### Dialects:
* `"escpos"` (Epson, Bixolon, Citizen, Xprinter)
* `"star"` (StarPRNT TSP100, TSP650II, mC-Print)

#### Example 1: Printing a Structured Restaurant Ticket

```bash
curl -X POST http://localhost:8080/api/print \
  -H "Content-Type: application/json" \
  -d '{
    "target": {"type": "mock"},
    "dialect": "escpos",
    "paper_width": "80mm",
    "ticket": {
      "title": "MINT BISTRO",
      "subtitle": "Table #4 - Order #1042",
      "address": "123 Market St, San Francisco",
      "metadata": [
        {"label": "Server", "value": "Luffy"},
        {"label": "Time", "value": "17:30"}
      ],
      "items": [
        {"qty": "2", "description": "Smashburger", "price": "$9.50", "total": "$19.00"},
        {"qty": "1", "description": "Truffle Fries", "price": "$5.00", "total": "$5.00"},
        {"qty": "2", "description": "Mint Iced Tea", "price": "$3.50", "total": "$7.00"}
      ],
      "totals": [
        {"label": "Subtotal", "value": "$31.00"},
        {"label": "Tax (8.5%)", "value": "$2.64"},
        {"label": "TOTAL", "value": "$33.64"}
      ],
      "qr": "https://mintbistro.com/pay/1042",
      "barcode": "10423364",
      "footer": "Thank you! Please visit us again.",
      "cut_mode": "full",
      "open_drawer": true,
      "beep": 1
    }
  }'
```

* **Response (`200 OK`)**:
  ```json
  {
    "success": true,
    "bytes_sent": 384,
    "mock_preview": "      MINT BISTRO      \nTable #4 - Order #1042\n..."
  }
  ```

#### Example 2: Sending Raw Wire Bytes

```bash
curl -X POST http://localhost:8080/api/print \
  -H "Content-Type: application/json" \
  -d '{
    "target": {"type": "tcp", "address": "192.168.1.200:9100"},
    "dialect": "escpos",
    "raw_bytes": [27, 64, 72, 101, 108, 108, 111, 10, 29, 86, 0]
  }'
```

---

### 2.4 Query Hardware Sensor Telemetry: `POST /api/status`

Queries real-time printer sensors (paper roll, cover open, drawer state, head overheat, and cutter jam).

* **Request**:
  ```bash
  curl -X POST http://localhost:8080/api/status \
    -H "Content-Type: application/json" \
    -d '{
      "target": {"type": "tcp", "address": "192.168.1.200:9100"},
      "dialect": "escpos"
    }'
  ```

* **Response (`200 OK`)**:
  ```json
  {
    "is_online": true,
    "is_ready": true,
    "paper": "Adequate",
    "cover": "Closed",
    "drawer": "Closed",
    "cutter_error": false,
    "head_overheated": false
  }
  ```

---

### 2.5 Trigger Cash Drawer: `POST /api/drawer`

Sends an electrical solenoid kick pulse to open the cash drawer.

* **Request**:
  ```bash
  curl -X POST http://localhost:8080/api/drawer \
    -H "Content-Type: application/json" \
    -d '{
      "target": {"type": "tcp", "address": "192.168.1.200:9100"},
      "dialect": "escpos",
      "pin": 2
    }'
  ```

* **Response (`200 OK`)**:
  ```json
  {
    "success": true,
    "message": "Cash drawer kick command sent to Pin 2"
  }
  ```

---

## 3. Cloud & Remote WebSocket Printing Gateway

In addition to serving local HTTP REST requests, `papermintd` can establish an **outbound persistent WebSocket connection** to your cloud API (e.g. Node.js, Hono, Go, or Python). This enables central cloud dashboards and mobile owner apps to print directly to physical in-store printers without port forwarding or dynamic DNS.

### 3.1 Gateway CLI Arguments & Environment Variables

```bash
papermintd \
  --gateway "wss://pos-api.yourdomain.com/ws/printer/shop_042" \
  --token "sk_live_secret_token" \
  --shop-id "shop_042" \
  --printer "tcp://192.168.1.200:9100"
```

| Flag | Env Var | Default | Description |
| :--- | :--- | :--- | :--- |
| `--gateway <URL>` | `GATEWAY_URL` | None | Outbound WebSocket server URL (`ws://` or `wss://`) |
| `--token <TOKEN>` | `GATEWAY_TOKEN` | None | Authentication bearer token sent in registration |
| `--shop-id <ID>` | `SHOP_ID` | `default` | Shop or branch identifier |
| `--printer <TARGET>` | `DEFAULT_PRINTER` | `mock` | Default printer target (`tcp://host:port`, `usb:vid:pid`, `serial:port:baud`, `mock`) |

### 3.2 Gateway Resilience
- **Exponential Backoff**: If network or cloud connection drops, `papermintd` automatically reconnects (1s, 2s, 4s, ... up to 30s).
- **Dual Mode**: `papermintd` simultaneously maintains the outbound WebSocket connection while serving local HTTP REST requests on `http://127.0.0.1:8080`.

### 3.3 Wire Protocol Events

1. **Registration (Daemon $\rightarrow$ Cloud)**:
   ```json
   {
     "event": "register",
     "version": "0.2.3",
     "shop_id": "shop_042",
     "token": "sk_live_secret_token",
     "capabilities": ["escpos", "star", "tspl", "zpl", "raw"]
   }
   ```
2. **Print Job (Cloud $\rightarrow$ Daemon)**:
   ```json
   {
     "event": "print_job",
     "job_id": "job_9981",
     "dialect": "escpos",
     "ticket": { "title": "MINT BISTRO", ... },
     "target": "tcp://192.168.1.200:9100"
   }
   ```
3. **Execution Acknowledgement (Daemon $\rightarrow$ Cloud)**:
   ```json
   {
     "event": "ack",
     "job_id": "job_9981",
     "success": true,
     "bytes_sent": 342,
     "error": null,
     "mock_preview": null
   }
   ```
4. **Heartbeat & Status (`ping` / `pong` / `status_query`)**:
   Enables cloud dashboards to monitor real-time printer paper levels, cover state, and drawer status.