@velion-la/onboarding-sdk-react-native 1.0.0-beta.4 → 1.0.0-beta.6

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 (184) hide show
  1. package/README.md +85 -0
  2. package/app.plugin.js +101 -0
  3. package/lib/commonjs/core/VelionOnboarding.js +246 -17
  4. package/lib/commonjs/core/VelionOnboarding.js.map +1 -1
  5. package/lib/commonjs/core/routingCommands.js +62 -0
  6. package/lib/commonjs/core/routingCommands.js.map +1 -0
  7. package/lib/commonjs/core/sessionStateMapper.js +63 -0
  8. package/lib/commonjs/core/sessionStateMapper.js.map +1 -1
  9. package/lib/commonjs/i18n/strings/en.js +1 -0
  10. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  11. package/lib/commonjs/i18n/strings/es.js +1 -0
  12. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  13. package/lib/commonjs/index.js.map +1 -1
  14. package/lib/commonjs/steps/AddressInfoStep.js +30 -18
  15. package/lib/commonjs/steps/AddressInfoStep.js.map +1 -1
  16. package/lib/commonjs/steps/DocumentsOcrStep.js +4 -0
  17. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  18. package/lib/commonjs/steps/EmailContactStep.js +5 -0
  19. package/lib/commonjs/steps/EmailContactStep.js.map +1 -1
  20. package/lib/commonjs/steps/EmailOtpStep.js +5 -0
  21. package/lib/commonjs/steps/EmailOtpStep.js.map +1 -1
  22. package/lib/commonjs/steps/HumanBasicInfoStep.js +12 -4
  23. package/lib/commonjs/steps/HumanBasicInfoStep.js.map +1 -1
  24. package/lib/commonjs/steps/HumanExtendedInfoStep.js +15 -8
  25. package/lib/commonjs/steps/HumanExtendedInfoStep.js.map +1 -1
  26. package/lib/commonjs/steps/LegalBasicInfoStep.js +13 -6
  27. package/lib/commonjs/steps/LegalBasicInfoStep.js.map +1 -1
  28. package/lib/commonjs/steps/LegalExtendedInfoStep.js +9 -2
  29. package/lib/commonjs/steps/LegalExtendedInfoStep.js.map +1 -1
  30. package/lib/commonjs/steps/PhoneContactStep.js +5 -0
  31. package/lib/commonjs/steps/PhoneContactStep.js.map +1 -1
  32. package/lib/commonjs/steps/PhoneOtpStep.js +5 -0
  33. package/lib/commonjs/steps/PhoneOtpStep.js.map +1 -1
  34. package/lib/commonjs/steps/SwornDeclarationStep.js +16 -6
  35. package/lib/commonjs/steps/SwornDeclarationStep.js.map +1 -1
  36. package/lib/commonjs/steps/TaxInfoStep.js +10 -3
  37. package/lib/commonjs/steps/TaxInfoStep.js.map +1 -1
  38. package/lib/commonjs/steps/TermsAndConditionsStep.js +7 -0
  39. package/lib/commonjs/steps/TermsAndConditionsStep.js.map +1 -1
  40. package/lib/commonjs/steps/_shared.js +21 -0
  41. package/lib/commonjs/steps/_shared.js.map +1 -1
  42. package/lib/commonjs/types/index.js +20 -1
  43. package/lib/commonjs/types/index.js.map +1 -1
  44. package/lib/commonjs/ui/StepShell.js +10 -2
  45. package/lib/commonjs/ui/StepShell.js.map +1 -1
  46. package/lib/commonjs/ui/VelionOnboardingScreen.js +25 -5
  47. package/lib/commonjs/ui/VelionOnboardingScreen.js.map +1 -1
  48. package/lib/commonjs/ui/icons/StepIcon.js.map +1 -1
  49. package/lib/commonjs/ui/primitives/BackButton.js +75 -0
  50. package/lib/commonjs/ui/primitives/BackButton.js.map +1 -0
  51. package/lib/commonjs/ui/primitives/index.js +7 -0
  52. package/lib/commonjs/ui/primitives/index.js.map +1 -1
  53. package/lib/commonjs/utils/googleMapsPreflight.js +20 -9
  54. package/lib/commonjs/utils/googleMapsPreflight.js.map +1 -1
  55. package/lib/commonjs/utils/velionExtra.js +48 -0
  56. package/lib/commonjs/utils/velionExtra.js.map +1 -0
  57. package/lib/module/core/VelionOnboarding.js +247 -18
  58. package/lib/module/core/VelionOnboarding.js.map +1 -1
  59. package/lib/module/core/routingCommands.js +57 -0
  60. package/lib/module/core/routingCommands.js.map +1 -0
  61. package/lib/module/core/sessionStateMapper.js +61 -0
  62. package/lib/module/core/sessionStateMapper.js.map +1 -1
  63. package/lib/module/i18n/strings/en.js +1 -0
  64. package/lib/module/i18n/strings/en.js.map +1 -1
  65. package/lib/module/i18n/strings/es.js +1 -0
  66. package/lib/module/i18n/strings/es.js.map +1 -1
  67. package/lib/module/index.js.map +1 -1
  68. package/lib/module/steps/AddressInfoStep.js +31 -19
  69. package/lib/module/steps/AddressInfoStep.js.map +1 -1
  70. package/lib/module/steps/DocumentsOcrStep.js +4 -0
  71. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  72. package/lib/module/steps/EmailContactStep.js +5 -0
  73. package/lib/module/steps/EmailContactStep.js.map +1 -1
  74. package/lib/module/steps/EmailOtpStep.js +5 -0
  75. package/lib/module/steps/EmailOtpStep.js.map +1 -1
  76. package/lib/module/steps/HumanBasicInfoStep.js +12 -4
  77. package/lib/module/steps/HumanBasicInfoStep.js.map +1 -1
  78. package/lib/module/steps/HumanExtendedInfoStep.js +16 -9
  79. package/lib/module/steps/HumanExtendedInfoStep.js.map +1 -1
  80. package/lib/module/steps/LegalBasicInfoStep.js +14 -7
  81. package/lib/module/steps/LegalBasicInfoStep.js.map +1 -1
  82. package/lib/module/steps/LegalExtendedInfoStep.js +10 -3
  83. package/lib/module/steps/LegalExtendedInfoStep.js.map +1 -1
  84. package/lib/module/steps/PhoneContactStep.js +5 -0
  85. package/lib/module/steps/PhoneContactStep.js.map +1 -1
  86. package/lib/module/steps/PhoneOtpStep.js +5 -0
  87. package/lib/module/steps/PhoneOtpStep.js.map +1 -1
  88. package/lib/module/steps/SwornDeclarationStep.js +18 -6
  89. package/lib/module/steps/SwornDeclarationStep.js.map +1 -1
  90. package/lib/module/steps/TaxInfoStep.js +11 -4
  91. package/lib/module/steps/TaxInfoStep.js.map +1 -1
  92. package/lib/module/steps/TermsAndConditionsStep.js +7 -0
  93. package/lib/module/steps/TermsAndConditionsStep.js.map +1 -1
  94. package/lib/module/steps/_shared.js +19 -0
  95. package/lib/module/steps/_shared.js.map +1 -1
  96. package/lib/module/types/index.js +21 -1
  97. package/lib/module/types/index.js.map +1 -1
  98. package/lib/module/ui/StepShell.js +10 -2
  99. package/lib/module/ui/StepShell.js.map +1 -1
  100. package/lib/module/ui/VelionOnboardingScreen.js +25 -5
  101. package/lib/module/ui/VelionOnboardingScreen.js.map +1 -1
  102. package/lib/module/ui/icons/StepIcon.js.map +1 -1
  103. package/lib/module/ui/primitives/BackButton.js +71 -0
  104. package/lib/module/ui/primitives/BackButton.js.map +1 -0
  105. package/lib/module/ui/primitives/index.js +1 -0
  106. package/lib/module/ui/primitives/index.js.map +1 -1
  107. package/lib/module/utils/googleMapsPreflight.js +20 -9
  108. package/lib/module/utils/googleMapsPreflight.js.map +1 -1
  109. package/lib/module/utils/velionExtra.js +44 -0
  110. package/lib/module/utils/velionExtra.js.map +1 -0
  111. package/lib/typescript/core/VelionOnboarding.d.ts +44 -1
  112. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  113. package/lib/typescript/core/routingCommands.d.ts +39 -0
  114. package/lib/typescript/core/routingCommands.d.ts.map +1 -0
  115. package/lib/typescript/core/sessionStateMapper.d.ts +20 -1
  116. package/lib/typescript/core/sessionStateMapper.d.ts.map +1 -1
  117. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  118. package/lib/typescript/i18n/strings/es.d.ts +1 -0
  119. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  120. package/lib/typescript/index.d.ts +1 -1
  121. package/lib/typescript/index.d.ts.map +1 -1
  122. package/lib/typescript/steps/AddressInfoStep.d.ts.map +1 -1
  123. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  124. package/lib/typescript/steps/EmailContactStep.d.ts.map +1 -1
  125. package/lib/typescript/steps/EmailOtpStep.d.ts.map +1 -1
  126. package/lib/typescript/steps/HumanBasicInfoStep.d.ts.map +1 -1
  127. package/lib/typescript/steps/HumanExtendedInfoStep.d.ts.map +1 -1
  128. package/lib/typescript/steps/LegalBasicInfoStep.d.ts.map +1 -1
  129. package/lib/typescript/steps/LegalExtendedInfoStep.d.ts.map +1 -1
  130. package/lib/typescript/steps/PhoneContactStep.d.ts.map +1 -1
  131. package/lib/typescript/steps/PhoneOtpStep.d.ts.map +1 -1
  132. package/lib/typescript/steps/SwornDeclarationStep.d.ts.map +1 -1
  133. package/lib/typescript/steps/TaxInfoStep.d.ts.map +1 -1
  134. package/lib/typescript/steps/TermsAndConditionsStep.d.ts.map +1 -1
  135. package/lib/typescript/steps/_shared.d.ts +11 -0
  136. package/lib/typescript/steps/_shared.d.ts.map +1 -1
  137. package/lib/typescript/steps/types.d.ts +15 -0
  138. package/lib/typescript/steps/types.d.ts.map +1 -1
  139. package/lib/typescript/types/index.d.ts +104 -5
  140. package/lib/typescript/types/index.d.ts.map +1 -1
  141. package/lib/typescript/ui/StepShell.d.ts +11 -1
  142. package/lib/typescript/ui/StepShell.d.ts.map +1 -1
  143. package/lib/typescript/ui/VelionOnboardingScreen.d.ts +9 -2
  144. package/lib/typescript/ui/VelionOnboardingScreen.d.ts.map +1 -1
  145. package/lib/typescript/ui/icons/StepIcon.d.ts +1 -1
  146. package/lib/typescript/ui/icons/StepIcon.d.ts.map +1 -1
  147. package/lib/typescript/ui/primitives/BackButton.d.ts +20 -0
  148. package/lib/typescript/ui/primitives/BackButton.d.ts.map +1 -0
  149. package/lib/typescript/ui/primitives/index.d.ts +1 -0
  150. package/lib/typescript/ui/primitives/index.d.ts.map +1 -1
  151. package/lib/typescript/utils/googleMapsPreflight.d.ts +15 -7
  152. package/lib/typescript/utils/googleMapsPreflight.d.ts.map +1 -1
  153. package/lib/typescript/utils/velionExtra.d.ts +24 -0
  154. package/lib/typescript/utils/velionExtra.d.ts.map +1 -0
  155. package/package.json +9 -2
  156. package/src/core/VelionOnboarding.ts +255 -16
  157. package/src/core/routingCommands.ts +63 -0
  158. package/src/core/sessionStateMapper.ts +65 -0
  159. package/src/i18n/strings/en.ts +1 -0
  160. package/src/i18n/strings/es.ts +1 -0
  161. package/src/index.ts +1 -0
  162. package/src/steps/AddressInfoStep.tsx +38 -20
  163. package/src/steps/DocumentsOcrStep.tsx +5 -0
  164. package/src/steps/EmailContactStep.tsx +6 -0
  165. package/src/steps/EmailOtpStep.tsx +6 -0
  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 +103 -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
  183. package/src/utils/googleMapsPreflight.ts +27 -10
  184. package/src/utils/velionExtra.ts +46 -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
  ```
package/app.plugin.js ADDED
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Expo config plugin for @velion-la/onboarding-sdk-react-native.
3
+ *
4
+ * Hosts register it from their `app.json` / `app.config.js`:
5
+ *
6
+ * {
7
+ * "expo": {
8
+ * "plugins": [
9
+ * ["@velion-la/onboarding-sdk-react-native", {
10
+ * "googleMapsApiKey": "AIza..."
11
+ * }]
12
+ * ]
13
+ * }
14
+ * }
15
+ *
16
+ * What it does
17
+ * ============
18
+ *
19
+ * - **Android**: copies the key into `config.android.config.googleMaps.apiKey`.
20
+ * Expo prebuild reads that and writes
21
+ * `<meta-data android:name="com.google.android.geo.API_KEY" .../>`
22
+ * into `AndroidManifest.xml`, which is the ONLY place the native Google
23
+ * Maps SDK looks for its key. Passing the key from JS does not work —
24
+ * the Maps SDK does not expose a runtime API.
25
+ *
26
+ * - **Runtime hand-off**: stores the same value on
27
+ * `config.extra.velionGoogleMapsApiKey` so the SDK can read it from
28
+ * `expo-constants` at runtime without the integrator having to also pass
29
+ * it through `VelionConfig.googleMapsApiKey`. The runtime prop still
30
+ * wins when set, which keeps the existing override path intact.
31
+ *
32
+ * - **iOS**: no-op. iOS uses Apple Maps and does not require a key, so we
33
+ * intentionally leave `config.ios` untouched.
34
+ *
35
+ * The plugin is pure JavaScript with JSDoc types (no TypeScript build
36
+ * step) so `expo prebuild` can require it directly out of the published
37
+ * tarball. Convention: a file named `app.plugin.js` in the package root
38
+ * is what Expo resolves first when a host registers the plugin by package
39
+ * name.
40
+ *
41
+ * @typedef {Object} VelionOnboardingPluginProps
42
+ * @property {string} [googleMapsApiKey] Google Maps Android SDK API key.
43
+ * When omitted (or empty), the assisted ADDRESS_INFO flow on Android
44
+ * falls back to the manual form — the SDK does NOT crash, by design.
45
+ *
46
+ * @typedef {Object} ExpoConfigShape
47
+ * @property {Object} [android]
48
+ * @property {Object} [extra]
49
+ *
50
+ * @param {ExpoConfigShape} config
51
+ * @param {VelionOnboardingPluginProps} [props]
52
+ * @returns {ExpoConfigShape}
53
+ */
54
+ function withVelionOnboarding(config, props) {
55
+ const apiKey =
56
+ props && typeof props.googleMapsApiKey === 'string'
57
+ ? props.googleMapsApiKey.trim()
58
+ : '';
59
+
60
+ if (!apiKey) {
61
+ // Hosts may register the plugin without a key for symmetry / future
62
+ // options. That's fine — the assisted Android map flow simply falls
63
+ // back to the manual form at runtime. iOS is unaffected. We log so
64
+ // a confused integrator can spot it in their `expo prebuild` output.
65
+ // eslint-disable-next-line no-console
66
+ console.warn(
67
+ '[@velion-la/onboarding-sdk-react-native] no googleMapsApiKey was passed to the plugin — ' +
68
+ 'the assisted ADDRESS_INFO flow on Android will fall back to the manual form. ' +
69
+ 'iOS is unaffected.',
70
+ );
71
+ return config;
72
+ }
73
+
74
+ // Android manifest path. `android.config.googleMaps.apiKey` is the
75
+ // Expo-canonical way to express the meta-data — prebuild's
76
+ // AndroidConfig.GoogleMaps mod reads from there.
77
+ const next = { ...config };
78
+ next.android = { ...(config.android || {}) };
79
+ next.android.config = { ...(next.android.config || {}) };
80
+ next.android.config.googleMaps = { ...(next.android.config.googleMaps || {}) };
81
+
82
+ const existing = next.android.config.googleMaps.apiKey;
83
+ if (typeof existing === 'string' && existing.length > 0 && existing !== apiKey) {
84
+ // eslint-disable-next-line no-console
85
+ console.warn(
86
+ '[@velion-la/onboarding-sdk-react-native] overriding the existing ' +
87
+ '`android.config.googleMaps.apiKey` with the value passed to the plugin. ' +
88
+ 'Remove the manual entry from app.json to silence this warning.',
89
+ );
90
+ }
91
+ next.android.config.googleMaps.apiKey = apiKey;
92
+
93
+ // Runtime hand-off via expo-constants.
94
+ next.extra = { ...(config.extra || {}) };
95
+ next.extra.velionGoogleMapsApiKey = apiKey;
96
+
97
+ return next;
98
+ }
99
+
100
+ module.exports = withVelionOnboarding;
101
+ module.exports.default = withVelionOnboarding;
@@ -7,9 +7,11 @@ exports.VelionOnboarding = void 0;
7
7
  var _EventEmitter = require("../utils/EventEmitter");
8
8
  var _api = require("../transport/api");
9
9
  var _log = require("../utils/log");
10
+ var _velionExtra = require("../utils/velionExtra");
10
11
  var _sessionStateMapper = require("./sessionStateMapper");
11
12
  var _sse = require("../transport/sse");
12
13
  var _sessionDeclinedCopy = require("./sessionDeclinedCopy");
14
+ var _routingCommands = require("./routingCommands");
13
15
  var _FingerprintStep = require("../steps/FingerprintStep");
14
16
  var _HumanBasicInfoStep = require("../steps/HumanBasicInfoStep");
15
17
  var _EmailContactStep = require("../steps/EmailContactStep");
@@ -56,6 +58,8 @@ var _types = require("../types");
56
58
  // INTERNAL CONTRACTS
57
59
  // ─────────────────────────────────────────────────────────────────────────────
58
60
 
61
+ /** Result of awaiting an active step module (see {@link VelionOnboarding.awaitModuleOutcome}). */
62
+
59
63
  const BACKEND_ONLY_ORCHESTRATED_STEPS = new Set(['FACE_MATCH', 'AML_SCREENING']);
60
64
  const DEFAULT_API_URL = 'https://sdk.velion.la/onboarding';
61
65
  function isBackendOnlyOrchestratedStep(step) {
@@ -117,6 +121,15 @@ class VelionOnboarding {
117
121
  sseNextStepResolve = null;
118
122
  queuedNextStepCommand = null;
119
123
  lastSseEventId = '0';
124
+ previousStepResolve = null;
125
+ queuedPreviousStepCommand = null;
126
+ backExitResolve = null;
127
+ queuedBackExitStep = null;
128
+ backRequestInFlight = false;
129
+
130
+ /** Per-step reversibility (workflow order) cached from the initial GET, used to
131
+ * derive `can_go_back` for steps reached via SSE (which doesn't carry it). */
132
+ stepReversibility = [];
120
133
  sessionDeclineHandler = null;
121
134
  pendingSessionDeclined = null;
122
135
  pendingTerminalEvent = null;
@@ -211,6 +224,10 @@ class VelionOnboarding {
211
224
  this.emitter.removeAllListeners();
212
225
  this.sessionDeclineHandler = null;
213
226
  this.pendingSessionDeclined = null;
227
+ this.previousStepResolve = null;
228
+ this.queuedPreviousStepCommand = null;
229
+ this.backExitResolve = null;
230
+ this.queuedBackExitStep = null;
214
231
  }
215
232
 
216
233
  // ── Initialization ────────────────────────────────────────────────────────
@@ -239,6 +256,9 @@ class VelionOnboarding {
239
256
  };
240
257
  }
241
258
  const sessionState = (0, _sessionStateMapper.mapOnboardingDtoToSessionState)(dto);
259
+ // Cache the workflow reversibility map so the "back" control can be resolved
260
+ // for steps reached via SSE (which doesn't carry `can_go_back`).
261
+ this.stepReversibility = sessionState.stepReversibility ?? [];
242
262
  this.emitter.emit('session:loaded', sessionState);
243
263
  if ((0, _sessionStateMapper.isTerminalSessionStatusFromDto)(dto.status)) {
244
264
  const result = (0, _sessionStateMapper.mapOnboardingDtoToResult)(dto, this.config.sessionId);
@@ -273,6 +293,8 @@ class VelionOnboarding {
273
293
  let index = 0;
274
294
  let currentStep = sessionState.currentStep;
275
295
  let currentStepConfig = sessionState.currentStepConfig;
296
+ let currentStepResult = sessionState.currentStepResult;
297
+ let currentCanGoBack = currentStep ? this.resolveCanGoBack(sessionState.canGoBack, currentStep) : false;
276
298
  const knownStepConfigs = {
277
299
  ...(sessionState.stepConfigs ?? {})
278
300
  };
@@ -294,6 +316,8 @@ class VelionOnboarding {
294
316
  }
295
317
  currentStep = routed.step;
296
318
  currentStepConfig = routed.stepConfig;
319
+ currentStepResult = undefined;
320
+ currentCanGoBack = this.resolveCanGoBack(routed.canGoBack, routed.step);
297
321
  } finally {
298
322
  this.showLoading(null);
299
323
  }
@@ -314,26 +338,50 @@ class VelionOnboarding {
314
338
  if (currentStepConfig) {
315
339
  knownStepConfigs[currentStep] = currentStepConfig;
316
340
  }
317
- const module = this.createModule(currentStep, currentStepConfig);
341
+ const module = this.createModule(currentStep, currentStepConfig, currentStepResult, currentCanGoBack);
318
342
  this.activeModule = module;
343
+ let outcome;
319
344
  try {
320
- const runOutcome = await this.withSessionDeclineRace(module.run());
321
- if (await this.consumePendingTerminalEvent()) {
322
- module.destroy();
323
- this.activeModule = null;
324
- return;
325
- }
326
- if (runOutcome.declined) {
327
- module.destroy();
328
- this.activeModule = null;
329
- this.endFlowWithSessionDeclined(runOutcome.event);
330
- return;
331
- }
345
+ outcome = await this.awaitModuleOutcome(module.run());
332
346
  } catch (err) {
333
347
  module.destroy();
334
348
  this.activeModule = null;
335
349
  throw err;
336
350
  }
351
+ if (await this.consumePendingTerminalEvent()) {
352
+ module.destroy();
353
+ this.activeModule = null;
354
+ return;
355
+ }
356
+ if (outcome.kind === 'declined') {
357
+ module.destroy();
358
+ this.activeModule = null;
359
+ this.endFlowWithSessionDeclined(outcome.event);
360
+ return;
361
+ }
362
+ if (outcome.kind === 'back') {
363
+ // Reverse navigation: tear down the active form and re-enter the loop on
364
+ // the re-opened step with its previous data as prefill. Do NOT advance
365
+ // the index nor emit step:complete — the step was not completed.
366
+ module.destroy();
367
+ this.activeModule = null;
368
+ this.view.setStepNode?.(null);
369
+ const command = outcome.command;
370
+ currentStep = command.step;
371
+ currentStepConfig = command.stepConfig ?? knownStepConfigs[command.step];
372
+ currentStepResult = command.stepResult;
373
+ currentCanGoBack = this.resolveCanGoBack(command.canGoBack, command.step);
374
+ this.showLoading(this.localizedLoadingMsg());
375
+ continue;
376
+ }
377
+ if (outcome.kind === 'exit') {
378
+ // Back on the first reversible step: there is no earlier step, so the
379
+ // backend told us to leave. Tear down and hand control back to the host.
380
+ module.destroy();
381
+ this.activeModule = null;
382
+ this.exitFlow(outcome.step);
383
+ return;
384
+ }
337
385
  module.destroy();
338
386
  this.activeModule = null;
339
387
  this.view.setStepNode?.(null);
@@ -379,7 +427,11 @@ class VelionOnboarding {
379
427
  }
380
428
  if (!next?.step) break;
381
429
  currentStep = next.step;
382
- currentStepConfig = next.stepConfig;
430
+ currentStepConfig = next.stepConfig ?? knownStepConfigs[next.step];
431
+ // Forward navigation: no prefill. `can_go_back` comes from the command
432
+ // when the backend sends it, else derived from the reversibility map.
433
+ currentStepResult = undefined;
434
+ currentCanGoBack = this.resolveCanGoBack(next.canGoBack, next.step);
383
435
  }
384
436
  this.showLoading(this.localizedFinalizingMsg());
385
437
  try {
@@ -405,7 +457,7 @@ class VelionOnboarding {
405
457
  this.showLoading(null);
406
458
  }
407
459
  }
408
- createModule(step, stepConfig) {
460
+ createModule(step, stepConfig, stepResult, canGoBack) {
409
461
  const deps = {
410
462
  api: this.api,
411
463
  sessionId: this.config.sessionId,
@@ -416,9 +468,28 @@ class VelionOnboarding {
416
468
  ...(stepConfig !== undefined && {
417
469
  stepConfig
418
470
  }),
419
- ...(this.config.googleMapsApiKey !== undefined && {
420
- googleMapsApiKey: this.config.googleMapsApiKey
471
+ ...(stepResult !== undefined && {
472
+ stepResult
421
473
  }),
474
+ // Reverse navigation: wire the "back" control only when the backend says
475
+ // the user can go back from this step (`can_go_back`). The orchestrator
476
+ // owns the POST + SSE handshake; the step only triggers it.
477
+ ...(canGoBack === true && {
478
+ onBack: () => this.requestBackNavigation(step)
479
+ }),
480
+ // Map key fallback chain:
481
+ // 1. `VelionConfig.googleMapsApiKey` (runtime override; takes precedence
482
+ // so hosts that already inject it via JS keep working).
483
+ // 2. `expoConfig.extra.velionGoogleMapsApiKey`, written by the SDK's
484
+ // Expo config plugin (`app.plugin.js`) during prebuild. This is the
485
+ // one-place-to-set-it path documented in the README.
486
+ ...(() => {
487
+ const fromConfig = this.config.googleMapsApiKey;
488
+ const resolved = typeof fromConfig === 'string' && fromConfig.trim().length > 0 ? fromConfig : (0, _velionExtra.getGoogleMapsApiKeyFromExpoExtra)();
489
+ return resolved !== undefined ? {
490
+ googleMapsApiKey: resolved
491
+ } : {};
492
+ })(),
422
493
  ...(this.config.fingerprintEndpoint !== undefined && {
423
494
  fingerprintEndpoint: this.config.fingerprintEndpoint
424
495
  }),
@@ -524,6 +595,29 @@ class VelionOnboarding {
524
595
  this.view.setResult?.(result);
525
596
  this.emitter.emit('flow:complete', result);
526
597
  }
598
+
599
+ /**
600
+ * Ends the flow because the user backed out of the first reversible step
601
+ * (`ROUTING_COMMAND / BACK_EXIT`). Not a verdict and not an error: the UI is
602
+ * cleared and the host is notified via `onExit` so it can dismiss the SDK.
603
+ */
604
+ exitFlow(step) {
605
+ if (this.sessionEnded) return;
606
+ this.sessionEnded = true;
607
+ this.setStatus('EXITED');
608
+ _log.log.info('[Flow] Session exited via back', {
609
+ sessionId: this.config.sessionId,
610
+ step
611
+ });
612
+ const exit = {
613
+ reason: 'BACK_EXIT',
614
+ ...(step !== undefined && {
615
+ step
616
+ })
617
+ };
618
+ this.view.setExit?.(exit);
619
+ this.emitter.emit('flow:exit', exit);
620
+ }
527
621
  endFlowWithSessionDeclined(event) {
528
622
  if (this.sessionEnded) return;
529
623
  this.sessionEnded = true;
@@ -604,6 +698,40 @@ class VelionOnboarding {
604
698
  resolveNext(null);
605
699
  }
606
700
  }
701
+ const maybePrevious = (0, _routingCommands.parsePreviousStepCommand)(event);
702
+ if (maybePrevious) {
703
+ _log.log.info('[Flow] PREVIOUS_STEP received from SSE', {
704
+ step: maybePrevious.step,
705
+ hasStepConfig: maybePrevious.stepConfig !== undefined,
706
+ hasStepResult: maybePrevious.stepResult !== undefined
707
+ });
708
+ if (this.previousStepResolve) {
709
+ const resolve = this.previousStepResolve;
710
+ this.previousStepResolve = null;
711
+ resolve(maybePrevious);
712
+ } else {
713
+ // Defensive: a PREVIOUS_STEP arrived while no step was waiting for it
714
+ // (e.g. between transitions). Queue it so the next module entry honors it.
715
+ this.queuedPreviousStepCommand = maybePrevious;
716
+ }
717
+ return;
718
+ }
719
+ const maybeBackExit = (0, _routingCommands.parseBackExitCommand)(event);
720
+ if (maybeBackExit) {
721
+ _log.log.info('[Flow] BACK_EXIT received from SSE', {
722
+ step: maybeBackExit.step
723
+ });
724
+ if (this.backExitResolve) {
725
+ const resolve = this.backExitResolve;
726
+ this.backExitResolve = null;
727
+ resolve(maybeBackExit.step);
728
+ } else {
729
+ this.queuedBackExitStep = {
730
+ step: maybeBackExit.step
731
+ };
732
+ }
733
+ return;
734
+ }
607
735
  const maybeNext = this.extractNextStepCommand(event);
608
736
  if (maybeNext) {
609
737
  _log.log.info('[Flow] ROUTING_COMMAND received from SSE', {
@@ -640,10 +768,46 @@ class VelionOnboarding {
640
768
  action,
641
769
  ...(event.step_config !== undefined && {
642
770
  stepConfig: event.step_config
771
+ }),
772
+ ...(typeof event.can_go_back === 'boolean' && {
773
+ canGoBack: event.can_go_back
643
774
  })
644
775
  };
645
776
  }
646
777
 
778
+ /**
779
+ * Fire-and-forget reverse navigation. POSTs `/sessions/:id/back`; the actual
780
+ * step transition arrives via SSE (`PREVIOUS_STEP`). A `400` (session not
781
+ * IN_PROGRESS) or any other failure is swallowed — the user keeps editing the
782
+ * current step. De-duplicated so rapid taps don't stack requests.
783
+ */
784
+ requestBackNavigation(fromStep) {
785
+ if (this.status === 'DESTROYED' || this.sessionEnded) return;
786
+ if (this.backRequestInFlight) return;
787
+ this.backRequestInFlight = true;
788
+ _log.log.info('[Flow] Requesting reverse navigation', {
789
+ fromStep
790
+ });
791
+ void this.api.post(`/sessions/${this.config.sessionId}/back`, {
792
+ from_step: fromStep
793
+ }).catch(err => {
794
+ _log.log.warn('[Flow] Back navigation request failed (ignored)', err);
795
+ }).finally(() => {
796
+ this.backRequestInFlight = false;
797
+ });
798
+ }
799
+
800
+ /**
801
+ * Derives `can_go_back` for a step from the cached workflow reversibility map.
802
+ * Matches the backend's barrier model: a step can go back when any earlier
803
+ * step is reversible (navigate) or the step itself is the first reversible one
804
+ * (back exits). Fallback only — an explicit `can_go_back` from the backend
805
+ * (GET, or a ROUTING_COMMAND that carries it) always wins.
806
+ */
807
+ resolveCanGoBack(explicit, step) {
808
+ return typeof explicit === 'boolean' ? explicit : (0, _sessionStateMapper.deriveCanGoBack)(step, this.stepReversibility);
809
+ }
810
+
647
811
  // ── Wait helpers ──────────────────────────────────────────────────────────
648
812
 
649
813
  /**
@@ -680,6 +844,9 @@ class VelionOnboarding {
680
844
  action: 'NEXT_STEP',
681
845
  ...(state.currentStepConfig !== undefined && {
682
846
  stepConfig: state.currentStepConfig
847
+ }),
848
+ ...(state.canGoBack !== undefined && {
849
+ canGoBack: state.canGoBack
683
850
  })
684
851
  });
685
852
  return;
@@ -735,6 +902,67 @@ class VelionOnboarding {
735
902
  return true;
736
903
  }
737
904
 
905
+ /**
906
+ * Runs the active step, resolving on the first of:
907
+ * - `completed` — the module's `run()` resolved (user advanced),
908
+ * - `declined` — SESSION_DECLINED arrived mid-step,
909
+ * - `back` — a PREVIOUS_STEP routing command arrived (user tapped back),
910
+ * - `exit` — a BACK_EXIT routing command arrived (back on the first
911
+ * reversible step → leave the flow).
912
+ *
913
+ * Rejects only if `run()` itself throws. Used in place of the plain decline
914
+ * race for the step loop so reverse navigation can interrupt an active form.
915
+ */
916
+ awaitModuleOutcome(run) {
917
+ if (this.queuedPreviousStepCommand) {
918
+ const command = this.queuedPreviousStepCommand;
919
+ this.queuedPreviousStepCommand = null;
920
+ return Promise.resolve({
921
+ kind: 'back',
922
+ command
923
+ });
924
+ }
925
+ if (this.queuedBackExitStep) {
926
+ const {
927
+ step
928
+ } = this.queuedBackExitStep;
929
+ this.queuedBackExitStep = null;
930
+ return Promise.resolve({
931
+ kind: 'exit',
932
+ step
933
+ });
934
+ }
935
+ return new Promise((resolve, reject) => {
936
+ let settled = false;
937
+ const cleanup = () => {
938
+ this.sessionDeclineHandler = null;
939
+ this.previousStepResolve = null;
940
+ this.backExitResolve = null;
941
+ };
942
+ const settle = run2 => {
943
+ if (settled) return;
944
+ settled = true;
945
+ cleanup();
946
+ run2();
947
+ };
948
+ this.sessionDeclineHandler = event => settle(() => resolve({
949
+ kind: 'declined',
950
+ event
951
+ }));
952
+ this.previousStepResolve = command => settle(() => resolve({
953
+ kind: 'back',
954
+ command
955
+ }));
956
+ this.backExitResolve = step => settle(() => resolve({
957
+ kind: 'exit',
958
+ step
959
+ }));
960
+ run.then(() => settle(() => resolve({
961
+ kind: 'completed'
962
+ }))).catch(err => settle(() => reject(err)));
963
+ });
964
+ }
965
+
738
966
  /**
739
967
  * Race a step's promise against SESSION_DECLINED. If decline arrives first,
740
968
  * `declined` is true so the caller can short-circuit cleanup.
@@ -775,6 +1003,7 @@ class VelionOnboarding {
775
1003
  const cb = this.config;
776
1004
  if (cb.onError) this.emitter.on('error', cb.onError);
777
1005
  if (cb.onSuccess) this.emitter.on('flow:complete', cb.onSuccess);
1006
+ if (cb.onExit) this.emitter.on('flow:exit', cb.onExit);
778
1007
  if (cb.onStepChange) {
779
1008
  this.emitter.on('step:change', ({
780
1009
  step,