@airmoney-degn/controller-sdk/README.md

SDK for controlling AirMoney devices, providing button screen management, key event handling, and device communication capabilities

# AirMoney Controller SDK

A TypeScript SDK for interacting with AirMoney device. This SDK provides functionality to control device button screens, handle key events, and perform cryptographic operations.

## Installation

```bash
npm install @airmoney-degn/controller-sdk
# or
yarn add @airmoney-degn/controller-sdk
```

## Prerequisites

Before using the SDK, you need to set up the `AIRMONEY_APP_ID` which should match the `identifier` value in your `metadata.json` file. This file is automatically generated when you create a new project using the `airmoney-cli` tool.

Example `metadata.json`:
```json
{
  "identifier": "your-app-id",
  "name": "Your App Name",
  "version": "1.0.0",
  // ... other fields
}
```

### Option 1: Direct Window Assignment

```typescript
window.AIRMONEY_APP_ID = 'your-app-id'; // Must match the identifier in metadata.json
```

### Option 2: Using Vite Configuration

If you're using Vite, you can import the identifier from `metadata.json` and set it in your `vite.config.ts`:

```typescript
import { defineConfig } from 'vite';
import { identifier } from './metadata.json';

export default defineConfig({
  define: {
    'window.AIRMONEY_APP_ID': JSON.stringify(identifier),
  },
  // ... other config options
});
```

The SDK will use the `AIRMONEY_APP_ID` value from the window object, which must match the `identifier` in your `metadata.json` file.

## Usage

### Basic Setup

```typescript
import { AirMoneyService, AirMoneyCryptoService } from '@airmoney-degn/controller-sdk';

// Initialize the services
const airMoneyService = new AirMoneyService();
const cryptoService = new AirMoneyCryptoService();
```

### Display Images

Display a static image on either the left or right screen:

```typescript
// Display an image
await airMoneyService.displayImage({
  id: 'left', // or 'right'
  imageName: 'your-image.png'
});
```

### Display GIFs

Display an animated GIF on either the left or right screen:

```typescript
// Display a GIF
await airMoneyService.displayGif({
  id: 'left', // or 'right'
  imageName: 'your-animation.gif'
});
```

### MPC (Multi-Party Computation) Operations

> ⚠️ **Deprecated**: MPC functionality is deprecated and will be removed in a future version. Please migrate to alternative solutions.

Manage MPC sessions:

```typescript
// Set an MPC value
await airMoneyService.setMPC('key', 'value');

// Get an MPC value
const result = await airMoneyService.getMPC('key');
```

### Key Event Handling

Handle device key events with support for combinations and double clicks:

```typescript
import { AirMoneyKeyEvent, AMKey } from '@airmoney-degn/controller-sdk';

const keyEvent = new AirMoneyKeyEvent({
  threshold: 300, // milliseconds for long press
  combinations: {
    'combination-name': [AMKey.LeftButton, AMKey.RightButton] // Define key combinations
  },
  doubleClicks: {
    'double-click-name': AMKey.RotaryButton // Define double click keys
  },
  debug: true // Enable debug logging
});

keyEvent.on((event) => {
  switch (event.subType) {
    case 'press':
      console.log('Key pressed:', event.data.key);
      break;
    case 'longpressdown':
      console.log('Key long pressed down:', event.data.key);
      break;
    case 'longpressup':
      console.log('Key long pressed up:', event.data.key);
      break;
    case 'doubleclick':
      console.log('Key double clicked:', event.data.key);
      break;
    case 'combinationdown':
      console.log('Combination pressed:', event.data.name);
      break;
    case 'combinationup':
      console.log('Combination released:', event.data.name);
      break;
  }
});

// Clean up when done
keyEvent.off();
```

### Cryptographic Operations

#### EVM (Ethereum Virtual Machine) Operations

```typescript
// Generate a new EVM wallet
const walletResponse = await cryptoService.generateEvmWallet();
if (isAMCryptoServiceSuccessResponse(walletResponse)) {
  console.log('New wallet address:', walletResponse.result.address);
}

// List all EVM wallets
const walletsResponse = await cryptoService.listEvmWallets();
if (isAMCryptoServiceSuccessResponse(walletsResponse)) {
  console.log('Available wallets:', walletsResponse.result.wallets);
}

// Sign a message
const messageResponse = await cryptoService.signEvmMessage(
  '0x...', // wallet address
  'Hello, World!'
);
if (isAMCryptoServiceSuccessResponse(messageResponse)) {
  console.log('Message signature:', messageResponse.result.signature);
}

// Sign a transaction
const transactionResponse = await cryptoService.signEvmTransaction(
  '0x...', // wallet address
  {
    to: '0x...',
    value: '0x...',
    // ... other transaction parameters
  },
  '0x1' // chain ID
);
if (isAMCryptoServiceSuccessResponse(transactionResponse)) {
  console.log('Signed transaction:', transactionResponse.result.signed_transaction);
}
```

#### Solana Operations

