Skip to main content

JavaScript SDK (browser)

@jodaprint/sdk

Classes​

JodaPrint​

Prints through the JodaPrint agent on this computer (local mode, A6).

const jp = new JodaPrint({ orgId, signer }); await jp.connect(); await jp.print({ type: "receipt", data: jp.receipt().text("Hello").cut() });

Constructors​

Constructor​

new JodaPrint(options?): JodaPrint

Parameters​
options?​

JodaPrintOptions = {}

Returns​

JodaPrint

Properties​

drawer​

readonly drawer: object

open​

open: (printer?, pin?) => Promise<{ ok: true; }>

Parameters​
printer?​

PrinterRef

pin?​

2 | 5

Returns​

Promise<{ ok: true; }>

jobs​

readonly jobs: object

cancel​

cancel: (jobId) => Promise<PrintResult>

Parameters​
jobId​

string

Returns​

Promise<PrintResult>

get​

get: (jobId) => Promise<Job>

Parameters​
jobId​

string

Returns​

Promise<Job>

printers​

readonly printers: object

list​

list: () => Promise<Printer[]>

Returns​

Promise<Printer[]>

status​

status: (printerId) => Promise<PrinterStatus>

Parameters​
printerId​

string

Returns​

Promise<PrinterStatus>

Accessors​

agent​
Get Signature​

get agent(): AgentInfo | null

The connected agent (version, capabilities...), or null.

Returns​

AgentInfo | null

Methods​

call()​

call<T>(method, params?): Promise<T>

Sends any agent method (the typed helpers above cover all of A6).

Type Parameters​
T​

T

Parameters​
method​

string

params?​

Record<string, unknown> = {}

Returns​

Promise<T>

connect()​

connect(): Promise<AgentInfo>

Finds the agent: tries each port in order and resolves with agent.info.

Returns​

Promise<AgentInfo>

disconnect()​

disconnect(): void

Closes the connection and stops reconnecting.

Returns​

void

isConnected()​

isConnected(): boolean

Returns​

boolean

on()​

on<E>(event, listener): () => void

Type Parameters​
E​

E extends keyof JodaPrintEvents

Parameters​
event​

E

listener​

Listener<E>

Returns​

() => void

print()​

print(job): Promise<PrintResult>

Queues a job. Resolves once the agent stored it ({ jobId, state }).

Parameters​
job​

PrintJob

Returns​

Promise<PrintResult>

printAndWait()​

printAndWait(job, options?): Promise<Job>

Prints and resolves when the job is printed; rejects with the job's error otherwise.

Parameters​
job​

PrintJob

options?​
timeoutMs?​

number

Returns​

Promise<Job>

receipt()​

receipt(options?): ReceiptBuilder

Starts an A8 receipt document.

Parameters​
options?​

ReceiptOptions

Returns​

ReceiptBuilder

JodaPrintError​

Every error the SDK throws: agent errors (A9) and SDK-only ones.

Extends​

  • Error

Constructors​

Constructor​

new JodaPrintError(code, message, extra?): JodaPrintError

Parameters​
code​

AnyErrorCode

message​

string

extra?​
details?​

Record<string, unknown>

helpUrl?​

string

retryable?​

boolean

Returns​

JodaPrintError

Overrides​

Error.constructor

Properties​

code​

readonly code: AnyErrorCode

details​

readonly details: Record<string, unknown> | undefined

helpUrl​

readonly helpUrl: string | undefined

Where to download the agent (AGENT_NOT_FOUND) or how to trust it (AGENT_CERT_UNTRUSTED).

name​

readonly name: "JodaPrintError" = "JodaPrintError"

Overrides​

Error.name

retryable​

readonly retryable: boolean

ReceiptBuilder​

Builds an A8 receipt document:

receipt({ width: "80mm" }) .text("Boutique Bèl Fanm").bold().center().size(2) .line("dashed") .pair("TOTAL", "2 400,00 HTG").bold() .qr("https://example.com/r/10492").center() .feed(3).cut() .build()

Style methods (bold, center, size, ...) change the block added just before them.

Constructors​

Constructor​

new ReceiptBuilder(options?): ReceiptBuilder

Parameters​
options?​

ReceiptOptions

Returns​

ReceiptBuilder

Methods​

align()​

align(align): this

Parameters​
align​

Align

Returns​

this

barcode()​

barcode(value, format?, options?): this

Parameters​
value​

string

format?​

