# API reference

> Every function and value exported by @82label/core (the global Label82).

Source: https://82label.app/en/docs/api/

Everything below is exported both by `import { … } from '@82label/core'` and on the CDN global `Label82`.

## Printing

| Name | What it does |
| --- | --- |
| `print(template, rows?, options?)` | Print a template (object or id) with data. `Promise<PrintResult>`. See [Printing](https://82label.app/en/docs/printing/). |
| `printers()` | The agent's printers `{ name, isDefault, dpi? }[]`, or `null` without an agent. |
| `agentStatus()` | `{ version, allowed, licensed }` or `null`. |
| `printViaBrowser(svgs, size)` | Print page SVGs through the browser dialog (`size` = `{ width, height }` in mm). |
| `rasterize(svg, widthMm, heightMm, dpi)` | An SVG as a PNG `Blob` at the given dpi. |
| `AgentError` | `mode: 'agent'` failures. `code`: unavailable, denied, license_required, failed. |
| `toPDF(template, rows?, options?)` | Labels as a PDF `Blob`; barcodes, QR and lines as vectors. Browser only. See [Save as PDF](https://82label.app/en/docs/pdf/). |
| `downloadPDF(template, rows?, filename?, options?)` | Make the PDF and download it. |
| `calibrationKey(via, printer?)` | Calibration key: `'browser'` or `'agent:printer'`. |
| `getCalibration(key) / setCalibration(key, cal \| null)` | Calibration `{ offsetX, offsetY, scale }` saved in this browser. See [Print calibration](https://82label.app/en/docs/calibration/). |
| `calibrationTemplate(template)` | A test print for the same paper (border, 1 cm ticks, cross, size). |
| `AGENT_PORTS` | Ports the agent listens on: `[18282, 18283, 18284]`. |

## Saved templates

| Name | What it does |
| --- | --- |
| `loadTemplate(id, base?)` | Fetch a template from `https://82label.app/api/t/<id>`; each id is fetched once per page. |
| `loadCourierTemplate(id, base?)` | A courier waybill preset (subscribers, needs the 82label.app sign-in cookie). |
| `clearTemplateCache()` | Forget fetched templates. |
| `TemplateNotFound` | Unknown id, deleted template, network error or invalid JSON. |
| `PaymentRequired` | 402: an unpaid saved template, or a courier preset that needs a subscription. |

## Rendering

| Name | What it does |
| --- | --- |
| `renderToSVG(template, row?, options?)` | One label as an SVG string (example values without `row`). No DOM needed. |
| `renderLabelSVG(template, row?, options?)` | `{ svg, errors }`. |
| `renderPageSVG(template, page, rows, options?)` | One page (a sheet, or a roll label) as `{ svg, errors }`. |
| `barcodeSVG(value, { format, height, moduleWidth, showText, codeSet })` | A barcode picture on its own. |
| `qrSVG(value, { ecc, size })` | A QR picture on its own. |
| `measureText(text, sizeMm, font?, bold?)` | Text width in mm (canvas in browsers). |
| `layoutPages(template, count, startAt?)` | Pages and slot positions for `count` labels: `Page[]`. |
| `pageSize(template)` | Printed page size `{ width, height }` in mm. |

## Barcodes and QR

| Name | What it does |
| --- | --- |
| `encodeBarcode(format, value, { codeSet? })` | Bar modules and the human-readable text; `BarcodeError` for invalid values. |
| `eanCheckDigit(digits)` | EAN/UPC check digit. |
| `mod7Check(digits)` | Remainder mod 7 (some courier tracking numbers). |
| `encodeQR(value, ecc?)` | QR module matrix; `QrError` when too long. |
| `BarcodeError, QrError` | Value errors. |

## Fields

| Name | What it does |
| --- | --- |
| `extractFields(template)` | Field names used by a template. |
| `fill(text, row, ctx?)` | Text with `{{name}}`, `{{name\|format}}`, `{{seq}}` and `{{today}}` replaced. `ctx` = `{ index, serialStart, now }`. |
| `FIELD_FORMATS` | Value formats `{ id, label, example }[]`. See [Value formats](https://82label.app/en/docs/formats/). |
| `exampleRow(template)` | An example row from `fields[].example`. |
| `escapeXml(text)` | Escape for SVG/HTML. |

## Paper and units

| Name | What it does |
| --- | --- |
| `FORMTEC` | Formtec A4 sheets `SheetSpec[]` (code, grid, size, margins, verified, source). |
| `ROLL_SIZES` | Common roll sizes `{ w, h, label, use }[]`. |
| `COURIERS` | Courier template info (empty in the open-source package; the site fills it). |
| `presetTemplate('roll', w, h) / presetTemplate('formtec', id)` | An empty template. |
| `SAMPLES / sampleTemplate(id)` | Free starter templates: Coupang Rocket Growth barcodes (50×30, 60×40, 70×40, A4 21 and 40), product notice, price tag, asset tag. |
| `sheetPaper(id)` | The `paper` object of a Formtec sheet. |
| `mmToPx(mm, dpi?), mmToDots(mm, dpi), ptToMm(pt), MM_PER_PT` | Unit conversion. |

## Other

| Name | What it does |
| --- | --- |
| `defineLabelElement(tag?)` | Register `<label-82>` (or another name); automatic in the CDN build. |
| `VERSION` | Library version string. |

## Types

```ts
type Template = { v: 1; name: string; paper: RollPaper | SheetPaper; label: { width; height; radius? }; elements: Element[]; fields?: FieldDef[] };
type RollPaper = { kind: 'roll'; gap?; dpi?: 203 | 300 | 600; direction?: 0 | 90 | 180 | 270 };
type SheetPaper = { kind: 'sheet'; preset?; page: 'A4' | 'Letter' | { width; height }; cols; rows; marginTop; marginLeft; pitchX; pitchY; shape?: 'rect' | 'circle' | 'ring'; innerDiameter? };
type Row = Record<string, string | number | null | undefined>;
type PrintOptions = { printer?; copies?; startAt?; mode?: 'auto' | 'agent' | 'browser'; dpi?; frames?; base?; serialStart?; now?: Date; calibration?: Calibration | false; qtyField? };
type Calibration = { offsetX?; offsetY?; scale? }; // mm, mm, 1 = 100%
type PrintResult = { via: 'agent' | 'browser'; printed; status: 'done' | 'pending_permission' | 'cancelled'; errors: RenderError[]; notice?: 'agent_license_required' };
type RenderError = { element: number; code: 'barcode_invalid' | 'qr_too_long' | 'overflow' | 'image_failed'; message: string };
```