omnipay-savings-sdk/README.md

Omnipay Savings SDK

# omnipay-savings-sdk

A React Native SDK for savings functionality that works with both Expo and bare React Native applications.

## Installation

```bash
npm install omnipay-savings-sdk
```

### Dependencies

This SDK bundles most dependencies internally, but **native dependencies require installation in your app** for proper linking.

**Required native dependencies:**

```bash
# For Expo projects
npx expo install react-native-gesture-handler react-native-safe-area-context @react-native-community/datetimepicker react-native-modal-datetime-picker

# For bare React Native projects
npm install react-native-gesture-handler react-native-safe-area-context @react-native-community/datetimepicker react-native-modal-datetime-picker
```

**Optional (for better integration):**

```bash
npm install @react-navigation/native @react-navigation/native-stack react-native-screens
```

#### For Expo Projects

The SDK is fully compatible with Expo managed workflow. Install the native dependencies above, then:

#### For Bare React Native Projects

Additional setup may be required for native dependencies. Follow the installation guides:

- [react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/installation)
- [react-native-safe-area-context](https://github.com/th3rdwave/react-native-safe-area-context#getting-started)
- [@react-native-community/datetimepicker](https://github.com/react-native-datetimepicker/datetimepicker#getting-started)

## Quick Start

```tsx
import React, {useState} from 'react';
import {View, TouchableOpacity, Text} from 'react-native';
import {OmniPaySavingsSDK} from 'omnipay-savings-sdk';
import type {SDKConfig} from 'omnipay-savings-sdk';

const MyApp = () => {
  const [showSDK, setShowSDK] = useState(false);

  const config: SDKConfig = {
    apiKey: 'your-api-key-here',
    primaryColor: 'rgba(166, 130, 255, 1)', // Optional
    onClose: () => {
      console.log('User wants to close the SDK');
      setShowSDK(false);
    },
    onTokenExpired: () => {
      console.log('Token expired, redirect to login');
      setShowSDK(false);
    },
    env: 'your-env-prod-or-dev',
  };

  if (showSDK) {
    return <OmniPaySavingsSDK config={config} />;
  }

  return (
    <View style={{flex: 1, justifyContent: 'center', alignItems: 'center'}}>
      <TouchableOpacity onPress={() => setShowSDK(true)}>
        <Text>Launch Savings SDK</Text>
      </TouchableOpacity>
    </View>
  );
};

export default MyApp;
```

## Configuration

The SDK accepts a `config` object with the following properties:

| Property         | Type       | Required | Description                                                      |
| ---------------- | ---------- | -------- | ---------------------------------------------------------------- |
| `apiKey`         | `string`   | Yes      | Your API key for authentication (JWT token)                      |
| `primaryColor`   | `string`   | No       | Primary color for the SDK UI (default: 'rgba(166, 130, 255, 1)') |
| `onClose`        | `function` | No       | Callback function when user wants to close the SDK               |
| `onTokenExpired` | `function` | No       | Callback function when the API token expires                     |
| `env`            | `string`   | Yes      | Your preferred environment with types 'prod' or 'dev'            |

### API Key Format

The API key should be a valid JWT token containing customer information. Example structure:

```json
{
  "customerId": "customer-id",
  "customerState": "Lagos",
  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "user@example.com"
}
```

## Features

- ✅ **Flexible Savings Plans**: Create custom savings plans with flexible amounts and frequencies
- ✅ **Locked Savings Accounts**: Set up locked savings with specific maturity dates and higher interest rates
- ✅ **Save As You Collect**: Automated savings that grow with your business collections
- ✅ **Multiple Categories**: Different savings types (Emergency, Investment, Business, etc.)
- ✅ **Transaction History**: Comprehensive transaction tracking and filtering
- ✅ **Interest Tracking**: Real-time interest calculations and earnings breakdown
- ✅ **Withdrawals**: Withdraw from eligible savings accounts with proper validation
- ✅ **Progress Tracking**: Visual progress indicators for savings goals
- ✅ **Responsive Design**: Works on phones and tablets

## Example App

Check out the complete example app in the [`example/`](./example/) directory to see the SDK in action:

```bash
# Clone the repository
git clone [repository-url]
cd omnipay-savings-sdk/example

# Install dependencies
npm install

# Run the example
npm start
```

The example demonstrates:

- Complete SDK integration
- State management patterns
- Callback handling
- Professional UI integration

## Platform Compatibility

| Platform     | Support |
| ------------ | ------- |
| iOS          | ✅      |
| Android      | ✅      |
| Web (Expo)   | ✅      |
| React Native | ✅      |
| Expo Managed | ✅      |
| Expo Bare    | ✅      |

## Requirements

- React Native >= 0.60.0
- React >= 16.8.0
- Node.js >= 18
- For iOS: iOS 11.0+
- For Android: API level 21+

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions. No additional type packages needed.

```tsx
import type {SDKConfig, SavingsAccountType} from 'omnipay-savings-sdk';
```

## Development

### Building the SDK

```bash
npm run build
```

### Running Tests

```bash
npm test
```

### Running Example App

```bash
npm run example:start
```

## Troubleshooting

### Common Issues

1. **Metro bundler issues**: Clear cache with `npx react-native start --reset-cache`
2. **iOS builds failing**: Ensure you have the latest Xcode and run `cd ios && pod install`
3. **Android builds failing**: Check that Android SDK is properly configured
4. **Token expired errors**: Ensure your API key is valid and not expired

### Debugging

The SDK includes comprehensive error logging. Check your console for detailed error messages.

## Contributing

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

## Changelog

### v0.0.4

- Added console log removal for production builds
- Updated dependencies
- Improved TypeScript definitions

### v0.0.3

- Initial public release
- Core savings functionality
- Example app