@velion-la/onboarding-sdk-react-native 1.4.0-beta.7 → 1.4.0-beta.9

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 (135) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +82 -1
  3. package/lib/commonjs/core/VelionOnboarding.js +156 -46
  4. package/lib/commonjs/core/VelionOnboarding.js.map +1 -1
  5. package/lib/commonjs/core/routingCommands.js +33 -0
  6. package/lib/commonjs/core/routingCommands.js.map +1 -1
  7. package/lib/commonjs/core/sessionStateMapper.js +48 -36
  8. package/lib/commonjs/core/sessionStateMapper.js.map +1 -1
  9. package/lib/commonjs/i18n/strings/en.js +27 -0
  10. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  11. package/lib/commonjs/i18n/strings/es.js +27 -0
  12. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  13. package/lib/commonjs/index.js +6 -0
  14. package/lib/commonjs/index.js.map +1 -1
  15. package/lib/commonjs/steps/CustomFormStep.js +348 -0
  16. package/lib/commonjs/steps/CustomFormStep.js.map +1 -0
  17. package/lib/commonjs/steps/EntityTypeSelectionStep.js +194 -0
  18. package/lib/commonjs/steps/EntityTypeSelectionStep.js.map +1 -0
  19. package/lib/commonjs/steps/customForm.js +251 -0
  20. package/lib/commonjs/steps/customForm.js.map +1 -0
  21. package/lib/commonjs/steps/entityType.js +30 -0
  22. package/lib/commonjs/steps/entityType.js.map +1 -0
  23. package/lib/commonjs/steps/submissionOutcome.js +101 -0
  24. package/lib/commonjs/steps/submissionOutcome.js.map +1 -0
  25. package/lib/commonjs/steps/unsupportedStep.js +33 -0
  26. package/lib/commonjs/steps/unsupportedStep.js.map +1 -0
  27. package/lib/commonjs/transport/api.js +9 -0
  28. package/lib/commonjs/transport/api.js.map +1 -1
  29. package/lib/commonjs/types/index.js +60 -4
  30. package/lib/commonjs/types/index.js.map +1 -1
  31. package/lib/commonjs/ui/VelionOnboardingScreen.js +20 -3
  32. package/lib/commonjs/ui/VelionOnboardingScreen.js.map +1 -1
  33. package/lib/commonjs/ui/primitives/RadioCard.js +120 -0
  34. package/lib/commonjs/ui/primitives/RadioCard.js.map +1 -0
  35. package/lib/commonjs/ui/primitives/Select.js +60 -7
  36. package/lib/commonjs/ui/primitives/Select.js.map +1 -1
  37. package/lib/commonjs/ui/primitives/index.js +7 -0
  38. package/lib/commonjs/ui/primitives/index.js.map +1 -1
  39. package/lib/commonjs/utils/sdkVersion.js +1 -1
  40. package/lib/module/core/VelionOnboarding.js +158 -48
  41. package/lib/module/core/VelionOnboarding.js.map +1 -1
  42. package/lib/module/core/routingCommands.js +33 -0
  43. package/lib/module/core/routingCommands.js.map +1 -1
  44. package/lib/module/core/sessionStateMapper.js +47 -36
  45. package/lib/module/core/sessionStateMapper.js.map +1 -1
  46. package/lib/module/i18n/strings/en.js +27 -0
  47. package/lib/module/i18n/strings/en.js.map +1 -1
  48. package/lib/module/i18n/strings/es.js +27 -0
  49. package/lib/module/i18n/strings/es.js.map +1 -1
  50. package/lib/module/index.js +1 -1
  51. package/lib/module/index.js.map +1 -1
  52. package/lib/module/steps/CustomFormStep.js +345 -0
  53. package/lib/module/steps/CustomFormStep.js.map +1 -0
  54. package/lib/module/steps/EntityTypeSelectionStep.js +189 -0
  55. package/lib/module/steps/EntityTypeSelectionStep.js.map +1 -0
  56. package/lib/module/steps/customForm.js +237 -0
  57. package/lib/module/steps/customForm.js.map +1 -0
  58. package/lib/module/steps/entityType.js +24 -0
  59. package/lib/module/steps/entityType.js.map +1 -0
  60. package/lib/module/steps/submissionOutcome.js +94 -0
  61. package/lib/module/steps/submissionOutcome.js.map +1 -0
  62. package/lib/module/steps/unsupportedStep.js +30 -0
  63. package/lib/module/steps/unsupportedStep.js.map +1 -0
  64. package/lib/module/transport/api.js +9 -0
  65. package/lib/module/transport/api.js.map +1 -1
  66. package/lib/module/types/index.js +68 -3
  67. package/lib/module/types/index.js.map +1 -1
  68. package/lib/module/ui/VelionOnboardingScreen.js +21 -4
  69. package/lib/module/ui/VelionOnboardingScreen.js.map +1 -1
  70. package/lib/module/ui/primitives/RadioCard.js +116 -0
  71. package/lib/module/ui/primitives/RadioCard.js.map +1 -0
  72. package/lib/module/ui/primitives/Select.js +62 -9
  73. package/lib/module/ui/primitives/Select.js.map +1 -1
  74. package/lib/module/ui/primitives/index.js +1 -0
  75. package/lib/module/ui/primitives/index.js.map +1 -1
  76. package/lib/module/utils/sdkVersion.js +1 -1
  77. package/lib/typescript/core/VelionOnboarding.d.ts +42 -5
  78. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  79. package/lib/typescript/core/routingCommands.d.ts +23 -0
  80. package/lib/typescript/core/routingCommands.d.ts.map +1 -1
  81. package/lib/typescript/core/sessionStateMapper.d.ts +13 -5
  82. package/lib/typescript/core/sessionStateMapper.d.ts.map +1 -1
  83. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  84. package/lib/typescript/i18n/strings/es.d.ts +27 -0
  85. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  86. package/lib/typescript/index.d.ts +3 -3
  87. package/lib/typescript/index.d.ts.map +1 -1
  88. package/lib/typescript/steps/CustomFormStep.d.ts +28 -0
  89. package/lib/typescript/steps/CustomFormStep.d.ts.map +1 -0
  90. package/lib/typescript/steps/EntityTypeSelectionStep.d.ts +24 -0
  91. package/lib/typescript/steps/EntityTypeSelectionStep.d.ts.map +1 -0
  92. package/lib/typescript/steps/customForm.d.ts +99 -0
  93. package/lib/typescript/steps/customForm.d.ts.map +1 -0
  94. package/lib/typescript/steps/entityType.d.ts +15 -0
  95. package/lib/typescript/steps/entityType.d.ts.map +1 -0
  96. package/lib/typescript/steps/submissionOutcome.d.ts +43 -0
  97. package/lib/typescript/steps/submissionOutcome.d.ts.map +1 -0
  98. package/lib/typescript/steps/types.d.ts +5 -0
  99. package/lib/typescript/steps/types.d.ts.map +1 -1
  100. package/lib/typescript/steps/unsupportedStep.d.ts +15 -0
  101. package/lib/typescript/steps/unsupportedStep.d.ts.map +1 -0
  102. package/lib/typescript/transport/api.d.ts +1 -0
  103. package/lib/typescript/transport/api.d.ts.map +1 -1
  104. package/lib/typescript/types/index.d.ts +139 -14
  105. package/lib/typescript/types/index.d.ts.map +1 -1
  106. package/lib/typescript/ui/VelionOnboardingScreen.d.ts +21 -2
  107. package/lib/typescript/ui/VelionOnboardingScreen.d.ts.map +1 -1
  108. package/lib/typescript/ui/primitives/RadioCard.d.ts +22 -0
  109. package/lib/typescript/ui/primitives/RadioCard.d.ts.map +1 -0
  110. package/lib/typescript/ui/primitives/Select.d.ts +9 -3
  111. package/lib/typescript/ui/primitives/Select.d.ts.map +1 -1
  112. package/lib/typescript/ui/primitives/index.d.ts +1 -0
  113. package/lib/typescript/ui/primitives/index.d.ts.map +1 -1
  114. package/lib/typescript/utils/sdkVersion.d.ts +1 -1
  115. package/package.json +1 -1
  116. package/src/core/VelionOnboarding.ts +168 -55
  117. package/src/core/routingCommands.ts +42 -0
  118. package/src/core/sessionStateMapper.ts +63 -52
  119. package/src/i18n/strings/en.ts +28 -0
  120. package/src/i18n/strings/es.ts +28 -0
  121. package/src/index.ts +10 -0
  122. package/src/steps/CustomFormStep.tsx +400 -0
  123. package/src/steps/EntityTypeSelectionStep.tsx +207 -0
  124. package/src/steps/customForm.ts +302 -0
  125. package/src/steps/entityType.ts +25 -0
  126. package/src/steps/submissionOutcome.ts +93 -0
  127. package/src/steps/types.ts +5 -0
  128. package/src/steps/unsupportedStep.ts +32 -0
  129. package/src/transport/api.ts +16 -1
  130. package/src/types/index.ts +151 -17
  131. package/src/ui/VelionOnboardingScreen.tsx +38 -1
  132. package/src/ui/primitives/RadioCard.tsx +127 -0
  133. package/src/ui/primitives/Select.tsx +73 -7
  134. package/src/ui/primitives/index.ts +1 -0
  135. package/src/utils/sdkVersion.ts +1 -1
