npm package: @nitra/zebra
Description: Zebra printer
Author: nitra
Latest version: 8.2.1

# @nitra/zebra

Capacitor-плагін для друку ZPL на принтерах Zebra з підтримкою веб (Web Serial API), iOS та Android.

## Вимоги

- **Capacitor** 7.0.0 або новіший
- **Веб**: браузер з підтримкою [Web Serial API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API) (Chrome, Edge, Opera)
- **Android**: minSdk 23, targetSdk 35
- **iOS**: 16.0+

## Встановлення

```bash
npm install @nitra/zebra
npx cap sync
```

## API

### `print(zpl: string | PrintOptions): Promise<{ sent?: boolean }>`

Відправляє ZPL-команду на принтер Zebra.

| Платформа   | Поведінка                                                                                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Web**     | Запитує порт через Web Serial API, відкриває з'єднання (9600 baud) і відправляє рядок ZPL на вибраний пристрій.                                                     |
| **iOS**     | Друк по **Bluetooth (MFi)**. Принтер спочатку спарюють у Налаштування → Bluetooth; далі `getPairedDevices()` та `print({ zpl, address })`.                          |
| **Android** | Відправка ZPL по **Bluetooth Classic (SPP)**. Потрібно спочатку викликати `setPrinterAddress({ address: "MAC" })` або передати `address` (Bluetooth MAC) у виклику. |

**Параметри (об'єкт для Android):**

- `zpl` — рядок ZPL-команд (наприклад, `^XA^FO50,50^A0N,28,28^FDHello^FS^XZ`).
- `address` — (Android, опційно) Bluetooth MAC-адреса принтера (наприклад `00:11:22:33:44:55`); якщо не передано, використовується збережена через `setPrinterAddress()`.
- `port` — ігнорується (для сумісності API).

**Приклад:**

```javascript
import { Zebra } from '@nitra/zebra'

const zpl = '^XA^FO50,50^A0N,28,28^FDHello World^FS^XZ'
await Zebra.print(zpl)
```

### `setPrinterAddress(options: { address: string, port?: number }): Promise<{ address }>` (Android / iOS)

Зберігає Bluetooth MAC-адресу принтера Zebra для подальших викликів `print(zpl)` без передачі адреси.

**Параметри:**

- `address` — на Android: Bluetooth MAC (наприклад `00:11:22:33:44:55`); на iOS: серійний номер або ім'я з `getPairedDevices()`.
- `port` — ігнорується (для сумісності API).

**Приклад (Android):**

```javascript
await Zebra.setPrinterAddress({ address: '00:11:22:33:44:55' })
await Zebra.print(zpl)
```

**Приклад (iOS):** використовуйте `address` з `getPairedDevices()` (серійний номер або ім'я принтера).

### `getPairedDevices(): Promise<{ devices: { address: string, name: string }[] }>` (Android / iOS)

Повертає список пристроїв: на Android — спарені Bluetooth-пристрої; на iOS — підключені MFi-аксесуари (Bluetooth). Корисно для вибору принтера. На Android 12+ потрібен дозвіл **BLUETOOTH_CONNECT** (запитати до виклику).

**Приклад (Android):**

```javascript
const { devices } = await Zebra.getPairedDevices()
// devices: [{ address: "00:11:22:33:44:55", name: "Zebra ZD420" }, ...]
```

**Приклад (iOS):** той самий API; `address` — серійний номер або ім'я MFi-пристрою.

## Веб (Web Serial API)

На веб-платформі плагін використовує Web Serial API:

1. При виклику `print()` користувачу показується діалог вибору послідовного порту (принтер, підключений через USB).
2. Відкривається з'єднання з параметрами: 9600 baud, 8 data bits, no parity, 1 stop bit.
3. ZPL-рядок відправляється на пристрій.

**Обмеження:** Web Serial API працює лише в підтримуваних браузерах (Chrome, Edge, Opera) і зазвичай лише через HTTPS або localhost.

## Android (Bluetooth Classic)

На Android плагін відправляє ZPL на принтер Zebra по **Bluetooth Classic** (профіль SPP):

1. Спаріть принтер у налаштуваннях Bluetooth пристрою.
2. Викличте `getPairedDevices()` щоб отримати список пристроїв (опційно) або введіть MAC-адресу вручну.
3. Викличте `setPrinterAddress({ address: "MAC_ПРИНТЕРА" })` один раз (наприклад, з налаштувань) або передайте `address` у виклику `print({ zpl, address })`.
4. Викличте `print(zpl)` або `print({ zpl })` — ZPL буде відправлено на принтер по Bluetooth.

Потрібні дозволи **BLUETOOTH**, **BLUETOOTH_ADMIN** (до API 30), **BLUETOOTH_CONNECT** (API 31+). На Android 12+ дозвіл `BLUETOOTH_CONNECT` потрібно запитати під час виконання (наприклад перед `getPairedDevices()` або `print()`).

## iOS (Bluetooth MFi)

На iOS друк працює лише по **Bluetooth** через **ExternalAccessory** (MFi). Підключення по Lightning/USB не підтримується Apple для Zebra в цьому режимі.

1. **Спаріть принтер:** Налаштування → Bluetooth → увімкніть принтер і підключіть його.
2. **У додатку:** викличте `getPairedDevices()` — повернуться підключені Zebra-пристрої (`address` та `name`).
3. Викличте `setPrinterAddress({ address })` або передайте `address` у `print({ zpl, address })` (адреса — це `address` з `getPairedDevices()`: серійний номер або ім'я).
4. `print({ zpl, address })` відправляє ZPL на принтер по Bluetooth.

**Обов'язково:** У проєкті додатку в `ios/App/App/Info.plist` мають бути протоколи Zebra в `UISupportedExternalAccessoryProtocols`, інакше iOS не покаже принтер:

```xml
<key>UISupportedExternalAccessoryProtocols</key>
<array>
  <string>com.zebra.rawport</string>
  <string>com.zebra.print</string>
</array>
```

## Структура пакету

- `dist/` — зібраний JS-плагін (rolldown)
- `src/` — вихідний код: `index.js`, `definitions.js`, `web.js` (Web Serial реалізація)
- `ios/` — нативний iOS-плагін (Swift)
- `android/` — нативний Android-плагін (Java)

## Скрипти

| Команда          | Опис                                            |
| ---------------- | ----------------------------------------------- |
| `npm run build`  | Збірка плагіну (rolldown)                       |
| `npm run verify` | Перевірка iOS, Android та веб-збірки            |
| `npm run fmt`    | Форматування коду (ESLint, Prettier, SwiftLint) |
| `npm run lint`   | Перевірка стилю коду                            |

## Ліцензія

MIT