@delicity/capacitor-thermal-printer 7.0.0

package/android/src/main/java/com/delicity/thermalprinter/adapters/StarAdapter.kt

@@ -0,0 +1,322 @@
+package com.delicity.thermalprinter.adapters
+
+import android.content.Context
+import android.graphics.Bitmap
+import com.delicity.thermalprinter.model.AdapterId
+import com.delicity.thermalprinter.model.DiscoveredPrinter
+import com.delicity.thermalprinter.model.ErrorCode
+import com.delicity.thermalprinter.model.PrinterException
+import com.delicity.thermalprinter.model.PrinterProfile
+import com.delicity.thermalprinter.model.PrinterStatus
+import com.delicity.thermalprinter.model.RenderOptions
+import com.delicity.thermalprinter.model.Transport
+import com.starmicronics.stario10.InterfaceType
+import com.starmicronics.stario10.StarConnectionSettings
+import com.starmicronics.stario10.StarDeviceDiscoveryManager
+import com.starmicronics.stario10.StarDeviceDiscoveryManagerFactory
+import com.starmicronics.stario10.StarPrinter
+import com.starmicronics.stario10.starxpandcommand.DocumentBuilder
+import com.starmicronics.stario10.starxpandcommand.DrawerBuilder
+import com.starmicronics.stario10.starxpandcommand.PrinterBuilder
+import com.starmicronics.stario10.starxpandcommand.StarXpandCommandBuilder
+import com.starmicronics.stario10.starxpandcommand.drawer.Channel
+import com.starmicronics.stario10.starxpandcommand.drawer.OpenParameter
+import com.starmicronics.stario10.starxpandcommand.printer.Alignment
+import com.starmicronics.stario10.starxpandcommand.printer.BarcodeParameter
+import com.starmicronics.stario10.starxpandcommand.printer.BarcodeSymbology
+import com.starmicronics.stario10.starxpandcommand.printer.CutType
+import com.starmicronics.stario10.starxpandcommand.printer.ImageParameter
+import com.starmicronics.stario10.starxpandcommand.printer.MagnificationParameter
+import com.starmicronics.stario10.starxpandcommand.printer.QRCodeLevel
+import com.starmicronics.stario10.starxpandcommand.printer.QRCodeParameter
+import java.util.concurrent.ConcurrentHashMap
+import kotlin.coroutines.resume
+import kotlinx.coroutines.suspendCancellableCoroutine
+
+/**
+ * Adapter Star basé sur le StarXpand SDK (`com.starmicronics:stario10`).
+ *
+ * ⭐ Star est le SEUL fabricant dont le SDK est 100 % auto-téléchargé (Maven
+ * Central) : cet adapter utilise donc des appels TYPÉS directs (pas de réflexion).
+ * Si la dépendance Maven est retirée du build, `isAvailable()` renvoie false par
+ * réflexion et l'adapter est ignoré.
+ *
+ * StarXpand expose :
+ *   - StarDeviceDiscoveryManager (LAN, Bluetooth, BLE, USB),
+ *   - StarXpandCommandBuilder + PrinterBuilder.actionPrintImage(...) pour l'image,
+ *   - PrinterBuilder.actionPrintText / QRCode / Barcode pour le texte stylé,
+ *   - getStatusAsync() pour papier/capot/massicot.
+ */
+class StarAdapter(private val context: Context) : PrinterAdapter {
+
+    override val id = AdapterId.STAR
+
+    /** Connexions ouvertes indexées par printerId. */
+    private val connections = ConcurrentHashMap<String, StarPrinter>()
+
+    override fun isAvailable(): Boolean =
+        EpsonAdapter.classExists("com.starmicronics.stario10.StarPrinter")
+
+    override fun supportsTextItems(): Boolean = true
+
+    // -------------------------------------------------------------------------
+    // Découverte
+    // -------------------------------------------------------------------------
+
+    override suspend fun discover(timeoutMs: Long, onFound: (DiscoveredPrinter) -> Unit) {
+        if (!isAvailable()) return
+        val manager = StarDeviceDiscoveryManagerFactory.create(
+            listOf(
+                InterfaceType.Lan,
+                InterfaceType.Bluetooth,
+                InterfaceType.BluetoothLE,
+                InterfaceType.Usb,
+            ),
+            context,
+        )
+        manager.discoveryTime = timeoutMs.toInt().coerceIn(1000, 30000)
+
+        suspendCancellableCoroutine<Unit> { cont ->
+            manager.callback = object : StarDeviceDiscoveryManager.Callback {
+                override fun onPrinterFound(printer: StarPrinter) {
+                    val settings = printer.connectionSettings
+                    val transport = transportFor(settings.interfaceType)
+                    val model = printer.information?.model?.name
+                    onFound(
+                        DiscoveredPrinter(
+                            id = "star:${settings.interfaceType}:${settings.identifier}",
+                            name = model ?: "Star Printer",
+                            brand = "Star",
+                            model = model,
+                            transport = transport,
+                            adapter = AdapterId.STAR,
+                            address = settings.identifier,
+                            discoveredBy = mutableSetOf(AdapterId.STAR),
+                        ),
+                    )
+                }
+
+                override fun onDiscoveryFinished() {
+                    if (cont.isActive) cont.resume(Unit)
+                }
+            }
+            cont.invokeOnCancellation { runCatching { manager.stopDiscovery() } }
+            runCatching { manager.startDiscovery() }
+                .onFailure { if (cont.isActive) cont.resume(Unit) }
+        }
+        runCatching { manager.stopDiscovery() }
+    }
+
+    override fun canHandle(profile: PrinterProfile): Boolean =
+        isAvailable() && profile.adapter == AdapterId.STAR
+
+    // -------------------------------------------------------------------------
+    // Connexion
+    // -------------------------------------------------------------------------
+
+    override suspend fun connect(profile: PrinterProfile, timeoutMs: Long) {
+        ensureSdk()
+        if (isConnected(profile.id)) return
+        val printer = StarPrinter(connectionSettingsFor(profile), context)
+        try {
+            printer.openAsync().await()
+        } catch (e: Exception) {
+            throw PrinterException(ErrorCode.CONNECTION_FAILED, "Connexion Star échouée: ${profile.address}", e.message, retryable = true)
+        }
+        connections[profile.id] = printer
+    }
+
+    override fun isConnected(printerId: String): Boolean = connections.containsKey(printerId)
+
+    override suspend fun disconnect(printerId: String) {
+        connections.remove(printerId)?.let { runCatching { it.closeAsync().await() } }
+    }
+
+    // -------------------------------------------------------------------------
+    // Impression
+    // -------------------------------------------------------------------------
+
+    override suspend fun printBitmap(profile: PrinterProfile, bitmap: Bitmap, options: RenderOptions): Int {
+        val printer = requireConnected(profile)
+        val printerDoc = PrinterBuilder()
+            .styleAlignment(alignmentFor(options.align))
+            .actionPrintImage(ImageParameter(bitmap, profile.capabilities.printableDots.coerceAtLeast(8)))
+        if (options.feedLines > 0) printerDoc.actionFeedLine(options.feedLines)
+        if (options.cut && profile.capabilities.supportsCut) printerDoc.actionCut(CutType.Partial)
+
+        val document = DocumentBuilder().addPrinter(printerDoc)
+        if (options.openCashDrawer && profile.capabilities.supportsCashDrawer) {
+            document.addDrawer(DrawerBuilder().actionOpen(OpenParameter().setChannel(Channel.No1)))
+        }
+        val commands = StarXpandCommandBuilder().addDocument(document).getCommands()
+
+        var sent = 0
+        repeat(options.copies.coerceAtLeast(1)) {
+            sendCommands(printer, commands, profile)
+            sent += commands.length
+        }
+        return sent
+    }
+
+    override suspend fun printItems(
+        profile: PrinterProfile,
+        items: List<com.delicity.thermalprinter.model.PrintItem>,
+        defaultCodePage: String,
+        cut: Boolean,
+        feedLines: Int,
+    ): Int {
+        val printer = requireConnected(profile)
+        val pb = PrinterBuilder()
+        for (item in items) mapItem(pb, item, profile)
+        if (feedLines > 0) pb.actionFeedLine(feedLines)
+        if (cut && profile.capabilities.supportsCut) pb.actionCut(CutType.Partial)
+        val commands = StarXpandCommandBuilder()
+            .addDocument(DocumentBuilder().addPrinter(pb))
+            .getCommands()
+        sendCommands(printer, commands, profile)
+        return commands.length
+    }
+
+    /** Mappe un PrintItem vers le builder StarXpand (best effort par type). */
+    private fun mapItem(pb: PrinterBuilder, item: com.delicity.thermalprinter.model.PrintItem, profile: PrinterProfile) {
+        when (item) {
+            is com.delicity.thermalprinter.model.PrintItem.Text -> {
+                item.style.align?.let { pb.styleAlignment(alignmentFor(it)) }
+                pb.styleBold(item.style.bold)
+                pb.styleInvert(item.style.invert)
+                pb.styleUnderLine(item.style.underline != "none")
+                pb.styleMagnification(MagnificationParameter(item.style.widthMultiplier.coerceIn(1, 6), item.style.heightMultiplier.coerceIn(1, 6)))
+                if (item.style.newline) pb.actionPrintText(item.value + "\n") else pb.actionPrintText(item.value)
+                // reset styles pour ne pas contaminer les items suivants
+                pb.styleBold(false).styleInvert(false).styleUnderLine(false)
+                    .styleMagnification(MagnificationParameter(1, 1))
+            }
+            is com.delicity.thermalprinter.model.PrintItem.Feed -> pb.actionFeedLine(item.lines.coerceAtLeast(1))
+            is com.delicity.thermalprinter.model.PrintItem.Cut ->
+                pb.actionCut(if (item.mode == "full") CutType.Full else CutType.Partial)
+            is com.delicity.thermalprinter.model.PrintItem.Divider -> {
+                val cols = item.columns ?: if (profile.capabilities.printableDots <= 420) 32 else 48
+                item.align?.let { pb.styleAlignment(alignmentFor(it)) }
+                pb.styleBold(item.bold)
+                pb.actionPrintText(item.char.repeat(cols.coerceIn(1, 96)) + "\n")
+                pb.styleBold(false)
+            }
+            is com.delicity.thermalprinter.model.PrintItem.QrCode -> {
+                pb.styleAlignment(alignmentFor(item.align))
+                pb.actionPrintQRCode(
+                    QRCodeParameter(item.value)
+                        .setLevel(qrLevelFor(item.ec))
+                        .setCellSize(item.size.coerceIn(1, 16)),
+                )
+            }
+            is com.delicity.thermalprinter.model.PrintItem.Barcode -> {
+                pb.styleAlignment(alignmentFor(item.align))
+                pb.actionPrintBarcode(
+                    BarcodeParameter(item.value, barcodeSymbologyFor(item.symbology))
+                        .setHeight(item.height.coerceIn(1, 255).toDouble())
+                        .setPrintHri(item.hri != "none"),
+                )
+            }
+            is com.delicity.thermalprinter.model.PrintItem.CashDrawer -> {
+                // Le tiroir est géré au niveau document ; ignoré ici (voir openCashDrawer).
+            }
+            is com.delicity.thermalprinter.model.PrintItem.Image -> {
+                // Les images inline dans printText ne sont pas pré-rendues ici ;
+                // l'app doit utiliser printImage pour un rendu maîtrisé.
+            }
+            is com.delicity.thermalprinter.model.PrintItem.Raw -> {
+                // StarXpand n'expose pas d'injection ESC/POS brute fiable -> ignoré.
+            }
+        }
+    }
+
+    private suspend fun sendCommands(printer: StarPrinter, commands: String, profile: PrinterProfile) {
+        try {
+            printer.printAsync(commands).await()
+        } catch (e: Exception) {
+            throw PrinterException(ErrorCode.PRINT_FAILED, "Impression Star échouée", e.message, retryable = true)
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Statut
+    // -------------------------------------------------------------------------
+
+    override suspend fun getStatus(profile: PrinterProfile): PrinterStatus {
+        val printer = connections[profile.id]
+            ?: return PrinterStatus(profile.id, "disconnected", online = false, paper = "unknown")
+        return try {
+            val st = printer.getStatusAsync().await()
+            val paperEmpty = runCatching { st.paperEmpty }.getOrDefault(false)
+            val paperNear = runCatching { st.paperNearEmpty }.getOrDefault(false)
+            val coverOpen = runCatching { st.coverOpen }.getOrDefault(false)
+            PrinterStatus(
+                id = profile.id,
+                connection = "connected",
+                online = !paperEmpty && !coverOpen,
+                paper = if (paperEmpty) "empty" else if (paperNear) "near_end" else "ok",
+                coverOpen = coverOpen,
+                errorCode = if (paperEmpty) ErrorCode.PAPER_EMPTY else if (coverOpen) ErrorCode.COVER_OPEN else null,
+                rawStatus = st.toString(),
+            )
+        } catch (e: Exception) {
+            PrinterStatus(profile.id, "error", online = false, paper = "unknown", rawStatus = e.message)
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+
+    private fun requireConnected(profile: PrinterProfile): StarPrinter =
+        connections[profile.id] ?: throw PrinterException(ErrorCode.CONNECTION_FAILED, "Star non connecté: ${profile.id}")
+
+    private fun connectionSettingsFor(profile: PrinterProfile): StarConnectionSettings {
+        val iface = when (profile.transport) {
+            Transport.WIFI, Transport.ETHERNET -> InterfaceType.Lan
+            Transport.BLUETOOTH -> InterfaceType.Bluetooth
+            Transport.BLE -> InterfaceType.BluetoothLE
+            Transport.USB -> InterfaceType.Usb
+        }
+        // Pour le LAN, l'identifier Star est l'IP (sans port).
+        val identifier = if (iface == InterfaceType.Lan) profile.address.substringBefore(":") else profile.address
+        return StarConnectionSettings(iface, identifier)
+    }
+
+    private fun transportFor(iface: InterfaceType): Transport = when (iface) {
+        InterfaceType.Lan -> Transport.WIFI
+        InterfaceType.Bluetooth -> Transport.BLUETOOTH
+        InterfaceType.BluetoothLE -> Transport.BLE
+        InterfaceType.Usb -> Transport.USB
+        else -> Transport.WIFI
+    }
+
+    private fun alignmentFor(align: String?): Alignment = when (align) {
+        "center" -> Alignment.Center
+        "right" -> Alignment.Right
+        else -> Alignment.Left
+    }
+
+    private fun qrLevelFor(ec: String): QRCodeLevel = when (ec.uppercase()) {
+        "L" -> QRCodeLevel.L
+        "Q" -> QRCodeLevel.Q
+        "H" -> QRCodeLevel.H
+        else -> QRCodeLevel.M
+    }
+
+    private fun barcodeSymbologyFor(symbology: String): BarcodeSymbology = when (symbology.uppercase()) {
+        "CODE39" -> BarcodeSymbology.Code39
+        "CODE93" -> BarcodeSymbology.Code93
+        "EAN13", "JAN13" -> BarcodeSymbology.Jan13
+        "EAN8", "JAN8" -> BarcodeSymbology.Jan8
+        "ITF" -> BarcodeSymbology.Itf
+        "UPCA" -> BarcodeSymbology.UpcA
+        "UPCE" -> BarcodeSymbology.UpcE
+        "NW7", "CODABAR" -> BarcodeSymbology.Nw7
+        else -> BarcodeSymbology.Code128
+    }
+
+    private fun ensureSdk() {
+        if (!isAvailable()) throw PrinterException(ErrorCode.SDK_NOT_AVAILABLE, "SDK Star absent")
+    }
+}

package/android/src/main/java/com/delicity/thermalprinter/adapters/UsbAdapter.kt

@@ -0,0 +1,248 @@
+package com.delicity.thermalprinter.adapters
+
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.graphics.Bitmap
+import android.hardware.usb.UsbConstants
+import android.hardware.usb.UsbDevice
+import android.hardware.usb.UsbDeviceConnection
+import android.hardware.usb.UsbEndpoint
+import android.hardware.usb.UsbInterface
+import android.hardware.usb.UsbManager
+import android.os.Build
+import com.delicity.thermalprinter.image.ImageProcessor
+import com.delicity.thermalprinter.model.AdapterId
+import com.delicity.thermalprinter.model.DiscoveredPrinter
+import com.delicity.thermalprinter.model.ErrorCode
+import com.delicity.thermalprinter.model.PrinterException
+import com.delicity.thermalprinter.model.PrinterProfile
+import com.delicity.thermalprinter.model.PrinterStatus
+import com.delicity.thermalprinter.model.RenderOptions
+import com.delicity.thermalprinter.model.Transport
+import java.util.concurrent.ConcurrentHashMap
+import kotlin.coroutines.resume
+import kotlinx.coroutines.suspendCancellableCoroutine
+
+/**
+ * Adapter USB (Android host) pour imprimantes ESC/POS branchées en USB.
+ *
+ * Détecte les périphériques de classe imprimante (USB class 7), demande la
+ * permission runtime, réclame l'interface et écrit le raster ESC/POS sur
+ * l'endpoint bulk OUT via bulkTransfer (par paquets).
+ *
+ * ⚠️ ANDROID UNIQUEMENT (iOS n'expose pas l'USB host pour ce cas).
+ */
+class UsbAdapter(private val context: Context) : PrinterAdapter {
+
+    override val id = AdapterId.ESCPOS
+    private val usbManager get() = context.getSystemService(Context.USB_SERVICE) as UsbManager
+
+    /** Connexions ouvertes indexées par printerId ("usb:vendorId:productId"). */
+    private val connections = ConcurrentHashMap<String, UsbLink>()
+
+    private data class UsbLink(
+        val connection: UsbDeviceConnection,
+        val iface: UsbInterface,
+        val endpointOut: UsbEndpoint,
+        val endpointIn: UsbEndpoint?,
+    )
+
+    override fun isAvailable(): Boolean =
+        context.packageManager.hasSystemFeature(android.content.pm.PackageManager.FEATURE_USB_HOST)
+
+    override fun supportsTextItems(): Boolean = true
+
+    override suspend fun discover(timeoutMs: Long, onFound: (DiscoveredPrinter) -> Unit) {
+        if (!isAvailable()) return
+        usbManager.deviceList.values.forEach { device ->
+            val isPrinter = (0 until device.interfaceCount).any { device.getInterface(it).interfaceClass == UsbConstants.USB_CLASS_PRINTER }
+            if (isPrinter) {
+                onFound(
+                    DiscoveredPrinter(
+                        id = "usb:${device.vendorId}:${device.productId}",
+                        name = device.productName ?: "USB Printer",
+                        brand = device.manufacturerName,
+                        transport = Transport.USB,
+                        adapter = AdapterId.ESCPOS,
+                        address = "${device.vendorId}:${device.productId}",
+                        discoveredBy = mutableSetOf(AdapterId.ESCPOS),
+                    ),
+                )
+            }
+        }
+    }
+
+    override fun canHandle(profile: PrinterProfile): Boolean = profile.transport == Transport.USB
+
+    override suspend fun connect(profile: PrinterProfile, timeoutMs: Long) {
+        ensureUsb()
+        if (isConnected(profile.id)) return
+
+        val device = findDevice(profile.address)
+            ?: throw PrinterException(ErrorCode.PRINTER_NOT_FOUND, "Périphérique USB introuvable: ${profile.address}")
+
+        if (!usbManager.hasPermission(device)) {
+            val granted = requestPermission(device, timeoutMs)
+            if (!granted) throw PrinterException(ErrorCode.PERMISSION_DENIED, "Permission USB refusée", retryable = true)
+        }
+
+        val iface = (0 until device.interfaceCount)
+            .map { device.getInterface(it) }
+            .firstOrNull { it.interfaceClass == UsbConstants.USB_CLASS_PRINTER }
+            ?: throw PrinterException(ErrorCode.UNSUPPORTED_PRINTER, "Aucune interface imprimante USB")
+
+        var endpointOut: UsbEndpoint? = null
+        var endpointIn: UsbEndpoint? = null
+        for (i in 0 until iface.endpointCount) {
+            val ep = iface.getEndpoint(i)
+            if (ep.type == UsbConstants.USB_ENDPOINT_XFER_BULK) {
+                if (ep.direction == UsbConstants.USB_DIR_OUT) endpointOut = ep
+                if (ep.direction == UsbConstants.USB_DIR_IN) endpointIn = ep
+            }
+        }
+        if (endpointOut == null) throw PrinterException(ErrorCode.UNSUPPORTED_PRINTER, "Endpoint USB bulk OUT introuvable")
+
+        val connection = usbManager.openDevice(device)
+            ?: throw PrinterException(ErrorCode.CONNECTION_FAILED, "Ouverture USB échouée", retryable = true)
+        if (!connection.claimInterface(iface, true)) {
+            connection.close()
+            throw PrinterException(ErrorCode.CONNECTION_FAILED, "claimInterface USB échoué", retryable = true)
+        }
+        connections[profile.id] = UsbLink(connection, iface, endpointOut, endpointIn)
+    }
+
+    override fun isConnected(printerId: String): Boolean = connections.containsKey(printerId)
+
+    override suspend fun disconnect(printerId: String) {
+        connections.remove(printerId)?.let { link ->
+            runCatching { link.connection.releaseInterface(link.iface) }
+            runCatching { link.connection.close() }
+        }
+    }
+
+    override suspend fun printBitmap(profile: PrinterProfile, bitmap: Bitmap, options: RenderOptions): Int {
+        val link = requireLink(profile)
+        val mono = ImageProcessor.toMono(bitmap, options)
+        val raster = ImageProcessor.encodeEscPosRaster(mono)
+        val job = EscPosCommands.buildJob(
+            rasterData = raster,
+            align = options.align,
+            feedLines = options.feedLines,
+            cut = options.cut && profile.capabilities.supportsCut,
+            openDrawer = options.openCashDrawer && profile.capabilities.supportsCashDrawer,
+        )
+        var sent = 0
+        repeat(options.copies.coerceAtLeast(1)) { sent += writeBulk(link, job) }
+        return sent
+    }
+
+    override suspend fun printItems(
+        profile: PrinterProfile,
+        items: List<com.delicity.thermalprinter.model.PrintItem>,
+        defaultCodePage: String,
+        cut: Boolean,
+        feedLines: Int,
+    ): Int {
+        val link = requireLink(profile)
+        val columns = if (profile.capabilities.printableDots <= 420) 32 else 48
+        val encoded = EscPosTextEncoder.encode(items, defaultCodePage, columns)
+        val out = java.io.ByteArrayOutputStream()
+        out.write(encoded.bytes)
+        if (feedLines > 0) out.write(EscPosCommands.feed(feedLines))
+        if (cut && profile.capabilities.supportsCut) out.write(EscPosCommands.CUT_PARTIAL)
+        return writeBulk(link, out.toByteArray())
+    }
+
+    override suspend fun getStatus(profile: PrinterProfile): PrinterStatus {
+        val link = connections[profile.id]
+            ?: return PrinterStatus(profile.id, "disconnected", online = false, paper = "unknown")
+        // DLE EOT 4 -> statut papier si un endpoint IN est exposé (rare en USB).
+        val epIn = link.endpointIn
+            ?: return PrinterStatus(profile.id, "connected", online = true, paper = "unknown", rawStatus = "no-in-endpoint")
+        return try {
+            writeBulk(link, EscPosCommands.realtimeStatus(4))
+            val buf = ByteArray(8)
+            val n = link.connection.bulkTransfer(epIn, buf, buf.size, 1500)
+            if (n <= 0) {
+                PrinterStatus(profile.id, "connected", online = true, paper = "unknown", rawStatus = "no-response")
+            } else {
+                val b = buf[0].toInt()
+                val paperEmpty = (b and 0x60) != 0
+                PrinterStatus(
+                    profile.id, "connected", online = true,
+                    paper = if (paperEmpty) "empty" else "ok",
+                    errorCode = if (paperEmpty) ErrorCode.PAPER_EMPTY else null,
+                    rawStatus = "0x%02X".format(b),
+                )
+            }
+        } catch (e: Exception) {
+            PrinterStatus(profile.id, "error", online = false, paper = "unknown", rawStatus = e.message)
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+
+    private fun requireLink(profile: PrinterProfile): UsbLink =
+        connections[profile.id] ?: throw PrinterException(ErrorCode.CONNECTION_FAILED, "USB non connecté: ${profile.id}")
+
+    /** Écrit un buffer sur l'endpoint bulk OUT par paquets (taille = maxPacketSize). */
+    private fun writeBulk(link: UsbLink, data: ByteArray): Int {
+        val ep = link.endpointOut
+        val chunk = if (ep.maxPacketSize > 0) ep.maxPacketSize else 16384
+        var offset = 0
+        while (offset < data.size) {
+            val len = minOf(chunk, data.size - offset)
+            val slice = if (offset == 0 && len == data.size) data else data.copyOfRange(offset, offset + len)
+            val n = link.connection.bulkTransfer(ep, slice, len, 5000)
+            if (n < 0) throw PrinterException(ErrorCode.PRINT_FAILED, "Écriture USB échouée (bulkTransfer=$n)", retryable = true)
+            offset += len
+        }
+        return data.size
+    }
+
+    private fun findDevice(address: String): UsbDevice? {
+        val parts = address.split(":")
+        if (parts.size < 2) return null
+        val vid = parts[0].toIntOrNull() ?: return null
+        val pid = parts[1].toIntOrNull() ?: return null
+        return usbManager.deviceList.values.firstOrNull { it.vendorId == vid && it.productId == pid }
+    }
+
+    /** Demande la permission USB runtime et suspend jusqu'à la réponse (ou timeout). */
+    private suspend fun requestPermission(device: UsbDevice, timeoutMs: Long): Boolean =
+        suspendCancellableCoroutine { cont ->
+            val action = "$ACTION_USB_PERMISSION.${device.deviceId}"
+            val receiver = object : BroadcastReceiver() {
+                override fun onReceive(ctx: Context, intent: Intent) {
+                    if (intent.action != action) return
+                    runCatching { context.unregisterReceiver(this) }
+                    val granted = intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)
+                    if (cont.isActive) cont.resume(granted)
+                }
+            }
+            val filter = IntentFilter(action)
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                context.registerReceiver(receiver, filter, Context.RECEIVER_NOT_EXPORTED)
+            } else {
+                @Suppress("UnspecifiedRegisterReceiverFlag")
+                context.registerReceiver(receiver, filter)
+            }
+            val flags = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) PendingIntent.FLAG_MUTABLE else 0
+            val pi = PendingIntent.getBroadcast(context, 0, Intent(action).setPackage(context.packageName), flags)
+            cont.invokeOnCancellation { runCatching { context.unregisterReceiver(receiver) } }
+            usbManager.requestPermission(device, pi)
+        }
+
+    private fun ensureUsb() {
+        if (!isAvailable()) throw PrinterException(ErrorCode.UNSUPPORTED_TRANSPORT, "USB host indisponible")
+    }
+
+    companion object {
+        private const val ACTION_USB_PERMISSION = "com.delicity.thermalprinter.USB_PERMISSION"
+    }
+}