BlueGit

timfa posprint

Files

posprint / docs / POSPRINT-URL.md

POSPRINT-URL.md

POSPRINT-URL.md 5.7 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

Without referrer, noconfirm=1 is rejected. Without noconfirm, behaviour is unchanged (interactive print dialog).

Localhost / private IP verification URLs are blocked by default. For local harnesses only, set POSPRINT_ALLOW_LOCAL_REFERRER=1 (see scripts/test-noconfirm/).

---

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
51Without `referrer`, `noconfirm=1` is rejected. Without `noconfirm`, behaviour is unchanged (interactive print dialog).
52
53Localhost / private IP verification URLs are blocked by default. For local harnesses only, set `POSPRINT_ALLOW_LOCAL_REFERRER=1` (see `scripts/test-noconfirm/`).
54
55---
56
57## Size limits
58
59Cross-platform bottleneck is usually the **Windows command line (~8191 characters)** for `"posprint.exe" "<url>"`.
60
61| Guidance | Size |
62|----------|------|
63| Soft warning (`posprint link`) | ~7000 characters URL length |
64| Practical `.pos` JSON | ~3–6 KB uncompressed (often more if it compresses well) |
65
66Prefer short templates + remote `@image https://…` over embedding image bytes in the JSON.
67
68---
69
70## Create a URL
71
72### CLI
73
74```bash
75posprint link receipt.pos
76```
77
78Prints one `posprint://…` line. Warns if the URL is longer than ~7000 characters.
79
80### Libraries
81
82| Runtime | Path |
83|---------|------|
84| PHP | [`lib/php/posprint_url.php`](../lib/php/posprint_url.php) |
85| Node.js | [`lib/node/posprint_url.js`](../lib/node/posprint_url.js) |
86| Browser | [`lib/browser/posprint_url.js`](../lib/browser/posprint_url.js) |
87
88All three use the same encoding: **UTF-8 JSON → raw deflate (RFC 1951) → base64url (no padding)**.
89
90#### PHP
91
92```php
93require 'lib/php/posprint_url.php';
94
95$url = posprint_url([
96 'version' => 1,
97 'metadata' => ['page_width_mm' => 53, 'chars_per_line' => 32],
98 'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n",
99]);
100// Auto-print: site must expose a verify URL that returns HTTP 200 for this code:
101$auto = posprint_url($pos, [
102 'noconfirm' => true,
103 'referrer' => 'https://shop.example.com/bonnen/verify?code=' . urlencode($code),
104]);
105// <a href="<?= htmlspecialchars($url) ?>">Print</a>
106```
107
108#### Node.js
109
110```js
111const { posprintUrl } = require('./lib/node/posprint_url');
112
113const url = posprintUrl({
114 version: 1,
115 metadata: { page_width_mm: 53, chars_per_line: 32 },
116 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
117});
118
119const auto = posprintUrl(pos, {
120 noconfirm: true,
121 referrer: `https://shop.example.com/bonnen/verify?code=${encodeURIComponent(code)}`,
122});
123```
124
125#### Browser
126
127```html
128<script type="module">
129 import { posprintUrl } from './lib/browser/posprint_url.js';
130 const url = await posprintUrl({
131 version: 1,
132 metadata: { page_width_mm: 53 },
133 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
134 });
135 const auto = await posprintUrl(pos, {
136 noconfirm: true,
137 referrer: `https://${location.host}/bonnen/verify?code=${encodeURIComponent(code)}`,
138 });
139 location.href = auto;
140</script>
141```
142
143`CompressionStream('deflate-raw')` is required (modern Chromium / Firefox / Safari).
144
145---
146
147## Protocol registration
148
149| Platform | How |
150|----------|-----|
151| **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"<exe>" "%1"` |
152| **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` |
153
154After a Linux package install, if links do not open:
155
156```bash
157xdg-mime default posprint-url.desktop x-scheme-handler/posprint
158```
159
160Run the GUI once (or any `posprint` launch) on Windows so the registry key exists.
161
162---
163
164## Example template body
165
166```markdown
167@barcode RASTER CODE128 ${data}
168Hello from posprint://
169@cut
170```
171
172Corresponding minimal `.pos` JSON:
173
174```json
175{
176 "version": 1,
177 "metadata": {
178 "title": "URL demo",
179 "page_width_mm": 53,
180 "chars_per_line": 32
181 },
182 "body": "@barcode RASTER CODE128 ${data}\nHello from posprint://\n@cut\n"
183}
184```