= labelprint

Unified UI for printing labels/receipts:

* Native ZPL printing to a Datamax-ONeil thermal barcode printer
* A proxy/switcher in front of three https://github.com/DL6ER/brother_ql_web[brother_ql_web] instances, one per Brother QL printer
* ESC/POS receipt printing to an Epson TM-T20II

== Routes

* `/` -- home page, links to everything below
* `/upload`, `POST /upload` -- upload a PDF/ZPL file and print it (Datamax)
* `POST /shipping/zpl` -- print raw ZPL text (see "API usage" below)
* `/test-print` -- print the bundled Datamax test label
* `/epson` -- receipt printing UI (title/body/QR template, or raw ESC/POS mnemonic notation)
* `POST /epson/print` -- print a title/body/QR receipt
* `POST /epson/raw` -- print already-formatted ESC/POS mnemonic notation (see "API usage" below)
* `POST /epson/test-print` -- print an Epson capability test page (text sizes, barcode, QR, raster image)
* `/labels` -- shared repository of saved ZPL labels / ESC-POS receipts (list, edit, preview, print, delete)
* `/brother` -- list of Brother QL printers
* `/brother/<printer>/*` -- proxied to that printer's brother_ql_web instance (UI and API alike)

== API usage (e.g. from Gitea Actions)

`POST /shipping/zpl` and `POST /epson/raw` are plain, unauthenticated form-POST endpoints -- no session/login needed, and printing without a `save_as`/`commit` param just prints (nothing gets kept in the label repository). That makes labelprint usable as a "dumb" print API for other automation: it doesn't need to know anything about the caller, and the caller doesn't need any labelprint-specific client, just an HTTP form POST.

Example: `randy/home-gitops` has a workflow (`.gitea/workflows/print-issues.yaml` + `scripts/print_issues.rb`) that fetches its own open issues via the Gitea API and prints a summary on the Epson receipt printer -- the Gitea-specific logic (fetching, formatting) lives entirely in that script, not here:

[source,ruby]
----
require 'net/http'

res = Net::HTTP.post_form(
  URI('http://rpi-printserver.hv.priesol.net/epson/raw'),
  'content' => "ESC E 0x01\nHello from CI\nESC E 0x00\nLF"
)
----

`content` uses labelprint's mnemonic ESC/POS notation: `ESC`/`GS`/`FS`/`LF`/`CR`/`HT`/`NUL` as command names, `0xNN` as a raw byte, anything else as literal text (CP852-encoded) -- see the `/epson` page for the full reference and worked examples (alignment, bold, barcodes). `POST /shipping/zpl` works the same way but with a `zpl` form field taking plain ZPL instead.

== Running

[source,shell]
----
bundle install
bundle exec ruby app.rb
----

Requires `config.json` (see printer definitions inside) and a `.session_secret` file (random string, not committed).

== Deployment

Runs as `sinatra.service` (systemd) on `rpi-printserver.hv.priesol.net`, under RVM (`rvm default do bundle exec ruby app.rb` -- always uses whatever ruby is currently the RVM default, no manual bumping needed).

`.gitea/workflows/deploy.yaml` deploys on every push to `main`: SSH into `rpi-printserver.hv.priesol.net`, `git pull`, `bundle install`, restart the service.

== Dependency updates

`.gitea/workflows/renovate.yaml` runs Renovate on a schedule (Monday 06:00 Europe/Bratislava, or manually) to open PRs for outdated gems and GitHub Actions. See the "Dependency Dashboard" issue for current status.