package/CHANGELOG.md CHANGED
@@ -10,6 +10,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
10
10
 
11
11
  ### Added
12
12
 
13
+ - `cancelSession(): Promise<void>` lets the integrator cancel the session
14
+ (OSDKR-44, backend VON-133), with the same name and semantics as the web SDK.
15
+ Available on `VelionOnboarding` and, through a `ref`, on
16
+ `<VelionOnboardingScreen>` (new `VelionOnboardingScreenHandle` type, which
17
+ also exposes `refreshSessionToken()`). It sends
18
+ `POST /sessions/:id/cancel`; on `204` the flow ends exactly as when the
19
+ backend cancels the session (`onSessionEvent` with `SESSION_CANCELLED`, then
20
+ `onError` / `onFail` with `SdkErrorCode.SESSION_CANCELLED`), the event stream
21
+ is closed and the later `SESSION_CANCELLED` SSE event is ignored, so the host
22
+ is told once. On failure the flow keeps running and the promise rejects with a
23
+ `CancelSessionError` whose `code` is a `CancelSessionErrorCode`:
24
+ `SESSION_NOT_OPEN` (`409` `VOB-40913`), `UNAUTHORIZED` (`401` / `403`; rotate
25
+ the token with `refreshSessionToken()` and call again) or `NETWORK`. Requires
26
+ the onboarding API with the SDK cancel endpoint (VON-133).
27
+
28
+ - `CUSTOM_FORM` and `ENTITY_TYPE_SELECTION` steps (OSDKR-47). Until now either
29
+ step stopped the flow with `UNKNOWN` ("not implemented yet"), so a workflow
30
+ using them could not be completed in an app.
31
+ - `CUSTOM_FORM` renders the workflow's `form_fields` (`TEXT`, `NUMBER`,
32
+ `BOOLEAN` as Yes / No, `DATE`, `LIST`, searchable above eight options) under
33
+ the optional `title` / `subtitle`, validates them with the same rules as the
34
+ backend and the web SDK, and submits
35
+ `POST /sessions/:id/custom-form/:stepKey { responses }`. An optional field
36
+ left empty is omitted. The backend's per-field `400` messages
37
+ (`errors["responses.<field_key>"]`) show next to each field.
38
+ - `ENTITY_TYPE_SELECTION` offers individual (`HUMAN`) or legal entity
39
+ (`LEGAL`) and submits `POST /sessions/:id/entity-type { selected_type }`.
40
+ - Both prefill the previous answers when the person goes back
41
+ (`step_result.responses` / `step_result.selected_type`).
42
+ - A submit refused because the session already left the step (`409`
43
+ `VOB-40908`) ends the step and follows the backend's routing instead of
44
+ offering a retry that cannot succeed.
45
+ - New public types: `CustomFormStepConfig`, `CustomFormField`,
46
+ `CustomFormFieldType`, `CustomFormSubmitPayload`, `CustomFormResponseValue`,
47
+ `EntityTypeSelectionPayload` and `EntityType`.
48
+ - Step instances are told apart by `step_key` (OSDKR-47). The step code still
49
+ picks the screen; the key (from `current_step.step_key`, `steps[].step_key`
50
+ and the SSE `step_key`, falling back to the code on older backends) picks the
51
+ instance. A `NEXT_STEP` from one `CUSTOM_FORM` to another is no longer
52
+ dropped as a duplicate, configs and back-navigation availability are cached
53
+ per key, and "back" sends the key as `from_step`. `SdkError` gains `stepKey`.
54
+ - `SdkErrorCode.UNSUPPORTED_STEP` (OSDKR-47). A step code this SDK does not
55
+ know, or a `CUSTOM_FORM` with a required field of an unknown type, stops the
56
+ flow with a "this step is not available" screen and
57
+ `onError({ code: 'UNSUPPORTED_STEP', stepCode, stepKey })`, instead of
58
+ `UNKNOWN`. The step is never skipped: the backend would decline the session.
59
+ An optional field of an unknown type renders as text.
60
+
13
61
  - A request rejected because the session was cancelled ends the flow
