expo-mercadopago-integration/README.md

Expo library for integrating Mercado Pago native SDK without ejecting

# Expo Mercado Pago SDK

Una librería npm para integrar el SDK nativo de Mercado Pago en aplicaciones Expo sin necesidad de ejectar.

## 🚀 Características

- ✅ Integración completa con el SDK nativo de Mercado Pago
- ✅ Soporte para iOS y Android
- ✅ No requiere ejectar de Expo
- ✅ TypeScript support
- ✅ Manejo de eventos de pago
- ✅ Verificación de app instalada
- ✅ Configuración automática de permisos

## 📦 Instalación

```bash
npm install expo-mercadopago-sdk
```

## 🔧 Configuración

### 1. Configurar el plugin en app.json

```json
{
  "expo": {
    "plugins": [
      [
        "./node_modules/expo-mercadopago-sdk/plugin.js",
        {
          "publicKey": "TEST-12345678-1234-1234-1234-123456789012"
        }
      ]
    ]
  }
}
```

### 2. Configurar las credenciales

Obtén tu `public_key` desde el [panel de desarrolladores de Mercado Pago](https://www.mercadopago.com.ar/developers/panel/credentials).

## 📖 Uso

### Inicialización básica

```typescript
import { createMercadoPagoSDK, MercadoPagoConfig } from 'expo-mercadopago-sdk';

const config: MercadoPagoConfig = {
  publicKey: 'TEST-12345678-1234-1234-1234-123456789012',
  siteId: 'MLA', // Argentina
  language: 'es',
};

const mercadopago = createMercadoPagoSDK(config);
await mercadopago.initialize();
```

### Iniciar un pago

```typescript
// Opción 1: Usando preference ID
const result = await mercadopago.startPayment('123456789-12345678-12345678-12345678');

// Opción 2: Configurando preference ID en la configuración
const config: MercadoPagoConfig = {
  publicKey: 'TEST-12345678-1234-1234-1234-123456789012',
  preferenceId: '123456789-12345678-12345678-12345678',
};

const mercadopago = createMercadoPagoSDK(config);
await mercadopago.initialize();
const result = await mercadopago.startPayment();
```

### Escuchar eventos de pago

```typescript
const subscription = mercadopago.addPaymentResultListener((result) => {
  switch (result.status) {
    case 'approved':
      console.log('Pago aprobado:', result.paymentId);
      break;
    case 'rejected':
      console.log('Pago rechazado:', result.statusDetail);
      break;
    case 'pending':
      console.log('Pago pendiente');
      break;
    case 'in_process':
      console.log('Pago en proceso');
      break;
  }
});

// Limpiar listener cuando no se necesite
mercadopago.removePaymentResultListener(subscription);
```

### Verificar si Mercado Pago está instalado

```typescript
const isInstalled = await mercadopago.isMercadoPagoInstalled();
console.log('Mercado Pago instalado:', isInstalled);
```

### Obtener versión del SDK

```typescript
const version = await mercadopago.getSDKVersion();
console.log('Versión del SDK:', version);
```

## 🏗️ Estructura del proyecto

```
expo-mercadopago-sdk/
├── src/
│   └── ExpoMercadoPagoModule.ts    # Interfaz TypeScript
├── ios/
│   ├── ExpoMercadoPagoModule.swift # Módulo nativo iOS
│   └── ExpoMercadoPagoModule.podspec
├── android/
│   ├── build.gradle
│   └── src/main/java/expo/modules/mercadopago/
│       └── ExpoMercadoPagoModule.kt # Módulo nativo Android
├── plugin.js                       # Plugin de configuración Expo
├── example/
│   └── App.tsx                     # Ejemplo de uso
├── package.json
└── README.md
```

## 🔌 API Reference

### MercadoPagoConfig

```typescript
interface MercadoPagoConfig {
  publicKey: string;        // Tu public key de Mercado Pago
  preferenceId?: string;    // ID de preferencia (opcional)
  siteId?: string;         // ID del sitio (ej: 'MLA' para Argentina)
  language?: string;       // Idioma (ej: 'es', 'en')
}
```

### PaymentResult

```typescript
interface PaymentResult {
  status: 'approved' | 'rejected' | 'pending' | 'in_process';
  paymentId: string;
  statusDetail: string;
  paymentData?: PaymentData;
  error?: {
    message: string;
    code: string;
  };
}
```

### Métodos disponibles

- `initialize()`: Inicializa el SDK
- `startPayment(preferenceId?)`: Inicia el flujo de pago
- `addPaymentResultListener(callback)`: Agrega listener para eventos de pago
- `removePaymentResultListener(subscription)`: Remueve listener
- `isMercadoPagoInstalled()`: Verifica si la app está instalada
- `getSDKVersion()`: Obtiene la versión del SDK

## 🛠️ Desarrollo

### Prerrequisitos

- Node.js 16+
- Expo CLI
- Xcode (para iOS)
- Android Studio (para Android)

### Instalación de dependencias

```bash
npm install
```

### Build

```bash
npm run build
```

### Limpiar

```bash
npm run clean
```

### Nota sobre dependencias

Esta librería utiliza `expo-modules-core` como dependencia principal. Si encuentras errores de instalación, asegúrate de tener una versión compatible de Expo en tu proyecto.

## 📱 Ejemplo completo

Ver el archivo `example/App.tsx` para un ejemplo completo de implementación.

## 🔒 Permisos

La librería automáticamente configura los siguientes permisos:

**Android:**
- `android.permission.INTERNET`
- `android.permission.ACCESS_NETWORK_STATE`

**iOS:**
- URL schemes para Mercado Pago

## 🐛 Troubleshooting

### Error: "Module not found"
Asegúrate de que el plugin esté configurado correctamente en `app.json`.

### Error: "Public key required"
Verifica que estés usando una public key válida de Mercado Pago.

### Error: "Preference ID required"
Asegúrate de proporcionar un preference ID válido antes de iniciar el pago.

## 📄 Licencia

MIT

## 🤝 Contribuir

1. Fork el proyecto
2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. Push a la rama (`git push origin feature/AmazingFeature`)
5. Abre un Pull Request

## 📞 Soporte

Si tienes problemas o preguntas, abre un issue en GitHub.

## 🔗 Enlaces útiles

- [Documentación oficial de Mercado Pago](https://www.mercadopago.com.ar/developers/es/docs/sdks-library/client-side/sdk-nativo)
- [Panel de desarrolladores](https://www.mercadopago.com.ar/developers/panel)
- [Expo Modules](https://docs.expo.dev/modules/module-api/)