@velion-la/onboarding-sdk-react-native 1.4.0-beta.6 → 1.4.0-beta.8

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 (119) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +31 -1
  3. package/lib/commonjs/core/VelionOnboarding.js +52 -44
  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.map +1 -1
  14. package/lib/commonjs/steps/CustomFormStep.js +348 -0
  15. package/lib/commonjs/steps/CustomFormStep.js.map +1 -0
  16. package/lib/commonjs/steps/EntityTypeSelectionStep.js +194 -0
  17. package/lib/commonjs/steps/EntityTypeSelectionStep.js.map +1 -0
  18. package/lib/commonjs/steps/customForm.js +251 -0
  19. package/lib/commonjs/steps/customForm.js.map +1 -0
  20. package/lib/commonjs/steps/entityType.js +30 -0
  21. package/lib/commonjs/steps/entityType.js.map +1 -0
  22. package/lib/commonjs/steps/submissionOutcome.js +101 -0
  23. package/lib/commonjs/steps/submissionOutcome.js.map +1 -0
  24. package/lib/commonjs/steps/unsupportedStep.js +33 -0
  25. package/lib/commonjs/steps/unsupportedStep.js.map +1 -0
  26. package/lib/commonjs/types/index.js +35 -3
  27. package/lib/commonjs/types/index.js.map +1 -1
  28. package/lib/commonjs/ui/primitives/RadioCard.js +120 -0
  29. package/lib/commonjs/ui/primitives/RadioCard.js.map +1 -0
  30. package/lib/commonjs/ui/primitives/Select.js +60 -7
  31. package/lib/commonjs/ui/primitives/Select.js.map +1 -1
  32. package/lib/commonjs/ui/primitives/index.js +7 -0
  33. package/lib/commonjs/ui/primitives/index.js.map +1 -1
  34. package/lib/commonjs/utils/sdkVersion.js +1 -1
  35. package/lib/module/core/VelionOnboarding.js +53 -45
  36. package/lib/module/core/VelionOnboarding.js.map +1 -1
  37. package/lib/module/core/routingCommands.js +33 -0
  38. package/lib/module/core/routingCommands.js.map +1 -1
  39. package/lib/module/core/sessionStateMapper.js +47 -36
  40. package/lib/module/core/sessionStateMapper.js.map +1 -1
  41. package/lib/module/i18n/strings/en.js +27 -0
  42. package/lib/module/i18n/strings/en.js.map +1 -1
  43. package/lib/module/i18n/strings/es.js +27 -0
  44. package/lib/module/i18n/strings/es.js.map +1 -1
  45. package/lib/module/index.js.map +1 -1
  46. package/lib/module/steps/CustomFormStep.js +345 -0
  47. package/lib/module/steps/CustomFormStep.js.map +1 -0
  48. package/lib/module/steps/EntityTypeSelectionStep.js +189 -0
  49. package/lib/module/steps/EntityTypeSelectionStep.js.map +1 -0
  50. package/lib/module/steps/customForm.js +237 -0
  51. package/lib/module/steps/customForm.js.map +1 -0
  52. package/lib/module/steps/entityType.js +24 -0
  53. package/lib/module/steps/entityType.js.map +1 -0
  54. package/lib/module/steps/submissionOutcome.js +94 -0
  55. package/lib/module/steps/submissionOutcome.js.map +1 -0
  56. package/lib/module/steps/unsupportedStep.js +30 -0
  57. package/lib/module/steps/unsupportedStep.js.map +1 -0
  58. package/lib/module/types/index.js +42 -3
  59. package/lib/module/types/index.js.map +1 -1
  60. package/lib/module/ui/primitives/RadioCard.js +116 -0
  61. package/lib/module/ui/primitives/RadioCard.js.map +1 -0
  62. package/lib/module/ui/primitives/Select.js +62 -9
  63. package/lib/module/ui/primitives/Select.js.map +1 -1
  64. package/lib/module/ui/primitives/index.js +1 -0
  65. package/lib/module/ui/primitives/index.js.map +1 -1
  66. package/lib/module/utils/sdkVersion.js +1 -1
  67. package/lib/typescript/core/VelionOnboarding.d.ts +11 -5
  68. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  69. package/lib/typescript/core/routingCommands.d.ts +23 -0
  70. package/lib/typescript/core/routingCommands.d.ts.map +1 -1
  71. package/lib/typescript/core/sessionStateMapper.d.ts +13 -5
  72. package/lib/typescript/core/sessionStateMapper.d.ts.map +1 -1
  73. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  74. package/lib/typescript/i18n/strings/es.d.ts +27 -0
  75. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  76. package/lib/typescript/index.d.ts +1 -1
  77. package/lib/typescript/index.d.ts.map +1 -1
  78. package/lib/typescript/steps/CustomFormStep.d.ts +28 -0
  79. package/lib/typescript/steps/CustomFormStep.d.ts.map +1 -0
  80. package/lib/typescript/steps/EntityTypeSelectionStep.d.ts +24 -0
  81. package/lib/typescript/steps/EntityTypeSelectionStep.d.ts.map +1 -0
  82. package/lib/typescript/steps/customForm.d.ts +99 -0
  83. package/lib/typescript/steps/customForm.d.ts.map +1 -0
  84. package/lib/typescript/steps/entityType.d.ts +15 -0
  85. package/lib/typescript/steps/entityType.d.ts.map +1 -0
  86. package/lib/typescript/steps/submissionOutcome.d.ts +43 -0
  87. package/lib/typescript/steps/submissionOutcome.d.ts.map +1 -0
  88. package/lib/typescript/steps/types.d.ts +5 -0
  89. package/lib/typescript/steps/types.d.ts.map +1 -1
  90. package/lib/typescript/steps/unsupportedStep.d.ts +15 -0
  91. package/lib/typescript/steps/unsupportedStep.d.ts.map +1 -0
  92. package/lib/typescript/types/index.d.ts +107 -14
  93. package/lib/typescript/types/index.d.ts.map +1 -1
  94. package/lib/typescript/ui/primitives/RadioCard.d.ts +22 -0
  95. package/lib/typescript/ui/primitives/RadioCard.d.ts.map +1 -0
  96. package/lib/typescript/ui/primitives/Select.d.ts +9 -3
  97. package/lib/typescript/ui/primitives/Select.d.ts.map +1 -1
  98. package/lib/typescript/ui/primitives/index.d.ts +1 -0
  99. package/lib/typescript/ui/primitives/index.d.ts.map +1 -1
  100. package/lib/typescript/utils/sdkVersion.d.ts +1 -1
  101. package/package.json +3 -3
  102. package/src/core/VelionOnboarding.ts +59 -53
  103. package/src/core/routingCommands.ts +42 -0
  104. package/src/core/sessionStateMapper.ts +63 -52
  105. package/src/i18n/strings/en.ts +28 -0
  106. package/src/i18n/strings/es.ts +28 -0
  107. package/src/index.ts +7 -0
  108. package/src/steps/CustomFormStep.tsx +400 -0
  109. package/src/steps/EntityTypeSelectionStep.tsx +207 -0
  110. package/src/steps/customForm.ts +302 -0
  111. package/src/steps/entityType.ts +25 -0
  112. package/src/steps/submissionOutcome.ts +93 -0
  113. package/src/steps/types.ts +5 -0
  114. package/src/steps/unsupportedStep.ts +32 -0
  115. package/src/types/index.ts +117 -17
  116. package/src/ui/primitives/RadioCard.tsx +127 -0
  117. package/src/ui/primitives/Select.tsx +73 -7
  118. package/src/ui/primitives/index.ts +1 -0
  119. package/src/utils/sdkVersion.ts +1 -1
