@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.
- package/README.md +85 -0
- package/lib/commonjs/core/VelionOnboarding.js +296 -15
- package/lib/commonjs/core/VelionOnboarding.js.map +1 -1
- package/lib/commonjs/core/retryStepCopy.js +43 -0
- package/lib/commonjs/core/retryStepCopy.js.map +1 -0
- package/lib/commonjs/core/routingCommands.js +62 -0
- package/lib/commonjs/core/routingCommands.js.map +1 -0
- package/lib/commonjs/core/sessionStateMapper.js +63 -0
- package/lib/commonjs/core/sessionStateMapper.js.map +1 -1
- package/lib/commonjs/i18n/strings/en.js +28 -0
- package/lib/commonjs/i18n/strings/en.js.map +1 -1
- package/lib/commonjs/i18n/strings/es.js +28 -0
- package/lib/commonjs/i18n/strings/es.js.map +1 -1
- package/lib/commonjs/index.js.map +1 -1
- package/lib/commonjs/steps/AddressInfoStep.js +30 -18
- package/lib/commonjs/steps/AddressInfoStep.js.map +1 -1
- package/lib/commonjs/steps/DocumentsOcrStep.js +4 -0
- package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
- package/lib/commonjs/steps/EmailContactStep.js +5 -0
- package/lib/commonjs/steps/EmailContactStep.js.map +1 -1
- package/lib/commonjs/steps/EmailOtpStep.js +5 -0
- package/lib/commonjs/steps/EmailOtpStep.js.map +1 -1
- package/lib/commonjs/steps/FaceMatchStep.js +16 -13
- package/lib/commonjs/steps/FaceMatchStep.js.map +1 -1
- package/lib/commonjs/steps/HumanBasicInfoStep.js +12 -4
- package/lib/commonjs/steps/HumanBasicInfoStep.js.map +1 -1
- package/lib/commonjs/steps/HumanExtendedInfoStep.js +15 -8
- package/lib/commonjs/steps/HumanExtendedInfoStep.js.map +1 -1
- package/lib/commonjs/steps/LegalBasicInfoStep.js +13 -6
- package/lib/commonjs/steps/LegalBasicInfoStep.js.map +1 -1
- package/lib/commonjs/steps/LegalExtendedInfoStep.js +9 -2
- package/lib/commonjs/steps/LegalExtendedInfoStep.js.map +1 -1
- package/lib/commonjs/steps/PhoneContactStep.js +5 -0
- package/lib/commonjs/steps/PhoneContactStep.js.map +1 -1
- package/lib/commonjs/steps/PhoneOtpStep.js +5 -0
- package/lib/commonjs/steps/PhoneOtpStep.js.map +1 -1
- package/lib/commonjs/steps/SwornDeclarationStep.js +16 -6
- package/lib/commonjs/steps/SwornDeclarationStep.js.map +1 -1
- package/lib/commonjs/steps/TaxInfoStep.js +10 -3
- package/lib/commonjs/steps/TaxInfoStep.js.map +1 -1
- package/lib/commonjs/steps/TermsAndConditionsStep.js +7 -0
- package/lib/commonjs/steps/TermsAndConditionsStep.js.map +1 -1
- package/lib/commonjs/steps/_shared.js +21 -0
- package/lib/commonjs/steps/_shared.js.map +1 -1
- package/lib/commonjs/types/index.js +36 -1
- package/lib/commonjs/types/index.js.map +1 -1
- package/lib/commonjs/ui/StepShell.js +10 -2
- package/lib/commonjs/ui/StepShell.js.map +1 -1
- package/lib/commonjs/ui/VelionOnboardingScreen.js +25 -5
- package/lib/commonjs/ui/VelionOnboardingScreen.js.map +1 -1
- package/lib/commonjs/ui/icons/StepIcon.js.map +1 -1
- package/lib/commonjs/ui/primitives/BackButton.js +75 -0
- package/lib/commonjs/ui/primitives/BackButton.js.map +1 -0
- package/lib/commonjs/ui/primitives/index.js +7 -0
- package/lib/commonjs/ui/primitives/index.js.map +1 -1
- package/lib/module/core/VelionOnboarding.js +297 -16
- package/lib/module/core/VelionOnboarding.js.map +1 -1
- package/lib/module/core/retryStepCopy.js +39 -0
- package/lib/module/core/retryStepCopy.js.map +1 -0
- package/lib/module/core/routingCommands.js +57 -0
- package/lib/module/core/routingCommands.js.map +1 -0
- package/lib/module/core/sessionStateMapper.js +61 -0
- package/lib/module/core/sessionStateMapper.js.map +1 -1
- package/lib/module/i18n/strings/en.js +28 -0
- package/lib/module/i18n/strings/en.js.map +1 -1
- package/lib/module/i18n/strings/es.js +28 -0
- package/lib/module/i18n/strings/es.js.map +1 -1
- package/lib/module/index.js.map +1 -1
- package/lib/module/steps/AddressInfoStep.js +31 -19
- package/lib/module/steps/AddressInfoStep.js.map +1 -1
- package/lib/module/steps/DocumentsOcrStep.js +4 -0
- package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
- package/lib/module/steps/EmailContactStep.js +5 -0
- package/lib/module/steps/EmailContactStep.js.map +1 -1
- package/lib/module/steps/EmailOtpStep.js +5 -0
- package/lib/module/steps/EmailOtpStep.js.map +1 -1
- package/lib/module/steps/FaceMatchStep.js +16 -13
- package/lib/module/steps/FaceMatchStep.js.map +1 -1
- package/lib/module/steps/HumanBasicInfoStep.js +12 -4
- package/lib/module/steps/HumanBasicInfoStep.js.map +1 -1
- package/lib/module/steps/HumanExtendedInfoStep.js +16 -9
- package/lib/module/steps/HumanExtendedInfoStep.js.map +1 -1
- package/lib/module/steps/LegalBasicInfoStep.js +14 -7
- package/lib/module/steps/LegalBasicInfoStep.js.map +1 -1
- package/lib/module/steps/LegalExtendedInfoStep.js +10 -3
- package/lib/module/steps/LegalExtendedInfoStep.js.map +1 -1
- package/lib/module/steps/PhoneContactStep.js +5 -0
- package/lib/module/steps/PhoneContactStep.js.map +1 -1
- package/lib/module/steps/PhoneOtpStep.js +5 -0
- package/lib/module/steps/PhoneOtpStep.js.map +1 -1
- package/lib/module/steps/SwornDeclarationStep.js +18 -6
- package/lib/module/steps/SwornDeclarationStep.js.map +1 -1
- package/lib/module/steps/TaxInfoStep.js +11 -4
- package/lib/module/steps/TaxInfoStep.js.map +1 -1
- package/lib/module/steps/TermsAndConditionsStep.js +7 -0
- package/lib/module/steps/TermsAndConditionsStep.js.map +1 -1
- package/lib/module/steps/_shared.js +19 -0
- package/lib/module/steps/_shared.js.map +1 -1
- package/lib/module/types/index.js +38 -1
- package/lib/module/types/index.js.map +1 -1
- package/lib/module/ui/StepShell.js +10 -2
- package/lib/module/ui/StepShell.js.map +1 -1
- package/lib/module/ui/VelionOnboardingScreen.js +25 -5
- package/lib/module/ui/VelionOnboardingScreen.js.map +1 -1
- package/lib/module/ui/icons/StepIcon.js.map +1 -1
- package/lib/module/ui/primitives/BackButton.js +71 -0
- package/lib/module/ui/primitives/BackButton.js.map +1 -0
- package/lib/module/ui/primitives/index.js +1 -0
- package/lib/module/ui/primitives/index.js.map +1 -1
- package/lib/typescript/core/VelionOnboarding.d.ts +56 -2
- package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
- package/lib/typescript/core/retryStepCopy.d.ts +27 -0
- package/lib/typescript/core/retryStepCopy.d.ts.map +1 -0
- package/lib/typescript/core/routingCommands.d.ts +39 -0
- package/lib/typescript/core/routingCommands.d.ts.map +1 -0
- package/lib/typescript/core/sessionStateMapper.d.ts +20 -1
- package/lib/typescript/core/sessionStateMapper.d.ts.map +1 -1
- package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
- package/lib/typescript/i18n/strings/es.d.ts +25 -0
- package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
- package/lib/typescript/index.d.ts +1 -1
- package/lib/typescript/index.d.ts.map +1 -1
- package/lib/typescript/steps/AddressInfoStep.d.ts.map +1 -1
- package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
- package/lib/typescript/steps/EmailContactStep.d.ts.map +1 -1
- package/lib/typescript/steps/EmailOtpStep.d.ts.map +1 -1
- package/lib/typescript/steps/FaceMatchStep.d.ts.map +1 -1
- package/lib/typescript/steps/HumanBasicInfoStep.d.ts.map +1 -1
- package/lib/typescript/steps/HumanExtendedInfoStep.d.ts.map +1 -1
- package/lib/typescript/steps/LegalBasicInfoStep.d.ts.map +1 -1
- package/lib/typescript/steps/LegalExtendedInfoStep.d.ts.map +1 -1
- package/lib/typescript/steps/PhoneContactStep.d.ts.map +1 -1
- package/lib/typescript/steps/PhoneOtpStep.d.ts.map +1 -1
- package/lib/typescript/steps/SwornDeclarationStep.d.ts.map +1 -1
- package/lib/typescript/steps/TaxInfoStep.d.ts.map +1 -1
- package/lib/typescript/steps/TermsAndConditionsStep.d.ts.map +1 -1
- package/lib/typescript/steps/_shared.d.ts +11 -0
- package/lib/typescript/steps/_shared.d.ts.map +1 -1
- package/lib/typescript/steps/types.d.ts +15 -0
- package/lib/typescript/steps/types.d.ts.map +1 -1
- package/lib/typescript/types/index.d.ts +127 -5
- package/lib/typescript/types/index.d.ts.map +1 -1
- package/lib/typescript/ui/StepShell.d.ts +11 -1
- package/lib/typescript/ui/StepShell.d.ts.map +1 -1
- package/lib/typescript/ui/VelionOnboardingScreen.d.ts +9 -2
- package/lib/typescript/ui/VelionOnboardingScreen.d.ts.map +1 -1
- package/lib/typescript/ui/icons/StepIcon.d.ts +1 -1
- package/lib/typescript/ui/icons/StepIcon.d.ts.map +1 -1
- package/lib/typescript/ui/primitives/BackButton.d.ts +20 -0
- package/lib/typescript/ui/primitives/BackButton.d.ts.map +1 -0
- package/lib/typescript/ui/primitives/index.d.ts +1 -0
- package/lib/typescript/ui/primitives/index.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/core/VelionOnboarding.ts +315 -16
- package/src/core/retryStepCopy.ts +54 -0
- package/src/core/routingCommands.ts +63 -0
- package/src/core/sessionStateMapper.ts +65 -0
- package/src/i18n/strings/en.ts +33 -0
- package/src/i18n/strings/es.ts +33 -0
- package/src/index.ts +2 -0
- package/src/steps/AddressInfoStep.tsx +38 -20
- package/src/steps/DocumentsOcrStep.tsx +5 -0
- package/src/steps/EmailContactStep.tsx +6 -0
- package/src/steps/EmailOtpStep.tsx +6 -0
- package/src/steps/FaceMatchStep.tsx +18 -19
- package/src/steps/HumanBasicInfoStep.tsx +16 -4
- package/src/steps/HumanExtendedInfoStep.tsx +18 -9
- package/src/steps/LegalBasicInfoStep.tsx +16 -7
- package/src/steps/LegalExtendedInfoStep.tsx +16 -3
- package/src/steps/PhoneContactStep.tsx +6 -0
- package/src/steps/PhoneOtpStep.tsx +6 -0
- package/src/steps/SwornDeclarationStep.tsx +23 -6
- package/src/steps/TaxInfoStep.tsx +15 -4
- package/src/steps/TermsAndConditionsStep.tsx +8 -0
- package/src/steps/_shared.ts +25 -0
- package/src/steps/types.ts +15 -0
- package/src/types/index.ts +131 -3
- package/src/ui/StepShell.tsx +17 -0
- package/src/ui/VelionOnboardingScreen.tsx +36 -2
- package/src/ui/icons/StepIcon.tsx +2 -1
- package/src/ui/primitives/BackButton.tsx +65 -0
- 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
|
-
|
|
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,
|