@devlas/capacitor-thermal-printer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devlas SpA
+
+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

@@ -0,0 +1,103 @@
+# @devlas/capacitor-thermal-printer
+
+Adaptador universal de impresión térmica **ESC/POS** para Capacitor (Android): **USB (OTG)**, **TCP/LAN/WiFi** y **Bluetooth SPP** con una sola API de bytes crudos.
+
+- **Bytes crudos, no formateo**: la app codifica el ticket ESC/POS (con su propio encoder) y el plugin solo lo transporta. Así el mismo encoder sirve para Electron, Web Serial, WebUSB y esta app nativa.
+- **Stateless**: cada `print()` conecta → escribe → cierra. Sin estado de conexión que se corrompa.
+- **Sin dependencias nativas**: `UsbManager`, `Socket` y `BluetoothSocket` del framework Android, nada más.
+- **Permisos modernos**: flujo USB compatible con Android 12/14+ (`FLAG_MUTABLE` + intent explícito + `RECEIVER_NOT_EXPORTED`), `BLUETOOTH_CONNECT` runtime en API 31+.
+- **Base64 en el bridge**: los bytes viajan como base64 — sin corrupción UTF-8 (el bug clásico de los plugins BT de la comunidad).
+
+> Matriz de transportes, librerías evaluadas y decisiones de diseño: [docs/TRANSPORTES.md](docs/TRANSPORTES.md)
+
+## Instalación
+
+```bash
+npm i @devlas/capacitor-thermal-printer
+npx cap sync android
+```
+
+Sin pasos extra: no requiere JitPack ni repositorios Maven adicionales.
+
+## API
+
+```ts
+import { ThermalPrinter, bytesToBase64 } from '@devlas/capacitor-thermal-printer'
+```
+
+### `list({ transport })`
+
+Lista dispositivos disponibles. `transport: 'usb' | 'bluetooth'` (TCP no es listable — la IP la ingresa el usuario).
+
+```ts
+const { devices } = await ThermalPrinter.list({ transport: 'usb' })
+// [{ transport: 'usb', vendorId: 1155, productId: 22304, name: 'POS58 Printer',
+//    canPrint: true, hasPermission: false, deviceId: 1002 }]
+
+const { devices } = await ThermalPrinter.list({ transport: 'bluetooth' })
+// [{ transport: 'bluetooth', address: '66:22:...', name: 'PT-210' }]
+// (solo emparejados — la impresora se empareja desde Ajustes del sistema)
+```
+
+### `requestPermission(target)`
+
+```ts
+// USB: diálogo del sistema por dispositivo. El permiso persiste hasta desconectar
+// el cable (o para siempre si el usuario marca "usar por defecto").
+const { granted } = await ThermalPrinter.requestPermission({
+  transport: 'usb', vendorId: 1155, productId: 22304,
+})
+
+// Bluetooth: permiso runtime BLUETOOTH_CONNECT (API 31+)
+await ThermalPrinter.requestPermission({ transport: 'bluetooth', address: '66:22:...' })
+
+// TCP: siempre { granted: true }
+```
+
+### `print(target & { data })`
+
+`data` = bytes ESC/POS en **base64** (usa el helper `bytesToBase64`).
+
+```ts
+const bytes: Uint8Array = miEncoderEscPos(ticket)   // el encoder es de la app
+
+// USB — si se omiten vendorId/productId usa la primera impresora detectada
+await ThermalPrinter.print({ transport: 'usb', vendorId: 1155, productId: 22304, data: bytesToBase64(bytes) })
+
+// TCP / LAN / WiFi — raw 9100 (JetDirect)
+await ThermalPrinter.print({ transport: 'tcp', host: '192.168.1.50', port: 9100, data: bytesToBase64(bytes) })
+
+// Bluetooth SPP
+await ThermalPrinter.print({ transport: 'bluetooth', address: '66:22:...', data: bytesToBase64(bytes) })
+```
+
+### Códigos de error
+
+`error.code` estable para manejar en JS:
+
+| Código | Significado |
+|---|---|
+| `unavailable` | El transporte no existe en el equipo (sin USB host / sin adaptador BT) |
+| `not_found` | Dispositivo no encontrado (desconectado, MAC inválida) |
+| `permission_denied` | Permiso USB o BLUETOOTH_CONNECT denegado |
+| `connect_failed` | No se pudo abrir la conexión (timeout TCP, socket BT, claim USB) |
+| `write_failed` | La escritura falló a mitad de trabajo |
+| `invalid_transport` / `invalid_data` | Parámetros mal formados |
+
+## Plataformas
+
+| Plataforma | Estado |
+|---|---|
+| Android (Capacitor WebView) | ✅ usb / tcp / bluetooth |
+| Web | ❌ stub — en navegador usa WebUSB / Web Serial directamente |
+| iOS | ❌ sin USB host ni SPP; ver [docs/TRANSPORTES.md](docs/TRANSPORTES.md) |
+
+## Publicar
+
+```bash
+npm publish --access public
+```
+
+## Licencia
+
+MIT © [Devlas SpA](https://devlas.cl)

package/android/build.gradle

@@ -0,0 +1,47 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    kotlinVersion = '1.9.22'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.2.1'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace "app.devlas.plugins.thermalprinter"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- USB host (OTG) — required=false: el plugin también sirve por TCP/BT en equipos sin OTG -->
+    <uses-feature android:name="android.hardware.usb.host" android:required="false" />
+
+    <!-- TCP/LAN/WiFi (raw 9100) -->
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <!-- Bluetooth SPP: legacy hasta API 30, BLUETOOTH_CONNECT runtime desde API 31 -->
+    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+
+</manifest>

package/android/src/main/java/app/devlas/plugins/thermalprinter/BluetoothTransport.kt

@@ -0,0 +1,75 @@
+package app.devlas.plugins.thermalprinter
+
+import android.annotation.SuppressLint
+import android.bluetooth.BluetoothManager
+import android.content.Context
+import com.getcapacitor.JSArray
+import com.getcapacitor.JSObject
+import java.io.IOException
+import java.util.UUID
+
+/**
+ * Transporte Bluetooth clásico (SPP/RFCOMM) — el perfil de las térmicas BT
+ * (PT-210, MTP-II, Rongta, Xprinter…). La impresora debe estar emparejada
+ * desde Ajustes del sistema; aquí solo se listan los dispositivos vinculados.
+ *
+ * El permiso BLUETOOTH_CONNECT (API 31+) lo gestiona ThermalPrinterPlugin
+ * vía el alias de permisos de Capacitor antes de llegar acá.
+ */
+class BluetoothTransport(private val context: Context) {
+
+    companion object {
+        /** UUID estándar del Serial Port Profile. */
+        private val SPP_UUID: UUID = UUID.fromString("00001101-0000-1000-8000-00805F9B34FB")
+        private const val CHUNK_SIZE = 1024
+    }
+
+    private val adapter
+        get() = (context.getSystemService(Context.BLUETOOTH_SERVICE) as? BluetoothManager)?.adapter
+
+    @SuppressLint("MissingPermission") // verificado por el plugin antes de llamar
+    fun list(): JSArray {
+        val result = JSArray()
+        val a = adapter ?: throw PrinterException("unavailable", "Bluetooth no disponible en este dispositivo")
+        for (device in a.bondedDevices) {
+            val obj = JSObject()
+            obj.put("transport", "bluetooth")
+            obj.put("address", device.address)
+            obj.put("name", device.name ?: device.address)
+            result.put(obj)
+        }
+        return result
+    }
+
+    /** Stateless: conecta → escribe chunked → flush → cierra. */
+    @SuppressLint("MissingPermission")
+    fun print(address: String, bytes: ByteArray) {
+        val a = adapter ?: throw PrinterException("unavailable", "Bluetooth no disponible en este dispositivo")
+        val device = try {
+            a.getRemoteDevice(address)
+        } catch (e: IllegalArgumentException) {
+            throw PrinterException("not_found", "Dirección Bluetooth inválida: $address")
+        }
+        try {
+            a.cancelDiscovery() // discovery activo degrada la conexión SPP
+            device.createRfcommSocketToServiceRecord(SPP_UUID).use { socket ->
+                socket.connect()
+                val out = socket.outputStream
+                var offset = 0
+                while (offset < bytes.size) {
+                    val len = minOf(CHUNK_SIZE, bytes.size - offset)
+                    out.write(bytes, offset, len)
+                    offset += len
+                }
+                out.flush()
+                // ponytail: conexión por trabajo (~1-2s de latencia BT por ticket);
+                // pool keep-alive si la latencia molesta en caja.
+                Thread.sleep(minOf(2000L, bytes.size / 16L))
+            }
+        } catch (e: SecurityException) {
+            throw PrinterException("permission_denied", "Sin permiso BLUETOOTH_CONNECT")
+        } catch (e: IOException) {
+            throw PrinterException("connect_failed", "No se pudo imprimir en $address: ${e.message}")
+        }
+    }
+}

package/android/src/main/java/app/devlas/plugins/thermalprinter/PrinterException.kt

@@ -0,0 +1,8 @@
+package app.devlas.plugins.thermalprinter
+
+/**
+ * Error con código estable que llega a JS como `error.code`:
+ * unavailable | not_found | permission_denied | connect_failed
+ * | write_failed | invalid_transport | invalid_data
+ */
+class PrinterException(val code: String, message: String) : Exception(message)

package/android/src/main/java/app/devlas/plugins/thermalprinter/TcpTransport.kt

@@ -0,0 +1,41 @@
+package app.devlas.plugins.thermalprinter
+
+import java.io.IOException
+import java.net.InetSocketAddress
+import java.net.Socket
+import java.net.SocketTimeoutException
+
+/**
+ * Transporte TCP — impresión raw a puerto 9100 (JetDirect), el estándar de
+ * térmicas de red cableada y WiFi. Sin librerías: un Socket y ya.
+ */
+class TcpTransport {
+
+    companion object {
+        private const val CONNECT_TIMEOUT_MS = 4000
+        private const val CHUNK_SIZE = 8192
+    }
+
+    fun print(host: String, port: Int, bytes: ByteArray) {
+        try {
+            Socket().use { socket ->
+                socket.connect(InetSocketAddress(host, port), CONNECT_TIMEOUT_MS)
+                val out = socket.getOutputStream()
+                var offset = 0
+                while (offset < bytes.size) {
+                    val len = minOf(CHUNK_SIZE, bytes.size - offset)
+                    out.write(bytes, offset, len)
+                    offset += len
+                }
+                out.flush()
+                // Espera proporcional antes de cerrar — evita truncar el búfer de la
+                // impresora en trabajos grandes (patrón DantSu: ~1ms por 16 bytes).
+                Thread.sleep(minOf(2000L, bytes.size / 16L))
+            }
+        } catch (e: SocketTimeoutException) {
+            throw PrinterException("connect_failed", "Timeout conectando a $host:$port")
+        } catch (e: IOException) {
+            throw PrinterException("connect_failed", "No se pudo imprimir en $host:$port: ${e.message}")
+        }
+    }
+}

package/android/src/main/java/app/devlas/plugins/thermalprinter/ThermalPrinterPlugin.kt

@@ -0,0 +1,137 @@
+package app.devlas.plugins.thermalprinter
+
+import android.Manifest
+import android.util.Base64
+import com.getcapacitor.JSObject
+import com.getcapacitor.PermissionState
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import com.getcapacitor.annotation.Permission
+import com.getcapacitor.annotation.PermissionCallback
+import java.util.concurrent.Executors
+
+@CapacitorPlugin(
+    name = "ThermalPrinter",
+    permissions = [
+        Permission(alias = "bluetooth", strings = [Manifest.permission.BLUETOOTH_CONNECT])
+    ]
+)
+class ThermalPrinterPlugin : Plugin() {
+
+    // Un solo hilo: serializa los trabajos (nunca dos impresiones concurrentes al
+    // mismo dispositivo) y saca el I/O bloqueante (sockets, bulkTransfer) del main.
+    private val executor = Executors.newSingleThreadExecutor()
+
+    private val usb by lazy { UsbTransport(context) }
+    private val tcp = TcpTransport()
+    private val bluetooth by lazy { BluetoothTransport(context) }
+
+    override fun handleOnDestroy() {
+        executor.shutdown()
+    }
+
+    // ── list ─────────────────────────────────────────────────────────────
+
+    @PluginMethod
+    fun list(call: PluginCall) {
+        when (call.getString("transport")) {
+            "usb" -> call.resolve(JSObject().put("devices", usb.list()))
+            "bluetooth" -> {
+                if (getPermissionState("bluetooth") != PermissionState.GRANTED) {
+                    requestPermissionForAlias("bluetooth", call, "bluetoothListCallback")
+                    return
+                }
+                resolveBluetoothList(call)
+            }
+            else -> call.reject("transport debe ser 'usb' o 'bluetooth'", "invalid_transport")
+        }
+    }
+
+    @PermissionCallback
+    private fun bluetoothListCallback(call: PluginCall) {
+        if (getPermissionState("bluetooth") == PermissionState.GRANTED) {
+            resolveBluetoothList(call)
+        } else {
+            call.reject("Permiso Bluetooth denegado", "permission_denied")
+        }
+    }
+
+    private fun resolveBluetoothList(call: PluginCall) {
+        try {
+            call.resolve(JSObject().put("devices", bluetooth.list()))
+        } catch (e: PrinterException) {
+            call.reject(e.message, e.code)
+        }
+    }
+
+    // ── requestPermission ────────────────────────────────────────────────
+
+    @PluginMethod
+    fun requestPermission(call: PluginCall) {
+        when (call.getString("transport")) {
+            "usb" -> usb.requestPermission(
+                vendorId = call.getInt("vendorId"),
+                productId = call.getInt("productId"),
+                onResult = { granted -> call.resolve(JSObject().put("granted", granted)) },
+                onError = { code, msg -> call.reject(msg, code) },
+            )
+            "bluetooth" -> {
+                if (getPermissionState("bluetooth") == PermissionState.GRANTED) {
+                    call.resolve(JSObject().put("granted", true))
+                } else {
+                    requestPermissionForAlias("bluetooth", call, "bluetoothPermissionCallback")
+                }
+            }
+            "tcp" -> call.resolve(JSObject().put("granted", true))
+            else -> call.reject("transport debe ser 'usb', 'tcp' o 'bluetooth'", "invalid_transport")
+        }
+    }
+
+    @PermissionCallback
+    private fun bluetoothPermissionCallback(call: PluginCall) {
+        call.resolve(JSObject().put("granted", getPermissionState("bluetooth") == PermissionState.GRANTED))
+    }
+
+    // ── print ────────────────────────────────────────────────────────────
+
+    @PluginMethod
+    fun print(call: PluginCall) {
+        val data = call.getString("data")
+        if (data.isNullOrEmpty()) {
+            call.reject("Falta 'data' (bytes ESC/POS en base64)", "invalid_data")
+            return
+        }
+        val bytes = try {
+            Base64.decode(data, Base64.DEFAULT)
+        } catch (e: IllegalArgumentException) {
+            call.reject("'data' no es base64 válido", "invalid_data")
+            return
+        }
+        val transport = call.getString("transport")
+        executor.execute {
+            try {
+                when (transport) {
+                    "usb" -> usb.print(call.getInt("vendorId"), call.getInt("productId"), bytes)
+                    "tcp" -> {
+                        val host = call.getString("host")
+                            ?: throw PrinterException("connect_failed", "Falta 'host' para transporte tcp")
+                        tcp.print(host, call.getInt("port") ?: 9100, bytes)
+                    }
+                    "bluetooth" -> {
+                        val address = call.getString("address")
+                            ?: throw PrinterException("not_found", "Falta 'address' para transporte bluetooth")
+                        bluetooth.print(address, bytes)
+                    }
+                    else -> throw PrinterException("invalid_transport", "transport debe ser 'usb', 'tcp' o 'bluetooth'")
+                }
+                call.resolve()
+            } catch (e: PrinterException) {
+                call.reject(e.message, e.code)
+            } catch (e: Exception) {
+                call.reject(e.message ?: "Error de impresión", "write_failed")
+            }
+        }
+    }
+}

package/android/src/main/java/app/devlas/plugins/thermalprinter/UsbTransport.kt

@@ -0,0 +1,146 @@
+package app.devlas.plugins.thermalprinter
+
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.hardware.usb.UsbConstants
+import android.hardware.usb.UsbDevice
+import android.hardware.usb.UsbEndpoint
+import android.hardware.usb.UsbInterface
+import android.hardware.usb.UsbManager
+import android.os.Build
+import androidx.core.content.ContextCompat
+import com.getcapacitor.JSArray
+import com.getcapacitor.JSObject
+
+/**
+ * Transporte USB host (OTG) — habla directo con UsbManager, sin librerías.
+ *
+ * Selección de interfaz: prefiere la de clase impresora (USB_CLASS_PRINTER);
+ * si el dispositivo no la declara (térmicas genéricas con clase vendor-specific),
+ * cae a la primera interfaz con endpoint bulk OUT — heurística equivalente a la
+ * usada por WebUSB en navegador, validada con hardware real.
+ */
+class UsbTransport(private val context: Context) {
+
+    companion object {
+        private const val ACTION_USB_PERMISSION = "app.devlas.plugins.thermalprinter.USB_PERMISSION"
+        private const val CHUNK_SIZE = 4096
+        private const val TRANSFER_TIMEOUT_MS = 3000
+    }
+
+    private val usbManager: UsbManager?
+        get() = context.getSystemService(Context.USB_SERVICE) as? UsbManager
+
+    fun list(): JSArray {
+        val result = JSArray()
+        val manager = usbManager ?: return result
+        for (device in manager.deviceList.values) {
+            val obj = JSObject()
+            obj.put("transport", "usb")
+            obj.put("deviceId", device.deviceId)
+            obj.put("vendorId", device.vendorId)
+            obj.put("productId", device.productId)
+            obj.put("name", device.productName ?: device.deviceName)
+            obj.put("canPrint", findPrinterInterface(device) != null)
+            obj.put("hasPermission", manager.hasPermission(device))
+            result.put(obj)
+        }
+        return result
+    }
+
+    /**
+     * Flujo de permiso compatible con Android 12/14+:
+     * PendingIntent MUTABLE (el sistema rellena EXTRA_PERMISSION_GRANTED),
+     * intent explícito (setPackage) y receiver RECEIVER_NOT_EXPORTED.
+     * Ninguno de los plugins de la comunidad revisados hace esto correctamente.
+     */
+    fun requestPermission(
+        vendorId: Int?,
+        productId: Int?,
+        onResult: (granted: Boolean) -> Unit,
+        onError: (code: String, msg: String) -> Unit,
+    ) {
+        val manager = usbManager ?: return onError("unavailable", "USB no disponible en este dispositivo")
+        val device = findDevice(manager, vendorId, productId)
+            ?: return onError("not_found", "No se encontró una impresora USB conectada")
+        if (manager.hasPermission(device)) return onResult(true)
+
+        val intent = Intent(ACTION_USB_PERMISSION).setPackage(context.packageName)
+        val flags = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) PendingIntent.FLAG_MUTABLE else 0
+        val pendingIntent = PendingIntent.getBroadcast(context, 0, intent, flags)
+
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(ctx: Context, received: Intent) {
+                if (received.action != ACTION_USB_PERMISSION) return
+                try { context.unregisterReceiver(this) } catch (_: Exception) { /* ya removido */ }
+                onResult(received.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false))
+            }
+        }
+        ContextCompat.registerReceiver(
+            context, receiver, IntentFilter(ACTION_USB_PERMISSION), ContextCompat.RECEIVER_NOT_EXPORTED
+        )
+        manager.requestPermission(device, pendingIntent)
+    }
+
+    /** Stateless: abre → reclama interfaz → escribe chunked → libera → cierra. */
+    fun print(vendorId: Int?, productId: Int?, bytes: ByteArray) {
+        val manager = usbManager
+            ?: throw PrinterException("unavailable", "USB no disponible en este dispositivo")
+        val device = findDevice(manager, vendorId, productId)
+            ?: throw PrinterException("not_found", "No se encontró una impresora USB conectada")
+        if (!manager.hasPermission(device)) {
+            throw PrinterException("permission_denied", "Sin permiso USB — llama a requestPermission() primero")
+        }
+        val (iface, endpoint) = findPrinterInterface(device)
+            ?: throw PrinterException("not_found", "El dispositivo no tiene endpoint de salida (bulk OUT)")
+        val connection = manager.openDevice(device)
+            ?: throw PrinterException("connect_failed", "No se pudo abrir el dispositivo USB")
+        try {
+            if (!connection.claimInterface(iface, true)) {
+                throw PrinterException("connect_failed", "No se pudo reclamar la interfaz USB")
+            }
+            var offset = 0
+            while (offset < bytes.size) {
+                val len = minOf(CHUNK_SIZE, bytes.size - offset)
+                val sent = connection.bulkTransfer(endpoint, bytes, offset, len, TRANSFER_TIMEOUT_MS)
+                if (sent < 0) throw PrinterException("write_failed", "bulkTransfer falló en offset $offset")
+                offset += sent
+            }
+        } finally {
+            try { connection.releaseInterface(iface) } catch (_: Exception) { /* best effort */ }
+            connection.close()
+        }
+    }
+
+    private fun findDevice(manager: UsbManager, vendorId: Int?, productId: Int?): UsbDevice? {
+        val devices = manager.deviceList.values
+        if (vendorId != null && productId != null) {
+            return devices.firstOrNull { it.vendorId == vendorId && it.productId == productId }
+        }
+        return devices.firstOrNull { findPrinterInterface(it) != null }
+    }
+
+    private fun findPrinterInterface(device: UsbDevice): Pair<UsbInterface, UsbEndpoint>? {
+        var fallback: Pair<UsbInterface, UsbEndpoint>? = null
+        for (i in 0 until device.interfaceCount) {
+            val iface = device.getInterface(i)
+            val out = bulkOutEndpoint(iface) ?: continue
+            if (iface.interfaceClass == UsbConstants.USB_CLASS_PRINTER) return iface to out
+            if (fallback == null) fallback = iface to out
+        }
+        return fallback
+    }
+
+    private fun bulkOutEndpoint(iface: UsbInterface): UsbEndpoint? {
+        for (j in 0 until iface.endpointCount) {
+            val ep = iface.getEndpoint(j)
+            if (ep.type == UsbConstants.USB_ENDPOINT_XFER_BULK && ep.direction == UsbConstants.USB_DIR_OUT) {
+                return ep
+            }
+        }
+        return null
+    }
+}