```typescript
// Generate a new Solana wallet
const walletResponse = await cryptoService.generateSolanaWallet();
if (isAMCryptoServiceSuccessResponse(walletResponse)) {
  console.log('New wallet address:', walletResponse.result.address);
}

// List all Solana wallets
const walletsResponse = await cryptoService.listSolanaWallets();
if (isAMCryptoServiceSuccessResponse(walletsResponse)) {
  console.log('Available wallets:', walletsResponse.result.wallets);
}

// Sign a message
const messageResponse = await cryptoService.signSolanaMessage(
  '...', // wallet address
  'Hello, World!'
);
if (isAMCryptoServiceSuccessResponse(messageResponse)) {
  console.log('Message signature:', messageResponse.result.signature);
}

// Sign a transaction
const transactionResponse = await cryptoService.signSolanaTransaction({
  address: '...', // wallet address
  transaction_base64: '...' // base64 encoded transaction
});
if (isAMCryptoServiceSuccessResponse(transactionResponse)) {
  console.log('Signed transaction:', transactionResponse.result.signed_transaction);
}
```

### Utility Functions

```typescript
import { 
  backToHome,
  isValidNumber,
  toBoolean,
  normalizeEVMTransaction,
  toHexString
} from '@airmoney-degn/controller-sdk';

// Navigate back to home
backToHome();

// Validate numbers
const isValid = isValidNumber('123.45'); // true

// Convert string to boolean
const boolValue = toBoolean('true'); // true

// Normalize EVM transaction
const normalizedTx = normalizeEVMTransaction({
  to: '0x...',
  value: '1000000000000000000',
  // ... other transaction parameters
});

// Convert to hex string
const hexValue = toHexString(123); // '0x7b'
```

## API Reference

### AirMoneyService

#### Constructor
```typescript
new AirMoneyService()
```

#### Methods

##### displayImage
```typescript
displayImage(params: { id: 'left' | 'right', imageName: string }): Promise<AMServiceScreenResponse>
```
Displays a static image on the specified screen.

##### displayGif
```typescript
displayGif(params: { id: 'left' | 'right', imageName: string }): Promise<AMServiceScreenResponse>
```
Displays an animated GIF on the specified screen.

##### setMPC
```typescript
/**
 * @deprecated MPC functionality is deprecated and will be removed in a future version
 */
setMPC(key: string, value: string): Promise<AMServiceMPCSetResponse>
```
Sets a value in the MPC session.

##### getMPC
```typescript
/**
 * @deprecated MPC functionality is deprecated and will be removed in a future version
 */
getMPC(key: string): Promise<AMServiceMPCGetResponse>
```
Retrieves a value from the MPC session.

### AirMoneyKeyEvent

#### Constructor
```typescript
new AirMoneyKeyEvent(config?: Partial<AMKeyEventConfig>)
```

#### Configuration Options
```typescript
interface AMKeyEventConfig {
  threshold: number; // milliseconds for long press detection
  combinations?: Record<string, AMKey[]>; // key combinations
  doubleClicks?: Record<string, AMKey>; // double click keys
  debug?: boolean; // enable debug logging
}
```

#### Methods

##### on
```typescript
on(callback: AMKeyEventCallback): void
```
Registers a callback for key events.

##### off
```typescript
off(): void
```
Removes all event listeners and callbacks.

### AirMoneyCryptoService

#### Constructor
```typescript
new AirMoneyCryptoService()
```

#### EVM Methods

##### generateEvmWallet
```typescript
generateEvmWallet(): Promise<AMCryptoServiceEvmWalletResponse>
```
Generates a new EVM wallet.

##### listEvmWallets
```typescript
listEvmWallets(): Promise<AMCryptoServiceEvmWalletsResponse>
```
Lists all available EVM wallets.

##### signEvmMessage
```typescript
signEvmMessage(address: `0x${string}`, message: string): Promise<AMCryptoServiceEvmMessageResponse>
```
Signs a message with the specified EVM wallet.

##### signEvmTransaction
```typescript
signEvmTransaction(address: HexString, transaction: EVMTransaction, chainId: HexString): Promise<AMCryptoServiceEvmTransactionResponse>
```
Signs an EVM transaction.

##### signGeneralEvmTransaction
```typescript
signGeneralEvmTransaction(address: HexString, transaction: EVMTransaction, chainId: HexString): Promise<AMCryptoServiceEvmTransactionResponse>
```
Signs a general EVM transaction.

#### Solana Methods

##### generateSolanaWallet
```typescript
generateSolanaWallet(): Promise<AMCryptoServiceSolanaWalletResponse>
```
Generates a new Solana wallet.

##### listSolanaWallets
```typescript
listSolanaWallets(): Promise<AMCryptoServiceSolanaWalletsResponse>
```
Lists all available Solana wallets.

##### signSolanaMessage
```typescript
signSolanaMessage(address: string, message: string): Promise<AMCryptoServiceSolanaMessageResponse>
```
Signs a message with the specified Solana wallet.

##### signSolanaTransaction
```typescript
signSolanaTransaction(transaction: { address: string; transaction_base64: string }): Promise<AMCryptoServiceSolanaTransactionResponse>
```
Signs a Solana transaction.

### Utility Functions

#### backToHome
```typescript
backToHome(): void
```
Navigates back to the home page.

#### isValidNumber
```typescript
isValidNumber(value?: string): value is string
```
Validates if a string is a valid number.

#### toBoolean
```typescript
toBoolean(value: string): boolean
```
Converts a string to a boolean value.

#### normalizeEVMTransaction
```typescript
normalizeEVMTransaction(obj: RawEVMTransaction): EVMTransaction
```
Normalizes an EVM transaction object.

#### toHexString
```typescript
toHexString(obj: bigint | number | string): HexString
```
Converts a value to a hex string.

## License

MIT © AirMoney