@hawcx/react-native-sdk 1.0.1

package/react_mobile_sdk_plan.md

@@ -0,0 +1,240 @@
+# Hawcx React Mobile SDK Delivery Plan
+
+## How to Use This Document
+- Read this file end-to-end before touching code. It establishes context from `hawcx_core_auth` and `dev_ios/ios_sdk` that must be mirrored exactly.
+- Every time you finish a task (or discover new work), update the **Progress Tracker** section with your initials, date, and notes so the next engineer knows where to resume.
+- Keep this document as the single source of truth. If you add architectural decisions, reference code paths and link PRs.
+
+## System Context
+### Backend (hawcx_core_auth)
+- V5 API endpoints live in `app/api/v5/endpoints.py` backed by `DeviceVerificationSystem`, Redis, and `DomainService` (`app/shared/domain_service.py`).
+- Device lifecycle:
+  1. `POST /hc_auth/v5/auth-init` → determines login vs registration via `hindex`.
+  2. `POST /hc_auth/v5/verify-otp` → completes registration with `keyset` + `H(I)`.
+  3. `POST /hc_auth/v5/verify-device` → persists salts, combined key blobs, and device fingerprint.
+  4. `POST /hc_auth/v5/verify-cipher` → login challenge signed with Ed25519 private key stored on device.
+- Device info schema (`app/api/v5/v5_dependencies/models/fingerprint.py`) expects the client to send fingerprints already computed on-device. Keep React SDK aligned.
+- QR/web session, push, and admin utilities share the same project/domain enforcement.
+
+### Native iOS SDK Baseline (dev_ios/ios_sdk)
+- `HawcxFramework` encapsulates all V5 crypto (see `internal/V5Crypto.swift`, `internal/V5CredentialStore.swift`, `auth/HawcxAuthV5.swift`). Secure Enclave + HKDF salt handling is already production-ready.
+- `HawcxSDK` (in `internal/HawcxSDK.swift`) exposes `authenticateV5`, `submitOtpV5`, session helpers, push registration, and web login utilities.
+- Demo app (`dev_ios/ios_sdk/../ios_demo_dev/HawcxDemoApp`) shows end-to-end UX and state transitions.
+- The React Native SDK MUST wrap this existing Swift implementation—do **not** rewrite crypto or network flows in JavaScript.
+
+### Native Android SDK Baseline (dev_android/android_sdk)
+- Kotlin sources under `app/src/main/Kotlin/com/hawcx` mirror the Swift modules and already implement V5.1. `internal/HawcxSDK.kt` wires `HawcxAuthV5`, `DevSession`, `WebLoginManager`, `KeystoreManager`, and `HawcxPushAuthDelegate` so the facade matches iOS.
+- `auth/HawcxAuthV5.kt`, `v5/V5CredentialStore.kt`, `v5/V5Crypto.kt`, `storage/KeystoreManager.kt`, and `utils/FingerprintGenerator.kt` cover HKDF salts, Ed25519 keypairs, AES-GCM secrets, and Android Keystore usage.
+- OAuth + network helpers live in `internal/HawcxOAuthConfig.kt`, `internal/OAuthTokenVerifier.kt`, and `network/ApiService.kt`, pointing at the same `/hc_auth/v5/oauth/token` + `EndPoints` constants as iOS.
+- Device/session utilities (`auth/WebLoginManager.kt`, `auth/DevSession.kt`, `utils/DeviceDetailsUtil.kt`) emit the same JSON schema that `hawcx_core_auth` expects, and push logic (`utils/HawcxPushAuthDelegate.kt`) drives `setFcmToken`, `handlePushNotification`, and approve/decline helpers.
+- `app/build.gradle` already packages the SDK as an AAR for the Compose demo. The React Native module should consume that binary (or a git submodule) instead of re-implementing anything in JS.
+
+### Android Demo App Baseline (dev_android/HawcxAndroidDemoApp/HawcxDemoApp)
+- Jetpack Compose UI demonstrates every V5 flow. `MainApplication.kt` instantiates `HawcxSDK`, configures OAuth, wires Firebase, and registers the push delegate.
+- View models under `app/src/main/java/com/hawcx/android/demoapp/viewmodel/` (`AuthenticateViewModel.kt`, `WebLoginViewModel.kt`, `SharedAuthManager.kt`, etc.) show how callbacks drive UX states identical to SwiftUI.
+- `messaging/DemoFirebaseMessagingService.kt` feeds FCM payloads into `hawcxSDK.handlePushNotification()` and raises approve/decline actions through `AppViewModel`.
+- `ui/` and `util/Constants.kt` document theme switching, device details cards, and the required configuration (API key, OAuth endpoints, `google-services.json`).
+- Treat this app as the Android source of truth when reproducing flows inside the React Native example and when validating push/web-session parity.
+
+## Goals & Non-Goals
+1. Keep the shipping iOS React Native bridge stable while extending the same Hawcx V5 feature set to Android by delegating directly to `dev_ios/ios_sdk/HawcxFramework` and `dev_android/android_sdk/app/src/main/Kotlin/com/hawcx/internal/HawcxSDK.kt`.
+2. Provide one TypeScript API (hooks, events, session + push helpers) that transparently drives both platforms and emits identical payloads/error codes for auth, OTP, device management, push approvals, and web login.
+3. Deliver an RN example application plus QA harness that runs end-to-end on simulators/emulators so customers can validate both platforms with minimal setup.
+4. Non-goals: rewriting crypto/network logic in JavaScript, deviating from backend lifecycles, or adding Android-only V4 bindings unless product explicitly asks for legacy support.
+
+## Guiding Principles
+- **Parity with Native SDKs**: All flows must call into `HawcxAuthV5`, `V5CredentialStore`, `ApiService`, `DevSession`, etc., on both Swift and Kotlin. Use bridging—no duplicated crypto logic.
+- **Cross-Platform Contract**: Event names (`hawcx.auth.event`, `hawcx.session.event`, `hawcx.push.event`) and payload shapes stay identical so TS hooks remain platform-agnostic. Any change must be reflected on iOS + Android simultaneously.
+- **Single Source Config**: Accept `projectApiKey`, optional OAuth config, and environment overrides identical to `ApiService` usage.
+- **Safety First**: Never expose private key material or salts to JS. Keep secrets on native side; JS receives only tokens/errors.
+- **Traceability**: Reference source files (e.g., `dev_ios/ios_sdk/HawcxFramework/auth/HawcxAuthV5.swift`, `dev_android/android_sdk/app/src/main/Kotlin/com/hawcx/auth/HawcxAuthV5.kt`) whenever you mirror behavior.
+- **Progress Discipline**: Update the tracker after each deliverable (even partial) so management can slot another engineer instantly.
+
+## High-Level Architecture
+1. **React Native Modules (iOS + Android)**
+   - iOS: `ios/HawcxReactNative.swift` (RCTEventEmitter subclass) maintains a singleton `HawcxSDK`, configures OAuth, and exposes bridging methods.
+   - Android: `android/src/main/java/com/hawcx/reactnative/HawcxReactNativeModule.kt` + `HawcxReactNativePackage.kt` will mirror the Swift API, hold a singleton `HawcxSDK`, and parse config maps.
+2. **Event Emitters**
+   - iOS already emits `hawcx.auth.event`, `hawcx.session.event`, `hawcx.push.event`.
+   - Android must use `DeviceEventManagerModule.RCTDeviceEventEmitter` to fire the exact same event names/payload schemas from `AuthV5Callback`, `DevSession.DevSessionCallback`, and `HawcxPushAuthDelegate`.
+3. **TypeScript API Layer** (`src/index.ts`)
+   - Provides typed methods (`authenticate`, `submitOtp`, `webLogin`, `webApprove`, `setApnsDeviceToken`/`setFcmToken`, `handlePushNotification`, etc.).
+   - Wraps native calls in promises + hooks so consuming apps stay identical regardless of platform, but enforces platform guards where necessary (e.g., APNs vs FCM tokens).
+4. **Distribution**
+   - npm package `@hawcx/react-native-sdk` ships `ios/` + `android/`. iOS uses `HawcxReactNative.podspec` to pull `HawcxFramework.xcframework`; Android ships Gradle config referencing the Hawcx Android AAR (`dev_android/android_sdk`) or Maven artifact and applies `maven-publish` for validation.
+5. **Example App**
+   - `example/` demonstrates the JS API on both platforms, mirroring the native demos for OTP, push approvals, biometrics, and web login. Maintains documentation for dev credentials (`hawcx.config.ts`, `google-services.json`).
+
+## Detailed Implementation Plan
+_Phases 0–6 capture the completed iOS scope and remain here for historical context. Keep them green while layering the Android workstreams described later in this section._
+### Phase 0 – Repo Bootstrap
+- Initialize monorepo structure inside `dev_react` (`package.json`, `tsconfig`, `babel.config`, RN scaffolding, Podspec referencing `HawcxFramework`).
+- Add linting (`eslint`, `prettier`) and SwiftLint; configure GitHub Actions skeleton.
+- Document environment setup (Xcode, CocoaPods, Node version) in this file.
+
+### Phase 1 – Native Bridge Skeleton
+- Create `HawcxReactNative` module exposing `initialize`, `authenticateV5`, `submitOtpV5`, `clearSession`, `getLastLoggedInUser` by delegating to `HawcxSDK`.
+- Implement `AuthV5Callback` bridging: translate `onOtpRequired`, `onAuthSuccess`, `onError` to RN events.
+- Ensure `isLoginFlow`, `accessToken`, `refreshToken`, and `AuthV5ErrorCode` are included in event payloads.
+
+### Phase 2 – TypeScript Surface & State Helpers
+- Implement `src/HawcxClient.ts` with:
+  - `initialize(config: HawcxConfig)`
+  - `authenticate(userId: string, options?: AuthOptions)` returning `{ promise, cancel }` + event channel
+  - `submitOtp(otp: string)`
+  - Session helpers (`getLastLoggedInUser`, `clearSessionTokens`, `clearDeviceData`).
+- Provide `AuthEvent` typings and optionally `useHawcxAuth` React hook to simplify OTP UI.
+
+### Phase 3 – Session, Web, and Admin Utilities
+- Bridge `devSessionManager` methods for device listing and token cleanup.
+- Expose `webLogin(pin)` / `webApprove(token)` hooking into backend `/websession-*` endpoints via `HawcxSDK`.
+- Document Domain/RP expectations from backend `DomainService` and how project IDs map to React clients.
+
+### Phase 4 – Push Notification Support
+- Wrap `setAPNsDeviceToken`, `handlePushNotification`, `approveLoginRequest`, `declineLoginRequest`.
+- Provide JS helpers for registering APNs token post-auth and handling push payloads.
+- Update example app to demonstrate receiving a login approval request.
+
+### Phase 5 – Example App & QA Harness
+- Build RN example mirroring `ios_demo_dev` flows (email input, OTP modal, success screen, push + web login tabs).
+- Write integration script to run on a simulator hitting `https://dev-api.hawcx.com` (registration + login scenario).
+- Add Detox/Maestro scenarios for OTP happy path and failure to ensure regressions are caught.
+
+### Phase 6 – Documentation & Release Prep
+- Generate API reference (typedoc or hand-written Markdown) and copy relevant sections into `docs/`.
+- Describe environment configuration, initialization snippet, error codes, troubleshooting, and migration guidance.
+- Finalize podspec, `package.json` metadata, semantic versioning, changelog, and publish instructions.
+
+### Android React Native Enablement (New Work)
+#### Phase A – Android module bootstrap & dependency wiring
+- Create the `android/` library (Gradle wrapper, `build.gradle`, `gradle.properties`, manifest, and `src/main/java/com/hawcx/reactnative/`). Mirror the `react-native-builder-bob` template so autolinking works out of the box.
+- Bring in the Android SDK artifact: either copy `dev_android/android_sdk/app/build/outputs/aar/hawcx-release.aar` into `android/libs/` or wire a git submodule. Document how to refresh this artifact whenever the native team bumps versions.
+- Configure AGP (minSdk 23+, target 34), Kotlin 1.9+, `compileOptions` for Java 17, and add dependencies on `com.facebook.react:react-native` + the Hawcx AAR.
+- Add `maven-publish` + `sourcesJar` so CI can run `./gradlew -p android assembleRelease lintRelease publishToMavenLocal` for validation before npm publish.
+
+#### Phase B – Kotlin native module + config bridge
+- Implement `HawcxReactNativeModule` (extends `ReactContextBaseJavaModule` + `LifecycleEventListener`) and `HawcxReactNativePackage`.
+- Store a singleton `HawcxSDK` bound to `reactApplicationContext.applicationContext`, mirroring Swift’s lifecycle.
+- Parse the JS config (`projectApiKey`, `oauthConfig`, future endpoint overrides) into `HawcxOAuthConfig`. Reject invalid payloads with the same error codes as iOS (`hawcx.config`, `hawcx.sdk`, `hawcx.input`).
+- Expose `initialize`, `authenticate(userid)`, `submitOtp(otp)`, `getLastLoggedInUser()`, `clearSessionTokens(forUser)`, and `clearUserKeychainData(forUser)` as Promise-returning methods.
+- Provide placeholder callback proxies (`AuthCallbackProxy`) that currently log events; Phase C will replace the internals with actual RN event emission while keeping Phase B green.
+
+#### Phase C – Auth/session events & data mapping
+- Create Kotlin proxies implementing `AuthV5Callback`, `DevSession.DevSessionCallback`, and `WebLoginManager.WebLoginCallback`. Convert models (`AuthSuccessPayload`, `DeviceDetails`, error codes) into `WritableMap` objects using the same keys/payloads as the Swift emitter.
+- Use `DeviceEventManagerModule.RCTDeviceEventEmitter` to emit `hawcx.auth.event`, `hawcx.session.event`, `hawcx.push.event`. Guarantee events serialize on the UI thread to avoid race conditions.
+- Bridge session helpers (`getDeviceDetails`, `getStoredDeviceDetails`, `webLogin`, `webApprove`) with Promise completion so JS callers can show loaders identical to iOS.
+- Build exhaustive error translation (map each `AuthV5ErrorCode` + exception to the shared `HawcxAuthError` payload) and add Robolectric tests that assert the payload structure.
+
+#### Phase D – Push + device lifecycle support
+- Bridge `setFcmToken`, `userDidAuthenticate`, `handlePushNotification`, `approvePushRequest`, and `declinePushRequest` directly to `HawcxSDK`. Ensure `handlePushNotification` returns whether a requestId was processed so JS can decide to show fallback UI.
+- Implement a `PushDelegateProxy` that conforms to `HawcxPushAuthDelegate`, emits push events, and mirrors the APNs payload shape (requestId, ipAddress, deviceInfo, location, timestamp).
+- Provide a lightweight helper (e.g., `HawcxReactNativePushHandler`) that host apps and the RN example can call from their `FirebaseMessagingService` to feed payloads + tokens back into the SDK even when JS is not running.
+- Surface cleanup helpers (`clearSessionTokens`, `clearUserKeychainData`, `clearLastLoggedInUser`) so RN apps can match the Compose demo’s “reset device” UX.
+
+#### Phase E – JS/TS API + platform ergonomics
+- Update `src/index.ts` to detect `Platform.OS` and fan out to `setApnsDeviceToken` vs `setFcmToken`, while maintaining backwards-compatible wrappers. Add `setPushDeviceToken`, `setFcmToken`, and `setApnsDeviceToken` exports with clear docs.
+- Extend the TS event types so push events can include Android-only metadata (e.g., `location`, `deviceInfo`). Ensure hooks (`useHawcxAuth`, `useHawcxWebLogin`) continue to work without platform-specific code.
+- Add Jest coverage that stubs the native module on Android and verifies the new methods reject invalid input the same way they do on iOS.
+- Update `hawcxClient` helpers to expose `notifyUserAuthenticated`, `setPushDeviceToken`, and `handlePushNotification` semantics called out in the Android demo.
+
+#### Phase F – Example app & Android QA harness
+- Wire the RN example to run on Android emulators: ensure `npm run android` succeeds, `MainApplication.kt` (generated by RN) references the autolinked package, and Hermes is enabled.
+- Document how to drop `google-services.json` under `example/android/app/` and where to paste `projectApiKey` + OAuth values (mirroring `example/src/hawcx.config.ts`).
+- Add a sample `FirebaseMessagingService` (Kotlin) inside the example app module that forwards tokens/payloads to the RN bridge so push approvals can be exercised without custom native code.
+- Expand Maestro/Detox scripts with Android variants (registration/login, OTP failure, push approval) and pipe them into CI.
+
+#### Phase G – Documentation, release, and handoff
+- Update `README.md`, `CHANGELOG.md`, and `docs/RELEASE.md` with Android setup instructions (Gradle sync, FCM requirements, example app steps, release checks for `./gradlew -p android assembleRelease lintRelease`).
+- Capture how to refresh the Hawcx Android AAR (pull from `dev_android/android_sdk`, update checksums, bump versions) so future engineers don’t guess.
+- Ensure the release checklist includes dual-platform smoke tests (`npm run ios`, `npm run android`), TypeScript build, Swift compilation, and Android linting before tagging/publishing.
+- Once Android ships, add new tracker rows + changelog entries summarizing parity status and any follow-up items (analytics hooks, tenant overrides, etc.).
+
+## Testing & Observability Strategy
+- **Unit Tests**: Swift bridging/event translation, Kotlin Robolectric tests for `HawcxReactNativeModule` + callback proxies, and Jest for TS utilities/hooks.
+- **Integration Tests**: Run the RN example on iOS (`npm run ios`) and Android (`npm run android`) against the dev backend with real API keys to cover registration, login, push approvals, and web login.
+- **E2E**: Detox/Maestro suites per platform (cover OTP happy path + failure, push approval, credential reset, biometric opt-in) wired into CI; reuse Maestro YAML from the native demos where possible.
+- **Logging & Telemetry**: Surface `SDKLogger` output to JS only in debug builds, hook Android logs via Logcat, and ensure no secrets leave native boundaries. Optionally expose an analytics callback so host apps can track auth outcomes consistently.
+
+## Deployment & Release Checklist
+1. **Sync + verify**
+   ```bash
+   git checkout main
+   git pull origin main
+   git status
+   ```
+2. **Quality gates (repo root unless noted)**
+   ```bash
+   npm install
+   npm run lint
+   npm run typecheck
+   npm test
+   npm run build
+   pod lib lint HawcxReactNative.podspec
+   ./gradlew -p android clean lintRelease testReleaseUnitTest assembleRelease publishToMavenLocal
+   ```
+   Confirm `android/build/reports/lint-results-release.html` and `lint-results.html` show no issues.
+3. **Update versioning artifacts**
+   - Bump `package.json` version and the corresponding Android `gradle.properties` (if we mirror the number there).
+   - Edit `CHANGELOG.md` with the release summary (mention whether Android/iOS changes are included).
+   - Commit once tests pass: `git commit -am "chore: release vX.Y.Z"`.
+4. **Smoke test example apps**
+   ```bash
+   cd example
+   npm install
+   npm run ios
+   npm run android
+   cd ..
+   ```
+   Verify OTP, login, push, and web login flows using dev credentials + Firebase config.
+5. **Publish artifacts**
+   - `npm publish --access public`
+   - `pod repo push trunk HawcxReactNative.podspec --allow-warnings`
+6. **Tag + push**
+   ```bash
+   git tag vX.Y.Z
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+7. **Customer handoff**
+   - Share the npm version + changelog.
+   - Provide iOS pod install instructions and Android setup notes (FCM token wiring, `google-services.json`, Gradle sync).
+   - Update this plan with any new follow-ups (e.g., analytics hooks, tenant overrides).
+
+## Progress Tracker
+_Update this table as you work. Status values: TODO / IN-PROGRESS / BLOCKED / DONE._
+
+| Phase | Task | Owner | Status | Notes |
+| --- | --- | --- | --- | --- |
+| 0 | Repo + tooling scaffold | Codex (2025-11-13) | DONE | Initialized RN package structure, tooling, Swift bridge scaffold |
+| 1 | Native bridge skeleton & callbacks | Codex (2025-11-13) | DONE | Swift bridge wraps HawcxSDK; JS API validates inputs & emits events |
+| 2 | TypeScript API + hooks | Codex (2025-11-13) | DONE | Added HawcxClient, useHawcxAuth, Jest coverage, README docs |
+| 3 | Session + web login utilities | Codex (2025-11-15) | DONE | Added device details + web login/approve bridges, hooks, tests |
+| 4 | Push notification bridge | Codex (2025-11-15) | DONE | Added APNs token handling, push events, approve/decline helpers |
+| 5 | Example RN app + E2E harness | Codex (2025-11-15) | DONE | Added example app + Maestro script under `example/` |
+| 6 | Docs, release pipeline, publishing | Codex (2025-11-15) | DONE | Added CHANGELOG, docs/RELEASE, README release steps, package metadata |
+| A | Android module bootstrap & dependency wiring | Codex (2025-11-15) | DONE | Added Gradle lib + hawcx-5.1.0.aar bundle, README refresh steps, Gradle tasks passing |
+| B | Kotlin native module + auth bridge | Codex (2025-11-15) | DONE | Added HawcxSDK-backed `initialize`/`authenticate`/OTP + cleanup helpers (auth events logging until Phase C) |
+| C | Session + web callbacks + error mapping | Codex (2025-11-15) | DONE | Auth/session events now emitted from Android; added `getDeviceDetails`, `webLogin`, `webApprove` bridges |
+| D | Push + lifecycle support | Codex (2025-11-15) | DONE | Added push delegate proxy, `setFcmToken`, `handlePushNotification`, approve/decline |
+| E | JS/TS platform ergonomics | Codex (2025-11-15) | DONE | Added cross-platform push helpers, Android guards, README/testing updates |
+| F | Example app + Android QA harness | Codex (2025-11-15) | DONE | Example app updated for Android + push harness, README + Maestro docs refreshed |
+| G | Docs + release updates | Codex (2025-11-15) | DONE | Release guide now covers Android Gradle checks + dual-platform handoff |
+
+Add rows if new scope appears (e.g., analytics hook, tenant-specific API). Include blockers and links to PRs.
+
+## Key References
+- Backend repo: `hawcx_core_auth`
+  - `app/api/v5/endpoints.py`, `app/api/v5/device_verification_manage.py`, `app/shared/domain_service.py`.
+- iOS SDK: `dev_ios/ios_sdk/HawcxFramework/`
+  - Crypto/storage: `internal/V5Crypto.swift`, `internal/V5CredentialStore.swift`, `internal/V5EnvironmentInfo.swift`.
+  - Auth orchestration: `auth/HawcxAuthV5.swift`, `internal/HawcxSDK.swift`, `network/ApiService.swift`.
+  - Fingerprint generation: `utils/FingerprintGenerator.swift`.
+- Android SDK: `dev_android/android_sdk/app/src/main/Kotlin/com/hawcx`
+  - Facade & config: `internal/HawcxSDK.kt`, `internal/HawcxOAuthConfig.kt`, `internal/OAuthTokenVerifier.kt`.
+  - Auth + storage: `auth/HawcxAuthV5.kt`, `v5/V5CredentialStore.kt`, `storage/KeystoreManager.kt`, `utils/FingerprintGenerator.kt`.
+  - Push/session: `auth/DevSession.kt`, `auth/WebLoginManager.kt`, `utils/HawcxPushAuthDelegate.kt`, `utils/DeviceDetailsUtil.kt`.
+- Demo apps
+  - iOS: `dev_ios/ios_demo_dev/HawcxDemoApp`
+  - Android: `dev_android/HawcxAndroidDemoApp/HawcxDemoApp` (`MainApplication.kt`, `viewmodel/`, `messaging/DemoFirebaseMessagingService.kt`) for parity, push wiring, and Compose UX flows.
+
+Keep this plan current. If you modify architecture, document the rationale here so any new engineer can resume without knowledge gaps.

package/src/__tests__/index.test.ts

@@ -0,0 +1,163 @@
+import {
+  initialize,
+  authenticate,
+  submitOtp,
+  webLogin,
+  webApprove,
+  approvePushRequest,
+  declinePushRequest,
+  setPushDeviceToken,
+  HawcxClient,
+  HawcxAuthError,
+  __INTERNAL_EVENTS__,
+} from '../index';
+import { Platform } from 'react-native';
+
+const ORIGINAL_PLATFORM = Platform.OS;
+
+const overridePlatformOS = (os: typeof Platform.OS) => {
+  Object.defineProperty(Platform, 'OS', {
+    configurable: true,
+    get: () => os,
+  });
+};
+
+describe('Hawcx React Native SDK', () => {
+  it('rejects initialize call without api key', async () => {
+    await expect(initialize({ projectApiKey: '' })).rejects.toThrow('projectApiKey is required');
+  });
+
+  it('rejects authenticate call without userId', async () => {
+    await expect(authenticate('   ')).rejects.toThrow('userId is required');
+  });
+
+  it('rejects submitOtp call without otp', async () => {
+    await expect(submitOtp('')).rejects.toThrow('otp is required');
+  });
+
+  it('rejects webLogin call without pin', async () => {
+    await expect(webLogin('')).rejects.toThrow('pin is required');
+  });
+
+  it('rejects webApprove call without token', async () => {
+    await expect(webApprove('')).rejects.toThrow('token is required');
+  });
+
+  it('rejects approvePushRequest call without requestId', async () => {
+    await expect(approvePushRequest('')).rejects.toThrow('requestId is required');
+  });
+
+  it('rejects declinePushRequest call without requestId', async () => {
+    await expect(declinePushRequest('')).rejects.toThrow('requestId is required');
+  });
+});
+
+describe('HawcxClient helpers', () => {
+  const client = new HawcxClient();
+  const emitAuth = (event: unknown) => {
+    __INTERNAL_EVENTS__.authEmitter.emit(__INTERNAL_EVENTS__.authEventName, event as never);
+  };
+  const emitSession = (event: unknown) => {
+    __INTERNAL_EVENTS__.sessionEmitter.emit(__INTERNAL_EVENTS__.sessionEventName, event as never);
+  };
+
+  afterEach(() => {
+    __INTERNAL_EVENTS__.authEmitter.removeAllListeners(__INTERNAL_EVENTS__.authEventName);
+    __INTERNAL_EVENTS__.sessionEmitter.removeAllListeners(__INTERNAL_EVENTS__.sessionEventName);
+  });
+
+  it('resolves authenticate promise on success event', async () => {
+    const invocation = client.authenticate('user@example.com');
+    emitAuth({
+      type: 'auth_success',
+      payload: { isLoginFlow: true, accessToken: 'a', refreshToken: 'r' },
+    });
+    await expect(invocation.promise).resolves.toEqual({
+      isLoginFlow: true,
+      accessToken: 'a',
+      refreshToken: 'r',
+    });
+  });
+
+  it('rejects authenticate promise on error event', async () => {
+    const invocation = client.authenticate('user@example.com');
+    emitAuth({
+      type: 'auth_error',
+      payload: { code: 'otp_invalid', message: 'Invalid OTP' },
+    });
+    await expect(invocation.promise).rejects.toBeInstanceOf(HawcxAuthError);
+  });
+
+  it('rejects authenticate promise when cancelled', async () => {
+    const invocation = client.authenticate('user@example.com');
+    invocation.cancel();
+    await expect(invocation.promise).rejects.toBeInstanceOf(HawcxAuthError);
+  });
+
+  it('invokes web login session event handler', async () => {
+    const handler = jest.fn();
+    await client.webLogin('1234', { onEvent: handler });
+    emitSession({ type: 'session_success' });
+    expect(handler).toHaveBeenCalledWith({ type: 'session_success' });
+  });
+
+  it('invokes web approve session event handler', async () => {
+    const handler = jest.fn();
+    await client.webApprove('token', { onEvent: handler });
+    emitSession({
+      type: 'session_error',
+      payload: { code: 'failedApprove', message: 'Failed' },
+    });
+    expect(handler).toHaveBeenCalledWith({
+      type: 'session_error',
+      payload: { code: 'failedApprove', message: 'Failed' },
+    });
+  });
+
+  it('invokes push event handlers', async () => {
+    const handler = jest.fn();
+    const subscription = client.addPushListener(handler);
+    __INTERNAL_EVENTS__.pushEmitter.emit(__INTERNAL_EVENTS__.pushEventName, {
+      type: 'push_login_request',
+      payload: {
+        requestId: 'req',
+        ipAddress: '1.1.1.1',
+        deviceInfo: 'Safari on Mac',
+        location: 'SF',
+        timestamp: '2025-01-01T00:00:00Z',
+      },
+    });
+    expect(handler).toHaveBeenCalledWith({
+      type: 'push_login_request',
+      payload: {
+        requestId: 'req',
+        ipAddress: '1.1.1.1',
+        deviceInfo: 'Safari on Mac',
+        location: 'SF',
+        timestamp: '2025-01-01T00:00:00Z',
+      },
+    });
+    subscription.remove();
+  });
+});
+
+describe('push token helpers', () => {
+  afterEach(() => {
+    overridePlatformOS(ORIGINAL_PLATFORM);
+    jest.restoreAllMocks();
+  });
+
+  it('rejects APNs string tokens on iOS', async () => {
+    overridePlatformOS('ios');
+    await expect(setPushDeviceToken('abc')).rejects.toThrow(
+      'APNs tokens must be provided as byte arrays or Uint8Arrays',
+    );
+  });
+
+  it('rejects non-string tokens on Android', async () => {
+    overridePlatformOS('android');
+    await expect(setPushDeviceToken([1, 2, 3])).rejects.toThrow(
+      'FCM token must be a string on Android',
+    );
+  });
+});