Print options

Every print option lives in options, and print() and preview() use them identically.

await client.compose({ queueId })
  .paper('A4')            // paper
  .copies(2)              // copies
  .duplex('long-edge')    // duplex
  .color(false)           // mono
  .addPdf(bytes)
  .printAndWait();

One job, one sheet size

paper is the single size for the whole job: with mixed content, every page lands on that sheet.

If you omit it, PrintLink derives one and says which rule it used in warnings:

When unsure, glance at the preview window's status bar — it shows the size actually used, so there is nothing to guess.

Common options

The uniform spelling of "automatic": auto and omitting the option are exactly equivalent — both mean "let PrintLink or the printer decide".

Switches (color, borderless, collate, reverseOrder) have no auto: omitting means "use the printer default", so do not write false — the two mean different things. For convenience, the strings 'true' / 'false' are also accepted on input, but PrintLink always returns a boolean.

Quality

Quality has exactly four levels, in the API and in the UI:

Drivers call these things all sorts of names ("Economy mode", "Low-compression JPEG", "Best photo"), which means nothing to a caller. So PrintLink maps the four levels onto this printer's own levels by rank: economy is always the first, best always the last. On a 3-level machine "best" and "high" land on the same level — that is expected, and all four stay selectable.

To target one specific driver level, use outputQuality:

const caps = await client.getCapabilities(queueId);
caps.outputQuality?.supported;   // the driver's own level keywords
caps.outputQuality?.names;       // display names, for UI only

When both are given, outputQuality wins. A printer that does not report this layer will drop it with a warning rather than silently substituting something.

Media type

For photo paper, transparencies and similar, set the media type as well:

const caps = await client.getCapabilities(queueId);
caps.mediaTypes?.supported;   // keywords; put one straight into options.mediaType

await client.compose({ queueId })
  .paper('4x6')
  .mediaType('photographic-glossy')
  .addImage(photoBytes)
  .printAndWait();

• The keyword is the submitted value; the names in caps.mediaTypes.names are for display only.
• A printer that does not report media types still accepts the keyword but returns MEDIA_TYPE_UNVERIFIED.
• Plain paper is stationery and is always available.

Image placement and size

The job-level pageLayout offers three uniform presets:

A single image can be adjusted precisely, affecting only that image:

await client.compose({ queueId })
  .paper('A4')
  .addImage(cover)
  .imageLayout({
    mode: 'custom',
    horizontal: 'left',           // left | center | right
    vertical: 'top',              // top | center | bottom
    scalePercent: 80,             // mutually exclusive with size
    offset: { xMm: 10, yMm: 15 },
    rotate: 90,                   // 0 | 90 | 180 | 270
    flipHorizontal: true,
  })
  .addPdf(report)                 // unaffected by the above
  .preview();

Dragging, scaling, rotating and flipping in the preview window write back exactly this set of values for the current image.

Printing only some pages

pageRange applies to output pages (after merging) and is independent of any per-item pageRange:

await client.compose({ queueId })
  .paper('A4')
  .addPdf(bytes).pageRange('2-4')   // pages 2–4 of that PDF
  .outputPageRange('1-2')           // only the first 2 merged pages
  .print();

The syntax is 1-based, e.g. '1-3,5'. '3-1' or 'a-b' gives INVALID_REQUEST; a partially out-of-range value is clamped with PAGE_RANGE_CLAMPED.

When an option does not apply

PrintLink never silently drops options: if the printer does not support a value, it downgrades compatibly and reports structured warnings.

const check = await client.compose({ queueId }).paper('A3').addPdf(bytes).validate();
console.log(check.requested);   // what you asked for
console.log(check.effective);   // what will actually be used
console.log(check.warnings);    // the difference

Call validate() before submitting so you can show the difference to the user instead of finding out after printing. The console's Jobs page keeps the same three sets of data for every job.

Common warnings:

Full details in error codes.

Saving common settings

When one printer always uses the same options, save them as a profile and reference it:

await client.compose({ queueId }).profile(profileId).addDocument(doc).print();

See printers & profiles.