Align React Native SDK with OMS Wallet 0.2.0

[tolgahan-arikan]

Summary

• Upgrade the wrapper to the OMS Wallet Swift and Kotlin SDK shape and rename the internal TurboModule and pod target accordingly.
• Finalize the public API around OMSWallet, WalletAccount, exported Networks, fixed OMS relay OIDC providers, custom provider redirects, structured session auth, stable OMS errors, fee selectors, and transaction status resolution.
• Move email session lifetime to startEmailAuth({ email, sessionLifetimeSeconds }) so invalid values fail before OTP delivery; completeEmailAuth now only completes the pending attempt.
• Require the actual callback URL when handling an OIDC redirect and keep native transport/codegen types behind SDK-owned public models.
• Normalize absent public values to optional properties or undefined; native bridge null values no longer leak through public responses, errors, selectors, or inputs.
• Enforce the documented single-OMSWallet lifecycle: constructing a replacement invalidates the old wrapper and clears stale listeners, replay state, and fee selectors.
• Update the bare React Native, Expo, and Trails examples together with focused bridge, runtime-shape, and declaration tests.
• Rewrite the README and API reference for React Native and Expo development builds, add packed-package Expo verification, and align the repository/package license with the other OMS Wallet SDKs under Apache-2.0.
• Pin the published OMS Wallet Swift and Kotlin SDK 0.2.0 releases, refresh the iOS example lockfile, and align signed release-tag metadata.

Breaking API Changes

• OMSClient becomes OMSWallet; an individual wallet record is WalletAccount.
• Public domain types use unprefixed names such as CompleteAuthResult, FeeOptionSelector, and TransactionStatusPollingOptions.
• Optional public inputs no longer accept null; omit them or pass undefined.
• Absent public output metadata uses optional properties or undefined, including session fields, transaction hashes, fee data, indexer metadata, access pagination, and structured error details.
• startEmailAuth accepts an object and owns sessionLifetimeSeconds; completeEmailAuth no longer accepts it.
• handleOidcRedirectCallback requires callbackUrl.
• OidcProviders becomes fixed OmsRelayOidcProviders values; custom providers require providerRedirectUri.
• Wallet, signing, transaction, and indexer methods use exported Network values.
• Signature verification methods are isValidMessageSignature and isValidTypedDataSignature.
• Redirect completion returns { type: "completed", result }; session state exposes structured auth details.
• A process should construct and reuse one OMSWallet; a later construction replaces the earlier instance.

React Native And Expo

• Supports React Native 0.85+, React 19.2+, Android compileSdk 36 / minSdk 24, iOS 15+, and Xcode 26.
• Expo SDK 56 is supported through a development build and standard native autolinking; no config plugin is required.
• Expo Go and React Native Web are not supported because the package contains native modules.
• Redirect examples distinguish react-native-inappbrowser-reborn for bare apps from expo-web-browser for Expo apps.

Diff Drivers

• Overall: 53 files, 6,146 additions, and 2,205 deletions.
• Most source churn comes from replacing the old wrapper/bridge surface with explicit public models, native-to-public hydration, renamed native modules, and stricter lifecycle handling.
• Documentation and example churn comes from replacing the stale API shape consistently across the API reference, README, bare React Native, Expo, and Trails examples.
• Test growth covers bridge routing, lifecycle behavior, native-null normalization, required indexer transaction fields, public declaration nullability, and package/autolinking behavior.
• The Apache-2.0 license text accounts for 202 added lines.
• Generated WaaS client contents were not edited.

Validation

• yarn verify: lint, TypeScript checks, package build, 23 focused bridge/public-boundary tests, and generated API reference verification.
• Packed local package installed into the Expo example; package metadata/license, TypeScript, and native autolinking passed.
• Public package declarations contain no | null outside the internal TurboModule transport and do not include test declarations.
• Full Android example build resolved OMS Wallet Kotlin SDK 0.2.0 and its generated runtime from Maven Central with Maven-local disabled.
• Full iOS Simulator example build resolved OMS Wallet Swift SDK 0.2.0 from CocoaPods and passed with Xcode 26.6.
• git diff --check.

[github-actions]

Claude finished @tolgahan-arikan's task —— View job

