omnipay-savings-sdk

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

Installation

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:

# 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):

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
• react-native-safe-area-context
• @react-native-community/datetimepicker

Quick Start

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:

{
  "customerId": "customer-id",
  "customerState": "Lagos",
  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "[email protected]"
}

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/ directory to see the SDK in action:

# 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.

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

Development

Building the SDK

npm run build

Running Tests

npm test

Running Example App

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