BlueGit

timfa posprint

Add per-library examples for posprint:// URL encoding.

Document array and local-file usage for PHP, Node, and browser helpers.

Co-authored-by: Cursor <cursoragent@cursor.com>

timfa Tim Falken · pushed by timfa

Authored 2026-07-21 · 3 months ago

Hash
f9bc0a4e29dc32981bbe9c5b4ce3713769369d37
Parent
941b860e
4 files changed +218 −5
lib/README.md +5 −5
@@ -4,10 +4,10 @@ Small helpers that turn a `.pos` document into a `posprint://` deep link.
4 4
5 5 See [docs/POSPRINT-URL.md](../docs/POSPRINT-URL.md) for the full URL format and size limits.
6 6
7 | Folder | Runtime |
8 |--------|---------|
9 | [`php/`](php/) | PHP (`gzdeflate`) |
10 | [`node/`](node/) | Node.js (`zlib.deflateRawSync`) |
11 | [`browser/`](browser/) | ES module (`CompressionStream('deflate-raw')`) |
7 | Folder | Runtime | Examples |
8 |--------|---------|----------|
9 | [`php/`](php/) | PHP (`gzdeflate`) | [examples.md](php/examples.md) |
10 | [`node/`](node/) | Node.js (`zlib.deflateRawSync`) | [examples.md](node/examples.md) |
11 | [`browser/`](browser/) | ES module (`CompressionStream('deflate-raw')`) | [examples.md](browser/examples.md) |
12 12
13 13 All implementations must stay byte-compatible with Rust `src/protocol_url.rs`.
@@ -4,10 +4,10 @@ Small helpers that turn a `.pos` document into a `posprint://` deep link.
4
4
5See [docs/POSPRINT-URL.md](../docs/POSPRINT-URL.md) for the full URL format and size limits.
5See [docs/POSPRINT-URL.md](../docs/POSPRINT-URL.md) for the full URL format and size limits.
6
6
7| Folder | Runtime |
7| Folder | Runtime | Examples |
8|--------|---------|
8|--------|---------|----------|
9| [`php/`](php/) | PHP (`gzdeflate`) |
9| [`php/`](php/) | PHP (`gzdeflate`) | [examples.md](php/examples.md) |
10| [`node/`](node/) | Node.js (`zlib.deflateRawSync`) |
10| [`node/`](node/) | Node.js (`zlib.deflateRawSync`) | [examples.md](node/examples.md) |
11| [`browser/`](browser/) | ES module (`CompressionStream('deflate-raw')`) |
11| [`browser/`](browser/) | ES module (`CompressionStream('deflate-raw')`) | [examples.md](browser/examples.md) |
12
12
13All implementations must stay byte-compatible with Rust `src/protocol_url.rs`.
13All implementations must stay byte-compatible with Rust `src/protocol_url.rs`.
lib/browser/examples.md added +85 −0
@@ -0,0 +1,85 @@
1 # Browser examples — `posprintUrl()`
2
3 See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.
4
5 Browsers cannot read arbitrary paths on disk. “Local file” here means a user-selected `.pos` file via `<input type="file">`, or JSON fetched from your server.
6
7 Requires `CompressionStream('deflate-raw')` (recent Chromium, Firefox, Safari).
8
9 ```html
10 <script type="module">
11 import { posprintUrl } from './posprint_url.js';
12 </script>
13 ```
14
15 ## From an object
16
17 Build the document in JavaScript and open the link:
18
19 ```html
20 <button id="print">Print</button>
21 <script type="module">
22 import { posprintUrl } from './posprint_url.js';
23
24 document.getElementById('print').addEventListener('click', async () => {
25 const url = await posprintUrl({
26 version: 1,
27 metadata: {
28 title: 'Barcode demo',
29 page_width_mm: 53,
30 chars_per_line: 32,
31 },
32 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
33 });
34 window.location.href = url;
35 });
36 </script>
37 ```
38
39 Or render a link without navigating immediately:
40
41 ```js
42 const url = await posprintUrl({ /* … */ });
43 const a = document.createElement('a');
44 a.href = url;
45 a.textContent = 'Print receipt';
46 document.body.append(a);
47 ```
48
49 ## From a local `.pos` file (user picks file)
50
51 ```html
52 <input type="file" id="pos-file" accept=".pos,application/json" />
53 <a id="print-link" hidden>Print</a>
54
55 <script type="module">
56 import { posprintUrl } from './posprint_url.js';
57
58 document.getElementById('pos-file').addEventListener('change', async (ev) => {
59 const file = ev.target.files?.[0];
60 if (!file) return;
61
62 const json = await file.text();
63 const url = await posprintUrl(json);
64
65 const link = document.getElementById('print-link');
66 link.href = url;
67 link.hidden = false;
68 });
69 </script>
70 ```
71
72 ## From a file on your server
73
74 If the `.pos` lives on the same site, fetch it and pass the JSON string:
75
76 ```js
77 const res = await fetch('/templates/receipt.pos');
78 const json = await res.text();
79 const url = await posprintUrl(json);
80 window.location.href = url;
81 ```
82
83 ## Length warning
84
85 On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. Prefer short templates and `@image https://…` for logos.
@@ -0,0 +1,85 @@
1# Browser examples — `posprintUrl()`
2
3See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.
4
5Browsers cannot read arbitrary paths on disk. “Local file” here means a user-selected `.pos` file via `<input type="file">`, or JSON fetched from your server.
6
7Requires `CompressionStream('deflate-raw')` (recent Chromium, Firefox, Safari).
8
9```html
10<script type="module">
11 import { posprintUrl } from './posprint_url.js';
12</script>
13```
14
15## From an object
16
17Build the document in JavaScript and open the link:
18
19```html
20<button id="print">Print</button>
21<script type="module">
22 import { posprintUrl } from './posprint_url.js';
23
24 document.getElementById('print').addEventListener('click', async () => {
25 const url = await posprintUrl({
26 version: 1,
27 metadata: {
28 title: 'Barcode demo',
29 page_width_mm: 53,
30 chars_per_line: 32,
31 },
32 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
33 });
34 window.location.href = url;
35 });
36</script>
37```
38
39Or render a link without navigating immediately:
40
41```js
42const url = await posprintUrl({ /* … */ });
43const a = document.createElement('a');
44a.href = url;
45a.textContent = 'Print receipt';
46document.body.append(a);
47```
48
49## From a local `.pos` file (user picks file)
50
51```html
52<input type="file" id="pos-file" accept=".pos,application/json" />
53<a id="print-link" hidden>Print</a>
54
55<script type="module">
56 import { posprintUrl } from './posprint_url.js';
57
58 document.getElementById('pos-file').addEventListener('change', async (ev) => {
59 const file = ev.target.files?.[0];
60 if (!file) return;
61
62 const json = await file.text();
63 const url = await posprintUrl(json);
64
65 const link = document.getElementById('print-link');
66 link.href = url;
67 link.hidden = false;
68 });
69</script>
70```
71
72## From a file on your server
73
74If the `.pos` lives on the same site, fetch it and pass the JSON string:
75
76```js
77const res = await fetch('/templates/receipt.pos');
78const json = await res.text();
79const url = await posprintUrl(json);
80window.location.href = url;
81```
82
83## Length warning
84
85On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. Prefer short templates and `@image https://…` for logos.
lib/node/examples.md added +67 −0
@@ -0,0 +1,67 @@
1 # Node.js examples — `posprintUrl()`
2
3 See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.
4
5 ```js
6 const { posprintUrl } = require('./posprint_url');
7 // or: import { posprintUrl } from './posprint_url.js'; // with "type": "module"
8 ```
9
10 ## From an object
11
12 Build the `.pos` document in JavaScript:
13
14 ```js
15 const url = posprintUrl({
16 version: 1,
17 metadata: {
18 title: 'Barcode demo',
19 page_width_mm: 53,
20 chars_per_line: 32,
21 },
22 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
23 });
24
25 console.log(url);
26 // posprint://print?v=1&d=…
27 ```
28
29 Express route example:
30
31 ```js
32 app.get('/print-link', (req, res) => {
33 const url = posprintUrl({ /* … */ });
34 res.redirect(url);
35 });
36 ```
37
38 ## From a local `.pos` file
39
40 Read the file and pass the JSON string:
41
42 ```js
43 const fs = require('fs');
44 const path = require('path');
45
46 const filePath = path.join(__dirname, '../../examples/url-demo.pos');
47 let json = fs.readFileSync(filePath, 'utf8');
48
49 // Optional: strip UTF-8 BOM
50 if (json.charCodeAt(0) === 0xfeff) {
51 json = json.slice(1);
52 }
53
54 const url = posprintUrl(json);
55 console.log(url);
56 ```
57
58 Or parse and validate first:
59
60 ```js
61 const doc = JSON.parse(json);
62 const url = posprintUrl(doc);
63 ```
64
65 ## Length warning
66
67 On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. For large templates, use `@image https://…` in the body instead of embedding image data.
@@ -0,0 +1,67 @@
1# Node.js examples — `posprintUrl()`
2
3See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.
4
5```js
6const { posprintUrl } = require('./posprint_url');
7// or: import { posprintUrl } from './posprint_url.js'; // with "type": "module"
8```
9
10## From an object
11
12Build the `.pos` document in JavaScript:
13
14```js
15const url = posprintUrl({
16 version: 1,
17 metadata: {
18 title: 'Barcode demo',
19 page_width_mm: 53,
20 chars_per_line: 32,
21 },
22 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
23});
24
25console.log(url);
26// posprint://print?v=1&d=…
27```
28
29Express route example:
30
31```js
32app.get('/print-link', (req, res) => {
33 const url = posprintUrl({ /* … */ });
34 res.redirect(url);
35});
36```
37
38## From a local `.pos` file
39
40Read the file and pass the JSON string:
41
42```js
43const fs = require('fs');
44const path = require('path');
45
46const filePath = path.join(__dirname, '../../examples/url-demo.pos');
47let json = fs.readFileSync(filePath, 'utf8');
48
49// Optional: strip UTF-8 BOM
50if (json.charCodeAt(0) === 0xfeff) {
51 json = json.slice(1);
52}
53
54const url = posprintUrl(json);
55console.log(url);
56```
57
58Or parse and validate first:
59
60```js
61const doc = JSON.parse(json);
62const url = posprintUrl(doc);
63```
64
65## Length warning
66
67On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. For large templates, use `@image https://…` in the body instead of embedding image data.
lib/php/examples.md added +61 −0
@@ -0,0 +1,61 @@
1 # PHP examples — `posprint_url()`
2
3 See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.
4
5 ```php
6 require __DIR__ . '/posprint_url.php';
7 ```
8
9 ## From an array
10
11 Build the `.pos` document in PHP and pass an associative array:
12
13 ```php
14 $url = posprint_url([
15 'version' => 1,
16 'metadata' => [
17 'title' => 'Barcode demo',
18 'page_width_mm' => 53.0,
19 'chars_per_line' => 32,
20 ],
21 'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n",
22 ]);
23
24 echo $url, "\n";
25 // posprint://print?v=1&d=…
26 ```
27
28 Use in HTML:
29
30 ```php
31 <a href="<?= htmlspecialchars($url, ENT_QUOTES, 'UTF-8') ?>">Print receipt</a>
32 ```
33
34 ## From a local `.pos` file
35
36 Read the file as JSON text and pass the string (same encoding path as an array):
37
38 ```php
39 $path = __DIR__ . '/../../examples/url-demo.pos';
40 $json = file_get_contents($path);
41 if ($json === false) {
42 throw new RuntimeException("Could not read {$path}");
43 }
44
45 // Optional: strip UTF-8 BOM if present (Windows editors)
46 $json = preg_replace('/^\xEF\xBB\xBF/', '', $json) ?? $json;
47
48 $url = posprint_url($json);
49 echo $url, "\n";
50 ```
51
52 Or decode first to validate, then encode:
53
54 ```php
55 $doc = json_decode($json, true, flags: JSON_THROW_ON_ERROR);
56 $url = posprint_url($doc);
57 ```
58
59 ## Length warning
60
61 On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. For large templates, keep images as `@image https://…` in the body instead of embedding bytes in JSON.
@@ -0,0 +1,61 @@
1# PHP examples — `posprint_url()`
2
3See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.
4
5```php
6require __DIR__ . '/posprint_url.php';
7```
8
9## From an array
10
11Build the `.pos` document in PHP and pass an associative array:
12
13```php
14$url = posprint_url([
15 'version' => 1,
16 'metadata' => [
17 'title' => 'Barcode demo',
18 'page_width_mm' => 53.0,
19 'chars_per_line' => 32,
20 ],
21 'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n",
22]);
23
24echo $url, "\n";
25// posprint://print?v=1&d=…
26```
27
28Use in HTML:
29
30```php
31<a href="<?= htmlspecialchars($url, ENT_QUOTES, 'UTF-8') ?>">Print receipt</a>
32```
33
34## From a local `.pos` file
35
36Read the file as JSON text and pass the string (same encoding path as an array):
37
38```php
39$path = __DIR__ . '/../../examples/url-demo.pos';
40$json = file_get_contents($path);
41if ($json === false) {
42 throw new RuntimeException("Could not read {$path}");
43}
44
45// Optional: strip UTF-8 BOM if present (Windows editors)
46$json = preg_replace('/^\xEF\xBB\xBF/', '', $json) ?? $json;
47
48$url = posprint_url($json);
49echo $url, "\n";
50```
51
52Or decode first to validate, then encode:
53
54```php
55$doc = json_decode($json, true, flags: JSON_THROW_ON_ERROR);
56$url = posprint_url($doc);
57```
58
59## Length warning
60
61On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. For large templates, keep images as `@image https://…` in the body instead of embedding bytes in JSON.