BlueGit

timfa posprint

Files

posprint / docs / POSPRINT-URL.md

POSPRINT-URL.md

POSPRINT-URL.md 4.9 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&origin=shop.example.com
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 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=<hostname> (e.g. shop.example.com or https://shop.example.com/checkout).

First visit from that originLater visits
posprint shows Trust this site?If trusted, prints without asking
Trust and print stores the hostname and continuesRevoke 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" "<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 (after the user trusts this site once):
$auto = posprint_url($pos, [
    'noconfirm' => true,
    'origin' => 'https://shop.example.com',
]);
// <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,
  origin: location.hostname, // or 'shop.example.com'
});

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,
    origin: location.origin,
  });
  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&origin=shop.example.com
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 domain trust; see below) |
28| `origin=` | Hostname of the calling site (required with `noconfirm`) |
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 trusted domains
35
36The OS protocol handler only receives the URL string — not the browser Referer. Callers that want silent print must pass **`origin=<hostname>`** (e.g. `shop.example.com` or `https://shop.example.com/checkout`).
37
38| First visit from that origin | Later visits |
39|------------------------------|--------------|
40| posprint shows **Trust this site?** | If trusted, prints without asking |
41| **Trust and print** stores the hostname and continues | Revoke under **Settings → Trusted sites** |
42
43Without `origin`, `noconfirm=1` is rejected with an error. Without `noconfirm`, behaviour is unchanged (interactive print dialog).
44
45---
46
47## Size limits
48
49Cross-platform bottleneck is usually the **Windows command line (~8191 characters)** for `"posprint.exe" "<url>"`.
50
51| Guidance | Size |
52|----------|------|
53| Soft warning (`posprint link`) | ~7000 characters URL length |
54| Practical `.pos` JSON | ~3–6 KB uncompressed (often more if it compresses well) |
55
56Prefer short templates + remote `@image https://…` over embedding image bytes in the JSON.
57
58---
59
60## Create a URL
61
62### CLI
63
64```bash
65posprint link receipt.pos
66```
67
68Prints one `posprint://…` line. Warns if the URL is longer than ~7000 characters.
69
70### Libraries
71
72| Runtime | Path |
73|---------|------|
74| PHP | [`lib/php/posprint_url.php`](../lib/php/posprint_url.php) |
75| Node.js | [`lib/node/posprint_url.js`](../lib/node/posprint_url.js) |
76| Browser | [`lib/browser/posprint_url.js`](../lib/browser/posprint_url.js) |
77
78All three use the same encoding: **UTF-8 JSON → raw deflate (RFC 1951) → base64url (no padding)**.
79
80#### PHP
81
82```php
83require 'lib/php/posprint_url.php';
84
85$url = posprint_url([
86 'version' => 1,
87 'metadata' => ['page_width_mm' => 53, 'chars_per_line' => 32],
88 'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n",
89]);
90// Auto-print (after the user trusts this site once):
91$auto = posprint_url($pos, [
92 'noconfirm' => true,
93 'origin' => 'https://shop.example.com',
94]);
95// <a href="<?= htmlspecialchars($url) ?>">Print</a>
96```
97
98#### Node.js
99
100```js
101const { posprintUrl } = require('./lib/node/posprint_url');
102
103const url = posprintUrl({
104 version: 1,
105 metadata: { page_width_mm: 53, chars_per_line: 32 },
106 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
107});
108
109const auto = posprintUrl(pos, {
110 noconfirm: true,
111 origin: location.hostname, // or 'shop.example.com'
112});
113```
114
115#### Browser
116
117```html
118<script type="module">
119 import { posprintUrl } from './lib/browser/posprint_url.js';
120 const url = await posprintUrl({
121 version: 1,
122 metadata: { page_width_mm: 53 },
123 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
124 });
125 const auto = await posprintUrl(pos, {
126 noconfirm: true,
127 origin: location.origin,
128 });
129 location.href = auto;
130</script>
131```
132
133`CompressionStream('deflate-raw')` is required (modern Chromium / Firefox / Safari).
134
135---
136
137## Protocol registration
138
139| Platform | How |
140|----------|-----|
141| **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"<exe>" "%1"` |
142| **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` |
143
144After a Linux package install, if links do not open:
145
146```bash
147xdg-mime default posprint-url.desktop x-scheme-handler/posprint
148```
149
150Run the GUI once (or any `posprint` launch) on Windows so the registry key exists.
151
152---
153
154## Example template body
155
156```markdown
157@barcode RASTER CODE128 ${data}
158Hello from posprint://
159@cut
160```
161
162Corresponding minimal `.pos` JSON:
163
164```json
165{
166 "version": 1,
167 "metadata": {
168 "title": "URL demo",
169 "page_width_mm": 53,
170 "chars_per_line": 32
171 },
172 "body": "@barcode RASTER CODE128 ${data}\nHello from posprint://\n@cut\n"
173}
174```