@velion-la/onboarding-sdk-react-native 1.0.0-beta.5 → 1.0.0-beta.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/README.md +85 -0
  2. package/lib/commonjs/core/VelionOnboarding.js +296 -15
  3. package/lib/commonjs/core/VelionOnboarding.js.map +1 -1
  4. package/lib/commonjs/core/retryStepCopy.js +43 -0
  5. package/lib/commonjs/core/retryStepCopy.js.map +1 -0
  6. package/lib/commonjs/core/routingCommands.js +62 -0
  7. package/lib/commonjs/core/routingCommands.js.map +1 -0
  8. package/lib/commonjs/core/sessionStateMapper.js +63 -0
  9. package/lib/commonjs/core/sessionStateMapper.js.map +1 -1
  10. package/lib/commonjs/i18n/strings/en.js +28 -0
  11. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  12. package/lib/commonjs/i18n/strings/es.js +28 -0
  13. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  14. package/lib/commonjs/index.js.map +1 -1
  15. package/lib/commonjs/steps/AddressInfoStep.js +30 -18
  16. package/lib/commonjs/steps/AddressInfoStep.js.map +1 -1
  17. package/lib/commonjs/steps/DocumentsOcrStep.js +4 -0
  18. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  19. package/lib/commonjs/steps/EmailContactStep.js +5 -0
  20. package/lib/commonjs/steps/EmailContactStep.js.map +1 -1
  21. package/lib/commonjs/steps/EmailOtpStep.js +5 -0
  22. package/lib/commonjs/steps/EmailOtpStep.js.map +1 -1
  23. package/lib/commonjs/steps/FaceMatchStep.js +16 -13
  24. package/lib/commonjs/steps/FaceMatchStep.js.map +1 -1
  25. package/lib/commonjs/steps/HumanBasicInfoStep.js +12 -4
  26. package/lib/commonjs/steps/HumanBasicInfoStep.js.map +1 -1
  27. package/lib/commonjs/steps/HumanExtendedInfoStep.js +15 -8
  28. package/lib/commonjs/steps/HumanExtendedInfoStep.js.map +1 -1
  29. package/lib/commonjs/steps/LegalBasicInfoStep.js +13 -6
  30. package/lib/commonjs/steps/LegalBasicInfoStep.js.map +1 -1
  31. package/lib/commonjs/steps/LegalExtendedInfoStep.js +9 -2
  32. package/lib/commonjs/steps/LegalExtendedInfoStep.js.map +1 -1
  33. package/lib/commonjs/steps/PhoneContactStep.js +5 -0
  34. package/lib/commonjs/steps/PhoneContactStep.js.map +1 -1
  35. package/lib/commonjs/steps/PhoneOtpStep.js +5 -0
  36. package/lib/commonjs/steps/PhoneOtpStep.js.map +1 -1
  37. package/lib/commonjs/steps/SwornDeclarationStep.js +16 -6
  38. package/lib/commonjs/steps/SwornDeclarationStep.js.map +1 -1
  39. package/lib/commonjs/steps/TaxInfoStep.js +10 -3
  40. package/lib/commonjs/steps/TaxInfoStep.js.map +1 -1
  41. package/lib/commonjs/steps/TermsAndConditionsStep.js +7 -0
  42. package/lib/commonjs/steps/TermsAndConditionsStep.js.map +1 -1
  43. package/lib/commonjs/steps/_shared.js +21 -0
  44. package/lib/commonjs/steps/_shared.js.map +1 -1
  45. package/lib/commonjs/types/index.js +36 -1
  46. package/lib/commonjs/types/index.js.map +1 -1
  47. package/lib/commonjs/ui/StepShell.js +10 -2
  48. package/lib/commonjs/ui/StepShell.js.map +1 -1
  49. package/lib/commonjs/ui/VelionOnboardingScreen.js +25 -5
  50. package/lib/commonjs/ui/VelionOnboardingScreen.js.map +1 -1
  51. package/lib/commonjs/ui/icons/StepIcon.js.map +1 -1
  52. package/lib/commonjs/ui/primitives/BackButton.js +75 -0
  53. package/lib/commonjs/ui/primitives/BackButton.js.map +1 -0
  54. package/lib/commonjs/ui/primitives/index.js +7 -0
  55. package/lib/commonjs/ui/primitives/index.js.map +1 -1
  56. package/lib/module/core/VelionOnboarding.js +297 -16
  57. package/lib/module/core/VelionOnboarding.js.map +1 -1
  58. package/lib/module/core/retryStepCopy.js +39 -0
  59. package/lib/module/core/retryStepCopy.js.map +1 -0
  60. package/lib/module/core/routingCommands.js +57 -0
  61. package/lib/module/core/routingCommands.js.map +1 -0
  62. package/lib/module/core/sessionStateMapper.js +61 -0
  63. package/lib/module/core/sessionStateMapper.js.map +1 -1
  64. package/lib/module/i18n/strings/en.js +28 -0
  65. package/lib/module/i18n/strings/en.js.map +1 -1
  66. package/lib/module/i18n/strings/es.js +28 -0
  67. package/lib/module/i18n/strings/es.js.map +1 -1
  68. package/lib/module/index.js.map +1 -1
  69. package/lib/module/steps/AddressInfoStep.js +31 -19
  70. package/lib/module/steps/AddressInfoStep.js.map +1 -1
  71. package/lib/module/steps/DocumentsOcrStep.js +4 -0
  72. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  73. package/lib/module/steps/EmailContactStep.js +5 -0
  74. package/lib/module/steps/EmailContactStep.js.map +1 -1
  75. package/lib/module/steps/EmailOtpStep.js +5 -0
  76. package/lib/module/steps/EmailOtpStep.js.map +1 -1
  77. package/lib/module/steps/FaceMatchStep.js +16 -13
  78. package/lib/module/steps/FaceMatchStep.js.map +1 -1
  79. package/lib/module/steps/HumanBasicInfoStep.js +12 -4
  80. package/lib/module/steps/HumanBasicInfoStep.js.map +1 -1
  81. package/lib/module/steps/HumanExtendedInfoStep.js +16 -9
  82. package/lib/module/steps/HumanExtendedInfoStep.js.map +1 -1
  83. package/lib/module/steps/LegalBasicInfoStep.js +14 -7
  84. package/lib/module/steps/LegalBasicInfoStep.js.map +1 -1
  85. package/lib/module/steps/LegalExtendedInfoStep.js +10 -3
  86. package/lib/module/steps/LegalExtendedInfoStep.js.map +1 -1
  87. package/lib/module/steps/PhoneContactStep.js +5 -0
  88. package/lib/module/steps/PhoneContactStep.js.map +1 -1
  89. package/lib/module/steps/PhoneOtpStep.js +5 -0
  90. package/lib/module/steps/PhoneOtpStep.js.map +1 -1
  91. package/lib/module/steps/SwornDeclarationStep.js +18 -6
  92. package/lib/module/steps/SwornDeclarationStep.js.map +1 -1
  93. package/lib/module/steps/TaxInfoStep.js +11 -4
  94. package/lib/module/steps/TaxInfoStep.js.map +1 -1
  95. package/lib/module/steps/TermsAndConditionsStep.js +7 -0
  96. package/lib/module/steps/TermsAndConditionsStep.js.map +1 -1
  97. package/lib/module/steps/_shared.js +19 -0
  98. package/lib/module/steps/_shared.js.map +1 -1
  99. package/lib/module/types/index.js +38 -1
  100. package/lib/module/types/index.js.map +1 -1
  101. package/lib/module/ui/StepShell.js +10 -2
  102. package/lib/module/ui/StepShell.js.map +1 -1
  103. package/lib/module/ui/VelionOnboardingScreen.js +25 -5
  104. package/lib/module/ui/VelionOnboardingScreen.js.map +1 -1
  105. package/lib/module/ui/icons/StepIcon.js.map +1 -1
  106. package/lib/module/ui/primitives/BackButton.js +71 -0
  107. package/lib/module/ui/primitives/BackButton.js.map +1 -0
  108. package/lib/module/ui/primitives/index.js +1 -0
  109. package/lib/module/ui/primitives/index.js.map +1 -1
  110. package/lib/typescript/core/VelionOnboarding.d.ts +56 -2
  111. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  112. package/lib/typescript/core/retryStepCopy.d.ts +27 -0
  113. package/lib/typescript/core/retryStepCopy.d.ts.map +1 -0
  114. package/lib/typescript/core/routingCommands.d.ts +39 -0
  115. package/lib/typescript/core/routingCommands.d.ts.map +1 -0
  116. package/lib/typescript/core/sessionStateMapper.d.ts +20 -1
  117. package/lib/typescript/core/sessionStateMapper.d.ts.map +1 -1
  118. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  119. package/lib/typescript/i18n/strings/es.d.ts +25 -0
  120. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  121. package/lib/typescript/index.d.ts +1 -1
  122. package/lib/typescript/index.d.ts.map +1 -1
  123. package/lib/typescript/steps/AddressInfoStep.d.ts.map +1 -1
  124. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  125. package/lib/typescript/steps/EmailContactStep.d.ts.map +1 -1
  126. package/lib/typescript/steps/EmailOtpStep.d.ts.map +1 -1
  127. package/lib/typescript/steps/FaceMatchStep.d.ts.map +1 -1
  128. package/lib/typescript/steps/HumanBasicInfoStep.d.ts.map +1 -1
  129. package/lib/typescript/steps/HumanExtendedInfoStep.d.ts.map +1 -1
  130. package/lib/typescript/steps/LegalBasicInfoStep.d.ts.map +1 -1
  131. package/lib/typescript/steps/LegalExtendedInfoStep.d.ts.map +1 -1
  132. package/lib/typescript/steps/PhoneContactStep.d.ts.map +1 -1
  133. package/lib/typescript/steps/PhoneOtpStep.d.ts.map +1 -1
  134. package/lib/typescript/steps/SwornDeclarationStep.d.ts.map +1 -1
  135. package/lib/typescript/steps/TaxInfoStep.d.ts.map +1 -1
  136. package/lib/typescript/steps/TermsAndConditionsStep.d.ts.map +1 -1
  137. package/lib/typescript/steps/_shared.d.ts +11 -0
  138. package/lib/typescript/steps/_shared.d.ts.map +1 -1
  139. package/lib/typescript/steps/types.d.ts +15 -0
  140. package/lib/typescript/steps/types.d.ts.map +1 -1
  141. package/lib/typescript/types/index.d.ts +127 -5
  142. package/lib/typescript/types/index.d.ts.map +1 -1
  143. package/lib/typescript/ui/StepShell.d.ts +11 -1
  144. package/lib/typescript/ui/StepShell.d.ts.map +1 -1
  145. package/lib/typescript/ui/VelionOnboardingScreen.d.ts +9 -2
  146. package/lib/typescript/ui/VelionOnboardingScreen.d.ts.map +1 -1
  147. package/lib/typescript/ui/icons/StepIcon.d.ts +1 -1
  148. package/lib/typescript/ui/icons/StepIcon.d.ts.map +1 -1
  149. package/lib/typescript/ui/primitives/BackButton.d.ts +20 -0
  150. package/lib/typescript/ui/primitives/BackButton.d.ts.map +1 -0
  151. package/lib/typescript/ui/primitives/index.d.ts +1 -0
  152. package/lib/typescript/ui/primitives/index.d.ts.map +1 -1
  153. package/package.json +1 -1
  154. package/src/core/VelionOnboarding.ts +315 -16
  155. package/src/core/retryStepCopy.ts +54 -0
  156. package/src/core/routingCommands.ts +63 -0
  157. package/src/core/sessionStateMapper.ts +65 -0
  158. package/src/i18n/strings/en.ts +33 -0
  159. package/src/i18n/strings/es.ts +33 -0
  160. package/src/index.ts +2 -0
  161. package/src/steps/AddressInfoStep.tsx +38 -20
  162. package/src/steps/DocumentsOcrStep.tsx +5 -0
  163. package/src/steps/EmailContactStep.tsx +6 -0
  164. package/src/steps/EmailOtpStep.tsx +6 -0
  165. package/src/steps/FaceMatchStep.tsx +18 -19
  166. package/src/steps/HumanBasicInfoStep.tsx +16 -4
  167. package/src/steps/HumanExtendedInfoStep.tsx +18 -9
  168. package/src/steps/LegalBasicInfoStep.tsx +16 -7
  169. package/src/steps/LegalExtendedInfoStep.tsx +16 -3
  170. package/src/steps/PhoneContactStep.tsx +6 -0
  171. package/src/steps/PhoneOtpStep.tsx +6 -0
  172. package/src/steps/SwornDeclarationStep.tsx +23 -6
  173. package/src/steps/TaxInfoStep.tsx +15 -4
  174. package/src/steps/TermsAndConditionsStep.tsx +8 -0
  175. package/src/steps/_shared.ts +25 -0
  176. package/src/steps/types.ts +15 -0
  177. package/src/types/index.ts +131 -3
  178. package/src/ui/StepShell.tsx +17 -0
  179. package/src/ui/VelionOnboardingScreen.tsx +36 -2
  180. package/src/ui/icons/StepIcon.tsx +2 -1
  181. package/src/ui/primitives/BackButton.tsx +65 -0
  182. package/src/ui/primitives/index.ts +1 -0
