@myazahq/kyc-sdk-react-native 2.0.2 → 2.1.0

package/src/screens/liveness/useSelfieUpload.ts

@@ -0,0 +1,107 @@
+import { useCallback, useRef, useState } from 'react';
+
+import { MAX_VIDEO_BYTES } from '../../config/captureSettings';
+import { compressVideo } from '../../services/mediaCompress';
+import { withRetry } from '../../services/retry';
+import { mapToKycError, safeReportError } from '../../services/errors';
+import { useKyc, useKycConfig } from '../../components/runtime';
+import { useToast } from '../../components/toast';
+
+// ---------------------------------------------------------------------------
+// The selfie and its liveness video, uploaded as soon as they exist.
+//
+// Split out of LivenessStep (200-line rule). It is a genuine boundary, not a
+// slice for size: everything here is about getting two files to the server and
+// reporting how that went, and none of it touches the camera or the state
+// machine.
+//
+// The two uploads are deliberately NOT equal. The selfie is the verification —
+// its failure is surfaced, retried and reported. The video is supporting
+// evidence the server re-scores, so a failure there is swallowed: losing it must
+// never block a user who has already done everything asked of them.
+// ---------------------------------------------------------------------------
+
+export interface SelfieUpload {
+  selfieUri: string | null;
+  setSelfieUri: (uri: string | null) => void;
+  uploading: boolean;
+  /** Which retry attempt is in flight, for the "retrying (2/3)" line. */
+  retryInfo: { attempt: number; total: number } | null;
+  uploadError: string | null;
+  setUploadError: (message: string | null) => void;
+  /** The uploaded selfie's media id — Continue is gated on it. */
+  selfieIdRef: React.MutableRefObject<string | null>;
+  /**
+   * The finished liveness-video path, kept so the review screen's "Try Again"
+   * can re-upload it. The recorder itself lives in useVideoRecorder.
+   */
+  videoPathRef: React.MutableRefObject<string | null>;
+  uploadSelfieAndVideo: (selfie: string, videoPath: string | null) => Promise<void>;
+}
+
+export function useSelfieUpload(): SelfieUpload {
+  const toast = useToast();
+  const config = useKycConfig();
+  const api = useKyc((s) => s.api);
+  const setMediaId = useKyc((s) => s.setMediaId);
+
+  const [selfieUri, setSelfieUri] = useState<string | null>(null);
+  const [uploading, setUploading] = useState(false);
+  const [retryInfo, setRetryInfo] = useState<{ attempt: number; total: number } | null>(null);
+  const [uploadError, setUploadError] = useState<string | null>(null);
+  const selfieIdRef = useRef<string | null>(null);
+  const videoPathRef = useRef<string | null>(null);
+
+  const uploadSelfieAndVideo = useCallback(
+    async (selfie: string, videoPath: string | null) => {
+      setUploading(true);
+      setUploadError(null);
+      setRetryInfo(null);
+      const onRetry = (attempt: number, total: number) => setRetryInfo({ attempt, total });
+      try {
+        const selfieId = await withRetry(
+          () => api.upload({ uri: selfie, type: 'image/jpeg' }, 'selfie'),
+          { onRetry },
+        );
+        selfieIdRef.current = selfieId;
+        setMediaId('selfie', selfieId);
+        // Liveness video is best-effort — a failure here must not block the user.
+        if (videoPath) {
+          try {
+            // Transcode the raw recording down to a small evidence clip first.
+            const small = await compressVideo(videoPath);
+            const videoId = await withRetry(
+              () => api.upload({ uri: small, type: 'video/mp4' }, 'liveness_video', MAX_VIDEO_BYTES),
+              { onRetry },
+            );
+            setMediaId('livenessVideo', videoId);
+          } catch {
+            /* keep the selfie, drop the video (incl. if it exceeded the 5MB cap) */
+          }
+        }
+        setRetryInfo(null);
+        setUploading(false);
+      } catch (err) {
+        setRetryInfo(null);
+        setUploading(false);
+        const kycError = mapToKycError(err, 'upload');
+        setUploadError(kycError.message);
+        toast.show({ variant: 'error', title: 'Upload failed', message: kycError.message });
+        safeReportError(config.onError, kycError);
+      }
+    },
+    [api, setMediaId, config.onError, toast],
+  );
+
+  return {
+    selfieUri,
+    setSelfieUri,
+    uploading,
+    retryInfo,
+    uploadError,
+    setUploadError,
+    selfieIdRef,
+    videoPathRef,
+    uploadSelfieAndVideo,
+  };
+}

