# Siraya Receipt Printing Agent v3

Production-grade local print agent for [Siraya POS](../siraya-pos). Runs as a Windows Service with an Electron desktop manager.

## Features (v3)

- **Single-folder deployment** — copy `dist/agent/` to register PC, run `SirayaPrinter.exe`
- **Electron desktop manager** — service control, printers, history, logs, settings, templates
- **Multi-template receipt engine** — Standard, KOT, Customer Copy, Delivery, Invoice, Packing
- **Durable print queue** with WAL, payload hash dedupe, job retention
- **Settings API** — `GET/PUT /settings`, port conflict detection, API key pairing
- **Security** — optional Bearer auth, rate limiting, request signing support
- **Auto-update** — Electron updater + service version rollback hooks

## Quick start (development)

```bash
cp .env.example .env
npm install
npm start
```

Open `http://127.0.0.1:5000` or run the desktop app:

```bash
npm run desktop:install
npm run desktop:start
```

## Production install

| Platform | Build | Copy to register PC | Run |
|----------|-------|---------------------|-----|
| **Windows** | `npm run build:agent` | `dist/agent/` | `SirayaPrinter.exe` |
| **Linux** | `npm run build:agent:linux` | `dist/agent-linux/` | `./Install.sh` then `SirayaPrinter.AppImage` |

### Windows — SirayaPrinter.exe

1. Build the agent package (Windows dev machine):

```powershell
npm install
npm run build:agent
```

2. Copy **`dist/agent/`** to the register PC (USB or zip).
3. Double-click **`SirayaPrinter.exe`** — first-run wizard installs the Windows Service (one UAC prompt).
4. Use the desktop app to select printer and test print.

### Legacy: USB folder + Install.cmd

Still supported via `npm run build:release` → `dist/release/Install.cmd`.

### Linux — SirayaPrinter.AppImage

1. On Ubuntu 22.04+ amd64:

```bash
npm install
npm run build:agent:linux
```

2. Copy **`dist/agent-linux/`** to the register PC.
3. Run **`./Install.sh`** once (installs CUPS, systemd service, opens setup UI).
4. Use **`SirayaPrinter.AppImage`** daily (same UI as Windows desktop app).

See [installer/linux/START_HERE.txt](installer/linux/START_HERE.txt) and [docs/USAGE.md](docs/USAGE.md).

## API summary

| Endpoint | Purpose |
|----------|---------|
| `GET /health` | Agent health + queue stats |
| `GET /settings` | Public settings |
| `PUT /settings` | Update port, CORS, auth |
| `POST /v1/print/jobs` | Submit print job (POS) |
| `GET /print/history` | Job history for UI |
| `GET /api/templates` | List receipt templates |

## POS configuration

```env
NEXT_PUBLIC_PRINT_SERVICE_URL=http://127.0.0.1:5000
NEXT_PUBLIC_PRINT_API_KEY=<from Siraya Printer Settings tab>
```

Pair the API key once per register from the desktop app **Settings** tab.

## Data directories

| Path | Contents |
|------|----------|
| `%ProgramData%\Siraya\Printer` | settings, templates, queue, logs, secrets |
| `%ProgramFiles%\Siraya\Printer` | service binaries |

See [docs/USAGE.md](docs/USAGE.md) and [docs/QA-PILOT-CHECKLIST.md](docs/QA-PILOT-CHECKLIST.md).
