# posprint:// URLs Magnet-style deep links that open **posprint’s print dialog** with an embedded `.pos` document. Useful from websites where posprint is installed on the client, not on the server. Full reference: create URLs from PHP, Node.js, or browser JavaScript using the helpers in [`lib/`](../lib/). --- ## Format ``` posprint://print?v=1&d= ``` Optional auto-print: ``` posprint://print?v=1&d=…&noconfirm=1&referrer=website.com%2Fbonnen%2Fverify%3Fcode%3D84923 ``` | Part | Meaning | |------|---------| | `posprint://` | Custom protocol (registered on install / first run) | | `print` | Open the print-only dialog (same UX as `posprint --print`) | | `v=1` | URL payload version | | `d=` | Compressed `.pos` file (JSON with `version`, `metadata`, `body`) | | `noconfirm=1` | Start printing immediately after referrer verification (+ domain trust) | | `referrer=` | **Percent-encoded** verification URL on the issuer’s domain (see below) | **Template parameters are not in the URL.** With a normal link the user fills `${Name}` / `$[Name]` in the dialog. Prefer templates without unresolved parameters when using `noconfirm`. **Images:** keep logos out of the URL. Use `@image https://…` (or `http://…`) in the template body; posprint downloads them when needed. ### Auto-print (`noconfirm`) and referrer verification The OS protocol handler only receives the URL string — not the browser Referer. A site that wants silent print must prove control of its domain: 1. Embed `&noconfirm=1&referrer=`. 2. Example referrer value (before encoding): `website.com/bonnen/verify?code=84923` (scheme optional → treated as `https://…`; or pass a full `https://…` URL). 3. posprint **GETs** that URL with **no redirects**. 4. **HTTP 200** → verification OK; trust host = hostname of the referrer URL (`website.com`). 5. **Any other status** (typically 4xx) → print refused. 6. Code format and how long it stays valid are **entirely up to the website**. | First successful verify from that host | Later verified visits | |----------------------------------------|------------------------| | posprint shows **Trust this site?** | If trusted, prints without asking | | **Trust and print** stores the hostname | Revoke under **Settings → Trusted sites** | After a successful print, posprint remembers that printer. On the next `noconfirm` (and in the interactive dialog), it selects that printer again **if it is still connected**; otherwise it keeps the usual first/default selection. Without `referrer`, `noconfirm=1` is rejected. Without `noconfirm`, behaviour is unchanged (interactive print dialog). Localhost / loopback verification URLs are allowed. Other private LAN addresses (e.g. `192.168.x.x`) are blocked. ### Browser “Open posprint?” prompt Browsers (Chrome / Edge) always ask before launching a custom protocol. That dialog is **not** controlled by posprint. - Typing or pasting `posprint://…` in the address bar usually offers **no** “always allow” option (no site origin). - A real click from an **https://** page can show “Always allow this site to open…” once the browser remembers the choice for that origin. - `http://127.0.0.1` / localhost test pages often never get a persistent allow checkbox. No extra posprint registry or config is required for protocol registration beyond what install / first run already does. --- ## Size limits Cross-platform bottleneck is usually the **Windows command line (~8191 characters)** for `"posprint.exe" ""`. | Guidance | Size | |----------|------| | Soft warning (`posprint link`) | ~7000 characters URL length | | Practical `.pos` JSON | ~3–6 KB uncompressed (often more if it compresses well) | Prefer short templates + remote `@image https://…` over embedding image bytes in the JSON. --- ## Create a URL ### CLI ```bash posprint link receipt.pos ``` Prints one `posprint://…` line. Warns if the URL is longer than ~7000 characters. ### Libraries | Runtime | Path | |---------|------| | PHP | [`lib/php/posprint_url.php`](../lib/php/posprint_url.php) | | Node.js | [`lib/node/posprint_url.js`](../lib/node/posprint_url.js) | | Browser | [`lib/browser/posprint_url.js`](../lib/browser/posprint_url.js) | All three use the same encoding: **UTF-8 JSON → raw deflate (RFC 1951) → base64url (no padding)**. #### PHP ```php require 'lib/php/posprint_url.php'; $url = posprint_url([ 'version' => 1, 'metadata' => ['page_width_mm' => 53, 'chars_per_line' => 32], 'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n", ]); // Auto-print: site must expose a verify URL that returns HTTP 200 for this code: $auto = posprint_url($pos, [ 'noconfirm' => true, 'referrer' => 'https://shop.example.com/bonnen/verify?code=' . urlencode($code), ]); // Print ``` #### Node.js ```js const { posprintUrl } = require('./lib/node/posprint_url'); const url = posprintUrl({ version: 1, metadata: { page_width_mm: 53, chars_per_line: 32 }, body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n', }); const auto = posprintUrl(pos, { noconfirm: true, referrer: `https://shop.example.com/bonnen/verify?code=${encodeURIComponent(code)}`, }); ``` #### Browser ```html ``` `CompressionStream('deflate-raw')` is required (modern Chromium / Firefox / Safari). --- ## Protocol registration | Platform | How | |----------|-----| | **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"" "%1"` | | **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` | After a Linux package install, if links do not open: ```bash xdg-mime default posprint-url.desktop x-scheme-handler/posprint ``` Run the GUI once (or any `posprint` launch) on Windows so the registry key exists. --- ## Example template body ```markdown @barcode RASTER CODE128 ${data} Hello from posprint:// @cut ``` Corresponding minimal `.pos` JSON: ```json { "version": 1, "metadata": { "title": "URL demo", "page_width_mm": 53, "chars_per_line": 32 }, "body": "@barcode RASTER CODE128 ${data}\nHello from posprint://\n@cut\n" } ```