"CODE128" | "EAN13" | "EAN8" | "UPC-A" | "CODE39" | "ITF"

options?​

BarcodeOptions

Returns​

this

bold()​

bold(on?): this

Parameters​
on?​

boolean

Returns​

this

build()​

build(): ReceiptDocument

The finished document (a copy: the builder can keep going).

Returns​

ReceiptDocument

center()​

center(): this

Returns​

this

cut()​

cut(mode?): this

Parameters​
mode?​

"full" | "partial"

Returns​

this

drawer()​

drawer(pin?): this

Parameters​
pin?​

2 | 5

Returns​

this

feed()​

feed(lines?): this

Parameters​
lines?​

number

Returns​

this

font()​

font(font): this

Parameters​
font​

"a" | "b"

Returns​

this

image()​

image(src, options?): this

An https URL or base64 PNG/JPEG; width in printer dots.

Parameters​
src​

string

options?​

ImageOptions

Returns​

this

invert()​

invert(on?): this

Parameters​
on?​

boolean

Returns​

this

left()​

left(): this

Returns​

this

line()​

line(style?): this

Parameters​
style?​

"solid" | "dashed" | "double"

Returns​

this

pair()​

pair(left, right, options?): this

Left and right text on one line, for totals.

Parameters​
left​

string

string

options?​

PairOptions

Returns​

this

qr()​

qr(value, options?): this

Parameters​
value​

string

options?​

QrOptions

Returns​

this

raw()​

raw(base64): this

Printer bytes (base64): an escape hatch for commands the format does not cover.

Parameters​
base64​

string

Returns​

this

right()​

right(): this

Returns​

this

size()​

size(size): this

Character magnification, 1 to 8.

Parameters​
size​

number

Returns​

this

table()​

table(columns, rows, options?): this

Columns with width fractions that add up to at most 1; numbers are shorthand for left-aligned columns of that width.

Parameters​
columns​

(number | TableColumn)[]

rows​

string[][]

options?​

TableOptions

Returns​

this

text()​

text(value, options?): this

Parameters​
value​

string

options?​

TextOptions

Returns​

this

toJSON()​

toJSON(): ReceiptDocument

Returns​

ReceiptDocument

underline()​

underline(on?): this

Parameters​
on?​

boolean

Returns​

this

Interfaces​

AgentInfo​

Result of agent.info (A6).

Properties​

activated​

activated: boolean

True once the agent is activated.

arch​

arch: "amd64" | "arm64" | "arm" | "386"

capabilities​

capabilities: AgentCapability[]

deviceId​

deviceId: string

Device ID, generated once per installation.

orgId​

orgId: string | null

Organization ID, null before activation.

os​

os: "windows" | "darwin" | "linux" | "android"

version​

version: string

Agent version (semver).

Job​

A job as stored by the agent or cloud (A7).

Properties​

attempt​

attempt: number

Print attempts made so far.

createdAt​

createdAt: string

When the job was created.

deviceId?​

optional deviceId?: string

errorCode?​

optional errorCode?: ErrorCode

errorMessage?​

optional errorMessage?: string

Last error message.

id​

id: string

Job ID.

idempotencyKey?​

optional idempotencyKey?: string

Idempotency key from the request.

metadata?​

optional metadata?: object

Free key/value pairs stored with the job and searchable.

Index Signature​

[k: string]: string

printedAt?​

optional printedAt?: string

When the job printed.

printerId​

printerId: string

source​

source: "local" | "cloud"

state​

state: JobState

type​

type: JobType

updatedAt​

updatedAt: string

When the job last changed state.

JodaPrintBridge​

The Android agent's WebView shell injects this object (Prompt 7.2, ADR 0039). It carries the same request, response and event envelopes as the WebSocket: one JSON text per message. Android's WebView delivers messages as events ({ data }); a plain string is accepted too.

Properties​

onmessage​

onmessage: ((message) => void) | null

Methods​

postMessage()​

postMessage(message): void

Parameters​
message​

string

Returns​

void

JodaPrintEvents​

@jodaprint/sdk: print from the browser through the JodaPrint agent on this computer (local mode, A6). Zero runtime dependencies.

Properties​

connected​

connected: AgentInfo

disconnected​

disconnected: object

code​

code: number

reason​

reason: string

job.updated​

job.updated: Job

printer.status​

printer.status: PrinterStatus

JodaPrintOptions​

@jodaprint/sdk: print from the browser through the JodaPrint agent on this computer (local mode, A6). Zero runtime dependencies.

