@velion-la/onboarding-sdk-react-native 1.0.0-beta.5 → 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 (169) hide show
  1. package/README.md +85 -0
  2. package/lib/commonjs/core/VelionOnboarding.js +233 -15
  3. package/lib/commonjs/core/VelionOnboarding.js.map +1 -1
  4. package/lib/commonjs/core/routingCommands.js +62 -0
  5. package/lib/commonjs/core/routingCommands.js.map +1 -0
  6. package/lib/commonjs/core/sessionStateMapper.js +63 -0
  7. package/lib/commonjs/core/sessionStateMapper.js.map +1 -1
  8. package/lib/commonjs/i18n/strings/en.js +1 -0
  9. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  10. package/lib/commonjs/i18n/strings/es.js +1 -0
  11. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  12. package/lib/commonjs/index.js.map +1 -1
  13. package/lib/commonjs/steps/AddressInfoStep.js +30 -18
  14. package/lib/commonjs/steps/AddressInfoStep.js.map +1 -1
  15. package/lib/commonjs/steps/DocumentsOcrStep.js +4 -0
  16. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  17. package/lib/commonjs/steps/EmailContactStep.js +5 -0
  18. package/lib/commonjs/steps/EmailContactStep.js.map +1 -1
  19. package/lib/commonjs/steps/EmailOtpStep.js +5 -0
  20. package/lib/commonjs/steps/EmailOtpStep.js.map +1 -1
  21. package/lib/commonjs/steps/HumanBasicInfoStep.js +12 -4
  22. package/lib/commonjs/steps/HumanBasicInfoStep.js.map +1 -1
  23. package/lib/commonjs/steps/HumanExtendedInfoStep.js +15 -8
  24. package/lib/commonjs/steps/HumanExtendedInfoStep.js.map +1 -1
  25. package/lib/commonjs/steps/LegalBasicInfoStep.js +13 -6
  26. package/lib/commonjs/steps/LegalBasicInfoStep.js.map +1 -1
  27. package/lib/commonjs/steps/LegalExtendedInfoStep.js +9 -2
  28. package/lib/commonjs/steps/LegalExtendedInfoStep.js.map +1 -1
  29. package/lib/commonjs/steps/PhoneContactStep.js +5 -0
  30. package/lib/commonjs/steps/PhoneContactStep.js.map +1 -1
  31. package/lib/commonjs/steps/PhoneOtpStep.js +5 -0
  32. package/lib/commonjs/steps/PhoneOtpStep.js.map +1 -1
  33. package/lib/commonjs/steps/SwornDeclarationStep.js +16 -6
  34. package/lib/commonjs/steps/SwornDeclarationStep.js.map +1 -1
  35. package/lib/commonjs/steps/TaxInfoStep.js +10 -3
  36. package/lib/commonjs/steps/TaxInfoStep.js.map +1 -1
  37. package/lib/commonjs/steps/TermsAndConditionsStep.js +7 -0
  38. package/lib/commonjs/steps/TermsAndConditionsStep.js.map +1 -1
  39. package/lib/commonjs/steps/_shared.js +21 -0
  40. package/lib/commonjs/steps/_shared.js.map +1 -1
  41. package/lib/commonjs/types/index.js +20 -1
  42. package/lib/commonjs/types/index.js.map +1 -1
  43. package/lib/commonjs/ui/StepShell.js +10 -2
  44. package/lib/commonjs/ui/StepShell.js.map +1 -1
  45. package/lib/commonjs/ui/VelionOnboardingScreen.js +25 -5
  46. package/lib/commonjs/ui/VelionOnboardingScreen.js.map +1 -1
  47. package/lib/commonjs/ui/icons/StepIcon.js.map +1 -1
  48. package/lib/commonjs/ui/primitives/BackButton.js +75 -0
  49. package/lib/commonjs/ui/primitives/BackButton.js.map +1 -0
  50. package/lib/commonjs/ui/primitives/index.js +7 -0
  51. package/lib/commonjs/ui/primitives/index.js.map +1 -1
  52. package/lib/module/core/VelionOnboarding.js +234 -16
  53. package/lib/module/core/VelionOnboarding.js.map +1 -1
  54. package/lib/module/core/routingCommands.js +57 -0
  55. package/lib/module/core/routingCommands.js.map +1 -0
  56. package/lib/module/core/sessionStateMapper.js +61 -0
  57. package/lib/module/core/sessionStateMapper.js.map +1 -1
  58. package/lib/module/i18n/strings/en.js +1 -0
  59. package/lib/module/i18n/strings/en.js.map +1 -1
  60. package/lib/module/i18n/strings/es.js +1 -0
  61. package/lib/module/i18n/strings/es.js.map +1 -1
  62. package/lib/module/index.js.map +1 -1
  63. package/lib/module/steps/AddressInfoStep.js +31 -19
  64. package/lib/module/steps/AddressInfoStep.js.map +1 -1
  65. package/lib/module/steps/DocumentsOcrStep.js +4 -0
  66. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  67. package/lib/module/steps/EmailContactStep.js +5 -0
  68. package/lib/module/steps/EmailContactStep.js.map +1 -1
  69. package/lib/module/steps/EmailOtpStep.js +5 -0
  70. package/lib/module/steps/EmailOtpStep.js.map +1 -1
  71. package/lib/module/steps/HumanBasicInfoStep.js +12 -4
  72. package/lib/module/steps/HumanBasicInfoStep.js.map +1 -1
  73. package/lib/module/steps/HumanExtendedInfoStep.js +16 -9
  74. package/lib/module/steps/HumanExtendedInfoStep.js.map +1 -1
  75. package/lib/module/steps/LegalBasicInfoStep.js +14 -7
  76. package/lib/module/steps/LegalBasicInfoStep.js.map +1 -1
  77. package/lib/module/steps/LegalExtendedInfoStep.js +10 -3
  78. package/lib/module/steps/LegalExtendedInfoStep.js.map +1 -1
  79. package/lib/module/steps/PhoneContactStep.js +5 -0
  80. package/lib/module/steps/PhoneContactStep.js.map +1 -1
  81. package/lib/module/steps/PhoneOtpStep.js +5 -0
  82. package/lib/module/steps/PhoneOtpStep.js.map +1 -1
  83. package/lib/module/steps/SwornDeclarationStep.js +18 -6
  84. package/lib/module/steps/SwornDeclarationStep.js.map +1 -1
  85. package/lib/module/steps/TaxInfoStep.js +11 -4
  86. package/lib/module/steps/TaxInfoStep.js.map +1 -1
  87. package/lib/module/steps/TermsAndConditionsStep.js +7 -0
  88. package/lib/module/steps/TermsAndConditionsStep.js.map +1 -1
  89. package/lib/module/steps/_shared.js +19 -0
  90. package/lib/module/steps/_shared.js.map +1 -1
  91. package/lib/module/types/index.js +21 -1
  92. package/lib/module/types/index.js.map +1 -1
  93. package/lib/module/ui/StepShell.js +10 -2
  94. package/lib/module/ui/StepShell.js.map +1 -1
  95. package/lib/module/ui/VelionOnboardingScreen.js +25 -5
  96. package/lib/module/ui/VelionOnboardingScreen.js.map +1 -1
  97. package/lib/module/ui/icons/StepIcon.js.map +1 -1
  98. package/lib/module/ui/primitives/BackButton.js +71 -0
  99. package/lib/module/ui/primitives/BackButton.js.map +1 -0
  100. package/lib/module/ui/primitives/index.js +1 -0
  101. package/lib/module/ui/primitives/index.js.map +1 -1
  102. package/lib/typescript/core/VelionOnboarding.d.ts +44 -1
  103. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  104. package/lib/typescript/core/routingCommands.d.ts +39 -0
  105. package/lib/typescript/core/routingCommands.d.ts.map +1 -0
  106. package/lib/typescript/core/sessionStateMapper.d.ts +20 -1
  107. package/lib/typescript/core/sessionStateMapper.d.ts.map +1 -1
  108. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  109. package/lib/typescript/i18n/strings/es.d.ts +1 -0
  110. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  111. package/lib/typescript/index.d.ts +1 -1
  112. package/lib/typescript/index.d.ts.map +1 -1
  113. package/lib/typescript/steps/AddressInfoStep.d.ts.map +1 -1
  114. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  115. package/lib/typescript/steps/EmailContactStep.d.ts.map +1 -1
  116. package/lib/typescript/steps/EmailOtpStep.d.ts.map +1 -1
  117. package/lib/typescript/steps/HumanBasicInfoStep.d.ts.map +1 -1
  118. package/lib/typescript/steps/HumanExtendedInfoStep.d.ts.map +1 -1
  119. package/lib/typescript/steps/LegalBasicInfoStep.d.ts.map +1 -1
  120. package/lib/typescript/steps/LegalExtendedInfoStep.d.ts.map +1 -1
  121. package/lib/typescript/steps/PhoneContactStep.d.ts.map +1 -1
  122. package/lib/typescript/steps/PhoneOtpStep.d.ts.map +1 -1
  123. package/lib/typescript/steps/SwornDeclarationStep.d.ts.map +1 -1
  124. package/lib/typescript/steps/TaxInfoStep.d.ts.map +1 -1
  125. package/lib/typescript/steps/TermsAndConditionsStep.d.ts.map +1 -1
  126. package/lib/typescript/steps/_shared.d.ts +11 -0
  127. package/lib/typescript/steps/_shared.d.ts.map +1 -1
  128. package/lib/typescript/steps/types.d.ts +15 -0
  129. package/lib/typescript/steps/types.d.ts.map +1 -1
  130. package/lib/typescript/types/index.d.ts +104 -5
  131. package/lib/typescript/types/index.d.ts.map +1 -1
  132. package/lib/typescript/ui/StepShell.d.ts +11 -1
  133. package/lib/typescript/ui/StepShell.d.ts.map +1 -1
  134. package/lib/typescript/ui/VelionOnboardingScreen.d.ts +9 -2
  135. package/lib/typescript/ui/VelionOnboardingScreen.d.ts.map +1 -1
  136. package/lib/typescript/ui/icons/StepIcon.d.ts +1 -1
  137. package/lib/typescript/ui/icons/StepIcon.d.ts.map +1 -1
  138. package/lib/typescript/ui/primitives/BackButton.d.ts +20 -0
  139. package/lib/typescript/ui/primitives/BackButton.d.ts.map +1 -0
  140. package/lib/typescript/ui/primitives/index.d.ts +1 -0
  141. package/lib/typescript/ui/primitives/index.d.ts.map +1 -1
  142. package/package.json +1 -1
  143. package/src/core/VelionOnboarding.ts +241 -14
  144. package/src/core/routingCommands.ts +63 -0
  145. package/src/core/sessionStateMapper.ts +65 -0
  146. package/src/i18n/strings/en.ts +1 -0
  147. package/src/i18n/strings/es.ts +1 -0
  148. package/src/index.ts +1 -0
  149. package/src/steps/AddressInfoStep.tsx +38 -20
  150. package/src/steps/DocumentsOcrStep.tsx +5 -0
  151. package/src/steps/EmailContactStep.tsx +6 -0
  152. package/src/steps/EmailOtpStep.tsx +6 -0
  153. package/src/steps/HumanBasicInfoStep.tsx +16 -4
  154. package/src/steps/HumanExtendedInfoStep.tsx +18 -9
  155. package/src/steps/LegalBasicInfoStep.tsx +16 -7
  156. package/src/steps/LegalExtendedInfoStep.tsx +16 -3
  157. package/src/steps/PhoneContactStep.tsx +6 -0
  158. package/src/steps/PhoneOtpStep.tsx +6 -0
  159. package/src/steps/SwornDeclarationStep.tsx +23 -6
  160. package/src/steps/TaxInfoStep.tsx +15 -4
  161. package/src/steps/TermsAndConditionsStep.tsx +8 -0
  162. package/src/steps/_shared.ts +25 -0
  163. package/src/steps/types.ts +15 -0
  164. package/src/types/index.ts +103 -3
  165. package/src/ui/StepShell.tsx +17 -0
  166. package/src/ui/VelionOnboardingScreen.tsx +36 -2
  167. package/src/ui/icons/StepIcon.tsx +2 -1
  168. package/src/ui/primitives/BackButton.tsx +65 -0
  169. package/src/ui/primitives/index.ts +1 -0
