@hawcx/react-native-sdk 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.0.3] - YYYY-MM-DD
+- TODO: add release notes
+
+## [1.0.2] - YYYY-MM-DD
+- OAuth flow update
+- Android release prep
+
 ## [1.0.1] - 2025-11-17
 - Point native Android/iOS SDKs at new production authentication endpoint
 - Refresh bundled Hawcx Android/iOS binaries for the 1.0.1 cut
@@ -7,4 +14,4 @@
 
 ## [0.0.1] - 2025-11-15
 - Initial React Native bridge for Hawcx V5 authentication
-- Added HawcxClient helpers, hooks, push support, and example app
+- Added HawcxClient helpers, hooks, push support, and example app

package/HawcxReactNative.podspec

@@ -9,10 +9,10 @@ Pod::Spec.new do |s|
     Production-grade React Native bridge that wraps HawcxFramework (iOS) to expose
     V5 authentication, OTP, push, and web session flows to JavaScript callers.
   DESC
-  s.homepage     = 'https://github.com/hawcx/react-native-sdk'
+  s.homepage     = 'https://github.com/hawcx/reactnative_sdk'
   s.license      = { :type => 'MIT', :file => 'LICENSE' }
   s.author       = { 'Hawcx Engineering' => 'engineering@hawcx.com' }
-  s.source       = { :git => 'https://github.com/hawcx/react-native-sdk.git', :tag => "v#{s.version}" }
+  s.source       = { :git => 'https://github.com/hawcx/reactnative_sdk.git', :tag => "v#{s.version}" }
 
   s.platform     = :ios, '17.5'
   s.swift_version = '5.9'

package/LICENSE

@@ -1,21 +1,54 @@
-MIT License
+Hawcx Proprietary License
 
-Copyright (c) 2025 Hawcx
+Copyright (c) 2025 Hawcx, Inc. All Rights Reserved.
 
-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:
+GRANT OF LICENSE
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+Subject to the terms and conditions of this License, Hawcx, Inc. ("Hawcx") 
+grants to authorized clients ("Licensee") a limited, non-exclusive, 
+non-transferable, non-sublicensable license to use this software and 
+associated documentation files (the "Software") solely for:
+
+1. Proof of Concept (POC) evaluation purposes, or
+2. Commercial use in production environments as explicitly authorized by Hawcx
+
+RESTRICTIONS
+
+Licensee shall NOT:
+- Modify, alter, or create derivative works of the Software
+- Distribute, sublicense, lease, rent, or transfer the Software to any third party
+- Reverse engineer, decompile, or disassemble the Software
+- Remove or alter any proprietary notices, labels, or marks on the Software
+- Use the Software for any purpose other than as expressly authorized
+
+AUTHORIZATION REQUIRED
+
+Use of this Software requires explicit written authorization from Hawcx. 
+Unauthorized use, reproduction, or distribution is strictly prohibited and 
+may result in severe civil and criminal penalties.
+
+OWNERSHIP
+
+Hawcx retains all right, title, and interest in and to the Software, 
+including all intellectual property rights. This License does not grant 
+Licensee any ownership rights to the Software.
+
+TERMINATION
+
+This License is effective until terminated. Hawcx may terminate this License 
+immediately if Licensee fails to comply with any term hereof. Upon termination, 
+Licensee must destroy all copies of the Software.
+
+WARRANTY DISCLAIMER
 
 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.
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL HAWCX 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.
+
+For licensing inquiries, contact: info@hawcx.com

package/README.md

@@ -1,109 +1,176 @@
-# Hawcx React Native SDK (iOS)
+# Hawcx React Native SDK
 
-This package provides the React Native wrapper for the Hawcx V5 mobile authentication framework. It reuses the production iOS implementation (`dev_ios/ios_sdk/HawcxFramework`) and exposes a typed JavaScript/TypeScript API for React Native applications.
+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.
 