14
62
  (OSDKR-49). When the backend cancels a session it revokes the token, and a
15
63
  request that arrives after that gets a `401` problem+json with
@@ -60,6 +108,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
60
108
  `onError({ code: 'ROUTING_TIMEOUT', stepCode })`, where `stepCode` is the
61
109
  step that was completed and never routed.
62
110
 
111
+ ### Changed
112
+
113
+ - `OnboardingDtoResponse` no longer has `onboarding_type` and `SessionState`
114
+ no longer has `onboardingType` (OSDKR-47): the backend does not send it; the
115
+ person picks the entity type in `ENTITY_TYPE_SELECTION`. `OnboardingType`
116
+ stays as a deprecated alias of `EntityType`. `StepConfigMap` is now keyed by
117
+ step key instead of step code.
118
+
63
119
  ### Fixed
64
120
 
65
121
  - The SDK reports its real version (OSDKR-48). `X-Velion-SDK-Version` and
package/README.md CHANGED
@@ -352,6 +352,57 @@ sdk.destroy();
352
352
 
353
353
  `<VelionOnboardingScreen>` is a thin wrapper over this API.
354
354
 
355
+ ### Cancelling the session (`cancelSession`)
356
+
357
+ To cancel the session from your app (e.g. a "Cancel verification" button in
358
+ your own chrome), call `cancelSession()` — through a `ref` on the component, or
359
+ directly on a `VelionOnboarding` instance. Same name and semantics as the web
360
+ SDK.
361
+
362
+ ```tsx
363
+ import {
364
+ VelionOnboardingScreen,
365
+ CancelSessionErrorCode,
366
+ type CancelSessionError,
367
+ type VelionOnboardingScreenHandle,
368
+ } from '@velion-la/onboarding-sdk-react-native';
369
+
370
+ const ref = useRef<VelionOnboardingScreenHandle>(null);
371
+
372
+ <VelionOnboardingScreen ref={ref} config={config} onFail={handleFail} />;
373
+
374
+ async function onCancelPressed() {
375
+ try {
376
+ await ref.current?.cancelSession();
377
+ // The flow already ended: onFail / onError got SESSION_CANCELLED.
378
+ } catch (e) {
379
+ const err = e as CancelSessionError;
380
+ if (err.code === CancelSessionErrorCode.UNAUTHORIZED) {
381
+ ref.current?.refreshSessionToken(await fetchFreshToken()); // then try again
382
+ }
383
+ }
384
+ }
385
+ ```
386
+
387
+ `cancelSession(): Promise<void>` sends `POST /sessions/{sessionId}/cancel` with
388
+ the session token. Once the backend confirms (`204`) the flow ends **exactly as
389
+ when the backend cancels the session**: `onSessionEvent` with a
390
+ `SESSION_CANCELLED` event, then `onError` / `onFail` with
391
+ `SdkErrorCode.SESSION_CANCELLED` and the cancelled screen. The event stream is
392
+ closed, and the `SESSION_CANCELLED` event the backend also publishes is
393
+ ignored, so your callbacks fire once. The promise resolves after that, and
394
+ resolves at once if the session was already cancelled. Concurrent calls share
395
+ one request.
396
+
397
+ If the request fails the flow keeps running and the promise rejects with a
398
+ `CancelSessionError` (`code`, `message`, `httpStatus?`, `cause?`):
399
+
400
+ | `code` | Meaning |
401
+ |---|---|
402
+ | `SESSION_NOT_OPEN` | `409` `VOB-40913`: the session already reached a verdict or was closed. Nothing to cancel. |
403
+ | `UNAUTHORIZED` | The session token was rejected (`401` / `403`) or has expired. The SDK does not renew tokens by itself: rotate it with `refreshSessionToken()` (also on the component `ref`) and call `cancelSession()` again. |
404
+ | `NETWORK` | The request did not get through (no connectivity, or an unexpected status — `httpStatus` is set then). Safe to retry. |
405
+
355
406
  ### Mount once per session
