sunmi-device-sdk/README.md

JavaScript SDK for Sunmi card readers and printers

# Sunmi Device SDK

A modern JavaScript/TypeScript SDK for Sunmi card readers and thermal printers. Works with **Expo**, React Native, Cordova, and Capacitor.

## Features

- 🃏 **Card Reader Support**: Read/write Mifare cards, IC cards, and magnetic cards
- 🖨️ **Thermal Printer**: Full control over Sunmi thermal printers
- 📘 **TypeScript**: Full type definitions included
- 🔌 **Multi-Platform**: Works with **Expo**, React Native, Cordova, and Capacitor
- 🎯 **Promise-based**: Modern async/await API
- ⚡ **No Cordova Required**: Pure npm package for modern apps

## Installation

```bash
npm install @sunmi/device-sdk
```

## Quick Start

### Card Reader

```typescript
import { SunmiCardReader, CardType } from '@sunmi/device-sdk';

// Start reading a card
const result = await SunmiCardReader.startReadCard(['mifare', 'ic']);
console.log('Card detected:', result);

// Authenticate and read Mifare card
await SunmiCardReader.authMifare('FFFFFFFFFFFF', 'A', 4);
const data = await SunmiCardReader.readBlockMifare(4);
console.log('Block data:', data);
```

### Thermal Printer

```typescript
import { SunmiPrinter, PrintAlignment } from '@sunmi/device-sdk';

// Initialize printer
await SunmiPrinter.init();

// Print some text
await SunmiPrinter.setAlignment(PrintAlignment.CENTER);
await SunmiPrinter.setFontSize(24);
await SunmiPrinter.printText('Hello, Sunmi!');

// Print QR code
await SunmiPrinter.printQRCode('https://example.com', 8, 1);

// Feed paper and finish
await SunmiPrinter.feedPaper(3);
```

## API Documentation

### Card Reader

#### `startReadCard(cardTypes: string[]): Promise<CardReadResult>`
Start reading a card. Supports multiple card types: `'mifare'`, `'ic'`, `'magnetic'`, `'psam'`.

#### `authMifare(blockKey: string, keyType: 'A' | 'B', blockToRead: number): Promise<void>`
Authenticate a Mifare card block before reading/writing.

#### `readBlockMifare(blockToRead: number): Promise<string>`
Read data from an authenticated Mifare block. Returns hex string.

#### `writeBlockMifare(blockToWrite: number, data: string): Promise<void>`
Write data to a Mifare block. Data must be a 16-byte hex string.

#### `cancelCheckCard(): Promise<void>`
Cancel an ongoing card reading operation.

### Printer

#### `init(): Promise<void>`
Initialize the printer. Call this before any other printer operations.

#### `printText(text: string): Promise<void>`
Print text with current settings.

#### `printTextWithFont(text: string, typeface: string, fontSize: number): Promise<void>`
Print text with specific font settings.

#### `setAlignment(alignment: PrintAlignment): Promise<void>`
Set text alignment. Options: `LEFT`, `CENTER`, `RIGHT`.

#### `setFontSize(fontSize: number): Promise<void>`
Set font size in points.

#### `printQRCode(data: string, moduleSize: number, errorLevel: number): Promise<void>`
Print a QR code.
- `moduleSize`: 1-16 (size of each QR module)
- `errorLevel`: 0-3 (error correction level)

#### `printBarcode(data: string, symbology: string, width: number, height: number, textPosition: BarcodeTextPosition): Promise<void>`
Print a barcode. Supports various symbologies like `'CODE128'`, `'EAN13'`, etc.

#### `printBitmap(base64Data: string, width: number, height: number): Promise<void>`
Print a bitmap image from base64-encoded data.

#### `printColumns(columns: string[], widths: number[], alignments: PrintAlignment[]): Promise<void>`
Print text in columns (useful for receipts).

#### `feedPaper(lines: number): Promise<void>`
Feed paper by specified number of lines.

#### `getSerialNumber(): Promise<string>`
Get printer serial number.

#### `getVersion(): Promise<string>`
Get printer firmware version.

#### `hasPrinter(): Promise<boolean>`
Check if printer is available on the device.

## Platform Setup

### Expo 🚀 (Easiest!)

