Local API & SDK

Web apps talk to the bridge over a WebSocket protocol at wss://127.0.0.1:31075/ws (JSON text frames; falls back to ws:// on loopback). A REST mirror exists but the WebSocket is the primary contract because it carries push events.

The @intrasys/presto-js client wraps this protocol; you can also speak it directly.

Message envelope

Request

{ "v": 1, "id": "c-42", "method": "print.raw", "params": { } }

Response

{ "v": 1, "id": "c-42", "ok": true, "result": { } }

Error

{ "v": 1, "id": "c-42", "ok": false, "error": { "code": "ORIGIN_DENIED", "message": "..." } }

Push event

{ "v": 1, "event": "job.update", "data": { } }

Methods

Method	Purpose
hello	Handshake; returns whether auth is required and the license state.
auth	Present a per-origin bearer token.
printers.list	List printers (aliases the origin may use).
printers.status	Live status for a printer.
print.raw	Submit raw printer-language bytes.
print.template	Submit a stored template with per-label parameters.
job.get	Fetch a job's current status.
subscribe	Subscribe to job.update / printer.status events.
templates.list	List stored templates.
ping	Keep-alive.

note

job.cancel exists in the protocol but is not yet implemented — it returns an error. Don't rely on cancellation.

Events

• job.update — a job's state or per-label results changed.
• printer.status — a printer came online / went offline or changed status.

Key shapes

printers.list → { printers: Printer[] }, where

{ "id": "zebra-dock-1", "name": "Dock 1", "transport": "tcp",
  "languages": ["zpl"], "dpmm": 8, "rfid": true, "feedback": "printer", "online": true }

print.raw params → { jobId }:

{ "printer": "zebra-dock-1", "data": "^XA...^XZ", "encoding": "utf8", "copies": 1 }

print.template — every {{n}} placeholder must be supplied, or the whole request fails TEMPLATE_PARAMS_MISSING and nothing prints:

{ "printer": "zebra-dock-1", "template": "tpl-swift-4a9c21",
  "labels": [ { "params": ["ACME", "SKU-001"] }, { "params": ["ACME", "SKU-002"] } ] }

Job status (job.get result and job.update data):

{ "job_id": "j-88", "printer": "zebra-dock-1", "state": "Done", "verification": "rfid",
  "labels": [ { "index": 0, "printed": true, "encoded": true, "voided": false,
               "epc": "E28068...DD" } ] }

Authentication & origins

1. Origin — the browser's Origin must match the bridge's deny-by-default allow-list, else ORIGIN_DENIED.
2. Pairing — if hello reports authRequired, the client calls auth with its per-origin bearer token (obtained when an admin approved the origin, or pre-provisioned for fleets).

See Setup → Origins & pairing.

License state

hello returns a license block the client reacts to:

{ "state": "valid", "tier": "pro", "rfidEncode": true, "serving": true, "expiresAt": "..." }

Printing while blocked returns LICENSE_BLOCKED; RFID without the entitlement is blocked too. See Presto Cloud.

Error codes

ORIGIN_DENIED · AUTH_REQUIRED · AUTH_INVALID · PRINTER_UNKNOWN · PRINTER_OFFLINE · PRINTER_UNBOUND · TEMPLATE_UNKNOWN · TEMPLATE_PARAMS_MISSING · LANGUAGE_MISMATCH · JOB_UNKNOWN · JOB_NOT_CANCELLABLE · RFID_VOID_LIMIT · LICENSE_BLOCKED · TRANSPORT_TIMEOUT · PAYLOAD_TOO_LARGE · RATE_LIMITED · PROTOCOL_ERROR · INTERNAL

JavaScript client

@intrasys/presto-js is a zero-dependency ESM client. Its current surface:

const presto = new Presto({ appName: 'my-app' });
await presto.connect();
const printers = await presto.listPrinters();
const { jobId } = await presto.printRaw(printers[0].id, '^XA...^XZ');
const job = await presto.getJob(jobId);
presto.on('job.update', (job) => { /* ... */ });
presto.close();

warning

The JS client is at an early (v0) stage and is not yet published to a public registry — obtain it from Intrasys. Template-print and reconnect helpers are on its roadmap (the daemon supports print.template today; drive it over the raw protocol until the wrapper lands).

REST mirror & rps-v2 compatibility

A REST surface mirrors the health and admin operations, and a compatibility shim implements the old rps-v2 endpoints (GET /api/v2/printers, POST /api/v2/printers/{id}/print, …) so existing rps-v2 apps can migrate by repointing their host — origin checks still apply.