@myazahq/kyc-sdk-react-native 2.3.0 → 2.5.0

package/src/screens/KeyPersonSheet.tsx

@@ -1,53 +1,65 @@
 import React, { useEffect, useState } from 'react';
-import {
-  Keyboard,
-  Modal,
-  Platform,
-  Pressable,
-  ScrollView,
-  useWindowDimensions,
-  View,
-} from 'react-native';
+import { Keyboard, Platform, Pressable, ScrollView, useWindowDimensions, View } from 'react-native';
 
-import { radius, spacing } from '../config/theme';
+import { spacing } from '../config/theme';
 import { useTheme } from '../components/runtime';
 import { MyazaText } from '../components/Typography';
 import { MyazaButton } from '../components/MyazaButton';
-import { Icon } from '../components/Icon';
+import { FloatingSheet } from '../components/glass/FloatingSheet';
 import { KeyPersonForm } from './KeyPersonForm';
 import { isKeyPersonRowValid, type KeyPersonEntry } from '../config/keyPeople';
+import type { KeyPeopleSection as SectionKey } from '../config/keyPeopleSections';
+import type { KeyPersonRole } from '../types/business';
+
+/** What the sheet calls itself, per the section that opened it. */
+const ADD_TITLES: Record<SectionKey, string> = {
+  ubos: 'Add a beneficial owner',
+  shareholders: 'Add a shareholder',
+  representatives: 'Add a representative',
+};
 
 // ---------------------------------------------------------------------------
 // The add/edit key-person sheet. The list step stays a clean stack of summary
-// cards; the FORM lives here — slide-up sheet, grab handle, the five fields,
-// and a pinned primary action. Editing adds a visually separated destructive
-// "Remove this person" beneath the save (never beside it — HIG destructive
-// separation).
+// cards; the FORM lives here — the same liquid-glass FloatingSheet every other
+// picker in the SDK rides (handle, glass surface, swipe-down), so the two
+// sheet kinds feel like one system. Editing adds a visually separated
+// destructive "Remove this person" beneath the save (never beside it — HIG
+// destructive separation).
 //
 // Keyboard handling mirrors DialCodePicker: the sheet is lifted above the keys
 // and sized against the space that remains, so the focused field is never
 // underneath the keyboard.
 //