package/src/screens/nfc/NfcMrzPrompt.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { MyazaText } from '../../components/Typography';
+import { MyazaButton } from '../../components/MyazaButton';
+import { MrzScanView } from '../MrzScanView';
+import type { MrzScan } from '../../mrz/parse';
+
+/**
+ * The second chance at the chip's key.
+ *
+ * Without an MRZ there is nothing to unlock the chip with, and this step used
+ * to dead-end there — which made the chip unreachable whenever the document
+ * photo happened to read badly. Scanning the strip live costs the user one
+ * more aim of the camera and recovers the whole step.
+ */
+export function NfcMrzPrompt({
+  onScanned,
+  onSkip,
+}: {
+  onScanned: (scan: MrzScan) => void;
+  /** Null hides the escape hatch (the flow set `allowSkip: false`). */
+  onSkip: (() => void) | null;
+}): React.ReactElement {
+  return (
+    <View>
+      <MyazaText variant="bodyMedium">
+        Point your camera at the photo page of your document. We’ll read the
+        printed code that unlocks its chip.
+      </MyazaText>
+      <View style={{ height: spacing.md }} />
+      <MrzScanView onScanned={onScanned} />
+      <View style={{ height: spacing.md }} />
+      {onSkip ? (
+        <MyazaButton label="Continue without the chip" variant="ghost" onPress={onSkip} />
+      ) : null}
+    </View>
+  );
+}

package/src/screens/nfc/NfcReadBody.tsx

@@ -0,0 +1,63 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { NfcReadProgress } from './NfcReadProgress';
+import { NfcScannedSummary } from './NfcScannedSummary';
+import { NfcScanIllustration } from './NfcScanIllustration';
+import type { NfcReadStage } from '../../emrtd';
+import type { MrzScan } from '../../mrz/parse';
+
+/**
+ * The chip step's body: the document illustration, the read narration, and
+ * what the MRZ scan found.
+ *
+ * The narration is the part that matters. iOS gets a system sheet describing
+ * the read for free; Android gets nothing, so without this the same read is a
+ * silent spinner — and silence is exactly what makes a user lift the document,
+ * which aborts it.
+ */
+export function NfcReadBody({
+  reading,
+  stage,
+  scan,
+}: {
+  reading: boolean;
+  stage: NfcReadStage;
+  scan: MrzScan;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <>
+      <NfcScanIllustration />
+      <View style={{ height: spacing.lg }} />
+
+      {reading ? (
+        <>
+          <MyazaText variant="bodyMedium" style={{ textAlign: 'center' }}>
+            {stage === 'waiting'
+              ? 'Hold the top edge of your document flat against the back of your phone and keep still…'
+              : 'Chip detected — keep the document still until this finishes.'}
+          </MyazaText>
+          <View style={{ height: spacing.md }} />
+          <NfcReadProgress stage={stage} />
+        </>
+      ) : (
+        <>
+          <MyazaText variant="bodySmall" color={colors.textMuted} style={{ textAlign: 'center' }}>
+            Hold the top edge of your document flat against the back of your
+            phone and keep still…
+          </MyazaText>
+          {/* Shown BEFORE the read, so the wrong document is obvious now rather
+              than after an opaque BAC failure. */}
+          <View style={{ height: spacing.md }} />
+          <View style={{ alignSelf: 'stretch' }}>
+            <NfcScannedSummary scan={scan} />
+          </View>
+        </>
+      )}
+    </>
+  );
+}