---

Review: PR #55 — Align React Native SDK with OMS Wallet 0.2.0

• Review TypeScript public API & exported types
• Check native bridge consistency (src/, android/, ios/)
• Review auth, session, wallet selection, signing, transaction security
• Check for backwards-compat shims
• Verify API.md / README.md / PUBLISHING.md updates
• Check Expo example dependency policy
• Assess test coverage & verification

Overall this is a clean, well-structured alignment. The TS spec, Android (OmsWalletReactNativeSdkModule.kt) and iOS (OmsWalletReactNativeSdkImpl.swift + .mm) bridges are consistent: all 28 methods and both events (onFeeOptionSelectionRequest, onSessionExpired) exist on every layer with matching argument order/count, module name OmsWalletReactNativeSdk matches the JS getEnforcing, and no backwards-compat shims remain. Public types correctly hide | null behind the internal transport and normalize to undefined (nicely enforced by test/public-api-types.ts).

A few issues to look at before merge:

Blockers / correctness

1. sessionLifetimeSeconds validation diverges across platforms. The PR body says invalid values should "fail before OTP delivery," but the two platforms disagree on what's invalid:

   • iOS rejects 0 — sessionLifetimeSeconds requires parsed > 0 (OmsWalletReactNativeSdkImpl.swift:1146).
   • Android accepts 0 — toLongOrNullParam only rejects negatives, so 0 passes through (OmsWalletReactNativeSdkModule.kt:1057-1061).

   Same input → error on iOS, silent accept on Android. Please align (reject <= 0 on both).

2. Default session lifetime may differ across platforms. iOS hardcodes defaultSessionLifetimeSeconds = 604_800 (swift:15) while Android uses WalletClient.DEFAULT_SESSION_LIFETIME_SECONDS (kt:1061). If the native default isn't also 7 days, the default session length silently differs per-OS. Worth confirming they match (and ideally sourcing iOS from the native constant too, to avoid future drift).

3. Signature verification: Android and iOS pass different args to the native SDK. iOS verifyMessageSignature/verifyTypedDataSignature resolve and pass walletAddress: requireActiveWalletAddress(client) (swift:527,547), and throw if there's no active session. Android calls isValidMessageSignature/isValidTypedDataSignature without a wallet address (kt:533-537,550-554). This is a behavioral difference (which address is being verified against, and whether an active session is required). Please confirm both resolve to the same semantics; if the Kotlin SDK infers the active wallet internally it may be fine, but the asymmetry is worth an explicit check.

Expo dependency policy (per review guidance)

4. examples/expo-example/package.json still pins @0xsequence/oms-react-native-sdk@0.1.0-alpha.4 while the package is now 0.2.0. The policy is to bump the Expo example only after the npm version is published, so keeping alpha.4 is arguably correct for now — but note expo-example:install builds from the local PACKAGE_VERSION (0.2.0) tarball, so local verification uses 0.2.0 while the committed manifest references alpha.4. Confirm this is intentional and that the manifest bump is tracked as a follow-up post-publish.

Nits

• iOS getBalances returns tokenBalancesResultDictionary(_ result: BalancesResult) but Android maps a TokenBalancesResult; naming differs but shapes match — fine, just noting.
• sendTransaction/callContract on iOS coalesce statusPolling ?? TransactionStatusPollingOptions() (default options) when null, whereas Android passes null through to the native SDK (kt:395,432). If the native SDK's own default differs from TransactionStatusPollingOptions(), waited-status polling defaults could differ per-OS when waitForStatus is true and no polling options are given. Low risk but worth a glance.
• No secrets/tokens are logged in either native layer — good. idToken, code, selectionToken, and publishableKey are passed straight through without logging.

Docs & tests

• API.md/README.md/CHANGELOG updates look thorough and match the new OMSWallet/WalletAccount surface. check:api gate in verify is a good addition.
• Test coverage (test/client.native.test.js, public-api-types.ts, api-docs.test.js) covers bridge routing, null-normalization, required indexer fields, and declaration nullability — solid for the JS boundary. Native lifecycle/auth paths still rely on manual verification (documented), which is acceptable given no native test harness.
  • align-oms-wallet-native-sdks