@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
@@ -19,6 +19,14 @@
19
19
  * token with the cancellation, so the SDK closes SSE and stops calling out
20
20
  * - A request rejected with the 401 `VOB-40103` (token revoked by that same
21
21
  * cancellation, SSE event missed) ends the flow exactly like SESSION_CANCELLED
22
+ * - `cancelSession()` (the integrator cancels): once the backend confirms with
23
+ * 204 the flow ends exactly like SESSION_CANCELLED; the SSE event that
24
+ * follows is dropped, so the host hears about the cancellation once
25
+ * - The step code picks the screen; the step key (`step_key`, else the code)
26
+ * picks the instance: dedupe, config cache, reversibility and back
27
+ * navigation all go by key, so two CUSTOM_FORMs in a row are two steps
28
+ * - A step this SDK cannot render ends the flow with UNSUPPORTED_STEP; it is
29
+ * never skipped
22
30
  */
23
31
 
24
32
  import { TypedEventEmitter } from '../utils/EventEmitter';
@@ -40,7 +48,9 @@ import { resolveSessionCancelledCopy } from './sessionCancelledCopy';
40
48
  import { resolveRetryStepCopy } from './retryStepCopy';
41
49
  import {
42
50
  parseBackExitCommand,
51
+ parseNextStepCommand,
43
52
  parsePreviousStepCommand,
53
+ type NextStepCommand,
44
54
  type PreviousStepCommand,
45
55
  } from './routingCommands';
46
56
  import { FingerprintStep } from '../steps/FingerprintStep';
@@ -60,8 +70,13 @@ import { AddressInfoStep } from '../steps/AddressInfoStep';
60
70
  import { DocumentsOcrStep } from '../steps/DocumentsOcrStep';
61
71
  import { LivenessMatchStep } from '../steps/LivenessMatchStep';
62
72
  import { FaceMatchStep } from '../steps/FaceMatchStep';