@@ -19,6 +19,11 @@
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
+ * - The step code picks the screen; the step key (`step_key`, else the code)
23
+ * picks the instance: dedupe, config cache, reversibility and back
24
+ * navigation all go by key, so two CUSTOM_FORMs in a row are two steps
25
+ * - A step this SDK cannot render ends the flow with UNSUPPORTED_STEP; it is
26
+ * never skipped
22
27
  */
23
28
 
24
29
  import { TypedEventEmitter } from '../utils/EventEmitter';
@@ -40,7 +45,9 @@ import { resolveSessionCancelledCopy } from './sessionCancelledCopy';
40
45
  import { resolveRetryStepCopy } from './retryStepCopy';
41
46
  import {
42
47
  parseBackExitCommand,
48
+ parseNextStepCommand,
43
49
  parsePreviousStepCommand,
50
+ type NextStepCommand,
44
51
  type PreviousStepCommand,
45
52
  } from './routingCommands';
46
53
  import { FingerprintStep } from '../steps/FingerprintStep';
@@ -60,6 +67,9 @@ import { AddressInfoStep } from '../steps/AddressInfoStep';
60
67
  import { DocumentsOcrStep } from '../steps/DocumentsOcrStep';
61
68
  import { LivenessMatchStep } from '../steps/LivenessMatchStep';
