# react-native-paygilant-wrapper

React Native bridge for the Paygilant fraud-detection SDK (Android and iOS). It exposes one JS/TS interface
(`import Paygilant from 'react-native-paygilant-wrapper'`) over the native Paygilant SDK.

## Installation

```sh
npm install react-native-paygilant-wrapper
cd ios && pod install
```

That is all. There are no Podfile changes and you do not add the Paygilant SDK yourself: the wrapper brings the
iOS SDK with it, and its version is the one that ships with the wrapper release.

On iOS, add the **Access WiFi Information** capability to your app target (Signing & Capabilities) and to the App ID in
the Apple Developer portal, and declare the permissions you ask for in `Info.plist`.

### What `pod install` does

The iOS SDK is no longer a CocoaPods dependency (the CocoaPods trunk stops accepting new versions on 2026-12-02).
During `pod install` the wrapper's podspec downloads the SDK xcframework for its version, verifies its SHA-256 checksum
against the `PaygilantSDK-SPM` release, and vendors it into the pod. Practical consequences:

- The first `pod install` needs network access (GitHub and the Paygilant artifact bucket) plus `curl` and `unzip`.
- The SDK is stored inside `node_modules/react-native-paygilant-wrapper/ios/`. Removing `node_modules` removes it; the
  next `pod install` downloads it again.
- Do not add a `pod 'PaygilantSDK'` line to your own Podfile: it would conflict.

### Swift Package Manager (React Native 0.87+, optional)

React Native's own SwiftPM support is **experimental** and opt-in; CocoaPods remains the default and is what we
recommend for React Native apps today. If you opt in:

```sh
npm install react-native-paygilant-wrapper
cd ios && npx react-native spm --deintegrate   # once, converts the app to SwiftPM
```

The SDK then arrives through this package's `Package.swift` (it depends on
[`PaygilantSDK-SPM`](https://github.com/Paygilant/PaygilantSDK-SPM) at the exact version of the release). After that, run
`npx react-native spm` after installing or removing packages, on a fresh clone, and in CI before building. Build the
`.xcodeproj` (not a workspace) and never run `pod install` again. `npx react-native spm deinit` goes back to CocoaPods.

## Supported versions

What was actually built and run (iOS simulator, Debug, Xcode 26.6):

| React Native | Architecture | Install path | App iOS minimum | Result |
| --- | --- | --- | --- | --- |
| 0.75.5 | Old (legacy) | CocoaPods | 13.4 | Builds, SDK embedded, app launches |
| 0.85.3 | New | CocoaPods, static linking | 15.1 | Builds, SDK embedded, app launches |
| 0.85.3 | New | CocoaPods, `USE_FRAMEWORKS=dynamic` | 15.1 | Builds, SDK embedded, app launches |
| 0.87.1 | New | SwiftPM (`npx react-native spm`) | 15.1 | Builds, SDK embedded, 12/12 end-to-end tests pass |

Notes:

- **Other React Native versions:** the CocoaPods install uses a standard vendored framework and nothing specific to a
  React Native version, so other versions are expected to work, but they have **not been tested**. SwiftPM needs React
  Native 0.87+.
- **Architecture:** old architecture was run on 0.75.5 and new architecture on 0.85.3 and 0.87.1. Neither version was
  run with the other architecture, and the end-to-end suite was not run on the old architecture.
- **iOS minimum:** the Paygilant iOS SDK supports **iOS 12 and up** (the `PaygilantSDK-SPM` package declares iOS 12).
  In a React Native app the effective minimum is the higher of that and what your React Native version requires
  (13.4 on 0.75, 15.1 on 0.85 and 0.87 in the apps above; the SwiftPM path needs 15). The wrapper itself does not raise
  it further.
- **Not tested:** Android with this release's changes, real devices, Release/Archive builds, Expo, and React Native
  older than 0.75.

## Updating

```sh
npm install react-native-paygilant-wrapper@<new-version>
cd ios && pod install          # or: npx react-native spm
```

To force a clean SDK download, delete `node_modules/react-native-paygilant-wrapper/ios/PaygilantSDK.xcframework`
(or `node_modules`) and run `pod install` again. If Xcode still shows old behavior, clear DerivedData
(for SwiftPM also File > Packages > Reset Package Caches).

## Usage

```ts
import Paygilant from 'react-native-paygilant-wrapper';

async function startPaygilant() {
  // 1. Initialize once at app start with the server URL Paygilant gave you.
  try {
    await Paygilant.initialize(serverUrl, clientSessionId, /* toAskPermissions */ true);
  } catch (e) {
    const message = String((e as Error)?.message ?? e);
    const policyNotApproved =
      message.includes('SET_APPROVE_POLICY_TO_TRUE') ||
      message.includes('setApprovePolicy method to true'); // Android / iOS
    if (!policyNotApproved) {
      // A real failure (for example no connection to the server): handle it in your app.
      return;
    }
    // 2. The privacy policy was not accepted yet, so nothing was sent. Show your own policy UI and, once the
    //    user accepts, approve it. The session starts then; there is no need to call initialize again.
    const accepted = await showYourPrivacyPolicyDialog(); // your own UI
    if (!accepted) return;
    await Paygilant.setApprovePolicy(true);
  }

  // 3. Session id for your backend calls ('no_session_id' if it could not be obtained)
  const sessionId = await Paygilant.getSessionId();
}
```

You can also call `Paygilant.setApprovePolicy(true)` before `initialize` if your app already has the user's consent, and
`Paygilant.isApprovePolicy()` tells you whether the policy was already accepted.

Other methods: `setClientSessionId`, `askPaygilantPermissions`, `startUserVerification`, `getDeviceId`, `setUserId`,
`startNewScreenListener`, `pauseListenToSensors`. See the Paygilant integration documentation for the full API.

## Contributing

See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
This repository has two example apps used by `npm run ci:tests`: [`example`](example) (CocoaPods) and
[`example-spm`](example-spm) (SwiftPM, React Native 0.87+).

## License

MIT

---

Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)