-## Repository Layout
-- `src/` – TypeScript entry point and public API surface.
-- `ios/` – Native bridge sources (Swift) plus the Podspec that embeds `HawcxFramework`.
-- `android/` – React Native Android bridge module (Gradle library) plus the bundled Hawcx SDK AAR.
-- `example/` – Runnable React Native demo app using the SDK (`npm install` -> `npm run ios`).
-- `react_mobile_sdk_plan.md` – Detailed delivery plan and progress tracker. **Always read and update this file when working on the SDK.**
+## Requirements
 
-## Scripts
-| Command | Description |
-| --- | --- |
-| `npm run clean` | Removes the build output under `lib/`. |
-| `npm run lint` | Runs ESLint using the React Native + TypeScript rules. |
-| `npm run typecheck` | Executes the TypeScript compiler in `--noEmit` mode. |
-| `npm run build` | Builds distributable bundles via `react-native-builder-bob`. |
+* 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**.
 
-> Note: Dependencies are declared in `package.json` but not yet installed. Install them once local tooling is in place (`npm install`).
+## Installation
 
-## Android Module (WIP)
-- `android/` hosts the Gradle-based library that React Native autolinks for Android builds. It already references the Hawcx Android SDK via `android/libs/hawcx-5.1.0.aar` and exposes `./gradlew` helpers for linting/publishing.
-- Run Gradle tasks from the repo root with `./gradlew -p android <task>` (for example, `./gradlew -p android :hawcxreactnative:lintRelease`). The first invocation requires network/Gradle cache access for AGP + React Native dependencies.
-- The bridge mirrors the iOS surface: `initialize`, `authenticate`, OTP/session helpers, push lifecycle (`setApnsDeviceToken` on iOS, `setFcmToken` on Android), and emits the same `hawcx.*` events for auth/session/push updates.
-- Android builds require `android/local.properties` pointing at your Android SDK (`sdk.dir=/Users/<you>/Library/Android/sdk`) and target `minSdkVersion` 26 to match the Hawcx AAR.
+```bash
+npm install @hawcx/react-native-sdk
+# or yarn add @hawcx/react-native-sdk
+```
+
+### iOS
+
+```
+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.
+
+### 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`.
+
+## Quick Start
+
+```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();
+  });
+}
+```
 
-### Refreshing the Hawcx Android SDK AAR
-1. Build the native Android SDK (`cd ~/dev_android/android_sdk && ./gradlew :app:assembleRelease`).
-2. Copy the generated `app/build/outputs/aar/hawcx-<version>.aar` into `android/libs/`, replacing the existing binary.
-3. Update any documentation or release notes (e.g., `react_mobile_sdk_plan.md`, `CHANGELOG.md`) to reflect the new Hawcx SDK version.
+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.
+
+> **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.
+
+### Authentication flow (OTP + authorization code)
+
+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.
+
+```tsx
+import React, { useEffect, useState } from 'react';
+import { useHawcxAuth, storeBackendOAuthTokens } from '@hawcx/react-native-sdk';
+
+export function SmartConnectScreen() {
+  const { state, authenticate, submitOtp, reset } = useHawcxAuth();
+  const [email, setEmail] = useState('');
+  const [otp, setOtp] = useState('');
+
+  useEffect(() => {
+    if (state.status === 'authorization_code') {
+      void exchangeCode(state.payload).finally(() => reset());
+    }
+  }, [state, reset]);
+
+  const exchangeCode = async ({ code, expiresIn }) => {
+    const response = await fetch('https://your-backend.example.com/api/hawcx/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: email.trim(), code, expires_in: expiresIn }),
+    });
+    if (!response.ok) {
+      throw new Error('Backend verification failed');
+    }
+    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>}
+    </>
+  );
+}
+```
 