package/src/screens/nfc/NfcReadProgress.tsx

@@ -0,0 +1,96 @@
+import React from 'react';
+import { ActivityIndicator, View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { Icon } from '../../components/Icon';
+import { NFC_STAGE_ORDER, nfcStageLabel, type NfcReadStage } from '../../emrtd';
+
+// ---------------------------------------------------------------------------
+// NFC read progress.
+//
+// iOS puts a system sheet over the screen for the whole chip read and narrates
+// it. Android has NO system NFC UI whatsoever, so the same read is otherwise a
+// bare spinner: the user cannot tell whether the chip has even been detected,
+// let alone that three data groups are being pulled off it — and the natural
+// response to that silence is to lift the document, which aborts the read.
+//
+// This draws the narration the platform does not. Same wording as the iOS
+// sheet, so both platforms describe the read identically. Ported from the
+// Flutter SDK's NfcReadProgress.
+// ---------------------------------------------------------------------------
+
+/**
+ * The steps worth showing. `waiting` is NOT one of them — it is the state
+ * before any step starts, and it gets its own prominent line above.
+ */
+const STEPS: NfcReadStage[] = [
+  'authenticating',
+  'readingData',
+  'readingSecurity',
+  'readingPhoto',
+];
+
+export function NfcReadProgress({ stage }: { stage: NfcReadStage }): React.ReactElement {
+  const { colors } = useTheme();
+
+  // Waiting is the state users misread as "nothing is happening", so it says
+  // what the phone is doing rather than leaving a silent spinner.
+  if (stage === 'waiting') {
+    return (
+      <View style={{ flexDirection: 'row', alignItems: 'center', justifyContent: 'center' }}>
+        <ActivityIndicator size="small" color={colors.primary} />
+        <View style={{ width: 8 }} />
+        <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '600' }}>
+          {nfcStageLabel('waiting')}
+        </MyazaText>
+      </View>
+    );
+  }
+
+  const currentIndex = NFC_STAGE_ORDER.indexOf(stage);
+
+  return (
+    <View style={{ alignSelf: 'stretch' }}>
+      {STEPS.map((step) => {
+        // `done` completes EVERY step: the photo group is skipped when the
+        // security object didn't come back, and a step left spinning after a
+        // successful read would read as a failure.
+        const complete = stage === 'done' || currentIndex > NFC_STAGE_ORDER.indexOf(step);
+        const active = stage === step;
+        return (
+          <View
+            key={step}
+            style={{ flexDirection: 'row', alignItems: 'center', marginBottom: spacing.sm }}
+          >
+            <View style={{ width: 18, alignItems: 'center' }}>
+              {complete ? (
+                <Icon name="badge-check" size={16} color={colors.success} />
+              ) : active ? (
+                <ActivityIndicator size="small" color={colors.primary} />
+              ) : (
+                <View
+                  style={{
+                    width: 8,
+                    height: 8,
+                    borderRadius: 4,
+                    backgroundColor: colors.gray300,
+                  }}
+                />
+              )}
+            </View>
+            <View style={{ width: 10 }} />
+            <MyazaText
+              variant="bodySmall"
+              color={complete || active ? colors.textDark : colors.textMuted}
+              style={{ fontWeight: active ? '600' : '400', flex: 1 }}
+            >
+              {nfcStageLabel(step)}
+            </MyazaText>
+          </View>
+        );
+      })}
+    </View>
+  );
+}

package/src/screens/nfc/NfcScanIllustration.tsx

