# Qserve Print Agent

A small helper that runs on a till and prints Qserve receipts to your network
printer. One agent per store; it pulls that store's print jobs from the API and
prints each to its printer (cross-platform raster over TCP — Windows, Linux,
Mac; Arabic + English).

---

## For tenants (setup)

1. In Qserve open **Printers**, add your printer by its **IP address**, make it
   the **Default**.
2. Tap the **🔑 key** button → **Print agent** → **Copy** your store token
   (or **Download the print agent** straight from there).
3. Run the downloaded agent. On first run it asks for the token — **paste it**.
   It autodetects Chrome, writes its config, and starts printing.

That's it. Keep one agent running per store.

> Chrome (or Edge) must be installed on the till — the agent uses it to render
> receipts. Most machines already have it; on a bare Linux till install
> Chromium (`apt install chromium` / `chromium-browser`).

---

## For the vendor (build the downloads)

The agent authenticates with a **per-store token** (no shared secret). Config
lives in `.env`, created by the first-run wizard (`src/setup.ts`).

### Build standalone executables (no Node needed on the till)

```
npm install
npm run package        # tsc + pkg → bin/ for win-x64, linux-x64, macos-x64
```

`pkg` bundles Node + the app into a single executable per OS (see the `pkg`
block in `package.json`). Chromium is **not** bundled — the agent finds the
installed Chrome/Edge, keeping the download small.

Zip each binary (optionally with this README) and publish them where the
landing page links expect them:

```
/downloads/qserve-print-agent-windows.zip
/downloads/qserve-print-agent-linux.zip
/downloads/qserve-print-agent-mac.zip
```

> Build each target on (or for) its OS for best results. Code-sign the Windows
> and macOS binaries to avoid SmartScreen/Gatekeeper warnings.

### Run from source (dev / fallback, needs Node)

```
npm install
npm run build:agent
node dist/start.js     # first run prompts for the token, then prints
```

### Config keys (`.env`)

| Key | Meaning |
|-----|---------|
| `QSERVE_AGENT_TOKEN` | per-store token (from Qserve → Printers → 🔑) |
| `QSERVE_BASE_URL` | API base, e.g. `https://api.qserve.qa/qserve` |
| `PRINT_WIDTH_DOTS` | `512` TM-T88/80mm@180dpi · `576` 80mm@203dpi · `384` 58mm |
| `chrome_path` | autodetected; set manually if needed |

For an unattended install, set `QSERVE_AGENT_TOKEN` (+ `QSERVE_BASE_URL`) in the
environment before launching — the wizard is skipped.
