BlueGit

timfa posprint

Files

posprint / docs / POSPRINT-URL.md

POSPRINT-URL.md

POSPRINT-URL.md 5.3 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
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 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" "<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 (browser protocol prompt is the consent gate):
$auto = posprint_url($pos, [
    'noconfirm' => true,
]);
// <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,
});

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,
  });
  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
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:

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
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 as soon as a printer is ready (no Print click) |
28
29**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`.
30
31**Images:** keep logos out of the URL. Use `@image https://…` (or `http://…`) in the template body; posprint downloads them when needed.
32
33### Auto-print (`noconfirm`)
34
35Add `&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.
36
37After 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.
38
39Legacy `&referrer=…` in old URLs is ignored.
40
41### Browser “Open posprint?” prompt
42
43Browsers (Chrome / Edge) always ask before launching a custom protocol. That dialog is **not** controlled by posprint.
44
45- Typing or pasting `posprint://…` in the address bar usually offers **no** “always allow” option (no site origin).
46- A real click from an **https://** page can show “Always allow this site to open…” once the browser remembers the choice for that origin.
47- `http://127.0.0.1` / localhost test pages often never get a persistent allow checkbox.
48
49No extra posprint registry or config is required for protocol registration beyond what install / first run already does.
50
51---
52
53## Size limits
54
55Cross-platform bottleneck is usually the **Windows command line (~8191 characters)** for `"posprint.exe" "<url>"`.
56
57| Guidance | Size |
58|----------|------|
59| Soft warning (`posprint link`) | ~7000 characters URL length |
60| Practical `.pos` JSON | ~3–6 KB uncompressed (often more if it compresses well) |
61
62Prefer short templates + remote `@image https://…` over embedding image bytes in the JSON.
63
64---
65
66## Create a URL
67
68### CLI
69
70```bash
71posprint link receipt.pos
72```
73
74Prints one `posprint://…` line. Warns if the URL is longer than ~7000 characters.
75
76### Libraries
77
78| Runtime | Path |
79|---------|------|
80| PHP | [`lib/php/posprint_url.php`](../lib/php/posprint_url.php) |
81| Node.js | [`lib/node/posprint_url.js`](../lib/node/posprint_url.js) |
82| Browser | [`lib/browser/posprint_url.js`](../lib/browser/posprint_url.js) |
83
84All three use the same encoding: **UTF-8 JSON → raw deflate (RFC 1951) → base64url (no padding)**.
85
86#### PHP
87
88```php
89require 'lib/php/posprint_url.php';
90
91$url = posprint_url([
92 'version' => 1,
93 'metadata' => ['page_width_mm' => 53, 'chars_per_line' => 32],
94 'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n",
95]);
96// Auto-print (browser protocol prompt is the consent gate):
97$auto = posprint_url($pos, [
98 'noconfirm' => true,
99]);
100// <a href="<?= htmlspecialchars($url) ?>">Print</a>
101```
102
103#### Node.js
104
105```js
106const { posprintUrl } = require('./lib/node/posprint_url');
107
108const url = posprintUrl({
109 version: 1,
110 metadata: { page_width_mm: 53, chars_per_line: 32 },
111 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
112});
113
114const auto = posprintUrl(pos, {
115 noconfirm: true,
116});
117```
118
119#### Browser
120
121```html
122<script type="module">
123 import { posprintUrl } from './lib/browser/posprint_url.js';
124 const url = await posprintUrl({
125 version: 1,
126 metadata: { page_width_mm: 53 },
127 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
128 });
129 const auto = await posprintUrl(pos, {
130 noconfirm: true,
131 });
132 location.href = auto;
133</script>
134```
135
136`CompressionStream('deflate-raw')` is required (modern Chromium / Firefox / Safari).
137
138---
139
140## Protocol registration
141
142| Platform | How |
143|----------|-----|
144| **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"<exe>" "%1"` |
145| **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` |
146| **macOS (`Posprint.app`)** | `Info.plist` registers `CFBundleURLSchemes = ["posprint"]` with LaunchServices and forwards `open location` AppleEvents to `posprint` |
147
148After a Linux package install, if links do not open:
149
150```bash
151xdg-mime default posprint-url.desktop x-scheme-handler/posprint
152```
153
154Run the GUI once (or any `posprint` launch) on Windows so the registry key exists.
155
156---
157
158## Example template body
159
160```markdown
161@barcode RASTER CODE128 ${data}
162Hello from posprint://
163@cut
164```
165
166Corresponding minimal `.pos` JSON:
167
168```json
169{
170 "version": 1,
171 "metadata": {
172 "title": "URL demo",
173 "page_width_mm": 53,
174 "chars_per_line": 32
175 },
176 "body": "@barcode RASTER CODE128 ${data}\nHello from posprint://\n@cut\n"
177}
178```