package/dist/esm/definitions.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @devlas/capacitor-thermal-printer — definiciones públicas.
+ *
+ * Filosofía: el plugin transporta BYTES CRUDOS (ESC/POS ya codificado por la app).
+ * No formatea texto, no conoce comandos — eso permite reusar el mismo encoder
+ * en todas las plataformas (Electron, Web Serial, WebUSB y esta app nativa).
+ */
+export type PrinterTransport = 'usb' | 'tcp' | 'bluetooth';
+export interface PrinterDevice {
+    transport: PrinterTransport;
+    /** Nombre legible del dispositivo (productName USB / nombre BT). */
+    name?: string;
+    vendorId?: number;
+    productId?: number;
+    /** ID de sesión Android — cambia al reconectar; usar vendorId+productId para persistir. */
+    deviceId?: number;
+    /** true si el dispositivo tiene un endpoint bulk OUT (puede recibir impresión). */
+    canPrint?: boolean;
+    /** true si Android ya otorgó permiso USB a este dispositivo. */
+    hasPermission?: boolean;
+    /** Dirección MAC del dispositivo emparejado. */
+    address?: string;
+}
+export interface UsbTarget {
+    transport: 'usb';
+    /** Si se omiten vendorId/productId, usa la primera impresora USB detectada. */
+    vendorId?: number;
+    productId?: number;
+}
+export interface TcpTarget {
+    transport: 'tcp';
+    host: string;
+    /** Puerto raw/JetDirect. Default: 9100. */
+    port?: number;
+}
+export interface BluetoothTarget {
+    transport: 'bluetooth';
+    /** MAC del dispositivo (debe estar emparejado en Ajustes del sistema). */
+    address: string;
+}
+export type PrintTarget = UsbTarget | TcpTarget | BluetoothTarget;
+/**
+ * Códigos de error estables (segundo argumento de reject, `error.code` en JS):
+ * `unavailable` | `not_found` | `permission_denied` | `connect_failed`
+ * | `write_failed` | `invalid_transport` | `invalid_data`
+ */
+export interface ThermalPrinterPlugin {
+    /**
+     * Lista dispositivos del transporte. USB: todos los conectados con metadata.
+     * Bluetooth: emparejados en el sistema (pide BLUETOOTH_CONNECT si falta).
+     * TCP no es listable — la IP la ingresa el usuario.
+     */
+    list(options: {
+        transport: 'usb' | 'bluetooth';
+    }): Promise<{
+        devices: PrinterDevice[];
+    }>;
+    /**
+     * Pide el permiso del transporte. USB: diálogo del sistema por dispositivo
+     * (persiste hasta desconectar, o siempre si el usuario marca "usar por defecto").
+     * Bluetooth: permiso runtime BLUETOOTH_CONNECT (API 31+). TCP: siempre granted.
+     */
+    requestPermission(options: PrintTarget): Promise<{
+        granted: boolean;
+    }>;
+    /**
+     * Envía bytes ESC/POS crudos codificados en base64.
+     * Stateless: conecta → escribe (chunked) → cierra. Sin estado que corromper.
+     * Los trabajos se serializan en un solo hilo — nunca dos impresiones concurrentes.
+     */
+    print(options: PrintTarget & {
+        data: string;
+    }): Promise<void>;
+}

