neotek-openbanking/README.md

neotek-openbanking

# React NeoTek Open Banking

A comprehensive React Native library for integrating Open Banking functionality into mobile applications. This library provides a complete solution for connecting bank accounts, managing financial institutions, and handling Open Banking workflows.

## Features

- 🔐 **Secure Authentication** - OAuth 2.0 integration with secure token management

- 📱 **Cross-Platform** - Works on both iOS and Android
- 🌍 **Internationalization** - Built-in support for English and Arabic
- 🎨 **Customizable UI** - Fully customizable themes and styling
- 📊 **Account Management** - View and manage connected accounts
- 🔄 **Real-time Updates** - Live account status and transaction updates

## Installation

```bash
npm install neotek-openbanking
```

### Peer Dependencies

This library requires the following peer dependencies:

```bash
npm install react-native-webview
```

## Quick Start

### Basic Usage

```tsx
import React, { useState } from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { NeoTek } from 'neotek-openbanking';

const App = () => {

  const theme = {
    themeMain: {
      primaryColor: '#0CBAB7',
      primaryButtonTextColor: '#ffffff',
      secondaryColor: '#D8ECEB',
      secondaryButtonTextColor: '#0CBAB4',
      textPrimaryColor: '#000000',
      textSecondaryColor: '#72788E',
      white: '#fff',
      gray: '#F7F8FA',
    },
    fontMain: {
      regular: 'sfprodisplayregular',
      bold: 'sfprodisplaybold',
      medium: 'sfprodisplaymedium',
      semiBold: 'sfprodisplaysemibold',
    },
    credentials: {
      baseUrl: 'https://your-api-domain.com',
      appName: 'Your App Name',
      token: 'your-access-token',
      scope: 'ob_connect iban_verification income_verification single_api e_statements',
      uuidKey: 'your-uuid-key',
      apiKey: 'your-api-key',
      logo: 'your-app-logo-url',
      userLoginId: 'your user login id',
      psuid: 'your user id'
    },
  };

  return (
    <NavigationContainer>
      <NeoTek
          data={NeotekTheme as any}
          screen={screen}
          callback={(status: string) => {
            if(status === 'success') {
              
            }else if(status === 'fail') {
              
            }else {
              
            }
          }}
        />
    </NavigationContainer>
  );
};

export default App;
```

## API Reference

### NeoTek Component

The main component that renders the Open Banking interface.

#### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `theme` | `NeotekTheme` | Yes | Theme configuration object |
| `screen` | `string` | Yes | Initial screen to display (Home or ConnectedAccounts) |
| `success`, `fail`, `close` | `Function` | Yes | Callback function when flow completes |

#### Theme Configuration

```tsx
interface NeotekTheme {
  themeMain: {
    primaryColor: string;           // Primary brand color
    primaryButtonTextColor: string; // Primary button text color
    secondaryColor: string;         // Secondary brand color
    secondaryButtonTextColor: string; // Secondary button text color
    textPrimaryColor: string;       // Primary text color
    textSecondaryColor: string;     // Secondary text color
    white: string;                  // White color
    gray: string;                   // Gray color
  };
  fontMain: {
    regular: string;                // Regular font family
    bold: string;                   // Bold font family
    medium: string;                 // Medium font family
    semiBold: string;               // Semi-bold font family
  };
  credentials: {
    baseUrl: string;                // API base URL
    appName: string;                // Application name
    token: string;                  // Access token
    scope: string;                  // OAuth scope
    uuidKey: string;                // UUID key for requests
    apiKey: string;                 // API key
    logo: string;                   // App logo URL
    userLoginId: string;            // User Login Id
    psuid: string;                  // 'User Id
  };
}
```

### Available Screens

| Screen | Description |
|--------|-------------|
| `Home` | Initial screen for selecting financial institutions |
| `ConnectedAccounts` | View and manage connected accounts |
| `Details` | Account details and connection flow |
| `Redirection` | OAuth redirection handling |
| `Success` | Success screen after successful connection |
| `Fail` | Error screen for failed operations |
| `ManageAccount` | Account management interface |
| `DisconnectedSuccess` | Success screen after disconnection |

## Authentication Flow

### 1. Token Generation

First, you need to obtain an access token from your Open Banking provider:

