tauri-plugin-sumup 0.1.3

# Tauri Plugin SumUp

A Tauri plugin for integrating SumUp payment processing into your mobile applications. This plugin provides a bridge between Tauri applications and the native SumUp SDK for iOS (Android support coming soon).

## Features

- Initialize SumUp SDK with your affiliate key
- Authenticate users with access tokens
- Retrieve merchant information
- Present card reader selection interface
- Process payments with card readers
- Full TypeScript support with type definitions
- iOS support (Android coming soon)
- Desktop platforms return clear error messages

## Platform Support

| Platform |  Supported  |
|----------|-------------|
| iOS      | Yes         |
| Android  | No (TODO)   |
| Desktop  | No (No SDK) |

## Prerequisites

- Tauri 2.0 or later
- A SumUp merchant account
- SumUp affiliate key
- SumUp access token for authentication
- **For iOS**: SumUp iOS SDK framework (see [iOS Setup Guide](IOS_SETUP.md))

## Installation

### Install the Rust crate

Add the plugin to your `Cargo.toml`:

```toml
[dependencies]
tauri-plugin-sumup = "0.1"
```

### Install the JavaScript package

```bash
npm install tauri-plugin-sumup-api
# or
pnpm add tauri-plugin-sumup-api
# or
yarn add tauri-plugin-sumup-api
```

### Register the plugin

In your Tauri application's `src-tauri/src/main.rs` or `src-tauri/src/lib.rs`:

```rust
fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_sumup::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

### Configure permissions

Add the plugin permissions to your `src-tauri/capabilities/default.json`:

```json
{
  "permissions": [
    "sumup:default"
  ]
}
```

## API Reference

### TypeScript API

#### `initSumupSdk(affiliateKey: string): Promise<boolean>`

Initialize the SumUp SDK with your affiliate key.

```typescript
import { initSumupSdk } from 'tauri-plugin-sumup-api';

await initSumupSdk('your-affiliate-key');
```

#### `loginWithToken(token: string): Promise<boolean>`

Authenticate with SumUp using an access token.

```typescript
import { loginWithToken } from 'tauri-plugin-sumup-api';

await loginWithToken('your-access-token');
```

#### `isLoggedIn(): Promise<boolean>`

Check if a user is currently logged in.

```typescript
import { isLoggedIn } from 'tauri-plugin-sumup-api';

const loggedIn = await isLoggedIn();
```

#### `logout(): Promise<void>`

Log out the current user.

```typescript
import { logout } from 'tauri-plugin-sumup-api';

await logout();
```

#### `getMerchant(): Promise<MerchantInfo>`

Get information about the current merchant.

```typescript
import { getMerchant } from 'tauri-plugin-sumup-api';

const merchant = await getMerchant();
console.log(merchant.merchantCode, merchant.currencyCode);
```

#### `prepareForCheckout(): Promise<void>`

Prepare the SDK for checkout. This should be called before presenting the card reader selection.

```typescript
import { prepareForCheckout } from 'tauri-plugin-sumup-api';

await prepareForCheckout();
```

#### `presentCardReaderSelection(): Promise<void>`

Present the card reader selection interface to the user.

```typescript
import { presentCardReaderSelection } from 'tauri-plugin-sumup-api';

await presentCardReaderSelection();
```

#### `checkout(request: CheckoutRequest): Promise<CheckoutResult>`

Process a payment transaction.

```typescript
import { checkout } from 'tauri-plugin-sumup-api';

const result = await checkout({
  total: 10.00,
  currency: 'EUR',
  title: 'Test Payment',
  receiptEmail: 'customer@example.com', // optional
  receiptSms: '+1234567890', // optional
  foreignTransactionId: 'your-transaction-id', // optional
  skipSuccessScreen: false, // optional
  skipFailedScreen: false, // optional
  additionalInfo: { // optional
    key1: 'value1',
    key2: 'value2'
  }
});

console.log(result.transactionCode, result.status);
```

#### `performCardReaderPayment(affiliateKey: string, token: string, request: CheckoutRequest): Promise<CheckoutResult>`

Convenience function that performs the complete payment flow: initialize SDK, login, prepare checkout, present card reader selection, and process payment.

```typescript
import { performCardReaderPayment } from 'tauri-plugin-sumup-api';

