# 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/`](../lib/).

---

## Format

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

Optional auto-print:

```
posprint://print?v=1&d=…&noconfirm=1
```

| Part | Meaning |
|------|---------|
| `posprint://` | Custom protocol (registered on install / first run) |
| `print` | Open the print-only dialog (same UX as `posprint --print`) |
| `v=1` | URL payload version |
| `d=` | Compressed `.pos` file (JSON with `version`, `metadata`, `body`) |
| `noconfirm=1` | Start 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>"`.

| Guidance | Size |
|----------|------|
| 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

```bash
posprint link receipt.pos
```

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

### Libraries

| Runtime | Path |
|---------|------|
| PHP | [`lib/php/posprint_url.php`](../lib/php/posprint_url.php) |
| Node.js | [`lib/node/posprint_url.js`](../lib/node/posprint_url.js) |
| Browser | [`lib/browser/posprint_url.js`](../lib/browser/posprint_url.js) |

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

#### PHP

```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

```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

```html
<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

| Platform | How |
|----------|-----|
| **Windows** | On 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:

```bash
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

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

Corresponding minimal `.pos` JSON:

```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"
}
```
