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

package/src/steps/TaxInfoStep.tsx

@@ -0,0 +1,277 @@
+/**
+ * TAX_INFO — POST /sessions/:id/tax-info { taxpayer_type, taxpayer_id_type, taxpayer_id }.
+ *
+ * Mirrors `TaxInfoModule.ts`:
+ *   - Resolves selectable lists from `stepConfig.accepted_tax_information`
+ *     (only — no SDK-side defaults), preferring `code` → `id` for the option
+ *     value sent in the payload.
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+import { View } from 'react-native';
+import {
+  SdkErrorCode,
+  type SdkError,
+  type TaxInfoAcceptedCountryRow,
+  type TaxInfoConfigOptionRow,
+  type TaxInfoPayload,
+  type TaxInfoStepConfig,
+} from '../types';
+import { Banner } from '../ui/primitives/Banner';
+import { Button } from '../ui/primitives/Button';
+import { Input } from '../ui/primitives/Input';
+import { Select, type SelectOption } from '../ui/primitives/Select';
+import { LoadingOverlay } from '../ui/overlays/LoadingOverlay';
+import { RetryDialog } from '../ui/overlays/RetryDialog';
+import { StepShell } from '../ui/StepShell';
+import { StepIcon } from '../ui/icons/StepIcon';
+import { required, useInlineValidation } from '../ui/forms';
+import { getStrings } from '../i18n';
+import { resolveTaxInfoConfig } from '../utils/taxInfoConfig';
+import type { ApiCaller } from '../transport/api';
+import type { StepDeps, StepModule } from './types';
+import { toSubmissionError } from './_shared';
+
+export class TaxInfoStep 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(
+        <TaxInfoView
+          api={this.deps.api}
+          sessionId={this.deps.sessionId}
+          locale={this.deps.locale}
+          stepConfig={this.deps.stepConfig as TaxInfoStepConfig | 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);
+  }
+}
+
+function taxInfoOptionValue(row: TaxInfoConfigOptionRow): string | undefined {
+  const c = typeof row.code === 'string' ? row.code.trim() : '';
+  if (c) return c;
+  const i = typeof row.id === 'string' ? row.id.trim() : '';
+  if (i) return i;
+  return undefined;
+}
+
+function rowsToOptions(
+  rows: TaxInfoConfigOptionRow[] | undefined,
+): SelectOption[] {
+  if (!Array.isArray(rows)) return [];
+  const out: SelectOption[] = [];
+  for (const row of rows) {
+    const value = taxInfoOptionValue(row);
+    if (!value) continue;
+    out.push({
+      value,
+      label:
+        typeof row.display_value === 'string' && row.display_value.trim().length > 0
+          ? row.display_value
+          : value,
+    });
+  }
+  return out;
+}
+
+interface FormState {
+  taxpayer_type: string;
+  taxpayer_id_type: string;
+  taxpayer_id: string;
+}
+
+interface ViewProps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  stepConfig: TaxInfoStepConfig | undefined;
+  onComplete: () => void;
+  onCancel: (err: SdkError) => void;
+}
+
+function TaxInfoView({
+  api,
+  sessionId,
+  locale,
+  stepConfig,
+  onComplete,
+  onCancel,
+}: ViewProps) {
+  const t = getStrings(locale);
+
+  const { categoryOptions, idTypeOptions } = useMemo(() => {
+    const acceptedRows = stepConfig?.accepted_tax_information;
+    const rows: TaxInfoAcceptedCountryRow[] = Array.isArray(acceptedRows)
+      ? acceptedRows
+      : [];
+    let categoryOptions: SelectOption[] = [];
+    let idTypeOptions: SelectOption[] = [];
+    for (const row of rows) {
+      if (categoryOptions.length === 0) {
+        categoryOptions = rowsToOptions(row?.taxpayer_categories);
+      }
+      if (idTypeOptions.length === 0) {
+        idTypeOptions = rowsToOptions(row?.identification_types);
+      }
+      if (categoryOptions.length > 0 && idTypeOptions.length > 0) break;
+    }
+    const resolved = resolveTaxInfoConfig({
+      taxpayerCategories: categoryOptions.map((o) => ({
+        id: o.value,
+        description: o.label,
+      })),
+      fiscalIdentifierTypes: idTypeOptions.map((o) => ({
+        id: o.value,
+        description: o.label,
+      })),
+    });
+    return {
+      categoryOptions: resolved.taxpayerCategories.map(
+        (o): SelectOption => ({ value: o.id, label: o.description }),
+      ),
+      idTypeOptions: resolved.fiscalIdentifierTypes.map(
+        (o): SelectOption => ({ value: o.id, label: o.description }),
+      ),
+    };
+  }, [stepConfig]);
+
+  const [form, setForm] = useState<FormState>(() => ({
+    taxpayer_type: categoryOptions[0]?.value ?? '',
+    taxpayer_id_type: idTypeOptions[0]?.value ?? '',
+    taxpayer_id: '',
+  }));
+  const [bannerError, setBannerError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [retry, setRetry] = useState<{ message: string } | null>(null);
+
+  const setField = useCallback(
+    <K extends keyof FormState>(name: K, value: FormState[K]) => {
+      setForm((f) => ({ ...f, [name]: value }));
+    },
+    [],
+  );
+
+  const validation = useInlineValidation<keyof FormState>(
+    [
+      {
+        name: 'taxpayer_type',
+        validate: required(t.tax_info.requiredCategory),
+      },
+      {
+        name: 'taxpayer_id_type',
+        validate: required(t.tax_info.requiredIdType),
+      },
+      { name: 'taxpayer_id', validate: required(t.tax_info.requiredId) },
+    ],
+    (name, value) => setField(name, value),
+  );
+
+  const handleSubmit = useCallback(async () => {
+    setBannerError(null);
+    if (!validation.validateAll(form)) return;
+    const payload: TaxInfoPayload = {
+      taxpayer_type: form.taxpayer_type.trim(),
+      taxpayer_id_type: form.taxpayer_id_type.trim(),
+      taxpayer_id: form.taxpayer_id.trim(),
+    };
+    setSubmitting(true);
+    try {
+      await api.post(`/sessions/${sessionId}/tax-info`, payload);
+      setSubmitting(false);
+      onComplete();
+    } catch (err) {
+      setSubmitting(false);
+      const sdkErr = toSubmissionError(err, t);
+      setBannerError(sdkErr.message);
+      setRetry({ message: sdkErr.message });
+    }
+  }, [api, form, 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.tax_info.title}
+        subtitle={t.tax_info.subtitle}
+        iconNode={<StepIcon name="receipt-long" />}
+      >
+        <Select
+          label={t.tax_info.taxpayerType}
+          required
+          options={categoryOptions}
+          value={form.taxpayer_type || null}
+          onChange={(v) => {
+            setField('taxpayer_type', v);
+            validation.setFieldError('taxpayer_type', null);
+          }}
+          errorMessage={validation.errors.taxpayer_type ?? null}
+        />
+        <Select
+          label={t.tax_info.taxpayerIdType}
+          required
+          options={idTypeOptions}
+          value={form.taxpayer_id_type || null}
+          onChange={(v) => {
+            setField('taxpayer_id_type', v);
+            validation.setFieldError('taxpayer_id_type', null);
+          }}
+          errorMessage={validation.errors.taxpayer_id_type ?? null}
+        />
+        <Input
+          label={t.tax_info.taxpayerId}
+          required
+          autoCapitalize="characters"
+          autoCorrect={false}
+          value={form.taxpayer_id}
+          {...validation.bind('taxpayer_id', form.taxpayer_id)}
+        />
+        {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>
+  );
+}

package/src/steps/TermsAndConditionsStep.tsx

@@ -0,0 +1,261 @@
+/**
+ * TERMS_AND_CONDITIONS — POST /sessions/:id/terms-and-conditions { acceptances }.
+ *
+ * Mirrors `TermsAndConditionsModule.ts`:
+ *   - Items resolved from `stepConfig.terms`. If empty, the step rejects with
+ *     `SdkErrorCode.UNKNOWN` (same as web — orchestrator can surface support copy).
+ *   - Each item has an optional `link` opened via React Native's `Linking`
+ *     (no extra dependency, OS picks the right handler — WebView, Safari, …).
+ *   - Submit gate: every item must be accepted.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { Linking, Pressable, StyleSheet, Text, View } from 'react-native';
+import {
+  SdkErrorCode,
+  type SdkError,
+  type TermsAndConditionsItem,
+  type TermsAndConditionsStepConfig,
+  type TermsAndConditionsSubmitPayload,
+} from '../types';
+import { Banner } from '../ui/primitives/Banner';
+import { Button } from '../ui/primitives/Button';
+import { Checkbox } from '../ui/primitives/Checkbox';
+import { LoadingOverlay } from '../ui/overlays/LoadingOverlay';
+import { RetryDialog } from '../ui/overlays/RetryDialog';
+import { StepShell } from '../ui/StepShell';
+import { StepIcon } from '../ui/icons/StepIcon';
+import { getStrings } from '../i18n';
+import { useTheme } from '../ui/theme';
+import { resolveTermsFromStepConfig } from '../utils/stepConfig';
+import { log } from '../utils/log';
+import type { ApiCaller } from '../transport/api';
+import type { StepDeps, StepModule } from './types';
+import { toSubmissionError } from './_shared';
+
+export class TermsAndConditionsStep 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(
+        <TermsAndConditionsView
+          api={this.deps.api}
+          sessionId={this.deps.sessionId}
+          locale={this.deps.locale}
+          stepConfig={this.deps.stepConfig as TermsAndConditionsStepConfig | 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);
+          }}
+          onNoItems={(err) => {
+            if (this.destroyed) return;
+            // Match the web: don't unmount the empty-state banner — the
+            // orchestrator surfaces the error and the user backs out.
+            this.rejectStep(err);
+          }}
+        />,
+      );
+    });
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.deps.ui.setNode(null);
+  }
+}
+
+interface ViewProps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  stepConfig: TermsAndConditionsStepConfig | undefined;
+  onComplete: () => void;
+  onCancel: (err: SdkError) => void;
+  onNoItems: (err: SdkError) => void;
+}
+
+function TermsAndConditionsView({
+  api,
+  sessionId,
+  locale,
+  stepConfig,
+  onComplete,
+  onCancel,
+  onNoItems,
+}: ViewProps) {
+  const t = getStrings(locale);
+  const theme = useTheme();
+  const items: TermsAndConditionsItem[] = useMemo(
+    () => resolveTermsFromStepConfig(stepConfig) ?? [],
+    [stepConfig],
+  );
+
+  const [accepted, setAccepted] = useState<Record<string, boolean>>({});
+  const [bannerError, setBannerError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [retry, setRetry] = useState<{ message: string } | null>(null);
+
+  // No items → surface the error. Don't navigate away from the screen so the
+  // user has context (matching the web flow).
+  useEffect(() => {
+    if (items.length === 0) {
+      onNoItems({
+        code: SdkErrorCode.UNKNOWN,
+        message: t.terms_and_conditions.noItems,
+      });
+    }
+  }, [items.length, onNoItems, t]);
+
+  const handleOpenLink = useCallback(async (url: string) => {
+    try {
+      const supported = await Linking.canOpenURL(url);
+      if (supported) {
+        await Linking.openURL(url);
+      } else {
+        log.warn('[T&C] Cannot open link', { url });
+      }
+    } catch (err) {
+      log.warn('[T&C] Failed to open link', err);
+    }
+  }, []);
+
+  const handleSubmit = useCallback(async () => {
+    setBannerError(null);
+    const payload: TermsAndConditionsSubmitPayload = {
+      acceptances: items.map((item) => ({
+        item_id: item.id,
+        accepted: accepted[item.id] === true,
+      })),
+    };
+    if (!payload.acceptances.every((a) => a.accepted)) {
+      setBannerError(t.terms_and_conditions.needAll);
+      return;
+    }
+    setSubmitting(true);
+    try {
+      await api.post(
+        `/sessions/${sessionId}/terms-and-conditions`,
+        payload,
+      );
+      setSubmitting(false);
+      onComplete();
+    } catch (err) {
+      setSubmitting(false);
+      const sdkErr = toSubmissionError(err, t);
+      setBannerError(sdkErr.message);
+      setRetry({ message: sdkErr.message });
+    }
+  }, [accepted, api, items, 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.API_ERROR, message: retry.message });
+        }}
+      />
+    );
+  }
+
+  if (items.length === 0) {
+    return (
+      <StepShell
+        title={t.terms_and_conditions.title}
+        subtitle={t.terms_and_conditions.subtitle}
+        iconNode={<StepIcon name="description" />}
+      >
+        <Banner message={t.terms_and_conditions.noItems} />
+      </StepShell>
+    );
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <StepShell
+        title={t.terms_and_conditions.title}
+        subtitle={t.terms_and_conditions.subtitle}
+        iconNode={<StepIcon name="description" />}
+      >
+        {items.map((item) => (
+          <View
+            key={item.id}
+            style={[
+              styles.itemBlock,
+              { borderTopColor: theme.borderColor },
+            ]}
+          >
+            <Text style={[styles.description, { color: theme.textColor }]}>
+              {item.description}
+            </Text>
+            {item.link ? (
+              <Pressable
+                accessibilityRole="link"
+                onPress={() => handleOpenLink(item.link as string)}
+                style={styles.linkRow}
+              >
+                <Text style={[styles.link, { color: theme.primaryColor }]}>
+                  {t.terms_and_conditions.openLink}
+                </Text>
+              </Pressable>
+            ) : null}
+            <Checkbox
+              variant="inline"
+              checked={accepted[item.id] === true}
+              onChange={(next) =>
+                setAccepted((prev) => ({ ...prev, [item.id]: next }))
+              }
+              label={t.terms_and_conditions.accept}
+            />
+          </View>
+        ))}
+        {bannerError ? <Banner message={bannerError} /> : null}
+        <Button
+          label={t.common.confirm}
+          onPress={handleSubmit}
+          loading={submitting}
+          disabled={submitting}
+        />
+      </StepShell>
+      {submitting ? <LoadingOverlay message={t.common.submitting} /> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  itemBlock: {
+    paddingVertical: 12,
+    borderTopWidth: StyleSheet.hairlineWidth,
+    gap: 6,
+  },
+  description: {
+    fontSize: 14,
+    lineHeight: 20,
+  },
+  linkRow: {
+    paddingVertical: 4,
+  },
+  link: {
+    fontSize: 14,
+    fontWeight: '500',
+    textDecorationLine: 'underline',
+  },
+});

package/src/steps/_shared.ts

@@ -0,0 +1,44 @@
+/**
+ * Helpers shared by every step module — kept in a single place so the per-step
+ * files stay focused on their specific UI + payload.
+ */
+
+import { SdkErrorCode, type SdkError } from '../types';
+import type { StringsTable } from '../i18n';
+
+export function toSubmissionError(err: unknown, t: StringsTable): SdkError {
+  if (
+    err != null &&
+    typeof err === 'object' &&
+    'code' in err &&
+    typeof (err as SdkError).code === 'string' &&
+    'message' in err &&
+    typeof (err as SdkError).message === 'string'
+  ) {
+    return err as SdkError;
+  }
+  const message =
+    err instanceof Error ? err.message : t.common.submissionFallback;
+  return {
+    code: SdkErrorCode.API_ERROR,
+    message: message || t.common.submissionFallback,
+    cause: err,
+  };
+}
+
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** Backend accepts any reasonably-shaped E.164 — keep this check loose. */
+const E164_REGEX = /^\+[1-9]\d{6,14}$/;
+const OTP_REGEX = /^\d{6}$/;
+
+export function isEmail(value: string): boolean {
+  return EMAIL_REGEX.test(value.trim());
+}
+
+export function isE164Phone(value: string): boolean {
+  return E164_REGEX.test(value.trim());
+}
+
+export function isOtpCode(value: string): boolean {
+  return OTP_REGEX.test(value.trim());
+}