-## Usage (WIP)
+### Backend exchange
+
+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.
 
 ```ts
-import {
-  initialize,
-  authenticate,
-  submitOtp,
-  addAuthListener,
-  hawcxClient,
-  useHawcxAuth,
-  useHawcxWebLogin,
-} from '@hawcx/react-native-sdk';
-
-await initialize({ projectApiKey: 'YOUR_PROJECT_KEY' });
-
-const subscription = addAuthListener(event => {
-  switch (event.type) {
-    case 'otp_required':
-      // show OTP UI
-      break;
-    case 'auth_success':
-      console.log('Login success', event.payload);
-      break;
-    case 'auth_error':
-      console.error('Auth failed', event.payload.message);
-      break;
-  }
-});
+import express from 'express';
+import { exchangeCodeForTokenAndClaims } from '@hawcx/oauth-client';
 
-await authenticate('user@example.com');
-await submitOtp('123456');
+const app = express();
+app.use(express.json());
 
-subscription.remove();
+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' });
+  }
 
-// HawcxClient helper
-const { promise } = hawcxClient.authenticate('user@example.com', {
-  onOtpRequired: () => console.log('show OTP UI'),
+  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,
+    });
+
+    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 });
+  }
 });
-const result = await promise; // -> { accessToken?, refreshToken?, isLoginFlow }
+```
 
