@taprel/sdk
v0.1.2
Published
Taprel: silent printing from web apps, through the desktop agent
Maintainers
Readme
Taprel
Silent printing from web apps: your page calls this package, and the Taprel desktop agent on the customer's PC prints with no print dialog.
Install
npm install @taprel/sdkThe package needs a bundler (Vite, webpack and similar). Printing also needs the Taprel agent installed on the PC with the printer. It's for Windows for now.
Print a receipt
import { PrintClient, receipt } from "@taprel/sdk";
const printer = new PrintClient({ client: { name: "my-pos" } });
await printer.printDocument(
receipt([
{ text: "Café Central", align: "center", bold: true, size: 2 },
{ line: true },
{ row: ["2 x Coffee", "6.00"] },
{ row: ["Total", "6.00"], bold: true },
{ cut: true },
]),
);The agent picks the customer's receipt printer, so no printer name ends up in your code. Use label(content, size) the same way for labels.
Writing a document
A document is a plain list, so your normal code builds it. false, null, undefined, 0 and "" are left out, which makes optional lines easy:
receipt([
{ image: logo, width: 30, align: "center" },
...order.items.map((item) => ({ row: [`${item.qty} x ${item.name}`, item.price.toFixed(2)] })),
order.discount && { row: ["Discount", order.discount.toFixed(2)] },
{ row: ["Total", order.total.toFixed(2)], bold: true },
{ cut: true },
]);- Warnings:
pathcounts after those values are left out, so look it up in the document'scontent, not in the list you wrote. - Images:
imagetakes aBlob, aFile, bytes, or base64 text, in PNG or JPEG. For a logo at an address:await (await fetch(url)).blob(). Use base64 text if you want to save the document as JSON, because aBlobcan't be saved that way. - Money: rows take text, not numbers, so
6.5can't print where you wanted6.50. - Sizes: text
sizeis 1, 2 or 3. Everything else, like a QR code'ssize, is in mm. - Elements in a variable: give it a type, or TypeScript reads
"center"as any string:const title: ReceiptText = { text: "Hi", align: "center" }.
What the client offers
| Call | What it does |
|---|---|
| printDocument(document, { printer, printerKind, copies }) | Prints a receipt or label. Target and copies are optional |
| previewDocument(document, { printer, printerKind }) | Returns the document as a base64 PNG, printing nothing |
| printPdf(printer, data, { copies, scale, paper }) | Prints a PDF through the printer's driver |
| printRaw(printer, data) | Sends bytes unchanged, in the printer's own language |
| listPrinters() | The customer's printers, with kind, status and sizes |
| connect() / close() | Connects now / disconnects and stops reconnecting |
data is a Uint8Array, ArrayBuffer, Blob, or a string already in base64.
The customer's two questions
The first connection can show the customer two questions. Creating a PrintClient asks nothing: they appear on the first request or on connect(), so call connect() at a moment that makes sense.
- The browser's: "Access other apps and services on this device". It can appear even when the agent is not running.
- The agent's: "Allow this website to print?"
Show help while they wait:
import { browserPermissionTexts } from "@taprel/sdk";
printer.onStatusChange((status, error) => {
if (status === "waiting-for-browser") show(browserPermissionTexts.beforeQuestion);
if (status === "waiting-for-agent") show("Answer the window on your computer: Allow this website to print?");
if (error?.code === "BROWSER_BLOCKED") show(browserPermissionTexts.afterBlock);
if (error?.code === "AGENT_NOT_RUNNING") show("Please start or install the printing app.");
});The texts are in English. For another language, show your own text instead.
Errors
Every failure is a PrintError with a code:
| Code | Meaning |
|---|---|
| AGENT_NOT_RUNNING | The agent is not installed or not started |
| BROWSER_BLOCKED | The customer refused the browser's question |
| ORIGIN_NOT_ALLOWED | The customer refused the agent's question |
| CONTENT_SECURITY_POLICY | Your website's Content-Security-Policy forbids the connection. Add ws://127.0.0.1:21873 to connect-src |
| CONNECTION_LOST | The connection dropped before the reply. The job may or may not have printed |
| REQUEST_TIMEOUT | No reply in time. The job may still print |
| PRINTER_NOT_FOUND | No printer has that exact name |
| PRINTER_NOT_CHOSEN | Several printers of that kind and none marked as main |
| LABEL_SIZE_MISSING | No label size in the document or the printer's settings |
| FONT_MISSING | No font has one of the characters |
| BAD_REQUEST | Something is wrong in the request. The message gives the exact place |
| PRINT_FAILED | The driver or the print queue failed |
| LICENSE_REQUIRED | This website needs a plan, or this computer needs linking. The message says what to do |
| LICENSE_UNAVAILABLE | The agent can't confirm the licence right now. Trying again later can work |
| INTERNAL | A bug in the agent |
The two licence errors come only from print requests, so previews and listPrinters() still work. Their messages are written for the person at the computer, so you can show them as they are:
try {
await printer.printDocument(document);
} catch (error) {
if (error instanceof PrintError && error.code.startsWith("LICENSE_")) show(error.message);
}A jobId in the reply means "handed to the print queue", not "came out on paper". The client never sends a print twice by itself: after CONNECTION_LOST or REQUEST_TIMEOUT, your app decides whether to try again.
Development
npm test: builds and runs the tests against a pretend agentnpm run demo: a demo page at http://127.0.0.1:5180, for the real agent and real printers
License
This package is MIT. The desktop agent it talks to is a separate product with its own terms.