Properties​

bridge?​

optional bridge?: boolean | JodaPrintBridge

Use window.JodaPrintBridge when the page runs in the Android agent's WebView shell (default true). Signatures and origin rules apply as over the WebSocket.

connectTimeoutMs?​

optional connectTimeoutMs?: number

Time to open the connection on one port. Default 3 s.

downloadUrl?​

optional downloadUrl?: string

Shown in AGENT_NOT_FOUND and AGENT_CERT_UNTRUSTED errors.

fetch?​

optional fetch?: {(input, init?): Promise<Response>; (input, init?): Promise<Response>; }

Replaces the global fetch used to diagnose connection failures.

Call Signature​

(input, init?): Promise<Response>

MDN Reference

Parameters​
input​

RequestInfo | URL

init?​

RequestInit

Returns​

Promise<Response>

Call Signature​

(input, init?): Promise<Response>

MDN Reference

Parameters​
input​

string | Request | URL

init?​

RequestInit

Returns​

Promise<Response>

host?​

optional host?: string

Agent host. Default "localhost".

locale?​

optional locale?: string

Language of the SDK's own error messages: en, fr or ht (default: the browser's).

orgId?​

optional orgId?: string

The organization's ID; required with a signer.

ports?​

optional ports?: number[]

reconnect?​

optional reconnect?: boolean

Reconnect after the agent restarts. Default true.

secure?​

optional secure?: boolean

Use wss (default). ws only for agents started without TLS in development.

signer?​

optional signer?: Signer

Signs each request on your backend. Without it requests are unsigned (unsigned mode, A10.3).

timeoutMs?​

optional timeoutMs?: number

Per-request timeout, and how long calls wait while reconnecting. Default 30 s.

webSocket?​

optional webSocket?: (url) => WebSocketLike

Replaces new WebSocket(url) (tests, Node).

Parameters​
url​

string

Returns​

WebSocketLike

Printer​

A printer the agent can reach (A7). IDs are stable hashes of connection + address or OS name.

Properties​

address?​

optional address?: string

Connection address: host:port, serial port, OS queue name or vendor ID.

alias?​

optional alias?: string

Alias from config.

capabilities​

capabilities: ("drawer" | "status.realtime" | "cut" | "color" | "duplex" | "copies" | "beep")[]

connection​

connection: "usb" | "network" | "serial" | "bluetooth" | "spooler" | "vendor" | "virtual"

id​

id: string

Stable printer ID.

isDefault​

isDefault: boolean

True for the default printer.

kind​

kind: "thermal" | "label" | "document"

name​

name: string

Display name.

paper?​

optional paper?: Paper

PrinterStatus​

Current state of one printer.

Properties​

coverOpen?​

optional coverOpen?: boolean

Cover open.

cutterError?​

optional cutterError?: boolean

Auto-cutter error.

errorCode?​

optional errorCode?: ErrorCode

message?​

optional message?: string

Details for humans.

paperNearEnd?​

optional paperNearEnd?: boolean

Paper near end sensor.

paperOut?​

optional paperOut?: boolean

Paper end sensor.

printerId​

printerId: string

state​

state: "online" | "offline" | "error" | "unknown"

unrecoverableError?​

optional unrecoverableError?: boolean

Unrecoverable printer error.

updatedAt​

updatedAt: string

When this status was observed.

PrintResult​

Result of print.

Properties​

jobId​

jobId: string

state​

state: JobState

ReceiptDocument​

A receipt described as blocks (A8). The agent renders it to ESC/POS for the target printer.

Properties​

blocks​

blocks: [ReceiptBlock, ...ReceiptBlock[]]

Min Items​

1

Max Items​

2000

codepage?​

optional codepage?: Codepage

width?​

optional width?: "58mm" | "80mm"

ReceiptOptions​

Properties​

codepage?​

optional codepage?: Codepage

width?​

optional width?: "58mm" | "80mm"

Signature​

@jodaprint/sdk: print from the browser through the JodaPrint agent on this computer (local mode, A6). Zero runtime dependencies.

Properties​

keyId​

keyId: string

nonce​

nonce: string

sig​

sig: string

ts​

ts: number

Unix seconds.

SignPayload​

What the developer's backend signs (A10.1); it answers with the signature.

Properties​

method​

method: string

orgId​

orgId: string

params​

params: unknown

WebSocketLike​

The subset of the browser WebSocket the SDK uses (tests and Node pass their own).

Properties​

onclose​

onclose: ((ev) => void) | null

