{"_id":"@amitkhare/capacitor-cat-printer","_rev":"5-e0503706f24fb648d205b535fe4e2579","name":"@amitkhare/capacitor-cat-printer","dist-tags":{"latest":"0.6.1"},"versions":{"0.6.0":{"name":"@amitkhare/capacitor-cat-printer","version":"0.6.0","keywords":["capacitor","plugin","thermal-printer","cat-printer","bluetooth","ble","receipt","pos"],"author":{"name":"Amit Kumar Khare","email":"amit@khare.co.in"},"license":"MIT","_id":"@amitkhare/capacitor-cat-printer@0.6.0","maintainers":[{"name":"amitkhare","email":"amit@khare.co.in"}],"homepage":"https://github.com/amitkhare/capacitor-cat-printer#readme","bugs":{"url":"https://github.com/amitkhare/capacitor-cat-printer/issues"},"dist":{"shasum":"fca81025b5a71681a116c081b9f6d14983baabea","tarball":"https://registry.npmjs.org/@amitkhare/capacitor-cat-printer/-/capacitor-cat-printer-0.6.0.tgz","fileCount":26,"integrity":"sha512-e8+k2RkkoV05GZGXMk/n6OxjOEf73ga86ON9ItBCdKEX2/6qyF1tCHx7rgZER7ulHdoklW97I+/ZZGPtiMj48A==","signatures":[{"sig":"MEUCIQDWCcsSKdBB87Haa3XIpOZPT6dN7rlio26BrEdFza4mYAIgLpN8XQG/980NXth6DG2tLops8Fn9pHc1Ll7QTku+6fQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":537542},"main":"dist/plugin.cjs.js","types":"dist/esm/index.d.ts","unpkg":"dist/plugin.js","module":"dist/esm/index.js","gitHead":"73894ea2bbcbd237b5900dcf5a297cfc5e9aeb9a","scripts":{"build":"npm run clean && tsc && rollup -c rollup.config.mjs","clean":"rimraf ./dist","git:release":"git checkout release && git merge master && git push origin release && git checkout master","prepublishOnly":"npm run build"},"_npmUser":{"name":"amitkhare","email":"amit@khare.co.in"},"capacitor":{"android":{"src":"android"}},"repository":{"url":"git+https://github.com/amitkhare/capacitor-cat-printer.git","type":"git"},"_npmVersion":"11.4.2","description":"Capacitor plugin for Cat thermal printers (BLE)","directories":{},"_nodeVersion":"22.14.0","_hasShrinkwrap":false,"devDependencies":{"rimraf":"^5.0.0","rollup":"^4.0.0","typescript":"^5.0.0","@capacitor/core":"^8.0.0","@capacitor/android":"^8.0.0","@types/web-bluetooth":"^0.0.21","@rollup/plugin-node-resolve":"^15.0.0"},"peerDependencies":{"@capacitor/core":">=5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/capacitor-cat-printer_0.6.0_1775240474852_0.38330877909779626","host":"s3://npm-registry-packages-npm-production"}},"0.6.1":{"name":"@amitkhare/capacitor-cat-printer","version":"0.6.1","description":"Capacitor plugin for Cat thermal printers (BLE)","main":"dist/plugin.cjs.js","module":"dist/esm/index.js","types":"dist/esm/index.d.ts","unpkg":"dist/plugin.js","author":{"name":"Amit Kumar Khare","email":"amit@khare.co.in"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/amitkhare/capacitor-cat-printer.git"},"keywords":["capacitor","plugin","thermal-printer","cat-printer","bluetooth","ble","receipt","pos"],"scripts":{"build":"npm run clean && tsc && rollup -c rollup.config.mjs","clean":"rimraf ./dist","prepublishOnly":"npm run build","git:release":"git checkout release && git merge master && git push origin release && git checkout master"},"devDependencies":{"@capacitor/android":"^8.0.0","@capacitor/core":"^8.0.0","@rollup/plugin-node-resolve":"^15.0.0","@types/web-bluetooth":"^0.0.21","rimraf":"^5.0.0","rollup":"^4.0.0","typescript":"^5.0.0"},"peerDependencies":{"@capacitor/core":">=5.0.0"},"capacitor":{"android":{"src":"android"}},"_id":"@amitkhare/capacitor-cat-printer@0.6.1","gitHead":"7010ce65bbd04c8dbf45269f989d13f87376e22f","bugs":{"url":"https://github.com/amitkhare/capacitor-cat-printer/issues"},"homepage":"https://github.com/amitkhare/capacitor-cat-printer#readme","_nodeVersion":"22.14.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-nDjYyc0gm80q9yNdJxO/V80kHkHLHpeIP/gHvRLdCrod7ZiXdx3gGTLcyBGxubRaGbJD8EJXeXTqJopUPC1EIw==","shasum":"d42f4c1193f4d9ab180cbec990aa68ac29b93223","tarball":"https://registry.npmjs.org/@amitkhare/capacitor-cat-printer/-/capacitor-cat-printer-0.6.1.tgz","fileCount":26,"unpackedSize":536872,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIET0zniFFxgOncS62AStqKs35pDMFBxnIcWX1GZOp8r7AiBeZ/qGa3sax4z1lBxf5dC3iS2v0r85iXQ8pHnrHTMSaA=="}]},"_npmUser":{"name":"amitkhare","email":"amit@khare.co.in"},"directories":{},"maintainers":[{"name":"amitkhare","email":"amit@khare.co.in"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/capacitor-cat-printer_0.6.1_1778598224258_0.6332089316757736"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-03T18:21:14.741Z","modified":"2026-05-12T15:03:44.572Z","0.5.0":"2025-12-23T17:32:17.316Z","0.5.2":"2025-12-24T19:41:52.600Z","0.6.0":"2026-04-03T18:21:15.163Z","0.6.1":"2026-05-12T15:03:44.454Z"},"bugs":{"url":"https://github.com/amitkhare/capacitor-cat-printer/issues"},"author":{"name":"Amit Kumar Khare","email":"amit@khare.co.in"},"license":"MIT","homepage":"https://github.com/amitkhare/capacitor-cat-printer#readme","keywords":["capacitor","plugin","thermal-printer","cat-printer","bluetooth","ble","receipt","pos"],"repository":{"type":"git","url":"git+https://github.com/amitkhare/capacitor-cat-printer.git"},"description":"Capacitor plugin for Cat thermal printers (BLE)","maintainers":[{"name":"amitkhare","email":"amit@khare.co.in"}],"readme":"# Capacitor Cat Printer\r\n\r\nA Capacitor plugin for thermal printers (Cat printers and compatibles) over Bluetooth LE. Works on Android and Web/PWA.\r\n\r\n## Features\r\n\r\n- BLE scanning and connection management\r\n- Text printing with full styling (bold, italic, underline, strikethrough)\r\n- Rich text with mixed formatting in a single print\r\n- Image printing with dithering, brightness/contrast adjustments\r\n- QR codes and barcodes (CODE128, EAN13, UPC, etc.) — Android only\r\n- Table/receipt layout printing\r\n- Custom font support (TTF/OTF on Android, CSS font families on web)\r\n- RTL text support\r\n- Printer status (battery, paper, charging)\r\n- Auto-reconnect (Android)\r\n- Dry-run mode for testing\r\n- 58mm and 80mm paper widths\r\n- Web/PWA support via Web Bluetooth API\r\n\r\n## Platform Support\r\n\r\n| Feature | Android | Web/PWA |\r\n|---|---|---|\r\n| BLE Scan | Background scan, returns device list | Browser device picker (user selects one) |\r\n| Connect / Disconnect | ✅ | ✅ |\r\n| Print Text | ✅ | ✅ |\r\n| Print Rich Text | ✅ | ✅ |\r\n| Print Image | ✅ | ✅ |\r\n| Print Table | ✅ | ✅ |\r\n| Print Barcode | ✅ | Use JS library + `printImage` |\r\n| Print QR Code | ✅ | Use JS library + `printImage` |\r\n| Preview | ✅ | ✅ (text, rich text, table, image) |\r\n| Auto-Reconnect | ✅ | Not supported |\r\n| Custom Fonts | TTF/OTF file path | CSS font family name |\r\n| Dry-Run Mode | ✅ | ✅ |\r\n\r\nWeb Bluetooth is supported in Chrome 56+, Edge 79+, Opera 43+, Samsung Internet 6.2+. Not supported in Safari or Firefox.\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install capacitor-cat-printer\r\nnpx cap sync android\r\n```\r\n\r\n## Android Permissions\r\n\r\nAdd to `AndroidManifest.xml` before `<application>`:\r\n\r\n```xml\r\n<uses-permission android:name=\"android.permission.BLUETOOTH\" android:maxSdkVersion=\"30\" />\r\n<uses-permission android:name=\"android.permission.BLUETOOTH_ADMIN\" android:maxSdkVersion=\"30\" />\r\n<uses-permission android:name=\"android.permission.BLUETOOTH_SCAN\" />\r\n<uses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\" />\r\n<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" />\r\n<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" />\r\n<uses-feature android:name=\"android.hardware.bluetooth_le\" android:required=\"true\" />\r\n```\r\n\r\n## Web Requirements\r\n\r\n- HTTPS (required by Web Bluetooth API)\r\n- A supported browser (Chrome, Edge, Opera)\r\n- User interaction (click/tap) is required to trigger the BLE device picker\r\n\r\n## Quick Start\r\n\r\n```typescript\r\nimport { CatPrinter } from 'capacitor-cat-printer';\r\n\r\n// Scan — on Android returns a list, on web opens browser device picker\r\nconst { devices } = await CatPrinter.scan({ duration: 5000 });\r\n\r\n// Connect\r\nawait CatPrinter.connect({ address: devices[0].address });\r\n\r\n// Print\r\nawait CatPrinter.printText({ text: 'Hello World!' });\r\n\r\n// Disconnect\r\nawait CatPrinter.disconnect();\r\n```\r\n\r\nThe same code works on both Android and Web. Capacitor automatically routes to the correct implementation.\r\n\r\n## API\r\n\r\n### Connection\r\n\r\n```typescript\r\n// Scan for printers\r\nconst { devices } = await CatPrinter.scan({ duration: 5000 });\r\n// devices: [{ name, address, rssi }]\r\n\r\n// Stop scan early (no-op on web)\r\nawait CatPrinter.stopScan();\r\n\r\n// Connect\r\nawait CatPrinter.connect({\r\n  address: 'AA:BB:CC:DD:EE:FF',\r\n  paperWidth: 384,        // 384 = 58mm, 576 = 80mm\r\n  timeout: 10000,\r\n  dryRun: false,          // true = simulate without printing\r\n  autoReconnect: false    // Android only\r\n});\r\n\r\n// Check status\r\nconst { connected, address, paperWidth } = await CatPrinter.isConnected();\r\n\r\n// Disconnect\r\nawait CatPrinter.disconnect();\r\n```\r\n\r\n### Print Text\r\n\r\n```typescript\r\nawait CatPrinter.printText({\r\n  text: 'Hello World!',\r\n  fontSize: 24,\r\n  align: 'center',        // 'left' | 'center' | 'right'\r\n  bold: true,\r\n  italic: false,\r\n  underline: false,\r\n  strikethrough: false,\r\n  lineSpacing: 1.2,\r\n  wordWrap: true,         // break at word boundaries\r\n  rtl: false,             // right-to-left\r\n  fontPath: '/path/to/font.ttf',  // Android: file path, Web: CSS font family\r\n  energy: 0.6,            // 0.0-1.0 darkness\r\n  quality: 3,             // 1-4\r\n  feedAfter: 100\r\n});\r\n```\r\n\r\n### Rich Text (Mixed Formatting)\r\n\r\nPrint text with different styles in the same line:\r\n\r\n```typescript\r\nawait CatPrinter.printRichText({\r\n  segments: [\r\n    { text: 'Normal ' },\r\n    { text: 'Bold', bold: true },\r\n    { text: ' and ' },\r\n    { text: 'Italic', italic: true },\r\n    { text: ' Big', fontSize: 32 }  // per-segment font size\r\n  ],\r\n  fontSize: 24,\r\n  align: 'left',\r\n  lineSpacing: 1.2,\r\n  rtl: false,\r\n  fontPath: '/path/to/font.ttf',\r\n  energy: 0.6,\r\n  quality: 3,\r\n  feedAfter: 100\r\n});\r\n```\r\n\r\n### Print Image\r\n\r\n```typescript\r\nawait CatPrinter.printImage({\r\n  imageBase64: '...',     // base64 PNG/JPEG (no data: prefix)\r\n  threshold: 127,         // 0-255 for B/W conversion\r\n  dither: true,           // Floyd-Steinberg dithering\r\n  brightness: 0,          // -100 to 100\r\n  contrast: 0,            // -100 to 100\r\n  invert: false,\r\n  flipHorizontal: false,\r\n  flipVertical: false,\r\n  compress: false,        // for newer printers (GB03+)\r\n  energy: 0.6,\r\n  quality: 3,\r\n  feedAfter: 100\r\n});\r\n```\r\n\r\n### QR Code (Android only)\r\n\r\n```typescript\r\nawait CatPrinter.printQRCode({\r\n  data: 'https://example.com',\r\n  size: 200,\r\n  errorCorrection: 'M',   // 'L' | 'M' | 'Q' | 'H'\r\n  align: 'center',\r\n  energy: 0.6,\r\n  feedAfter: 100\r\n});\r\n```\r\n\r\nOn web, generate the QR code with a library like `qrcode` and use `printImage()`:\r\n\r\n```typescript\r\nimport QRCode from 'qrcode';\r\nconst base64 = await QRCode.toDataURL('https://example.com');\r\nawait CatPrinter.printImage({\r\n  imageBase64: base64.replace('data:image/png;base64,', '')\r\n});\r\n```\r\n\r\n### Barcode (Android only)\r\n\r\n```typescript\r\nawait CatPrinter.printBarcode({\r\n  data: '123456789',\r\n  type: 'CODE128',        // CODE128, CODE39, EAN13, EAN8, UPC_A, UPC_E, ITF, CODABAR\r\n  height: 80,\r\n  showText: true,\r\n  align: 'center',\r\n  energy: 0.6,\r\n  feedAfter: 100\r\n});\r\n```\r\n\r\nOn web, generate the barcode with a library like `JsBarcode` and use `printImage()`.\r\n\r\n### Table / Receipt\r\n\r\n```typescript\r\nawait CatPrinter.printTable({\r\n  rows: [\r\n    { columns: [{ text: 'RECEIPT', align: 'center' }], bold: true, fontSize: 28 },\r\n    { columns: [{ text: '─'.repeat(16), align: 'center' }] },\r\n    { \r\n      columns: [\r\n        { text: 'Item', width: 60 },           // width as percentage\r\n        { text: 'Price', width: 40, align: 'right' }\r\n      ], \r\n      bold: true \r\n    },\r\n    { columns: [{ text: 'Coffee' }, { text: '$4.00', align: 'right' }] },\r\n    { columns: [{ text: 'Muffin' }, { text: '$3.50', align: 'right' }] },\r\n    { columns: [{ text: '─'.repeat(16), align: 'center' }] },\r\n    { columns: [{ text: 'Total' }, { text: '$7.50', align: 'right' }], bold: true }\r\n  ],\r\n  fontSize: 22,\r\n  showLines: false,       // horizontal lines between rows\r\n  lineChar: '-',          // character for lines\r\n  borderStyle: 'none',    // 'none' | 'all' | 'outer' | 'horizontal' | 'header'\r\n  energy: 0.6,\r\n  feedAfter: 100\r\n});\r\n```\r\n\r\n### Paper Control\r\n\r\n```typescript\r\nawait CatPrinter.feedPaper({ pixels: 100 });\r\nawait CatPrinter.retractPaper({ pixels: 50 });\r\nawait CatPrinter.cancelPrint();\r\n```\r\n\r\n### Auto-Reconnect (Android only)\r\n\r\n```typescript\r\nawait CatPrinter.setAutoReconnect({\r\n  enabled: true,\r\n  maxAttempts: 3,\r\n  delayMs: 2000\r\n});\r\n```\r\n\r\nOn web, this is a no-op. The browser manages BLE connection lifecycle.\r\n\r\n### Printer Info\r\n\r\n```typescript\r\n// Get printer model\r\nconst model = await CatPrinter.getPrinterModel();\r\n// { model: 'GB03', isNewKind: true, hasFeedingProblems: false, paperWidth: 384, deviceName: '...' }\r\n\r\n// Get printer status\r\nconst status = await CatPrinter.getPrinterStatus();\r\n// { connected, batteryLevel, isCharging, hasPaper, firmwareVersion, paperWidth }\r\n\r\n// Get raw device info\r\nconst info = await CatPrinter.getDeviceInfo();\r\n```\r\n\r\n### Preview (Without Printing)\r\n\r\n```typescript\r\nconst preview = await CatPrinter.getPreview({\r\n  type: 'text',\r\n  options: { text: 'Preview this', fontSize: 24 }\r\n});\r\n// { imageBase64, width, height }\r\n```\r\n\r\nSupported preview types: `image`, `text`, `richtext`, `table`. Barcode and QR code previews are Android only.\r\n\r\n### Events\r\n\r\n```typescript\r\n// Device found during scan\r\nCatPrinter.addListener('scanResult', (device) => {\r\n  console.log('Found:', device.name, device.address);\r\n});\r\n\r\n// Connection state changed\r\nCatPrinter.addListener('connectionState', (state) => {\r\n  console.log('Connected:', state.connected);\r\n});\r\n\r\n// Print progress\r\nCatPrinter.addListener('printProgress', (progress) => {\r\n  console.log(`${progress.percent}% - ${progress.status}`);\r\n  // status: 'processing' | 'printing' | 'feeding' | 'done' | 'error'\r\n});\r\n\r\n// Remove all listeners\r\nawait CatPrinter.removeAllListeners();\r\n```\r\n\r\n### Platform Detection\r\n\r\n```typescript\r\nimport { Capacitor } from '@capacitor/core';\r\n\r\nif (Capacitor.getPlatform() === 'web') {\r\n  // Web: scan() opens browser device picker\r\n  // Show a \"Select Printer\" button that triggers scan()\r\n} else {\r\n  // Android: scan() returns a list of nearby devices\r\n  // Show a scanning UI with device list\r\n}\r\n```\r\n\r\n## Constants\r\n\r\n```typescript\r\nimport { PaperWidth, BarcodeType, PrinterModels } from 'capacitor-cat-printer';\r\n\r\nPaperWidth.MM_58  // 384\r\nPaperWidth.MM_80  // 576\r\n\r\nBarcodeType.CODE128\r\nBarcodeType.EAN13\r\n// etc.\r\n\r\nPrinterModels.GB01\r\nPrinterModels.GB03\r\nPrinterModels.MX05\r\n// etc.\r\n```\r\n\r\n## Supported Printers\r\n\r\nWorks with Cat thermal printers and compatibles using BLE characteristics:\r\n- TX: `0000ae01-0000-1000-8000-00805f9b34fb`\r\n- RX: `0000ae02-0000-1000-8000-00805f9b34fb`\r\n\r\nKnown models: GB01, GB02, GB03, GT01, MX05, MX06, MX08, MX09, MX10, MX11, YT01\r\n\r\n## Tips\r\n\r\n- Enable Location Services for BLE scanning on Android\r\n- Use `energy: 0.6-0.8` for darker prints\r\n- Enable `dither: true` for images with gradients\r\n- Use `quality: 4` for best quality (slower)\r\n- Lower `threshold` = more black pixels in images\r\n- On web, ensure your app is served over HTTPS\r\n- On web, `scan()` must be triggered by a user gesture (click/tap)\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}