# 🌿 `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"
```
| `--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.