# 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&origin=shop.example.com ``` | 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 domain trust; see below) | | `origin=` | Hostname of the calling site (required with `noconfirm`) | **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 trusted domains The OS protocol handler only receives the URL string — not the browser Referer. Callers that want silent print must pass **`origin=`** (e.g. `shop.example.com` or `https://shop.example.com/checkout`). | First visit from that origin | Later visits | |------------------------------|--------------| | posprint shows **Trust this site?** | If trusted, prints without asking | | **Trust and print** stores the hostname and continues | Revoke under **Settings → Trusted sites** | Without `origin`, `noconfirm=1` is rejected with an error. Without `noconfirm`, behaviour is unchanged (interactive print dialog). --- ## 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 (after the user trusts this site once): $auto = posprint_url($pos, [ 'noconfirm' => true, 'origin' => 'https://shop.example.com', ]); // 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, origin: location.hostname, // or 'shop.example.com' }); ``` #### 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" } ```