@@ -0,0 +1,244 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { AccessibilityInfo, Animated, Easing, View } from 'react-native';
+import Svg, { Circle, Defs, G, Path, RadialGradient, Rect, Stop } from 'react-native-svg';
+
+import { useTheme } from '../../components/runtime';
+
+/**
+ * The NFC scan illustration, ported 1:1 from the web SDK's
+ * `NfcScanIllustration` — same 320×240 geometry, same three beats: a document
+ * with a CHIP, a phone held over it, a FIELD between them. The web component
+ * is the design source of truth; every coordinate here matches it digit for
+ * digit so the builder preview (web) and the live mobile screen stay the same
+ * picture. Change the web one first, then mirror.
+ *
+ * Exactly ONE element is `primary`: the field. Everything else is neutral
+ * theme tokens, so it inherits an org's palette and works in both modes.
+ */
+
+/** Where the field originates: on the phone's edge, at antenna height. */
+const COUPLING = { x: 173, y: 88 } as const;
+
+/** Arc radii, innermost first — each is one "ripple" of the field. */
+const WAVES = [
+  { r: 16, opacity: 0.9, delay: 0 },
+  { r: 28, opacity: 0.65, delay: 150 },
+  { r: 40, opacity: 0.42, delay: 300 },
+  { r: 50, opacity: 0.25, delay: 450 },
+] as const;
+
+/** Half-angle of the fan, in degrees. */
+const SPREAD = 56;
+
+/** Web keyframes: 0% .25 → 45% 1 → 100% .25 over 1.8s, staggered. */
+const PERIOD_MS = 1800;
+const RISE_MS = PERIOD_MS * 0.45;
+
+function wavePath(r: number): string {
+  const rad = (SPREAD * Math.PI) / 180;
+  const dx = Math.cos(rad) * r;
+  const dy = Math.sin(rad) * r;
+  const x = COUPLING.x + dx;
+  return `M ${x.toFixed(1)} ${(COUPLING.y - dy).toFixed(1)} A ${r} ${r} 0 0 1 ${x.toFixed(1)} ${(COUPLING.y + dy).toFixed(1)}`;
+}
+
+const AnimatedPath = Animated.createAnimatedComponent(Path);
+
+/**
+ * Web-parity alpha suffixes for the theme's hex colours (the web draws with
+ * `token/NN` Tailwind opacities; RN colours are plain hex strings).
+ */
+const A10 = '1A';
+const A20 = '33';
+const A25 = '40';
+const A40 = '66';
+const A50 = '80';
+const A70 = 'B3';
+
+export function NfcScanIllustration(): React.ReactElement {
+  const { colors } = useTheme();
+
+  // One value per ripple; the element opacity animates while strokeOpacity
+  // holds the per-arc base — exactly the web's two-layer opacity.
+  const pulses = useRef(WAVES.map(() => new Animated.Value(1))).current;
+  const [reduceMotion, setReduceMotion] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    void AccessibilityInfo.isReduceMotionEnabled().then((reduced) => {
+      if (!cancelled) setReduceMotion(reduced);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (reduceMotion) {
+      // Same behaviour as the web's reduced-motion rule: the animation stops
+      // and the arcs stay VISIBLE at full element opacity.
+      pulses.forEach((v) => v.setValue(1));
+      return undefined;
+    }
+    const runs = pulses.map((value, i) => {
+      value.setValue(0.25);
+      const run = Animated.sequence([
+        Animated.delay(WAVES[i]!.delay),
+        Animated.loop(
+          Animated.sequence([
+            Animated.timing(value, {
+              toValue: 1,
+              duration: RISE_MS,
+              easing: Easing.inOut(Easing.ease),
+              // SVG props can't ride the native driver.
+              useNativeDriver: false,
+            }),
+            Animated.timing(value, {
+              toValue: 0.25,
+              duration: PERIOD_MS - RISE_MS,
+              easing: Easing.inOut(Easing.ease),
+              useNativeDriver: false,
+            }),
+          ]),
+        ),
+      ]);
+      run.start();
+      return run;
+    });
+    return () => runs.forEach((r) => r.stop());
+  }, [pulses, reduceMotion]);
+
+  return (
+    // Same footprint as the web: full width up to 384 (`max-w-sm`), 320:240.
+    <View style={{ width: '100%', maxWidth: 384, aspectRatio: 320 / 240, alignSelf: 'center' }}>
+      <Svg width="100%" height="100%" viewBox="0 0 320 240">
+        <Defs>
+          {/* The field falls off with distance — the reason the document has
+              to be held CLOSE, said as a gradient instead of a caption. */}
+          <RadialGradient
+            id="kyc-nfc-field"
+            cx={COUPLING.x}
+            cy={COUPLING.y}
+            r={90}
+            gradientUnits="userSpaceOnUse"
+          >
+            <Stop offset="0" stopColor={colors.primary} stopOpacity={0.18} />
+            <Stop offset="0.55" stopColor={colors.primary} stopOpacity={0.06} />
+            <Stop offset="1" stopColor={colors.primary} stopOpacity={0} />
+          </RadialGradient>
+        </Defs>
+
+        {/* ── The document, tucked BEHIND the phone: portrait, chip, MRZ. ── */}
+        <G rotation={7} origin="212, 112">
+          <Rect
+            x={154}
+            y={30}
+            width={114}
+            height={164}
+            rx={10}
+            fill={`${colors.backgroundSecondary}${A50}`}
+            stroke={colors.border}
+            strokeWidth={2}
+          />
+
+          {/* Portrait, top-right — an outline glyph floating in its frame. */}
+          <Rect
+            x={224}
+            y={46}
+            width={32}
+            height={42}
+            rx={6}
+            fill={`${colors.textDark}${A10}`}
+            stroke={colors.border}
+            strokeWidth={1.5}
+          />
+          <G
+            stroke={`${colors.textSecondary}${A50}`}
+            strokeWidth={2}
+            strokeLinecap="round"
+            fill="none"
+          >
+            <Circle cx={240} cy={61} r={5.5} />
+            <Path d="M231.5 77.5a8.5 8.5 0 0 1 17 0" />
+          </G>
+
+          {/* The chip — the familiar card contact pad, centred on the card,
+              below the fan's lowest reach so the arcs can never touch it. */}
+          <G stroke={`${colors.textSecondary}${A70}`} strokeWidth={1.5} fill="none">
+            <Rect
+              x={200.5}
+              y={133}
+              width={21}
+              height={16}
+              rx={3}
+              fill={`${colors.textDark}${A10}`}
+            />
+            <Path d="M200.5 138.3h21M200.5 143.7h21M211 138.3v5.4" />
+          </G>
+
+          {/* The MRZ, low on the card, running edge to edge behind the phone.
+              Border tone: background texture, not an icon. */}
+          <G stroke={colors.border} strokeWidth={3} strokeLinecap="round" fill="none">
+            <Path d="M170 174h84" strokeDasharray="6 4" />
+            <Path d="M166 184h88" strokeDasharray="4 5" strokeOpacity={0.7} />
+          </G>
+        </G>
+
+        {/* ── The phone, in front, screen toward us — pressed in close. ── */}
+        <G x={12}>
+          <G rotation={-5} origin="112, 126">
+            {/* Volume buttons, on the side away from the field. */}
+            <Rect x={57} y={84} width={3} height={14} rx={1.5} fill={`${colors.textDark}${A25}`} />
+            <Rect x={57} y={103} width={3} height={14} rx={1.5} fill={`${colors.textDark}${A25}`} />
+
+            {/* Opaque base + tint: the tint token alone is an alpha fill and
+                let the card ghost THROUGH the glass. */}
+            <Rect x={60} y={30} width={104} height={192} rx={24} fill={colors.background} />
+            <Rect
+              x={60}
+              y={30}
+              width={104}
+              height={192}
+              rx={24}
+              fill={`${colors.backgroundSecondary}${A40}`}
+              stroke={`${colors.textDark}${A25}`}
+              strokeWidth={2}
+            />
+            <Rect x={99} y={46} width={26} height={8} rx={4} fill={`${colors.textDark}${A25}`} />
+
+            {/* Ghost caption bars where the instruction copy sits in the app. */}
+            <Rect x={87} y={170} width={50} height={5} rx={2.5} fill={colors.border} />
+            <Rect
+              x={96}
+              y={181}
+              width={32}
+              height={4}
+              rx={2}
+              fill={colors.border}
+              opacity={0.6}
+            />
+
+            {/* Home indicator — the strongest "this is the front" cue. */}
+            <Rect x={97} y={205} width={30} height={3.5} rx={1.75} fill={`${colors.textDark}${A20}`} />
+          </G>
+        </G>
+
+        {/* ── The field, over both objects. ── */}
+        <Circle cx={COUPLING.x} cy={COUPLING.y} r={90} fill="url(#kyc-nfc-field)" />
+        <Circle cx={COUPLING.x} cy={COUPLING.y} r={4.5} fill={colors.primary} />
+        {WAVES.map((w, i) => (
+          <AnimatedPath
+            key={w.r}
+            d={wavePath(w.r)}
+            stroke={colors.primary}
+            strokeWidth={3.25}
+            strokeLinecap="round"
+            fill="none"
+            strokeOpacity={w.opacity}
+            opacity={pulses[i]!}
+          />
+        ))}
+      </Svg>
+    </View>
+  );
+}