package/README.md CHANGED
@@ -409,6 +409,15 @@ interface OnboardingResult {
409
409
  onError: (err: SdkError) => void;
410
410
  ```
411
411
 
412
+ ```ts
413
+ onExit: (exit: OnboardingExit) => void; // { reason: 'BACK_EXIT'; step?: OnboardingStep }
414
+ ```
415
+
416
+ Fires when the user leaves the flow **without a verdict** — currently only when
417
+ they tap "back" on the first reversible step. Neither `onSuccess` nor `onError`
418
+ runs; dismiss the SDK screen and return the user to the previous context. See
419
+ [Reverse navigation](#reverse-navigation-back).
420
+
412
421
  ```ts
413
422
  interface SdkError {
414
423
  code: SdkErrorCode;
@@ -718,6 +727,82 @@ the SSE `ROUTING_COMMAND` events. The SDK does no client-side routing.
718
727
 
719
728
  ---
720
729
 
730
+ ## Reverse navigation ("Back")
731
+
732
+ Form steps can let the user return to a previous step to fix earlier answers.
733
+ As with everything else, **the SDK does not decide the sequence or which steps
734
+ are reversible — it obeys the backend**.
735
+
736
+ How it works, end to end:
737
+
738
+ 1. **When to show it.** The backend computes a session-level **`can_go_back`**
739
+ flag from the workflow graph (barrier model) and delivers it both on
740
+ `GET /sessions/:id` (top-level) and inside the `ROUTING_COMMAND / NEXT_STEP`
741
+ and `PREVIOUS_STEP` SSE messages. The SDK renders a top-left **"Atrás"**
742
+ control (chevron-back) **when `can_go_back === true`** — *not* a step's
743
+ intrinsic `reversible` flag. So the control also appears on non-reversible
744
+ steps (e.g. `DOCUMENTS_OCR`, before capturing) when there's an earlier
745
+ reversible step to return to, and is hidden on the very first step when
746
+ there's nowhere to go. `reversible` is still used for the prefill on
747
+ re-entry. The SDK never hardcodes the list.
748
+
749
+ > The backend `can_go_back` is the source of truth — the SDK uses it
750
+ > verbatim on the GET and on every routing command. As a safety net (e.g. an
751
+ > older backend that omits it, or the GET-on-resume path), the SDK falls back
752
+ > to deriving the flag from the per-step reversibility map cached at session
753
+ > load: a step can go back when any earlier step is reversible, or it is
754
+ > itself the first reversible step.
755
+ 2. **Tapping it.** The SDK calls `POST /sessions/:id/back` (fire-and-forget;
756
+ the same session `Bearer` token as every other call). A `400`
757
+ (`SESSION_INVALID_STATE`, session not `IN_PROGRESS`) or any other failure is
758
+ swallowed silently — the user simply keeps editing the current step.
759
+ 3. **The transition.** The backend re-opens the nearest reversible step and
760
+ pushes a `ROUTING_COMMAND` with `action: "PREVIOUS_STEP"` over SSE, carrying
761
+ the step's `step_config` and the previously-captured `step_result`. The SDK
762
+ tears down the active form and re-renders the re-opened step **prefilled**
763
+ with `step_result`.
764
+ 4. **Exiting from the first step.** When there is no earlier reversible step
765
+ (the user tapped back on the first interactive step), the backend instead
766
+ sends `action: "BACK_EXIT"`. The SDK leaves the flow: it clears its UI and
767
+ fires `onExit` (`{ reason: 'BACK_EXIT', step }`) so the host can dismiss the
768
+ SDK screen and return the user to the previous context. This is **neither**
769
+ `onSuccess` **nor** `onError`.
770
+ 5. **Idempotency.** Prefill is treated as editable initial state only — going
771
+ back never re-fires a step's side effects (no re-sending OTPs, no
772
+ re-uploading documents).
773
+
774
+ Reversible form steps and the data they prefill: `HUMAN_BASIC_INFO`,
775
+ `LEGAL_BASIC_INFO`, `HUMAN_EXTENDED_INFO`, `LEGAL_EXTENDED_INFO`, `TAX_INFO`,
776
+ and `ADDRESS_INFO`. For the assisted (map-based) address flow the structured
777
+ fields are re-confirmed on the map; the manual address form prefills every
778
+ field. This mirrors the Web SDK runtime for UX parity.
779
+
780
+ There is nothing to configure — the feature is driven entirely by the backend
781
+ `reversible` flag and the `PREVIOUS_STEP` routing command.
782
+
783
+ The only host-facing hook is the optional **`onExit`** callback (on
784
+ `VelionConfig` and as a `<VelionOnboardingScreen onExit={…} />` prop), invoked
785
+ on `BACK_EXIT` so you can unmount/dismiss the SDK:
786
+
787
+ ```tsx
788
+ <VelionOnboardingScreen
789
+ config={config}
790
+ onComplete={(result) => { /* verdict */ }}
791
+ onFail={(err) => { /* error / declined */ }}
792
+ onExit={({ step }) => navigation.goBack()} // user backed out of the first step
793
+ />
794
+ ```
795
+
796
+ > **Backend requirement.** Reverse navigation needs an Onboarding backend that
797
+ > exposes `POST /sessions/:id/back`, the session-level `can_go_back` flag (on the
798
+ > GET and on the `NEXT_STEP` / `PREVIOUS_STEP` routing commands; plus per-step
799
+ > `reversible` for prefill), and the `ROUTING_COMMAND` SSE commands
800
+ > `PREVIOUS_STEP` and `BACK_EXIT` (VON-20). Against an older backend `can_go_back`
801
+ > is absent and no earlier step is reversible, so the control never shows and the
802
+ > flow behaves exactly as before.
803
+
804
+ ---
805
+
721
806
  ## Stack and architecture
722
807
 
723
808
  ```
@@ -11,6 +11,8 @@ var _velionExtra = require("../utils/velionExtra");
11
11
  var _sessionStateMapper = require("./sessionStateMapper");
12
12
  var _sse = require("../transport/sse");
13
13
  var _sessionDeclinedCopy = require("./sessionDeclinedCopy");
14
+ var _retryStepCopy = require("./retryStepCopy");
15
+ var _routingCommands = require("./routingCommands");
14
16
  var _FingerprintStep = require("../steps/FingerprintStep");
15
17
  var _HumanBasicInfoStep = require("../steps/HumanBasicInfoStep");
16
18
  var _EmailContactStep = require("../steps/EmailContactStep");
@@ -28,6 +30,8 @@ var _DocumentsOcrStep = require("../steps/DocumentsOcrStep");
28
30
  var _LivenessMatchStep = require("../steps/LivenessMatchStep");
29
31
  var _FaceMatchStep = require("../steps/FaceMatchStep");
30
32
  var _types = require("../types");
33
+ var _react = require("react");
34
+ var _RetryDialog = require("../ui/overlays/RetryDialog");
31
35
  /**
32
36
  * @fileoverview VelionOnboarding — orchestrator for the React Native SDK.
33
37
  *
@@ -38,6 +42,8 @@ var _types = require("../types");
38
42
  * Invariants:
39
43
  * - SSE dedupe by `event_id` (monotonic)
40
44
  * - Suppress duplicate `NEXT_STEP` for the just-completed step
45
+ * - `RETRY_STEP` shows a retry dialog (Retry re-mounts the step, Cancel exits);
46
+ * once the retry quota is exhausted the backend emits SESSION_DECLINED instead
41
47
  * - 45 s watchdog for terminal SSE event after final step → fallback GET
42
48
  * - SESSION_DECLINED handling races with module.run()
43
49
  */
@@ -57,6 +63,8 @@ var _types = require("../types");
57
63
  // INTERNAL CONTRACTS
58
64
  // ─────────────────────────────────────────────────────────────────────────────
59
65
 
66
+ /** Result of awaiting an active step module (see {@link VelionOnboarding.awaitModuleOutcome}). */
67
+
60
68
  const BACKEND_ONLY_ORCHESTRATED_STEPS = new Set(['FACE_MATCH', 'AML_SCREENING']);
61
69
  const DEFAULT_API_URL = 'https://sdk.velion.la/onboarding';
62
70
  function isBackendOnlyOrchestratedStep(step) {
@@ -118,6 +126,18 @@ class VelionOnboarding {
118
126
  sseNextStepResolve = null;
119
127
  queuedNextStepCommand = null;
120
128
  lastSseEventId = '0';
129
+ previousStepResolve = null;
130
+ queuedPreviousStepCommand = null;
131
+ backExitResolve = null;
132
+ queuedBackExitStep = null;
133
+ backRequestInFlight = false;
134
+
135
+ /** Resolver for the in-flight retry dialog (RETRY_STEP), cleared on destroy. */
136
+ retryDialogResolve = null;
137
+
138
+ /** Per-step reversibility (workflow order) cached from the initial GET, used to
139
+ * derive `can_go_back` for steps reached via SSE (which doesn't carry it). */
140
+ stepReversibility = [];
121
141
  sessionDeclineHandler = null;
122
142
  pendingSessionDeclined = null;
123
143
  pendingTerminalEvent = null;
@@ -212,6 +232,11 @@ class VelionOnboarding {
212
232
  this.emitter.removeAllListeners();
213
233
  this.sessionDeclineHandler = null;
214
234
  this.pendingSessionDeclined = null;
235
+ this.previousStepResolve = null;
236
+ this.queuedPreviousStepCommand = null;
237
+ this.backExitResolve = null;
238
+ this.queuedBackExitStep = null;
239
+ this.retryDialogResolve = null;
215
240
  }
216
241
 
217
242
  // ── Initialization ────────────────────────────────────────────────────────
@@ -240,6 +265,9 @@ class VelionOnboarding {
240
265
  };
241
266
  }
242
267
  const sessionState = (0, _sessionStateMapper.mapOnboardingDtoToSessionState)(dto);
268
+ // Cache the workflow reversibility map so the "back" control can be resolved
269
+ // for steps reached via SSE (which doesn't carry `can_go_back`).
270
+ this.stepReversibility = sessionState.stepReversibility ?? [];
243
271
  this.emitter.emit('session:loaded', sessionState);
244
272
  if ((0, _sessionStateMapper.isTerminalSessionStatusFromDto)(dto.status)) {
245
273
  const result = (0, _sessionStateMapper.mapOnboardingDtoToResult)(dto, this.config.sessionId);
@@ -274,6 +302,8 @@ class VelionOnboarding {
274
302
  let index = 0;
275
303
  let currentStep = sessionState.currentStep;
276
304
  let currentStepConfig = sessionState.currentStepConfig;
305
+ let currentStepResult = sessionState.currentStepResult;
306
+ let currentCanGoBack = currentStep ? this.resolveCanGoBack(sessionState.canGoBack, currentStep) : false;
277
307
  const knownStepConfigs = {
278
308
  ...(sessionState.stepConfigs ?? {})
279
309
  };
@@ -295,6 +325,8 @@ class VelionOnboarding {
295
325
  }
296
326
  currentStep = routed.step;
297
327
  currentStepConfig = routed.stepConfig;
328
+ currentStepResult = undefined;
329
+ currentCanGoBack = this.resolveCanGoBack(routed.canGoBack, routed.step);
298
330
  } finally {
299
331
  this.showLoading(null);
300
332
  }
@@ -315,26 +347,50 @@ class VelionOnboarding {
315
347
  if (currentStepConfig) {
316
348
  knownStepConfigs[currentStep] = currentStepConfig;
317
349
  }
318
- const module = this.createModule(currentStep, currentStepConfig);
350
+ const module = this.createModule(currentStep, currentStepConfig, currentStepResult, currentCanGoBack);
319
351
  this.activeModule = module;
352
+ let outcome;
320
353
  try {
321
- const runOutcome = await this.withSessionDeclineRace(module.run());
322
- if (await this.consumePendingTerminalEvent()) {
323
- module.destroy();
324
- this.activeModule = null;
325
- return;
326
- }
327
- if (runOutcome.declined) {
328
- module.destroy();
329
- this.activeModule = null;
330
- this.endFlowWithSessionDeclined(runOutcome.event);
331
- return;
332
- }
354
+ outcome = await this.awaitModuleOutcome(module.run());
333
355
  } catch (err) {
334
356
  module.destroy();
335
357
  this.activeModule = null;
336
358
  throw err;
337
359
  }
360
+ if (await this.consumePendingTerminalEvent()) {
361
+ module.destroy();
362
+ this.activeModule = null;
363
+ return;
364
+ }
365
+ if (outcome.kind === 'declined') {
366
+ module.destroy();
367
+ this.activeModule = null;
368
+ this.endFlowWithSessionDeclined(outcome.event);
369
+ return;
370
+ }
371
+ if (outcome.kind === 'back') {
372
+ // Reverse navigation: tear down the active form and re-enter the loop on
373
+ // the re-opened step with its previous data as prefill. Do NOT advance
374
+ // the index nor emit step:complete — the step was not completed.
375
+ module.destroy();
376
+ this.activeModule = null;
377
+ this.view.setStepNode?.(null);
378
+ const command = outcome.command;
379
+ currentStep = command.step;
380
+ currentStepConfig = command.stepConfig ?? knownStepConfigs[command.step];
381
+ currentStepResult = command.stepResult;
382
+ currentCanGoBack = this.resolveCanGoBack(command.canGoBack, command.step);
383
+ this.showLoading(this.localizedLoadingMsg());
384
+ continue;
385
+ }
386
+ if (outcome.kind === 'exit') {
387
+ // Back on the first reversible step: there is no earlier step, so the
388
+ // backend told us to leave. Tear down and hand control back to the host.
389
+ module.destroy();
390
+ this.activeModule = null;
391
+ this.exitFlow(outcome.step);
392
+ return;
393
+ }
338
394
  module.destroy();
339
395
  this.activeModule = null;
340
396
  this.view.setStepNode?.(null);
@@ -379,8 +435,34 @@ class VelionOnboarding {
379
435
  this.showLoading(null);
380
436
  }
381
437
  if (!next?.step) break;
438
+
439
+ // RETRY_STEP: the step failed but the retry quota is not exhausted. Show a
440
+ // retry dialog before re-presenting the step. "Retry" re-mounts the same
441
+ // step for a fresh submit; "Cancel" exits the flow cleanly (no verdict).
442
+ // When the quota IS exhausted the backend emits SESSION_DECLINED instead,
443
+ // so this dialog never shows for the final attempt.
444
+ if (next.action === 'RETRY_STEP') {
445
+ const choice = await this.presentRetryStepDialog(next.step);
446
+ if (this.sessionEnded || this.status === 'DESTROYED') return;
447
+ if (await this.consumePendingTerminalEvent()) return;
448
+ if (this.pendingSessionDeclined) {
449
+ const ev = this.pendingSessionDeclined;
450
+ this.pendingSessionDeclined = null;
451
+ this.endFlowWithSessionDeclined(ev);
452
+ return;
453
+ }
454
+ if (choice === 'cancel') {
455
+ this.exitFlow(next.step, 'RETRY_CANCELLED');
456
+ return;
457
+ }
458
+ this.showLoading(this.localizedLoadingMsg());
459
+ }
382
460
  currentStep = next.step;
383
- currentStepConfig = next.stepConfig;
461
+ currentStepConfig = next.stepConfig ?? knownStepConfigs[next.step];
462
+ // Forward navigation: no prefill. `can_go_back` comes from the command
463
+ // when the backend sends it, else derived from the reversibility map.
464
+ currentStepResult = undefined;
465
+ currentCanGoBack = this.resolveCanGoBack(next.canGoBack, next.step);
384
466
  }
385
467
  this.showLoading(this.localizedFinalizingMsg());
386
468
  try {
@@ -406,7 +488,7 @@ class VelionOnboarding {
406
488
  this.showLoading(null);
407
489
  }
408
490
  }
409
- createModule(step, stepConfig) {
491
+ createModule(step, stepConfig, stepResult, canGoBack) {
410
492
  const deps = {
411
493
  api: this.api,
412
494
  sessionId: this.config.sessionId,
@@ -417,6 +499,15 @@ class VelionOnboarding {
417
499
  ...(stepConfig !== undefined && {
418
500
  stepConfig
419
501
  }),
502
+ ...(stepResult !== undefined && {
503
+ stepResult
504
+ }),
505
+ // Reverse navigation: wire the "back" control only when the backend says
506
+ // the user can go back from this step (`can_go_back`). The orchestrator
507
+ // owns the POST + SSE handshake; the step only triggers it.
508
+ ...(canGoBack === true && {
509
+ onBack: () => this.requestBackNavigation(step)
510
+ }),
420
511
  // Map key fallback chain:
421
512
  // 1. `VelionConfig.googleMapsApiKey` (runtime override; takes precedence
422
513
  // so hosts that already inject it via JS keep working).
@@ -535,6 +626,61 @@ class VelionOnboarding {
535
626
  this.view.setResult?.(result);
536
627
  this.emitter.emit('flow:complete', result);
537
628
  }
629
+
630
+ /**
631
+ * Ends the flow without a verdict and notifies the host via `onExit`. Not an
632
+ * error: the UI is cleared so the host can dismiss the SDK. Triggered by
633
+ * backing out of the first reversible step (`BACK_EXIT`) or cancelling the
634
+ * retry dialog (`RETRY_CANCELLED`).
635
+ */
636
+ exitFlow(step, reason = 'BACK_EXIT') {
637
+ if (this.sessionEnded) return;
638
+ this.sessionEnded = true;
639
+ this.view.setStepNode?.(null);
640
+ this.setStatus('EXITED');
641
+ _log.log.info('[Flow] Session exited', {
642
+ sessionId: this.config.sessionId,
643
+ reason,
644
+ step
645
+ });
646
+ const exit = {
647
+ reason,
648
+ ...(step !== undefined && {
649
+ step
650
+ })
651
+ };
652
+ this.view.setExit?.(exit);
653
+ this.emitter.emit('flow:exit', exit);
654
+ }
655
+
656
+ /**
657
+ * Mounts the retry dialog for a `RETRY_STEP` and resolves with the user's
658
+ * choice. Copy is derived from the step (not the backend `reason`, which is a
659
+ * diagnostic string) and can be overridden per-step via `retryStepTexts`.
660
+ */
661
+ presentRetryStepDialog(step) {
662
+ const copy = (0, _retryStepCopy.resolveRetryStepCopy)(this.config.locale, this.config.retryStepTexts, step);
663
+ _log.log.info('[Flow] Presenting RETRY_STEP dialog', {
664
+ step
665
+ });
666
+ return new Promise(resolve => {
667
+ const settle = choice => {
668
+ if (this.retryDialogResolve === null) return;
669
+ this.retryDialogResolve = null;
670
+ this.view.setStepNode?.(null);
671
+ resolve(choice);
672
+ };
673
+ this.retryDialogResolve = resolve;
674
+ this.view.setStepNode?.(/*#__PURE__*/(0, _react.createElement)(_RetryDialog.RetryDialog, {
675
+ title: copy.title,
676
+ message: copy.message,
677
+ retryLabel: copy.retryLabel,
678
+ cancelLabel: copy.cancelLabel,
679
+ onRetry: () => settle('retry'),
680
+ onCancel: () => settle('cancel')
681
+ }));
682
+ });
683
+ }
538
684
  endFlowWithSessionDeclined(event) {
539
685
  if (this.sessionEnded) return;
540
686
  this.sessionEnded = true;
@@ -615,6 +761,40 @@ class VelionOnboarding {
615
761
  resolveNext(null);
616
762
  }
617
763
  }
764
+ const maybePrevious = (0, _routingCommands.parsePreviousStepCommand)(event);
765
+ if (maybePrevious) {
766
+ _log.log.info('[Flow] PREVIOUS_STEP received from SSE', {
767
+ step: maybePrevious.step,
768
+ hasStepConfig: maybePrevious.stepConfig !== undefined,
769
+ hasStepResult: maybePrevious.stepResult !== undefined
770
+ });
771
+ if (this.previousStepResolve) {
772
+ const resolve = this.previousStepResolve;
773
+ this.previousStepResolve = null;
774
+ resolve(maybePrevious);
775
+ } else {
776
+ // Defensive: a PREVIOUS_STEP arrived while no step was waiting for it
777
+ // (e.g. between transitions). Queue it so the next module entry honors it.
778
+ this.queuedPreviousStepCommand = maybePrevious;
779
+ }
780
+ return;
781
+ }
782
+ const maybeBackExit = (0, _routingCommands.parseBackExitCommand)(event);
783
+ if (maybeBackExit) {
784
+ _log.log.info('[Flow] BACK_EXIT received from SSE', {
785
+ step: maybeBackExit.step
786
+ });
787
+ if (this.backExitResolve) {
788
+ const resolve = this.backExitResolve;
789
+ this.backExitResolve = null;
790
+ resolve(maybeBackExit.step);
791
+ } else {
792
+ this.queuedBackExitStep = {
793
+ step: maybeBackExit.step
794
+ };
795
+ }
796
+ return;
797
+ }
618
798
  const maybeNext = this.extractNextStepCommand(event);
619
799
  if (maybeNext) {
620
800
  _log.log.info('[Flow] ROUTING_COMMAND received from SSE', {
@@ -651,10 +831,46 @@ class VelionOnboarding {
651
831
  action,
652
832
  ...(event.step_config !== undefined && {
653
833
  stepConfig: event.step_config
834
+ }),
835
+ ...(typeof event.can_go_back === 'boolean' && {
836
+ canGoBack: event.can_go_back
654
837
  })
655
838
  };
656
839
  }
657
840
 
841
+ /**
842
+ * Fire-and-forget reverse navigation. POSTs `/sessions/:id/back`; the actual
843
+ * step transition arrives via SSE (`PREVIOUS_STEP`). A `400` (session not
844
+ * IN_PROGRESS) or any other failure is swallowed — the user keeps editing the
845
+ * current step. De-duplicated so rapid taps don't stack requests.
846
+ */
847
+ requestBackNavigation(fromStep) {
848
+ if (this.status === 'DESTROYED' || this.sessionEnded) return;
849
+ if (this.backRequestInFlight) return;
850
+ this.backRequestInFlight = true;
851
+ _log.log.info('[Flow] Requesting reverse navigation', {
852
+ fromStep
853
+ });
854
+ void this.api.post(`/sessions/${this.config.sessionId}/back`, {
855
+ from_step: fromStep
856
+ }).catch(err => {
857
+ _log.log.warn('[Flow] Back navigation request failed (ignored)', err);
858
+ }).finally(() => {
859
+ this.backRequestInFlight = false;
860
+ });
861
+ }
862
+
863
+ /**
864
+ * Derives `can_go_back` for a step from the cached workflow reversibility map.
865
+ * Matches the backend's barrier model: a step can go back when any earlier
866
+ * step is reversible (navigate) or the step itself is the first reversible one
867
+ * (back exits). Fallback only — an explicit `can_go_back` from the backend
868
+ * (GET, or a ROUTING_COMMAND that carries it) always wins.
869
+ */
870
+ resolveCanGoBack(explicit, step) {
871
+ return typeof explicit === 'boolean' ? explicit : (0, _sessionStateMapper.deriveCanGoBack)(step, this.stepReversibility);
872
+ }
873
+
658
874
  // ── Wait helpers ──────────────────────────────────────────────────────────
659
875
 
660
876
  /**
@@ -691,6 +907,9 @@ class VelionOnboarding {
691
907
  action: 'NEXT_STEP',
692
908
  ...(state.currentStepConfig !== undefined && {
693
909
  stepConfig: state.currentStepConfig
910
+ }),
911
+ ...(state.canGoBack !== undefined && {
912
+ canGoBack: state.canGoBack
694
913
  })
695
914
  });
696
915
  return;
@@ -746,6 +965,67 @@ class VelionOnboarding {
746
965
  return true;
747
966
  }
748
967
 
968
+ /**
969
+ * Runs the active step, resolving on the first of:
970
+ * - `completed` — the module's `run()` resolved (user advanced),
971
+ * - `declined` — SESSION_DECLINED arrived mid-step,
972
+ * - `back` — a PREVIOUS_STEP routing command arrived (user tapped back),
973
+ * - `exit` — a BACK_EXIT routing command arrived (back on the first
974
+ * reversible step → leave the flow).
975
+ *
976
+ * Rejects only if `run()` itself throws. Used in place of the plain decline
977
+ * race for the step loop so reverse navigation can interrupt an active form.
978
+ */
979
+ awaitModuleOutcome(run) {
980
+ if (this.queuedPreviousStepCommand) {
981
+ const command = this.queuedPreviousStepCommand;
982
+ this.queuedPreviousStepCommand = null;
983
+ return Promise.resolve({
984
+ kind: 'back',
985
+ command
986
+ });
987
+ }
988
+ if (this.queuedBackExitStep) {
989
+ const {
990
+ step
991
+ } = this.queuedBackExitStep;
992
+ this.queuedBackExitStep = null;
993
+ return Promise.resolve({
994
+ kind: 'exit',
995
+ step
996
+ });
997
+ }
998
+ return new Promise((resolve, reject) => {
999
+ let settled = false;
1000
+ const cleanup = () => {
1001
+ this.sessionDeclineHandler = null;
1002
+ this.previousStepResolve = null;
1003
+ this.backExitResolve = null;
1004
+ };
1005
+ const settle = run2 => {
1006
+ if (settled) return;
1007
+ settled = true;
1008
+ cleanup();
1009
+ run2();
1010
+ };
1011
+ this.sessionDeclineHandler = event => settle(() => resolve({
1012
+ kind: 'declined',
1013
+ event
1014
+ }));
1015
+ this.previousStepResolve = command => settle(() => resolve({
1016
+ kind: 'back',
1017
+ command
1018
+ }));
1019
+ this.backExitResolve = step => settle(() => resolve({
1020
+ kind: 'exit',
1021
+ step
1022
+ }));
1023
+ run.then(() => settle(() => resolve({
1024
+ kind: 'completed'
1025
+ }))).catch(err => settle(() => reject(err)));
1026
+ });
1027
+ }
1028
+
749
1029
  /**
750
1030
  * Race a step's promise against SESSION_DECLINED. If decline arrives first,
751
1031
  * `declined` is true so the caller can short-circuit cleanup.
@@ -786,6 +1066,7 @@ class VelionOnboarding {
786
1066
  const cb = this.config;
787
1067
  if (cb.onError) this.emitter.on('error', cb.onError);
788
1068
  if (cb.onSuccess) this.emitter.on('flow:complete', cb.onSuccess);
1069
+ if (cb.onExit) this.emitter.on('flow:exit', cb.onExit);
789
1070
  if (cb.onStepChange) {
790
1071
  this.emitter.on('step:change', ({
791
1072
  step,