@propel-nsl/propel-react-native-sdk 1.0.0 → 1.0.1

package/CLIENT_INTEGRATION_GUIDE.md

@@ -0,0 +1,499 @@
+# Propel SDK Integration Guide for Clients
+
+## Overview
+
+The Propel SDK is a comprehensive React Native library that enables seamless integration of reward and redemption functionality into your mobile application. This guide provides step-by-step instructions for integrating the SDK into your React Native project.
+
+## Prerequisites
+
+- React Native version 0.72.0 or higher
+- React version 18.0.0 or higher
+- Node.js version 18 or higher
+- iOS deployment target: iOS 12.0 or higher
+- Android API Level: 21 or higher
+
+## Quick Start
+
+### 1. Installation
+
+Install the Propel SDK package from npm:
+
+```bash
+npm install @propel-nsl/propel-react-native-sdk
+# or
+yarn add @propel-nsl/propel-react-native-sdk
+```
+
+### 2. Required Dependencies
+
+Install all required peer dependencies:
+
+```bash
+npm install @react-native-async-storage/async-storage \
+@react-native-community/netinfo \
+@react-navigation/native \
+@react-navigation/stack \
+@react-navigation/bottom-tabs \
+@reduxjs/toolkit \
+react-redux \
+redux-saga \
+react-native-gesture-handler \
+react-native-reanimated \
+react-native-safe-area-context \
+react-native-screens \
+react-native-device-info \
+react-native-svg \
+react-native-toast-message
+```
+
+### 3. Optional Dependencies
+
+For enhanced functionality, install these optional dependencies:
+
+```bash
+npm install @react-native-clipboard/clipboard \
+@react-native-community/masked-view \
+react-native-fast-image \
+react-native-image-picker \
+react-native-permissions \
+react-native-size-matters \
+react-native-render-html \
+react-native-otp-entry \
+react-native-keyboard-aware-scroll-view \
+react-native-country-picker-modal \
+formik \
+yup \
+buffer
+```
+
+### 4. Metro Configuration
+
+Update your `metro.config.js` file to properly resolve the SDK modules:
+
+```javascript
+const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
+const path = require('path');
+const exclusionList = require('metro-config/src/defaults/exclusionList');
+
+// SDK installation path
+const sdkRoot = path.resolve(
+  __dirname, 'node_modules/@propel-nsl/propel-react-native-sdk'
+);
+
+// Axios ESM browser build path
+const axiosEsm = path.resolve(__dirname, 'node_modules/axios/dist/esm/axios.js');
+
+const config = {
+  projectRoot: __dirname,
+  watchFolders: [sdkRoot],
+  resolver: {
+    blockList: exclusionList([
+      /.*\/axios\/dist\/node\/.*/,
+    ]),
+    resolveRequest: (context, moduleName, platform) => {
+      if (moduleName === 'axios' || moduleName === 'axios/lib/axios') {
+        return {
+          filePath: axiosEsm,
+          type: 'sourceFile',
+        };
+      }
+      return context.resolveRequest(context, moduleName, platform);
+    },
+    extraNodeModules: {
+      'src-app': path.resolve(sdkRoot, 'src-app'),
+      react: path.resolve(__dirname, 'node_modules/react'),
+      'react-native': path.resolve(__dirname, 'node_modules/react-native'),
+      'react-redux': path.resolve(__dirname, 'node_modules/react-redux'),
+      '@reduxjs/toolkit': path.resolve(__dirname, 'node_modules/@reduxjs/toolkit'),
+      '@react-navigation/native': path.resolve(__dirname, 'node_modules/@react-navigation/native'),
+      '@react-navigation/stack': path.resolve(__dirname, 'node_modules/@react-navigation/stack'),
+      '@react-navigation/bottom-tabs': path.resolve(__dirname, 'node_modules/@react-navigation/bottom-tabs'),
+      'react-native-gesture-handler': path.resolve(__dirname, 'node_modules/react-native-gesture-handler'),
+      'react-native-reanimated': path.resolve(__dirname, 'node_modules/react-native-reanimated'),
+      'react-native-screens': path.resolve(__dirname, 'node_modules/react-native-screens'),
+      'react-native-safe-area-context': path.resolve(__dirname, 'node_modules/react-native-safe-area-context'),
+      'react-native-svg': path.resolve(__dirname, 'node_modules/react-native-svg'),
+      'react-native-fast-image': path.resolve(__dirname, 'node_modules/react-native-fast-image'),
+      '@react-native-async-storage/async-storage': path.resolve(__dirname, 'node_modules/@react-native-async-storage/async-storage'),
+      '@react-native-community/netinfo': path.resolve(__dirname, 'node_modules/@react-native-community/netinfo'),
+      '@react-native-clipboard/clipboard': path.resolve(__dirname, 'node_modules/@react-native-clipboard/clipboard'),
+      '@react-native-community/masked-view': path.resolve(__dirname, 'node_modules/@react-native-community/masked-view'),
+      'react-native-toast-message': path.resolve(__dirname, 'node_modules/react-native-toast-message'),
+      'react-native-device-info': path.resolve(__dirname, 'node_modules/react-native-device-info'),
+      'react-native-image-picker': path.resolve(__dirname, 'node_modules/react-native-image-picker'),
+      'react-native-permissions': path.resolve(__dirname, 'node_modules/react-native-permissions'),
+      'redux-saga': path.resolve(__dirname, 'node_modules/redux-saga'),
+      axios: axiosEsm,
+      buffer: path.resolve(__dirname, 'node_modules/buffer'),
+      formik: path.resolve(__dirname, 'node_modules/formik'),
+      yup: path.resolve(__dirname, 'node_modules/yup'),
+      'react-native-size-matters': path.resolve(__dirname, 'node_modules/react-native-size-matters'),
+      'react-native-render-html': path.resolve(__dirname, 'node_modules/react-native-render-html'),
+      'react-native-otp-entry': path.resolve(__dirname, 'node_modules/react-native-otp-entry'),
+      'react-native-keyboard-aware-scroll-view': path.resolve(__dirname, 'node_modules/react-native-keyboard-aware-scroll-view'),
+      'react-native-country-picker-modal': path.resolve(__dirname, 'node_modules/react-native-country-picker-modal'),
+    },
+    nodeModulesPaths: [
+      path.resolve(__dirname, 'node_modules'),
+    ],
+  },
+};
+
+module.exports = mergeConfig(getDefaultConfig(__dirname), config);
+```
+
+### 5. iOS Setup
+
+After installing dependencies, run:
+
+```bash
+cd ios && pod install && cd ..
+```
+
+## Integration Steps
+
+### Step 1: Configure Navigation
+
+Set up your app navigation to include the Propel SDK screen:
+
+```tsx
+import React from 'react';
+import { NavigationContainer } from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { PropelSDKScreen } from '@propel-nsl/propel-react-native-sdk';
+
+export type RootStackParamList = {
+  Home: undefined;
+  PropelSDK: {
+    screen: string;
+    authToken: string;
+    authId: string;
+    apiUrl?: string;
+    userId?: string;
+    userName?: string;
+    userMobile?: string;
+    userEmail?: string;
+    deviceId?: string;
+    clientName?: string;
+    clientVersion?: string;
+    environment?: 'development' | 'staging' | 'production';
+  };
+};
+
+const Stack = createStackNavigator<RootStackParamList>();
+
+function App() {
+  return (
+    <SafeAreaProvider>
+      <NavigationContainer>
+        <Stack.Navigator
+          screenOptions={{ headerShown: false, gestureEnabled: false }}
+        >
+          <Stack.Screen name="Home" component={HomeScreen} />
+          <Stack.Screen
+            name="PropelSDK"
+            component={PropelSDKScreen}
+            options={{
+              gestureEnabled: false,
+              animationEnabled: true,
+            }}
+          />
+        </Stack.Navigator>
+      </NavigationContainer>
+    </SafeAreaProvider>
+  );
+}
+```
+
+### Step 2: Create Navigation Function
+
+Create a function to navigate to the SDK with proper parameters:
+
+```tsx
+import { StackNavigationProp } from '@react-navigation/stack';
+import type { RootStackParamList } from './App';
+
+type NavigationProp = StackNavigationProp<RootStackParamList, 'Home'>;
+
+interface SDKNavigationParams {
+  screen: 'dashboard' | 'redeem' | 'redemption-history';
+  authToken: string;
+  authId: string;
+  apiUrl?: string;
+  environment?: 'development' | 'staging' | 'production';
+  userId?: string;
+  userName?: string;
+  userMobile?: string;
+  userEmail?: string;
+}
+
+const openPropelSDK = (
+  navigation: NavigationProp,
+  params: SDKNavigationParams
+) => {
+  navigation.navigate('PropelSDK', {
+    screen: params.screen,
+    authToken: params.authToken,
+    authId: params.authId,
+    apiUrl: params.apiUrl || 'https://api.propel.com',
+    environment: params.environment || 'production',
+    userId: params.userId,
+    userName: params.userName,
+    userMobile: params.userMobile,
+    userEmail: params.userEmail,
+  });
+};
+```
+
+### Step 3: Implement SDK Launch
+
+Add buttons or triggers to launch the SDK:
+
+```tsx
+import React from 'react';
+import { TouchableOpacity, Text, StyleSheet, View } from 'react-native';
+
+const LaunchButtons: React.FC<{ navigation: NavigationProp }> = ({ navigation }) => {
+  const handleOpenDashboard = () => {
+    openPropelSDK(navigation, {
+      screen: 'dashboard',
+      authToken: 'YOUR_AUTH_TOKEN',
+      authId: 'YOUR_AUTH_ID',
+      environment: 'production',
+    });
+  };
+
+  const handleOpenRedeem = () => {
+    openPropelSDK(navigation, {
+      screen: 'redeem',
+      authToken: 'YOUR_AUTH_TOKEN',
+      authId: 'YOUR_AUTH_ID',
+      environment: 'production',
+    });
+  };
+
+  const handleOpenHistory = () => {
+    openPropelSDK(navigation, {
+      screen: 'redemption-history',
+      authToken: 'YOUR_AUTH_TOKEN',
+      authId: 'YOUR_AUTH_ID',
+      environment: 'production',
+    });
+  };
+
+  return (
+    <View style={styles.container}>
+      <TouchableOpacity style={styles.button} onPress={handleOpenDashboard}>
+        <Text style={styles.buttonText}>Open Dashboard</Text>
+      </TouchableOpacity>
+      
+      <TouchableOpacity style={styles.button} onPress={handleOpenRedeem}>
+        <Text style={styles.buttonText}>Redeem Rewards</Text>
+      </TouchableOpacity>
+      
+      <TouchableOpacity style={styles.button} onPress={handleOpenHistory}>
+        <Text style={styles.buttonText}>View History</Text>
+      </TouchableOpacity>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 20,
+    gap: 10,
+  },
+  button: {
+    backgroundColor: '#007AFF',
+    padding: 15,
+    borderRadius: 8,
+    alignItems: 'center',
+  },
+  buttonText: {
+    color: 'white',
+    fontSize: 16,
+    fontWeight: '600',
+  },
+});
+```
+
+## Configuration Parameters
+
+### Required Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `screen` | string | Target screen: `dashboard`, `redeem`, or `redemption-history` |
+| `authToken` | string | Authentication token provided by Propel |
+| `authId` | string | Authentication ID provided by Propel |
+
+### Optional Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `apiUrl` | string | Custom API endpoint URL |
+| `environment` | string | Environment: `development`, `staging`, or `production` |
+| `userId` | string | Your application's user identifier |
+| `userName` | string | User's display name |
+| `userMobile` | string | User's mobile number |
+| `userEmail` | string | User's email address |
+| `deviceId` | string | Device identifier |
+| `clientName` | string | Your application name |
+| `clientVersion` | string | Your application version |
+
+## Available Screens
+
+### Dashboard
+- **Purpose**: Main landing screen showing user rewards overview
+- **Screen Value**: `dashboard`
+
+### Redeem
+- **Purpose**: Screen for redeeming available rewards
+- **Screen Value**: `redeem`
+
+### Redemption History
+- **Purpose**: Screen showing transaction and redemption history
+- **Screen Value**: `redemption-history`
+
+## Authentication
+
+The Propel SDK handles authentication internally using the provided `authToken` and `authId`. These credentials will be provided to you by Propel during the onboarding process.
+
+### Authentication Flow
+1. SDK receives authentication credentials
+2. Validates credentials with Propel API
+3. Establishes secure session
+4. Provides access to requested functionality
+
+## Environment Configuration
+
+### Production
+```tsx
+openPropelSDK(navigation, {
+  screen: 'dashboard',
+  authToken: 'PRODUCTION_AUTH_TOKEN',
+  authId: 'PRODUCTION_AUTH_ID',
+  environment: 'production',
+  apiUrl: 'https://api.propel.com'
+});
+```
+
+### Staging
+```tsx
+openPropelSDK(navigation, {
+  screen: 'dashboard',
+  authToken: 'STAGING_AUTH_TOKEN',
+  authId: 'STAGING_AUTH_ID',
+  environment: 'staging',
+  apiUrl: 'https://staging-api.propel.com'
+});
+```
+
+### Development
+```tsx
+openPropelSDK(navigation, {
+  screen: 'dashboard',
+  authToken: 'DEV_AUTH_TOKEN',
+  authId: 'DEV_AUTH_ID',
+  environment: 'development',
+  apiUrl: 'https://dev-api.propel.com'
+});
+```
+
+## Best Practices
+
+### 1. Secure Credential Management
+- Store authentication credentials securely
+- Use environment variables for different environments
+- Never hard-code credentials in your application
+
+### 2. Error Handling
+```tsx
+const handleOpenSDK = async (screen: string) => {
+  try {
+    if (!authToken || !authId) {
+      Alert.alert('Error', 'Missing authentication credentials');
+      return;
+    }
+    
+    openPropelSDK(navigation, {
+      screen: screen as any,
+      authToken,
+      authId,
+      environment: 'production',
+    });
+  } catch (error) {
+    console.error('Failed to open Propel SDK:', error);
+    Alert.alert('Error', 'Unable to open rewards portal');
+  }
+};
+```
+
+### 3. User Experience
+- Provide clear loading states during SDK initialization
+- Handle network connectivity issues gracefully
+- Offer retry mechanisms for failed operations
+
+### 4. Performance Optimization
+- Pre-load SDK data when possible
+- Cache user information to reduce API calls
+- Optimize images and assets for mobile devices
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Metro Bundler Errors**
+   - Ensure metro.config.js is properly configured
+   - Clear Metro cache: `npx react-native start --reset-cache`
+
+2. **iOS Build Issues**
+   - Run `pod install` in iOS directory
+   - Clean build folder in Xcode
+
+3. **Navigation Not Working**
+   - Verify screen names match exactly
+   - Check TypeScript types for parameter validation
+
+4. **Authentication Failures**
+   - Validate authToken and authId are correct
+   - Check network connectivity to API endpoint
+
+### Debug Mode
+
+Enable debug logging for development:
+
+```tsx
+openPropelSDK(navigation, {
+  screen: 'dashboard',
+  authToken,
+  authId,
+  environment: 'development', // Enables debug logging
+});
+```
+
+## Support
+
+For technical support and integration assistance:
+
+1. **Documentation**: Refer to this guide and inline code comments
+2. **Debug Logs**: Enable debug mode and check console logs
+3. **Contact**: Reach out to your Propel technical contact
+
+## Version Information
+
+- **Current SDK Version**: 1.0.0
+- **React Native Compatibility**: >= 0.72.0
+- **React Compatibility**: >= 18.0.0
+- **iOS Compatibility**: >= 12.0
+- **Android Compatibility**: API Level >= 21
+
+## License
+
+The Propel SDK is proprietary software. Usage is subject to Propel's terms of service and license agreement. Please ensure you have the appropriate licenses before integrating the SDK into your application.
+
+---
+
+**Last Updated**: February 2026
+**Version**: 1.0.0

