BlueGit

timfa posprint

Files

posprint / docs / POSPRINT-URL.md

POSPRINT-URL.md

POSPRINT-URL.md 6.5 KiB Download Raw

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/.

---

Format

posprint://print?v=1&d=<BASE64URL(raw_deflate(utf8(.pos JSON)))>

Optional auto-print:

posprint://print?v=1&d=…&noconfirm=1&referrer=website.com%2Fbonnen%2Fverify%3Fcode%3D84923
PartMeaning
posprint://Custom protocol (registered on install / first run)
printOpen the print-only dialog (same UX as posprint --print)
v=1URL payload version
d=Compressed .pos file (JSON with version, metadata, body)
noconfirm=1Start 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=<URL-encoded verification URL>. 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 hostLater verified visits
posprint shows Trust this site?If trusted, prints without asking
Trust and print stores the hostnameRevoke 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" "<url>".

GuidanceSize
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

posprint link receipt.pos

Prints one posprint://… line. Warns if the URL is longer than ~7000 characters.

Libraries

RuntimePath
PHPlib/php/posprint_url.php
Node.jslib/node/posprint_url.js
Browserlib/browser/posprint_url.js

All three use the same encoding: UTF-8 JSON → raw deflate (RFC 1951) → base64url (no padding).

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),
]);
// <a href="<?= htmlspecialchars($url) ?>">Print</a>

Node.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

<script type="module">
  import { posprintUrl } from './lib/browser/posprint_url.js';
  const url = await posprintUrl({
    version: 1,
    metadata: { page_width_mm: 53 },
    body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
  });
  const auto = await posprintUrl(pos, {
    noconfirm: true,
    referrer: `https://${location.host}/bonnen/verify?code=${encodeURIComponent(code)}`,
  });
  location.href = auto;
</script>

CompressionStream('deflate-raw') is required (modern Chromium / Firefox / Safari).

---

Protocol registration

PlatformHow
WindowsOn each launch, posprint registers HKCU\Software\Classes\posprint → "<exe>" "%1"
Linux (deb/Arch)Ships posprint-url.desktop with MimeType=x-scheme-handler/posprint

After a Linux package install, if links do not open:

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

@barcode RASTER CODE128 ${data}
Hello from posprint://
@cut

