sunmi-device-sdk/MIGRATION.md

JavaScript SDK for Sunmi card readers and printers

# Migration Guide: Cordova Plugin → npm Package

## Overview

This guide helps you migrate from the Cordova plugin to the new npm package.

## Installation

### Old (Cordova Plugin)
```bash
cordova plugin add sunmi-card-reader
```

### New (npm Package)
```bash
npm install @sunmi/device-sdk
```

## API Changes

### Card Reader

#### Old Cordova API
```javascript
// Global object exposed by Cordova
SunmiCardReader.startReadCard(['mifare'])
  .then(result => console.log(result))
  .catch(err => console.error(err));
```

#### New npm API
```javascript
// Import from package
import { SunmiCardReader } from '@sunmi/device-sdk';

// Same promise-based API
const result = await SunmiCardReader.startReadCard(['mifare']);
```

### Printer

#### Old Cordova API
```javascript
// Global object
sunmiInnerPrinter.printerInit()
  .then(() => sunmiInnerPrinter.printString('Hello'))
  .then(() => sunmiInnerPrinter.lineWrap(3));
```

#### New npm API
```javascript
// Import and use cleaner method names
import { SunmiPrinter } from '@sunmi/device-sdk';

await SunmiPrinter.init();
await SunmiPrinter.printText('Hello');
await SunmiPrinter.feedPaper(3);
```

## Method Name Changes

### Printer Methods

| Old Name | New Name |
|----------|----------|
| `printerInit` | `init` |
| `lineWrap` | `feedPaper` |
| `printString` | `printText` |
| `getPrinterSerialNo` | `getSerialNumber` |
| `printerSelfChecking` | `selfCheck` |

All card reader methods remain the same.

## Type Safety (TypeScript)

### Before
```javascript
// No type checking
sunmiInnerPrinter.setAlignment(1); // What does 1 mean?
```

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

// Type-safe with enums
await SunmiPrinter.setAlignment(PrintAlignment.CENTER);
```

## Platform Support

The new package supports:
- ✅ **Cordova** (backward compatible)
- ✅ **React Native** (with native modules)
- ✅ **Capacitor** (with plugins)

## Complete Example Migration

### Before (Cordova)
```javascript
document.addEventListener('deviceready', function() {
  // Wait for Cordova
  
  sunmiInnerPrinter.printerInit().then(() => {
    return sunmiInnerPrinter.setAlignment(1);
  }).then(() => {
    return sunmiInnerPrinter.printString('Hello');
  }).then(() => {
    return sunmiInnerPrinter.lineWrap(3);
  }).catch(err => {
    console.error(err);
  });
});
```

### After (npm package)
```javascript
import { SunmiPrinter, PrintAlignment } from '@sunmi/device-sdk';

document.addEventListener('deviceready', async function() {
  try {
    await SunmiPrinter.init();
    await SunmiPrinter.setAlignment(PrintAlignment.CENTER);
    await SunmiPrinter.printText('Hello');
    await SunmiPrinter.feedPaper(3);
  } catch (err) {
    console.error(err);
  }
});
```

## React Native Setup

If using React Native, you need to create native modules:

```java
// android/app/src/main/java/com/yourapp/SunmiPrinterModule.java
public class SunmiPrinterModule extends ReactContextBaseJavaModule {
  @ReactMethod
  public void printerInit(Promise promise) {
    // Your implementation using the Sunmi printer SDK
  }
  
  // ... other methods
}
```

Then register in MainApplication.java:
```java
@Override
protected List<ReactPackage> getPackages() {
  return Arrays.asList(
    new MainReactPackage(),
    new SunmiPrinterPackage() // Your package
  );
}
```

## Capacitor Setup

For Capacitor, create a plugin:

```bash
npm init @capacitor/plugin
```

Then implement the native Android code following Capacitor's plugin structure.

## Testing Your Migration

1. Install the package: `npm install @sunmi/device-sdk`
2. Update imports from global objects to package imports
3. Update method names (see table above)
4. Test on a Sunmi device
5. Enjoy better TypeScript support!

## Need Help?

- Check the [examples/](./examples/) directory for working code
- Read the [README.md](./README.md) for full API documentation
- Open an issue on GitHub