# 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`).

### First launch — get past the OS security warning (one time)

The downloaded agent isn't code-signed yet, so the OS warns the first time:

- **macOS** ("Apple could not verify… free of malware"): in **Finder**,
  **right-click** the `q-serve-print-macos` file → **Open** → **Open**. (Or
  **System Settings → Privacy & Security**, scroll down, click **Open Anyway**.)
  If it still refuses, open **Terminal** and run
  `xattr -dr com.apple.quarantine ~/Downloads/qserve-print-agent-mac*/q-serve-print-macos`
  then run it again.
- **Windows** (SmartScreen "Windows protected your PC"): click **More info** →
  **Run anyway**.

This is a one-time approval per download.

### Runs silently in the background (Windows)

On Windows the agent now backgrounds itself automatically:

1. Run the `.exe` and paste your token on first run.
2. It then **relaunches hidden** (no window) and prints *"running in the
   background… you can close this window"* — close it; printing keeps going.
3. It also registers itself to **auto-start hidden at every login** (a
   `QservePrintAgent.vbs` in your Startup folder). Nothing else to set up.

Only one agent ever runs even if you double-click the `.exe` again (a
single-instance lock prevents duplicate prints). To stop auto-start, delete
`QservePrintAgent.vbs` from the Startup folder (Win+R → `shell:startup`). The
bundled `run-hidden.vbs` still works as a manual hidden launcher if you prefer.

(On Mac/Linux, run it under `nohup … &`, `screen`/`tmux`, or as a `launchd`/
`systemd` service to keep it running in the background.)

---

## 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.
