# expo-esim-manager

Expo module for managing eSIM functionality on Android devices. This module provides a comprehensive interface for installing, managing, and monitoring eSIM profiles on Android devices that support eSIM technology.

## Features

- ✅ Install eSIM profiles using activation codes
- ✅ Scan QR codes for eSIM installation
- ✅ List installed eSIM profiles
- ✅ Check eSIM support on device
- ✅ Diagnostic information
- ✅ Real-time installation status tracking
- ✅ Comprehensive error handling
- ✅ React Hook for easy integration

## Platform Support

- **Android**: ✅ Full support
- **iOS**: ❌ Not implemented (iOS eSIM management requires different APIs)

## Installation

```bash
npx expo install expo-esim-manager
```

## Permissions

This module requires the following Android permissions:

- `READ_PHONE_STATE`
- `READ_PHONE_NUMBERS`

The module will automatically request these permissions when needed.

## Usage

### Basic Usage

```javascript
import { ExpoEsimManager, useEsimManager } from "expo-esim-manager";

// Check if device supports eSIM
const isSupported = ExpoEsimManager.isEsimSupported();

// Get installed eSIM profiles
const installedEsims = ExpoEsimManager.getInstalledEsims();

// Install eSIM using activation code
const installEsim = async (activationCode) => {
  try {
    const result = await ExpoEsimManager.install({ activationCode });
    console.log("eSIM installed successfully:", result);
  } catch (error) {
    console.error("Installation failed:", error);
  }
};

// Scan QR code for eSIM installation
const scanQrCode = async () => {
  try {
    const result = await ExpoEsimManager.scanQrCode();
    console.log("eSIM installed from QR code:", result);
  } catch (error) {
    console.error("QR scan failed:", error);
  }
};
```

### Using the React Hook

```javascript
import React from "react";
import { View, Text, Button } from "react-native";
import { useEsimManager, InstallationStatus } from "expo-esim-manager";

export default function EsimManager() {
  const {
    permissionsGranted,
    installedEsims,
    installationStatus,
    installError,
    installESim,
    scanQrCode,
    runDiagnostic,
  } = useEsimManager();

  const handleInstall = async () => {
    await installESim("your-activation-code-here");
  };

  const handleScanQr = async () => {
    await scanQrCode();
  };

  return (
    <View>
      <Text>Permissions: {permissionsGranted ? "Granted" : "Not Granted"}</Text>
      <Text>Installed eSIMs: {installedEsims.length}</Text>
      <Text>Status: {installationStatus}</Text>

      {installError && <Text>Error: {installError.message}</Text>}

      <Button title="Install eSIM" onPress={handleInstall} />
      <Button title="Scan QR Code" onPress={handleScanQr} />
      <Button title="Run Diagnostic" onPress={runDiagnostic} />
    </View>
  );
}
```

## API Reference

### Core Functions

#### `isEsimSupported(): boolean`

Checks if the device supports eSIM functionality.

#### `getInstalledEsims(): EsimInfo[]`

Returns an array of installed eSIM profiles.

#### `install(params: { activationCode: string }): Promise<EsimInstallResult>`

Installs an eSIM profile using an activation code.

#### `scanQrCode(): Promise<EsimInstallResult>`

Opens QR code scanner for eSIM installation.

#### `diagnosticInfo(): Record<string, any>`

Returns diagnostic information about the eSIM system.

### React Hook: `useEsimManager()`

Returns an object with the following properties:

#### State Properties

- `permissionsGranted: boolean` - Whether required permissions are granted
- `installedEsims: EsimInfo[]` - Array of installed eSIM profiles
- `diagnosticData: any` - Diagnostic information
- `installationStatus: InstallationStatus` - Current installation status
- `installError: InstallError` - Error information if installation failed

#### Actions

- `installESim(activationCode: string): Promise<void>` - Install eSIM with activation code
- `scanQrCode(): Promise<void>` - Scan QR code for eSIM installation
- `runDiagnostic(): void` - Run diagnostic check
- `checkInstalledEsims(): void` - Refresh installed eSIM list

### Types

#### `EsimInfo`

```typescript
type EsimInfo = {
  displayName: string;
  carrierName: string;
  isActive: boolean;
  subscriptionId: number;
  countryIso: string;
};
```

#### `EsimInstallResult`

```typescript
type EsimInstallResult = {
  status: "success";
  message: string;
};
```

#### `InstallationStatus`

```typescript
enum InstallationStatus {
  NotStarted = "NotStarted",
  Started = "Started",
  Confirming = "Confirming",
  Completed = "Completed",
  Failed = "Failed",
  Cancelled = "Cancelled",
}
```

#### `EsimInstallError`

```typescript
type EsimInstallError = {
  code: string; // Various error codes
  message: string;
};
```

## Error Codes

The module provides comprehensive error handling with specific error codes:

- `INVALID_ACTIVATION_CODE` - Invalid or expired activation code
- `PROFILE_ALREADY_EXISTS` - eSIM profile already installed
- `NETWORK_ERROR` - Network connectivity issues
- `SERVER_ERROR` - Server-side errors
- `USER_CANCELED` - User cancelled the operation
- `UNSUPPORTED_ERROR` - Device doesn't support eSIM
- `AMBIGUOUS_RESULT` - Installation result unclear (requires verification)

And many more specific error codes for different scenarios.

## Example Project

Check out the `example/` directory for a complete working example of how to use this module.

## Development

```bash
# Install dependencies
npm install

# Build the module
npm run build

# Run tests
npm test

# Open example app
npm run open:android
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](https://github.com/fleye-me/expo-esim-mananger)
- 🐛 [Report a bug](https://github.com/fleye-me/expo-esim-mananger/issues)
- 💡 [Request a feature](https://github.com/fleye-me/expo-esim-mananger/issues)