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

package/src/core/VelionOnboarding.ts

@@ -0,0 +1,974 @@
+/**
+ * @fileoverview VelionOnboarding — orchestrator for the React Native SDK.
+ *
+ * Platform-agnostic dynamic state machine: deals with HTTP, SSE, dedupe and
+ * step-module orchestration. UI mounting is delegated to a React component
+ * (`VelionOnboardingScreen`) instead of direct DOM manipulation.
+ *
+ * Invariants:
+ *   - SSE dedupe by `event_id` (monotonic)
+ *   - Suppress duplicate `NEXT_STEP` for the just-completed step
+ *   - 45 s watchdog for terminal SSE event after final step → fallback GET
+ *   - SESSION_DECLINED handling races with module.run()
+ */
+
+import { TypedEventEmitter } from '../utils/EventEmitter';
+import { createApiCaller, type ApiCaller } from '../transport/api';
+import { setDebugEnabled, log } from '../utils/log';
+import {
+  mapOnboardingDtoToSessionState,
+  mapOnboardingDtoToResult,
+  mapOnboardingDtoToResultWithStatus,
+  isTerminalSessionStatusFromDto,
+  requiresCurrentStepForSessionStatus,
+} from './sessionStateMapper';
+import { createSessionEventSource } from '../transport/sse';
+import { resolveSessionDeclinedCopy } from './sessionDeclinedCopy';
+import { FingerprintStep } from '../steps/FingerprintStep';
+import { HumanBasicInfoStep } from '../steps/HumanBasicInfoStep';
+import { EmailContactStep } from '../steps/EmailContactStep';
+import { PhoneContactStep } from '../steps/PhoneContactStep';
+import { EmailOtpStep } from '../steps/EmailOtpStep';
+import { PhoneOtpStep } from '../steps/PhoneOtpStep';
+import { TaxInfoStep } from '../steps/TaxInfoStep';
+import { SwornDeclarationStep } from '../steps/SwornDeclarationStep';
+import { TermsAndConditionsStep } from '../steps/TermsAndConditionsStep';
+import { LegalBasicInfoStep } from '../steps/LegalBasicInfoStep';
+import { HumanExtendedInfoStep } from '../steps/HumanExtendedInfoStep';
+import { LegalExtendedInfoStep } from '../steps/LegalExtendedInfoStep';
+import { AddressInfoStep } from '../steps/AddressInfoStep';
+import { DocumentsOcrStep } from '../steps/DocumentsOcrStep';
+import { LivenessMatchStep } from '../steps/LivenessMatchStep';
+import { FaceMatchStep } from '../steps/FaceMatchStep';
+import {
+  SdkErrorCode,
+  type VelionConfig as WebVelionConfig,
+  type SdkStatus,
+  type SdkEventMap,
+  type SdkError,
+  type OnboardingStep,
+  type OnboardingResult,
+  type OnboardingDtoResponse,
+  type OnboardingSessionEvent,
+  type SessionState,
+} from '../types';
+import type { StepModule, StepUiHandle } from '../steps/types';
+import type { ReactNode } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PUBLIC CONFIG (RN flavor)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * RN-specific config. Drops web-only fields (`containerId`, `allowEmbedded`,
+ * `iframeParentOrigin`) and keeps everything else identical to
+ * `WebVelionConfig`, including `fingerprintEndpoint` and `fingerprintApiKey`
+ * — both are honoured by the native Fingerprint Pro SDK on mobile too.
+ */
+export type VelionConfig = Omit<
+  WebVelionConfig,
+  'containerId' | 'allowEmbedded' | 'iframeParentOrigin'
+>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// INTERNAL CONTRACTS
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NextStepCommand {
+  step: OnboardingStep;
+  stepConfig?: Record<string, unknown>;
+  /** `NEXT_STEP` advances; `RETRY_STEP` re-runs the same step intentionally. */
+  action: 'NEXT_STEP' | 'RETRY_STEP';
+}
+
+const BACKEND_ONLY_ORCHESTRATED_STEPS = new Set<string>(['FACE_MATCH', 'AML_SCREENING']);
+
+const DEFAULT_API_URL = 'https://sdk.velion.la/onboarding';
+
+function isBackendOnlyOrchestratedStep(step: string | undefined): boolean {
+  if (typeof step !== 'string' || step.trim() === '') return false;
+  return BACKEND_ONLY_ORCHESTRATED_STEPS.has(step.trim().toUpperCase());
+}
+
+function isTerminalSessionEvent(event: OnboardingSessionEvent): boolean {
+  const t = event.event_type;
+  return (
+    t === 'SESSION_APPROVED' ||
+    t === 'SESSION_MANUAL_REVIEW' ||
+    t === 'SESSION_DECLINED' ||
+    t === 'SESSION_TERMINATED'
+  );
+}
+
+function terminalEventTypeToStatus(
+  eventType: string | undefined,
+): OnboardingResult['status'] | undefined {
+  switch (eventType) {
+    case 'SESSION_APPROVED':
+      return 'APPROVED';
+    case 'SESSION_MANUAL_REVIEW':
+      return 'MANUAL_REVIEW';
+    case 'SESSION_DECLINED':
+      return 'DECLINED';
+    case 'SESSION_TERMINATED':
+      return 'REJECTED';
+    default:
+      return undefined;
+  }
+}
+
+function isSessionTokenAuthSdkError(err: unknown): err is SdkError {
+  return (
+    err != null &&
+    typeof err === 'object' &&
+    (err as SdkError).code === SdkErrorCode.SESSION_EXPIRED
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PUBLIC: ORCHESTRATOR
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Optional view bridge given to the orchestrator by `VelionOnboardingScreen`.
+ *
+ * The orchestrator never reads from this — it only writes:
+ *   - `setLoading(text)` to display a status message between steps
+ *   - `setStepNode(node)` to mount the active step's UI
+ *   - `setError(err)` to surface a fatal error
+ *   - `setResult(result)` on flow completion (host may show their own result)
+ */
+export interface OrchestratorView {
+  setLoading?: (text: string | null) => void;
+  setStepNode?: (node: ReactNode | null) => void;
+  setError?: (err: SdkError) => void;
+  setResult?: (result: OnboardingResult) => void;
+}
+
+/**
+ * Top-level entry point. Instantiate once per session, call `start()`, and
+ * `destroy()` from the host's unmount path.
+ */
+export class VelionOnboarding {
+  private readonly config: Readonly<VelionConfig & { apiUrl: string }>;
+  private readonly emitter = new TypedEventEmitter<SdkEventMap>();
+  private readonly api: ApiCaller;
+  private readonly constructionError: SdkError | null;
+
+  private status: SdkStatus = 'IDLE';
+  private activeModule: StepModule | null = null;
+  private view: OrchestratorView = {};
+  private readonly uiHandle: StepUiHandle = {
+    setNode: (node) => this.view.setStepNode?.(node),
+  };
+
+  private initAbortController = new AbortController();
+  private sseAbortController = new AbortController();
+  private sseCleanup: (() => void) | null = null;
+
+  private sseTerminalResolve: ((event: OnboardingSessionEvent) => void) | null = null;
+  private sseNextStepResolve: ((cmd: NextStepCommand | null) => void) | null = null;
+  private queuedNextStepCommand: NextStepCommand | null = null;
+  private lastSseEventId = '0';
+
+  private sessionDeclineHandler: ((event: OnboardingSessionEvent) => void) | null = null;
+  private pendingSessionDeclined: OnboardingSessionEvent | null = null;
+  private pendingTerminalEvent: OnboardingSessionEvent | null = null;
+  private sessionEnded = false;
+
+  constructor(config: VelionConfig) {
+    const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
+    this.config = Object.freeze({ ...config, apiUrl });
+    if (this.config.debug === true) setDebugEnabled(true);
+    let api: ApiCaller;
+    let constructionError: SdkError | null = null;
+    try {
+      api = createApiCaller(
+        apiUrl,
+        config.sessionToken,
+        config.expiresAt,
+      );
+    } catch (err) {
+      constructionError = err as SdkError;
+      // Provide a safe-but-unused caller so typed code paths don't crash.
+      api = createApiCaller(
+        'https://invalid.velion.invalid',
+        config.sessionToken,
+        config.expiresAt,
+      );
+    }
+    this.api = api;
+    this.constructionError = constructionError;
+    this.wireExternalCallbacks();
+  }
+
+  /** Connects an `OrchestratorView` (typically `VelionOnboardingScreen`). */
+  attachView(view: OrchestratorView): void {
+    this.view = view;
+  }
+
+  /** Detaches the active view (called from screen unmount). */
+  detachView(): void {
+    this.view = {};
+  }
+
+  on<K extends keyof SdkEventMap>(
+    event: K,
+    listener: (payload: SdkEventMap[K]) => void,
+  ): () => void {
+    return this.emitter.on(event, listener);
+  }
+
+  getStatus(): SdkStatus {
+    return this.status;
+  }
+
+  /**
+   * Hot-rotate the bearer token used by every subsequent backend call. The SSE
+   * stream is also reopened so the new token reaches the server-side authenticator.
+   */
+  refreshSessionToken(token: string, expiresAt?: string): void {
+    if (this.status === 'DESTROYED') return;
+    this.api.setSessionToken(token, expiresAt);
+    if (this.sseCleanup) {
+      log.info('[Flow] Reopening SSE after session token rotation');
+      this.sseCleanup();
+      this.sseAbortController.abort();
+      this.sseAbortController = new AbortController();
+      this.openSseStream(token);
+    }
+  }
+
+  async start(): Promise<void> {
+    if (this.status === 'DESTROYED') {
+      this.emitError({
+        code: SdkErrorCode.INSTANCE_DESTROYED,
+        message:
+          'This VelionOnboarding instance has been destroyed. Create a new instance to retry.',
+      });
+      return;
+    }
+
+    if (this.status !== 'IDLE') {
+      this.emitError({
+        code: SdkErrorCode.ALREADY_STARTED,
+        message:
+          'start() was called on an already-running SDK instance. Call destroy() before re-starting.',
+      });
+      return;
+    }
+
+    if (this.constructionError) {
+      this.emitError(this.constructionError);
+      return;
+    }
+
+    try {
+      await this.initialize();
+    } catch (err) {
+      this.emitError(err as SdkError);
+    }
+  }
+
+  destroy(): void {
+    if (this.status === 'DESTROYED') return;
+    this.setStatus('DESTROYED');
+    this.initAbortController.abort();
+    this.sseCleanup?.();
+    this.sseAbortController.abort();
+    this.activeModule?.destroy();
+    this.activeModule = null;
+    this.view.setStepNode?.(null);
+    this.view.setLoading?.(null);
+    this.emitter.removeAllListeners();
+    this.sessionDeclineHandler = null;
+    this.pendingSessionDeclined = null;
+  }
+
+  // ── Initialization ────────────────────────────────────────────────────────
+
+  private async initialize(): Promise<void> {
+    this.setStatus('INITIALIZING');
+    this.showLoading(this.localizedLoadingMsg());
+
+    let dto: OnboardingDtoResponse;
+    try {
+      dto = await this.api.get<OnboardingDtoResponse>(
+        `/sessions/${this.config.sessionId}`,
+        {
+          signal: this.initAbortController.signal,
+          extraHeaders: {
+            'Cache-Control': 'no-cache, no-store, must-revalidate',
+            Pragma: 'no-cache',
+          },
+        },
+      );
+    } catch (err) {
+      this.showLoading(null);
+      if (isSessionTokenAuthSdkError(err)) {
+        throw err;
+      }
+      throw {
+        code: SdkErrorCode.SESSION_FETCH_FAILED,
+        message:
+          `Failed to fetch session for sessionId="${this.config.sessionId}". Verify the apiUrl and sessionToken are correct.`,
+        cause: err,
+      } satisfies SdkError;
+    }
+
+    const sessionState = mapOnboardingDtoToSessionState(dto);
+    this.emitter.emit('session:loaded', sessionState);
+
+    if (isTerminalSessionStatusFromDto(dto.status)) {
+      const result = mapOnboardingDtoToResult(dto, this.config.sessionId);
+      this.completeFlow(result);
+      return;
+    }
+
+    this.validateSessionState(dto, sessionState);
+
+    this.sseAbortController = new AbortController();
+    this.openSseStream(this.config.sessionToken);
+
+    this.setStatus('RUNNING');
+    await this.runStepMachine(sessionState);
+  }
+
+  private validateSessionState(
+    dto: OnboardingDtoResponse,
+    state: SessionState,
+  ): void {
+    if (
+      requiresCurrentStepForSessionStatus(dto.status) &&
+      !state.currentStep
+    ) {
+      throw {
+        code: SdkErrorCode.SESSION_FETCH_FAILED,
+        message:
+          `Session ${this.config.sessionId} reports status="${dto.status}" but no current_step. Backend payload is incomplete.`,
+      } satisfies SdkError;
+    }
+  }
+
+  // ── Step Machine ──────────────────────────────────────────────────────────
+
+  private async runStepMachine(sessionState: SessionState): Promise<void> {
+    if (await this.consumePendingTerminalEvent()) return;
+    if (this.pendingSessionDeclined) {
+      const ev = this.pendingSessionDeclined;
+      this.pendingSessionDeclined = null;
+      this.endFlowWithSessionDeclined(ev);
+      return;
+    }
+
+    let index = 0;
+    let currentStep = sessionState.currentStep;
+    let currentStepConfig = sessionState.currentStepConfig;
+    const knownStepConfigs = { ...(sessionState.stepConfigs ?? {}) };
+
+    if (currentStep && isBackendOnlyOrchestratedStep(currentStep)) {
+      this.showLoading(this.localizedProcessingMsg());
+      try {
+        const outcome = await this.withSessionDeclineRace(
+          this.waitForRoutingAfterBackendOnlyStep(),
+        );
+        if (await this.consumePendingTerminalEvent()) return;
+        if (outcome.declined) {
+          this.endFlowWithSessionDeclined(outcome.event);
+          return;
+        }
+        const routed = outcome.value;
+        if (!routed?.step) {
+          throw {
+            code: SdkErrorCode.SESSION_FETCH_FAILED,
+            message:
+              `Timed out waiting for ROUTING_COMMAND while the session was on a backend-only step (${String(currentStep)}).`,
+          } satisfies SdkError;
+        }
+        currentStep = routed.step;
+        currentStepConfig = routed.stepConfig;
+      } finally {
+        this.showLoading(null);
+      }
+    }
+
+    while (currentStep) {
+      if (await this.consumePendingTerminalEvent()) return;
+      if (this.pendingSessionDeclined) {
+        const ev = this.pendingSessionDeclined;
+        this.pendingSessionDeclined = null;
+        this.endFlowWithSessionDeclined(ev);
+        return;
+      }
+      this.setStatus('STEP_PROCESSING');
+      this.emitter.emit('step:change', { step: currentStep, index });
+
+      if (currentStepConfig) {
+        knownStepConfigs[currentStep] = currentStepConfig;
+      }
+
+      const module = this.createModule(currentStep, currentStepConfig);
+      this.activeModule = module;
+
+      try {
+        const runOutcome = await this.withSessionDeclineRace(module.run());
+        if (await this.consumePendingTerminalEvent()) {
+          module.destroy();
+          this.activeModule = null;
+          return;
+        }
+        if (runOutcome.declined) {
+          module.destroy();
+          this.activeModule = null;
+          this.endFlowWithSessionDeclined(runOutcome.event);
+          return;
+        }
+      } catch (err) {
+        module.destroy();
+        this.activeModule = null;
+        throw err;
+      }
+
+      module.destroy();
+      this.activeModule = null;
+      this.view.setStepNode?.(null);
+      this.emitter.emit('step:complete', { step: currentStep });
+      this.setStatus('RUNNING');
+      index += 1;
+
+      this.showLoading('');
+      let next: NextStepCommand | null;
+      try {
+        const nextOutcome = await this.withSessionDeclineRace(
+          this.resolveNextStepAfterCompletion(),
+        );
+        if (await this.consumePendingTerminalEvent()) {
+          this.showLoading(null);
+          return;
+        }
+        if (nextOutcome.declined) {
+          this.endFlowWithSessionDeclined(nextOutcome.event);
+          return;
+        }
+        next = nextOutcome.value;
+      } catch (err) {
+        this.showLoading(null);
+        throw err;
+      }
+
+      while (
+        next?.step &&
+        next.action === 'NEXT_STEP' &&
+        next.step === currentStep
+      ) {
+        log.warn('[Flow] Dropping duplicate NEXT_STEP for just-completed step', {
+          step: currentStep,
+        });
+        const retryOutcome = await this.withSessionDeclineRace(
+          this.resolveNextStepAfterCompletion(),
+        );
+        if (await this.consumePendingTerminalEvent()) {
+          this.showLoading(null);
+          return;
+        }
+        if (retryOutcome.declined) {
+          this.endFlowWithSessionDeclined(retryOutcome.event);
+          return;
+        }
+        next = retryOutcome.value;
+      }
+
+      if (next?.step) {
+        this.showLoading(null);
+      }
+      if (!next?.step) break;
+      currentStep = next.step;
+      currentStepConfig = next.stepConfig;
+    }
+
+    this.showLoading(this.localizedFinalizingMsg());
+    try {
+      if (this.pendingSessionDeclined) {
+        const ev = this.pendingSessionDeclined;
+        this.pendingSessionDeclined = null;
+        this.endFlowWithSessionDeclined(ev);
+        return;
+      }
+      if (await this.consumePendingTerminalEvent()) return;
+      const terminalOutcome = await this.withSessionDeclineRace(
+        this.waitForTerminalSseEvent(45_000),
+      );
+      if (terminalOutcome.declined) {
+        this.endFlowWithSessionDeclined(terminalOutcome.event);
+        return;
+      }
+      const terminalEvent = terminalOutcome.value;
+      if (terminalEvent) {
+        await this.finalizeSessionWithTerminalEvent(terminalEvent);
+        return;
+      }
+      await this.finalizeSessionSingleGet();
+    } finally {
+      this.showLoading(null);
+    }
+  }
+
+  private createModule(
+    step: OnboardingStep,
+    stepConfig: Record<string, unknown> | undefined,
+  ): StepModule {
+    const deps = {
+      api: this.api,
+      sessionId: this.config.sessionId,
+      locale: this.config.locale ?? 'es',
+      colorMode: (this.config.colorMode ?? 'light') as 'light' | 'dark',
+      ui: this.uiHandle,
+      step,
+      ...(stepConfig !== undefined && { stepConfig }),
+      ...(this.config.googleMapsApiKey !== undefined && {
+        googleMapsApiKey: this.config.googleMapsApiKey,
+      }),
+      ...(this.config.fingerprintEndpoint !== undefined && {
+        fingerprintEndpoint: this.config.fingerprintEndpoint,
+      }),
+      ...(this.config.fingerprintApiKey !== undefined && {
+        fingerprintApiKey: this.config.fingerprintApiKey,
+      }),
+      ...(this.config.fingerprintTimeoutMs !== undefined && {
+        fingerprintTimeoutMs: this.config.fingerprintTimeoutMs,
+      }),
+      ...(this.config.livenessCalibrationLabel !== undefined && {
+        livenessCalibrationLabel: this.config.livenessCalibrationLabel,
+      }),
+    } as const;
+
+    switch (step) {
+      case 'DEVICE_FINGERPRINT':
+        return new FingerprintStep(deps);
+      case 'HUMAN_BASIC_INFO':
+        return new HumanBasicInfoStep(deps);
+      case 'EMAIL_CONTACT':
+        return new EmailContactStep(deps);
+      case 'PHONE_CONTACT':
+        return new PhoneContactStep(deps);
+      case 'EMAIL_OTP':
+        return new EmailOtpStep(deps);
+      case 'PHONE_OTP':
+        return new PhoneOtpStep(deps);
+      case 'TAX_INFO':
+        return new TaxInfoStep(deps);
+      case 'SWORN_DECLARATION':
+        return new SwornDeclarationStep(deps);
+      case 'TERMS_AND_CONDITIONS':
+        return new TermsAndConditionsStep(deps);
+      case 'LEGAL_BASIC_INFO':
+        return new LegalBasicInfoStep(deps);
+      case 'HUMAN_EXTENDED_INFO':
+        return new HumanExtendedInfoStep(deps);
+      case 'LEGAL_EXTENDED_INFO':
+        return new LegalExtendedInfoStep(deps);
+      case 'ADDRESS_INFO':
+        return new AddressInfoStep(deps);
+      case 'DOCUMENTS_OCR':
+        return new DocumentsOcrStep(deps);
+      case 'LIVENESS_MATCH':
+        return new LivenessMatchStep(deps);
+      case 'FACE_MATCH':
+        return new FaceMatchStep(deps);
+      default:
+        throw {
+          code: SdkErrorCode.UNKNOWN,
+          message:
+            `Step "${String(step)}" is not implemented yet in the React Native SDK. ` +
+            'See the port roadmap in the repo README.',
+        } satisfies SdkError;
+    }
+  }
+
+  // ── Finalization ──────────────────────────────────────────────────────────
+
+  private async finalizeSessionWithTerminalEvent(
+    event: OnboardingSessionEvent,
+  ): Promise<void> {
+    const status = terminalEventTypeToStatus(event.event_type);
+    if (!status) {
+      await this.finalizeSessionSingleGet();
+      return;
+    }
+    let dto: OnboardingDtoResponse;
+    try {
+      dto = await this.api.get<OnboardingDtoResponse>(
+        `/sessions/${this.config.sessionId}`,
+      );
+    } catch (err) {
+      throw {
+        code: SdkErrorCode.API_ERROR,
+        message: 'All steps completed but failed to retrieve the final session result.',
+        cause: err,
+      } satisfies SdkError;
+    }
+    const result = mapOnboardingDtoToResultWithStatus(
+      dto,
+      this.config.sessionId,
+      status,
+      event.reason,
+    );
+    this.completeFlow(result);
+  }
+
+  private async finalizeSessionSingleGet(): Promise<void> {
+    let dto: OnboardingDtoResponse;
+    try {
+      dto = await this.api.get<OnboardingDtoResponse>(
+        `/sessions/${this.config.sessionId}`,
+      );
+    } catch (err) {
+      throw {
+        code: SdkErrorCode.API_ERROR,
+        message:
+          'All steps completed but no terminal SSE event was received within the timeout, and the session fetch failed.',
+        cause: err,
+      } satisfies SdkError;
+    }
+    const result = mapOnboardingDtoToResult(dto, this.config.sessionId);
+    this.completeFlow(result);
+  }
+
+  private completeFlow(result: OnboardingResult): void {
+    this.sessionEnded = true;
+    this.setStatus('COMPLETED');
+    log.info('[Flow] Session finalized', {
+      sessionId: result.sessionId,
+      status: result.status,
+      terminalReason: result.terminalReason,
+      referenceId: result.referenceId,
+      completedAt: result.completedAt,
+    });
+    this.view.setResult?.(result);
+    this.emitter.emit('flow:complete', result);
+  }
+
+  private endFlowWithSessionDeclined(event: OnboardingSessionEvent): void {
+    if (this.sessionEnded) return;
+    this.sessionEnded = true;
+    log.info('[Flow] Session finalized', {
+      sessionId: this.config.sessionId,
+      status: 'DECLINED',
+      terminalReason: event.reason,
+      stepCode: event.step_code,
+    });
+    const copy = resolveSessionDeclinedCopy(
+      this.config.locale,
+      this.config.sessionDeclinedReasonTexts,
+      event.reason,
+      this.config.finalResultScreenTexts?.dismissLabel,
+    );
+    const err: SdkError = {
+      code: SdkErrorCode.SESSION_DECLINED,
+      message: copy.message,
+      ...(event.reason !== undefined && { declineReason: event.reason }),
+      ...(event.step_code !== undefined && { stepCode: event.step_code }),
+      declineTitle: copy.title,
+      declineMessage: copy.message,
+    };
+    this.emitError(err);
+  }
+
+  // ── SSE plumbing ──────────────────────────────────────────────────────────
+
+  private openSseStream(sessionToken: string): void {
+    this.sseCleanup = createSessionEventSource({
+      baseUrl: this.config.apiUrl,
+      sessionId: this.config.sessionId,
+      sessionToken,
+      lastEventId: this.lastSseEventId,
+      signal: this.sseAbortController.signal,
+      onEvent: (event) => this.handleSseEvent(event),
+      onError: (err) => {
+        log.warn('[Flow] SSE onError callback invoked', err);
+      },
+    });
+  }
+
+  private handleSseEvent(event: OnboardingSessionEvent): void {
+    if (this.sessionEnded) return;
+
+    if (event.event_id !== undefined) {
+      const incoming = Number(event.event_id);
+      const lastSeen = Number(this.lastSseEventId);
+      if (
+        Number.isFinite(incoming) &&
+        Number.isFinite(lastSeen) &&
+        incoming <= lastSeen
+      ) {
+        log.info('[SSE] Skipping replayed event', {
+          eventId: event.event_id,
+          lastSeen: this.lastSseEventId,
+          eventType: event.event_type,
+          action: event.action,
+        });
+        return;
+      }
+      if (Number.isFinite(incoming)) {
+        this.lastSseEventId = String(event.event_id);
+      }
+    }
+
+    this.config.onSessionEvent?.(event);
+    const isTerminal = isTerminalSessionEvent(event);
+
+    if (event.event_type === 'SESSION_DECLINED') {
+      this.pendingTerminalEvent = event;
+      if (this.sessionDeclineHandler) {
+        this.sessionDeclineHandler(event);
+      } else {
+        this.pendingSessionDeclined = event;
+      }
+      return;
+    }
+
+    if (isTerminal) {
+      this.pendingTerminalEvent = event;
+      if (this.sseNextStepResolve) {
+        log.info('[Flow] Terminal event interrupted ROUTING_COMMAND wait', {
+          eventType: event.event_type,
+        });
+        const resolveNext = this.sseNextStepResolve;
+        this.sseNextStepResolve = null;
+        resolveNext(null);
+      }
+    }
+
+    const maybeNext = this.extractNextStepCommand(event);
+    if (maybeNext) {
+      log.info('[Flow] ROUTING_COMMAND received from SSE', {
+        step: maybeNext.step,
+        hasStepConfig: maybeNext.stepConfig !== undefined,
+        eventType: event.event_type,
+        action: event.action,
+      });
+      if (this.sseNextStepResolve) {
+        const resolve = this.sseNextStepResolve;
+        this.sseNextStepResolve = null;
+        resolve(maybeNext);
+      } else {
+        this.queuedNextStepCommand = maybeNext;
+      }
+    }
+
+    if (this.sseTerminalResolve && isTerminal) {
+      log.info('[Flow] Terminal event received from SSE', {
+        eventType: event.event_type,
+      });
+      const resolve = this.sseTerminalResolve;
+      this.sseTerminalResolve = null;
+      resolve(event);
+    }
+  }
+
+  private extractNextStepCommand(
+    event: OnboardingSessionEvent,
+  ): NextStepCommand | null {
+    if (event.event_type !== 'ROUTING_COMMAND') return null;
+    const action = event.action;
+    if (action !== 'NEXT_STEP' && action !== 'RETRY_STEP') return null;
+    const step = event.step_code as OnboardingStep | undefined;
+    if (!step) return null;
+    return {
+      step,
+      action,
+      ...(event.step_config !== undefined && { stepConfig: event.step_config }),
+    };
+  }
+
+  // ── Wait helpers ──────────────────────────────────────────────────────────
+
+  /**
+   * Wait for the next ROUTING_COMMAND. The orchestrator races this with a 30 s
+   * timeout that, on fire, falls back to a fresh GET /sessions/:id to recover
+   * if SSE was missed.
+   */
+  private resolveNextStepAfterCompletion(): Promise<NextStepCommand | null> {
+    if (this.queuedNextStepCommand) {
+      const next = this.queuedNextStepCommand;
+      this.queuedNextStepCommand = null;
+      return Promise.resolve(next);
+    }
+
+    return new Promise<NextStepCommand | null>((resolve) => {
+      const timeout = setTimeout(async () => {
+        if (this.sseNextStepResolve) {
+          this.sseNextStepResolve = null;
+        }
+        log.warn(
+          '[Flow] No ROUTING_COMMAND within 30 s — falling back to GET /sessions for next step',
+        );
+        try {
+          const dto = await this.api.get<OnboardingDtoResponse>(
+            `/sessions/${this.config.sessionId}`,
+            {
+              extraHeaders: {
+                'Cache-Control': 'no-cache, no-store, must-revalidate',
+              },
+            },
+          );
+          if (isTerminalSessionStatusFromDto(dto.status)) {
+            resolve(null);
+            return;
+          }
+          const state = mapOnboardingDtoToSessionState(dto);
+          if (state.currentStep) {
+            resolve({
+              step: state.currentStep,
+              action: 'NEXT_STEP',
+              ...(state.currentStepConfig !== undefined && {
+                stepConfig: state.currentStepConfig,
+              }),
+            });
+            return;
+          }
+          resolve(null);
+        } catch (err) {
+          log.error('[Flow] Fallback GET /sessions failed', err);
+          resolve(null);
+        }
+      }, 30_000);
+
+      this.sseNextStepResolve = (cmd) => {
+        clearTimeout(timeout);
+        resolve(cmd);
+      };
+    });
+  }
+
+  private waitForRoutingAfterBackendOnlyStep(): Promise<NextStepCommand | null> {
+    return this.resolveNextStepAfterCompletion();
+  }
+
+  private waitForTerminalSseEvent(
+    timeoutMs: number,
+  ): Promise<OnboardingSessionEvent | null> {
+    if (this.pendingTerminalEvent) {
+      const ev = this.pendingTerminalEvent;
+      return Promise.resolve(ev);
+    }
+    return new Promise<OnboardingSessionEvent | null>((resolve) => {
+      const timeout = setTimeout(() => {
+        if (this.sseTerminalResolve) {
+          this.sseTerminalResolve = null;
+          resolve(null);
+        }
+      }, timeoutMs);
+      this.sseTerminalResolve = (event) => {
+        clearTimeout(timeout);
+        resolve(event);
+      };
+    });
+  }
+
+  /**
+   * Drain a pending terminal event (e.g. SESSION_APPROVED arrived while the
+   * orchestrator was busy mid-step). Returns true when the flow has been ended
+   * by the consumed event.
+   */
+  private async consumePendingTerminalEvent(): Promise<boolean> {
+    const event = this.pendingTerminalEvent;
+    if (!event) return false;
+    this.pendingTerminalEvent = null;
+    if (event.event_type === 'SESSION_DECLINED') {
+      this.endFlowWithSessionDeclined(event);
+      return true;
+    }
+    await this.finalizeSessionWithTerminalEvent(event);
+    return true;
+  }
+
+  /**
+   * Race a step's promise against SESSION_DECLINED. If decline arrives first,
+   * `declined` is true so the caller can short-circuit cleanup.
+   */
+  private withSessionDeclineRace<T>(
+    promise: Promise<T>,
+  ): Promise<
+    | { declined: false; value: T }
+    | { declined: true; event: OnboardingSessionEvent }
+  > {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const declineHandler = (event: OnboardingSessionEvent): void => {
+        if (settled) return;
+        settled = true;
+        this.sessionDeclineHandler = null;
+        resolve({ declined: true, event });
+      };
+      this.sessionDeclineHandler = declineHandler;
+
+      promise
+        .then((value) => {
+          if (settled) return;
+          settled = true;
+          this.sessionDeclineHandler = null;
+          resolve({ declined: false, value });
+        })
+        .catch((err) => {
+          if (settled) return;
+          settled = true;
+          this.sessionDeclineHandler = null;
+          reject(err);
+        });
+    });
+  }
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+
+  private wireExternalCallbacks(): void {
+    const cb = this.config;
+    if (cb.onError) this.emitter.on('error', cb.onError);
+    if (cb.onSuccess) this.emitter.on('flow:complete', cb.onSuccess);
+    if (cb.onStepChange) {
+      this.emitter.on('step:change', ({ step, index }) =>
+        cb.onStepChange?.(step, index),
+      );
+    }
+    if (cb.onStepComplete) {
+      this.emitter.on('step:complete', ({ step }) => cb.onStepComplete?.(step));
+    }
+    // session:loaded has no public callback — internal only.
+  }
+
+  private setStatus(next: SdkStatus): void {
+    this.status = next;
+    this.emitter.emit('status:change', next);
+  }
+
+  private emitError(err: SdkError): void {
+    if (this.status === 'DESTROYED') return;
+    this.setStatus('ERROR');
+    this.view.setError?.(err);
+    this.emitter.emit('error', err);
+  }
+
+  private isEnglish(): boolean {
+    return (this.config.locale ?? 'es').toLowerCase().startsWith('en');
+  }
+
+  private localizedLoadingMsg(): string {
+    return this.isEnglish() ? 'Loading…' : 'Cargando…';
+  }
+
+  private localizedProcessingMsg(): string {
+    return this.isEnglish()
+      ? 'Processing your verification…'
+      : 'Procesando tu verificación…';
+  }
+
+  private localizedFinalizingMsg(): string {
+    return this.isEnglish()
+      ? 'Processing your information…'
+      : 'Procesando tu información…';
+  }
+
+  private showLoading(text: string | null): void {
+    this.view.setLoading?.(text);
+  }
+}