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

package/src/steps/EmailOtpStep.tsx

@@ -0,0 +1,250 @@
+/**
+ * EMAIL_OTP — send + verify 6-digit OTP via email.
+ * POST /sessions/:id/email/send-otp { email }
+ * POST /sessions/:id/email/verify-otp { otp }
+ *
+ * Mirrors `EmailOtpModule.ts`. Single-screen flow: `Send code` first, then a
+ * second pane appears with the 6-digit input + `Verify`. iOS gets
+ * `textContentType="oneTimeCode"` so the system keyboard surfaces the SMS-/
+ * email-delivered code automatically.
+ */
+
+import { useCallback, useState } from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { SdkErrorCode, 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 { useTheme } from '../ui/theme';
+import type { ApiCaller } from '../transport/api';
+import type { StepDeps, StepModule } from './types';
+import { isEmail, isOtpCode, toSubmissionError } from './_shared';
+
+export class EmailOtpStep 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(
+        <EmailOtpView
+          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 EmailOtpView({
+  api,
+  sessionId,
+  locale,
+  onComplete,
+  onCancel,
+}: ViewProps) {
+  const t = getStrings(locale);
+  const theme = useTheme();
+  const [email, setEmail] = useState('');
+  const [otp, setOtp] = useState('');
+  const [stage, setStage] = useState<'request' | 'verify'>('request');
+  const [bannerError, setBannerError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<null | 'sending' | 'verifying'>(null);
+  const [retry, setRetry] = useState<{ message: string } | null>(null);
+
+  const emailValidation = useInlineValidation<'email'>(
+    [
+      {
+        name: 'email',
+        validate: compose(
+          required(t.email_otp.emailRequired),
+          (v) => (isEmail(v) ? null : t.email_contact.invalid),
+        ),
+      },
+    ],
+    (_n, v) => setEmail(v),
+  );
+
+  const otpValidation = useInlineValidation<'otp'>(
+    [
+      {
+        name: 'otp',
+        validate: compose(
+          required(t.email_otp.otpRequired),
+          (v) => (isOtpCode(v) ? null : t.email_otp.otpFormat),
+        ),
+      },
+    ],
+    (_n, v) => setOtp(v),
+  );
+
+  const sendOtp = useCallback(async () => {
+    setBannerError(null);
+    if (!emailValidation.validateAll({ email })) return;
+    setBusy('sending');
+    try {
+      await api.post(`/sessions/${sessionId}/email/send-otp`, {
+        email: email.trim(),
+      });
+      setBusy(null);
+      setStage('verify');
+    } catch (err) {
+      setBusy(null);
+      const sdkErr = toSubmissionError(err, t);
+      setBannerError(sdkErr.message);
+      setRetry({ message: sdkErr.message });
+    }
+  }, [api, email, emailValidation, sessionId, t]);
+
+  const verifyOtp = useCallback(async () => {
+    setBannerError(null);
+    if (!otpValidation.validateAll({ otp })) return;
+    setBusy('verifying');
+    try {
+      await api.post(`/sessions/${sessionId}/email/verify-otp`, {
+        otp: otp.trim(),
+      });
+      setBusy(null);
+      onComplete();
+    } catch (err) {
+      setBusy(null);
+      const sdkErr = toSubmissionError(err, t);
+      setBannerError(sdkErr.message);
+    }
+  }, [api, onComplete, otp, otpValidation, 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.API_ERROR, message: retry.message });
+        }}
+      />
+    );
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <StepShell
+        title={t.email_otp.title}
+        subtitle={t.email_otp.emailHint}
+        iconNode={<StepIcon name="mail-outline" />}
+      >
+        <Input
+          label={t.email_otp.emailLabel}
+          required
+          autoCapitalize="none"
+          autoCorrect={false}
+          autoComplete="email"
+          textContentType="emailAddress"
+          keyboardType="email-address"
+          editable={stage === 'request'}
+          value={email}
+          {...emailValidation.bind('email', email)}
+        />
+        {stage === 'request' ? (
+          <Button
+            label={t.email_otp.sendCode}
+            onPress={sendOtp}
+            loading={busy === 'sending'}
+            disabled={busy !== null}
+          />
+        ) : (
+          <>
+            <Input
+              label={t.email_otp.otpLabel}
+              required
+              autoCapitalize="none"
+              autoCorrect={false}
+              keyboardType="number-pad"
+              textContentType="oneTimeCode"
+              maxLength={6}
+              value={otp}
+              {...otpValidation.bind('otp', otp)}
+            />
+            {bannerError ? <Banner message={bannerError} /> : null}
+            <Button
+              label={t.email_otp.verify}
+              onPress={verifyOtp}
+              loading={busy === 'verifying'}
+              disabled={busy !== null}
+            />
+            <Pressable
+              accessibilityRole="link"
+              onPress={() => {
+                setOtp('');
+                setStage('request');
+              }}
+              style={styles.resend}
+            >
+              <Text style={[styles.resendText, { color: theme.primaryColor }]}>
+                {t.email_otp.resend}
+              </Text>
+            </Pressable>
+          </>
+        )}
+        {stage === 'request' && bannerError ? (
+          <Banner message={bannerError} />
+        ) : null}
+      </StepShell>
+      {busy ? (
+        <LoadingOverlay
+          message={busy === 'sending' ? t.email_otp.sendingCode : t.email_otp.verifying}
+        />
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  resend: {
+    paddingVertical: 8,
+    alignItems: 'center',
+  },
+  resendText: {
+    fontSize: 14,
+    fontWeight: '500',
+    textDecorationLine: 'underline',
+  },
+});

package/src/steps/FaceMatchStep.tsx

@@ -0,0 +1,177 @@
+/**
+ * FACE_MATCH — backend-only step.
+ *
+ * The web `FaceMatchModule` polls `GET /sessions/:id` every 2s and resolves
+ * once the step is COMPLETED / SKIPPED (or session terminal). In the RN port
+ * the orchestrator already drains pending terminal events through SSE and
+ * routes via `ROUTING_COMMAND`, so we can keep this step minimal: just show
+ * a "Procesando…" panel and await the SSE-driven step transition.
+ *
+ * As a safety net we still poll GET every 2s up to 6 min — same upper bound
+ * as the web (`MAX_POLLS=180`). When the orchestrator emits `ROUTING_COMMAND`
+ * for the next step, `VelionOnboarding` calls `destroy()` which aborts the
+ * poll loop.
+ */
+
+import { useEffect, useRef } from 'react';
+import { ActivityIndicator, StyleSheet, Text, View } from 'react-native';
+import {
+  SdkErrorCode,
+  type OnboardingDtoResponse,
+  type SdkError,
+} from '../types';
+import { getStrings } from '../i18n';
+import { useTheme } from '../ui/theme';
+import { log } from '../utils/log';
+import type { StepDeps, StepModule } from './types';
+
+const POLL_MS = 2_000;
+const MAX_POLLS = 180;
+
+export class FaceMatchStep implements StepModule {
+  private resolveStep!: () => void;
+  private rejectStep!: (err: SdkError) => void;
+  private destroyed = false;
+  private abortController = new AbortController();
+
+  constructor(private readonly deps: StepDeps) {}
+
+  run(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.resolveStep = resolve;
+      this.rejectStep = reject;
+      this.deps.ui.setNode(<FaceMatchView locale={this.deps.locale} />);
+      void this.poll();
+    });
+  }
+
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.abortController.abort();
+    this.deps.ui.setNode(null);
+  }
+
+  private async poll(): Promise<void> {
+    const t = getStrings(this.deps.locale);
+    for (let i = 0; i < MAX_POLLS; i += 1) {
+      if (this.destroyed) return;
+      try {
+        const dto = await this.deps.api.get<OnboardingDtoResponse>(
+          `/sessions/${this.deps.sessionId}`,
+          {
+            signal: this.abortController.signal,
+            extraHeaders: {
+              'Cache-Control': 'no-cache, no-store, must-revalidate',
+              Pragma: 'no-cache',
+            },
+          },
+        );
+        const status = (dto.status ?? '').toUpperCase();
+        if (status === 'REJECTED') {
+          this.rejectStep({
+            code: SdkErrorCode.API_ERROR,
+            message:
+              this.deps.locale === 'en'
+                ? 'Session was rejected during face match.'
+                : 'La sesión fue rechazada durante la verificación facial.',
+          });
+          return;
+        }
+        if (status === 'APPROVED' || status === 'MANUAL_REVIEW') {
+          this.resolveStep();
+          return;
+        }
+        const face = (dto.steps ?? []).find((s) => s.code === 'FACE_MATCH');
+        const stepStatus = face?.status?.toUpperCase();
+        if (stepStatus === 'COMPLETED' || stepStatus === 'SKIPPED') {
+          this.resolveStep();
+          return;
+        }
+        if (stepStatus === 'FAILED') {
+          this.rejectStep({
+            code: SdkErrorCode.API_ERROR,
+            message:
+              this.deps.locale === 'en'
+                ? 'Face match step failed.'
+                : 'La verificación facial no pudo completarse.',
+          });
+          return;
+        }
+      } catch (err) {
+        if (this.destroyed) return;
+        const name = (err as { name?: string } | null)?.name;
+        if (name === 'AbortError') return;
+        log.warn('[FaceMatch] poll failed', err);
+      }
+      if (this.destroyed) return;
+      await sleep(POLL_MS);
+    }
+    if (!this.destroyed) {
+      this.rejectStep({
+        code: SdkErrorCode.UNKNOWN,
+        message:
+          this.deps.locale === 'en'
+            ? 'Timed out waiting for face match to complete.'
+            : 'Tiempo de espera agotado para la verificación facial.',
+      });
+    }
+    log.info('[FaceMatch] gave up after', MAX_POLLS, 'polls', t.common.finalizing);
+  }
+}
+
+interface ViewProps {
+  locale: string;
+}
+
+function FaceMatchView({ locale }: ViewProps) {
+  const theme = useTheme();
+  const t = getStrings(locale);
+  // Keep the spinner mounted until the orchestrator unmounts the step node.
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  return (
+    <View style={[styles.root, { backgroundColor: theme.backgroundColor }]}>
+      <ActivityIndicator size="large" color={theme.primaryColor} />
+      <Text style={[styles.title, { color: theme.textColor }]}>
+        {locale.toLowerCase().startsWith('en')
+          ? 'Verifying your face'
+          : 'Verificando tu rostro'}
+      </Text>
+      <Text style={[styles.body, { color: theme.textSecondaryColor }]}>
+        {t.common.finalizing}
+      </Text>
+    </View>
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 24,
+    gap: 14,
+  },
+  title: {
+    fontSize: 18,
+    fontWeight: '600',
+    textAlign: 'center',
+    marginTop: 8,
+  },
+  body: {
+    fontSize: 14,
+    textAlign: 'center',
+    lineHeight: 20,
+    maxWidth: 320,
+  },
+});

