Docs
SDK Reference
@portixone/sdk — one class, Portix.
Source: sdk-js/.
new Portix(options?)
| Option | Type | Default | Description |
|---|---|---|---|
| mode | "runtime" | "mock" | "runtime" | "mock" needs no runtime and no printer |
| apiKey | string | "dev-local-key" | Must match the runtime's PORTIX_LOCAL_API_KEY — only needed until pair() is used |
| host | string | "127.0.0.1" | Runtime host |
| port | number | 17321 | Runtime port |
| appId | string | — | Your integration's identity. Required for pair() |
| tenant | string | — | The specific business/customer this connection is for. Required for pair() |
Methods
portix.connect(): Promise<void>
Verifies the runtime is reachable (skipped entirely in mock mode). Throws if it isn't — call this before any other method.
portix.disconnect(): Promise<void>
Ends the SDK session: stops any in-flight pairing poll, closes the live-events socket if one was opened, and drops the connection. Doesn't affect the pairing itself.
portix.print({ content, printerName?, copies? }): Promise<{ jobId, status, message? }>
Sends a print job. status is "pending" right after this call resolves — the job is processed asynchronously. See on() below to follow it to "printing"/"completed"/"failed".
portix.getStatus(): Promise<{ status, version, defaultPrinter? }>
Reads the runtime's health endpoint (or a static mock status in mock mode).
portix.ping(): Promise<{ pong: boolean }>
A cheaper liveness check than getStatus() — no version/printer info, just "is it up".
portix.listPrinters(): Promise<PrinterInfo[]>
Every printer the runtime can see, with { name, driver?, port?, status?, online }. Empty array in mock mode.
portix.getPrinter(name): Promise<PrinterInfo>
Same shape as one entry from listPrinters(). Throws PRINTER_NOT_FOUND if it doesn't exist.
portix.getJobs(): Promise<JobRecord[]>
Every job this connection is allowed to see — all jobs for the admin key, only this tenant/app's own jobs once paired.
portix.cancel(jobId): Promise<{ jobId, status, message? }>
Cancels a job that hasn't started printing yet. Throws JOB_NOT_CANCELLABLE if it's already printing/completed/failed/cancelled.
portix.pair(): Promise<{ code, expiresAt }>
Requests pairing for this { tenant, appId } and returns a short code for a human to approve locally on the runtime. Requires tenant/appId in the constructor options.
portix.on(event, handler): () => void
Subscribes to real-time events pushed by the runtime — "status", "job:queued", "job:printing", "job:printed", "job:error", "job:cancelled" — plus the SDK-local "paired" event. Returns an unsubscribe function.
portix.getMetrics(): Promise<RuntimeMetrics>
Job counts/durations, pairing duration, and WebSocket disconnects. Named honestly — totalDisconnects counts disconnects, not successful reconnections, since reconnect-on-drop isn't built yet. Requires the admin key.
Mock mode
No runtime or printer nearby? Pass mode: "mock" and use the exact same API —
print() renders a text preview instead of sending it anywhere. Going to
production is a one-word change: drop the option, or set it to "runtime".
Pairing — for multi-tenant integrations
If you're building a product other businesses install PortixOne for, don't share the runtime's admin key — pair each installation once instead:
const portix = new Portix({ tenant: "acme-cafe", appId: "kubia" });
await portix.connect();
const { code } = await portix.pair();
// Show `code` to whoever is at the machine — they approve it locally.
portix.on("paired", ({ deviceId, permissions }) => {
// print()/getJobs()/cancel() are now scoped to this tenant/app.
});See Runtime API if you need to call the local HTTP/WebSocket surface directly instead of through the SDK.