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

package/src/core/sessionDeclinedCopy.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Default and merged copy for the SESSION_DECLINED SSE error screen.
+ */
+
+import type { VelionSessionDeclinedReasonTexts } from '../types';
+import { SESSION_DECLINED_REASON_MESSAGES } from './sseReasonMessages';
+
+export interface ResolvedSessionDeclinedCopy {
+  title: string;
+  message: string;
+  dismissLabel: string;
+}
+
+function isEnglishLocale(locale: string | undefined): boolean {
+  return (locale ?? 'es').toLowerCase().startsWith('en');
+}
+
+function humanizeStepFailedCode(reasonKey: string): string {
+  return reasonKey.replace(/_FAILED$/iu, '').replace(/_/g, ' ').toLowerCase();
+}
+
+function stepFailedFallback(reasonKey: string, lang: 'en' | 'es'): { title: string; message: string } {
+  const stepLabel = humanizeStepFailedCode(reasonKey);
+  if (lang === 'en') {
+    return {
+      title: 'We could not complete this step',
+      message: `The verification step (${stepLabel}) did not complete successfully. Please try again or contact support.`,
+    };
+  }
+  return {
+    title: 'No pudimos completar este paso',
+    message: `El paso de verificación (${stepLabel}) no se completó correctamente. Intentá de nuevo o contactá a soporte.`,
+  };
+}
+
+function pickDeclineDefaults(
+  reasonKey: string,
+  lang: 'en' | 'es',
+): { title: string; message: string } | undefined {
+  const fromMap = SESSION_DECLINED_REASON_MESSAGES[reasonKey]?.[lang];
+  if (fromMap) return fromMap;
+  if (/_FAILED$/iu.test(reasonKey)) {
+    return stepFailedFallback(reasonKey, lang);
+  }
+  return undefined;
+}
+
+/**
+ * Resolves title, body, and dismiss label for a SESSION_DECLINED screen.
+ */
+export function resolveSessionDeclinedCopy(
+  locale: string | undefined,
+  texts: VelionSessionDeclinedReasonTexts | undefined,
+  reason: string | undefined,
+  /** Same dismiss as `VelionFinalResultScreenTexts.dismissLabel` when set. */
+  finalResultDismissLabel?: string,
+): ResolvedSessionDeclinedCopy {
+  const lang = isEnglishLocale(locale) ? 'en' : 'es';
+  const reasonKey = reason ?? '';
+  const defaults = pickDeclineDefaults(reasonKey, lang);
+  const override = reason ? texts?.[reason]?.[lang] : undefined;
+  const dismissLabel =
+    finalResultDismissLabel ?? (isEnglishLocale(locale) ? 'Got it' : 'Entendido');
+  return {
+    title: override?.title ?? defaults?.title ?? (isEnglishLocale(locale)
+      ? 'We could not continue'
+      : 'No pudimos continuar'),
+    message:
+      override?.message ??
+      defaults?.message ??
+      (isEnglishLocale(locale)
+        ? 'This session could not be completed. Please try again or contact support.'
+        : 'No se pudo completar esta sesión. Intentá de nuevo o contactá a soporte.'),
+    dismissLabel,
+  };
+}

