PrintLinkEvents
Live notifications for job progress, printer status, authorisation and service changes, and how to subscribe.
Last updated
Anything that benefits from a live connection is pushed as an event — there is
nothing to poll. Every on* method returns an unsubscribe function, and
close() clears all of them.
const off = client.onJobStatus((event) => console.log(event.jobId, event.status));
// when you no longer need it:
off();Events
| Method | Event | Notes |
|---|---|---|
onJobStatus(handler) | job.status | Status transitions for this site's jobs |
onDuplicateSuppressed(handler) | job.duplicateSuppressed | An idempotency key suppressed a repeat |
onPrinterStatusChanged(handler) | printer.statusChanged | Printer status changes (with a rising revision) |
onAuthDecisionChanged(handler) | auth.decisionChanged | The user accepted or refused pairing |
onHealthAlert(handler) | health.alert | Printer health alerts |
onServiceMigrated(handler) | system.serviceMigrated | The service port changed |
onScanStatus(handler) | scan.status | Scan job status, including awaiting-consent and terminal states |
onScanPageReady(handler) | scan.pageReady | A page is downloadable (metadata only) |
onScannerListChanged(handler) | scanner.listChanged | The scanner list changed |
Job status
created → validating → rendering → ready → queued → spooling → printing → completed
├─► failed
└─► canceledThe terminal states are completed / failed / canceled; use
isTerminalJobStatus() from @printlink/types to test for them.
client.onJobStatus((event) => {
console.log(event.jobId, event.status, event.progress);
if (event.warnings?.length) showWarnings(event.warnings);
if (isTerminalJobStatus(event.status)) cleanup(event.jobId);
});Events carry queueId, progress, warnings and error.
printAndWait(params, { onStatus }) receives these intermediate states while
waiting for the terminal one — internally it is "submit, then listen to this
event".
For a failure, look at the job, not just the event
An event tells you the terminal state and the error code. The job details
(getJob) also carry the requested options, the effective options, downgrade
warnings and the full status timeline — that is the data to explain "why is this
not what I chose?" to a user.
Connection state
onConnectionStateChange delivers a snapshot rather than incremental events,
which makes it ideal for driving a "connecting / awaiting authorisation / ready /
disconnected" indicator:
const off = client.onConnectionStateChange((state) => {
// state: { transport, authorization, ready }
setStatus(state.ready ? 'ready' : state.authorization);
});Port changes
After the port is changed in the console, connected pages receive
system.serviceMigrated. Stop issuing new requests and guide the user to the new
address:
client.onServiceMigrated((event) => {
showReconnectPrompt(event.endpoint);
});Never retry silently against the old address.