npm package: @sunnypay/react-native
Description: Official React Native SDK for Sunny Payments - Accept Mobile payments, cards, crypto, BNPL and more
Author: Sunny Payments
Latest version: 1.0.0

<p align="center">
  <img src="assets/sunny-logo.svg" alt="Sunny Payments" width="60" height="60">
  <img src="assets/react-native.svg" alt="React Native" width="60" height="60">
</p>

<h1 align="center">Sunny Payments React Native SDK</h1>

<p align="center">
  The official React Native SDK for <a href="https://sunnypay.co.ke">Sunny Payments</a> - Accept M-Pesa, cards, crypto, BNPL and more in your React Native apps.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@sunnypayments/react-native"><img src="https://img.shields.io/npm/v/@sunnypayments/react-native.svg" alt="npm version"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

## Installation

```bash
npm install @sunnypayments/react-native
# or
yarn add @sunnypayments/react-native
```

## Requirements

- React Native 0.64.0 or higher
- React 17.0.0 or higher

## Quick Start

### Option 1: Direct Usage

```typescript
import { SunnyClient } from '@sunnypayments/react-native';

const sunny = new SunnyClient('sk_live_your_api_key');

// M-Pesa STK Push
const result = await sunny.mobileMoney.mpesaSTKPush({
  phoneNumber: '254712345678',
  amount: 1000,
  accountReference: 'ORDER-001',
});

console.log(result.checkout_request_id);
```

### Option 2: Using React Hooks (Recommended)

```tsx
import { SunnyProvider, useSunny } from '@sunnypayments/react-native';

// App.tsx - Wrap your app
function App() {
  return (
    <SunnyProvider apiKey="sk_live_xxx">
      <PaymentScreen />
    </SunnyProvider>
  );
}

// PaymentScreen.tsx - Use the hook
function PaymentScreen() {
  const sunny = useSunny();
  
  const handlePayment = async () => {
    const result = await sunny.mobileMoney.mpesaSTKPush({
      phoneNumber: '254712345678',
      amount: 1000,
      accountReference: 'ORDER-001',
    });
    console.log(result);
  };
  
  return <Button title="Pay with M-Pesa" onPress={handlePayment} />;
}
```

## Features

All 12 Sunny Payments resources are supported:

| Resource | Description |
|----------|-------------|
| `payments` | Create, capture, refund payments |
| `customers` | Manage customer profiles |
| `refunds` | Process refunds |
| `webhooks` | Register endpoints |
| `bills` | Airtime, data, electricity payments |
| `crypto` | BTC, ETH, USDT, USDC payments |
| `mobileMoney` | M-Pesa, MTN MoMo, Airtel Money |
| `invoices` | Create and manage invoices |
| `qrCodes` | Static and dynamic QR payments |
| `virtualAccounts` | Virtual bank account numbers |
| `bnpl` | Buy Now Pay Later |
| `ussd` | USSD application management |

## Usage Examples

### Purchase Airtime

```typescript
const tx = await sunny.bills.purchaseAirtime({
  phoneNumber: '+254712345678',
  amount: 100,
  network: 'safaricom',
});
```

### Accept Crypto Payments

```typescript
// Get rates
const rates = await sunny.crypto.getRates();
console.log(`BTC: $${rates.BTC}`);

// Create payment address
const address = await sunny.crypto.createAddress('BTC', 10000);
console.log(`Send ${address.amount_crypto} BTC to: ${address.address}`);
```

### BNPL (Buy Now Pay Later)

```typescript
// Check eligibility
const eligibility = await sunny.bnpl.checkEligibility('cus_123', 50000);

if (eligibility.eligible) {
  const plan = await sunny.bnpl.create({
    customer: 'cus_123',
    amount: 30000,
    installments: 3,
  });
  console.log(`Monthly payment: ${plan.installment_amount}`);
}
```

### Create Invoice

```typescript
const invoice = await sunny.invoices.create({
  customer: 'cus_123',
  items: [
    { description: 'Widget', quantity: 2, unit_price: 500, amount: 1000 },
  ],
});
await sunny.invoices.send(invoice.id);
```

## Error Handling

```typescript
import { 
  AuthenticationError, 
  ValidationError, 
  RateLimitError,
  ApiError,
  NetworkError 
} from '@sunnypayments/react-native';

try {
  const result = await sunny.payments.create(params);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.log(`Validation error: ${error.message}`);
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ApiError) {
    console.log(`API error [${error.statusCode}]: ${error.message}`);
  } else if (error instanceof NetworkError) {
    console.log('Network error - check connection');
  }
}
```

## TypeScript Support

Full TypeScript support is included. All types are exported:

```typescript
import type { 
  Payment, 
  Customer,
  STKPushParams,
  STKPushResult,
  // ... all types
} from '@sunnypayments/react-native';
```

## Configuration

```typescript
const sunny = new SunnyClient('sk_live_xxx', {
  baseUrl: 'https://api.sunnypay.co.ke/v1',
  timeout: 30000,
  maxRetries: 3,
});
```

## React Native Compatibility

| Platform | Status |
|----------|--------|
| iOS | ✅ Fully supported |
| Android | ✅ Fully supported |
| Expo | ✅ Fully supported |
| Web (react-native-web) | ✅ Fully supported |

## Resources

- [npm Package](https://www.npmjs.com/package/@sunnypayments/react-native)
- [GitHub Repository](https://github.com/SUNNYPAY-LIMITED/sunny-react-native)
- [API Documentation](https://docs.sunnypay.co.ke)
- [Support](mailto:support@sunnypay.co.ke)

## License

MIT License - see [LICENSE](LICENSE) for details.