# 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 ``` | 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 as soon as a printer is ready (no Print click) | **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`) Add `&noconfirm=1` to print without waiting for the Print button. Consent to open posprint is handled by the **browser** (protocol launch prompt), not by a second trust dialog in the app. 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. Legacy `&referrer=…` in old URLs is ignored. ### 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 (browser protocol prompt is the consent gate): $auto = posprint_url($pos, [ 'noconfirm' => true, ]); // 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, }); ``` #### 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` | | **macOS (`Posprint.app`)** | `Info.plist` registers `CFBundleURLSchemes = ["posprint"]` with LaunchServices and forwards `open location` AppleEvents to `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" } ```