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

package/lib/module/core/VelionOnboarding.js

@@ -0,0 +1,811 @@
+"use strict";
+
+/**
+ * @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 } 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 } from '../types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 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.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// INTERNAL CONTRACTS
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BACKEND_ONLY_ORCHESTRATED_STEPS = new Set(['FACE_MATCH', 'AML_SCREENING']);
+const DEFAULT_API_URL = 'https://sdk.velion.la/onboarding';
+function isBackendOnlyOrchestratedStep(step) {
+  if (typeof step !== 'string' || step.trim() === '') return false;
+  return BACKEND_ONLY_ORCHESTRATED_STEPS.has(step.trim().toUpperCase());
+}
+function isTerminalSessionEvent(event) {
+  const t = event.event_type;
+  return t === 'SESSION_APPROVED' || t === 'SESSION_MANUAL_REVIEW' || t === 'SESSION_DECLINED' || t === 'SESSION_TERMINATED';
+}
+function terminalEventTypeToStatus(eventType) {
+  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) {
+  return err != null && typeof err === 'object' && err.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)
+ */
+
+/**
+ * Top-level entry point. Instantiate once per session, call `start()`, and
+ * `destroy()` from the host's unmount path.
+ */
+export class VelionOnboarding {
+  emitter = new TypedEventEmitter();
+  status = 'IDLE';
+  activeModule = null;
+  view = {};
+  uiHandle = {
+    setNode: node => this.view.setStepNode?.(node)
+  };
+  initAbortController = new AbortController();
+  sseAbortController = new AbortController();
+  sseCleanup = null;
+  sseTerminalResolve = null;
+  sseNextStepResolve = null;
+  queuedNextStepCommand = null;
+  lastSseEventId = '0';
+  sessionDeclineHandler = null;
+  pendingSessionDeclined = null;
+  pendingTerminalEvent = null;
+  sessionEnded = false;
+  constructor(config) {
+    const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
+    this.config = Object.freeze({
+      ...config,
+      apiUrl
+    });
+    if (this.config.debug === true) setDebugEnabled(true);
+    let api;
+    let constructionError = null;
+    try {
+      api = createApiCaller(apiUrl, config.sessionToken, config.expiresAt);
+    } catch (err) {
+      constructionError = err;
+      // 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) {
+    this.view = view;
+  }
+
+  /** Detaches the active view (called from screen unmount). */
+  detachView() {
+    this.view = {};
+  }
+  on(event, listener) {
+    return this.emitter.on(event, listener);
+  }
+  getStatus() {
+    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, expiresAt) {
+    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() {
+    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);
+    }
+  }
+  destroy() {
+    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 ────────────────────────────────────────────────────────
+
+  async initialize() {
+    this.setStatus('INITIALIZING');
+    this.showLoading(this.localizedLoadingMsg());
+    let dto;
+    try {
+      dto = await this.api.get(`/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
+      };
+    }
+    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);
+  }
+  validateSessionState(dto, state) {
+    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.`
+      };
+    }
+  }
+
+  // ── Step Machine ──────────────────────────────────────────────────────────
+
+  async runStepMachine(sessionState) {
+    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)}).`
+          };
+        }
+        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;
+      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);
+    }
+  }
+  createModule(step, stepConfig) {
+    const deps = {
+      api: this.api,
+      sessionId: this.config.sessionId,
+      locale: this.config.locale ?? 'es',
+      colorMode: this.config.colorMode ?? 'light',
+      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
+      })
+    };
+    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.'
+        };
+    }
+  }
+
+  // ── Finalization ──────────────────────────────────────────────────────────
+
+  async finalizeSessionWithTerminalEvent(event) {
+    const status = terminalEventTypeToStatus(event.event_type);
+    if (!status) {
+      await this.finalizeSessionSingleGet();
+      return;
+    }
+    let dto;
+    try {
+      dto = await this.api.get(`/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
+      };
+    }
+    const result = mapOnboardingDtoToResultWithStatus(dto, this.config.sessionId, status, event.reason);
+    this.completeFlow(result);
+  }
+  async finalizeSessionSingleGet() {
+    let dto;
+    try {
+      dto = await this.api.get(`/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
+      };
+    }
+    const result = mapOnboardingDtoToResult(dto, this.config.sessionId);
+    this.completeFlow(result);
+  }
+  completeFlow(result) {
+    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);
+  }
+  endFlowWithSessionDeclined(event) {
+    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 = {
+      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 ──────────────────────────────────────────────────────────
+
+  openSseStream(sessionToken) {
+    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);
+      }
+    });
+  }
+  handleSseEvent(event) {
+    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);
+    }
+  }
+  extractNextStepCommand(event) {
+    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;
+    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.
+   */
+  resolveNextStepAfterCompletion() {
+    if (this.queuedNextStepCommand) {
+      const next = this.queuedNextStepCommand;
+      this.queuedNextStepCommand = null;
+      return Promise.resolve(next);
+    }
+    return new Promise(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(`/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);
+      };
+    });
+  }
+  waitForRoutingAfterBackendOnlyStep() {
+    return this.resolveNextStepAfterCompletion();
+  }
+  waitForTerminalSseEvent(timeoutMs) {
+    if (this.pendingTerminalEvent) {
+      const ev = this.pendingTerminalEvent;
+      return Promise.resolve(ev);
+    }
+    return new Promise(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.
+   */
+  async consumePendingTerminalEvent() {
+    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.
+   */
+  withSessionDeclineRace(promise) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const declineHandler = event => {
+        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 ───────────────────────────────────────────────────────────────
+
+  wireExternalCallbacks() {
+    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.
+  }
+  setStatus(next) {
+    this.status = next;
+    this.emitter.emit('status:change', next);
+  }
+  emitError(err) {
+    if (this.status === 'DESTROYED') return;
+    this.setStatus('ERROR');
+    this.view.setError?.(err);
+    this.emitter.emit('error', err);
+  }
+  isEnglish() {
+    return (this.config.locale ?? 'es').toLowerCase().startsWith('en');
+  }
+  localizedLoadingMsg() {
+    return this.isEnglish() ? 'Loading…' : 'Cargando…';
+  }
+  localizedProcessingMsg() {
+    return this.isEnglish() ? 'Processing your verification…' : 'Procesando tu verificación…';
+  }
+  localizedFinalizingMsg() {
+    return this.isEnglish() ? 'Processing your information…' : 'Procesando tu información…';
+  }
+  showLoading(text) {
+    this.view.setLoading?.(text);
+  }
+}
+//# sourceMappingURL=VelionOnboarding.js.map