Corresponding minimal .pos 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"
}
Source
1# posprint:// URLs
2
3Magnet-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.
4
5Full reference: create URLs from PHP, Node.js, or browser JavaScript using the helpers in [`lib/`](../lib/).
6
7---
8
9## Format
10
11```
12posprint://print?v=1&d=<BASE64URL(raw_deflate(utf8(.pos JSON)))>
13```
14
15Optional auto-print:
16
17```
18posprint://print?v=1&d=…&noconfirm=1&referrer=website.com%2Fbonnen%2Fverify%3Fcode%3D84923
19```
20
21| Part | Meaning |
22|------|---------|
23| `posprint://` | Custom protocol (registered on install / first run) |
24| `print` | Open the print-only dialog (same UX as `posprint --print`) |
25| `v=1` | URL payload version |
26| `d=` | Compressed `.pos` file (JSON with `version`, `metadata`, `body`) |
27| `noconfirm=1` | Start printing immediately after referrer verification (+ domain trust) |
28| `referrer=` | **Percent-encoded** verification URL on the issuer’s domain (see below) |
29
30**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`.
31
32**Images:** keep logos out of the URL. Use `@image https://…` (or `http://…`) in the template body; posprint downloads them when needed.
33
34### Auto-print (`noconfirm`) and referrer verification
35
36The OS protocol handler only receives the URL string — not the browser Referer. A site that wants silent print must prove control of its domain:
37
381. Embed `&noconfirm=1&referrer=<URL-encoded verification URL>`.
392. Example referrer value (before encoding): `website.com/bonnen/verify?code=84923`
40 (scheme optional → treated as `https://…`; or pass a full `https://…` URL).
413. posprint **GETs** that URL with **no redirects**.
424. **HTTP 200** → verification OK; trust host = hostname of the referrer URL (`website.com`).
435. **Any other status** (typically 4xx) → print refused.
446. Code format and how long it stays valid are **entirely up to the website**.
45
46| First successful verify from that host | Later verified visits |
47|----------------------------------------|------------------------|
48| posprint shows **Trust this site?** | If trusted, prints without asking |
49| **Trust and print** stores the hostname | Revoke under **Settings → Trusted sites** |
50
51After 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.
52
53Without `referrer`, `noconfirm=1` is rejected. Without `noconfirm`, behaviour is unchanged (interactive print dialog).
54
55Localhost / loopback verification URLs are allowed. Other private LAN addresses (e.g. `192.168.x.x`) are blocked.
56
57### Browser “Open posprint?” prompt
58
59Browsers (Chrome / Edge) always ask before launching a custom protocol. That dialog is **not** controlled by posprint.
60
61- Typing or pasting `posprint://…` in the address bar usually offers **no** “always allow” option (no site origin).
62- A real click from an **https://** page can show “Always allow this site to open…” once the browser remembers the choice for that origin.
63- `http://127.0.0.1` / localhost test pages often never get a persistent allow checkbox.
64
65No extra posprint registry or config is required for protocol registration beyond what install / first run already does.
66
67---
68
69## Size limits
70
71Cross-platform bottleneck is usually the **Windows command line (~8191 characters)** for `"posprint.exe" "<url>"`.
72
73| Guidance | Size |
74|----------|------|
75| Soft warning (`posprint link`) | ~7000 characters URL length |
76| Practical `.pos` JSON | ~3–6 KB uncompressed (often more if it compresses well) |
77
78Prefer short templates + remote `@image https://…` over embedding image bytes in the JSON.
79
80---
81
82## Create a URL
83
84### CLI
85
86```bash
87posprint link receipt.pos
88```
89
90Prints one `posprint://…` line. Warns if the URL is longer than ~7000 characters.
91
92### Libraries
93
94| Runtime | Path |
95|---------|------|
96| PHP | [`lib/php/posprint_url.php`](../lib/php/posprint_url.php) |
97| Node.js | [`lib/node/posprint_url.js`](../lib/node/posprint_url.js) |
98| Browser | [`lib/browser/posprint_url.js`](../lib/browser/posprint_url.js) |
99
100All three use the same encoding: **UTF-8 JSON → raw deflate (RFC 1951) → base64url (no padding)**.
101
102#### PHP
103
104```php
105require 'lib/php/posprint_url.php';
106
107$url = posprint_url([
108 'version' => 1,
109 'metadata' => ['page_width_mm' => 53, 'chars_per_line' => 32],
110 'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n",
111]);
112// Auto-print: site must expose a verify URL that returns HTTP 200 for this code:
113$auto = posprint_url($pos, [
114 'noconfirm' => true,
115 'referrer' => 'https://shop.example.com/bonnen/verify?code=' . urlencode($code),
116]);
117// <a href="<?= htmlspecialchars($url) ?>">Print</a>
118```
119
120#### Node.js
121
122```js
123const { posprintUrl } = require('./lib/node/posprint_url');
124
125const url = posprintUrl({
126 version: 1,
127 metadata: { page_width_mm: 53, chars_per_line: 32 },
128 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
129});
130
131const auto = posprintUrl(pos, {
132 noconfirm: true,
133 referrer: `https://shop.example.com/bonnen/verify?code=${encodeURIComponent(code)}`,
134});
135```
136
137#### Browser
138
139```html
140<script type="module">
141 import { posprintUrl } from './lib/browser/posprint_url.js';
142 const url = await posprintUrl({
143 version: 1,
144 metadata: { page_width_mm: 53 },
145 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
146 });
147 const auto = await posprintUrl(pos, {
148 noconfirm: true,
149 referrer: `https://${location.host}/bonnen/verify?code=${encodeURIComponent(code)}`,
150 });
151 location.href = auto;
152</script>
153```
154
155`CompressionStream('deflate-raw')` is required (modern Chromium / Firefox / Safari).
156
157---
158
159## Protocol registration
160
161| Platform | How |
162|----------|-----|
163| **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"<exe>" "%1"` |
164| **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` |
165
166After a Linux package install, if links do not open:
167
168```bash
169xdg-mime default posprint-url.desktop x-scheme-handler/posprint
170```
171
172Run the GUI once (or any `posprint` launch) on Windows so the registry key exists.
173
174---
175
176## Example template body
177
178```markdown
179@barcode RASTER CODE128 ${data}
180Hello from posprint://
181@cut
182```
183
184Corresponding minimal `.pos` JSON:
185
186```json
187{
188 "version": 1,
189 "metadata": {
190 "title": "URL demo",
191 "page_width_mm": 53,
192 "chars_per_line": 32
193 },
194 "body": "@barcode RASTER CODE128 ${data}\nHello from posprint://\n@cut\n"
195}
196```