62
69
  import { FaceMatchStep } from '../steps/FaceMatchStep';
70
+ import { CustomFormStep } from '../steps/CustomFormStep';
71
+ import { EntityTypeSelectionStep } from '../steps/EntityTypeSelectionStep';
72
+ import { unsupportedStepError } from '../steps/unsupportedStep';
63
73
  import {
64
74
  SdkErrorCode,
65
75
  type VelionConfig as WebVelionConfig,
@@ -77,6 +87,7 @@ import type { StepModule, StepUiHandle } from '../steps/types';
77
87
  import { createElement, type ReactNode } from 'react';
78
88
  import { RetryDialog } from '../ui/overlays/RetryDialog';
79
89
  import { getStrings } from '../i18n';
90
+ import { SDK_VERSION } from '../utils/sdkVersion';
80
91
 
81
92
  // ─────────────────────────────────────────────────────────────────────────────
82
93
  // PUBLIC CONFIG (RN flavor)
@@ -97,15 +108,6 @@ export type VelionConfig = Omit<
97
108
  // INTERNAL CONTRACTS
98
109
  // ─────────────────────────────────────────────────────────────────────────────
99
110
 
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
111
  /** Result of one routing cycle (SSE wait + fallback GET) after a completed step. */
110
112
  type RoutingResolution =
111
113
  | { kind: 'routed'; command: NextStepCommand }
@@ -255,7 +257,7 @@ export class VelionOnboarding {
255
257
 
256
258
  /** Per-step reversibility (workflow order) cached from the initial GET, used to
257
259
  * derive `can_go_back` for steps reached via SSE (which doesn't carry it). */
258
- private stepReversibility: ReadonlyArray<{ code: OnboardingStep; reversible: boolean }> = [];
260
+ private stepReversibility: ReadonlyArray<{ stepKey: string; reversible: boolean }> = [];
259
261
 
260
262
  private sessionDeclineHandler: ((event: OnboardingSessionEvent) => void) | null = null;
261
263
  private pendingSessionDeclined: OnboardingSessionEvent | null = null;
@@ -469,10 +471,11 @@ export class VelionOnboarding {
469
471
 
470
472
  let index = 0;
471
473
  let currentStep = sessionState.currentStep;
474
+ let currentStepKey: string = sessionState.currentStepKey ?? currentStep ?? '';
472
475
  let currentStepConfig = sessionState.currentStepConfig;
473
476
  let currentStepResult = sessionState.currentStepResult;
474
477
  let currentCanGoBack = currentStep
475
- ? this.resolveCanGoBack(sessionState.canGoBack, currentStep)
478
+ ? this.resolveCanGoBack(sessionState.canGoBack, currentStepKey)
476
479
  : false;
477
480
  const knownStepConfigs = { ...(sessionState.stepConfigs ?? {}) };
478
481
 
@@ -496,9 +499,10 @@ export class VelionOnboarding {
496
499
  } satisfies SdkError;
497
500
  }
498
501
  currentStep = routed.step;
502
+ currentStepKey = routed.stepKey;
499
503
  currentStepConfig = routed.stepConfig;
500
504
  currentStepResult = undefined;
501
- currentCanGoBack = this.resolveCanGoBack(routed.canGoBack, routed.step);
505
+ currentCanGoBack = this.resolveCanGoBack(routed.canGoBack, routed.stepKey);
502
506
  } finally {
503
507
  this.showLoading(null);
504
508
  }
@@ -513,14 +517,15 @@ export class VelionOnboarding {
513
517
  return;
514
518
  }
515
519
  this.setStatus('STEP_PROCESSING');
516
- this.emitter.emit('step:change', { step: currentStep, index });
520
+ this.emitter.emit('step:change', { step: currentStep, stepKey: currentStepKey, index });
517
521
 
518
522
  if (currentStepConfig) {
519
- knownStepConfigs[currentStep] = currentStepConfig;
523
+ knownStepConfigs[currentStepKey] = currentStepConfig;
520
524
  }
521
525
 
522
526
  const module = this.createModule(
523
527
  currentStep,
528
+ currentStepKey,
524
529
  currentStepConfig,
525
530
  currentStepResult,
526
531
  currentCanGoBack,
@@ -556,10 +561,11 @@ export class VelionOnboarding {
556
561
  this.view.setStepNode?.(null);
557
562
  const command = outcome.command;
558
563
  currentStep = command.step;
564
+ currentStepKey = command.stepKey;
559
565
  currentStepConfig =
560
- command.stepConfig ?? knownStepConfigs[command.step];
566
+ command.stepConfig ?? knownStepConfigs[command.stepKey];
561
567
  currentStepResult = command.stepResult;
562
- currentCanGoBack = this.resolveCanGoBack(command.canGoBack, command.step);
568
+ currentCanGoBack = this.resolveCanGoBack(command.canGoBack, command.stepKey);
563
569
  this.showLoading(this.localizedLoadingMsg());
564
570
  continue;
565
571
  }
@@ -575,14 +581,14 @@ export class VelionOnboarding {
575
581
  module.destroy();
576
582
  this.activeModule = null;
577
583
  this.view.setStepNode?.(null);
578
- this.emitter.emit('step:complete', { step: currentStep });
584
+ this.emitter.emit('step:complete', { step: currentStep, stepKey: currentStepKey });
579
585
  this.setStatus('RUNNING');
580
586
  index += 1;
581
587
 
582
588
  this.showLoading('');
583
589
  let next: NextStepCommand;
584
590
  try {
585
- const routed = await this.awaitRoutingAfterStep(currentStep);
591
+ const routed = await this.awaitRoutingAfterStep(currentStep, currentStepKey);
586
592
  if (routed.kind === 'ended') return;
587
593
  if (routed.kind === 'verdict-pending') break;
588
594
  next = routed.command;
@@ -615,11 +621,12 @@ export class VelionOnboarding {
615
621
  }
616
622
 
617
623
  currentStep = next.step;
618
- currentStepConfig = next.stepConfig ?? knownStepConfigs[next.step];
624
+ currentStepKey = next.stepKey;
625
+ currentStepConfig = next.stepConfig ?? knownStepConfigs[next.stepKey];
619
626
  // Forward navigation: no prefill. `can_go_back` comes from the command
620
627
  // when the backend sends it, else derived from the reversibility map.
621
628
  currentStepResult = undefined;
622
- currentCanGoBack = this.resolveCanGoBack(next.canGoBack, next.step);
629
+ currentCanGoBack = this.resolveCanGoBack(next.canGoBack, next.stepKey);
623
630
  }
624
631
 
625
632
  this.showLoading(this.localizedFinalizingMsg());
@@ -651,6 +658,7 @@ export class VelionOnboarding {
651
658
 
652
659
  private createModule(
653
660
  step: OnboardingStep,
661
+ stepKey: string,
654
662
  stepConfig: Record<string, unknown> | undefined,
655
663
  stepResult?: Record<string, unknown>,
656
664
  canGoBack?: boolean,
@@ -662,13 +670,14 @@ export class VelionOnboarding {
662
670
  colorMode: (this.config.colorMode ?? 'light') as 'light' | 'dark',
663
671
  ui: this.uiHandle,
664
672
  step,
673
+ stepKey,
665
674
  ...(stepConfig !== undefined && { stepConfig }),
666
675
  ...(stepResult !== undefined && { stepResult }),
667
676
  // Reverse navigation: wire the "back" control only when the backend says
668
677
  // the user can go back from this step (`can_go_back`). The orchestrator
669
678
  // owns the POST + SSE handshake; the step only triggers it.
670
679
  ...(canGoBack === true && {
671
- onBack: () => this.requestBackNavigation(step),
680
+ onBack: () => this.requestBackNavigation(stepKey),
672
681
  }),
673
682
  // Map key fallback chain:
674
683
  // 1. `VelionConfig.googleMapsApiKey` (runtime override; takes precedence
@@ -739,13 +748,19 @@ export class VelionOnboarding {
739
748
  return new LivenessMatchStep(deps);
740
749
  case 'FACE_MATCH':
741
750
  return new FaceMatchStep(deps);
751
+ case 'CUSTOM_FORM':
752
+ return new CustomFormStep(deps);
753
+ case 'ENTITY_TYPE_SELECTION':
754
+ return new EntityTypeSelectionStep(deps);
742
755
  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;
756
+ // Never skipped: a skipped step stays PENDING and the session would be
757
+ // declined at evaluation. The host has to ship a newer SDK.
758
+ throw unsupportedStepError(
759
+ this.config.locale,
760
+ String(step),
761
+ stepKey,
762
+ `Step "${String(step)}" is not supported by this version of the React Native SDK (${SDK_VERSION}).`,
763
+ );
749
764
  }
750
765
  }
751
766
 
@@ -1099,10 +1114,11 @@ export class VelionOnboarding {
1099
1114
  return;
1100
1115
  }
1101
1116
 
1102
- const maybeNext = this.extractNextStepCommand(event);
1117
+ const maybeNext = parseNextStepCommand(event);
1103
1118
  if (maybeNext) {
1104
1119
  log.info('[Flow] ROUTING_COMMAND received from SSE', {
1105
1120
  step: maybeNext.step,
1121
+ stepKey: maybeNext.stepKey,
1106
1122
  hasStepConfig: maybeNext.stepConfig !== undefined,
1107
1123
  eventType: event.event_type,
1108
1124
  action: event.action,
@@ -1126,29 +1142,15 @@ export class VelionOnboarding {
1126
1142
  }
1127
1143
  }
1128
1144
 
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
1145
  /**
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.
1146
+ * Fire-and-forget reverse navigation. POSTs `/sessions/:id/back` with the
1147
+ * step key as `from_step` (the backend accepts a key or a code; only the key
1148
+ * tells two CUSTOM_FORMs apart); the actual step transition arrives via SSE
1149
+ * (`PREVIOUS_STEP`). A `400` (session not IN_PROGRESS) or any other failure is
1150
+ * swallowed — the user keeps editing the current step. De-duplicated so rapid
1151
+ * taps don't stack requests.
1150
1152
  */
1151
- private requestBackNavigation(fromStep: OnboardingStep): void {
1153
+ private requestBackNavigation(fromStep: string): void {
1152
1154
  if (this.status === 'DESTROYED' || this.sessionEnded) return;
1153
1155
  if (this.backRequestInFlight) return;
1154
1156
  this.backRequestInFlight = true;
@@ -1172,11 +1174,11 @@ export class VelionOnboarding {
1172
1174
  */
1173
1175
  private resolveCanGoBack(
1174
1176
  explicit: boolean | undefined,
1175
- step: OnboardingStep,
1177
+ stepKey: string,
1176
1178
  ): boolean {
1177
1179
  return typeof explicit === 'boolean'
1178
1180
  ? explicit
1179
- : deriveCanGoBack(step, this.stepReversibility);
1181
+ : deriveCanGoBack(stepKey, this.stepReversibility);
1180
1182
  }
1181
1183
 
1182
1184
  // ── Wait helpers ──────────────────────────────────────────────────────────
@@ -1208,6 +1210,7 @@ export class VelionOnboarding {
1208
1210
  */
1209
1211
  private async awaitRoutingAfterStep(
1210
1212
  completedStep: OnboardingStep,
1213
+ completedStepKey: string,
1211
1214
  ): Promise<
1212
1215
  | { kind: 'routed'; command: NextStepCommand }
1213
1216
  | { kind: 'verdict-pending' }
@@ -1239,12 +1242,14 @@ export class VelionOnboarding {
1239
1242
  // NextStepRequestedEvent (Kafka re-delivery, late ack, double command
1240
1243
  // dispatch); it is also what the fallback GET returns while the worker
1241
1244
  // 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) {
1245
+ // intentional and is allowed through. Compared by key: a NEXT_STEP from
1246
+ // one CUSTOM_FORM to the next shares the code and is a real move.
1247
+ if (command.action !== 'NEXT_STEP' || command.stepKey !== completedStepKey) {
1244
1248
  return { kind: 'routed', command };
1245
1249
  }
1246
1250
  log.warn('[Flow] Dropping duplicate NEXT_STEP for just-completed step', {
1247
1251
  step: completedStep,
1252
+ stepKey: completedStepKey,
1248
1253
  });
1249
1254
  }
1250
1255
 
@@ -1357,6 +1362,7 @@ export class VelionOnboarding {
1357
1362
  kind: 'routed',
1358
1363
  command: {
1359
1364
  step: state.currentStep,
1365
+ stepKey: state.currentStepKey ?? state.currentStep,
1360
1366
  // GET fallback represents "advance to current step" — equivalent to
1361
1367
  // a NEXT_STEP routing command. Retries always come over SSE.
1362
1368
  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 }),
@@ -6,56 +6,76 @@ import type {
6
6
  OnboardingDtoResponse,
7
7
  OnboardingResult,
8
8
  OnboardingStep,
9
+ OnboardingStepDto,
9
10
  SessionState,
10
- OnboardingType,
11
11
  StepConfigMap,
12
12
  } from '../types';
13
13
 
14
14
  const TERMINAL_STEP_STATUSES = new Set(['COMPLETED', 'SKIPPED']);
15
15
 
16
+ /**
17
+ * Instance key of a step: its `step_key`, or its code when the backend sends no
18
+ * key (older backends, and every step but `CUSTOM_FORM`, where both match).
19
+ */
20
+ export function resolveStepKey(
21
+ stepKey: string | undefined | null,
22
+ code: string,
23
+ ): string {
24
+ return typeof stepKey === 'string' && stepKey.trim() !== '' ? stepKey : code;
25
+ }
26
+
27
+ function asRecord(value: unknown): Record<string, unknown> | undefined {
28
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
29
+ ? (value as Record<string, unknown>)
30
+ : undefined;
31
+ }
32
+
16
33
  /**
17
34
  * Maps the onboarding DTO returned by GET /sessions/:sessionId to the
18
35
  * SessionState shape used by the step machine.
36
+ *
37
+ * The code of a step decides which screen renders; its `step_key` decides which
38
+ * instance the SDK answers to, so configs and reversibility are keyed by it.
19
39
  */
20
40
  export function mapOnboardingDtoToSessionState(
21
41
  dto: OnboardingDtoResponse,
22
42
  ): SessionState {
23
43
  const steps = dto.steps ?? [];
24
- const sorted = [...steps].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
25
-
26
- const onboardingType = dto.onboarding_type as OnboardingType | undefined;
27
- const validType: OnboardingType | undefined =
28
- onboardingType === 'HUMAN' || onboardingType === 'LEGAL'
29
- ? onboardingType
30
- : undefined;
44
+ const sorted = [...steps]
45
+ .filter((s): s is OnboardingStepDto => typeof s?.code === 'string' && s.code !== '')
46
+ .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
31
47
 
32
48
  const stepConfigs: StepConfigMap = {};
33
49
 
34
50
  for (const s of sorted) {
35
- const code = s.code as OnboardingStep | undefined;
36
- if (!code || typeof code !== 'string') continue;
37
- if (s.result && typeof s.result === 'object') {
38
- stepConfigs[code] = s.result;
51
+ const key = resolveStepKey(s.step_key, s.code);
52
+ const result = asRecord(s.result);
53
+ if (result) {
54
+ stepConfigs[key] = result;
39
55
  }
40
- const maybeConfig = (s as unknown as { config?: Record<string, unknown> }).config;
41
- if (maybeConfig && typeof maybeConfig === 'object') {
42
- stepConfigs[code] = maybeConfig;
56
+ const config = asRecord(s.config);
57
+ if (config) {
58
+ stepConfigs[key] = config;
43
59
  }
44
60
  }
45
61
 
46
- const currentStepCode = dto.current_step?.code;
47
- const currentStep =
48
- typeof currentStepCode === 'string'
49
- ? (currentStepCode as OnboardingStep)
50
- : resolveCurrentStepFromLegacySteps(sorted);
62
+ // `current_step` may be omitted: fall back to the first unfinished step.
63
+ const reported = dto.current_step;
64
+ const reportedCode = typeof reported?.code === 'string' && reported.code !== ''
65
+ ? reported.code
66
+ : undefined;
67
+ const legacy = reportedCode === undefined ? resolveCurrentStepFromLegacySteps(sorted) : undefined;
68
+ const currentStep = (reportedCode ?? legacy?.code) as OnboardingStep | undefined;
69
+ const currentStepKey = reportedCode !== undefined
70
+ ? resolveStepKey(reported?.step_key, reportedCode)
71
+ : legacy !== undefined
72
+ ? resolveStepKey(legacy.step_key, legacy.code)
73
+ : undefined;
51
74
  const currentStepConfig =
52
- dto.current_step?.config && typeof dto.current_step.config === 'object'
53
- ? dto.current_step.config
54
- : currentStep
55
- ? stepConfigs[currentStep]
56
- : undefined;
57
- if (currentStep && currentStepConfig) {
58
- stepConfigs[currentStep] = currentStepConfig;
75
+ asRecord(reported?.config) ??
76
+ (currentStepKey !== undefined ? stepConfigs[currentStepKey] : undefined);
77
+ if (currentStepKey && currentStepConfig) {
78
+ stepConfigs[currentStepKey] = currentStepConfig;
59
79
  }
60
80
 
61
81
  // Whether the SDK shows the "back" control on the current step. The backend
@@ -66,23 +86,15 @@ export function mapOnboardingDtoToSessionState(
66
86
 
67
87
  // Per-step reversibility in workflow order, so the orchestrator can derive
68
88
  // `can_go_back` for steps reached via SSE (which does not carry the flag).
69
- const stepReversibility = sorted
70
- .map((s) => {
71
- const code = s.code as OnboardingStep | undefined;
72
- if (!code || typeof code !== 'string') return null;
73
- const maybeConfig = (s as unknown as { config?: Record<string, unknown> })
74
- .config;
75
- const reversible = resolveReversibleFlag(s.reversible, maybeConfig) === true;
76
- return { code, reversible };
77
- })
78
- .filter((s): s is { code: OnboardingStep; reversible: boolean } => s !== null);
89
+ const stepReversibility = sorted.map((s) => ({
90
+ code: s.code as OnboardingStep,
91
+ stepKey: resolveStepKey(s.step_key, s.code),
92
+ reversible: resolveReversibleFlag(s.reversible, asRecord(s.config)) === true,
93
+ }));
79
94
 
80
95
  // Prefill: data previously captured for `currentStep`, present when a reverse
81
96
  // navigation re-opened a completed step (GET reflects it on `current_step.result`).
82
- const currentStepResult =
83
- dto.current_step?.result && typeof dto.current_step.result === 'object'
84
- ? dto.current_step.result
85
- : undefined;
97
+ const currentStepResult = asRecord(reported?.result) ?? asRecord(legacy?.result);
86
98
 
87
99
  const allowedParentOrigins = Array.isArray(dto.allowed_parent_origins)
88
100
  ? dto.allowed_parent_origins.filter(
@@ -92,12 +104,12 @@ export function mapOnboardingDtoToSessionState(
92
104
 
93
105
  const state: SessionState = {
94
106
  ...(currentStep !== undefined && { currentStep }),
107
+ ...(currentStepKey !== undefined && { currentStepKey }),
95
108
  ...(currentStepConfig !== undefined && { currentStepConfig }),
96
109
  ...(canGoBack !== undefined && { canGoBack }),
97
110
  ...(stepReversibility.length > 0 && { stepReversibility }),
98
111
  ...(currentStepResult !== undefined && { currentStepResult }),
99
112
  ...(Object.keys(stepConfigs).length > 0 && { stepConfigs }),
100
- ...(validType !== undefined && { onboardingType: validType }),
101
113
  ...(dto.metadata !== undefined && { metadata: dto.metadata }),
102
114
  ...(allowedParentOrigins !== undefined && { allowedParentOrigins }),
103
115
  };
@@ -126,14 +138,14 @@ export function resolveReversibleFlag(
126
138
  * fallback when the backend doesn't send `can_go_back` explicitly — e.g. on a
127
139
  * step reached via SSE). Matches the backend's barrier model: a step can go back
128
140
  * when any earlier step is reversible (navigate to it) or the step itself is the
129
- * first reversible step (back exits the flow). Returns `false` when the step is
130
- * not in the cached order.
141
+ * first reversible step (back exits the flow). The step is looked up by its
142
+ * instance key. Returns `false` when the step is not in the cached order.
131
143
  */
132
144
  export function deriveCanGoBack(
133
- step: OnboardingStep,
134
- order: ReadonlyArray<{ code: OnboardingStep; reversible: boolean }>,
145
+ stepKey: string,
146
+ order: ReadonlyArray<{ stepKey: string; reversible: boolean }>,
135
147
  ): boolean {
136
- const index = order.findIndex((s) => s.code === step);
148
+ const index = order.findIndex((s) => s.stepKey === stepKey);
137
149
  if (index < 0) return false;
138
150
  const previousReversible = order.slice(0, index).some((s) => s.reversible);
139
151
  const currentReversible = order[index]?.reversible === true;
@@ -141,16 +153,15 @@ export function deriveCanGoBack(
141
153
  }
142
154
 
143
155
  function resolveCurrentStepFromLegacySteps(
144
- sorted: Array<{ code: string; status?: string }>,
145
- ): OnboardingStep | undefined {
156
+ sorted: ReadonlyArray<OnboardingStepDto>,
157
+ ): OnboardingStepDto | undefined {
146
158
  for (const s of sorted) {
147
159
  const status = s.status;
148
160
  if (!status || !TERMINAL_STEP_STATUSES.has(status)) {
149
- return s.code as OnboardingStep;
161
+ return s;
150
162
  }
151
163
  }
152
- const last = sorted.at(-1);
153
- return last?.code as OnboardingStep | undefined;
164
+ return sorted.at(-1);
154
165
  }
155
166
 
156
167
  /**
@@ -112,6 +112,34 @@ export const EN: StringsTable = {
112
112
  empty: 'No activities match your search.',
113
113
  required: 'Select an activity to continue.',
114
114
  },
115
+ custom_form: {
116
+ defaultTitle: 'Complete the form',
117
+ selectPlaceholder: 'Select an option',
118
+ searchPlaceholder: 'Search',
119
+ empty: 'No options match your search.',
120
+ yes: 'Yes',
121
+ no: 'No',
122
+ required: 'This field is required.',
123
+ textTooLong: 'Enter up to 255 characters.',
124
+ invalidNumber: 'Enter a valid number.',
125
+ invalidBoolean: 'Choose Yes or No.',
126
+ invalidDate: 'Enter a valid date.',
127
+ invalidOption: 'Choose one of the options.',
128
+ },
129
+ entity_type: {
130
+ title: 'How are you signing up?',
131
+ subtitle: 'Choose whether you sign up as an individual or on behalf of a legal entity.',
132
+ human: 'Individual',
133
+ humanDescription: 'I am signing up on my own behalf.',
134
+ legal: 'Legal entity',
135
+ legalDescription: 'I am signing up a company, partnership or other organization.',
136
+ required: 'Choose an option to continue.',
137
+ },
138
+ unsupported_step: {
139
+ title: 'This step is not available',
140
+ message:
141
+ 'This version cannot show the next step of your onboarding. Please try again later; your progress was saved.',
142
+ },
115
143
  terms_and_conditions: {
116
144
  title: 'Terms and conditions',
117
145
  subtitle: 'Review each item and confirm your acceptance to continue.',
@@ -115,6 +115,34 @@ export const ES = {
115
115
  empty: 'No encontramos actividades para tu búsqueda.',
116
116
  required: 'Seleccioná una actividad para continuar.',
117
117
  },
118
+ custom_form: {
119
+ defaultTitle: 'Completá el formulario',
120
+ selectPlaceholder: 'Seleccioná una opción',
121
+ searchPlaceholder: 'Buscar',
122
+ empty: 'No encontramos opciones para tu búsqueda.',
123
+ yes: 'Sí',
124
+ no: 'No',
125
+ required: 'Este campo es obligatorio.',
126
+ textTooLong: 'Ingresá hasta 255 caracteres.',
127
+ invalidNumber: 'Ingresá un número válido.',
128
+ invalidBoolean: 'Elegí Sí o No.',
129
+ invalidDate: 'Ingresá una fecha válida.',
130
+ invalidOption: 'Elegí una de las opciones.',
131
+ },
132
+ entity_type: {
133
+ title: '¿Cómo te vas a registrar?',
134
+ subtitle: 'Elegí si te registrás como persona humana o en nombre de una persona jurídica.',
135
+ human: 'Persona humana',
136
+ humanDescription: 'Me registro a título personal.',
137
+ legal: 'Persona jurídica',
138
+ legalDescription: 'Registro una empresa, sociedad u otra organización.',
139
+ required: 'Elegí una opción para continuar.',
140
+ },
141
+ unsupported_step: {
142
+ title: 'Este paso no está disponible',
143
+ message:
144
+ 'Esta versión no puede mostrar el siguiente paso de tu registro. Volvé a intentar más tarde; tu avance quedó guardado.',
145
+ },
118
146
  terms_and_conditions: {
119
147
  title: 'Términos y condiciones',
120
148
  subtitle: 'Revisá cada punto y marcá que aceptás para continuar.',
package/src/index.ts CHANGED
@@ -100,6 +100,7 @@ export type {
100
100
  OnboardingStep,
101
101
  OnboardingStepStatus,
102
102
  OnboardingType,
103
+ EntityType,
103
104
  OnboardingResult,
104
105
  OnboardingExit,
105
106
  OnboardingSessionEvent,
@@ -124,6 +125,9 @@ export type {
124
125
  EconomicActivityItem,
125
126
  DocumentsOcrStepConfig,
126
127
  TermsAndConditionsStepConfig,
128
+ CustomFormStepConfig,
129
+ CustomFormField,
130
+ CustomFormFieldType,
127
131
  // Payloads
128
132
  HumanBasicInfoPayload,
129
133
  LegalBasicInfoPayload,
@@ -132,6 +136,9 @@ export type {
132
136
  AddressInfoPayload,
133
137
  SwornDeclarationPayload,
134
138
  EconomicActivitySelectionPayload,
139
+ CustomFormSubmitPayload,
140
+ CustomFormResponseValue,
141
+ EntityTypeSelectionPayload,
135
142
  EmailContactPayload,
136
143
  PhoneContactPayload,
137
144
  TaxInfoPayload,