package/src/steps/types.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Internal contracts shared by all step modules.
+ *
+ * Step modules own their network lifecycle and (when applicable) drive the UI
+ * via a `StepUiHandle` provided by the orchestrator. Modules that don't need
+ * a screen (e.g. DEVICE_FINGERPRINT, FACE_MATCH) ignore the UI handle entirely.
+ */
+
+import type { ReactNode } from 'react';
+import type { ApiCaller } from '../transport/api';
+import type { OnboardingStep, SdkError } from '../types';
+
+/**
+ * Internal contract every step module must implement. The orchestrator awaits
+ * `run()` and calls `destroy()` exactly once when the step is leaving the flow.
+ */
+export interface StepModule {
+  run(): Promise<void>;
+  destroy(): void;
+}
+
+/**
+ * Bridge a step module uses to render its UI inside `VelionOnboardingScreen`.
+ *
+ * - `setNode(node)` mounts a React subtree as the active step view.
+ * - `setNode(null)` (or omitting all calls) leaves whatever the orchestrator
+ *   considers the default chrome — typically a loading overlay.
+ *
+ * The orchestrator clears the slot automatically between steps, so modules
+ * don't need to call `setNode(null)` on `destroy()` for cleanup purposes.
+ */
+export interface StepUiHandle {
+  setNode(node: ReactNode | null): void;
+}
+
+/** Constructor arguments shared by every step module. */
+export interface StepDeps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  colorMode: 'light' | 'dark';
+  ui: StepUiHandle;
+  step: OnboardingStep;
+  stepConfig?: Record<string, unknown>;
+  /**
+   * Google Maps Platform API key (Maps + Places). Forwarded to the assisted
+   * `ADDRESS_INFO` flow when the consumer passes it via `VelionConfig`. Steps
+   * that don't use it can ignore the field.
+   */
+  googleMapsApiKey?: string;
+  /**
+   * Fingerprint Pro endpoint URL (custom subdomain). Defaults to
+   * `https://fp.velion.la`. Only read by `FingerprintStep`.
+   */
+  fingerprintEndpoint?: string;
+  /** Override of the public Fingerprint Pro key. Only read by `FingerprintStep`. */
+  fingerprintApiKey?: string;
+  /** Per-call timeout for Fingerprint identification. Only read by `FingerprintStep`. */
+  fingerprintTimeoutMs?: number;
+  /**
+   * Optional Iris calibration tag for LIVENESS_MATCH. See
+   * `VelionConfig.livenessCalibrationLabel` for details. Only read by
+   * `LivenessMatchStep`.
+   */
+  livenessCalibrationLabel?: string;
+}
+
+/**
+ * Convenience type used by step modules that propagate failures to the
+ * orchestrator. The orchestrator translates these into `onError` calls.
+ */
+export type StepFailure = SdkError;