package/dist/esm/definitions.js

@@ -0,0 +1,8 @@
+/**
+ * @devlas/capacitor-thermal-printer — definiciones públicas.
+ *
+ * Filosofía: el plugin transporta BYTES CRUDOS (ESC/POS ya codificado por la app).
+ * No formatea texto, no conoce comandos — eso permite reusar el mismo encoder
+ * en todas las plataformas (Electron, Web Serial, WebUSB y esta app nativa).
+ */
+export {};

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+import type { ThermalPrinterPlugin } from './definitions';
+declare const ThermalPrinter: ThermalPrinterPlugin;
+/**
+ * Convierte bytes ESC/POS a base64 para `print({ data })`.
+ * Seguro para arrays grandes (evita el límite de argumentos de String.fromCharCode).
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export * from './definitions';
+export { ThermalPrinter };

package/dist/esm/index.js

@@ -0,0 +1,18 @@
+import { registerPlugin } from '@capacitor/core';
+const ThermalPrinter = registerPlugin('ThermalPrinter', {
+    web: () => import('./web').then((m) => new m.ThermalPrinterWeb()),
+});
+/**
+ * Convierte bytes ESC/POS a base64 para `print({ data })`.
+ * Seguro para arrays grandes (evita el límite de argumentos de String.fromCharCode).
+ */
+export function bytesToBase64(bytes) {
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+export * from './definitions';
+export { ThermalPrinter };

package/dist/esm/web.d.ts

@@ -0,0 +1,20 @@
+import { WebPlugin } from '@capacitor/core';
+import type { PrinterDevice, PrintTarget, ThermalPrinterPlugin } from './definitions';
+/**
+ * Stub web: este plugin es Android-nativo. En navegador usa las APIs del
+ * browser directamente (WebUSB / Web Serial) — no las envolvemos aquí para
+ * no duplicar lo que la plataforma ya expone a la app web.
+ */
+export declare class ThermalPrinterWeb extends WebPlugin implements ThermalPrinterPlugin {
+    list(_options: {
+        transport: 'usb' | 'bluetooth';
+    }): Promise<{
+        devices: PrinterDevice[];
+    }>;
+    requestPermission(_options: PrintTarget): Promise<{
+        granted: boolean;
+    }>;
+    print(_options: PrintTarget & {
+        data: string;
+    }): Promise<void>;
+}

package/dist/esm/web.js

@@ -0,0 +1,17 @@
+import { WebPlugin } from '@capacitor/core';
+/**
+ * Stub web: este plugin es Android-nativo. En navegador usa las APIs del
+ * browser directamente (WebUSB / Web Serial) — no las envolvemos aquí para
+ * no duplicar lo que la plataforma ya expone a la app web.
+ */
+export class ThermalPrinterWeb extends WebPlugin {
+    async list(_options) {
+        throw this.unimplemented('Solo Android. En navegador usa WebUSB o Web Serial.');
+    }
+    async requestPermission(_options) {
+        throw this.unimplemented('Solo Android. En navegador usa WebUSB o Web Serial.');
+    }
+    async print(_options) {
+        throw this.unimplemented('Solo Android. En navegador usa WebUSB o Web Serial.');
+    }
+}

package/docs/TRANSPORTES.md

@@ -0,0 +1,52 @@
+# Transportes — matriz, investigación y decisiones de diseño
+
+Documento de referencia del adapter. Actualizar cuando se agregue un transporte o cambie una decisión.
+
+## Matriz de transportes
+
+| Transporte | Estado | Implementación | Notas |
+|---|---|---|---|
+| **USB (OTG)** | ✅ Validado en hardware real (2026-07-06) | `UsbTransport.kt` — `UsbManager` puro | Requiere adaptador OTG real (no todos los USB-A→C lo son). Permiso por dispositivo vía diálogo del sistema — Android lo revoca al re-enchufar o reinstalar la app; el consumidor debe re-pedirlo y reintentar (ver useAndroidUsbPrinter del POS). |
+| **TCP / LAN / WiFi** | ✅ Implementado (sin validar en hardware) | `TcpTransport.kt` — `Socket` puro | Raw 9100 (JetDirect). "WiFi" e "impresora de red" son el mismo transporte. |
+| **Bluetooth SPP** | ✅ Validado en hardware real (2026-07-06) | `BluetoothTransport.kt` — `BluetoothSocket` RFCOMM | Solo dispositivos emparejados. Conexión por trabajo (~1-2 s de latencia); pool keep-alive si molesta en caja. |
+| **Serial RS232** | ⏳ Roadmap | Requiere [mik3y/usb-serial-for-android](https://github.com/mik3y/usb-serial-for-android) | Solo aplica a dongles USB-serial (FTDI/CH340/PL2303). Las "impresoras serie" reales llegan por BT-SPP o USB, ya cubiertos. Agregar solo cuando un cliente tenga ese hardware. |
+| **BLE** | ❌ Descartado | — | Las térmicas POS usan BT clásico (SPP), no BLE. Los pocos modelos BLE no justifican la complejidad GATT. |
+| **iOS** | ❌ Sin soporte | — | iOS no tiene API de USB host ni SPP (solo MFi/BLE). TCP sería posible si algún día existe app iOS — el diseño del plugin lo permite sin romper la API. |
+
+## Por qué existe este plugin (y no una librería de terceros)
+
+Se evaluaron a fondo (código fuente leído, no solo READMEs) las opciones existentes:
+
+| Librería / plugin | Qué es | Veredicto |
+|---|---|---|
+| [DantSu/ESCPOS-ThermalPrinter-Android](https://github.com/DantSu/ESCPOS-ThermalPrinter-Android) (1.5k ★, MIT) | Librería Android BT+TCP+USB | La más madura, pero su API es de **texto formateado** (`[C]<b>…`), no bytes crudos; su filtro USB exige clase 7 (USB_CLASS_PRINTER) y deja fuera térmicas genéricas vendor-specific. Se rescataron sus patrones (ver abajo) sin heredar la dependencia. |
+| [paystory-de/thermal-printer-cordova-plugin](https://github.com/paystory-de/thermal-printer-cordova-plugin) (Apache-2.0) | Plugin Cordova sobre DantSu | Código limpio y un solo mecanismo de conexión, pero **solo API de texto formateado** — habría obligado a reescribir el encoder de tickets. Permiso USB sin los flags de Android 14+. |
+| `@atomsolution/usb-printer-capacitor` (npm) | Plugin Capacitor USB | Descartado tras auditar el `.tgz`: depende de un SDK propietario (`omnidriver`, terminales Landi), doble mecanismo de conexión inconsistente (UsbManager para connect, DantSu para print) y código muerto. |
+| [KhairoHumsi/Printer-ktx](https://github.com/KhairoHumsi/Printer-ktx) | Port Kotlin de DantSu | Abandonado (última release 2021). |
+| `@e-is/capacitor-bluetooth-serial` | Plugin BT que usa el POS de Devlas hoy | Funciona, pero hubo que **parcharlo a mano en node_modules** (base64 para bytes crudos + pre-poblar scan con emparejados) — parche frágil que se pierde en cada `npm install`. Este adapter lo hace nativo desde el día 1; la migración del POS a este plugin elimina el parche. |
+| [WebUSBReceiptPrinter](https://github.com/NielsLeenheer/WebUSBReceiptPrinter) / WebSerialReceiptPrinter | Librerías browser (no Capacitor) | No aplican al WebView (Chromium no expone WebUSB/Web Serial en Android WebView — [issue 41441927](https://issues.chromium.org/issues/41441927)). Sus ideas de identidad de dispositivo (vendorId+productId) sí se adoptaron. |
+
+**Conclusión**: ninguna opción ofrecía bytes crudos + USB sin filtro de clase + permisos Android 14+ + cero dependencias. El costo de mantener ~400 líneas de Kotlin propio es menor que adoptar cualquiera de esos compromisos.
+
+## Qué se rescató de cada una
+
+- **DantSu**: preferencia por interfaz clase impresora (USB_CLASS_PRINTER) antes del fallback; espera proporcional al tamaño del trabajo antes de cerrar (~1 ms / 16 bytes) para no truncar el búfer de la impresora en TCP/BT.
+- **WebUSB (validado con hardware real en este proyecto)**: fallback a "primera interfaz con endpoint bulk OUT" para térmicas genéricas que no declaran clase 7.
+- **atomsolution**: escritura USB chunked (4096 bytes / timeout 3 s por chunk).
+- **paystory**: metadata rica en el listado de dispositivos; flujo de permiso con BroadcastReceiver (corregido aquí para Android 12/14+: `FLAG_MUTABLE`, `setPackage`, `RECEIVER_NOT_EXPORTED` — ninguno de los plugins lo hace bien).
+- **Parche de e-is en el POS**: bytes como base64 en el bridge JS↔nativo — aquí es el contrato de la API, no un parche.
+
+## Decisiones de diseño
+
+1. **Bytes crudos, encoder en la app.** El plugin no sabe qué es una boleta. `generarEscPosTicketBoleta()` (o cualquier encoder) vive en la app y se reusa en todas las plataformas.
+2. **Stateless por trabajo.** Conectar→escribir→cerrar en cada `print()`. Elimina toda la clase de bugs de "conexión zombie" (la causa del doble mecanismo inconsistente de atomsolution). El costo es latencia de reconexión BT (~1-2 s); si molesta, el roadmap contempla keep-alive opcional.
+3. **Un solo hilo ejecutor.** Serializa trabajos (nunca dos impresiones simultáneas al mismo dispositivo) y saca el I/O bloqueante del main thread (obligatorio para TCP: `NetworkOnMainThreadException`).
+4. **Códigos de error estables** (`unavailable`, `not_found`, `permission_denied`, `connect_failed`, `write_failed`) — la app mapea a mensajes de usuario sin parsear strings.
+5. **Sin auto-prompt de permiso dentro de `print()`.** Si falta permiso USB, rechaza con `permission_denied`; el flujo de configuración (Ajustes) llama a `requestPermission()` explícitamente. Una venta nunca se bloquea en un diálogo inesperado.
+
+## Roadmap
+
+- [ ] **Serial RS232** vía `usb-serial-for-android` — cuando exista un cliente con ese hardware.
+- [ ] **Keep-alive opcional BT** — pool de sockets con TTL si la latencia por ticket molesta en caja.
+- [ ] **Migrar el BT del POS Devlas** de `@e-is/capacitor-bluetooth-serial` (parchado) a este plugin — elimina el parche de node_modules.
+- [ ] **iOS TCP** — solo si algún día hay app iOS.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@devlas/capacitor-thermal-printer",
+  "version": "0.1.0",
+  "description": "Adaptador universal de impresión térmica ESC/POS para Capacitor Android: USB (OTG), TCP/LAN/WiFi y Bluetooth SPP con una sola API de bytes crudos.",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "android/src/main/",
+    "android/build.gradle",
+    "dist/",
+    "src/",
+    "docs/"
+  ],
+  "capacitor": {
+    "android": {
+      "src": "android"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Devlas SpA <ti@devlas.cl> (https://devlas.cl)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devlas-cl/capacitor-thermal-printer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/devlas-cl/capacitor-thermal-printer/issues"
+  },
+  "homepage": "https://github.com/devlas-cl/capacitor-thermal-printer#readme",
+  "keywords": [
+    "capacitor",
+    "capacitor-plugin",
+    "thermal-printer",
+    "impresora-termica",
+    "esc-pos",
+    "escpos",
+    "usb",
+    "otg",
+    "tcp",
+    "lan",
+    "wifi",
+    "bluetooth",
+    "spp",
+    "android",
+    "pos",
+    "point-of-sale",
+    "punto-de-venta",
+    "boleta",
+    "ticket"
+  ],
+  "peerDependencies": {
+    "@capacitor/core": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@capacitor/core": "^8.0.0",
+    "typescript": "~5.7.0"
+  },
+  "license": "MIT"
+}

package/src/definitions.ts

@@ -0,0 +1,77 @@
+/**
+ * @devlas/capacitor-thermal-printer — definiciones públicas.
+ *
+ * Filosofía: el plugin transporta BYTES CRUDOS (ESC/POS ya codificado por la app).
+ * No formatea texto, no conoce comandos — eso permite reusar el mismo encoder
+ * en todas las plataformas (Electron, Web Serial, WebUSB y esta app nativa).
+ */
+
+export type PrinterTransport = 'usb' | 'tcp' | 'bluetooth'
+
+export interface PrinterDevice {
+  transport: PrinterTransport
+  /** Nombre legible del dispositivo (productName USB / nombre BT). */
+  name?: string
+  // ── USB ──
+  vendorId?: number
+  productId?: number
+  /** ID de sesión Android — cambia al reconectar; usar vendorId+productId para persistir. */
+  deviceId?: number
+  /** true si el dispositivo tiene un endpoint bulk OUT (puede recibir impresión). */
+  canPrint?: boolean
+  /** true si Android ya otorgó permiso USB a este dispositivo. */
+  hasPermission?: boolean
+  // ── Bluetooth ──
+  /** Dirección MAC del dispositivo emparejado. */
+  address?: string
+}
+
+export interface UsbTarget {
+  transport: 'usb'
+  /** Si se omiten vendorId/productId, usa la primera impresora USB detectada. */
+  vendorId?: number
+  productId?: number
+}
+
+export interface TcpTarget {
+  transport: 'tcp'
+  host: string
+  /** Puerto raw/JetDirect. Default: 9100. */
+  port?: number
+}
+
+export interface BluetoothTarget {
+  transport: 'bluetooth'
+  /** MAC del dispositivo (debe estar emparejado en Ajustes del sistema). */
+  address: string
+}
+
+export type PrintTarget = UsbTarget | TcpTarget | BluetoothTarget
+
+/**
+ * Códigos de error estables (segundo argumento de reject, `error.code` en JS):
+ * `unavailable` | `not_found` | `permission_denied` | `connect_failed`
+ * | `write_failed` | `invalid_transport` | `invalid_data`
+ */
+export interface ThermalPrinterPlugin {
+  /**
+   * Lista dispositivos del transporte. USB: todos los conectados con metadata.
+   * Bluetooth: emparejados en el sistema (pide BLUETOOTH_CONNECT si falta).
+   * TCP no es listable — la IP la ingresa el usuario.
+   */
+  list(options: { transport: 'usb' | 'bluetooth' }): Promise<{ devices: PrinterDevice[] }>
+
+  /**
+   * Pide el permiso del transporte. USB: diálogo del sistema por dispositivo
+   * (persiste hasta desconectar, o siempre si el usuario marca "usar por defecto").
+   * Bluetooth: permiso runtime BLUETOOTH_CONNECT (API 31+). TCP: siempre granted.
+   */
+  requestPermission(options: PrintTarget): Promise<{ granted: boolean }>
+
+  /**
+   * Envía bytes ESC/POS crudos codificados en base64.
+   * Stateless: conecta → escribe (chunked) → cierra. Sin estado que corromper.
+   * Los trabajos se serializan en un solo hilo — nunca dos impresiones concurrentes.
+   */
+  print(options: PrintTarget & { data: string }): Promise<void>
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { registerPlugin } from '@capacitor/core'
+import type { ThermalPrinterPlugin } from './definitions'
+
+const ThermalPrinter = registerPlugin<ThermalPrinterPlugin>('ThermalPrinter', {
+  web: () => import('./web').then((m) => new m.ThermalPrinterWeb()),
+})
+
+/**
+ * Convierte bytes ESC/POS a base64 para `print({ data })`.
+ * Seguro para arrays grandes (evita el límite de argumentos de String.fromCharCode).
+ */
+export function bytesToBase64(bytes: Uint8Array): string {
+  let binary = ''
+  const CHUNK = 0x8000
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK))
+  }
+  return btoa(binary)
+}
+
+export * from './definitions'
+export { ThermalPrinter }

package/src/web.ts

@@ -0,0 +1,21 @@
+import { WebPlugin } from '@capacitor/core'
+import type { PrinterDevice, PrintTarget, ThermalPrinterPlugin } from './definitions'
+
+/**
+ * Stub web: este plugin es Android-nativo. En navegador usa las APIs del
+ * browser directamente (WebUSB / Web Serial) — no las envolvemos aquí para
+ * no duplicar lo que la plataforma ya expone a la app web.
+ */
+export class ThermalPrinterWeb extends WebPlugin implements ThermalPrinterPlugin {
+  async list(_options: { transport: 'usb' | 'bluetooth' }): Promise<{ devices: PrinterDevice[] }> {
+    throw this.unimplemented('Solo Android. En navegador usa WebUSB o Web Serial.')
+  }
+
+  async requestPermission(_options: PrintTarget): Promise<{ granted: boolean }> {
+    throw this.unimplemented('Solo Android. En navegador usa WebUSB o Web Serial.')
+  }
+
+  async print(_options: PrintTarget & { data: string }): Promise<void> {
+    throw this.unimplemented('Solo Android. En navegador usa WebUSB o Web Serial.')
+  }
+}