package/src/steps/FingerprintStep.tsx

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview DEVICE_FINGERPRINT step.
+ *
+ * Runs Fingerprint Pro RN to obtain `requestId` (+ optional `sealedResult`)
+ * and POSTs them to `/sessions/:id/fingerprint`. The backend uses these to
+ * enrich the session with AML / fraud signals via Fingerprint server-side
+ * decryption.
+ *
+ * Mounts a centred LoadingOverlay with a "Evaluating your device" message so
+ * the user understands why the screen is blocked for a couple of seconds.
+ * Without it, slow networks / VPNs make the SDK feel frozen.
+ *
+ * Defaults: Velion's public Fingerprint Pro key + `https://fp.velion.la` as
+ * endpoint. Override knobs: `fingerprintApiKey`, `fingerprintEndpoint` and
+ * `fingerprintTimeoutMs` in `VelionConfig`.
+ */
+
+import { LoadingOverlay } from '../ui/overlays/LoadingOverlay';
+import { getStrings } from '../i18n';
+import { SdkErrorCode, type SdkError } from '../types';
+import {
+  generateDeviceFingerprint,
+  type DeviceFingerprintResult,
+} from '../utils/deviceFingerprint';
+import { log } from '../utils/log';
+import type { StepDeps, StepModule } from './types';
+
+/** Default Velion-managed Fingerprint endpoint (proxy with TLS termination). */
+const DEFAULT_FINGERPRINT_ENDPOINT = 'https://fp.velion.la';
+
+interface FingerprintSubmitPayload {
+  request_id: string;
+  sealed_result?: string;
+}
+
+export class FingerprintStep implements StepModule {
+  private destroyed = false;
+
+  constructor(private readonly deps: StepDeps) {}
+
+  async run(): Promise<void> {
+    if (this.destroyed) return;
+    log.info('[FingerprintStep] generating device fingerprint');
+
+    const t = getStrings(this.deps.locale);
+    this.deps.ui.setNode(<LoadingOverlay message={t.fingerprint.evaluating} />);
+
+    let result: DeviceFingerprintResult;
+    try {
+      result = await generateDeviceFingerprint({
+        endpoint: this.deps.fingerprintEndpoint ?? DEFAULT_FINGERPRINT_ENDPOINT,
+        ...(this.deps.fingerprintApiKey !== undefined && {
+          apiKey: this.deps.fingerprintApiKey,
+        }),
+        ...(this.deps.fingerprintTimeoutMs !== undefined && {
+          timeoutMs: this.deps.fingerprintTimeoutMs,
+        }),
+      });
+    } catch (err) {
+      this.deps.ui.setNode(null);
+      // generateDeviceFingerprint already throws shaped SdkError; rethrow as-is
+      // so the orchestrator can route through `emitError` without re-wrapping.
+      if (typeof err === 'object' && err !== null && 'code' in err) {
+        throw err;
+      }
+      throw {
+        code: SdkErrorCode.FINGERPRINT_FAILED,
+        message: 'Could not generate the device fingerprint.',
+        cause: err,
+      } satisfies SdkError;
+    }
+
+    if (this.destroyed) {
+      this.deps.ui.setNode(null);
+      return;
+    }
+    log.info('[FingerprintStep] POST /fingerprint', {
+      hasSealedResult: result.sealed_result !== undefined,
+    });
+
+    const payload: FingerprintSubmitPayload = { request_id: result.request_id };
+    if (result.sealed_result !== undefined) {
+      payload.sealed_result = result.sealed_result;
+    }
+
+    try {
+      await this.deps.api.post(
+        `/sessions/${this.deps.sessionId}/fingerprint`,
+        payload,
+      );
+    } finally {
+      this.deps.ui.setNode(null);
+    }
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+  }
+}