@zen-print/sdk

Browser SDK for Zen Print — the local printer bridge.

Install

npm install @zen-print/sdk

Publish (maintainers)

Publishing runs automatically when a version tag is pushed (e.g. v0.1.0) or via the Publish SDK workflow in GitHub Actions.

Setup (one time):

1. Create the @zen-print npm organization (or ensure you have publish access).
2. Generate an npm access token with Publish scope.
3. Add it as repository secret NPM_TOKEN in GitHub → Settings → Secrets and variables → Actions.

Manual publish:

npm run build
npm publish --access public

Demo

The demo page loads the built SDK from /dist. Serve the repository root, not the examples/ folder.

npm install
npm run demo

Open http://localhost:3000/examples/demo.html.

Zen Print must be running locally on ws://127.0.0.1:8181. Enter your certificate fingerprint and private key PEM from Site Manager in the Zen Print app.

When generating a site certificate, include this demo origin in Allowed origins, for example:

http://localhost:3000

Printers are listed automatically after connect. If listing fails, check the error hint in the demo output — common causes are a mismatched private key, a missing allowed origin, or an outdated Zen Print build on Linux.

Quick start

import { ZenPrint } from "@zen-print/sdk";

const zen = new ZenPrint({
  url: "ws://127.0.0.1:8181",
  certificateFingerprint: "sha256:...",
  privateKeyPem: `-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----`,
});

await zen.connect();

const version = await zen.version();
const printers = await zen.listPrinters();

await zen.printRaw({
  printer: "Microsoft Print to PDF",
  data: new TextEncoder().encode("\x1B\x40Hello from Zen Print\x0A\x0A\x0A"),
});

zen.disconnect();

API

| Method | Auth | Description | |--------|------|-------------| | connect() | No | Open WebSocket to Zen Print | | disconnect() | No | Close connection | | ping() | No | Health check | | version() | No | Agent version info | | listPrinters() | Yes | List installed printers | | defaultPrinter() | Yes | Get default printer name | | printRaw({ printer, data }) | Yes | Send raw bytes to a printer |

Protected methods are signed automatically using the configured private key.

Events

zen.onEvent((event) => {
  switch (event.type) {
    case "connected":
      console.log("connected", event.url);
      break;
    case "disconnected":
      console.log("disconnected", event.reason);
      break;
    case "error":
      console.error(event.error);
      break;
  }
});

Security note

The private key lives in your web app when using client-side signing. Treat it as sensitive and restrict allowed origins in Zen Print.