react-native-knotapi/README.md

Provide a seamless way for end users to link their merchant accounts to your mobile app.

# React Native KnotAPI

[![Test Bridge](https://github.com/knotapi/react-native-knotapi/actions/workflows/test.yml/badge.svg)](https://github.com/knotapi/react-native-knotapi/actions/workflows/test.yml)

Please see https://docs.knotapi.com/ for installation instructions.

## 🚨 Critical Bridge Fixes

This version includes critical fixes to prevent crashes in React Native applications, specifically addressing bridge teardown race conditions and memory management issues.

### Quick Fix Summary
- **Bridge State Management**: Added lifecycle tracking to prevent events being sent to deallocated bridges
- **Close Protection**: Prevents multiple close calls and double teardown scenarios  
- **Delegate Safety**: All delegate methods now safely ignore events when bridge is inactive
- **Exception Handling**: Graceful handling of exceptions during close operations
- **Memory Management**: Proper cleanup and weak reference patterns

### Crash Scenarios Fixed
- ✅ Bridge teardown race conditions
- ✅ Events sent to deallocated bridge
- ✅ Multiple close() calls causing double teardown
- ✅ Memory leaks and retain cycles
- ✅ Exception handling during close operations

### Required iOS SDK Fix
**CRITICAL**: The iOS SDK must also be updated to make `KnotSession.delegate` a weak reference:

```swift
// In KnotSession.swift - REQUIRED FIX
public weak var delegate: KnotEventDelegate?
```

### Testing
Comprehensive test suite included to verify all crash scenarios are handled:

```bash
cd ios/
./run_tests.sh
```

**Test Options:**
- **Simple Tests** (No Xcode required) - Quick verification of all fixes
- **Full XCTest Suite** - Comprehensive testing with mocking and edge cases
- **Crash Scenario Tests** - Specific tests for crash prevention


### GitHub Actions Integration
Automated testing with GitHub Actions:

- **Bridge Tests** - Runs on push/PR/release, comprehensive bridge testing
- **Conditional Testing** - Additional tests run on releases (iOS compatibility, documentation)


## 📚 Technical Details

### Bridge Fixes Implementation

**Files Modified:**
- `ios/Knotapi.mm` - Core bridge implementation with safety checks

**Key Changes:**
```objc
// Added properties
@property (nonatomic, assign) BOOL isBridgeActive;
@property (nonatomic, assign) BOOL isClosing;

// Added safety checks to all delegate methods
- (void)onErrorWithError:(enum KnotError)error {
    if (!self.isBridgeActive) {
        NSLog(@"KnotAPI onError: Bridge inactive, ignoring event");
        return;
    }
    // ... rest of method
}

// Added close protection
- (void)close {
    if (self.isClosing) {
        NSLog(@"KnotAPI close: Already closing, ignoring duplicate call");
        return;
    }
    self.isClosing = YES;
    // ... rest of method
}
```

### Test Suite

**Test Files:**
- `ios/SimpleBridgeTest.m` - Quick verification (no Xcode required)
- `ios/KnotapiTests.m` - Full XCTest suite
- `ios/KnotapiCrashScenarioTests.m` - Crash scenario tests
- `ios/run_tests.sh` - Comprehensive test runner (includes verification)

**Running Tests:**
```bash
cd ios/
./run_tests.sh
```

### GitHub Actions

**Workflow:** `.github/workflows/test.yml`
- **Triggers:** Push/PR/release/manual
- **Tests:** Bridge fixes, compilation, integration
- **Conditional:** iOS compatibility and docs on releases

**Manual Testing:**
```bash
gh workflow run test.yml
```

---

## 🔧 Troubleshooting

### iOS Build Issues

#### Node.js Path Issues (Homebrew Installation)

If you installed Node.js via Homebrew and encounter build errors like:
```
/usr/local/bin/node: No such file or directory
```

**Solution:**
Create a symlink to make Node.js accessible at the expected path:

```bash
sudo ln -sf /opt/homebrew/bin/node /usr/local/bin/node
```

**Verify the fix:**
```bash
which node
# Should show: /opt/homebrew/bin/node

/usr/local/bin/node --version
# Should show your Node.js version
```

#### Test Files in Library Build

If you encounter errors like:
```
'XCTest/XCTest.h' file not found (in target 'react-native-knotapi' from project 'Pods')
```

**Solution:**
The podspec has been updated to exclude test files from the main library build. If you're still seeing this error:

1. Clean your build:
   ```bash
   cd example/ios
   rm -rf build Pods Podfile.lock
   ```

2. Reinstall pods:
   ```bash
   pod install
   ```

3. Try building again:
   ```bash
   cd ..
   npm run ios
   ```

#### General iOS Build Issues

If you encounter other iOS build issues:

1. **Clean everything:**
   ```bash
   cd example/ios
   rm -rf build Pods Podfile.lock
   cd ..
   rm -rf node_modules
   npm install
   cd ios
   pod install
   ```

2. **Check Xcode version compatibility:**
   - Ensure you're using Xcode 16.1 or later
   - Verify iOS deployment target is 15.1+

3. **Verify React Native setup:**
   ```bash
   npx react-native doctor
   ```

---

## Installation & Usage

Please see https://docs.knotapi.com/ for complete installation and usage instructions.