356
407
 
357
408
  `<VelionOnboardingScreen>` opens an SSE stream and drives a state machine on
@@ -516,6 +567,7 @@ Possible `SdkErrorCode` values:
516
567
  | `SESSION_DECLINED` | Backend sent `SESSION_DECLINED` over SSE. |
517
568
  | `SESSION_CANCELLED` | The backend cancelled the session: `SESSION_CANCELLED` over SSE, `status: CANCELLED` on load, or a request rejected with the 401 `VOB-40103` (the SDK then also calls `onSessionEvent` with a `SESSION_CANCELLED` event, as if it had come over SSE). Not a verdict on the person. `cancelReason` carries the backend reason (e.g. `WORKFLOW_VERSION_RETIRED`). The session token is revoked: the SDK closes the event stream and sends no further requests. Create a new session to let the person start again. |
518
569
  | `ROUTING_TIMEOUT` | A step was completed but the backend did not route the session to the next one within `routingTimeoutMs` (default 120 s). The session is still alive; `stepCode` is the completed step. |
570
+ | `UNSUPPORTED_STEP` | The backend routed the session to a step this SDK version cannot render (an unknown step code, or a `CUSTOM_FORM` with a required field of an unknown type). `stepCode` and `stepKey` name it. The step is not skipped; ship a newer SDK. |
519
571
  | `FINGERPRINT_FAILED` | Visitor id could not be generated. |
520
572
  | `DOCUMENT_UPLOAD_FAILED` | `PUT` to the signed URL or `verify` step failed. |
521
573
  | `LIVENESS_FAILED` | Liveness service closed the WebSocket with a terminal warning. |
@@ -892,10 +944,36 @@ without `lat`/`lng`.
892
944
  | `DOCUMENTS_OCR` | `POST /documents-init` + `PUT` × 2 + `verify` | Camera + intro tips |
893
945
  | `LIVENESS_MATCH` | `POST /liveness-init` + WebSocket + `verify` | Front camera + oval mask |
894
946
  | `FACE_MATCH` | (backend-only, no POST) | Loading + poll |
947
+ | `CUSTOM_FORM` | `POST /custom-form/:stepKey` | Form built from `form_fields` |
948
+ | `ENTITY_TYPE_SELECTION` | `POST /entity-type` | Two cards: individual / legal entity |
895
949
 
896
950
  The order is determined dynamically by the backend via `current_step` and
897
951
  the SSE `ROUTING_COMMAND` events. The SDK does no client-side routing.
898
952
 
953
+ The step **code** (`code` / `step_code`) picks the screen; the step **key**
954
+ (`step_key`, the code when the backend sends none) picks the instance. They
955
+ only differ for `CUSTOM_FORM`: a workflow may hold several forms, each with its
956
+ own key, and the SDK submits each to `POST /custom-form/:stepKey`.
957
+
958
+ `CUSTOM_FORM` renders the workflow's `form_fields` with the optional `title` /
959
+ `subtitle` (a generic title otherwise). Field types:
960
+
961
+ | `type` | Control | Sent in `responses` |
962
+ |---|---|---|
963
+ | `TEXT` | Text input | Trimmed string, at most 255 characters |
964
+ | `NUMBER` | Decimal keyboard (comma or dot) | JSON number |
965
+ | `BOOLEAN` | Yes / No cards | `true` / `false` |
966
+ | `DATE` | Day / month / year selects | `"yyyy-MM-dd"` |
967
+ | `LIST` | Select, searchable above 8 options | One of `options` |
968
+
969
+ An optional field left empty is omitted. The backend validates the same rules;
970
+ its per-field `400` messages are shown next to each field.
971
+
972
+ A step the SDK does not know — or a `CUSTOM_FORM` with a required field of an
973
+ unknown type — is never skipped: the flow stops with a "this step is not
974
+ available" screen and `onError({ code: 'UNSUPPORTED_STEP', stepCode, stepKey })`.
975
+ Publish an app with a newer SDK to support it.
976
+
899
977
  ---
900
978
 
901
979
  ## Reverse navigation ("Back")
@@ -944,7 +1022,10 @@ How it works, end to end:
944
1022
 
945
1023
  Reversible form steps and the data they prefill: `HUMAN_BASIC_INFO`,
946
1024
  `LEGAL_BASIC_INFO`, `HUMAN_EXTENDED_INFO`, `LEGAL_EXTENDED_INFO`, `TAX_INFO`,
947
- and `ADDRESS_INFO`. For the assisted (map-based) address flow the structured
1025
+ `ADDRESS_INFO`, `CUSTOM_FORM` (`step_result.responses`) and
1026
+ `ENTITY_TYPE_SELECTION` (`step_result.selected_type`). Going back sends the
1027
+ step key as `from_step`, so the backend knows which of several forms the
1028
+ person is on. For the assisted (map-based) address flow the structured
948
1029
  fields are re-confirmed on the map; the manual address form prefills every