**Perfect for Expo users!** Uses Expo's prebuild workflow:

1. **Install:**
   ```bash
   npm install @sunmi/device-sdk
   ```

2. **Prebuild:**
   ```bash
   npx expo prebuild
   ```

3. **Copy native files and register packages** (one-time setup)

4. **Use it:**
   ```typescript
   import { SunmiPrinter } from '@sunmi/device-sdk';
   await SunmiPrinter.printText('Hello from Expo!');
   ```

**See `EXPO_SETUP.md` for complete step-by-step instructions** and check out the `expo-example/` folder for a working app!

### React Native ⚡

**No Cordova needed!** Follow these steps:

1. **Install the package:**
   ```bash
   npm install @sunmi/device-sdk
   ```

2. **Add native modules:**
   Copy the bridge files from `react-native/` directory to your Android project:
   - `SunmiPrinterModule.java`
   - `SunmiPrinterPackage.java`
   - `SunmiCardReaderModule.java`
   - `SunmiCardReaderPackage.java`

3. **Copy native Android code:**
   ```bash
   cp -r src/android/com your-rn-project/android/app/src/main/java/
   cp -r src/android/woyou your-rn-project/android/app/src/main/aidl/
   cp libs/rel.aar your-rn-project/android/app/libs/
   ```

4. **Register in MainApplication.java:**
   ```java
   import com.sunmi.SunmiCardReaderPackage;
   import com.sunmi.SunmiPrinterPackage;
   
   @Override
   protected List<ReactPackage> getPackages() {
     return Arrays.asList(
       new MainReactPackage(),
       new SunmiCardReaderPackage(),
       new SunmiPrinterPackage()
     );
   }
   ```

5. **Use in your app:**
   ```typescript
   import { SunmiPrinter } from '@sunmi/device-sdk';
   await SunmiPrinter.printText('Hello from React Native!');
   ```

See `react-native/README.md` for complete setup instructions.

### Cordova

The package maintains Cordova compatibility. The existing plugin.xml works as-is.

### Capacitor

Similar setup to React Native. Create Capacitor plugins using the native Android code.

## Examples

### Print a Receipt

```typescript
import { SunmiPrinter, PrintAlignment } from '@sunmi/device-sdk';

async function printReceipt() {
  await SunmiPrinter.init();
  
  // Header
  await SunmiPrinter.setAlignment(PrintAlignment.CENTER);
  await SunmiPrinter.setFontSize(28);
  await SunmiPrinter.printText('My Store Name');
  await SunmiPrinter.feedPaper(1);
  
  // Items
  await SunmiPrinter.setAlignment(PrintAlignment.LEFT);
  await SunmiPrinter.setFontSize(20);
  await SunmiPrinter.printColumns(
    ['Item 1', '10.00'],
    [20, 10],
    [PrintAlignment.LEFT, PrintAlignment.RIGHT]
  );
  
  await SunmiPrinter.printColumns(
    ['Item 2', '15.00'],
    [20, 10],
    [PrintAlignment.LEFT, PrintAlignment.RIGHT]
  );
  
  // Total
  await SunmiPrinter.feedPaper(1);
  await SunmiPrinter.printColumns(
    ['TOTAL', '25.00'],
    [20, 10],
    [PrintAlignment.LEFT, PrintAlignment.RIGHT]
  );
  
  await SunmiPrinter.feedPaper(3);
}
```

### Read Mifare Card

```typescript
import { SunmiCardReader } from '@sunmi/device-sdk';

async function readCard() {
  // Start reading
  const card = await SunmiCardReader.startReadCard(['mifare']);
  console.log('Card UID:', card.uid);
  
  // Authenticate with default key
  const block = 4;
  await SunmiCardReader.authMifare('FFFFFFFFFFFF', 'A', block);
  
  // Read data
  const data = await SunmiCardReader.readBlockMifare(block);
  console.log('Block data:', data);
}
```

## Error Handling

All methods return promises that reject on error:

```typescript
try {
  await SunmiPrinter.printText('Hello');
} catch (error) {
  console.error('Print failed:', error);
}
```

## License

MIT

## Contributing

Contributions welcome! Please open an issue or PR on GitHub.