# API 레퍼런스

> @82label/core(전역 Label82)가 내보내는 모든 함수와 값.

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

아래는 `import { … } from '@82label/core'` 와 CDN 의 전역 `Label82` 에 똑같이 들어 있습니다.

## 인쇄

| 이름 | 설명 |
| --- | --- |
| `print(template, rows?, options?)` | 서식(객체 또는 ID)과 데이터로 인쇄. `Promise<PrintResult>`. [인쇄](https://82label.app/docs/printing/) 참고. |
| `printers()` | 출력 프로그램의 프린터 목록 `{ name, isDefault, dpi? }[]`, 없으면 `null`. |
| `agentStatus()` | `{ version, allowed, licensed }` 또는 `null`. |
| `printViaBrowser(svgs, size)` | 페이지 SVG 목록을 브라우저 인쇄 창으로(`size` = `{ width, height }` mm). |
| `rasterize(svg, widthMm, heightMm, dpi)` | SVG 를 dpi 해상도 PNG `Blob` 으로. |
| `AgentError` | `mode: 'agent'` 실패. `code`: unavailable · denied · license_required · failed. |
| `toPDF(template, rows?, options?)` | 라벨 PDF `Blob`. 바코드·QR·선은 벡터. 브라우저 전용. [PDF 저장](https://82label.app/docs/pdf/) 참고. |
| `downloadPDF(template, rows?, filename?, options?)` | PDF 를 만들어 바로 내려받습니다. |
| `calibrationKey(via, printer?)` | 보정 저장 키: `'browser'` 또는 `'agent:프린터'`. |
| `getCalibration(key) / setCalibration(key, cal \| null)` | 이 브라우저에 저장한 보정 `{ offsetX, offsetY, scale }`. [인쇄 보정](https://82label.app/docs/calibration/) 참고. |
| `calibrationTemplate(template)` | 같은 용지의 시험 인쇄 서식(테두리, 1 cm 눈금, 십자, 크기). |
| `AGENT_PORTS` | 출력 프로그램이 듣는 포트 후보 `[18282, 18283, 18284]`. |

## 저장한 서식

| 이름 | 설명 |
| --- | --- |
| `loadTemplate(id, base?)` | `https://82label.app/api/t/<id>` 에서 서식을 받습니다. 같은 ID 는 페이지에서 한 번만 받습니다. |
| `loadCourierTemplate(id, base?)` | 택배 송장 기본서식(구독자, 82label.app 로그인 쿠키 필요). |
| `clearTemplateCache()` | 받아 둔 서식을 비웁니다. |
| `TemplateNotFound` | 없는 ID, 지운 서식, 네트워크 오류, 잘못된 JSON. |
| `PaymentRequired` | 402: 결제가 멈춘 유료 서식 또는 구독이 필요한 택배 서식. |

## 그리기

| 이름 | 설명 |
| --- | --- |
| `renderToSVG(template, row?, options?)` | 라벨 한 장의 SVG 문자열(`row` 가 없으면 예시값). DOM 불필요. |
| `renderLabelSVG(template, row?, options?)` | `{ svg, errors }`. |
| `renderPageSVG(template, page, rows, options?)` | 한 페이지(시트 한 장 또는 롤 한 장)의 `{ svg, errors }`. |
| `barcodeSVG(value, { format, height, moduleWidth, showText, codeSet })` | 라벨 없이 바코드 그림만. |
| `qrSVG(value, { ecc, size })` | 라벨 없이 QR 그림만. |
| `measureText(text, sizeMm, font?, bold?)` | 글자 폭(mm). 브라우저에서는 canvas 로 잽니다. |
| `layoutPages(template, count, startAt?)` | 라벨 `count` 장의 페이지와 칸 좌표 `Page[]`. |
| `pageSize(template)` | 인쇄 페이지 크기 `{ width, height }` mm. |

## 바코드·QR

| 이름 | 설명 |
| --- | --- |
| `encodeBarcode(format, value, { codeSet? })` | 막대 모듈 배열과 사람이 읽는 글자. 잘못된 값이면 `BarcodeError`. |
| `eanCheckDigit(digits)` | EAN·UPC 체크 숫자. |
| `mod7Check(digits)` | 7로 나눈 나머지(일부 택배사 송장번호 검사). |
| `encodeQR(value, ecc?)` | QR 모듈 행렬. 너무 길면 `QrError`. |
| `BarcodeError, QrError` | 값 오류. |

## 필드

| 이름 | 설명 |
| --- | --- |
| `extractFields(template)` | 서식에 쓰인 `{{이름}}` 목록. |
| `fill(text, row, ctx?)` | `{{이름}}`·`{{이름\|서식}}`·`{{seq}}`·`{{today}}` 을 값으로 바꾼 글자. `ctx` = `{ index, serialStart, now }`. |
| `FIELD_FORMATS` | 값 서식 목록 `{ id, label, example }[]`. [값 서식](https://82label.app/docs/formats/) 참고. |
| `exampleRow(template)` | `fields[].example` 로 만든 예시 행. |
| `escapeXml(text)` | SVG·HTML 에 넣을 수 있게 이스케이프. |

## 용지와 단위

| 이름 | 설명 |
| --- | --- |
| `FORMTEC` | 폼텍 A4 시트 규격 목록 `SheetSpec[]`(코드, 칸, 크기, 여백, 확인 여부, 출처). |
| `ROLL_SIZES` | 자주 쓰는 롤 크기 `{ w, h, label, use }[]`. |
| `COURIERS` | 택배 서식 정보(공개 패키지에서는 빈 목록, 사이트가 채움). |
| `presetTemplate('roll', w, h) / presetTemplate('formtec', id)` | 빈 서식. |
| `SAMPLES / sampleTemplate(id)` | 무료 시작 서식: 쿠팡 로켓그로스 바코드(50×30, 60×40, 70×40, A4 21·40칸), 표시사항, 가격표, 자산 번호. |
| `sheetPaper(id)` | 폼텍 규격의 `paper` 객체. |
| `mmToPx(mm, dpi?), mmToDots(mm, dpi), ptToMm(pt), MM_PER_PT` | 단위 변환. |

## 기타

| 이름 | 설명 |
| --- | --- |
| `defineLabelElement(tag?)` | `<label-82>`(또는 다른 이름) 등록. CDN 빌드는 자동. |
| `VERSION` | 라이브러리 버전 문자열. |

## 타입

```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 };
```