73
+ import { CustomFormStep } from '../steps/CustomFormStep';
74
+ import { EntityTypeSelectionStep } from '../steps/EntityTypeSelectionStep';
75
+ import { unsupportedStepError } from '../steps/unsupportedStep';
63
76
  import {
77
+ CancelSessionErrorCode,
64
78
  SdkErrorCode,
79
+ type CancelSessionError,
65
80
  type VelionConfig as WebVelionConfig,
66
81
  type SdkStatus,
67
82
  type SdkEventMap,
@@ -77,6 +92,7 @@ import type { StepModule, StepUiHandle } from '../steps/types';
77
92
  import { createElement, type ReactNode } from 'react';
78
93
  import { RetryDialog } from '../ui/overlays/RetryDialog';
79
94
  import { getStrings } from '../i18n';
95
+ import { SDK_VERSION } from '../utils/sdkVersion';
80
96
 
81
97
  // ─────────────────────────────────────────────────────────────────────────────
82
98
  // PUBLIC CONFIG (RN flavor)
@@ -97,15 +113,6 @@ export type VelionConfig = Omit<
97
113
  // INTERNAL CONTRACTS
98
114
  // ─────────────────────────────────────────────────────────────────────────────
99
115
 
100
- interface NextStepCommand {
101
- step: OnboardingStep;
102
- stepConfig?: Record<string, unknown>;
103
- /** `NEXT_STEP` advances; `RETRY_STEP` re-presents the same step (via a retry dialog). */
104
- action: 'NEXT_STEP' | 'RETRY_STEP';
105
- /** Whether the target step can go back (when the backend sends it on the command). */
106
- canGoBack?: boolean;
107
- }
108
-
109
116
  /** Result of one routing cycle (SSE wait + fallback GET) after a completed step. */
110
117
  type RoutingResolution =
111
118
  | { kind: 'routed'; command: NextStepCommand }
@@ -180,6 +187,11 @@ function cancelledEventFromDto(): OnboardingSessionEvent {
180
187
  * A request got the 401 `VOB-40103`: the same cancellation SSE would have
181
188
  * announced, rebuilt with the reason the 401 body carries.
182
189
  */
190
+ /** The integrator cancelled through `cancelSession()`; the 204 carries no reason. */
191
+ function cancelledEventFromIntegrator(): OnboardingSessionEvent {
192
+ return { event_type: 'SESSION_CANCELLED', session_status: 'CANCELLED' };
193
+ }
194
+
183
195
  function cancelledEventFromRevokedToken(reason: string | undefined): OnboardingSessionEvent {
184
196
  return {
185
197
  event_type: 'SESSION_CANCELLED',
@@ -188,6 +200,45 @@ function cancelledEventFromRevokedToken(reason: string | undefined): OnboardingS
188
200
  };
189
201
  }
190
202
 
203
+ /** Backend code of the 409 for a cancel on a session that is no longer open. */
204
+ const SESSION_NOT_OPEN_BACKEND_CODE = 'VOB-40913';
205
+
206
+ /** Maps a failed `POST /sessions/:id/cancel` to the error `cancelSession()` rejects with. */
207
+ function toCancelSessionError(err: unknown): CancelSessionError {
208
+ const sdkErr = (err ?? {}) as Partial<SdkError>;
209
+ const httpStatus = sdkErr.httpStatus;
210
+ const backendCode = (sdkErr.cause as { code?: unknown } | undefined)?.code;
211
+ const withStatus = httpStatus !== undefined ? { httpStatus } : {};
212
+ if (httpStatus === 409 || backendCode === SESSION_NOT_OPEN_BACKEND_CODE) {
213
+ return {
214
+ code: CancelSessionErrorCode.SESSION_NOT_OPEN,
215
+ message: 'The session is no longer open; there is nothing to cancel.',
216
+ ...withStatus,
217
+ cause: err,
218
+ };
219
+ }
220
+ if (
221
+ httpStatus === 401 ||
222
+ httpStatus === 403 ||
223
+ sdkErr.code === SdkErrorCode.SESSION_EXPIRED ||
224
+ sdkErr.code === SdkErrorCode.SESSION_INVALID
225
+ ) {
226
+ return {
227
+ code: CancelSessionErrorCode.UNAUTHORIZED,
228
+ message:
229
+ 'The session token was rejected. Rotate it with refreshSessionToken() and call cancelSession() again.',
230
+ ...withStatus,
231
+ cause: err,
232
+ };
233
+ }
234
+ return {
235
+ code: CancelSessionErrorCode.NETWORK,
236
+ message: sdkErr.message ?? 'The cancel request did not get through.',
237
+ ...withStatus,
238
+ cause: err,
239
+ };
240
+ }
241
+
191
242
  function isSessionTokenAuthSdkError(err: unknown): err is SdkError {
192
243
  return (
193
244
  err != null &&
@@ -255,12 +306,16 @@ export class VelionOnboarding {
255
306
 
256
307
  /** Per-step reversibility (workflow order) cached from the initial GET, used to
257
308
  * derive `can_go_back` for steps reached via SSE (which doesn't carry it). */
258
- private stepReversibility: ReadonlyArray<{ code: OnboardingStep; reversible: boolean }> = [];
309
+ private stepReversibility: ReadonlyArray<{ stepKey: string; reversible: boolean }> = [];
259
310
 
260
311
  private sessionDeclineHandler: ((event: OnboardingSessionEvent) => void) | null = null;
261
312
  private pendingSessionDeclined: OnboardingSessionEvent | null = null;
262
313
  private pendingTerminalEvent: OnboardingSessionEvent | null = null;
263
314
  private sessionEnded = false;
315
+ /** Set once the session is known to be cancelled, however the SDK learned it. */
316
+ private sessionCancelled = false;
317
+ /** In-flight `cancelSession()`, shared by concurrent calls. */
318
+ private cancelRequest: Promise<void> | null = null;
264
319
 
265
320
  constructor(config: VelionConfig) {
266
321
  const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
@@ -330,6 +385,31 @@ export class VelionOnboarding {
330
385
  }
331
386
  }
332
387
 
388
+ /**
389
+ * Cancels the session on the integrator's behalf (`POST /sessions/:id/cancel`).
390
+ *
391
+ * Once the backend confirms, the flow ends exactly as when it cancels the
392
+ * session itself: `onSessionEvent` with `SESSION_CANCELLED`, then `onError`
393
+ * with `SdkErrorCode.SESSION_CANCELLED` and the cancelled screen. SSE is
394
+ * closed and the `SESSION_CANCELLED` event that follows is ignored, so the
395
+ * host is told once. Resolves after that; resolves at once when the session
396
+ * was already cancelled. Concurrent calls share one request.
397
+ *
398
+ * On failure the flow keeps running and the promise rejects with a
399
+ * {@link CancelSessionError}: `SESSION_NOT_OPEN` (409 `VOB-40913`),
400
+ * `UNAUTHORIZED` (401/403 — rotate the token with
401
+ * {@link refreshSessionToken} and call again) or `NETWORK`.
402
+ */
403
+ cancelSession(): Promise<void> {
404
+ if (this.sessionCancelled) return Promise.resolve();
405
+ if (this.cancelRequest === null) {
406
+ this.cancelRequest = this.requestCancellation().finally(() => {
407
+ this.cancelRequest = null;
408
+ });
409
+ }
410
+ return this.cancelRequest;
411
+ }
412
+
333
413
  async start(): Promise<void> {
334
414
  if (this.status === 'DESTROYED') {
335
415
  this.emitError({
@@ -384,6 +464,21 @@ export class VelionOnboarding {
384
464
  this.retryDialogResolve = null;
385
465
  }
386
466
 
467
+ private async requestCancellation(): Promise<void> {
468
+ try {
469
+ await this.api.postEmpty<void>(`/sessions/${this.config.sessionId}/cancel`);
470
+ } catch (err) {
471
+ // A 401 `VOB-40103` (or a caller already closed) means the session was
472
+ // cancelled meanwhile, and that path has already ended the flow.
473
+ if (this.sessionCancelled) return;
474
+ throw toCancelSessionError(err);
475
+ }
476
+ log.info('[Flow] Session cancelled by the integrator', {
477
+ sessionId: this.config.sessionId,
478
+ });
479
+ this.endFlowWithLocalCancellation(cancelledEventFromIntegrator());
480
+ }
481
+
387
482
  // ── Initialization ────────────────────────────────────────────────────────
388
483
 
389
484
  private async initialize(): Promise<void> {
@@ -469,10 +564,11 @@ export class VelionOnboarding {
469
564
 
470
565
  let index = 0;
471
566
  let currentStep = sessionState.currentStep;
567
+ let currentStepKey: string = sessionState.currentStepKey ?? currentStep ?? '';
472
568
  let currentStepConfig = sessionState.currentStepConfig;
473
569
  let currentStepResult = sessionState.currentStepResult;
474
570
  let currentCanGoBack = currentStep
475
- ? this.resolveCanGoBack(sessionState.canGoBack, currentStep)
571
+ ? this.resolveCanGoBack(sessionState.canGoBack, currentStepKey)
476
572
  : false;
477
573
  const knownStepConfigs = { ...(sessionState.stepConfigs ?? {}) };
478
574
 
@@ -496,9 +592,10 @@ export class VelionOnboarding {
496
592
  } satisfies SdkError;
497
593
  }
498
594
  currentStep = routed.step;
595
+ currentStepKey = routed.stepKey;
499
596
  currentStepConfig = routed.stepConfig;
500
597
  currentStepResult = undefined;
501
- currentCanGoBack = this.resolveCanGoBack(routed.canGoBack, routed.step);
598
+ currentCanGoBack = this.resolveCanGoBack(routed.canGoBack, routed.stepKey);
502
599
  } finally {
503
600
  this.showLoading(null);
504
601
  }
@@ -513,14 +610,15 @@ export class VelionOnboarding {
513
610
  return;
514
611
  }
515
612
  this.setStatus('STEP_PROCESSING');
516
- this.emitter.emit('step:change', { step: currentStep, index });
613
+ this.emitter.emit('step:change', { step: currentStep, stepKey: currentStepKey, index });
517
614
 
518
615
  if (currentStepConfig) {
519
- knownStepConfigs[currentStep] = currentStepConfig;
616
+ knownStepConfigs[currentStepKey] = currentStepConfig;
520
617
  }
521
618
 
522
619
  const module = this.createModule(
523
620
  currentStep,
621
+ currentStepKey,
524
622
  currentStepConfig,
525
623
  currentStepResult,
526
624
  currentCanGoBack,
@@ -556,10 +654,11 @@ export class VelionOnboarding {
556
654
  this.view.setStepNode?.(null);
557
655
  const command = outcome.command;
558
656
  currentStep = command.step;
657
+ currentStepKey = command.stepKey;
559
658
  currentStepConfig =
560
- command.stepConfig ?? knownStepConfigs[command.step];
659
+ command.stepConfig ?? knownStepConfigs[command.stepKey];
561
660
  currentStepResult = command.stepResult;
562
- currentCanGoBack = this.resolveCanGoBack(command.canGoBack, command.step);
661
+ currentCanGoBack = this.resolveCanGoBack(command.canGoBack, command.stepKey);
563
662
  this.showLoading(this.localizedLoadingMsg());
564
663
  continue;
565
664
  }
@@ -575,14 +674,14 @@ export class VelionOnboarding {
575
674
  module.destroy();
576
675
  this.activeModule = null;
577
676
  this.view.setStepNode?.(null);
578
- this.emitter.emit('step:complete', { step: currentStep });
677
+ this.emitter.emit('step:complete', { step: currentStep, stepKey: currentStepKey });
579
678
  this.setStatus('RUNNING');
580
679
  index += 1;
581
680
 
582
681
  this.showLoading('');
583
682
  let next: NextStepCommand;
584
683
  try {
585
- const routed = await this.awaitRoutingAfterStep(currentStep);
684
+ const routed = await this.awaitRoutingAfterStep(currentStep, currentStepKey);
586
685
  if (routed.kind === 'ended') return;
587
686
  if (routed.kind === 'verdict-pending') break;
588
687
  next = routed.command;
@@ -615,11 +714,12 @@ export class VelionOnboarding {
615
714
  }
616
715
 
617
716
  currentStep = next.step;
618
- currentStepConfig = next.stepConfig ?? knownStepConfigs[next.step];
717
+ currentStepKey = next.stepKey;
718
+ currentStepConfig = next.stepConfig ?? knownStepConfigs[next.stepKey];
619
719
  // Forward navigation: no prefill. `can_go_back` comes from the command
620
720
  // when the backend sends it, else derived from the reversibility map.
621
721
  currentStepResult = undefined;
622
- currentCanGoBack = this.resolveCanGoBack(next.canGoBack, next.step);
722
+ currentCanGoBack = this.resolveCanGoBack(next.canGoBack, next.stepKey);
623
723
  }
624
724
 
625
725
  this.showLoading(this.localizedFinalizingMsg());
@@ -651,6 +751,7 @@ export class VelionOnboarding {
651
751
 
652
752
  private createModule(
653
753
  step: OnboardingStep,
754
+ stepKey: string,
654
755
  stepConfig: Record<string, unknown> | undefined,
655
756
  stepResult?: Record<string, unknown>,
656
757
  canGoBack?: boolean,
@@ -662,13 +763,14 @@ export class VelionOnboarding {
662
763
  colorMode: (this.config.colorMode ?? 'light') as 'light' | 'dark',
663
764
  ui: this.uiHandle,
664
765
  step,
766
+ stepKey,
665
767
  ...(stepConfig !== undefined && { stepConfig }),
666
768
  ...(stepResult !== undefined && { stepResult }),
667
769
  // Reverse navigation: wire the "back" control only when the backend says
668
770
  // the user can go back from this step (`can_go_back`). The orchestrator
669
771
  // owns the POST + SSE handshake; the step only triggers it.
670
772
  ...(canGoBack === true && {
671
- onBack: () => this.requestBackNavigation(step),
773
+ onBack: () => this.requestBackNavigation(stepKey),
672
774
  }),
673
775
  // Map key fallback chain:
674
776
  // 1. `VelionConfig.googleMapsApiKey` (runtime override; takes precedence
@@ -739,13 +841,19 @@ export class VelionOnboarding {
739
841
  return new LivenessMatchStep(deps);
740
842
  case 'FACE_MATCH':
741
843
  return new FaceMatchStep(deps);
844
+ case 'CUSTOM_FORM':
845
+ return new CustomFormStep(deps);
846
+ case 'ENTITY_TYPE_SELECTION':
847
+ return new EntityTypeSelectionStep(deps);
742
848
  default:
743
- throw {
744
- code: SdkErrorCode.UNKNOWN,
745
- message:
746
- `Step "${String(step)}" is not implemented yet in the React Native SDK. ` +
747
- 'See the port roadmap in the repo README.',
748
- } satisfies SdkError;
849
+ // Never skipped: a skipped step stays PENDING and the session would be
850
+ // declined at evaluation. The host has to ship a newer SDK.
851
+ throw unsupportedStepError(
852
+ this.config.locale,
853
+ String(step),
854
+ stepKey,
855
+ `Step "${String(step)}" is not supported by this version of the React Native SDK (${SDK_VERSION}).`,
856
+ );
749
857
  }
750
858
  }
751
859
 
@@ -938,6 +1046,7 @@ export class VelionOnboarding {
938
1046
  * SESSION_DECLINED — carrying the localized cancelled copy.
939
1047
  */
940
1048
  private endFlowWithSessionCancelled(event: OnboardingSessionEvent): void {
1049
+ this.sessionCancelled = true;
941
1050
  if (this.sessionEnded) return;
942
1051
  this.sessionEnded = true;
943
1052
  this.stopTalkingToBackend();
@@ -972,8 +1081,21 @@ export class VelionOnboarding {
972
1081
  * refresh a token that belongs to a closed session.
973
1082
  */
974
1083
  private endFlowWithRevokedToken(reason: string | undefined): void {
975
- if (this.sessionEnded || this.status === 'DESTROYED') return;
976
- const event = cancelledEventFromRevokedToken(reason);
1084
+ this.endFlowWithLocalCancellation(cancelledEventFromRevokedToken(reason));
1085
+ }
1086
+
1087
+ /**
1088
+ * The SDK learned of the cancellation from a request (a 401 `VOB-40103`, or
1089
+ * the 204 of `cancelSession()`) rather than from SSE. Reports it as if SSE
1090
+ * had delivered `event`. After the flow already ended (e.g. the user backed
1091
+ * out) it only stops talking to the backend: the host was told how it ended.
1092
+ */
1093
+ private endFlowWithLocalCancellation(event: OnboardingSessionEvent): void {
1094
+ if (this.sessionEnded || this.status === 'DESTROYED') {
1095
+ this.sessionCancelled = true;
1096
+ this.stopTalkingToBackend();
1097
+ return;
1098
+ }
977
1099
  this.showLoading(null);
978
1100
  this.config.onSessionEvent?.(event);
979
1101
  this.endFlowWithSessionCancelled(event);
@@ -1099,10 +1221,11 @@ export class VelionOnboarding {
1099
1221
  return;
1100
1222
  }
1101
1223
 
1102
- const maybeNext = this.extractNextStepCommand(event);
1224
+ const maybeNext = parseNextStepCommand(event);
1103
1225
  if (maybeNext) {
1104
1226
  log.info('[Flow] ROUTING_COMMAND received from SSE', {
1105
1227
  step: maybeNext.step,
1228
+ stepKey: maybeNext.stepKey,
1106
1229
  hasStepConfig: maybeNext.stepConfig !== undefined,
1107
1230
  eventType: event.event_type,
1108
1231
  action: event.action,
@@ -1126,29 +1249,15 @@ export class VelionOnboarding {
1126
1249
  }
1127
1250
  }
1128
1251
 
1129
- private extractNextStepCommand(
1130
- event: OnboardingSessionEvent,
1131
- ): NextStepCommand | null {
1132
- if (event.event_type !== 'ROUTING_COMMAND') return null;
1133
- const action = event.action;
1134
- if (action !== 'NEXT_STEP' && action !== 'RETRY_STEP') return null;
1135
- const step = event.step_code as OnboardingStep | undefined;
1136
- if (!step) return null;
1137
- return {
1138
- step,
1139
- action,
1140
- ...(event.step_config !== undefined && { stepConfig: event.step_config }),
1141
- ...(typeof event.can_go_back === 'boolean' && { canGoBack: event.can_go_back }),
1142
- };
1143
- }
1144
-
1145
1252
  /**
1146
- * Fire-and-forget reverse navigation. POSTs `/sessions/:id/back`; the actual
1147
- * step transition arrives via SSE (`PREVIOUS_STEP`). A `400` (session not
1148
- * IN_PROGRESS) or any other failure is swallowed — the user keeps editing the
1149
- * current step. De-duplicated so rapid taps don't stack requests.
1253
+ * Fire-and-forget reverse navigation. POSTs `/sessions/:id/back` with the
1254
+ * step key as `from_step` (the backend accepts a key or a code; only the key
1255
+ * tells two CUSTOM_FORMs apart); the actual step transition arrives via SSE
1256
+ * (`PREVIOUS_STEP`). A `400` (session not IN_PROGRESS) or any other failure is
1257
+ * swallowed — the user keeps editing the current step. De-duplicated so rapid
1258
+ * taps don't stack requests.
1150
1259
  */
1151
- private requestBackNavigation(fromStep: OnboardingStep): void {
1260
+ private requestBackNavigation(fromStep: string): void {
1152
1261
  if (this.status === 'DESTROYED' || this.sessionEnded) return;
1153
1262
  if (this.backRequestInFlight) return;
1154
1263
  this.backRequestInFlight = true;
@@ -1172,11 +1281,11 @@ export class VelionOnboarding {
1172
1281
  */
1173
1282
  private resolveCanGoBack(
1174
1283
  explicit: boolean | undefined,
1175
- step: OnboardingStep,
1284
+ stepKey: string,
1176
1285
  ): boolean {
1177
1286
  return typeof explicit === 'boolean'
1178
1287
  ? explicit
1179
- : deriveCanGoBack(step, this.stepReversibility);
1288
+ : deriveCanGoBack(stepKey, this.stepReversibility);
1180
1289
  }
1181
1290
 
1182
1291
  // ── Wait helpers ──────────────────────────────────────────────────────────
@@ -1208,6 +1317,7 @@ export class VelionOnboarding {
1208
1317
  */
1209
1318
  private async awaitRoutingAfterStep(
1210
1319
  completedStep: OnboardingStep,
1320
+ completedStepKey: string,
1211
1321
  ): Promise<
1212
1322
  | { kind: 'routed'; command: NextStepCommand }
1213
1323
  | { kind: 'verdict-pending' }
@@ -1239,12 +1349,14 @@ export class VelionOnboarding {
1239
1349
  // NextStepRequestedEvent (Kafka re-delivery, late ack, double command
1240
1350
  // dispatch); it is also what the fallback GET returns while the worker
1241
1351
  // has not advanced the session yet. RETRY_STEP for the same step is
1242
- // intentional and is allowed through.
1243
- if (command.action !== 'NEXT_STEP' || command.step !== completedStep) {
1352
+ // intentional and is allowed through. Compared by key: a NEXT_STEP from
1353
+ // one CUSTOM_FORM to the next shares the code and is a real move.
1354
+ if (command.action !== 'NEXT_STEP' || command.stepKey !== completedStepKey) {
1244
1355
  return { kind: 'routed', command };
1245
1356
  }
1246
1357
  log.warn('[Flow] Dropping duplicate NEXT_STEP for just-completed step', {
1247
1358
  step: completedStep,
1359
+ stepKey: completedStepKey,
1248
1360
  });
1249
1361
  }
1250
1362
 
@@ -1357,6 +1469,7 @@ export class VelionOnboarding {
1357
1469
  kind: 'routed',
1358
1470
  command: {
1359
1471
  step: state.currentStep,
1472
+ stepKey: state.currentStepKey ?? state.currentStep,
1360
1473
  // GET fallback represents "advance to current step" — equivalent to
1361
1474
  // a NEXT_STEP routing command. Retries always come over SSE.
1362
1475
  action: 'NEXT_STEP',
@@ -7,6 +7,45 @@
7
7
  */
8
8
 
9
9
  import type { OnboardingSessionEvent, OnboardingStep } from '../types';
10
+ import { resolveStepKey } from './sessionStateMapper';
11
+
12
+ /**
13
+ * Forward routing command (`ROUTING_COMMAND / NEXT_STEP` or `RETRY_STEP`). The
14
+ * code picks the screen; the key picks the step instance (two `CUSTOM_FORM`s
15
+ * share a code but not a key).
16
+ */
17
+ export interface NextStepCommand {
18
+ step: OnboardingStep;
19
+ /** `step_key` of the event, or `step_code` when the backend sends no key. */
20
+ stepKey: string;
21
+ stepConfig?: Record<string, unknown>;
22
+ /** `NEXT_STEP` advances; `RETRY_STEP` re-presents the same step (via a retry dialog). */
23
+ action: 'NEXT_STEP' | 'RETRY_STEP';
24
+ /** Whether the target step can go back (when the backend sends it on the command). */
25
+ canGoBack?: boolean;
26
+ }
27
+
28
+ /**
29
+ * Parses a forward routing command from an SSE event. Returns `null` for any
30
+ * event that is not a `ROUTING_COMMAND` `NEXT_STEP` / `RETRY_STEP` with a
31
+ * `step_code`.
32
+ */
33
+ export function parseNextStepCommand(
34
+ event: OnboardingSessionEvent,
35
+ ): NextStepCommand | null {
36
+ if (event.event_type !== 'ROUTING_COMMAND') return null;
37
+ const action = event.action;
38
+ if (action !== 'NEXT_STEP' && action !== 'RETRY_STEP') return null;
39
+ const step = event.step_code as OnboardingStep | undefined;
40
+ if (!step) return null;
41
+ return {
42
+ step,
43
+ stepKey: resolveStepKey(event.step_key, step),
44
+ action,
45
+ ...(event.step_config !== undefined && { stepConfig: event.step_config }),
46
+ ...(typeof event.can_go_back === 'boolean' && { canGoBack: event.can_go_back }),
47
+ };
48
+ }
10
49
 
11
50
  /**
12
51
  * Reverse-navigation command (`ROUTING_COMMAND / PREVIOUS_STEP`). Carries the
@@ -14,6 +53,8 @@ import type { OnboardingSessionEvent, OnboardingStep } from '../types';
14
53
  */
15
54
  export interface PreviousStepCommand {
16
55
  step: OnboardingStep;
56
+ /** `step_key` of the event, or `step_code` when the backend sends no key. */
57
+ stepKey: string;
17
58
  stepConfig?: Record<string, unknown>;
18
59
  stepResult?: Record<string, unknown>;
19
60
  /** Whether the re-opened step can itself go back further (when the backend sends it). */
@@ -35,6 +76,7 @@ export function parsePreviousStepCommand(
35
76
  if (!step) return null;
36
77
  return {
37
78
  step,
79
+ stepKey: resolveStepKey(event.step_key, step),
38
80
  ...(event.step_config !== undefined && { stepConfig: event.step_config }),
39
81
  ...(event.step_result !== undefined && { stepResult: event.step_result }),
40
82
  ...(typeof event.can_go_back === 'boolean' && { canGoBack: event.can_go_back }),