@hawcx/react-native-sdk 1.0.8 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## [1.1.0] - YYYY-MM-DD
+- TODO: add release notes
+
 ## [1.0.8] - 2026-01-21
 - Android biometrics restriction issue fixed
 

package/HawcxReactNative.podspec

@@ -4,10 +4,10 @@ package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
 Pod::Spec.new do |s|
   s.name         = 'HawcxReactNative'
   s.version      = package['version']
-  s.summary      = 'React Native bindings for the Hawcx V5 mobile authentication framework.'
+  s.summary      = 'React Native bindings for the Hawcx mobile authentication SDKs (V5 + V6).'
   s.description  = <<-DESC
     Production-grade React Native bridge that wraps HawcxFramework (iOS) to expose
-    V5 authentication, OTP, push, and web session flows to JavaScript callers.
+    Hawcx V5 and V6 authentication, device trust, push, and web session flows to JavaScript callers.
   DESC
   s.homepage     = 'https://github.com/hawcx/reactnative_sdk'
   s.license      = { :type => 'MIT', :file => 'LICENSE' }

package/README.md

@@ -1,176 +1,394 @@
 # Hawcx React Native SDK
 
-Official React Native bindings for the Hawcx V5 mobile authentication platform. The package wraps the production Hawcx iOS and Android SDKs so you can deliver Smart‑Connect (OTP + device trust + push approvals) inside a single cross‑platform API.
+Official React Native bindings for the Hawcx mobile authentication platform. The package
+wraps the production Hawcx iOS and Android SDKs so you can ship the current V6 adaptive
+flow in a single cross-platform API while keeping existing V5 utilities available during
+migration.
+
+## What This Package Includes
+
+- V6 adaptive authentication via `useHawcxV6Auth`, `startV6Flow`, and `hawcxV6Client`
+- Production native iOS and Android SDK integrations under the hood
+- Redirect, approval polling, and QR approval helpers for V6 flows
+- Existing V5 auth and push/session helpers for apps already in production
 
 ## Requirements
 
-* React Native ≥ 0.73 (Hermes enabled by default)
-* iOS 17+ / Android 8+ (SDK requires API level 26 for Android)
-* OAuth client credentials **must stay on your backend**.
+- React Native 0.73+
+- iOS 17.5+
+- Android API 26+
+- OAuth client credentials kept on your backend
 
 ## Installation
 
+Add the package:
+
 ```bash
-npm install @hawcx/react-native-sdk@1.0.8
-# or yarn add @hawcx/react-native-sdk
+npm install @hawcx/react-native-sdk
 ```
 
+Pin to the released version your team has approved for production.
+
 ### iOS
 