-// React hook example
-function AuthScreen() {
-  const { state, authenticate, submitOtp } = useHawcxAuth();
+Once the backend responds, call `storeBackendOAuthTokens(userId, tokens)` so the Hawcx SDK saves them securely and can continue handling push registration and device sessions.
 
-  const start = () => authenticate('user@example.com');
-  const sendOtp = (otp: string) => submitOtp(otp);
+## Hooks & Helpers
 
-  return null;
-}
+* `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.
 
-function WebLoginScreen() {
-  const { state, webLogin, webApprove, getDeviceDetails } = useHawcxWebLogin();
+Refer to the updated [React Quickstart documentation](https://docs.hawcx.com/react/quickstart) for details on each API, push approvals, and device session management.
 
-  const validatePin = (pin: string) => webLogin(pin);
-  const approveSession = (token: string) => webApprove(token);
-  const refreshDevices = () => getDeviceDetails();
+## Example App
 
-  return null;
-}
+`/example` contains a full React Native app wired to the SDK with logging, OTP UI, push harness, and a backend toggle. To run it:
+
+```bash
+cd example
+npm install
+npm run ios   # or npm run android
 ```
 
-## Example App & E2E
-- `cd example && npm install` to bootstrap the sample app.
-- Edit `example/src/hawcx.config.ts` with your project API key plus the OAuth client ID, token endpoint, and PEM from `dev_ios/ios_demo_dev`, then run `npm run ios` or `npm run android`.
-- Use `example/e2e/hawcx-login.yaml` with [Maestro](https://maestro.mobile.dev/) to drive a smoke test through OTP login. Adjust selectors to match your bundle ID and UI tweaks.
-
-## Release Process
-Review `docs/RELEASE.md` before publishing. In short:
-1. Run `npm run lint && npm run typecheck && npm test && npm run build`.
-2. Update `package.json` + `CHANGELOG.md`.
-3. Smoke test the example app.
-4. `npm publish --access public` and `pod repo push trunk HawcxReactNative.podspec`.
-5. Tag the repo (`git tag vX.Y.Z && git push origin --tags`).
-
-## Next Steps
-1. Follow `react_mobile_sdk_plan.md` Phase 1+ to implement the native bridge and JS API.
-2. Keep this README updated with integration steps and release instructions as the SDK matures.
+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 }`.
+
+## Support
+
+* Documentation: [React Quickstart](https://docs.hawcx.com/react/quickstart)
+* Questions? Reach out to your Hawcx solutions engineer or info@hawcx.com.

package/docs/RELEASE.md

@@ -36,11 +36,13 @@ This document outlines every command, directory, and deliverable required to pub
    npm test
    npm run build      # produces lib/
    ./gradlew -p android clean lintRelease testReleaseUnitTest assembleRelease publishToMavenLocal
+   Ensure to udpate api("api.hawcx:hawcx:5.1.1") version in dev_react/android/build.gradle if android aar file version changed
+   Then run ./gradlew clean assembleRelease --refresh-dependencies to test if android picks up new aar maven release
    pod lib lint HawcxReactNative.podspec
    ```
    - `./gradlew … publishToMavenLocal` validates the Android bridge (with the bundled Hawcx AAR) builds and can be published.
    - `pod lib lint` confirms the Podspec + `HawcxFramework.xcframework` remain valid.
-
+   
 3. **Update version + changelog (repo root)**
    - Edit `package.json` → bump `version` (run `npm install` afterward so `package-lock.json` picks up the new number).
    - Update `android/build.gradle`’s fallback `version` string and `example/package.json` (re-run `npm install` inside `example/` so its lockfile updates).
@@ -50,14 +52,23 @@ This document outlines every command, directory, and deliverable required to pub
      ```bash
     git add package.json package-lock.json android/build.gradle example/package.json example/package-lock.json example/ios/Podfile.lock CHANGELOG.md
     git commit -m "chore: release vX.Y.Z"
-     ```
+    ```
     Include refreshed native artifacts (`ios/Frameworks/*.xcframework`, `android/libs/*.aar`) in the same commit when they change.
 
 4. **Smoke test the example app**
+
+   rm -rf ~/Library/Developer/Xcode/DerivedData/HawcxExampleApp*
+
    ```bash
    cd example
    npm install
-   npm run ios
+   For ios:
+   cd example/ios: pod install
+   cd .. 
+   npm run ios or npm run ios -- --no-packager
+   For android: 
+   cd example/android: ./gradlew clean
+   cd ..
    npm run android
    # Use your dev credentials in example/src/hawcx.config.ts
    cd ..
@@ -73,7 +84,7 @@ This document outlines every command, directory, and deliverable required to pub
 
 6. **Publish CocoaPods spec (repo root)**
    ```bash
-   pod repo push trunk HawcxReactNative.podspec --allow-warnings
+   pod trunk push HawcxReactNative.podspec --allow-warnings
    ```
    Ensure the command finishes without validation errors. If you have trouble with trunk authentication, re-run `pod trunk register`.
 

package/example/README.md

@@ -9,7 +9,7 @@ This example demonstrates the cross-platform APIs exported by `@hawcx/react-nati
    cd example
    npm install
    ```
-2. Configure credentials in `src/hawcx.config.ts`. The file ships with dev defaults—replace the API key and OAuth values with your own.
+2. Configure credentials in `src/hawcx.config.ts`. The file ships with dev defaults—replace the API key **and** `HAWCX_BASE_URL` host with your tenant’s values.
 3. **iOS only:** install pods:
    ```bash
    cd ios && pod install && cd ..

package/example/android/build.gradle

@@ -21,3 +21,15 @@ buildscript {
 }
 
 apply plugin: "com.facebook.react.rootproject"
+
+subprojects { subproject ->
+    subproject.configurations.all { config ->
+        config.resolutionStrategy.eachDependency { details ->
+            if (details.requested.group == "androidx.core" &&
+                (details.requested.name == "core" || details.requested.name == "core-ktx")) {
+                details.useVersion("1.13.1")
+                details.because("core-ktx 1.16.0 requires compileSdk/AGP 35+, but the demo targets 34/AGP 8.1.1")
+            }
+        }
+    }
+}

package/example/android/settings.gradle

@@ -1,3 +1,37 @@
+import org.gradle.api.initialization.resolve.RepositoriesMode
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
+    repositories {
+        google()
+        mavenCentral()
+        maven { url = uri("https://www.jitpack.io") }
+        maven {
+            url = uri("https://raw.githubusercontent.com/hawcx/hawcx_android_sdk/main/maven")
+            content {
+                includeGroup("api.hawcx")
+            }
+            metadataSources {
+                mavenPom()
+                artifact()
+            }
+        }
+        def localHawcxRepo = new File(rootDir, "../../../prod_android/hawcx_android_sdk/maven")
+        if (localHawcxRepo.exists()) {
+            maven {
+                url = localHawcxRepo.toURI()
+                content {
+                    includeGroup("api.hawcx")
+                }
+                metadataSources {
+                    mavenPom()
+                    artifact()
+                }
+            }
+        }
+    }
+}
+
 rootProject.name = 'com.hawcx.example'
 apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings)
 include ':app'