package/README.md

@@ -0,0 +1,36 @@
+# Propel React Native SDK
+
+A comprehensive React Native library for integrating Propel's reward and redemption functionality into your mobile application.
+
+## Quick Start
+
+```bash
+npm install @propel-nsl/propel-react-native-sdk
+```
+
+## Documentation
+
+For complete integration instructions, please see our [Client Integration Guide](./CLIENT_INTEGRATION_GUIDE.md).
+
+## Features
+
+- 🚀 Easy integration with React Native navigation
+- 🔐 Secure authentication handling
+- 📱 Cross-platform support (iOS & Android)
+- 🎨 Customizable UI components
+- 📊 Comprehensive reward management
+- 📱 Transaction history tracking
+
+## Requirements
+
+- React Native >= 0.72.0
+- React >= 18.0.0
+- Node.js >= 18
+
+## License
+
+Proprietary software. See license agreement for usage terms.
+
+## Support
+
+For technical support, please refer to the [Client Integration Guide](./CLIENT_INTEGRATION_GUIDE.md) or contact your Propel technical representative.

package/RN_HOST_INTEGRATION.md

@@ -0,0 +1,152 @@
+# Propel SDK — React Native Host App Integration Guide
+
+## Overview
+
+When the host app is also a React Native app, the SDK is consumed as an **npm package** (`@propel-nsl/propel-react-native-sdk`). The host app imports `PropelSDKScreen` and adds it to its navigation tree. No native bridge modules are needed.
+
+## Installation
+
+### 1. Install the SDK package
+
+```bash
+npm install @propel-nsl/propel-react-native-sdk
+# or
+yarn add @propel-nsl/propel-react-native-sdk
+```
+
+### 2. Install peer dependencies
+
+The SDK declares its React Native dependencies as `peerDependencies`. Your host app must have these installed:
+
+**Required:**
+- `react` (>=18.0.0)
+- `react-native` (>=0.72.0)
+- `@react-native-async-storage/async-storage`
+- `@react-native-community/netinfo`
+- `@react-navigation/native`, `@react-navigation/stack`, `@react-navigation/bottom-tabs`
+- `@reduxjs/toolkit`, `react-redux`, `redux-saga`
+- `react-native-gesture-handler`, `react-native-reanimated`
+- `react-native-safe-area-context`, `react-native-screens`
+- `react-native-device-info`
+- `react-native-svg`
+- `react-native-toast-message`
+
+**Optional:**
+- `@react-native-clipboard/clipboard`
+- `@react-native-community/masked-view`
+- `react-native-fast-image`
+- `react-native-image-picker`
+- `react-native-permissions`
+
+### 3. Configure Metro
+
+The SDK ships raw TypeScript source that Metro transpiles. Add the SDK to your `metro.config.js` so Metro can resolve its internal `src-app` alias:
+
+```js
+const path = require('path');
+const sdkRoot = path.resolve(__dirname, 'node_modules/@propel-nsl/propel-react-native-sdk');
+
+const config = {
+  watchFolders: [
+    sdkRoot,
+  ],
+  resolver: {
+    extraNodeModules: {
+      'src-app': path.resolve(sdkRoot, 'src-app'),
+    },
+    nodeModulesPaths: [
+      path.resolve(__dirname, 'node_modules'),
+    ],
+  },
+};
+```
+
+### 4. iOS: pod install
+
+```bash
+cd ios && pod install
+```
+
+## Usage
+
+### Add the SDK screen to your navigator
+
+```tsx
+import { PropelSDKScreen } from '@propel-nsl/propel-react-native-sdk';
+
+const Stack = createStackNavigator();
+
+function App() {
+  return (
+    <NavigationContainer>
+      <Stack.Navigator>
+        <Stack.Screen name="Home" component={HomeScreen} />
+        <Stack.Screen
+          name="PropelSDK"
+          component={PropelSDKScreen}
+          options={{ headerShown: false, gestureEnabled: false }}
+        />
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+### Navigate to the SDK
+
+```tsx
+// Open Redeem screen
+navigation.navigate('PropelSDK', {
+  screen: 'redeem',
+  authToken: '<your-auth-token>',
+  authId: '<your-auth-id>',
+  apiUrl: 'https://staging-admin.zaggle.in',
+  environment: 'staging',
+});
+
+// Open Redemption History screen
+navigation.navigate('PropelSDK', {
+  screen: 'redemption-history',
+  authToken: '<your-auth-token>',
+  authId: '<your-auth-id>',
+  apiUrl: 'https://staging-admin.zaggle.in',
+  environment: 'staging',
+});
+```
+
+### Available `screen` values
+
+| Value | Destination |
+|---|---|
+| `dashboard` | Dashboard / Homepage |
+| `redeem` | Redeem |
+| `redemption-history` | Redemption History |
+| `transaction-history` | Redemption History (alias) |
+
+### Full list of params
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `screen` | string | Yes | Target screen (`dashboard`, `redeem`, or `redemption-history`) |
+| `authToken` | string | Yes | Authentication token for SDK API calls |
+| `authId` | string | Yes | Authentication ID |
+| `apiUrl` | string | No | Override API base URL |
+| `userId` | string | No | User identifier |
+| `userName` | string | No | User display name |
+| `userMobile` | string | No | User mobile number |
+| `userEmail` | string | No | User email |
+| `deviceId` | string | No | Device identifier |
+| `clientName` | string | No | Client app name |
+| `clientVersion` | string | No | Client app version |
+| `environment` | string | No | `development`, `staging`, or `production` |
+| `userToken` | string | No | Pre-existing access token (skips SDK auth) |
+
+## Architecture
+
+- The SDK runs its **own isolated Redux store** — it does not share state with the host app.
+- When `__rnHostMode` is detected (set automatically by `PropelSDKScreen`), the SDK skips the native bridge and reads params directly from React props.
+- The SDK authenticates itself using `authToken` + `authId` via its internal `sdkAuthApi`, then navigates to the requested screen.
+
+## Sample Host App
+
+See `propel-sample-host-app-rn/` for a complete working example.

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@propel-nsl/propel-react-native-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Propel Mobile SDK - React Native Core",
-  "files": ["src/", "src-app/", "lib/", "assets/", "index.ts"],
+  "files": ["src/", "src-app/", "lib/", "assets/", "index.ts", "CLIENT_INTEGRATION_GUIDE.md", "RN_HOST_INTEGRATION.md", "README.md"],
   "main": "index.ts",
   "react-native": "lib/index.ts",
   "types": "lib/index.ts",
+  "README": "CLIENT_INTEGRATION_GUIDE.md",
   "scripts": {
     "bundle:android": "react-native bundle --platform android --dev false --entry-file index.ts --bundle-output ../android/propelsdk/src/main/assets/index.android.bundle --assets-dest ../android/propelsdk/src/main/res --minify",
     "bundle:ios": "react-native bundle --platform ios --dev false --entry-file index.ts --bundle-output ../ios/PropelSDK/Assets/index.ios.jsbundle --assets-dest ../ios/PropelSDK/Assets --minify",
     "bundle:android:dev": "react-native bundle --platform android --dev true --entry-file index.ts --bundle-output ../android/propelsdk/src/main/assets/index.android.bundle --assets-dest ../android/propelsdk/src/main/res",
-    "bundle:ios:dev": "react-native bundle --platform ios --dev true --entry-file index.ts --bundle-output ../ios/PropelSDK/Assets/index.ios.jsbundle --assets-dest ../ios/PropelSDK/Assets"
+    "bundle:ios:dev": "react-native bundle --platform ios --dev true --entry-file index.ts --bundle-output ../ios/PropelSDK/Assets/index.ios.jsbundle --assets-dest ../ios/PropelSDK/Assets",
+    "prepare": "npm run build",
+    "build": "echo 'Building SDK package...' && echo 'Documentation included in package'",
+    "prepublishOnly": "echo 'Preparing to publish SDK with documentation...' && npm run build"
   },
   "dependencies": {
     "@babel/runtime": "^7.28.4",