-```
+Install pods after adding the package:
+
+```bash
 cd ios
 pod install
 cd ..
 ```
 
-Open the workspace (`ios/*.xcworkspace`) in Xcode when you need to run on a device. The pod installs the vendored HawcxFramework.xcframework automatically.
+The Podspec vendors `HawcxFramework.xcframework` automatically, so no manual iOS
+framework setup is required.
 
 ### Android
 
-No manual steps are required—Gradle picks up the bundled `hawcx-*.aar`. Make sure the Android SDK is installed and `ANDROID_HOME`/`adb` are on your path, then run `npm run android`. If you upgrade from an older package version, run `cd android && ./gradlew clean` once before rebuilding so React Native re-links the native module.
+The React Native package depends on the released Hawcx Android SDK, so your Android app
+must be able to resolve the Hawcx Maven repository.
+
+Add the repository in `android/settings.gradle`:
+
+```groovy
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+        maven {
+            url = uri("https://raw.githubusercontent.com/hawcx/hawcx_android_sdk/main/maven")
+            metadataSources {
+                mavenPom()
+                artifact()
+            }
+        }
+    }
+}
+```
+
+The hosted Hawcx Maven repository is public. You do not need a GitHub token for the
+standard React Native setup.
 
-## Quick Start
+If your Android project still bundles a local `hawcx-*.aar` or uses `flatDir { dirs("libs") }`,
+remove that and let Gradle resolve the native SDK from Maven.
+
+If Gradle has cached an older dependency graph, run:
+
+```bash
+cd android
+./gradlew clean
+cd ..
+```
+
+## V6 Quick Start
+
+Initialize the SDK once during app bootstrap:
 
 ```tsx
-import { useEffect } from 'react';
-import { initialize, addAuthListener } from '@hawcx/react-native-sdk';
-
-export function bootstrapHawcx() {
-  return initialize({
-    projectApiKey: 'YOUR_PROJECT_API_KEY',
-    baseUrl: 'https://your-hawcx-host.example.com',
-  }).then(() => {
-    const subscription = addAuthListener(event => {
-      if (event.type === 'auth_error') {
-        console.warn('Hawcx error', event.payload);
-      }
-    });
-    return () => subscription.remove();
-  });
+import { initialize } from '@hawcx/react-native-sdk';
+
+await initialize({
+  projectApiKey: '<YOUR_CONFIG_ID>',
+  baseUrl: 'https://stage-api.hawcx.com',
+  autoPollApprovals: true,
+});
+```
+
+### Initialization Notes
+
+- `projectApiKey` is the Hawcx value provisioned for this integration. In current public
+  releases, this is the same value you may receive as your project API key / Config ID.
+- `baseUrl` should point to your Hawcx tenant host root. Do not append `/v1`, `/auth`,
+  or `/hc_auth` yourself.
+- `autoPollApprovals` defaults to `true`, which is the right choice for most apps.
+- `relyingParty` is optional. Set it only when your backend expects the
+  `X-Relying-Party` header for this integration.
+- `oauthConfig` is not required for the recommended V6 flow. Keep OAuth credentials on
+  your backend.
+
+## How V6 Works
+
+1. Initialize the package with your Config ID and tenant host.
+2. Start a flow, usually `signin`, with the user's identifier.
+3. Render the next prompt Hawcx returns.
+4. Send the user's input back to the SDK.
+5. When the flow completes, send the authorization code to your backend.
+6. Let your backend exchange the code and create the app session.
+
+The native SDKs handle protocol requests, PKCE when needed, trusted-device storage,
+device-trust processing, and approval polling.
+
+## Build an Auth Screen
+
+The recommended React Native integration shape is a screen or coordinator that:
+
+1. holds the current `HawcxV6AuthState`
+2. starts the flow
+3. reacts to the current prompt
+4. forwards the user's input back to the SDK
+
+```tsx
+import { useState } from 'react';
+import { Button, Text, TextInput, View } from 'react-native';
+import {
+  useHawcxV6Auth,
+  type HawcxV6Method,
+} from '@hawcx/react-native-sdk';
+
+export function V6AuthScreen() {
+  const [identifier, setIdentifier] = useState('');
+  const [code, setCode] = useState('');
+  const [totp, setTotp] = useState('');
+  const v6 = useHawcxV6Auth(undefined, { flowType: 'signin' });
+
+  const renderPrompt = () => {
+    switch (v6.state.status) {
+      case 'select_method':
+        return v6.state.prompt?.prompt.type === 'select_method'
+          ? v6.state.prompt.prompt.methods.map((method: HawcxV6Method) => (
+              <Button
+                key={method.id}
+                title={method.label}
+                onPress={() => void v6.selectMethod(method.id)}
+              />
+            ))
+          : null;
+
+      case 'enter_code':
+        return (
+          <>
+            <TextInput value={code} onChangeText={setCode} keyboardType="number-pad" />
+            <Button title="Continue" onPress={() => void v6.submitCode(code)} />
+          </>
+        );
+
+      case 'enter_totp':
+        return (
+          <>
+            <TextInput value={totp} onChangeText={setTotp} />
+            <Button title="Continue" onPress={() => void v6.submitTotp(totp)} />
+          </>
+        );
+
+      case 'await_approval':
+        return <Text>Waiting for approval...</Text>;
+
+      case 'redirect':
+        return <Text>Continue in the browser to finish this step.</Text>;
+
+      default:
+        return null;
+    }
+  };
+
+  return (
+    <View>
+      <TextInput value={identifier} onChangeText={setIdentifier} />
+      <Button
+        title="Continue"
+        onPress={() =>
+          void v6.start({
+            flowType: 'signin',
+            identifier: identifier.trim(),
+          })
+        }
+      />
+      {renderPrompt()}
+    </View>
+  );
 }
 ```
 
-Call `bootstrapHawcx()` once when your app starts (e.g., inside your root component or Redux saga). After that you can use hooks or imperative helpers to drive Smart‑Connect.
+### V6 Flow Types
+
+`flowType` supports:
+
+- `signin`
+- `signup`
+- `account_manage`
 
-> **Note:** `baseUrl` must be the tenant-specific Hawcx host (e.g., `https://hawcx-api.hawcx.com`). The native SDK appends `/hc_auth` internally and routes all APIs through that cluster.
+Most apps should start with `signin`.
 
-### Authentication flow (OTP + authorization code)
+## Redirect Handling
 
-The SDK now always returns an authorization code. Your frontend must forward it to your backend, which redeems it with Hawcx using the OAuth client credentials we issued for your project.
+When the current prompt is `redirect`, open the provided URL in the browser and forward
+the return URL back into the SDK:
 
 ```tsx
-import React, { useEffect, useState } from 'react';
-import { useHawcxAuth, storeBackendOAuthTokens } from '@hawcx/react-native-sdk';
+import { useEffect } from 'react';
+import { Linking } from 'react-native';
 
-export function SmartConnectScreen() {
-  const { state, authenticate, submitOtp, reset } = useHawcxAuth();
-  const [email, setEmail] = useState('');
-  const [otp, setOtp] = useState('');
+useEffect(() => {
+  const subscription = Linking.addEventListener('url', ({ url }) => {
+    void v6.handleRedirectUrl(url);
+  });
 
-  useEffect(() => {
-    if (state.status === 'authorization_code') {
-      void exchangeCode(state.payload).finally(() => reset());
-    }
-  }, [state, reset]);
+  return () => subscription.remove();
+}, [v6.handleRedirectUrl]);
+
+const openRedirect = async () => {
+  if (v6.state.prompt?.prompt.type !== 'redirect') {
+    return;
+  }
+
+  await Linking.openURL(v6.state.prompt.prompt.url);
+};
+```
+
+React Native handles the JavaScript callback side, but you still need to register your
+callback scheme natively on iOS and Android so the app receives the return URL.
+
+## Backend Exchange
+
+When the flow completes, the SDK returns:
+
+- `session`
+- `authCode`
+- `expiresAt`
+- `codeVerifier` when PKCE was generated by the SDK
+- `traceId` for support and correlation
+
+For most apps, send `authCode` and `codeVerifier` to your backend immediately over HTTPS
+and perform the exchange there. Keep OAuth client credentials and token verification on
+the server, not in the React Native app.
+
+Recommended payload shape:
+
+```json
+{
+  "authCode": "<authCode>",
+  "codeVerifier": "<optional-codeVerifier>",
+  "identifier": "user@example.com",
+  "session": "<optional-session>"
+}
+```
+
+Your backend should:
+
+1. exchange `authCode` and `codeVerifier` with the Hawcx backend SDK
+2. verify the returned claims
+3. create your app session or tokens
+4. return the app auth result your app needs
+
+### React Native app-to-backend example
+
+```tsx
+import { useEffect } from 'react';
+import {
+  storeBackendOAuthTokens,
+  useHawcxV6Auth,
+} from '@hawcx/react-native-sdk';
+
+useEffect(() => {
+  if (v6.state.status !== 'completed' || !v6.state.completed) {
+    return;
+  }
 
-  const exchangeCode = async ({ code, expiresIn }) => {
-    const response = await fetch('https://your-backend.example.com/api/hawcx/login', {
+  const run = async () => {
+    const response = await fetch('https://your-backend.example.com/api/hawcx/exchange', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ email: email.trim(), code, expires_in: expiresIn }),
+      body: JSON.stringify({
+        authCode: v6.state.completed.authCode,
+        codeVerifier: v6.state.completed.codeVerifier,
+        identifier,
+        session: v6.state.completed.session,
+      }),
     });
+
     if (!response.ok) {
-      throw new Error('Backend verification failed');
+      throw new Error('Backend exchange failed');
+    }
+
+    const result = await response.json();
+
+    if (result.accessToken) {
+      await storeBackendOAuthTokens(
+        identifier,
+        result.accessToken,
+        result.refreshToken,
+      );
     }
-    const { access_token, refresh_token } = await response.json();
-    await storeBackendOAuthTokens(email.trim(), access_token, refresh_token);
   };
 
-  return (
-    <>
-      {/* Collect identifier */}
-      <Button title="Continue" onPress={() => authenticate(email.trim())} />
-
-      {state.status === 'otp' && (
-        <>
-          <TextInput value={otp} onChangeText={setOtp} keyboardType="number-pad" />
-          <Button title="Verify OTP" onPress={() => submitOtp(otp)} />
-        </>
-      )}
-
-      {state.status === 'authorization_code' && <Text>Sending authorization code…</Text>}
-      {state.status === 'additional_verification_required' && (
-        <Text>Additional verification required: {state.payload.detail ?? state.payload.sessionId}</Text>
-      )}
-      {state.status === 'error' && <Text>{state.error.message}</Text>}
-    </>
-  );
-}
+  void run();
+}, [identifier, v6.state]);
 ```
 
-### Backend exchange
+`storeBackendOAuthTokens` is optional for the core V6 flow. Use it when your backend
+returns tokens that the shared native session and push helpers should persist.
 
-Redeem the authorization code on your server using the hawcx/oauth-client package or your preferred language SDK. Never ship `clientId`, token endpoint, private keys, or Hawcx public keys inside your mobile app.
+For backend implementation details, see:
 
-```ts
-import express from 'express';
-import { exchangeCodeForTokenAndClaims } from '@hawcx/oauth-client';
+- [Node.js backend quickstart](https://docs.hawcx.com/docs/v1/sdk-reference/backend/nodejs/quickstart)
+- [Python backend quickstart](https://docs.hawcx.com/docs/v1/sdk-reference/backend/python/quickstart)
 
-const app = express();
-app.use(express.json());
+## QR Approvals and Web Login Helpers
 
-app.post('/api/hawcx/login', async (req, res) => {
-  const { email, code, expires_in } = req.body ?? {};
-  if (!email || !code) {
-    return res.status(400).json({ success: false, error: 'Missing email or code' });
-  }
+The package also exposes helpers for QR approval and legacy web-login scans:
 
-  try {
-    const [claims, idToken] = await exchangeCodeForTokenAndClaims({
-      code,
-      oauthTokenUrl: process.env.HAWCX_OAUTH_TOKEN_ENDPOINT!,
-      clientId: process.env.HAWCX_OAUTH_CLIENT_ID!,
-      publicKey: process.env.HAWCX_OAUTH_PUBLIC_KEY_PEM!,
-      audience: process.env.HAWCX_OAUTH_CLIENT_ID,
-      issuer: process.env.HAWCX_OAUTH_ISSUER,
-    });
+- `routeWebLoginScan(raw)`
+- `approveV6Qr(rawPayload, identifier, options)`
+- `useHawcxWebLogin()`
 
-    return res.json({
-      success: true,
-      message: `Verified ${claims.email}`,
-      access_token: idToken,
-      refresh_token: idToken,
-    });
-  } catch (error) {
-    return res.status(401).json({ success: false, error: error.message });
-  }
-});
+For protocol QR payloads, you can approve directly from React Native:
+
+```tsx
+import { approveV6Qr, routeWebLoginScan } from '@hawcx/react-native-sdk';
+
+const route = routeWebLoginScan(scanValue);
+if (route.kind === 'protocol_qr') {
+  const result = await approveV6Qr(route.payload.raw, identifier, {
+    rememberDevice: true,
+  });
+
+  console.log(result.outcome, result.payloadType);
+}
 ```
 
-Once the backend responds, call `storeBackendOAuthTokens(userId, tokens)` so the Hawcx SDK saves them securely and can continue handling push registration and device sessions.
+## Existing V5 and Shared Helpers
+
+The package still includes the older V5 auth surface for apps that already use it,
+including:
 
-## Hooks & Helpers
+- `authenticate`, `submitOtp`, `useHawcxAuth`
+- `useHawcxWebLogin`
+- `setPushDeviceToken`
+- `notifyUserAuthenticated`
+- `handlePushNotification`, `approvePushRequest`, `declinePushRequest`
 
-* `useHawcxAuth()` – React hook that exposes the current auth state and helpers (`authenticate`, `submitOtp`, `reset`).
-* `useHawcxWebLogin()` – Drive QR/PIN based approvals.
-* `addAuthListener` / `addSessionListener` / `addPushListener` – Lower-level event APIs if you prefer an imperative approach.
-* `setPushDeviceToken` / `notifyUserAuthenticated` – Wire push login approvals.
+Shared helpers such as `initialize` and `storeBackendOAuthTokens` remain available across
+the current package surface.
 
-Refer to the updated [React Quickstart documentation](https://docs.hawcx.com/react/quickstart) for details on each API, push approvals, and device session management.
+That makes incremental migration possible: new V6 flows can live on
+`useHawcxV6Auth` while existing utilities remain available in the same package.
 
 ## Example App
 
-`/example` contains a full React Native app wired to the SDK with logging, OTP UI, push harness, and a backend toggle. To run it:
+The `example/` directory contains the in-repo React Native reference app used during SDK
+development:
 
 ```bash
 cd example
 npm install
-npm run ios   # or npm run android
+npm run ios
+# or
+npm run android
 ```
 
-Add your Project API key in `example/src/hawcx.config.ts` or paste it into the in-app form. The **Authorization Code & Backend Exchange** card runs in demo mode by default (codes complete locally). Set `BACKEND_FLOW_ENABLED = true` in `example/src/App.tsx` when you have a tunnel or backend ready to receive `{ code, email, expires_in }`.
+Use it to validate V6 auth flows against your environment before integrating into your
+own app.
+
+## Documentation
+
+- [V6 React Native guide](https://docs.hawcx.com/docs/v1/sdk-reference/frontend/react-native/sdk-v6)
+- [V5 React Native guide](https://docs.hawcx.com/docs/v1/sdk-reference/frontend/react-native/sdk)
+- [V6 iOS guide](https://docs.hawcx.com/docs/v1/sdk-reference/frontend/ios/sdk-v6)
+- [V6 Android guide](https://docs.hawcx.com/docs/v1/sdk-reference/frontend/android/sdk-v6)
+- [Node.js backend quickstart](https://docs.hawcx.com/docs/v1/sdk-reference/backend/nodejs/quickstart)
+- [Python backend quickstart](https://docs.hawcx.com/docs/v1/sdk-reference/backend/python/quickstart)
+- [Documentation home](https://docs.hawcx.com)
 
 ## Support
 
-* Documentation: [React Quickstart](https://docs.hawcx.com/react/quickstart)
-* Questions? Reach out to your Hawcx solutions engineer or info@hawcx.com.
+- [Website](https://www.hawcx.com)
+- [Support Email](mailto:info@hawcx.com)

package/android/build.gradle

@@ -22,7 +22,7 @@ def safeExtGet(prop, fallback) {
 }
 
 group = 'com.hawcx.reactnative'
-version = project.findProperty('HAWCX_REACT_NATIVE_ANDROID_VERSION') ?: '1.0.8'
+version = project.findProperty('HAWCX_REACT_NATIVE_ANDROID_VERSION') ?: '1.1.0'
 
 repositories {
     mavenCentral()
@@ -124,7 +124,7 @@ afterEvaluate {
 }
 
 dependencies {
-    api("api.hawcx:hawcx:5.1.4")
+    api("api.hawcx:hawcx:6.0.2")
     def reactNativeVersion = safeExtGet('reactNativeAndroidVersion', '0.73.9')
     implementation "com.facebook.react:react-android:$reactNativeVersion"
     implementation 'androidx.annotation:annotation:1.8.1'

package/android/src/main/java/com/hawcx/reactnative/HawcxEventDispatcher.kt

@@ -21,6 +21,10 @@ internal class HawcxEventDispatcher(
         emitEvent(PUSH_EVENT_NAME, type, payload)
     }
 
+    fun emitV6FlowEvent(type: String, payload: WritableMap? = null) {
+        emitEvent(V6_FLOW_EVENT_NAME, type, payload)
+    }
+
     private fun emitEvent(eventName: String, type: String, payload: WritableMap?) {
         val map = Arguments.createMap().apply {
             putString("type", type)