tauri-plugin-thermal-printer 1.1.0 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Andres Gonzalez Corzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,11 +7,9 @@ This plugin provides thermal printer functionality for Tauri applications, allow
 | Linux    | ✅        |
 | macOS    | ✅        |
 | Windows  | ✅        |
-| Android  | ❌        |
+| Android  | ?        |
 | iOS      | ❌        |
 
-For mobile applications, this plugin is currently working on this...
-
 ## Table of Contents
 
 - [How it Works](#how-it-works)
@@ -24,6 +22,8 @@ For mobile applications, this plugin is currently working on this...
   - [List Printers](#list-printers)
   - [Test Printer](#test-printer)
   - [Print Document](#print-document)
+  - [Paper Size Helpers (TypeScript)](#paper-size-helpers-typescript)
+  - [Error Handling](#error-handling)
 - [Section Types](#section-types)
   - [Title](#title)
   - [Subtitle](#subtitle)
@@ -41,6 +41,11 @@ For mobile applications, this plugin is currently working on this...
   - [Logo](#logo)
   - [Line](#line)
   - [GlobalStyles](#globalstyles)
+- [TypeScript Constants & Helpers](#typescript-constants--helpers)
+  - [CodePage](#codepage)
+  - [Style constants](#style-constants)
+  - [Section builder helpers](#section-builder-helpers)
+  - [Helper example (all builders)](#helper-example-all-builders)
 - [Examples](#examples)
 
 ## How it Works
@@ -50,13 +55,17 @@ This plugin acts as a **translator** between a user-friendly JavaScript/TypeScri
 ### Architecture
 
 ```
-Frontend (JavaScript/TypeScript) 
+Frontend (JavaScript/TypeScript)
     ↓ (IPC Commands)
-Tauri Core (Rust)
+Tauri Core (Rust)  ←— ESC/POS generation (shared across all platforms)
     ↓ (Platform-specific implementations)
-Operating System (Linux/macOS/Windows)
-    ↓ (Raw binary data)
-Thermal Printer (ESC/POS protocol)
+    ├── Desktop: Operating System (Linux/macOS/Windows)
+    │       ↓ (Raw binary data)
+    │   Thermal Printer (ESC/POS protocol)
+    │
+    └── Android: Kotlin Plugin
+            ↓ (Bluetooth SPP / RFCOMM)
+        Thermal Printer (ESC/POS protocol)
 ```
 
 ### Core Components
@@ -78,14 +87,14 @@ Converts data structures into ESC/POS binary commands:
 pub fn generate_document(&mut self, print_job: &PrintJobRequest) -> Result<Vec<u8>, String>
 ```
 
-#### 4. **OS Integration** (`src/desktop_printers/`)
+#### 4. **OS Integration** (`src/desktop_printers/` and `android/`)
 - **Linux/macOS**: Uses CUPS system (`lpstat`, `lp` commands)
 - **Windows**: Uses WinAPI (Windows API) to directly access system printers via functions such as EnumPrintersW for listing printers, OpenPrinterW for opening printer handles, and WritePrinter for sending raw data
-- **Android**: Basic structure present, not yet implemented
+- **Android**: Kotlin plugin with Bluetooth SPP and USB printer discovery and printing
 
 ### Workflow
 
-#### Printing a Document:
+#### Printing a Document (Desktop):
 
 1. **Frontend** sends `PrintJobRequest` with sections and configuration
 2. **Tauri** receives the command and processes it in Rust
@@ -93,6 +102,14 @@ pub fn generate_document(&mut self, print_job: &PrintJobRequest) -> Result<Vec<u
 4. **Operating System** sends binary data to the printer
 5. **Thermal Printer** interprets ESC/POS commands and prints
 
+#### Printing a Document (Android):
+
+1. **Frontend** sends `PrintJobRequest` with sections and configuration
+2. **Rust** generates ESC/POS binary data using the same `ProcessPrint` pipeline
+3. **Kotlin plugin** receives the binary data and the printer MAC address
+4. **Bluetooth SPP** connection is established to the printer
+5. **Thermal Printer** interprets ESC/POS commands and prints
+
 #### Print Structure Example:
 ```json
 {
@@ -133,15 +150,18 @@ The plugin translates all sections into **ESC/POS** (Escape Sequence for Point o
 - ✅ **Linux**: Fully functional (CUPS)
 - ✅ **macOS**: Fully functional (CUPS)
 - ✅ **Windows**: Fully functional (WinAPI)
-- ❌ **Android**: Basic structure present, not implemented
+- ✅ **Android**: Bluetooth and USB printer discovery and printing
 - ❌ **iOS**: Not implemented
 
 ### Supported Connections
 
-- **USB**: Direct USB port connection
-- **Network**: TCP/IP (port 9100 typical)
-- **Serial**: RS-232 (less common)
-- **Bluetooth**: For Android (when implemented)
+| Connection | Linux | macOS | Windows | Android |
+| ---------- | ----- | ----- | ------- | ------- |
+| USB        | ✅    | ✅    | ✅      | ✅ (discovery only) |
+| Network    | ✅    | ✅    | ✅      | ❌      |
+| Bluetooth  | ❌    | ❌    | ❌      | ✅      |
+
+> **Android note**: The `printer` field in `PrintJobRequest` must be the Bluetooth MAC address of the printer (e.g. `"AA:BB:CC:DD:EE:FF"`). The printer must be previously paired in the Android Bluetooth settings. Bluetooth permissions are requested automatically at runtime.
 
 ## Installation
 
@@ -215,7 +235,11 @@ Get all printers available in the system. It just lists the configured printers.
 ```typescript
 import { list_thermal_printers } from "tauri-plugin-thermal-printer";
 
-const response = await list_thermal_printers();
+try {
+  const response = await list_thermal_printers();
+} catch (error) {
+  console.log("List printers failed: " + error)
+}
 ```
 
 #### Response
@@ -252,7 +276,7 @@ Send a print test to a specific printer to verify functionality.
 ```typescript
 import { test_thermal_printer, type TestPrintRequest } from "tauri-plugin-thermal-printer";
 
-const response = await test_thermal_printer({
+try { await test_thermal_printer({
   "printer_info": {
     "printer": "TM-T20II",
     "paper_size": "Mm80",
@@ -280,7 +304,7 @@ const response = await test_thermal_printer({
   "test_all_fonts": false,
   "test_invert": false,
   "test_rotate": false
-} as TestPrintRequest)
+} as TestPrintRequest) } catch (error) { console.error("Test print failed:", error); }
 ```
 
 #### Request parameters (TestPrintRequest):
@@ -307,9 +331,7 @@ const response = await test_thermal_printer({
 | `test_rotate` | boolean | ❌ No | Text rotation test (default: `false`) |
 
 #### Response:
-Returns `boolean`:
-- `true`: Test completed successfully
-- `false`: Test failed
+Returns `Promise<void>`. Resolves when the test print completes successfully. **Throws a `string`** with the error message if it fails. Use `try/catch` to handle errors — see [Error Handling](#error-handling).
 
 ---
 
@@ -321,7 +343,7 @@ Print a personalized document with the specified sections.
 ```typescript
 import { print_thermal_printer, type PrintJobRequest } from "tauri-plugin-thermal-printer";
 
-const response = await print_thermal_printer({
+try { await print_thermal_printer({
   "printer": "TM-T20II",
   "paper_size": "Mm80",
   "options": {
@@ -338,34 +360,116 @@ const response = await print_thermal_printer({
     {"Beep": {"times": 1, "duration": 100}},
     {"Drawer": {"pin": 2, "pulse_time": 100}},
     {"Qr": {"data": "https://example.com", "size": 5, "error_correction": "M", "model": 2}},
-    {"Barcode": {"data": "123456789", "barcode_type": "CODE128", "width": 2, "height": 100, "text_position": "below"}},
-    {"Table": {"columns": 3, "column_widths": [10, 15, 10], "header": [{"text": "Col1"}, {"text": "Col2"}, {"text": "Col3"}], "body": [[{"text": "Data1"}, {"text": "Data2"}, {"text": "Data3"}]], "truncate": false}},
+    {"Barcode": {"data": "123456789012", "barcode_type": "CODE128", "width": 2, "height": 100, "text_position": "below"}},
+    {"Table": {"columns": 3, "column_widths": [16, 16, 16], "header": [{"text": "Col1"}, {"text": "Col2"}, {"text": "Col3"}], "body": [[{"text": "Data1"}, {"text": "Data2"}, {"text": "Data3"}]], "truncate": false}},
     {"DataMatrix": {"data": "DataMatrix data", "size": 5}},
     {"Pdf417": {"data": "PDF417 data", "columns": 2, "rows": 5, "width": 3, "height": 5, "error_correction": 2}},
-    {"Image": {"data": "{please introduce a base64 data image}", "max_width": 384, "align": "center", "dithering": true, "size": "normal"}},
+    {"Image": {"data": "{base64 image data}", "max_width": 384, "align": "center", "dithering": true, "size": "normal"}},
     {"Logo": {"key_code": 1, "mode": "normal"}},
     {"Line": {"character": "="}}
   ]
-} as PrintJobRequest)
+} as PrintJobRequest) } catch (error) { console.error("Print failed:", error); }
 ```
 
 #### Response:
-Returns `boolean`:
-- `true`: Print completed successfully
-- `false`: Print failed
+Returns `Promise<void>`. Resolves when printing completes successfully. **Throws a `string`** with the error message if the job fails (e.g., printer not found, invalid barcode data, QR data too long). Use `try/catch` to handle errors — see [Error Handling](#error-handling).
 
 #### Main parameters (PrintJobRequest):
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `printer` | string | ✅ Yes | Printer name |
-| `paper_size` | string | ❌ No | Paper size: `"Mm58"` or `"Mm80"` (default: `"Mm80"`) |
+| `paper_size` | PaperSize | ❌ No | Paper size (default: `"Mm80"`) — see [Paper Sizes](#paper-sizes) |
 | `options` | PrinterOptions | ❌ No | Configuration options |
 | `options.cut_paper` | boolean | ❌ No | Cut paper after printing (default: `true`) |
 | `options.beep` | boolean | ❌ No | Beep after printing (default: `false`) |
 | `options.open_cash_drawer` | boolean | ❌ No | Open cash drawer after printing (default: `false`) |
+| `options.code_page` | CodePage | ❌ No | Character encoding for special characters (default: `"Default"`) — see [CodePage](#codepage) |
 | `sections` | array | ✅ Yes | Array of sections to print (see [Section Types](#section-types)) |
 
+#### Paper Sizes
+
+| Value | Paper width | Chars/line | Typical use |
+|-------|-------------|------------|-------------|
+| `"Mm40"` | 40mm | 21 | Handheld ticket printers |
+| `"Mm44"` | 44mm | 24 | Compact POS |
+| `"Mm58"` | 58mm | 32 | Small format (most common portable) |
+| `"Mm72"` | 72mm | 42 | Mid-range printers |
+| `"Mm80"` | 80mm | 48 | Standard large format (default) |
+| `"Mm104"` | 104mm | 62 | Wide format |
+
+#### Paper Size Helpers (TypeScript)
+
+The TypeScript package exports constants and helper functions with the same values used by the Rust backend.
+
+```typescript
+import {
+  PAPER_SIZE_CHARS_PER_LINE,
+  PAPER_SIZE_PIXELS_WIDTH,
+  DEFAULT_PAPER_SIZE,
+  getPaperSizeCharsPerLine,
+  getPaperSizePixelsWidth,
+  type PaperSize,
+} from "tauri-plugin-thermal-printer";
+
+const size: PaperSize = "Mm58";
+
+console.log(DEFAULT_PAPER_SIZE); // "Mm80"
+console.log(PAPER_SIZE_CHARS_PER_LINE[size]); // 32
+console.log(PAPER_SIZE_PIXELS_WIDTH[size]); // 384
+
+// Equivalent helper functions:
+console.log(getPaperSizeCharsPerLine(size)); // 32
+console.log(getPaperSizePixelsWidth(size)); // 384
+```
+
+Values per paper size:
+
+| PaperSize | Chars/line | Pixels width |
+|-----------|------------|--------------|
+| `"Mm40"` | 21 | 256 |
+| `"Mm44"` | 24 | 288 |
+| `"Mm58"` | 32 | 384 |
+| `"Mm72"` | 42 | 512 |
+| `"Mm80"` | 48 | 576 |
+| `"Mm104"` | 62 | 752 |
+
+---
+
+### Error Handling
+
+`print_thermal_printer` and `test_thermal_printer` now return `Promise<void>` and **throw** a descriptive `string` when something fails. Always wrap calls in `try/catch`:
+
+```typescript
+import { print_thermal_printer, type PrintJobRequest } from "tauri-plugin-thermal-printer";
+
+try {
+  await print_thermal_printer(job);
+} catch (error) {
+  // `error` is a string describing what went wrong, e.g.:
+  // "Printer not specified"
+  // "Barcode data cannot be empty"
+  // "Barcode type 'EAN13' only accepts numeric digits"
+  // "QR data length 5000 exceeds maximum 4296 for error correction level 'M'"
+  // "Table row 2 has 2 cells but 3 columns declared"
+  // "column_widths sum (45) must equal paper chars_per_line (48)"
+  // "Image data cannot be empty"
+  console.error("Print failed:", error);
+}
+```
+
+`list_thermal_printers` also throws on failure (e.g., CUPS not available):
+
+```typescript
+try {
+  const printers = await list_thermal_printers();
+} catch (error) {
+  console.error("Could not list printers:", error);
+}
+```
+
+---
+
 #### Section Types
 
 Sections are defined as objects in the `sections` array. Each section is an enum variant with its data. Below are all supported section types:
@@ -503,8 +607,11 @@ Advances the paper by a specific number of lines.
 }
 ```
 
-- `feed_type` (string, required): Feed type ("lines")
-- `value` (number, required): Number of lines to advance
+- `feed_type` (string, required): Feed type:
+  - `"lines"` — advance N lines (`ESC d n`)
+  - `"dots"` — advance N dot rows (`ESC J n`)
+  - `"line_feed"` — send N raw LF characters
+- `value` (number, required): Amount to advance
 
 ##### Cut
 Cuts the paper.
@@ -518,7 +625,11 @@ Cuts the paper.
 }
 ```
 
-- `mode` (string, required): Cut mode ("full", "partial")
+- `mode` (string, required): Cut mode:
+  - `"full"` — full cut
+  - `"partial"` — partial cut (default fallback)
+  - `"partial_alt"` — partial cut (alternate)
+  - `"partial_alt2"` — full cut (alternate)
 - `feed` (number, required): Lines to advance before cutting
 
 ##### Beep
@@ -566,11 +677,11 @@ Prints a QR code.
 }
 ```
 
-- `data` (string, required): QR data
-- `size` (number, required): Module size (1-16)
-- `error_correction` (string, required): Error correction level ("L", "M", "Q", "H")
-- `model` (number, required): QR model (1 or 2)
-- `align` (string, optional): Alignment ("left", "center", "right")
+- `data` (string, required): QR data. **Must not be empty.** Maximum length depends on error correction level — the backend will throw if exceeded.
+- `size` (number, required): Module size (1–16)
+- `error_correction` (string, required): `"L"` (7089 chars max) | `"M"` (4296, default) | `"Q"` (2953) | `"H"` (1817)
+- `model` (number, required): QR model (`1` or `2`)
+- `align` (string, optional): `"left"` | `"center"` | `"right"`
 
 ##### Barcode
 Prints a barcode.
@@ -588,12 +699,12 @@ Prints a barcode.
 }
 ```
 
-- `data` (string, required): Barcode data
-- `barcode_type` (string, required): Type ("UPC-A", "UPC-E", "EAN13", "EAN8", "CODE39", "ITF", "CODABAR", "CODE93", "CODE128")
-- `width` (number, required): Module width
-- `height` (number, required): Height in dots
-- `text_position` (string, required): Text position ("not_printed", "above", "below", "both")
-- `align` (string, optional): Horizontal alignment ("left", "center", "right") (default: current global alignment)
+- `data` (string, required): Barcode data. **Must not be empty.** Numeric-only types (`UPC-A`, `UPC-E`, `EAN13`, `EAN8`, `ITF`) only accept digit characters — the backend will throw an error otherwise.
+- `barcode_type` (string, required): `"UPC-A"` | `"UPC-E"` | `"EAN13"` | `"EAN8"` | `"CODE39"` | `"ITF"` | `"CODABAR"` | `"CODE93"` | `"CODE128"`
+- `width` (number, required): Module width (1–6)
+- `height` (number, required): Height in dots (must be > 0)
+- `text_position` (string, required): `"none"` | `"above"` | `"below"` | `"both"`
+- `align` (string, optional): `"left"` | `"center"` | `"right"` (default: current global alignment)
 
 ##### Table
 Prints a table.
@@ -638,10 +749,10 @@ Or simply:
 ```
 
 - `columns` (number, required): Number of columns
-- `column_widths` (array, optional): Widths of each column. If not provided, columns will be evenly distributed across the paper width
-- `header` (array, optional): Column headers (array of Text objects)
-- `body` (array, required): Data rows (array of arrays of Text objects)
-- `truncate` (boolean, optional): Truncate long text (default: false)
+- `column_widths` (array, optional): Widths of each column in characters. **When provided: length must equal `columns` and the sum must equal the paper's chars/line** (e.g., 48 for Mm80). If omitted, columns are distributed evenly.
+- `header` (array, optional): Column headers — must have exactly `columns` elements if provided
+- `body` (array, required): Data rows — each row must have exactly `columns` cells
+- `truncate` (boolean, optional): Truncate long text instead of wrapping (default: `false`)
 
 ##### DataMatrix
 Prints a DataMatrix code.
@@ -696,11 +807,11 @@ Prints an image.
 }
 ```
 
-- `data` (string, required): Base64 encoded image
-- `max_width` (number, required): Maximum width in pixels
-- `align` (string, required): Alignment ("left", "center", "right")
-- `dithering` (boolean, required): Apply dithering
-- `size` (string, required): Size ("normal", "double_width", "double_height", "quadruple")
+- `data` (string, required): Base64 encoded image. **Must not be empty.**
+- `max_width` (number, required): Maximum width in pixels (0 or values larger than the paper width are clamped to the paper width automatically)
+- `align` (string, required): `"left"` | `"center"` | `"right"`
+- `dithering` (boolean, required): Apply Floyd-Steinberg dithering for better quality on monochrome printers
+- `size` (string, required): `"normal"` | `"double_width"` | `"double_height"` | `"quadruple"`
 
 ##### Logo
 Prints a logo stored in the printer.
@@ -762,6 +873,234 @@ Changes the current global styles that will be applied to subsequent text sectio
 
 ---
 
+## TypeScript Constants & Helpers
+
+The plugin exports typed constants and builder functions so you never have to type raw strings.
+
+### CodePage
+
+Set the character encoding once in `PrinterOptions.code_page` and all text sections (`Title`, `Subtitle`, `Text`, `Table`) will use it automatically.
+
+Each printer model assigns its own numbers to code pages, so `CodePage` accepts the raw page number directly via `codePage(n)`. Check your printer's manual for the correct value.
+
+```typescript
+import { codePage, CODE_PAGE, type CodePage } from "tauri-plugin-thermal-printer";
+
+const options = {
+  cut_paper: true,
+  beep: false,
+  open_cash_drawer: false,
+  code_page: codePage(2),  // sends ESC t 2 — CP850 on most Epson-compatible printers
+};
+```
+
+| Value | Description |
+|---|---|
+| `codePage(n)` | Sends `ESC t n` with the given number. The user is responsible for choosing the correct value for their printer model. |
+| `CODE_PAGE.ACCENT_REMOVER` | Removes accents and special characters by converting them to their ASCII equivalents (á→a, ß→ss, ¿→?, €→EUR). Useful when printers do not support alternative code pages. |
+
+> **Note**: Without a `code_page`, accented characters (á, ñ, ü, etc.) will print as `?`. Set it once in `options` and it applies to the entire document.
+
+---
+
+### Style constants
+
+Instead of typing raw strings you can import typed constant objects:
+
+```typescript
+import {
+  TEXT_ALIGN,
+  TEXT_SIZE,
+  TEXT_FONT,
+  BARCODE_TYPE,
+  BARCODE_TEXT_POSITION,
+  QR_ERROR_CORRECTION,
+  IMAGE_MODE,
+  CUT_MODE,
+} from "tauri-plugin-thermal-printer";
+
+// Examples:
+const styles = {
+  align: TEXT_ALIGN.CENTER,   // "center"
+  size: TEXT_SIZE.DOUBLE,     // "double"
+  font: TEXT_FONT.B,          // "B"
+  bold: true,
+};
+
+const barcode = {
+  barcode_type: BARCODE_TYPE.EAN13,             // "EAN13"
+  text_position: BARCODE_TEXT_POSITION.BELOW,   // "below"
+};
+
+const qr = {
+  error_correction: QR_ERROR_CORRECTION.M,      // "M"
+};
+```
+
+| Export | Values |
+|---|---|
+| `TEXT_ALIGN` | `LEFT` `CENTER` `RIGHT` |
+| `TEXT_SIZE` | `NORMAL` `HEIGHT` `WIDTH` `DOUBLE` |
+| `TEXT_FONT` | `A` `B` `C` |
+| `BARCODE_TYPE` | `UPC_A` `UPC_E` `EAN13` `EAN8` `CODE39` `ITF` `CODABAR` `CODE93` `CODE128` |
+| `BARCODE_TEXT_POSITION` | `NONE` `ABOVE` `BELOW` `BOTH` |
+| `QR_ERROR_CORRECTION` | `L` `M` `Q` `H` |
+| `IMAGE_MODE` | `NORMAL` `DOUBLE_WIDTH` `DOUBLE_HEIGHT` `QUADRUPLE` |
+| `CUT_MODE` | `FULL` `PARTIAL` |
+
+---
+
+### Section builder helpers
+
+Short helper functions to build section types without enum wrapper boilerplate:
+
+```typescript
+import {
+  title, subtitle, text, line, feed, cut, globalStyles,
+  beep, drawer, table, qr, barcode, dataMatrix, pdf417, image, logo,
+  TEXT_ALIGN, TEXT_SIZE, BARCODE_TYPE, QR_ERROR_CORRECTION,
+} from "tauri-plugin-thermal-printer";
+
+const sections = [
+  title("My Business"),
+  subtitle("Receipt #001"),
+  text("Thank you for your purchase!", { align: TEXT_ALIGN.CENTER }),
+  line("="),
+  qr("https://example.com/order/123", {
+    size: 6,
+    error_correction: QR_ERROR_CORRECTION.M,
+  }),
+  barcode("123456789012", BARCODE_TYPE.EAN13),
+  beep(),
+  text("Total: $50.00", { bold: true, size: TEXT_SIZE.DOUBLE }),
+  line("-"),
+  feed(3),
+  cut(),
+];
+```
+
+| Helper | Description |
+|---|---|
+| `title(text, styles?)` | Creates a `{ Title: ... }` section |
+| `subtitle(text, styles?)` | Creates a `{ Subtitle: ... }` section |
+| `text(text, styles?)` | Creates a `{ Text: ... }` section |
+| `line(character?)` | Creates a `{ Line: ... }` section (default `"-"`) |
+| `feed(value, type?)` | Creates a `{ Feed: ... }` section (default `"lines"`) |
+| `cut(mode?, feedLines?)` | Creates a `{ Cut: ... }` section (default `"partial"`, 4 lines) |
+| `globalStyles(styles)` | Creates a `{ GlobalStyles: ... }` section |
+| `beep(times?, duration?)` | Creates a `{ Beep: ... }` section (default `1`, `3`) |
+| `drawer(pin?, pulse_time?)` | Creates a `{ Drawer: ... }` section (default `2`, `120`) |
+| `table(columns, body, options?)` | Creates a `{ Table: ... }` section (`truncate` default `true`) |
+| `qr(data, options?)` | Creates a `{ Qr: ... }` section (`size=6`, `error_correction="M"`, `model=2`) |
+| `barcode(data, barcode_type?, options?)` | Creates a `{ Barcode: ... }` section (`CODE128`, `width=3`, `height=80`, `text_position="below"`) |
+| `dataMatrix(data, size?)` | Creates a `{ DataMatrix: ... }` section (default `size=6`) |
+| `pdf417(data, options?)` | Creates a `{ Pdf417: ... }` section (`columns=0`, `rows=0`, `width=2`, `height=3`, `error_correction=2`) |
+| `image(data, options?)` | Creates a `{ Image: ... }` section (`max_width=0`, `align="center"`, `dithering=true`, `size="normal"`) |
+| `logo(key_code, mode?)` | Creates a `{ Logo: ... }` section (default `mode="normal"`) |
+
+### Helper example (all builders)
+
+```typescript
+import {
+  print_thermal_printer,
+  type PrintJobRequest,
+  title,
+  subtitle,
+  text,
+  line,
+  feed,
+  cut,
+  globalStyles,
+  beep,
+  drawer,
+  table,
+  qr,
+  barcode,
+  dataMatrix,
+  pdf417,
+  image,
+  logo,
+  TEXT_ALIGN,
+  TEXT_SIZE,
+  BARCODE_TYPE,
+  BARCODE_TEXT_POSITION,
+  QR_ERROR_CORRECTION,
+  IMAGE_MODE,
+  CODE_PAGE,
+} from "tauri-plugin-thermal-printer";
+
+const job: PrintJobRequest = {
+  printer: "TM-T20II",
+  paper_size: "Mm80",
+  options: {
+    cut_paper: true,
+    beep: false,
+    open_cash_drawer: false,
+    code_page: CODE_PAGE.WINDOWS_LATIN,
+  },
+  sections: [
+    globalStyles({ align: TEXT_ALIGN.LEFT }),
+    title("DEMO STORE"),
+    subtitle("Receipt #A-1001"),
+    text("Date: 2026-03-30 14:22"),
+    line("="),
+    table(
+      3,
+      [
+        [text("1"), text("Americano"), text("$2.50", { align: TEXT_ALIGN.RIGHT })],
+        [text("2"), text("Croissant"), text("$7.00", { align: TEXT_ALIGN.RIGHT })],
+      ],
+      {
+        column_widths: [6, 28, 14],
+        header: [
+          text("QTY", { bold: true }),
+          text("ITEM", { bold: true }),
+          text("TOTAL", { bold: true, align: TEXT_ALIGN.RIGHT }),
+        ],
+        truncate: true,
+      },
+    ),
+    line("-"),
+    text("Grand total: $9.50", { bold: true, size: TEXT_SIZE.DOUBLE, align: TEXT_ALIGN.RIGHT }),
+    qr("https://example.com/r/A-1001", {
+      size: 6,
+      error_correction: QR_ERROR_CORRECTION.M,
+      model: 2,
+      align: TEXT_ALIGN.CENTER,
+    }),
+    barcode("123456789012", BARCODE_TYPE.EAN13, {
+      width: 3,
+      height: 70,
+      text_position: BARCODE_TEXT_POSITION.BELOW,
+      align: TEXT_ALIGN.CENTER,
+    }),
+    dataMatrix("A-1001", 6),
+    pdf417("A-1001|TOTAL=9.50|PAID", {
+      columns: 0,
+      rows: 0,
+      width: 2,
+      height: 3,
+      error_correction: 2,
+    }),
+    image("<BASE64_IMAGE>", {
+      max_width: 0,
+      align: TEXT_ALIGN.CENTER,
+      dithering: true,
+      size: IMAGE_MODE.NORMAL,
+    }),
+    logo(1, IMAGE_MODE.NORMAL),
+    drawer(2, 120),
+    beep(1, 3),
+    feed(3),
+    cut(),
+  ],
+};
+
+await print_thermal_printer(job);
+```
+
+---
+
 ## Examples
 
 This section contains practical examples for different use cases. Each example demonstrates how to structure print jobs for various business scenarios.
@@ -1221,6 +1560,8 @@ const paymentReceipt: PrintJobRequest = {
 };
 ```
 
+
+
 ---
 
 ### 📋 Summary