949
1030
  field. This mirrors the Web SDK runtime for UX parity.
950
1031
 
@@ -31,10 +31,14 @@ var _AddressInfoStep = require("../steps/AddressInfoStep");
31
31
  var _DocumentsOcrStep = require("../steps/DocumentsOcrStep");
32
32
  var _LivenessMatchStep = require("../steps/LivenessMatchStep");
33
33
  var _FaceMatchStep = require("../steps/FaceMatchStep");
34
+ var _CustomFormStep = require("../steps/CustomFormStep");
35
+ var _EntityTypeSelectionStep = require("../steps/EntityTypeSelectionStep");
36
+ var _unsupportedStep = require("../steps/unsupportedStep");
34
37
  var _types = require("../types");
35
38
  var _react = require("react");
36
39
  var _RetryDialog = require("../ui/overlays/RetryDialog");
37
40
  var _i18n = require("../i18n");
41
+ var _sdkVersion = require("../utils/sdkVersion");
38
42
  /**
39
43
  * @fileoverview VelionOnboarding — orchestrator for the React Native SDK.
40
44
  *
@@ -56,6 +60,14 @@ var _i18n = require("../i18n");
56
60
  * token with the cancellation, so the SDK closes SSE and stops calling out
57
61
  * - A request rejected with the 401 `VOB-40103` (token revoked by that same
58
62
  * cancellation, SSE event missed) ends the flow exactly like SESSION_CANCELLED
63
+ * - `cancelSession()` (the integrator cancels): once the backend confirms with
64
+ * 204 the flow ends exactly like SESSION_CANCELLED; the SSE event that
65
+ * follows is dropped, so the host hears about the cancellation once
66
+ * - The step code picks the screen; the step key (`step_key`, else the code)
67
+ * picks the instance: dedupe, config cache, reversibility and back
68
+ * navigation all go by key, so two CUSTOM_FORMs in a row are two steps
69
+ * - A step this SDK cannot render ends the flow with UNSUPPORTED_STEP; it is
70
+ * never skipped
59
71
  */
60
72
 
61
73
  // ─────────────────────────────────────────────────────────────────────────────
@@ -129,6 +141,13 @@ function cancelledEventFromDto() {
129
141
  * A request got the 401 `VOB-40103`: the same cancellation SSE would have
130
142
  * announced, rebuilt with the reason the 401 body carries.
131
143
  */
144
+ /** The integrator cancelled through `cancelSession()`; the 204 carries no reason. */
145
+ function cancelledEventFromIntegrator() {
146
+ return {
147
+ event_type: 'SESSION_CANCELLED',
148
+ session_status: 'CANCELLED'
149
+ };
150
+ }
132
151
  function cancelledEventFromRevokedToken(reason) {
133
152
  return {
134
153
  event_type: 'SESSION_CANCELLED',
@@ -138,6 +157,41 @@ function cancelledEventFromRevokedToken(reason) {
138
157
  })
139
158
  };
140
159
  }
160
+
161
+ /** Backend code of the 409 for a cancel on a session that is no longer open. */
162
+ const SESSION_NOT_OPEN_BACKEND_CODE = 'VOB-40913';
163
+
164
+ /** Maps a failed `POST /sessions/:id/cancel` to the error `cancelSession()` rejects with. */
165
+ function toCancelSessionError(err) {
166
+ const sdkErr = err ?? {};
167
+ const httpStatus = sdkErr.httpStatus;
168
+ const backendCode = sdkErr.cause?.code;
169
+ const withStatus = httpStatus !== undefined ? {
170
+ httpStatus
171
+ } : {};
172
+ if (httpStatus === 409 || backendCode === SESSION_NOT_OPEN_BACKEND_CODE) {
173
+ return {
174
+ code: _types.CancelSessionErrorCode.SESSION_NOT_OPEN,
175
+ message: 'The session is no longer open; there is nothing to cancel.',
176
+ ...withStatus,
177
+ cause: err
178
+ };
179
+ }
180
+ if (httpStatus === 401 || httpStatus === 403 || sdkErr.code === _types.SdkErrorCode.SESSION_EXPIRED || sdkErr.code === _types.SdkErrorCode.SESSION_INVALID) {
181
+ return {
182
+ code: _types.CancelSessionErrorCode.UNAUTHORIZED,
183
+ message: 'The session token was rejected. Rotate it with refreshSessionToken() and call cancelSession() again.',
184
+ ...withStatus,
185
+ cause: err
186
+ };
187
+ }
188
+ return {
189
+ code: _types.CancelSessionErrorCode.NETWORK,
190
+ message: sdkErr.message ?? 'The cancel request did not get through.',
191
+ ...withStatus,
192
+ cause: err
193
+ };
194
+ }
141
195
  function isSessionTokenAuthSdkError(err) {
142
196
  return err != null && typeof err === 'object' && err.code === _types.SdkErrorCode.SESSION_EXPIRED;
143
197
  }