package/src/screens/nfc/NfcScannedSummary.tsx

@@ -0,0 +1,74 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { Icon } from '../../components/Icon';
+import type { MrzScan } from '../../mrz/parse';
+
+// ---------------------------------------------------------------------------
+// Scanned identity card.
+//
+// What the MRZ scan read, shown back for confirmation — so the wrong document is
+// obvious BEFORE the chip read rather than after an opaque BAC failure.
+//
+// NAME and DOCUMENT NUMBER only, 1:1 with the Flutter SDK's NfcScannedSummary.
+// Those two are what a user actually checks against the printed page; the dates
+// were noise on a screen whose job is "is this the right document, yes or no".
+//
+// Labels are uppercase, 10pt, 0.8 letter-spacing — the same treatment Flutter
+// gives them, so the two SDKs read as one product.
+// ---------------------------------------------------------------------------
+
+export function NfcScannedSummary({ scan }: { scan: MrzScan }): React.ReactElement {
+  const { colors } = useTheme();
+  const name = [scan.firstName, scan.lastName].filter(Boolean).join(' ');
+
+  const Label = ({ children }: { children: string }): React.ReactElement => (
+    <MyazaText
+      variant="bodySmall"
+      color={colors.textMuted}
+      style={{ fontSize: 10, fontWeight: '600', letterSpacing: 0.8 }}
+    >
+      {children.toUpperCase()}
+    </MyazaText>
+  );
+
+  return (
+    <View
+      style={{
+        padding: spacing.md,
+        backgroundColor: colors.primary50,
+        borderRadius: radius.md,
+        borderWidth: 1,
+        borderColor: `${colors.primary}40`,
+        flexDirection: 'row',
+        alignItems: 'flex-start',
+      }}
+    >
+      {/* Optically aligned with the first line of text rather than the block's
+          centre, which drifts as the name wraps. */}
+      <View style={{ paddingTop: 2 }}>
+        <Icon name="badge-check" size={18} color={colors.primary} />
+      </View>
+      <View style={{ width: spacing.sm }} />
+      <View style={{ flex: 1 }}>
+        {name ? (
+          <View style={{ marginBottom: spacing.sm }}>
+            <Label>Name</Label>
+            <MyazaText variant="bodyMedium" color={colors.textDark} style={{ fontWeight: '600' }}>
+              {name}
+            </MyazaText>
+          </View>
+        ) : null}
+        <View>
+          <Label>Document number</Label>
+          <MyazaText variant="bodyMedium" color={colors.textDark} style={{ fontWeight: '600' }}>
+            {scan.documentNumber}
+          </MyazaText>
+        </View>
+      </View>
+    </View>
+  );
+}