nimbbl-mobile-react-native-sdk 1.0.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nimbbl Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,569 @@
+# Nimbbl React Native SDK
+
+A comprehensive React Native SDK for integrating Nimbbl payment gateway into your mobile applications. This SDK provides a seamless bridge between React Native and native payment functionality.
+
+## Features
+
+- 🚀 **Easy Integration** - Simple setup and initialization
+- 💳 **Multiple Payment Methods** - Support for cards, UPI, netbanking, wallets, EMI, and cash
+- 🌐 **WebView Integration** - Built-in payment webview with customization options
+- 🔗 **Bridge Module** - Robust native bridge for communication
+- 📱 **Cross Platform** - Support for both iOS and Android
+- 🛡️ **Type Safety** - Comprehensive TypeScript definitions
+- 📊 **Analytics** - Built-in analytics and logging
+- 🔄 **Event Handling** - Real-time payment status updates
+
+## Installation
+
+### Option 1: Install from npm (Recommended for production)
+
+```bash
+npm install nimbbl-mobile-react-native-sdk
+# or
+yarn add nimbbl-mobile-react-native-sdk
+```
+
+### Option 2: Local Development Setup
+
+For local development and testing of the SDK itself:
+
+1. Clone this repository
+2. Navigate to your React Native project
+3. Install the local SDK:
+
+```bash
+npm run link:local
+# or manually:
+npm install path/to/nimbbl_mobile_kit_react_native_sdk
+```
+
+### Switching Between Local and NPM
+
+Use the provided scripts in your sample app:
+
+```bash
+# Link to local development version
+npm run link:local
+
+# Link to published npm version  
+npm run link:npm
+```
+
+## Compatibility
+
+### NPM Version Support
+
+The Nimbbl React Native SDK is compatible with the following npm versions:
+
+| NPM Version | Support Status | Notes |
+|-------------|----------------|-------|
+| `^1.0.0-alpha.0` | ✅ Supported | Initial alpha release |
+| `^1.0.0-alpha.1` | ✅ Supported | Bug fixes and improvements |
+| `^1.0.0-alpha.2` | ✅ Supported | Enhanced error handling |
+| `^1.0.0-alpha.3` | ✅ Supported | Latest alpha release |
+| `^1.0.0` | 🔄 Coming Soon | Stable release |
+| `^1.1.0` | 🔄 Coming Soon | Feature updates |
+| `^2.0.0` | 🔄 Coming Soon | Major version with breaking changes |
+
+### React Native Version Support
+
+| React Native Version | Support Status | Notes |
+|----------------------|----------------|-------|
+| `^0.70.0` | ✅ Supported | Minimum supported version |
+| `^0.71.0` | ✅ Supported | Recommended version |
+| `^0.72.0` | ✅ Supported | Recommended version |
+| `^0.73.0` | ✅ Supported | Latest stable version |
+| `^0.74.0` | ✅ Supported | Latest stable version |
+| `^0.75.0` | ✅ Supported | Latest stable version |
+| `^0.76.0` | ✅ Supported | Latest stable version |
+
+### Node.js Version Support
+
+| Node.js Version | Support Status | Notes |
+|-----------------|----------------|-------|
+| `^16.0.0` | ✅ Supported | Minimum supported version |
+| `^18.0.0` | ✅ Supported | Recommended version |
+| `^20.0.0` | ✅ Supported | Latest LTS version |
+| `^21.0.0` | ✅ Supported | Latest stable version |
+
+### Platform Support
+
+| Platform | Support Status | Minimum Version |
+|----------|----------------|-----------------|
+| **Android** | ✅ Supported | API Level 21 (Android 5.0) |
+| **iOS** | ✅ Supported | iOS 13.0+ |
+
+### Breaking Changes
+
+- **Alpha Releases**: Alpha versions may contain breaking changes between releases
+- **Stable Releases**: Breaking changes will be clearly documented in release notes
+- **Migration Guide**: Migration guides will be provided for major version updates
+
+### Versioning Strategy
+
+- **Alpha Releases** (`1.0.0-alpha.X`): For testing and early adoption
+- **Beta Releases** (`1.0.0-beta.X`): For feature-complete testing
+- **Release Candidates** (`1.0.0-rc.X`): For final testing before stable release
+- **Stable Releases** (`1.0.0`, `1.1.0`, etc.): For production use
+
+## Quick Start
+
+### Import the SDK
+
+The import statement depends on whether you're using the npm package or local development version:
+
+**For npm package (production use):**
+```javascript
+import { NimbblSDK } from 'nimbbl-mobile-react-native-sdk';
+```
+
+**For local development:**
+```javascript
+import { NimbblSDK } from '../nimbbl_mobile_kit_react_native_sdk/src/index';
+// or if you've linked it locally:
+import { NimbblSDK } from 'nimbbl-react-native-sdk';
+```
+
+### 1. Initialize the SDK
+
+```javascript
+import { NimbblSDK } from 'nimbbl-mobile-react-native-sdk';
+
+const nimbblSDK = NimbblSDK.getSharedInstance();
+
+// Initialize the SDK (no credentials required - matches iOS pattern)
+await nimbblSDK.initialize({
+  environment: 'sandbox' // or 'production'
+});
+```
+
+### 2. Create an Order
+
+```javascript
+const orderData = {
+  currency: 'INR',
+  amount: '1000', // Amount as string
+  productId: '11', // Product ID for header customization
+  orderLineItems: true,
+  checkoutExperience: 'redirect',
+  paymentMode: '', // Leave empty for all payment modes
+  subPaymentMode: 'all banks', // or specific bank
+  user: {
+    email: 'john@example.com',
+    name: 'John Doe',
+    mobile_number: '9876543210'
+  }
+};
+
+const order = await nimbblSDK.createShopOrder(
+  orderData.currency,
+  orderData.amount,
+  orderData.productId,
+  orderData.orderLineItems,
+  orderData.checkoutExperience,
+  orderData.paymentMode,
+  orderData.subPaymentMode,
+  orderData.user
+);
+```
+
+### 3. Process Payment
+
+```javascript
+// Process payment using checkout method (matching iOS pattern)
+const checkoutResult = await nimbblSDK.checkout({
+  orderToken: order.data.token,
+  paymentModeCode: '', // Leave empty for all payment modes
+  bankCode: '', // Leave empty for all banks
+  walletCode: '', // Leave empty for all wallets
+  paymentFlow: '' // Leave empty for default flow (or 'phonepe', 'collect', 'intent' for UPI)
+});
+```
+
+### 4. Handle Payment Status
+
+The SDK automatically handles payment status through event listeners. You don't need to manually check status.
+
+## API Reference
+
+### NimbblSDK
+
+The main SDK class that provides all payment functionality.
+
+#### Methods
+
+- `getSharedInstance()` - Get shared SDK instance (singleton pattern)
+- `initialize(config)` - Initialize the SDK with configuration
+- `createShopOrder(currency, amount, productId, orderLineItems, checkoutExperience, paymentMode, subPaymentMode, user)` - Create a new payment order
+- `checkout(options)` - Process payment with order token
+- `testNativeModule()` - Test native module availability
+- `addEventListener(eventName, callback)` - Add event listener
+- `removeEventListener(eventName, callback)` - Remove event listener
+- `removeAllEventListeners()` - Remove all event listeners
+
+### Event Handling
+
+```javascript
+import { NimbblSDK, EVENTS } from 'nimbbl-react-native-sdk';
+
+const nimbblSDK = NimbblSDK.getSharedInstance();
+
+// Listen for payment events
+nimbblSDK.addEventListener(EVENTS.PAYMENT_SUCCESS, (data) => {
+  console.log('Payment successful:', data);
+  // Handle success - navigate to success screen
+});
+
+nimbblSDK.addEventListener(EVENTS.PAYMENT_FAILED, (data) => {
+  console.log('Payment failed:', data);
+  // Handle failure - show error message
+});
+```
+
+## Configuration
+
+### SDK Configuration
+
+```javascript
+const config = {
+  environment: 'sandbox', // 'sandbox' or 'production'
+  options: {
+    timeout: 30000,
+    enable_logging: true,
+    enable_analytics: true,
+    api_base_url: 'https://api.nimbbl.tech/' // Optional: override default URL
+  }
+};
+```
+
+## Constants
+
+The SDK provides various constants for better development experience:
+
+```javascript
+import {
+  EVENTS,
+  ENVIRONMENTS,
+  ERROR_CODES,
+  ERROR_MESSAGES,
+  DEFAULT_CONFIG,
+  SDK_VERSION
+} from 'nimbbl-react-native-sdk';
+```
+
+## Error Handling
+
+```javascript
+try {
+  const order = await nimbblSDK.createShopOrder(
+    'INR', '1000', '11', true, 'redirect', '', 'all banks',
+    { email: 'john@example.com', name: 'John Doe', mobile_number: '9876543210' }
+  );
+} catch (error) {
+  console.error('Error creating order:', error.message);
+  
+  // Check error codes
+  if (error.code === ERROR_CODES.INVALID_AMOUNT) {
+    // Handle invalid amount error
+  }
+}
+```
+
+## Platform Setup
+
+### iOS
+
+1. Install pods:
+```bash
+cd ios && pod install
+```
+
+2. Add to your `Info.plist`:
+```xml
+<key>NSAppTransportSecurity</key>
+<dict>
+    <key>NSAllowsArbitraryLoads</key>
+    <true/>
+</dict>
+```
+
+**Note:** The iOS implementation is written in Swift for modern, type-safe development.
+
+### Android
+
+1. Add to your `android/app/build.gradle`:
+```gradle
+android {
+    defaultConfig {
+        minSdkVersion 21
+    }
+}
+```
+
+2. Add to your `android/app/src/main/AndroidManifest.xml`:
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+```
+
+**Note:** The Android implementation is written in Kotlin for modern, type-safe development.
+
+## Examples
+
+### Complete Payment Flow
+
+```javascript
+import { NimbblSDK, EVENTS } from 'nimbbl-react-native-sdk';
+
+class PaymentManager {
+  constructor() {
+    this.nimbblSDK = NimbblSDK.getSharedInstance();
+  }
+
+  async initialize() {
+    await this.nimbblSDK.initialize({
+      environment: 'sandbox'
+    });
+  }
+
+  setupEventListeners() {
+    this.nimbblSDK.addEventListener(EVENTS.PAYMENT_SUCCESS, (data) => {
+      console.log('Payment successful:', data);
+      // Navigate to success screen
+    });
+
+    this.nimbblSDK.addEventListener(EVENTS.PAYMENT_FAILED, (data) => {
+      console.log('Payment failed:', data);
+      // Show error message
+    });
+  }
+
+  async processPayment(amount, customerDetails) {
+    try {
+      // Create order
+      const order = await this.nimbblSDK.createShopOrder(
+        'INR',
+        amount.toString(),
+        '11',
+        true,
+        'redirect',
+        '',
+        'all banks',
+        customerDetails
+      );
+
+      // Process payment using the order token
+      const result = await this.nimbblSDK.checkout({
+        orderToken: order.data.token,
+        paymentModeCode: '',
+        bankCode: '',
+        walletCode: '',
+        paymentFlow: ''
+      });
+      
+      return { success: true, order, result };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+}
+```
+
+## Development Workflow
+
+### Setting up for local development
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/nimbbl-tech/nimbbl_mobile_kit_react_native_sdk.git
+   cd nimbbl_mobile_kit_react_native_sdk
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+3. **Build the SDK:**
+   ```bash
+   npm run build
+   ```
+
+4. **Link to sample app:**
+   ```bash
+   npm run example:local
+   ```
+
+### Integration with Sample App
+
+The SDK is integrated into the sample app through the `PaymentService` class. Here's how it works:
+
+1. **Configuration**: Update `src/constants/config.ts` with your Nimbbl credentials
+2. **Payment Processing**: The `PaymentService` uses the Nimbbl SDK to:
+   - Initialize the SDK with your credentials
+   - Create orders using `NimbblSDK.createShopOrder()`
+   - Process payments using `NimbblSDK.checkout()`
+   - Handle payment events through event listeners
+
+3. **Usage Flow**:
+   - User fills order details in the sample app
+   - Clicks "Pay" button
+   - `PaymentService.processPayment()` is called
+   - SDK creates order and opens payment WebView
+   - Payment events are handled through event listeners
+
+### Sample App Structure
+
+```
+nimbbl_react_native_sample_app/
+├── src/
+│   ├── services/
+│   │   └── PaymentService.ts          # Integrated with Nimbbl SDK
+│   ├── constants/
+│   │   └── config.ts                  # SDK configuration
+│   ├── screens/
+│   │   └── MainScreen.tsx             # Main payment screen
+│   └── hooks/
+│       └── usePayment.ts              # Payment hook using PaymentService
+```
+
+### Development Scripts
+
+```bash
+# Build the SDK
+npm run build
+
+# Build in watch mode (rebuilds on changes)
+npm run dev
+
+# Clean build artifacts
+npm run clean
+
+# Run linter
+npm run lint
+
+# Fix linting issues
+npm run lint:fix
+
+# Type checking
+npm run type-check
+
+# Link sample app to local SDK
+npm run example:local
+
+# Link sample app to npm SDK
+npm run example:npm
+```
+
+### Testing Your Changes
+
+1. Make changes to the SDK source code
+2. Run `npm run build` to compile TypeScript
+3. Test in the sample app
+4. The sample app should automatically pick up your changes
+
+### Publishing
+
+1. Update version in `package.json`
+2. Run `npm run build`
+3. Run `npm publish`
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes and test with local development setup
+4. Commit your changes (`git commit -m 'Add some amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+For support, email support@nimbbl.tech or join our Slack channel.
+
+## Version Migration
+
+### Upgrading Between Alpha Versions
+
+When upgrading between alpha versions, check the changelog for breaking changes:
+
+```bash
+# Check current version
+npm list nimbbl-mobile-react-native-sdk
+
+# Upgrade to latest alpha
+npm install nimbbl-mobile-react-native-sdk@latest
+
+# Or upgrade to specific version
+npm install nimbbl-mobile-react-native-sdk@1.0.0-alpha.3
+```
+
+### Migration from Alpha to Stable
+
+When the stable version is released:
+
+```bash
+# Upgrade from alpha to stable
+npm install nimbbl-mobile-react-native-sdk@^1.0.0
+
+# Update your package.json
+# Change from: "nimbbl-mobile-react-native-sdk": "^1.0.0-alpha.3"
+# To: "nimbbl-mobile-react-native-sdk": "^1.0.0"
+```
+
+### Breaking Changes Migration
+
+For major version updates (e.g., 1.x to 2.x):
+
+1. Check the migration guide in the release notes
+2. Update your code according to the breaking changes
+3. Test thoroughly before deploying to production
+
+### Version Locking
+
+For production applications, consider locking to specific versions:
+
+```json
+{
+  "dependencies": {
+    "nimbbl-mobile-react-native-sdk": "1.0.0-alpha.3"
+  }
+}
+```
+
+### Deprecation Policy
+
+- **Alpha versions**: Features may be deprecated without notice
+- **Stable versions**: Deprecated features will be marked with warnings for at least one minor version
+- **Major versions**: Breaking changes will be clearly documented
+
+## Changelog
+
+### 1.0.0-alpha.3
+- Updated package name to `nimbbl-mobile-react-native-sdk`
+- Enhanced compatibility documentation
+- Improved version migration guides
+- Fixed package-lock.json tracking issues
+
+### 1.0.0-alpha.2
+- Enhanced error handling
+- Improved event communication
+- Fixed IntentReceiver leak
+- Standardized Activity Result communication
+
+### 1.0.0-alpha.1
+- Bug fixes and improvements
+- Enhanced WebView integration
+- Improved TypeScript definitions
+
+### 1.0.0-alpha.0
+- Initial alpha release
+- Core payment functionality
+- WebView integration
+- Bridge module
+- Type definitions
+- Comprehensive documentation
+- Unified payment result screen

package/android/build.gradle

@@ -0,0 +1,86 @@
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.1.0'
+        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
+apply plugin: 'maven-publish'
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+        maven { url 'https://jitpack.io' }
+        maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
+        maven { url "$rootDir/../node_modules/react-native/android" }
+    }
+}
+
+group = 'com.nimbbl.reactnative'
+version = '1.0.0'
+
+android {
+    namespace 'com.nimbbl.reactnative'
+    compileSdkVersion 36
+    buildToolsVersion "36.0.0"
+
+    defaultConfig {
+        minSdkVersion 24
+        targetSdkVersion 36
+        versionCode 1
+        versionName "1.0.0"
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+
+    lintOptions {
+        abortOnError false
+    }
+}
+
+dependencies {
+    // React Native dependencies (required for bridge)
+    compileOnly 'com.facebook.react:react-native:+'
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+    
+    // Nimbbl WebView SDK dependency (includes all necessary dependencies)
+    implementation 'com.github.nimbbl-tech:nimbbl_mobile_kit_android_webview_sdk:3.0.12'
+    
+    // Add Retrofit and Coroutines dependencies for Android SDK
+    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4'
+}
+
+afterEvaluate {
+    publishing {
+        publications {
+            release(MavenPublication) {
+                from components.release
+                groupId = 'com.nimbbl.reactnative'
+                artifactId = 'nimbbl-react-native-sdk'
+                version = '1.0.0'
+            }
+        }
+    }
+}

package/android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,6 @@
+#Tue Aug 05 20:11:30 IST 2025
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

package/android/gradle.properties

@@ -0,0 +1,4 @@
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+android.useAndroidX=true
+android.enableJetifier=true
+android.suppressUnsupportedCompileSdk=36