```tsx
const getAccessToken = async () => {
  const client_id = 'your-client-id';
  const client_secret = 'your-client-secret';
  const apiKey = 'your-api-key';
  const uuidKey = 'your-uuid-key';
  const scope: 'ob_connect iban_verification income_verification single_api e_statements'

  const body = {
    grant_type: 'client_credentials',
    client_id: client_id,
    client_secret: client_secret,
    scope: scope,
  };
  
  const response = await fetch('https://your-domain.com/auth/token', {
    method: 'POST',
    body: new URLSearchParams(body).toString(),
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded',
      'scope': 'ob_connect iban_verification income_verification single_api e_statements',
      'uuidKey': uuidKey,
      'apiKey': apiKey,
    },
  });
  
  const json = await response.json();
  return json.token_type + ' ' + json.access_token;
};
```

### 2. Integration

```tsx
import React, { useState, useEffect } from 'react';
import { NeoTek } from 'neotek-openbanking';

const OpenBankingComponent = () => {
  const [token, setToken] = useState('');

  useEffect(() => {
    // Get token when component mounts
    getAccessToken().then(setToken);
  }, []);

  const theme = {
    themeMain: {
      primaryColor: '#0CBAB7',
      primaryButtonTextColor: '#ffffff',
      secondaryColor: '#D8ECEB',
      secondaryButtonTextColor: '#0CBAB4',
      textPrimaryColor: '#000000',
      textSecondaryColor: '#72788E',
      white: '#fff',
      gray: '#F7F8FA',
    },
    fontMain: {
      regular: 'sfprodisplayregular',
      bold: 'sfprodisplaybold',
      medium: 'sfprodisplaymedium',
      semiBold: 'sfprodisplaysemibold',
    },
    credentials: {
      baseUrl: 'https://your-api-domain.com',
      appName: 'Your App Name',
      token: token,
      scope: 'ob_connect iban_verification income_verification single_api e_statements',
      uuidKey: 'your-uuid-key',
      apiKey: 'your-api-key',
      logo: 'your-app-logo-url',
      userLoginId: 'your user login id',
      psuid: 'your user id'
    },
  };

  return (
    <>
      {token && (
        <NeoTek
          data={NeotekTheme as any}
          screen={screen}
          callback={(status: string) => {
            if(status === 'success') {
              
            }else if(status === 'fail') {
              
            }else {
              
            }
          }}
        />
      )}
    </>
  );
};
```

## Internationalization

The library supports multiple languages. Currently supported:

- English (en)
- Arabic (ar)

Language is automatically detected based on your app settings.

## Customization

### Custom Themes

You can create custom themes by extending the default theme:

```tsx
const customTheme = {
  themeMain: {
    primaryColor: '#FF6B6B',
    primaryButtonTextColor: '#FFFFFF',
    secondaryColor: '#4ECDC4',
    secondaryButtonTextColor: '#FFFFFF',
    textPrimaryColor: '#2C3E50',
    textSecondaryColor: '#7F8C8D',
    white: '#FFFFFF',
    gray: '#F8F9FA',
  },
  fontMain: {
    regular: 'YourRegularFont',
    bold: 'YourBoldFont',
    medium: 'YourMediumFont',
    semiBold: 'YourSemiBoldFont',
  },
  credentials: {
    // Your credentials here
  },
};
```

### Custom Fonts

To use custom fonts, ensure they are properly linked in your React Native project:
if expo project
  1. install expo-font 
  2. Add font files to your project
  3. Link them using `react-native link` or manually
  4. in app.tsx add
  useFonts({
      'sfprodisplayregular': require('../assets/fonts/regular-font'),
      'sfprodisplaybold': require('../assets/fonts/bold-font'),
      'sfprodisplaymedium': require('../assets/fonts/medium-font'),
      'sfprodisplaysemibold': require('../assets/fonts/semibold-font'),
    });
  5. Reference them in the theme configuration
if cli project
  1. Create a folder in your project to store fonts, ./assets/fonts
  2. assets/fonts/CustomFont-Regular.ttf
     assets/fonts/CustomFont-Bold.ttf
     assets/fonts/CustomFont-semiBold.ttf
     assets/fonts/CustomFont-medium.ttf
  3. create file if not exist react-native.config.js
  4. module.exports = {
        assets: ['./assets/fonts/'], // Path to your font files
      };
  5. npx react-native-asset


## Security Considerations

- Always use HTTPS for API communications
- Follow OAuth 2.0 best practices
- Validate all user inputs

## Troubleshooting

### Common Issues

1. **Navigation Errors**: Ensure all peer dependencies are installed
2. **Font Loading Issues**: Verify fonts are properly linked
3. **API Connection Errors**: Check network connectivity and API credentials
4. **Token Expiration**: insure use valid token

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

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

## Support

For support and questions:

- Create an issue on GitHub
- Check the documentation
- Review the example app

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.