@@ -50,6 +50,7 @@ export class TermsAndConditionsStep implements StepModule {
50
50
  sessionId={this.deps.sessionId}
51
51
  locale={this.deps.locale}
52
52
  stepConfig={this.deps.stepConfig as TermsAndConditionsStepConfig | undefined}
53
+ onBack={this.deps.onBack}
53
54
  onComplete={() => {
54
55
  if (this.destroyed) return;
55
56
  this.deps.ui.setNode(null);
@@ -82,6 +83,7 @@ interface ViewProps {
82
83
  sessionId: string;
83
84
  locale: string;
84
85
  stepConfig: TermsAndConditionsStepConfig | undefined;
86
+ onBack?: (() => void) | undefined;
85
87
  onComplete: () => void;
86
88
  onCancel: (err: SdkError) => void;
87
89
  onNoItems: (err: SdkError) => void;
@@ -92,6 +94,7 @@ function TermsAndConditionsView({
92
94
  sessionId,
93
95
  locale,
94
96
  stepConfig,
97
+ onBack,
95
98
  onComplete,
96
99
  onCancel,
97
100
  onNoItems,
@@ -182,6 +185,8 @@ function TermsAndConditionsView({
182
185
  title={t.terms_and_conditions.title}
183
186
  subtitle={t.terms_and_conditions.subtitle}
184
187
  iconNode={<StepIcon name="description" />}
188
+ onBack={onBack}
189
+ backLabel={t.common.back}
185
190
  >
186
191
  <Banner message={t.terms_and_conditions.noItems} />
187
192
  </StepShell>
@@ -194,6 +199,9 @@ function TermsAndConditionsView({
194
199
  title={t.terms_and_conditions.title}
195
200
  subtitle={t.terms_and_conditions.subtitle}
196
201
  iconNode={<StepIcon name="description" />}
202
+ onBack={onBack}
203
+ backLabel={t.common.back}
204
+ backDisabled={submitting}
197
205
  >
198
206
  {items.map((item) => (
199
207
  <View
@@ -42,3 +42,28 @@ export function isE164Phone(value: string): boolean {
42
42
  export function isOtpCode(value: string): boolean {
43
43
  return OTP_REGEX.test(value.trim());
44
44
  }
45
+
46
+ /**
47
+ * Reads a string field from a step's prefill `result` map (sent by the backend
48
+ * on reverse navigation). Returns `''` when absent or not a string, so it can
49
+ * seed a controlled text input directly.
50
+ */
51
+ export function prefillString(
52
+ result: Record<string, unknown> | undefined,
53
+ key: string,
54
+ ): string {
55
+ const value = result?.[key];
56
+ return typeof value === 'string' ? value : '';
57
+ }
58
+
59
+ /**
60
+ * Like {@link prefillString} but returns `null` for empty/absent values — handy
61
+ * for `<Select>` / `<CountrySelect>` / `<DatePicker>` whose empty state is `null`.
62
+ */
63
+ export function prefillStringOrNull(
64
+ result: Record<string, unknown> | undefined,
65
+ key: string,
66
+ ): string | null {
67
+ const value = result?.[key];
68
+ return typeof value === 'string' && value.length > 0 ? value : null;
69
+ }
@@ -42,6 +42,21 @@ export interface StepDeps {
42
42
  ui: StepUiHandle;
43
43
  step: OnboardingStep;
44
44
  stepConfig?: Record<string, unknown>;
45
+ /**
46
+ * Previously-captured data for this step, used as form prefill when the step
47
+ * is re-opened by a reverse navigation (`ROUTING_COMMAND / PREVIOUS_STEP`) or
48
+ * resumed from GET `current_step.result`. Treat it as editable initial state —
49
+ * never re-fire side effects (no re-sending OTPs, no re-uploading documents).
50
+ */
51
+ stepResult?: Record<string, unknown>;
52
+ /**
53
+ * Requests reverse navigation. Present only when the backend reports the user
54
+ * can go back from this step (`can_go_back`); steps render the "back" (chevron)
55
+ * control iff this is set. Fire-and-forget: the orchestrator POSTs
56
+ * `/sessions/:id/back` and the actual transition is driven by the backend over
57
+ * SSE (PREVIOUS_STEP to a prior step, or BACK_EXIT to leave the flow).
58
+ */
59
+ onBack?: () => void;
45
60
  /**
46
61
  * Google Maps Platform API key (Maps + Places). Forwarded to the assisted
47
62
  * `ADDRESS_INFO` flow when the consumer passes it via `VelionConfig`. Steps
@@ -532,6 +532,17 @@ export interface VelionCallbacks {
532
532
  */
533
533
  onFinalResultScreenDismiss?: () => void;
534
534
 
535
+ /**
536
+ * Fires when the user leaves the flow without a verdict — currently only when
537
+ * they tap "back" on the first reversible step (`ROUTING_COMMAND / BACK_EXIT`).
538
+ * The SDK has already torn down its UI; the host should dismiss the SDK screen
539
+ * and return the user to the previous context. Neither `onSuccess` nor
540
+ * `onError` fires in this case.
541
+ *
542
+ * @param exit - Why the flow ended and, when available, the step exited from.
543
+ */
544
+ onExit?: (exit: OnboardingExit) => void;
545
+
535
546
  /**
536
547
  * Fires when the LIVENESS_MATCH step successfully uploaded the recorded
537
548
  * session video to the onboarding storage (GCS PUT returned 200). Best-effort:
@@ -776,6 +787,14 @@ export interface OnboardingStepDto {
776
787
  required?: boolean;
777
788
  /** Step-specific payload (e.g. OCR fields, fingerprint, T&amp;C items). */
778
789
  result?: Record<string, unknown>;
790
+ /**
791
+ * Whether the user may navigate back into this step after completing it.
792
+ * Resolved by the backend (step-type default merged with the workflow
793
+ * override) and surfaced as a first-class flag so the SDK can decide whether
794
+ * to render the "back" (chevron) control. The SDK never hardcodes the
795
+ * reversibility list — it obeys this flag verbatim.
796
+ */
797
+ reversible?: boolean;
779
798
  }
780
799
 
781
800
  /**
@@ -791,12 +810,28 @@ export interface OnboardingDtoResponse {
791
810
  code?: string;
792
811
  status?: string;
793
812
  config?: Record<string, unknown>;
813
+ /** When `true`, the SDK renders the "back" control for this step. */
814
+ reversible?: boolean;
815
+ /**
816
+ * Previously-captured data for the current step (present after a reverse
817
+ * navigation re-opens a completed step). Used as prefill so the form
818
+ * re-renders with the user's earlier answers.
819
+ */
820
+ result?: Record<string, unknown>;
794
821
  };
795
822
  steps?: OnboardingStepDto[];
796
823
  created_at?: string;
797
824
  updated_at?: string;
798
825
  completed_at?: string;
799
826
  metadata?: Record<string, unknown>;
827
+ /**
828
+ * Whether the user can navigate back from `current_step`. Computed server-side
829
+ * from the workflow graph: `true` when there is a previous reversible step to
830
+ * re-open, OR when the current step is the first reversible step (back exits
831
+ * the flow via `BACK_EXIT`). The SDK uses **this** — not a step's intrinsic
832
+ * `reversible` flag — to decide whether to render the "back" control.
833
+ */
834
+ can_go_back?: boolean;
800
835
  /**
801
836
  * Origins (scheme + host + port) authorized by the customer to embed the SDK.
802
837
  * The iframe validates `event.origin` of the loader's first VELION_INIT against
@@ -815,6 +850,25 @@ export interface SessionState {
815
850
  currentStep?: OnboardingStep;
816
851
  /** Step-specific config for `currentStep` from GET /sessions/:id `current_step.config`. */
817
852
  currentStepConfig?: Record<string, unknown>;
853
+ /**
854
+ * Whether the SDK should render the "back" control on `currentStep`. Sourced
855
+ * from GET `can_go_back` (workflow-graph computed). When absent (e.g. reached
856
+ * via SSE), the orchestrator derives it from {@link stepReversibility}.
857
+ */
858
+ canGoBack?: boolean;
859
+ /**
860
+ * Per-step reversibility in workflow order, cached at session load so the
861
+ * orchestrator can derive `can_go_back` for steps reached via SSE (which does
862
+ * not carry the flag): a step can go back when any earlier step is reversible
863
+ * or the step itself is the first reversible one (back exits).
864
+ */
865
+ stepReversibility?: Array<{ code: OnboardingStep; reversible: boolean }>;
866
+ /**
867
+ * Previously-captured data for `currentStep`, used as form prefill after a
868
+ * reverse navigation re-opens a completed step. Sourced from GET
869
+ * `current_step.result`.
870
+ */
871
+ currentStepResult?: Record<string, unknown>;
818
872
  /** Cached configs discovered from GET session and SSE `step_config`. */
819
873
  stepConfigs?: StepConfigMap;
820
874
  /** Session type (HUMAN or LEGAL). Constrains which steps are applicable. */
@@ -828,6 +882,22 @@ export interface SessionState {
828
882
  allowedParentOrigins?: string[];
829
883
  }
830
884
 
885
+ /**
886
+ * Emitted when the user leaves the onboarding flow without a backend verdict.
887
+ *
888
+ * Currently the only trigger is `BACK_EXIT`: the user tapped "back" on the
889
+ * first reversible step, where there is no earlier step to return to, so the
890
+ * backend instructs the SDK to exit. This is neither success nor error — the
891
+ * host should dismiss the SDK screen and return the user to wherever they came
892
+ * from. See {@link VelionCallbacks.onExit}.
893
+ */
894
+ export interface OnboardingExit {
895
+ /** Why the flow ended without a verdict. */
896
+ reason: 'BACK_EXIT';
897
+ /** The step the user exited from (SSE `step_code`), when the backend provides it. */
898
+ step?: OnboardingStep;
899
+ }
900
+
831
901
  /**
832
902
  * A single T&amp;C line item (matches backend TermsAndConditionsItemDto / domain record).
833
903
  */
@@ -1078,10 +1148,20 @@ export interface TermsAndConditionsSubmitPayload {
1078
1148
  *
1079
1149
  * Event types (event_type):
1080
1150
  * - STEP_UPDATED — a workflow step changed status (step_code, step_status)
1081
- * - ROUTING_COMMAND — next/retry/terminate instruction (action: NEXT_STEP | RETRY_STEP | TERMINATE)
1151
+ * - ROUTING_COMMAND — next/previous/retry/terminate instruction
1152
+ * (action: NEXT_STEP | PREVIOUS_STEP | RETRY_STEP | TERMINATE)
1082
1153
  * - SESSION_APPROVED — all checks passed; session_status = APPROVED
1083
1154
  * - SESSION_MANUAL_REVIEW — manual review required; session_status = MANUAL_REVIEW
1084
1155
  * - SESSION_DECLINED — session ended with decline (step_code, session_status DECLINED, reason)
1156
+ *
1157
+ * Reverse navigation ("back") arrives as a STEP_UPDATED (the re-opened step
1158
+ * moves to IN_PROGRESS) followed by a ROUTING_COMMAND with action PREVIOUS_STEP
1159
+ * carrying `step_config` and `step_result` (prefill) for the re-opened step.
1160
+ *
1161
+ * Tapping "back" on the first interactive (reversible) step instead yields a
1162
+ * ROUTING_COMMAND with action BACK_EXIT (`step_code` = the step exited from):
1163
+ * there is no earlier reversible step, so the SDK leaves the flow and returns
1164
+ * control to the host (see {@link VelionCallbacks.onExit}).
1085
1165
  */
1086
1166
  export interface OnboardingSessionEvent {
1087
1167
  /** Onboarding session identifier (Long in backend). */
@@ -1094,12 +1174,29 @@ export interface OnboardingSessionEvent {
1094
1174
  step_status?: string;
1095
1175
  /** Present for terminal events; e.g. APPROVED | MANUAL_REVIEW | REJECTED. */
1096
1176
  session_status?: string;
1097
- /** For ROUTING_COMMAND: NEXT_STEP | RETRY_STEP (render step_code) or TERMINATE (end flow). */
1177
+ /**
1178
+ * For ROUTING_COMMAND: NEXT_STEP | PREVIOUS_STEP | RETRY_STEP (render step_code),
1179
+ * BACK_EXIT (user backed out of the first reversible step — leave the flow),
1180
+ * or TERMINATE (end flow).
1181
+ */
1098
1182
  action?: string;
1099
1183
  /** For SESSION_DECLINED / SESSION_MANUAL_REVIEW or ROUTING_COMMAND TERMINATE; e.g. UNREADABLE_DOCUMENT. */
1100
1184
  reason?: string;
1101
- /** Step-specific config sent with ROUTING_COMMAND NEXT_STEP. */
1185
+ /** Step-specific config sent with ROUTING_COMMAND NEXT_STEP / PREVIOUS_STEP. */
1102
1186
  step_config?: Record<string, unknown>;
1187
+ /**
1188
+ * Previously-captured data for the re-opened step, sent with ROUTING_COMMAND
1189
+ * PREVIOUS_STEP. The SDK uses it to prefill the step's form on reverse
1190
+ * navigation.
1191
+ */
1192
+ step_result?: Record<string, unknown>;
1193
+ /**
1194
+ * Whether the user can navigate back from the step this command routes to.
1195
+ * Optional: when the backend includes it on a ROUTING_COMMAND the SDK uses it
1196
+ * to decide the "back" control verbatim; otherwise the SDK derives it from the
1197
+ * step reversibility map cached at session load.
1198
+ */
1199
+ can_go_back?: boolean;
1103
1200
  /** Epoch millis; used as SSE id for Last-Event-ID on reconnect. */
1104
1201
  event_id?: number;
1105
1202
  }
@@ -1175,6 +1272,7 @@ export type SdkStatus =
1175
1272
  | 'RUNNING' // Orchestrating steps
1176
1273
  | 'STEP_PROCESSING'// A module is actively running
1177
1274
  | 'COMPLETED' // All steps done, onSuccess fired
1275
+ | 'EXITED' // User left the flow via back on the first step, onExit fired
1178
1276
  | 'ERROR' // Unrecoverable error, onError fired
1179
1277
  | 'DESTROYED'; // destroy() was called, instance is a no-op
1180
1278
 
@@ -1187,6 +1285,7 @@ export type SdkEventName =
1187
1285
  | 'step:complete'
1188
1286
  | 'session:loaded'
1189
1287
  | 'flow:complete'
1288
+ | 'flow:exit'
1190
1289
  | 'error'
1191
1290
  | 'status:change';
1192
1291
 
@@ -1200,6 +1299,7 @@ export interface SdkEventMap extends Record<string, unknown> {
1200
1299
  'step:complete': { step: OnboardingStep };
1201
1300
  'session:loaded': SessionState;
1202
1301
  'flow:complete': OnboardingResult;
1302
+ 'flow:exit': OnboardingExit;
1203
1303
  'error': SdkError;
1204
1304
  'status:change': SdkStatus;
1205
1305
  }
@@ -16,6 +16,7 @@ import {
16
16
  View,
17
17
  } from 'react-native';
18
18
  import { useTheme, withAlpha } from './theme';
19
+ import { BackButton } from './primitives/BackButton';
19
20
 
20
21
  export interface StepShellProps {
21
22
  title: string;
@@ -25,6 +26,16 @@ export interface StepShellProps {
25
26
  children: ReactNode;
26
27
  /** When true, the body is wrapped in a `KeyboardAvoidingView` (form-friendly). */
27
28
  avoidKeyboard?: boolean | undefined;
29
+ /**
30
+ * When provided, renders a top-left "back" (chevron) control. Only reversible
31
+ * steps wire this — the orchestrator decides based on the backend's
32
+ * `reversible` flag, so non-reversible steps simply omit it.
33
+ */
34
+ onBack?: (() => void) | undefined;
35
+ /** Label for the back control (localized). Defaults are provided by callers. */
36
+ backLabel?: string | undefined;
37
+ /** Disables the back control (e.g. while a back request is already in flight). */
38
+ backDisabled?: boolean | undefined;
28
39
  }
29
40
 
30
41
  export function StepShell({
@@ -33,6 +44,9 @@ export function StepShell({
33
44
  iconNode,
34
45
  children,
35
46
  avoidKeyboard = true,
47
+ onBack,
48
+ backLabel = 'Atrás',
49
+ backDisabled = false,
36
50
  }: StepShellProps) {
37
51
  const theme = useTheme();
38
52
 
@@ -44,6 +58,9 @@ export function StepShell({
44
58
  contentContainerStyle={styles.scrollBody}
45
59
  keyboardShouldPersistTaps="handled"
46
60
  >
61
+ {onBack ? (
62
+ <BackButton label={backLabel} onPress={onBack} disabled={backDisabled} />
63
+ ) : null}
47
64
  <View style={styles.header}>
48
65
  {showIconCircle ? (
49
66
  <View
@@ -17,7 +17,12 @@ import React, {
17
17
  } from 'react';
18
18
  import { StyleSheet, Text, View } from 'react-native';
19
19
  import { VelionOnboarding, type VelionConfig } from '../core/VelionOnboarding';
20
- import type { OnboardingResult, OnboardingStep, SdkError } from '../types';
20
+ import type {
21
+ OnboardingExit,
22
+ OnboardingResult,
23
+ OnboardingStep,
24
+ SdkError,
25
+ } from '../types';
21
26
  import { ThemeProvider, useTheme } from './theme';
22
27
  import { LoadingOverlay } from './overlays/LoadingOverlay';
23
28
  import { PROGRESS_BAR, ProgressBar } from './overlays/ProgressBar';
@@ -31,6 +36,13 @@ export interface VelionOnboardingScreenProps {
31
36
  config: VelionConfig;
32
37
  onComplete?: ((result: OnboardingResult) => void) | undefined;
33
38
  onFail?: ((err: SdkError) => void) | undefined;
39
+ /**
40
+ * Fires when the user leaves the flow without a verdict — they tapped "back"
41
+ * on the first reversible step (`BACK_EXIT`). The SDK has cleared its UI; the
42
+ * host should dismiss/unmount this screen and return the user to the previous
43
+ * context. Mirrors `VelionConfig.onExit`.
44
+ */
45
+ onExit?: ((exit: OnboardingExit) => void) | undefined;
34
46
  }
35
47
 
36
48
  interface ViewState {
@@ -38,6 +50,8 @@ interface ViewState {
38
50
  stepNode: ReactNode | null;
39
51
  error: SdkError | null;
40
52
  result: OnboardingResult | null;
53
+ /** Set once the user backed out of the first step; renders a blank surface. */
54
+ exited: boolean;
41
55
  }
42
56
 
43
57
  const INITIAL_STATE: ViewState = {
@@ -45,12 +59,14 @@ const INITIAL_STATE: ViewState = {
45
59
  stepNode: null,
46
60
  error: null,
47
61
  result: null,
62
+ exited: false,
48
63
  };
49
64
 
50
65
  export function VelionOnboardingScreen({
51
66
  config,
52
67
  onComplete,
53
68
  onFail,
69
+ onExit,
54
70
  }: VelionOnboardingScreenProps) {
55
71
  return (
56
72
  <ThemeProvider
@@ -61,6 +77,7 @@ export function VelionOnboardingScreen({
61
77
  config={config}
62
78
  onComplete={onComplete}
63
79
  onFail={onFail}
80
+ onExit={onExit}
64
81
  />
65
82
  </ThemeProvider>
66
83
  );
@@ -70,6 +87,7 @@ function VelionOnboardingInner({
70
87
  config,
71
88
  onComplete,
72
89
  onFail,
90
+ onExit,
73
91
  }: VelionOnboardingScreenProps) {
74
92
  const theme = useTheme();
75
93
  const t = getStrings(config.locale);
@@ -89,8 +107,10 @@ function VelionOnboardingInner({
89
107
 
90
108
  const onCompleteRef = useRef(onComplete);
91
109
  const onFailRef = useRef(onFail);
110
+ const onExitRef = useRef(onExit);
92
111
  onCompleteRef.current = onComplete;
93
112
  onFailRef.current = onFail;
113
+ onExitRef.current = onExit;
94
114
 
95
115
  useEffect(() => {
96
116
  // Hold a wake lock for the full duration of the flow. Camera-heavy steps
@@ -113,6 +133,20 @@ function VelionOnboardingInner({
113
133
  setTimeout(() => setProgressHidden(true), 400);
114
134
  onCompleteRef.current?.(result);
115
135
  },
136
+ setExit: (exit) => {
137
+ // User backed out of the first step: blank the surface (no overlay, no
138
+ // result) and let the host dismiss the screen via onExit.
139
+ setState((s) => ({
140
+ ...s,
141
+ exited: true,
142
+ loading: null,
143
+ stepNode: null,
144
+ error: null,
145
+ result: null,
146
+ }));
147
+ setProgressHidden(true);
148
+ onExitRef.current?.(exit);
149
+ },
116
150
  });
117
151
 
118
152
  const unsubStepChange = sdk.on('step:change', () => {
@@ -169,7 +203,7 @@ function VelionOnboardingInner({
169
203
  }, [state, theme, t]);
170
204
 
171
205
  const showLoadingOverlay =
172
- !state.error && !state.result && !state.stepNode;
206
+ !state.error && !state.result && !state.stepNode && !state.exited;
173
207
  const loadingText = state.loading ?? t.common.loading;
174
208
  // Progress bar is shown unless EITHER `config.showProgressBar === false`
175
209
  // OR `theme.hideProgressBar === true`. Both paths exist for parity with
@@ -27,7 +27,8 @@ export type MaterialIconName =
27
27
  | 'phone-iphone'
28
28
  | 'face'
29
29
  | 'photo-camera'
30
- | 'fingerprint';
30
+ | 'fingerprint'
31
+ | 'chevron-left';
31
32
 
32
33
  let MaterialIcons:
33
34
  | (new () => unknown)
@@ -0,0 +1,65 @@
1
+ /**
2
+ * @fileoverview BackButton — the "Atrás" / "Back" control for reversible steps.
3
+ *
4
+ * A small, top-left chevron-back pill rendered by `StepShell` only when the
5
+ * current step is reversible (the backend's `reversible` flag drives this; the
6
+ * SDK never decides reversibility on its own). Tapping it asks the orchestrator
7
+ * to navigate to the previous reversible step — the actual transition is driven
8
+ * by the backend's `ROUTING_COMMAND / PREVIOUS_STEP` over SSE.
9
+ *
10
+ * The chevron uses `MaterialIcons` (via `StepIcon`); when `@expo/vector-icons`
11
+ * is unavailable the icon falls back gracefully and only the label shows.
12
+ */
13
+
14
+ import { Pressable, StyleSheet, Text } from 'react-native';
15
+ import { useTheme, withAlpha } from '../theme';
16
+ import { StepIcon } from '../icons/StepIcon';
17
+
18
+ export interface BackButtonProps {
19
+ label: string;
20
+ onPress: () => void;
21
+ /** Disables the control (e.g. while a back request is already in flight). */
22
+ disabled?: boolean;
23
+ }
24
+
25
+ export function BackButton({ label, onPress, disabled = false }: BackButtonProps) {
26
+ const theme = useTheme();
27
+ return (
28
+ <Pressable
29
+ accessibilityRole="button"
30
+ accessibilityLabel={label}
31
+ accessibilityState={{ disabled }}
32
+ disabled={disabled}
33
+ onPress={onPress}
34
+ hitSlop={8}
35
+ style={({ pressed }) => [
36
+ styles.base,
37
+ pressed && !disabled && { backgroundColor: withAlpha(theme.textColor, 0.06) },
38
+ disabled && styles.disabled,
39
+ ]}
40
+ >
41
+ <StepIcon name="chevron-left" size={20} color={theme.textColor} />
42
+ <Text style={[styles.label, { color: theme.textColor }]}>{label}</Text>
43
+ </Pressable>
44
+ );
45
+ }
46
+
47
+ const styles = StyleSheet.create({
48
+ base: {
49
+ flexDirection: 'row',
50
+ alignItems: 'center',
51
+ alignSelf: 'flex-start',
52
+ minHeight: 44,
53
+ paddingRight: 10,
54
+ paddingVertical: 6,
55
+ marginLeft: -4,
56
+ },
57
+ disabled: {
58
+ opacity: 0.45,
59
+ },
60
+ label: {
61
+ fontSize: 15,
62
+ fontWeight: '600',
63
+ marginLeft: 2,
64
+ },
65
+ });
@@ -1,4 +1,5 @@
1
1
  export { Button, type ButtonProps, type ButtonVariant } from './Button';
2
+ export { BackButton, type BackButtonProps } from './BackButton';
2
3
  export { Input, type InputProps } from './Input';
3
4
  export { Select, type SelectProps, type SelectOption } from './Select';
4
5
  export { Card, type CardProps } from './Card';