const result = await performCardReaderPayment(
  'your-affiliate-key',
  'your-access-token',
  {
    total: 10.00,
    currency: 'EUR',
    title: 'Test Payment'
  }
);
```

### Types

#### `CheckoutRequest`

```typescript
interface CheckoutRequest {
  total: number;
  currency: string;
  title?: string;
  receiptEmail?: string;
  receiptSms?: string;
  additionalInfo?: Record<string, string>;
  foreignTransactionId?: string;
  skipSuccessScreen?: boolean;
  skipFailedScreen?: boolean;
}
```

#### `CheckoutResult`

```typescript
interface CheckoutResult {
  transactionCode?: string;
  cardType?: string;
  merchantCode?: string;
  amount?: number;
  currency?: string;
  status: string;
  paymentType?: string;
  entryMode?: string;
  installments?: number;
}
```

#### `MerchantInfo`

```typescript
interface MerchantInfo {
  merchantCode: string;
  currencyCode: string;
}
```

## Usage Example

```typescript
import { 
  initSumupSdk, 
  loginWithToken, 
  isLoggedIn,
  prepareForCheckout,
  presentCardReaderSelection,
  checkout 
} from 'tauri-plugin-sumup-api';

async function processPayment() {
  try {
    // Initialize SDK
    await initSumupSdk('sup_afk_XXXXXXXXXXXXX');
    
    // Login if not already logged in
    if (!(await isLoggedIn())) {
      await loginWithToken('your-access-token');
    }
    
    // Prepare for checkout
    await prepareForCheckout();
    
    // Let user select card reader
    await presentCardReaderSelection();
    
    // Process payment
    const result = await checkout({
      total: 25.50,
      currency: 'EUR',
      title: 'Coffee and Croissant'
    });
    
    console.log('Payment successful:', result.transactionCode);
  } catch (error) {
    console.error('Payment failed:', error);
  }
}
```

## Important Notes

### Currency Matching

The currency code used in your checkout request must match the currency configured in your SumUp merchant account. Mismatched currencies will result in an error (SumUp SDK error 52).

You can retrieve your merchant's currency using `getMerchant()`:

```typescript
const merchant = await getMerchant();
console.log('Merchant currency:', merchant.currencyCode);
```

### Threading

All UI operations (card reader selection, checkout) are automatically dispatched to the main thread by the plugin. You don't need to worry about thread safety when calling these functions.

### Desktop Platform Support

This plugin is designed for mobile platforms only. When used on desktop platforms (Windows, macOS, Linux), all plugin methods will return a clear error:

```
Error: SumUp plugin is not supported on desktop platforms. This plugin requires iOS or Android.
```

This allows you to include the plugin in your project and handle desktop platforms gracefully:

```typescript
try {
  await initSumupSdk(affiliateKey);
} catch (error) {
  if (error.includes('not supported on desktop')) {
    console.log('Payment features unavailable on desktop');
    // Show alternative payment method or message
  }
}
```

### Platform-Specific Configuration

#### iOS

**Important**: You must manually download and install the SumUp iOS SDK framework. See the [iOS Setup Guide](IOS_SETUP.md) for detailed instructions.

Ensure your iOS deployment target is set appropriately in your `tauri.conf.json`:

```json
{
  "identifier": "com.yourcompany.yourapp",
  "ios": {
    "minimumSystemVersion": "13.0"
  }
}
```

#### Android

Android support is planned but not yet implemented. Contributions are welcome!

## Development

### Building the Plugin

```bash
# Build Rust code
cargo build

# Build JavaScript/TypeScript code
pnpm install
pnpm build
```

### Running the Example

```bash
cd examples/tauri-app
pnpm install
pnpm tauri ios dev
# or
pnpm tauri android dev
```

## Troubleshooting

### "Currency code mismatch" error

Ensure the currency in your checkout request matches your merchant account's currency. Check using `getMerchant()`.

### "Not logged in" error

Call `loginWithToken()` before attempting checkout operations.

### UI not presenting

Ensure you've called `prepareForCheckout()` before presenting the card reader selection.

## License

MIT or Apache-2.0

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Support

For SumUp SDK specific questions, refer to the official SumUp documentation:
- [SumUp iOS SDK Documentation](https://github.com/sumup/sumup-ios-sdk)
- [SumUp Android SDK Documentation](https://github.com/sumup/sumup-android-sdk)

For plugin-related issues, please open an issue on the GitHub repository.