onerror​

onerror: ((ev) => void) | null

onmessage​

onmessage: ((ev) => void) | null

onopen​

onopen: ((ev) => void) | null

readyState​

readonly readyState: number

Methods​

close()​

close(code?, reason?): void

Parameters​
code?​

number

reason?​

string

Returns​

void

send()​

send(data): void

Parameters​
data​

string

Returns​

void

Type Aliases​

Align​

Align = "left" | "center" | "right"

AnyErrorCode​

AnyErrorCode = ErrorCode | SdkErrorCode

Any error code a developer can receive from JodaPrint.

BarcodeOptions​

BarcodeOptions = Omit<BarcodeBlock, "type" | "value" | "format">

ContentPrintJob​

ContentPrintJob = Omit<ContentJobRequest, "encoding" | "data"> & object

A job as the SDK accepts it: encoding is optional and a receipt builder can be the data.

Type Declaration​

data​

data: string | ReceiptDocument | ReceiptBuilder

encoding?​

optional encoding?: ContentJobRequest["encoding"]

ImageOptions​

ImageOptions = Omit<ImageBlock, "type" | "src">

JobRequest​

JobRequest = object

A print job submitted by a client (A7). With encoding json, data is a receipt document. With encoding url, data is an https URL the agent downloads. With templateId (Prompt 8.1), data holds the template's variables and the template sets the type and content.

Properties​

data​

data: string | ReceiptDocument | { }

Job content, or template variables with templateId.

encoding?​

optional encoding?: "json" | "base64" | "utf8" | "url"

idempotencyKey?​

optional idempotencyKey?: string

Same key within 24 h returns the first job and prints nothing.

metadata?​

optional metadata?: object

Free key/value pairs stored with the job and searchable.

Index Signature​

[k: string]: string

options?​

optional options?: JobOptions

printer?​

optional printer?: PrinterRef

templateId?​

optional templateId?: string

Print a stored template (ZPL, EPL or receipt) filled with data. The job then has no type or encoding.

type?​

optional type?: JobType

JobState​

JobState = "queued" | "sending" | "printed" | "failed" | "cancelled"

PairOptions​

PairOptions = Omit<PairBlock, "type" | "left" | "right">

PrinterRef​

PrinterRef = PrinterRefById | PrinterRefByAlias | PrinterRefByName

Selects a printer by id, alias or name (A7). Omit the whole reference to use the default printer.

PrintJob​

PrintJob = ContentPrintJob | TemplatePrintJob

@jodaprint/sdk: print from the browser through the JodaPrint agent on this computer (local mode, A6). Zero runtime dependencies.

QrOptions​

QrOptions = Omit<QrBlock, "type" | "value">

ReceiptBlock​

ReceiptBlock = TextBlock | LineBlock | PairBlock | TableBlock | QrBlock | BarcodeBlock | ImageBlock | FeedBlock | CutBlock | DrawerBlock | RawBlock

Signer​

Signer = (payload) => Promise<Signature>

@jodaprint/sdk: print from the browser through the JodaPrint agent on this computer (local mode, A6). Zero runtime dependencies.

Parameters​

payload​

SignPayload

Returns​

Promise<Signature>

TableOptions​

TableOptions = Omit<TableBlock, "type" | "columns" | "rows">

TemplatePrintJob​

TemplatePrintJob = TemplateJobRequest

A template stored in the dashboard, filled with variables (Prompt 8.1): { templateId, data }.

TextOptions​

TextOptions = Omit<TextBlock, "type" | "value">

Variables​

DEFAULT_DOWNLOAD_URL​

const DEFAULT_DOWNLOAD_URL: "https://dashboard-production-b942.up.railway.app/" = "https://dashboard-production-b942.up.railway.app/"

@jodaprint/sdk: print from the browser through the JodaPrint agent on this computer (local mode, A6). Zero runtime dependencies.

DEFAULT_PORTS​

const DEFAULT_PORTS: number[]

Ports the agent tries, in order (A6).

Functions​

httpSigner()​

httpSigner(url, init?): Signer

A signer that POSTs { method, orgId, params } to your backend (see @jodaprint/node signRequestHandler) and returns its { keyId, sig, ts, nonce }.

Parameters​

url​

string

init?​

RequestInit = {}

Returns​

Signer

receipt()​

receipt(options?): ReceiptBuilder

Starts a receipt document.

Parameters​

options?​

ReceiptOptions

Returns​

ReceiptBuilder