@@ -191,6 +245,10 @@ class VelionOnboarding {
191
245
  pendingSessionDeclined = null;
192
246
  pendingTerminalEvent = null;
193
247
  sessionEnded = false;
248
+ /** Set once the session is known to be cancelled, however the SDK learned it. */
249
+ sessionCancelled = false;
250
+ /** In-flight `cancelSession()`, shared by concurrent calls. */
251
+ cancelRequest = null;
194
252
  constructor(config) {
195
253
  const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
196
254
  this.config = Object.freeze({
@@ -246,6 +304,31 @@ class VelionOnboarding {
246
304
  this.openSseStream(token);
247
305
  }
248
306
  }
307
+
308
+ /**
309
+ * Cancels the session on the integrator's behalf (`POST /sessions/:id/cancel`).
310
+ *
311
+ * Once the backend confirms, the flow ends exactly as when it cancels the
312
+ * session itself: `onSessionEvent` with `SESSION_CANCELLED`, then `onError`
313
+ * with `SdkErrorCode.SESSION_CANCELLED` and the cancelled screen. SSE is
314
+ * closed and the `SESSION_CANCELLED` event that follows is ignored, so the
315
+ * host is told once. Resolves after that; resolves at once when the session
316
+ * was already cancelled. Concurrent calls share one request.
317
+ *
318
+ * On failure the flow keeps running and the promise rejects with a
319
+ * {@link CancelSessionError}: `SESSION_NOT_OPEN` (409 `VOB-40913`),
320
+ * `UNAUTHORIZED` (401/403 — rotate the token with
321
+ * {@link refreshSessionToken} and call again) or `NETWORK`.
322
+ */
323
+ cancelSession() {
324
+ if (this.sessionCancelled) return Promise.resolve();
325
+ if (this.cancelRequest === null) {
326
+ this.cancelRequest = this.requestCancellation().finally(() => {
327
+ this.cancelRequest = null;
328
+ });
329
+ }
330
+ return this.cancelRequest;
331
+ }
249
332
  async start() {
250
333
  if (this.status === 'DESTROYED') {
251
334
  this.emitError({
@@ -293,6 +376,20 @@ class VelionOnboarding {
293
376
  this.queuedBackExitStep = null;
294
377
  this.retryDialogResolve = null;
295
378
  }
379
+ async requestCancellation() {
380
+ try {
381
+ await this.api.postEmpty(`/sessions/${this.config.sessionId}/cancel`);
382
+ } catch (err) {
383
+ // A 401 `VOB-40103` (or a caller already closed) means the session was
384
+ // cancelled meanwhile, and that path has already ended the flow.
385
+ if (this.sessionCancelled) return;
386
+ throw toCancelSessionError(err);
387
+ }
388
+ _log.log.info('[Flow] Session cancelled by the integrator', {
389
+ sessionId: this.config.sessionId
390
+ });
391
+ this.endFlowWithLocalCancellation(cancelledEventFromIntegrator());
392
+ }
296
393
 
297
394
  // ── Initialization ────────────────────────────────────────────────────────
298
395
 
@@ -360,9 +457,10 @@ class VelionOnboarding {
360
457
  }
361
458
  let index = 0;
362
459
  let currentStep = sessionState.currentStep;
460
+ let currentStepKey = sessionState.currentStepKey ?? currentStep ?? '';
363
461
  let currentStepConfig = sessionState.currentStepConfig;
364
462
  let currentStepResult = sessionState.currentStepResult;
365
- let currentCanGoBack = currentStep ? this.resolveCanGoBack(sessionState.canGoBack, currentStep) : false;
463
+ let currentCanGoBack = currentStep ? this.resolveCanGoBack(sessionState.canGoBack, currentStepKey) : false;
366
464
  const knownStepConfigs = {
367
465
  ...(sessionState.stepConfigs ?? {})
368
466
  };
@@ -383,9 +481,10 @@ class VelionOnboarding {
383
481
  };
384
482
  }
385
483
  currentStep = routed.step;
484
+ currentStepKey = routed.stepKey;
386
485
  currentStepConfig = routed.stepConfig;
387
486
  currentStepResult = undefined;
388
- currentCanGoBack = this.resolveCanGoBack(routed.canGoBack, routed.step);
487
+ currentCanGoBack = this.resolveCanGoBack(routed.canGoBack, routed.stepKey);
389
488
  } finally {
390
489
  this.showLoading(null);
391
490
  }
@@ -401,12 +500,13 @@ class VelionOnboarding {
401
500
  this.setStatus('STEP_PROCESSING');
402
501
  this.emitter.emit('step:change', {
403
502
  step: currentStep,
503
+ stepKey: currentStepKey,
404
504
  index
405
505
  });
406
506
  if (currentStepConfig) {
407
- knownStepConfigs[currentStep] = currentStepConfig;
507
+ knownStepConfigs[currentStepKey] = currentStepConfig;
408
508
  }
409
- const module = this.createModule(currentStep, currentStepConfig, currentStepResult, currentCanGoBack);
509
+ const module = this.createModule(currentStep, currentStepKey, currentStepConfig, currentStepResult, currentCanGoBack);
410
510
  this.activeModule = module;
411
511
  let outcome;
412
512
  try {
@@ -436,9 +536,10 @@ class VelionOnboarding {
436
536
  this.view.setStepNode?.(null);
437
537
  const command = outcome.command;
438
538
  currentStep = command.step;
439
- currentStepConfig = command.stepConfig ?? knownStepConfigs[command.step];
539
+ currentStepKey = command.stepKey;
540
+ currentStepConfig = command.stepConfig ?? knownStepConfigs[command.stepKey];
440
541
  currentStepResult = command.stepResult;
441
- currentCanGoBack = this.resolveCanGoBack(command.canGoBack, command.step);
542
+ currentCanGoBack = this.resolveCanGoBack(command.canGoBack, command.stepKey);
442
543
  this.showLoading(this.localizedLoadingMsg());
443
544
  continue;
444
545
  }
@@ -454,14 +555,15 @@ class VelionOnboarding {
454
555
  this.activeModule = null;
455
556
  this.view.setStepNode?.(null);
456
557
  this.emitter.emit('step:complete', {
457
- step: currentStep
558
+ step: currentStep,
559
+ stepKey: currentStepKey
458
560
  });
459
561
  this.setStatus('RUNNING');
460
562
  index += 1;
461
563
  this.showLoading('');
462
564
  let next;
463
565
  try {
464
- const routed = await this.awaitRoutingAfterStep(currentStep);
566
+ const routed = await this.awaitRoutingAfterStep(currentStep, currentStepKey);
465
567
  if (routed.kind === 'ended') return;
466
568
  if (routed.kind === 'verdict-pending') break;
467
569
  next = routed.command;
@@ -493,11 +595,12 @@ class VelionOnboarding {
493
595
  this.showLoading(this.localizedLoadingMsg());
494
596
  }
495
597
  currentStep = next.step;
496
- currentStepConfig = next.stepConfig ?? knownStepConfigs[next.step];
598
+ currentStepKey = next.stepKey;
599
+ currentStepConfig = next.stepConfig ?? knownStepConfigs[next.stepKey];
497
600
  // Forward navigation: no prefill. `can_go_back` comes from the command
498
601
  // when the backend sends it, else derived from the reversibility map.
499
602
  currentStepResult = undefined;
500
- currentCanGoBack = this.resolveCanGoBack(next.canGoBack, next.step);
603
+ currentCanGoBack = this.resolveCanGoBack(next.canGoBack, next.stepKey);
501
604
  }
502
605
  this.showLoading(this.localizedFinalizingMsg());
503
606
  try {
@@ -523,7 +626,7 @@ class VelionOnboarding {
523
626
  this.showLoading(null);
524
627
  }
525
628
  }
526
- createModule(step, stepConfig, stepResult, canGoBack) {
629
+ createModule(step, stepKey, stepConfig, stepResult, canGoBack) {
527
630
  const deps = {
528
631
  api: this.api,
529
632
  sessionId: this.config.sessionId,
@@ -531,6 +634,7 @@ class VelionOnboarding {
531
634
  colorMode: this.config.colorMode ?? 'light',
532
635
  ui: this.uiHandle,
533
636
  step,
637
+ stepKey,
534
638
  ...(stepConfig !== undefined && {
535
639
  stepConfig
536
640
  }),
@@ -541,7 +645,7 @@ class VelionOnboarding {
541
645
  // the user can go back from this step (`can_go_back`). The orchestrator
542
646
  // owns the POST + SSE handshake; the step only triggers it.
543
647
  ...(canGoBack === true && {
544
- onBack: () => this.requestBackNavigation(step)
648
+ onBack: () => this.requestBackNavigation(stepKey)
545
649
  }),
546
650
  // Map key fallback chain:
547
651
  // 1. `VelionConfig.googleMapsApiKey` (runtime override; takes precedence
@@ -610,11 +714,14 @@ class VelionOnboarding {
610
714
  return new _LivenessMatchStep.LivenessMatchStep(deps);
611
715
  case 'FACE_MATCH':
612
716
  return new _FaceMatchStep.FaceMatchStep(deps);
717
+ case 'CUSTOM_FORM':
718
+ return new _CustomFormStep.CustomFormStep(deps);
719
+ case 'ENTITY_TYPE_SELECTION':
720
+ return new _EntityTypeSelectionStep.EntityTypeSelectionStep(deps);
613
721
  default:
614
- throw {
615
- code: _types.SdkErrorCode.UNKNOWN,
616
- message: `Step "${String(step)}" is not implemented yet in the React Native SDK. ` + 'See the port roadmap in the repo README.'
617
- };
722
+ // Never skipped: a skipped step stays PENDING and the session would be
723
+ // declined at evaluation. The host has to ship a newer SDK.
724
+ throw (0, _unsupportedStep.unsupportedStepError)(this.config.locale, String(step), stepKey, `Step "${String(step)}" is not supported by this version of the React Native SDK (${_sdkVersion.SDK_VERSION}).`);
618
725
  }
619
726
  }
620
727
 
@@ -785,6 +892,7 @@ class VelionOnboarding {
785
892
  * SESSION_DECLINED — carrying the localized cancelled copy.
786
893
  */
787
894
  endFlowWithSessionCancelled(event) {
895
+ this.sessionCancelled = true;
788
896
  if (this.sessionEnded) return;
789
897
  this.sessionEnded = true;
790
898
  this.stopTalkingToBackend();
@@ -819,8 +927,21 @@ class VelionOnboarding {
819
927
  * refresh a token that belongs to a closed session.
820
928
  */
821
929
  endFlowWithRevokedToken(reason) {
822
- if (this.sessionEnded || this.status === 'DESTROYED') return;
823
- const event = cancelledEventFromRevokedToken(reason);
930
+ this.endFlowWithLocalCancellation(cancelledEventFromRevokedToken(reason));
931
+ }
932
+
933
+ /**
934
+ * The SDK learned of the cancellation from a request (a 401 `VOB-40103`, or
935
+ * the 204 of `cancelSession()`) rather than from SSE. Reports it as if SSE
936
+ * had delivered `event`. After the flow already ended (e.g. the user backed
937
+ * out) it only stops talking to the backend: the host was told how it ended.
938
+ */
939
+ endFlowWithLocalCancellation(event) {
940
+ if (this.sessionEnded || this.status === 'DESTROYED') {
941
+ this.sessionCancelled = true;
942
+ this.stopTalkingToBackend();
943
+ return;
944
+ }
824
945
  this.showLoading(null);
825
946
  this.config.onSessionEvent?.(event);
826
947
  this.endFlowWithSessionCancelled(event);
@@ -938,10 +1059,11 @@ class VelionOnboarding {
938
1059
  }
939
1060
  return;
940
1061
  }
941
- const maybeNext = this.extractNextStepCommand(event);
1062
+ const maybeNext = (0, _routingCommands.parseNextStepCommand)(event);
942
1063
  if (maybeNext) {
943
1064
  _log.log.info('[Flow] ROUTING_COMMAND received from SSE', {
944
1065
  step: maybeNext.step,
1066
+ stepKey: maybeNext.stepKey,
945
1067
  hasStepConfig: maybeNext.stepConfig !== undefined,
946
1068
  eventType: event.event_type,
947
1069
  action: event.action
@@ -963,29 +1085,14 @@ class VelionOnboarding {
963
1085
  resolve(event);
964
1086
  }
965
1087
  }
966
- extractNextStepCommand(event) {
967
- if (event.event_type !== 'ROUTING_COMMAND') return null;
968
- const action = event.action;
969
- if (action !== 'NEXT_STEP' && action !== 'RETRY_STEP') return null;
970
- const step = event.step_code;
971
- if (!step) return null;
972
- return {
973
- step,
974
- action,
975
- ...(event.step_config !== undefined && {
976
- stepConfig: event.step_config
977
- }),
978
- ...(typeof event.can_go_back === 'boolean' && {
979
- canGoBack: event.can_go_back
980
- })
981
- };
982
- }
983
1088
 
984
1089
  /**
985
- * Fire-and-forget reverse navigation. POSTs `/sessions/:id/back`; the actual
986
- * step transition arrives via SSE (`PREVIOUS_STEP`). A `400` (session not
987
- * IN_PROGRESS) or any other failure is swallowed — the user keeps editing the
988
- * current step. De-duplicated so rapid taps don't stack requests.
1090
+ * Fire-and-forget reverse navigation. POSTs `/sessions/:id/back` with the
1091
+ * step key as `from_step` (the backend accepts a key or a code; only the key
1092
+ * tells two CUSTOM_FORMs apart); the actual step transition arrives via SSE
1093
+ * (`PREVIOUS_STEP`). A `400` (session not IN_PROGRESS) or any other failure is
1094
+ * swallowed — the user keeps editing the current step. De-duplicated so rapid
1095
+ * taps don't stack requests.
989
1096
  */
990
1097
  requestBackNavigation(fromStep) {
991
1098
  if (this.status === 'DESTROYED' || this.sessionEnded) return;
@@ -1010,8 +1117,8 @@ class VelionOnboarding {
1010
1117
  * (back exits). Fallback only — an explicit `can_go_back` from the backend
1011
1118
  * (GET, or a ROUTING_COMMAND that carries it) always wins.
1012
1119
  */
1013
- resolveCanGoBack(explicit, step) {
1014
- return typeof explicit === 'boolean' ? explicit : (0, _sessionStateMapper.deriveCanGoBack)(step, this.stepReversibility);
1120
+ resolveCanGoBack(explicit, stepKey) {
1121
+ return typeof explicit === 'boolean' ? explicit : (0, _sessionStateMapper.deriveCanGoBack)(stepKey, this.stepReversibility);
1015
1122
  }
1016
1123
 
1017
1124
  // ── Wait helpers ──────────────────────────────────────────────────────────
@@ -1039,7 +1146,7 @@ class VelionOnboarding {
1039
1146
  * finalization wait. `ended` means the flow was closed here (declined,
1040
1147
  * terminal event or destroyed) and the caller must return.
1041
1148
  */
1042
- async awaitRoutingAfterStep(completedStep) {
1149
+ async awaitRoutingAfterStep(completedStep, completedStepKey) {
1043
1150
  const timeoutMs = this.routingTimeoutMs();
1044
1151
  const deadline = Date.now() + timeoutMs;
1045
1152
  let emptyCycles = 0;
@@ -1073,15 +1180,17 @@ class VelionOnboarding {
1073
1180
  // NextStepRequestedEvent (Kafka re-delivery, late ack, double command
1074
1181
  // dispatch); it is also what the fallback GET returns while the worker
1075
1182
  // has not advanced the session yet. RETRY_STEP for the same step is
1076
- // intentional and is allowed through.
1077
- if (command.action !== 'NEXT_STEP' || command.step !== completedStep) {
1183
+ // intentional and is allowed through. Compared by key: a NEXT_STEP from
1184
+ // one CUSTOM_FORM to the next shares the code and is a real move.
1185
+ if (command.action !== 'NEXT_STEP' || command.stepKey !== completedStepKey) {
1078
1186
  return {
1079
1187
  kind: 'routed',
1080
1188
  command
1081
1189
  };
1082
1190
  }
1083
1191
  _log.log.warn('[Flow] Dropping duplicate NEXT_STEP for just-completed step', {
1084
- step: completedStep
1192
+ step: completedStep,
1193
+ stepKey: completedStepKey
1085
1194
  });
1086
1195
  }
1087
1196
  emptyCycles += 1;
@@ -1207,6 +1316,7 @@ class VelionOnboarding {
1207
1316
  kind: 'routed',
1208
1317
  command: {
1209
1318
  step: state.currentStep,
1319
+ stepKey: state.currentStepKey ?? state.currentStep,
1210
1320
  // GET fallback represents "advance to current step" — equivalent to
1211
1321
  // a NEXT_STEP routing command. Retries always come over SSE.
1212
1322
  action: 'NEXT_STEP',