@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/steps/DocumentsOcrStep.tsx

@@ -0,0 +1,472 @@
+/**
+ * DOCUMENTS_OCR — capture front + back, upload to signed URLs, trigger OCR.
+ *
+ * Mirrors `DocumentsModule.ts` flow:
+ *   intro → captureFront → reviewFront → captureBack → reviewBack →
+ *   POST /documents-init → PUT image/jpeg × 2 → POST /documents-verify → done.
+ *
+ * No edge detection / OpenCV port (intentional MVP scope per the brief). The
+ * camera shows the ID-1 frame guide and the user fills it; the backend OCR
+ * pipeline handles cropping.
+ *
+ * Compression: vision-camera writes a high-quality JPEG. We re-compress with
+ * `expo-image-manipulator` before upload so we keep the payload under the
+ * 5 MB ceiling Velion's storage layer expects.
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+import {
+  Image,
+  Platform,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+} from 'react-native';
+import * as ImageManipulator from 'expo-image-manipulator';
+import type { PhotoFile } from 'react-native-vision-camera';
+import {
+  SdkErrorCode,
+  type DocumentSide,
+  type DocumentsInitResponse,
+  type DocumentsOcrStepConfig,
+  type DocumentOrientation,
+  type SdkError,
+} from '../types';
+import { Banner } from '../ui/primitives/Banner';
+import { Button } from '../ui/primitives/Button';
+import { LoadingOverlay } from '../ui/overlays/LoadingOverlay';
+import { RetryDialog } from '../ui/overlays/RetryDialog';
+import { StepShell } from '../ui/StepShell';
+import { StepIcon } from '../ui/icons/StepIcon';
+import { useTheme, mixHex } from '../ui/theme';
+import { getStrings } from '../i18n';
+import { resolveCaptureModeFromStepConfig } from '../utils/stepConfig';
+import { log } from '../utils/log';
+import { DocumentCapture } from '../camera/DocumentCapture';
+import type { ApiCaller } from '../transport/api';
+import type { StepDeps, StepModule } from './types';
+import { toSubmissionError } from './_shared';
+
+const DOCUMENTS_INIT_DOCUMENT_TYPE = 'ARG_DNI';
+const MAX_BYTES = 5 * 1024 * 1024;
+const COMPRESS_QUALITY = 0.78;
+const MAX_LONG_EDGE = 1800;
+
+interface CapturedSide {
+  uri: string;
+  width: number;
+  height: number;
+  byteLength: number;
+}
+
+type Phase =
+  | 'intro'
+  | 'captureFront'
+  | 'reviewFront'
+  | 'captureBack'
+  | 'reviewBack';
+
+export class DocumentsOcrStep implements StepModule {
+  private resolveStep!: () => void;
+  private rejectStep!: (err: SdkError) => void;
+  private destroyed = false;
+
+  constructor(private readonly deps: StepDeps) {}
+
+  run(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.resolveStep = resolve;
+      this.rejectStep = reject;
+      this.deps.ui.setNode(
+        <DocumentsOcrView
+          api={this.deps.api}
+          sessionId={this.deps.sessionId}
+          locale={this.deps.locale}
+          stepConfig={this.deps.stepConfig as DocumentsOcrStepConfig | undefined}
+          onComplete={() => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.resolveStep();
+          }}
+          onCancel={(err) => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.rejectStep(err);
+          }}
+        />,
+      );
+    });
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.deps.ui.setNode(null);
+  }
+}
+
+interface ViewProps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  stepConfig: DocumentsOcrStepConfig | undefined;
+  onComplete: () => void;
+  onCancel: (err: SdkError) => void;
+}
+
+function DocumentsOcrView({
+  api,
+  sessionId,
+  locale,
+  stepConfig,
+  onComplete,
+  onCancel,
+}: ViewProps) {
+  const t = getStrings(locale);
+  const theme = useTheme();
+  // Default to portrait — most ID documents are held vertically by users on
+  // mobile and the portrait crop ratio fits the screen better than landscape.
+  // Backend can still override via stepConfig.document_orientation.
+  const orientation: DocumentOrientation =
+    stepConfig?.document_orientation ?? 'portrait';
+  const captureMode = useMemo(
+    () => resolveCaptureModeFromStepConfig(stepConfig) ?? 'camera',
+    [stepConfig],
+  );
+  // File-picker mode is not supported in this port yet — we always go to the
+  // camera. The captureMode is captured for future iterations (e.g. fallback
+  // when the user rejects camera permission).
+  log.info('[DocumentsOCR] captureMode resolved', { captureMode });
+
+  const [phase, setPhase] = useState<Phase>('intro');
+  const [front, setFront] = useState<CapturedSide | null>(null);
+  const [back, setBack] = useState<CapturedSide | null>(null);
+  const [bannerError, setBannerError] = useState<string | null>(null);
+  const [busyLabel, setBusyLabel] = useState<string | null>(null);
+  const [retry, setRetry] = useState<{ message: string } | null>(null);
+
+  const handleCaptured = useCallback(
+    async (photo: PhotoFile, side: DocumentSide) => {
+      try {
+        const compressed = await compressJpeg(photo.path);
+        if (compressed.byteLength > MAX_BYTES) {
+          setBannerError(t.documents_ocr.fileTooLarge);
+          // Stay on the capture phase so the user can retake immediately.
+          return;
+        }
+        if (side === 'FRONT') {
+          setFront(compressed);
+          setPhase('reviewFront');
+        } else {
+          setBack(compressed);
+          setPhase('reviewBack');
+        }
+      } catch (err) {
+        const sdkErr = toSubmissionError(err, t);
+        setBannerError(sdkErr.message);
+      }
+    },
+    [t],
+  );
+
+  const submit = useCallback(async () => {
+    if (!front || !back) return;
+    setBannerError(null);
+    setBusyLabel(t.documents_ocr.initializing);
+    try {
+      const init = await api.post<DocumentsInitResponse>(
+        `/sessions/${sessionId}/documents-init`,
+        { document_type: DOCUMENTS_INIT_DOCUMENT_TYPE },
+      );
+      if (!init.front_side_upload_url || !init.back_side_upload_url) {
+        throw new Error('documents-init response missing signed URLs.');
+      }
+
+      setBusyLabel(t.documents_ocr.uploadingFront);
+      await uploadJpeg(front.uri, init.front_side_upload_url);
+
+      setBusyLabel(t.documents_ocr.uploadingBack);
+      await uploadJpeg(back.uri, init.back_side_upload_url);
+
+      setBusyLabel(t.documents_ocr.verifying);
+      await api.post(`/sessions/${sessionId}/documents-verify`, {});
+
+      setBusyLabel(null);
+      onComplete();
+    } catch (err) {
+      setBusyLabel(null);
+      const sdkErr: SdkError = {
+        code: SdkErrorCode.DOCUMENT_UPLOAD_FAILED,
+        message:
+          (err && typeof err === 'object' && 'message' in err
+            ? String((err as { message?: unknown }).message)
+            : '') || t.common.submissionFallback,
+        cause: err,
+      };
+      setBannerError(sdkErr.message);
+      setRetry({ message: sdkErr.message });
+    }
+  }, [api, back, front, onComplete, sessionId, t]);
+
+  if (retry) {
+    return (
+      <RetryDialog
+        title={t.common.submissionTitle}
+        message={retry.message || t.common.submissionFallback}
+        retryLabel={t.common.retry}
+        cancelLabel={t.common.cancel}
+        onRetry={() => setRetry(null)}
+        onCancel={() => {
+          setRetry(null);
+          onCancel({
+            code: SdkErrorCode.DOCUMENT_UPLOAD_FAILED,
+            message: retry.message,
+          });
+        }}
+      />
+    );
+  }
+
+  if (phase === 'captureFront' || phase === 'captureBack') {
+    const side: DocumentSide = phase === 'captureFront' ? 'FRONT' : 'BACK';
+    return (
+      <DocumentCapture
+        side={side}
+        orientation={orientation}
+        instructions={
+          side === 'FRONT'
+            ? t.documents_ocr.frontInstruction
+            : t.documents_ocr.backInstruction
+        }
+        captureLabel={t.documents_ocr.captureBtn}
+        permissionDeniedLabel={t.documents_ocr.cameraPermissionDenied}
+        retryLabel={t.documents_ocr.cameraTryAgain}
+        cancelLabel={t.common.cancel}
+        onCancel={() =>
+          setPhase(side === 'FRONT' ? 'intro' : 'reviewFront')
+        }
+        onCaptured={handleCaptured}
+      />
+    );
+  }
+
+  if (phase === 'reviewFront' || phase === 'reviewBack') {
+    const side: DocumentSide = phase === 'reviewFront' ? 'FRONT' : 'BACK';
+    const captured = side === 'FRONT' ? front : back;
+    if (!captured) {
+      // Defensive: should never happen but bail to capture if it does.
+      setPhase(side === 'FRONT' ? 'captureFront' : 'captureBack');
+      return <View />;
+    }
+    return (
+      <View style={[styles.reviewRoot, { backgroundColor: theme.backgroundColor }]}>
+        <Text style={[styles.reviewTitle, { color: theme.textColor }]}>
+          {side === 'FRONT' ? t.documents_ocr.frontTitle : t.documents_ocr.backTitle}
+        </Text>
+        <View style={styles.previewWrap}>
+          <Image
+            source={{ uri: captured.uri }}
+            style={styles.preview}
+            resizeMode="contain"
+          />
+        </View>
+        {bannerError ? <Banner message={bannerError} /> : null}
+        <View style={styles.reviewActions}>
+          <Button
+            variant="ghost"
+            label={t.documents_ocr.retakeBtn}
+            onPress={() =>
+              setPhase(side === 'FRONT' ? 'captureFront' : 'captureBack')
+            }
+            fullWidth={false}
+            style={styles.reviewBtn}
+          />
+          <Button
+            label={
+              side === 'FRONT'
+                ? t.documents_ocr.confirmFront
+                : t.documents_ocr.confirmBack
+            }
+            onPress={() => {
+              if (side === 'FRONT') {
+                setPhase('captureBack');
+              } else {
+                void submit();
+              }
+            }}
+            loading={Boolean(busyLabel)}
+            disabled={Boolean(busyLabel)}
+            fullWidth={false}
+            style={styles.reviewBtn}
+          />
+        </View>
+        {busyLabel ? <LoadingOverlay message={busyLabel} /> : null}
+      </View>
+    );
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <StepShell
+        title={t.documents_ocr.introTitle}
+        subtitle={t.documents_ocr.introSubtitle}
+        iconNode={<StepIcon name="badge" />}
+      >
+        <ScrollView style={styles.tipsScroll} contentContainerStyle={styles.tipsList}>
+          {t.documents_ocr.introTips.map((tip, idx) => (
+            <View
+              key={idx}
+              style={[
+                styles.tipRow,
+                {
+                  borderColor: theme.borderColor,
+                  backgroundColor: mixHex(
+                    theme.primaryColor,
+                    theme.backgroundColor,
+                    6,
+                  ),
+                  borderRadius: theme.borderRadiusPx,
+                },
+              ]}
+            >
+              <View
+                style={[
+                  styles.tipIcon,
+                  {
+                    backgroundColor: mixHex(
+                      theme.primaryColor,
+                      theme.backgroundColor,
+                      18,
+                    ),
+                  },
+                ]}
+              >
+                <Text style={[styles.tipIconText, { color: theme.primaryColor }]}>
+                  {idx + 1}
+                </Text>
+              </View>
+              <Text style={[styles.tipText, { color: theme.textColor }]}>
+                {tip}
+              </Text>
+            </View>
+          ))}
+        </ScrollView>
+        {bannerError ? <Banner message={bannerError} /> : null}
+        <Button
+          label={t.documents_ocr.introStart}
+          onPress={() => setPhase('captureFront')}
+        />
+      </StepShell>
+    </View>
+  );
+}
+
+async function compressJpeg(uri: string): Promise<CapturedSide> {
+  // Vision-camera produces 4 K JPEGs on modern phones — well past the 5 MB
+  // budget. Resize the long edge to 1800 px and recompress to ~78% quality;
+  // empirically that lands at < 600 KB while keeping OCR-grade legibility.
+  const result = await ImageManipulator.manipulateAsync(
+    normalizeFileUri(uri),
+    [{ resize: { width: MAX_LONG_EDGE } }],
+    { compress: COMPRESS_QUALITY, format: ImageManipulator.SaveFormat.JPEG },
+  );
+  const byteLength = await fetchByteLength(result.uri);
+  return {
+    uri: result.uri,
+    width: result.width,
+    height: result.height,
+    byteLength,
+  };
+}
+
+async function uploadJpeg(uri: string, signedUrl: string): Promise<void> {
+  const response = await fetch(uri);
+  if (!response.ok) {
+    throw new Error(`Could not read captured photo: HTTP ${response.status}`);
+  }
+  const blob = await response.blob();
+  const put = await fetch(signedUrl, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'image/jpeg' },
+    body: blob,
+  });
+  if (!put.ok) {
+    throw new Error(`Signed URL upload failed: HTTP ${put.status}`);
+  }
+}
+
+async function fetchByteLength(uri: string): Promise<number> {
+  const response = await fetch(uri);
+  if (!response.ok) return 0;
+  const blob = await response.blob();
+  return blob.size;
+}
+
+function normalizeFileUri(uri: string): string {
+  // Vision-camera returns paths with a leading `/var/mobile/...` on iOS
+  // (no scheme) — `expo-image-manipulator` requires a `file://` prefix.
+  if (uri.startsWith('file://') || uri.startsWith('http')) return uri;
+  if (Platform.OS === 'ios' || Platform.OS === 'android') {
+    return `file://${uri}`;
+  }
+  return uri;
+}
+
+const styles = StyleSheet.create({
+  tipsScroll: {
+    flexGrow: 0,
+  },
+  tipsList: {
+    paddingVertical: 4,
+    gap: 10,
+  },
+  tipRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 12,
+    padding: 12,
+    borderWidth: 1,
+  },
+  tipIcon: {
+    width: 32,
+    height: 32,
+    borderRadius: 16,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  tipIconText: {
+    fontSize: 14,
+    fontWeight: '700',
+  },
+  tipText: {
+    flex: 1,
+    fontSize: 14,
+    lineHeight: 20,
+  },
+  reviewRoot: {
+    flex: 1,
+    padding: 18,
+    gap: 14,
+  },
+  reviewTitle: {
+    fontSize: 18,
+    fontWeight: '700',
+    textAlign: 'center',
+  },
+  previewWrap: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  preview: {
+    width: '100%',
+    height: '100%',
+  },
+  reviewActions: {
+    flexDirection: 'row',
+    gap: 10,
+  },
+  reviewBtn: {
+    flex: 1,
+  },
+});

package/src/steps/EmailContactStep.tsx

@@ -0,0 +1,159 @@
+/**
+ * EMAIL_CONTACT — collect email without OTP. Mirrors `EmailContactModule.ts`.
+ * POST /sessions/:id/contact/email { email }
+ */
+
+import { useCallback, useState } from 'react';
+import { View } from 'react-native';
+import {
+  SdkErrorCode,
+  type EmailContactPayload,
+  type SdkError,
+} from '../types';
+import { Banner } from '../ui/primitives/Banner';
+import { Button } from '../ui/primitives/Button';
+import { Input } from '../ui/primitives/Input';
+import { LoadingOverlay } from '../ui/overlays/LoadingOverlay';
+import { RetryDialog } from '../ui/overlays/RetryDialog';
+import { StepShell } from '../ui/StepShell';
+import { StepIcon } from '../ui/icons/StepIcon';
+import { compose, required, useInlineValidation } from '../ui/forms';
+import { getStrings } from '../i18n';
+import type { ApiCaller } from '../transport/api';
+import type { StepDeps, StepModule } from './types';
+import { isEmail, toSubmissionError } from './_shared';
+
+export class EmailContactStep implements StepModule {
+  private resolveStep!: () => void;
+  private rejectStep!: (err: SdkError) => void;
+  private destroyed = false;
+
+  constructor(private readonly deps: StepDeps) {}
+
+  run(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.resolveStep = resolve;
+      this.rejectStep = reject;
+      this.deps.ui.setNode(
+        <EmailContactView
+          api={this.deps.api}
+          sessionId={this.deps.sessionId}
+          locale={this.deps.locale}
+          onComplete={() => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.resolveStep();
+          }}
+          onCancel={(err) => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.rejectStep(err);
+          }}
+        />,
+      );
+    });
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.deps.ui.setNode(null);
+  }
+}
+
+interface ViewProps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  onComplete: () => void;
+  onCancel: (err: SdkError) => void;
+}
+
+function EmailContactView({
+  api,
+  sessionId,
+  locale,
+  onComplete,
+  onCancel,
+}: ViewProps) {
+  const t = getStrings(locale);
+  const [email, setEmail] = useState('');
+  const [bannerError, setBannerError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [retry, setRetry] = useState<{ message: string } | null>(null);
+
+  const validation = useInlineValidation<'email'>(
+    [
+      {
+        name: 'email',
+        validate: compose(
+          required(t.email_contact.required),
+          (value) => (isEmail(value) ? null : t.email_contact.invalid),
+        ),
+      },
+    ],
+    (_n, v) => setEmail(v),
+  );
+
+  const handleSubmit = useCallback(async () => {
+    setBannerError(null);
+    if (!validation.validateAll({ email })) return;
+    const payload: EmailContactPayload = { email: email.trim() };
+    setSubmitting(true);
+    try {
+      await api.post(`/sessions/${sessionId}/contact/email`, payload);
+      setSubmitting(false);
+      onComplete();
+    } catch (err) {
+      setSubmitting(false);
+      const sdkErr = toSubmissionError(err, t);
+      setBannerError(sdkErr.message);
+      setRetry({ message: sdkErr.message });
+    }
+  }, [api, email, onComplete, sessionId, t, validation]);
+
+  if (retry) {
+    return (
+      <RetryDialog
+        title={t.common.submissionTitle}
+        message={retry.message || t.common.submissionFallback}
+        retryLabel={t.common.retry}
+        cancelLabel={t.common.cancel}
+        onRetry={() => setRetry(null)}
+        onCancel={() => {
+          setRetry(null);
+          onCancel({ code: SdkErrorCode.API_ERROR, message: retry.message });
+        }}
+      />
+    );
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <StepShell
+        title={t.email_contact.title}
+        subtitle={t.email_contact.hint}
+        iconNode={<StepIcon name="mail-outline" />}
+      >
+        <Input
+          label={t.email_contact.label}
+          required
+          autoCapitalize="none"
+          autoCorrect={false}
+          autoComplete="email"
+          textContentType="emailAddress"
+          keyboardType="email-address"
+          value={email}
+          {...validation.bind('email', email)}
+        />
+        {bannerError ? <Banner message={bannerError} /> : null}
+        <Button
+          label={t.common.continue}
+          onPress={handleSubmit}
+          loading={submitting}
+          disabled={submitting}
+        />
+      </StepShell>
+      {submitting ? <LoadingOverlay message={t.common.submitting} /> : null}
+    </View>
+  );
+}