package/src/core/sessionStateMapper.ts

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Maps backend OnboardingDto (GET /sessions/:id) to SDK SessionState.
+ */
+
+import type {
+  OnboardingDtoResponse,
+  OnboardingResult,
+  OnboardingStep,
+  SessionState,
+  OnboardingType,
+  StepConfigMap,
+} from '../types';
+
+const TERMINAL_STEP_STATUSES = new Set(['COMPLETED', 'SKIPPED']);
+
+/**
+ * Maps the onboarding DTO returned by GET /sessions/:sessionId to the
+ * SessionState shape used by the step machine.
+ */
+export function mapOnboardingDtoToSessionState(
+  dto: OnboardingDtoResponse,
+): SessionState {
+  const steps = dto.steps ?? [];
+  const sorted = [...steps].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+
+  const onboardingType = dto.onboarding_type as OnboardingType | undefined;
+  const validType: OnboardingType | undefined =
+    onboardingType === 'HUMAN' || onboardingType === 'LEGAL'
+      ? onboardingType
+      : undefined;
+
+  const stepConfigs: StepConfigMap = {};
+
+  for (const s of sorted) {
+    const code = s.code as OnboardingStep | undefined;
+    if (!code || typeof code !== 'string') continue;
+    if (s.result && typeof s.result === 'object') {
+      stepConfigs[code] = s.result;
+    }
+    const maybeConfig = (s as unknown as { config?: Record<string, unknown> }).config;
+    if (maybeConfig && typeof maybeConfig === 'object') {
+      stepConfigs[code] = maybeConfig;
+    }
+  }
+
+  const currentStepCode = dto.current_step?.code;
+  const currentStep =
+    typeof currentStepCode === 'string'
+      ? (currentStepCode as OnboardingStep)
+      : resolveCurrentStepFromLegacySteps(sorted);
+  const currentStepConfig =
+    dto.current_step?.config && typeof dto.current_step.config === 'object'
+      ? dto.current_step.config
+      : currentStep
+        ? stepConfigs[currentStep]
+        : undefined;
+  if (currentStep && currentStepConfig) {
+    stepConfigs[currentStep] = currentStepConfig;
+  }
+
+  const allowedParentOrigins = Array.isArray(dto.allowed_parent_origins)
+    ? dto.allowed_parent_origins.filter(
+        (o): o is string => typeof o === 'string' && o.length > 0,
+      )
+    : undefined;
+
+  const state: SessionState = {
+    ...(currentStep !== undefined && { currentStep }),
+    ...(currentStepConfig !== undefined && { currentStepConfig }),
+    ...(Object.keys(stepConfigs).length > 0 && { stepConfigs }),
+    ...(validType !== undefined && { onboardingType: validType }),
+    ...(dto.metadata !== undefined && { metadata: dto.metadata }),
+    ...(allowedParentOrigins !== undefined && { allowedParentOrigins }),
+  };
+  return state;
+}
+
+function resolveCurrentStepFromLegacySteps(
+  sorted: Array<{ code: string; status?: string }>,
+): OnboardingStep | undefined {
+  for (const s of sorted) {
+    const status = s.status;
+    if (!status || !TERMINAL_STEP_STATUSES.has(status)) {
+      return s.code as OnboardingStep;
+    }
+  }
+  const last = sorted.at(-1);
+  return last?.code as OnboardingStep | undefined;
+}
+
+/**
+ * Maps GET /sessions `status` to {@link OnboardingResult.status}.
+ * Unknown values fall back to `MANUAL_REVIEW`.
+ */
+export function mapSessionDtoStatusToResultStatus(
+  raw: string | undefined,
+): OnboardingResult['status'] {
+  const s = typeof raw === 'string' ? raw.trim().toUpperCase() : '';
+  if (s === 'APPROVED') return 'APPROVED';
+  if (s === 'MANUAL_REVIEW' || s === 'IN_REVIEW') return 'MANUAL_REVIEW';
+  if (s === 'REJECTED') return 'REJECTED';
+  if (s === 'DECLINED') return 'DECLINED';
+  return 'MANUAL_REVIEW';
+}
+
+/**
+ * True when GET session has no runnable step but onboarding is already finished
+ * (no `current_step` expected).
+ */
+export function isTerminalSessionStatusFromDto(raw: string | undefined): boolean {
+  const s = typeof raw === 'string' ? raw.trim().toUpperCase() : '';
+  return (
+    s === 'APPROVED' ||
+    s === 'MANUAL_REVIEW' ||
+    s === 'REJECTED' ||
+    s === 'DECLINED' ||
+    s === 'IN_REVIEW'
+  );
+}
+
+/**
+ * True when the SDK must run workflow steps; backend should send `current_step`.
+ */
+export function requiresCurrentStepForSessionStatus(raw: string | undefined): boolean {
+  const s = typeof raw === 'string' ? raw.trim().toUpperCase() : '';
+  return s === 'INITIATED' || s === 'IN_PROGRESS';
+}
+
+/**
+ * Builds OnboardingResult from the same onboarding DTO when status is terminal.
+ */
+export function mapOnboardingDtoToResult(
+  dto: OnboardingDtoResponse,
+  sessionId: string,
+): OnboardingResult {
+  const terminal = mapSessionDtoStatusToResultStatus(dto.status);
+  return buildResultFromDto(dto, sessionId, terminal);
+}
+
+/**
+ * Builds OnboardingResult using completed_at and referenceId from the DTO
+ * but with an explicit terminal status (e.g. from a terminal SSE event).
+ */
+export function mapOnboardingDtoToResultWithStatus(
+  dto: OnboardingDtoResponse,
+  sessionId: string,
+  terminalStatus: OnboardingResult['status'],
+  terminalReason?: string,
+): OnboardingResult {
+  return buildResultFromDto(dto, sessionId, terminalStatus, terminalReason);
+}
+
+function buildResultFromDto(
+  dto: OnboardingDtoResponse,
+  sessionId: string,
+  terminal: OnboardingResult['status'],
+  terminalReason?: string,
+): OnboardingResult {
+  return {
+    sessionId,
+    completedAt: dto.completed_at ?? new Date().toISOString(),
+    status: terminal,
+    ...(dto.id !== undefined && dto.id !== '' && { referenceId: String(dto.id) }),
+    ...(terminalReason !== undefined &&
+      terminalReason.trim() !== '' && { terminalReason: terminalReason.trim() }),
+  };
+}