-// Save is enabled once the draft is valid. A combined-ownership overshoot
-// WARNS here but never blocks saving — the fix may live on a different
-// person's %, and trapping the user inside this sheet would force them to
-// discard their work to go adjust it.
+// Save is enabled once the draft is valid (including a REQUIRED email when the
+// workflow demands one for the role). A combined-ownership overshoot WARNS
+// here but never blocks saving — the fix may live on a different person's %,
+// and trapping the user inside this sheet would force them to discard their
+// work to go adjust it.
 // ---------------------------------------------------------------------------
 
 export function KeyPersonSheet({
   mode,
+  section,
+  corporateKyb = false,
   initial,
   uboThreshold,
   otherPctTotal,
+  emailRequiredFor,
   onSave,
   onRemove,
   onClose,
 }: {
   mode: 'add' | 'edit';
+  /** The section whose add-tile or card opened the sheet. */
+  section: SectionKey;
+  /** The workflow sends corporate shareholders their own KYB application. */
+  corporateKyb?: boolean;
   initial: KeyPersonEntry;
   uboThreshold?: number;
   /** Sum of every OTHER person's ownership % — for the combined warning. */
   otherPctTotal: number;
+  /** Roles whose email is mandatory (they are sent a verification link). */
+  emailRequiredFor?: ReadonlySet<KeyPersonRole>;
   onSave: (entry: KeyPersonEntry) => void;
   /** Edit mode only — removes the person and closes. */
   onRemove?: () => void;
@@ -82,103 +94,75 @@ export function KeyPersonSheet({
   const fmtPct = (n: number): string => (Number.isInteger(n) ? String(n) : n.toFixed(1));
   const combinedPctError =
     combinedTotal > 100
-      ? `Combined ownership would be ${fmtPct(combinedTotal)}% — over by ${fmtPct(combinedTotal - 100)}%.`
+      ? `Combined ownership would be ${fmtPct(combinedTotal)}%, over by ${fmtPct(combinedTotal - 100)}%.`
       : null;
 
-  const canSave = isKeyPersonRowValid(draft) && draft.name.trim().length >= 2;
+  const canSave =
+    isKeyPersonRowValid(draft, emailRequiredFor ?? new Set()) && draft.name.trim().length >= 2;
 
   return (
-    <Modal visible transparent animationType="slide" onRequestClose={onClose}>
-      {/* Same wrapper as MyazaSelect's option sheet: a flex-end backdrop with
-          the sheet inside it, so the top corners round identically. Tapping
-          the backdrop dismisses; a tap inside the sheet does not. */}
-      <Pressable
-        onPress={onClose}
-        accessibilityLabel="Close"
+    <FloatingSheet
+      visible
+      onClose={onClose}
+      maxHeight={maxHeight}
+      // Ride above a raised keyboard — this sheet is a form.
+      bottomOffset={keyboard}
+      closeLabel="Close person editor"
+    >
+      <MyazaText
+        variant="body"
         style={{
-          flex: 1,
-          backgroundColor: 'rgba(0,0,0,0.45)',
-          justifyContent: 'flex-end',
+          fontWeight: '700',
+          paddingHorizontal: spacing.md,
+          // Tight under the handle, the way the system sheet titles sit.
+          paddingTop: spacing.xs,
+          paddingBottom: spacing.sm,
         }}
       >
-        <Pressable
-          onPress={() => {}}
-          style={{
-            maxHeight,
-            marginBottom: keyboard,
-            backgroundColor: colors.background,
-            borderTopLeftRadius: radius.lg,
-            borderTopRightRadius: radius.lg,
-            overflow: 'hidden',
-          }}
-        >
-        <View
-          style={{
-            alignSelf: 'center',
-            width: 36,
-            height: 4,
-            borderRadius: radius.full,
-            backgroundColor: colors.border,
-            marginTop: spacing.sm,
-          }}
-        />
-        <View
-          style={{
-            flexDirection: 'row',
-            alignItems: 'center',
-            paddingHorizontal: spacing.md,
-            paddingTop: spacing.sm + 4,
-            paddingBottom: spacing.sm,
-          }}
-        >
-          <MyazaText variant="body" style={{ flex: 1, fontWeight: '700' }}>
-            {mode === 'add' ? 'Add a person' : 'Edit person'}
-          </MyazaText>
-          <Pressable onPress={onClose} hitSlop={12} accessibilityRole="button" accessibilityLabel="Close">
-            <Icon name="x" size={20} color={colors.textSecondary} />
-          </Pressable>
-        </View>
+        {mode === 'add' ? ADD_TITLES[section] : draft.isCorporate ? 'Edit company' : 'Edit person'}
+      </MyazaText>
 
-        <ScrollView
-          bounces={false}
-          keyboardShouldPersistTaps="handled"
-          contentContainerStyle={{ paddingHorizontal: spacing.md, paddingBottom: spacing.sm }}
-        >
-          <KeyPersonForm
-            entry={draft}
-            onChange={(patch) => setDraft((d) => ({ ...d, ...patch }))}
-            uboThreshold={uboThreshold}
-            combinedPctError={combinedPctError}
-          />
-        </ScrollView>
+      <ScrollView
+        bounces={false}
+        keyboardShouldPersistTaps="handled"
+        contentContainerStyle={{ paddingHorizontal: spacing.md, paddingBottom: spacing.sm }}
+      >
+        <KeyPersonForm
+          entry={draft}
+          section={section}
+          corporateKyb={corporateKyb}
+          onChange={(patch) => setDraft((d) => ({ ...d, ...patch }))}
+          uboThreshold={uboThreshold}
+          combinedPctError={combinedPctError}
+          emailRequiredFor={emailRequiredFor}
+        />
+      </ScrollView>
 
-        <View style={{ paddingHorizontal: spacing.md, paddingTop: spacing.sm, paddingBottom: spacing.lg }}>
-          <MyazaButton
-            label={mode === 'add' ? 'Add person' : 'Save changes'}
-            onPress={canSave ? () => onSave(draft) : undefined}
-            disabled={!canSave}
-          />
-          {mode === 'edit' && onRemove ? (
-            <Pressable
-              onPress={onRemove}
-              accessibilityRole="button"
-              accessibilityLabel="Remove this person"
-              style={({ pressed }) => ({
-                height: 44,
-                alignItems: 'center',
-                justifyContent: 'center',
-                marginTop: spacing.xs,
-                opacity: pressed ? 0.7 : 1,
-              })}
-            >
-              <MyazaText variant="bodySmall" color={colors.error} style={{ fontWeight: '600' }}>
-                Remove this person
-              </MyazaText>
-            </Pressable>
-          ) : null}
-          </View>
-        </Pressable>
-      </Pressable>
-    </Modal>
+      <View style={{ paddingHorizontal: spacing.md, paddingTop: spacing.sm }}>
+        <MyazaButton
+          label={mode === 'add' ? (draft.isCorporate ? 'Add company' : 'Add person') : 'Save changes'}
+          onPress={canSave ? () => onSave(draft) : undefined}
+          disabled={!canSave}
+        />
+        {mode === 'edit' && onRemove ? (
+          <Pressable
+            onPress={onRemove}
+            accessibilityRole="button"
+            accessibilityLabel="Remove this person"
+            style={({ pressed }) => ({
+              height: 44,
+              alignItems: 'center',
+              justifyContent: 'center',
+              marginTop: spacing.xs,
+              opacity: pressed ? 0.7 : 1,
+            })}
+          >
+            <MyazaText variant="bodyMedium" color={colors.error} style={{ fontWeight: '600' }}>
+              {draft.isCorporate ? 'Remove this company' : 'Remove this person'}
+            </MyazaText>
+          </Pressable>
+        ) : null}
+      </View>
+    </FloatingSheet>
   );
 }

package/src/screens/LivenessStep.tsx

@@ -31,6 +31,7 @@ import {
 import { Icon } from '../components/Icon';
 import { useToast } from '../components/toast';
 import { CameraPermissionView, CameraUnavailableView, CameraPermissionPrimingView } from '../components/CameraPermissionView';
+import { useFaceModelReady } from '../liveness/useModelReady';
 import { ReadyPrimer } from '../components/ReadyPrimer';
 import { READY_LIVENESS } from '../components/readyPrimerContent';
 import { LivenessAvatar } from './LivenessAvatar';
@@ -113,6 +114,11 @@ export function LivenessStep(): React.ReactElement {
   const [perm, setPerm] = useState<'priming' | 'requesting' | 'granted' | 'denied'>(
     hasPermission ? 'granted' : 'priming',
   );
+
+  // Android fetches the face model through Play Services rather than bundling
+  // it, so it can be absent on a fresh install. Normally already 'ready' here —
+  // the flow primes the download at open, behind consent and ID-type selection.
+  const modelState = useFaceModelReady();
   const permReportedRef = useRef(false);
 
   // Camera-availability grace (a simulator has no front camera).
@@ -351,6 +357,18 @@ export function LivenessStep(): React.ReactElement {
   if (cameraUnavailable) {
     return <CameraUnavailableView />;
   }
+  // The face model is fetched on demand on Android (see useModelReady), so it
+  // can be absent on a fresh install or a device without Play Services. Checked
+  // here, before the camera opens, because detectFace reports a missing model
+  // and an empty frame identically — gating on frames would leave the user on
+  // "position your face" forever with nothing to explain it.
+  if (modelState === 'unavailable') {
+    return (
+      <CameraUnavailableView
+        message="Face verification couldn't start on this device. Check your connection and try again, or use a different device."
+      />
+    );
+  }
   // "Here's what happens next", BEFORE the OS prompt — and shown even when
   // permission is already granted, because it is about what the step will ask
   // of the user, not about access. Opening the camera unannounced is what makes

package/src/screens/NfcStep.tsx

@@ -8,6 +8,7 @@ import { MyazaButton } from '../components/MyazaButton';
 import { MyazaPulseLoader } from '../components/MyazaPulseLoader';
 import { Icon } from '../components/Icon';
 import { cancelChipRead, nfcUnavailableReason, readPassportChip, type EmrtdReadResult } from '../emrtd';
+import { fromBase64 } from '../emrtd/bytes';
 import { useNfcAvailability } from './nfc/useNfcAvailability';
 import { readErrorMessage } from './nfc/readErrorMessage';
 import { successHaptic } from '../services/haptics';
@@ -136,6 +137,18 @@ export function NfcStep(): React.ReactElement {
     stageRef.current = 'waiting';
     readingRef.current = true;
     try {
+      // The anti-clone challenge, asked for BEFORE the read so the whole thing
+      // happens in one session on the document. Best-effort by design: the
+      // server may not answer, and a chip read without a challenge is exactly
+      // the read this SDK did before Active Authentication existed. It must
+      // never be the reason a passport cannot be scanned.
+      const aaChallenge = await store
+        .getState()
+        .api.nfcChallenge()
+        .then((res) => ({ id: res.challengeId, bytes: fromBase64(res.challenge) }))
+        .catch(() => undefined);
+      if (!liveRef.current || seq !== readSeqRef.current) return;
+
       const result = await readPassportChip(
         {
           documentNumber: mrz.documentNumber,
@@ -143,6 +156,7 @@ export function NfcStep(): React.ReactElement {
           dateOfExpiry: toMrzDate(mrz.dateOfExpiry),
         },
         {
+          ...(aaChallenge ? { aaChallenge } : {}),
           onStage: (s) => {
             if (!liveRef.current || seq !== readSeqRef.current) return;
             stageRef.current = s;

package/src/screens/ProofOfAddressStep.tsx

@@ -8,6 +8,7 @@ import { MyazaButton } from '../components/MyazaButton';
 import { Icon } from '../components/Icon';
 import { MediaSourceSheet } from '../components/MediaSourceSheet';
 import { MyazaSelect } from '../components/MyazaSelect';
+import { DashedBorder } from '../components/DashedBorder';
 import { withRetry } from '../services/retry';
 import { compressDocumentImage } from '../services/mediaCompress';
 import { poaDocumentTypes, poaMaxAgeDays, poaTypeLabel } from '../config/proofOfAddress';
@@ -201,11 +202,13 @@ export function ProofOfAddressStep(): React.ReactElement {
             paddingVertical: spacing.xl,
             paddingHorizontal: spacing.lg,
             borderRadius: radius.md,
-            borderWidth: 1.5,
-            borderStyle: 'dashed',
-            borderColor: colors.border,
           }}
         >
+          <DashedBorder
+            color={colors.border}
+            radius={radius.md}
+            strokeWidth={1.5}
+          />
           {busy ? (
             <ActivityIndicator size="small" color={colors.primary} />
           ) : (

package/src/screens/SubmittedStep.tsx

@@ -3,6 +3,7 @@ import { View } from 'react-native';
 
 import { radius, spacing } from '../config/theme';
 import { mapToKycError, safeReportError } from '../services/errors';
+import { contactStepFor, expiredContactChannels } from '../lib/contact-recovery';
 import type { KYCError, KYCSubmission } from '../types/verification';
 import { useKyc, useKycConfig, useKycStore, useTheme } from '../components/runtime';
 import { MyazaText } from '../components/Typography';
@@ -11,7 +12,10 @@ import { MyazaAlert } from '../components/MyazaAlert';
 import { MyazaPulseLoader } from '../components/MyazaPulseLoader';
 import { Icon } from '../components/Icon';
 import { fillTokens } from '../utils/tokens';
-import { KeyPeopleInviteLinks } from './KeyPeopleInviteLinks';
+import { KeepLinksSheet } from './KeepLinksSheet';
+import { KeyPeopleAwaitList, rowsFromServer } from './KeyPeopleAwaitList';
+import { KeyPeoplePending } from './KeyPeoplePending';
+import { useAwaitingPeople } from './useAwaitingPeople';
 
 // Terminal screen — 1:1 with the Flutter SDK's SubmittedScreen. Calls
 // submitAsync on mount; renders submitting / success / error views with the same
@@ -20,8 +24,13 @@ import { KeyPeopleInviteLinks } from './KeyPeopleInviteLinks';
 type Phase = 'submitting' | 'success' | 'error';
 
 const DEFAULT_SUCCESS_TITLE = 'Verification Submitted!';
-const DEFAULT_SUCCESS_DESCRIPTION =
-  "Your identity verification has been submitted for review. You'll be notified of the result.";
+// The default description depends on WHAT was submitted. A KYB applicant told
+// "your identity verification has been submitted" is being told about the wrong
+// thing: they submitted a company. Mirrors the web SDK's successDescription.
+const defaultSuccessDescription = (isBusiness: boolean): string =>
+  isBusiness
+    ? "Your business verification has been submitted for review. You'll be notified of the result."
+    : "Your identity verification has been submitted for review. You'll be notified of the result.";
 
 const ERROR_TITLES: Record<string, string> = {
   insufficient_credits: 'Credits Exhausted',
@@ -38,7 +47,13 @@ export function SubmittedStep({ onClose }: { onClose: () => void }): React.React
   const existingResult = useKyc((s) => s.submissionResult);
 
   const [phase, setPhase] = useState<Phase>('submitting');
+  // The people list comes from the SERVER once registry discovery settles —
+  // the submit-time invites are a first draft the register can contradict
+  // (it adds people the applicant never listed, including ones they removed).
+  const sessionId = useKyc((s) => s.sessionId);
+  const settled = useAwaitingPeople(store.getState().api, sessionId, phase === 'success');
   const [error, setError] = useState<KYCError | null>(null);
+  const [keepLinksOpen, setKeepLinksOpen] = useState(false);
   const [retry, setRetry] = useState<{ attempt: number; total: number } | null>(null);
   const reportedRef = useRef(false);
   const kickedRef = useRef(false);
@@ -51,13 +66,22 @@ export function SubmittedStep({ onClose }: { onClose: () => void }): React.React
       const result = await store.getState().submitAsync((attempt, total) => setRetry({ attempt, total }));
       const submission: KYCSubmission = {
         verificationId: result.verificationId,
-        status: 'pending',
+        status: 'processing',
         metadata: config.metadata ?? {},
         submittedAt: new Date().toISOString(),
       };
       config.onSubmit?.(submission);
       setPhase('success');
     } catch (err) {
+      // A refusal over stale contact proofs is recoverable in-flow: clear the
+      // dead tokens and walk back to the contact step, which routes straight
+      // back here once re-verified (see lib/contact-recovery.ts).
+      const expired = expiredContactChannels(err);
+      if (expired.length > 0) {
+        store.getState().clearContactProofs(expired);
+        store.getState().goToStep(contactStepFor(expired[0]!));
+        return;
+      }
       const kycError = mapToKycError(err, 'verify');
       setError(kycError);
       if (!reportedRef.current) {
@@ -135,10 +159,22 @@ export function SubmittedStep({ onClose }: { onClose: () => void }): React.React
   const title = config.success?.title ? fillTokens(config.success.title, config.userData) : DEFAULT_SUCCESS_TITLE;
   const description = config.success?.description
     ? fillTokens(config.success.description, config.userData)
-    : DEFAULT_SUCCESS_DESCRIPTION;
-  // KYB: per-person verification links for full-KYC key people — rendered so
-  // the applicant can send each one immediately.
-  const invites = store.getState().keyPeopleInvites; // set before phase flips to success
+    : defaultSuccessDescription(config.subjectType === 'business');
+  // KYB: whether a people list is COMING (the submit minted invites). The list
+  // itself renders from the server's reconciled view, never from this draft.
+  const invitesExpected = store.getState().keyPeopleInvites.length > 0;
+
+  // People still owing a check when the applicant leaves. The settled list is
+  // authoritative once it arrives; before that, minted invites are the signal.
+  const outstanding = settled
+    ? settled.some((r) => r.status === 'pending' || r.status === 'failed')
+    : invitesExpected;
+  const sessionUrl = store.getState().sessionUrl;
+  // Tapping Done with links still live: offer the web page those links live
+  // on, because this screen dies with the app and the links die with it.
+  // Workflow opt-out: `keyPeopleLinkRecovery: false` (on by default).
+  const offerRecovery =
+    outstanding && !!sessionUrl && config.keyPeopleLinkRecovery !== false;
 
   return (
     <View style={{ flex: 1, justifyContent: 'space-between' }}>
@@ -155,9 +191,29 @@ export function SubmittedStep({ onClose }: { onClose: () => void }): React.React
         <MyazaText variant="bodyMedium" style={{ textAlign: 'center' }}>
           {description}
         </MyazaText>
-        <KeyPeopleInviteLinks invites={invites} />
+        {settled
+          ? settled.length > 0
+            ? <KeyPeopleAwaitList rows={rowsFromServer(settled)} />
+            : null
+          : invitesExpected
+            ? <KeyPeoplePending />
+            : null}
       </View>
-      <MyazaButton label="Done" onPress={onClose} />
+      <MyazaButton
+        label="Done"
+        onPress={() => (offerRecovery ? setKeepLinksOpen(true) : onClose())}
+      />
+      {offerRecovery ? (
+        <KeepLinksSheet
+          open={keepLinksOpen}
+          url={sessionUrl!}
+          onClose={() => setKeepLinksOpen(false)}
+          onDone={() => {
+            setKeepLinksOpen(false);
+            onClose();
+          }}
+        />
+      ) : null}
     </View>
   );
 }

package/src/screens/nfc/NfcReadProgress.tsx

@@ -30,6 +30,7 @@ const STEPS: NfcReadStage[] = [
   'readingData',
   'readingSecurity',
   'readingPhoto',
+  'readingDetails',
 ];
 
 export function NfcReadProgress({ stage }: { stage: NfcReadStage }): React.ReactElement {

package/src/screens/useAwaitingPeople.ts

@@ -0,0 +1,90 @@
+import { useEffect, useState } from 'react';
+import { AppState } from 'react-native';
+import type { KYCApi } from '../services/api';
+import type { AwaitingPersonPayload } from '../services/api-types';
+
+// The SERVER's list of who a submitted KYB application is waiting on — mirrors
+// the web SDK's use-awaiting-people 1:1.
+//
+// MEMBERSHIP settles once: registry discovery runs after submission and can
+// add people the applicant never listed, so nothing renders until the server
+// says it has finished (`keyPeopleSettled`). A list shown earlier is one
+// director short and would be contradicted moments later.
+//
+// STATUS stays live: the people named go and verify after this screen is first
+// shown, so once settled the list re-reads slowly while anybody still owes a
+// check — and re-reads on foreground, which is exactly when a stale badge
+// would be noticed.
+
+/** How often to re-ask while the server says it is still reconciling. */
+const RETRY_MS = 1500;
+/** How long to wait before showing whatever there is (discovery's final write
+ *  is best-effort; a spinner forever is worse than a list that might be short). */
+const GIVE_UP_MS = 15_000;
+/** Status-refresh cadence once settled, while anybody owes a check. */
+const POLL_MS = 20_000;
+
+function anyoneStillOwes(people: AwaitingPersonPayload[]): boolean {
+  return people.some(
+    (p) => p.status === 'pending' || p.status === 'submitted' || p.status === 'failed',
+  );
+}
+
+export function useAwaitingPeople(
+  api: KYCApi,
+  sessionId: string | null,
+  enabled: boolean,
+): AwaitingPersonPayload[] | null {
+  const [people, setPeople] = useState<AwaitingPersonPayload[] | null>(null);
+
+  useEffect(() => {
+    if (!sessionId || !enabled) return undefined;
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let committed = false;
+    const startedAt = Date.now();
+
+    const read = async (): Promise<void> => {
+      if (cancelled) return;
+      const summary = await api.sessionSummary(sessionId).catch(() => null);
+      if (cancelled) return;
+      const expired = Date.now() - startedAt > GIVE_UP_MS;
+
+      if (summary && (summary.keyPeopleSettled !== false || expired)) {
+        committed = true;
+        setPeople(summary.keyPeople);
+        if (anyoneStillOwes(summary.keyPeople)) {
+          timer = setTimeout(() => void read(), POLL_MS);
+        }
+        return;
+      }
+      if (committed) {
+        // One failed refresh must not end the updates: the list on screen is
+        // still true, only a little older.
+        timer = setTimeout(() => void read(), POLL_MS);
+        return;
+      }
+      if (expired) {
+        // Nothing readable at all — leave the list absent rather than empty,
+        // which would claim there is nobody to verify.
+        return;
+      }
+      timer = setTimeout(() => void read(), RETRY_MS);
+    };
+
+    const sub = AppState.addEventListener('change', (state) => {
+      if (state !== 'active') return;
+      if (timer) clearTimeout(timer);
+      void read();
+    });
+
+    void read();
+    return () => {
+      cancelled = true;
+      if (timer) clearTimeout(timer);
+      sub.remove();
+    };
+  }, [api, sessionId, enabled]);
+
+  return people;
+}