@velion-la/onboarding-sdk-react-native 1.4.0-beta.1 → 1.4.0-beta.2

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 (64) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +11 -0
  3. package/lib/commonjs/core/VelionOnboarding.js +123 -6
  4. package/lib/commonjs/core/VelionOnboarding.js.map +1 -1
  5. package/lib/commonjs/core/sessionCancelledCopy.js +25 -0
  6. package/lib/commonjs/core/sessionCancelledCopy.js.map +1 -0
  7. package/lib/commonjs/core/sessionStateMapper.js +17 -4
  8. package/lib/commonjs/core/sessionStateMapper.js.map +1 -1
  9. package/lib/commonjs/core/sseReasonMessages.js +19 -1
  10. package/lib/commonjs/core/sseReasonMessages.js.map +1 -1
  11. package/lib/commonjs/i18n/strings/en.js +5 -1
  12. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  13. package/lib/commonjs/i18n/strings/es.js +5 -1
  14. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  15. package/lib/commonjs/transport/api.js +18 -1
  16. package/lib/commonjs/transport/api.js.map +1 -1
  17. package/lib/commonjs/transport/sse.js +2 -2
  18. package/lib/commonjs/transport/sse.js.map +1 -1
  19. package/lib/commonjs/types/index.js +11 -0
  20. package/lib/commonjs/types/index.js.map +1 -1
  21. package/lib/module/core/VelionOnboarding.js +124 -7
  22. package/lib/module/core/VelionOnboarding.js.map +1 -1
  23. package/lib/module/core/sessionCancelledCopy.js +21 -0
  24. package/lib/module/core/sessionCancelledCopy.js.map +1 -0
  25. package/lib/module/core/sessionStateMapper.js +16 -4
  26. package/lib/module/core/sessionStateMapper.js.map +1 -1
  27. package/lib/module/core/sseReasonMessages.js +18 -0
  28. package/lib/module/core/sseReasonMessages.js.map +1 -1
  29. package/lib/module/i18n/strings/en.js +5 -1
  30. package/lib/module/i18n/strings/en.js.map +1 -1
  31. package/lib/module/i18n/strings/es.js +5 -1
  32. package/lib/module/i18n/strings/es.js.map +1 -1
  33. package/lib/module/transport/api.js +18 -1
  34. package/lib/module/transport/api.js.map +1 -1
  35. package/lib/module/transport/sse.js +2 -2
  36. package/lib/module/transport/sse.js.map +1 -1
  37. package/lib/module/types/index.js +11 -0
  38. package/lib/module/types/index.js.map +1 -1
  39. package/lib/typescript/core/VelionOnboarding.d.ts +24 -0
  40. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  41. package/lib/typescript/core/sessionCancelledCopy.d.ts +14 -0
  42. package/lib/typescript/core/sessionCancelledCopy.d.ts.map +1 -0
  43. package/lib/typescript/core/sessionStateMapper.d.ts +11 -3
  44. package/lib/typescript/core/sessionStateMapper.d.ts.map +1 -1
  45. package/lib/typescript/core/sseReasonMessages.d.ts +6 -0
  46. package/lib/typescript/core/sseReasonMessages.d.ts.map +1 -1
  47. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  48. package/lib/typescript/i18n/strings/es.d.ts +2 -0
  49. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  50. package/lib/typescript/transport/api.d.ts +1 -0
  51. package/lib/typescript/transport/api.d.ts.map +1 -1
  52. package/lib/typescript/transport/sse.d.ts.map +1 -1
  53. package/lib/typescript/types/index.d.ts +23 -5
  54. package/lib/typescript/types/index.d.ts.map +1 -1
  55. package/package.json +1 -1
  56. package/src/core/VelionOnboarding.ts +118 -5
  57. package/src/core/sessionCancelledCopy.ts +29 -0
  58. package/src/core/sessionStateMapper.ts +18 -5
  59. package/src/core/sseReasonMessages.ts +20 -0
  60. package/src/i18n/strings/en.ts +5 -0
  61. package/src/i18n/strings/es.ts +5 -0
  62. package/src/transport/api.ts +17 -1
  63. package/src/transport/sse.ts +2 -0
  64. package/src/types/index.ts +23 -5
@@ -14,6 +14,9 @@
14
14
  * once the retry quota is exhausted the backend emits SESSION_DECLINED instead
15
15
  * - 45 s watchdog for terminal SSE event after final step → fallback GET
16
16
  * - SESSION_DECLINED handling races with module.run()
17
+ * - SESSION_CANCELLED rides the same channel as SESSION_DECLINED (it can land
18
+ * mid-step too) but never triggers a GET: the backend revokes the session
19
+ * token with the cancellation, so the SDK closes SSE and stops calling out
17
20
  */
18
21
 
19
22
  import { TypedEventEmitter } from '../utils/EventEmitter';
@@ -25,11 +28,13 @@ import {
25
28
  mapOnboardingDtoToResult,
26
29
  mapOnboardingDtoToResultWithStatus,
27
30
  isTerminalSessionStatusFromDto,
31
+ isCancelledSessionStatus,
28
32
  requiresCurrentStepForSessionStatus,
29
33
  deriveCanGoBack,
30
34
  } from './sessionStateMapper';
31
35
  import { createSessionEventSource } from '../transport/sse';
32
36
  import { resolveSessionDeclinedCopy } from './sessionDeclinedCopy';
37
+ import { resolveSessionCancelledCopy } from './sessionCancelledCopy';
33
38
  import { resolveRetryStepCopy } from './retryStepCopy';
34
39
  import {
35
40
  parseBackExitCommand,
@@ -132,10 +137,21 @@ function isTerminalSessionEvent(event: OnboardingSessionEvent): boolean {
132
137
  t === 'SESSION_APPROVED' ||
133
138
  t === 'SESSION_MANUAL_REVIEW' ||
134
139
  t === 'SESSION_DECLINED' ||
140
+ t === 'SESSION_CANCELLED' ||
135
141
  t === 'SESSION_TERMINATED'
136
142
  );
137
143
  }
138
144
 
145
+ /**
146
+ * Terminal events that end the flow on their own, without a GET for the final
147
+ * result: they can arrive mid-step and race the active module. SESSION_CANCELLED
148
+ * is here because its token is already revoked when it arrives.
149
+ */
150
+ function isSessionEndingEvent(event: OnboardingSessionEvent): boolean {
151
+ const t = event.event_type;
152
+ return t === 'SESSION_DECLINED' || t === 'SESSION_CANCELLED';
153
+ }
154
+
139
155
  function terminalEventTypeToStatus(
140
156
  eventType: string | undefined,
141
157
  ): OnboardingResult['status'] | undefined {
@@ -153,6 +169,11 @@ function terminalEventTypeToStatus(
153
169
  }
154
170
  }
155
171
 
172
+ /** GET reported `CANCELLED`; its DTO carries no reason, so the event has none. */
173
+ function cancelledEventFromDto(): OnboardingSessionEvent {
174
+ return { event_type: 'SESSION_CANCELLED', session_status: 'CANCELLED' };
175
+ }
176
+
156
177
  function isSessionTokenAuthSdkError(err: unknown): err is SdkError {
157
178
  return (
158
179
  err != null &&
@@ -378,9 +399,13 @@ export class VelionOnboarding {
378
399
  this.stepReversibility = sessionState.stepReversibility ?? [];
379
400
  this.emitter.emit('session:loaded', sessionState);
380
401
 
402
+ if (isCancelledSessionStatus(dto.status)) {
403
+ this.showLoading(null);
404
+ this.endFlowWithSessionCancelled(cancelledEventFromDto());
405
+ return;
406
+ }
381
407
  if (isTerminalSessionStatusFromDto(dto.status)) {
382
- const result = mapOnboardingDtoToResult(dto, this.config.sessionId);
383
- this.completeFlow(result);
408
+ this.completeFlow(this.resultFromDtoOrThrow(dto));
384
409
  return;
385
410
  }
386
411
 
@@ -707,6 +732,10 @@ export class VelionOnboarding {
707
732
  private async finalizeSessionWithTerminalEvent(
708
733
  event: OnboardingSessionEvent,
709
734
  ): Promise<void> {
735
+ if (isSessionEndingEvent(event)) {
736
+ this.endFlowWithSessionDeclined(event);
737
+ return;
738
+ }
710
739
  const status = terminalEventTypeToStatus(event.event_type);
711
740
  if (!status) {
712
741
  await this.finalizeSessionSingleGet();
@@ -747,8 +776,25 @@ export class VelionOnboarding {
747
776
  cause: err,
748
777
  } satisfies SdkError;
749
778
  }
779
+ if (isCancelledSessionStatus(dto.status)) {
780
+ this.endFlowWithSessionCancelled(cancelledEventFromDto());
781
+ return;
782
+ }
783
+ this.completeFlow(this.resultFromDtoOrThrow(dto));
784
+ }
785
+
786
+ /**
787
+ * Maps a terminal GET to the host result. A status this SDK does not know is
788
+ * an error, not a verdict: reporting it as MANUAL_REVIEW (the old default)
789
+ * would tell the host something the backend never said.
790
+ */
791
+ private resultFromDtoOrThrow(dto: OnboardingDtoResponse): OnboardingResult {
750
792
  const result = mapOnboardingDtoToResult(dto, this.config.sessionId);
751
- this.completeFlow(result);
793
+ if (result) return result;
794
+ throw {
795
+ code: SdkErrorCode.API_ERROR,
796
+ message: `Session ${this.config.sessionId} reports an unknown status "${String(dto.status)}".`,
797
+ } satisfies SdkError;
752
798
  }
753
799
 
754
800
  private completeFlow(result: OnboardingResult): void {
@@ -827,7 +873,16 @@ export class VelionOnboarding {
827
873
  });
828
874
  }
829
875
 
876
+ /**
877
+ * Ends the flow on an SSE event that carries its own outcome. Dispatches
878
+ * SESSION_CANCELLED to {@link endFlowWithSessionCancelled}; everything else
879
+ * routed here is SESSION_DECLINED.
880
+ */
830
881
  private endFlowWithSessionDeclined(event: OnboardingSessionEvent): void {
882
+ if (event.event_type === 'SESSION_CANCELLED') {
883
+ this.endFlowWithSessionCancelled(event);
884
+ return;
885
+ }
831
886
  if (this.sessionEnded) return;
832
887
  this.sessionEnded = true;
833
888
  log.info('[Flow] Session finalized', {
@@ -853,6 +908,55 @@ export class VelionOnboarding {
853
908
  this.emitError(err);
854
909
  }
855
910
 
911
+ /**
912
+ * SESSION_CANCELLED: the backend retired the session and revoked its token.
913
+ * Also reached when GET reports `status: CANCELLED`. Closes SSE (so it does
914
+ * not reconnect into 401s) and the API caller, drops any active module, and
915
+ * emits `onError` with `SESSION_CANCELLED` — the same channel as
916
+ * SESSION_DECLINED — carrying the localized cancelled copy.
917
+ */
918
+ private endFlowWithSessionCancelled(event: OnboardingSessionEvent): void {
919
+ if (this.sessionEnded) return;
920
+ this.sessionEnded = true;
921
+ this.stopTalkingToBackend();
922
+ log.info('[Flow] Session finalized', {
923
+ sessionId: this.config.sessionId,
924
+ status: 'CANCELLED',
925
+ terminalReason: event.reason,
926
+ stepCode: event.step_code,
927
+ });
928
+ const copy = resolveSessionCancelledCopy(
929
+ this.config.locale,
930
+ this.config.finalResultScreenTexts,
931
+ event.reason,
932
+ );
933
+ const err: SdkError = {
934
+ code: SdkErrorCode.SESSION_CANCELLED,
935
+ message: copy.message,
936
+ ...(event.reason !== undefined && { cancelReason: event.reason }),
937
+ ...(event.step_code !== undefined && { stepCode: event.step_code }),
938
+ declineTitle: copy.title,
939
+ declineMessage: copy.message,
940
+ };
941
+ this.emitError(err);
942
+ }
943
+
944
+ /** Closes SSE and the API caller, and tears down the active step. */
945
+ private stopTalkingToBackend(): void {
946
+ this.api.close();
947
+ this.sseCleanup?.();
948
+ this.sseCleanup = null;
949
+ this.sseAbortController.abort();
950
+ this.activeModule?.destroy();
951
+ this.activeModule = null;
952
+ this.retryDialogResolve?.('cancel');
953
+ this.retryDialogResolve = null;
954
+ // Release a pending routing wait now instead of at its 30 s timeout.
955
+ const resolveNext = this.sseNextStepResolve;
956
+ this.sseNextStepResolve = null;
957
+ resolveNext?.(null);
958
+ }
959
+
856
960
  // ── SSE plumbing ──────────────────────────────────────────────────────────
857
961
 
858
962
  private openSseStream(sessionToken: string): void {
@@ -896,10 +1000,15 @@ export class VelionOnboarding {
896
1000
  this.config.onSessionEvent?.(event);
897
1001
  const isTerminal = isTerminalSessionEvent(event);
898
1002
 
899
- if (event.event_type === 'SESSION_DECLINED') {
1003
+ if (isSessionEndingEvent(event)) {
900
1004
  this.pendingTerminalEvent = event;
901
1005
  if (this.sessionDeclineHandler) {
902
1006
  this.sessionDeclineHandler(event);
1007
+ } else if (event.event_type === 'SESSION_CANCELLED' && this.retryDialogResolve) {
1008
+ // The retry dialog waits on the user, not on SSE: a cancelled session
1009
+ // must not sit behind it, since retrying would only hit a revoked token.
1010
+ this.pendingTerminalEvent = null;
1011
+ this.endFlowWithSessionCancelled(event);
903
1012
  } else {
904
1013
  this.pendingSessionDeclined = event;
905
1014
  }
@@ -1140,6 +1249,10 @@ export class VelionOnboarding {
1140
1249
  Math.min(ROUTING_SSE_WAIT_MS, budgetMs),
1141
1250
  );
1142
1251
  if (sseNext) return { kind: 'routed', command: sseNext };
1252
+ // The flow ended while this cycle waited (e.g. SESSION_CANCELLED won the
1253
+ // decline race): nobody consumes the result, and the fallback GET would only
1254
+ // hit a revoked token.
1255
+ if (this.sessionEnded || this.status === 'DESTROYED') return { kind: 'unresolved' };
1143
1256
  // A terminal event interrupted the wait: the caller consumes it.
1144
1257
  if (this.pendingTerminalEvent) return { kind: 'terminal' };
1145
1258
  const afterWait = this.consumeQueuedNextStepCommand();
@@ -1252,7 +1365,7 @@ export class VelionOnboarding {
1252
1365
  const event = this.pendingTerminalEvent;
1253
1366
  if (!event) return false;
1254
1367
  this.pendingTerminalEvent = null;
1255
- if (event.event_type === 'SESSION_DECLINED') {
1368
+ if (isSessionEndingEvent(event)) {
1256
1369
  this.endFlowWithSessionDeclined(event);
1257
1370
  return true;
1258
1371
  }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * @fileoverview Copy for a cancelled session (SSE SESSION_CANCELLED or GET
3
+ * `status: CANCELLED`). A cancellation is not a verdict on the person: the
4
+ * backend closed the session. Precedence: `finalResultScreenTexts.cancelled`,
5
+ * then the built-in copy for the backend `reason`, then the generic copy.
6
+ */
7
+
8
+ import { getStrings, resolveLocale } from '../i18n';
9
+ import type { VelionFinalResultScreenTexts } from '../types';
10
+ import { SESSION_CANCELLED_REASON_MESSAGES } from './sseReasonMessages';
11
+
12
+ export interface ResolvedSessionCancelledCopy {
13
+ title: string;
14
+ message: string;
15
+ }
16
+
17
+ /** Resolves the title and body shown when the session was cancelled. */
18
+ export function resolveSessionCancelledCopy(
19
+ locale: string | undefined,
20
+ texts: VelionFinalResultScreenTexts | undefined,
21
+ reason?: string,
22
+ ): ResolvedSessionCancelledCopy {
23
+ const generic = getStrings(locale).result;
24
+ const byReason = SESSION_CANCELLED_REASON_MESSAGES[reason?.trim() ?? '']?.[resolveLocale(locale)];
25
+ return {
26
+ title: texts?.cancelled?.title ?? byReason?.title ?? generic.cancelledTitle,
27
+ message: texts?.cancelled?.message ?? byReason?.message ?? generic.cancelledBody,
28
+ };
29
+ }
@@ -155,17 +155,28 @@ function resolveCurrentStepFromLegacySteps(
155
155
 
156
156
  /**
157
157
  * Maps GET /sessions `status` to {@link OnboardingResult.status}.
158
- * Unknown values fall back to `MANUAL_REVIEW`.
158
+ *
159
+ * `INITIATED` / `IN_PROGRESS` map to `MANUAL_REVIEW`: they only reach this
160
+ * mapper when the SDK gave up waiting for the verdict, which the backend will
161
+ * still produce asynchronously. Any other value returns `null`: a status this
162
+ * SDK does not know (`CANCELLED` before OSDKR-44 was one) must not be reported
163
+ * to the host as a verdict it never was.
159
164
  */
160
165
  export function mapSessionDtoStatusToResultStatus(
161
166
  raw: string | undefined,
162
- ): OnboardingResult['status'] {
167
+ ): OnboardingResult['status'] | null {
163
168
  const s = typeof raw === 'string' ? raw.trim().toUpperCase() : '';
164
169
  if (s === 'APPROVED') return 'APPROVED';
165
170
  if (s === 'MANUAL_REVIEW' || s === 'IN_REVIEW') return 'MANUAL_REVIEW';
166
171
  if (s === 'REJECTED') return 'REJECTED';
167
172
  if (s === 'DECLINED') return 'DECLINED';
168
- return 'MANUAL_REVIEW';
173
+ if (s === 'INITIATED' || s === 'IN_PROGRESS') return 'MANUAL_REVIEW';
174
+ return null;
175
+ }
176
+
177
+ /** True when GET session reports a session cancelled by the backend (not a verdict). */
178
+ export function isCancelledSessionStatus(raw: string | undefined): boolean {
179
+ return typeof raw === 'string' && raw.trim().toUpperCase() === 'CANCELLED';
169
180
  }
170
181
 
171
182
  /**
@@ -179,6 +190,7 @@ export function isTerminalSessionStatusFromDto(raw: string | undefined): boolean
179
190
  s === 'MANUAL_REVIEW' ||
180
191
  s === 'REJECTED' ||
181
192
  s === 'DECLINED' ||
193
+ s === 'CANCELLED' ||
182
194
  s === 'IN_REVIEW'
183
195
  );
184
196
  }
@@ -193,13 +205,14 @@ export function requiresCurrentStepForSessionStatus(raw: string | undefined): bo
193
205
 
194
206
  /**
195
207
  * Builds OnboardingResult from the same onboarding DTO when status is terminal.
208
+ * Returns `null` when the status is not one {@link mapSessionDtoStatusToResultStatus} knows.
196
209
  */
197
210
  export function mapOnboardingDtoToResult(
198
211
  dto: OnboardingDtoResponse,
199
212
  sessionId: string,
200
- ): OnboardingResult {
213
+ ): OnboardingResult | null {
201
214
  const terminal = mapSessionDtoStatusToResultStatus(dto.status);
202
- return buildResultFromDto(dto, sessionId, terminal);
215
+ return terminal === null ? null : buildResultFromDto(dto, sessionId, terminal);
203
216
  }
204
217
 
205
218
  /**
@@ -529,3 +529,23 @@ export const SESSION_MANUAL_REVIEW_REASON_MESSAGES: Record<string, LocalizedPair
529
529
  },
530
530
  },
531
531
  };
532
+
533
+ /**
534
+ * Reasons on SESSION_CANCELLED. A cancellation is not a verdict on the person:
535
+ * the backend closed the session (e.g. a new workflow version was published
536
+ * forcing it). Unknown reasons fall back to the generic cancelled copy.
537
+ */
538
+ export const SESSION_CANCELLED_REASON_MESSAGES: Record<string, LocalizedPair> = {
539
+ WORKFLOW_VERSION_RETIRED: {
540
+ en: {
541
+ title: 'The verification process was updated',
542
+ message:
543
+ 'We closed this session because the process changed. Start the verification again to continue with the current version.',
544
+ },
545
+ es: {
546
+ title: 'El proceso de verificación se actualizó',
547
+ message:
548
+ 'Cerramos esta sesión porque el proceso cambió. Volvé a iniciar la verificación para continuar con la versión actual.',
549
+ },
550
+ },
551
+ };
@@ -304,6 +304,11 @@ export const EN: StringsTable = {
304
304
  rejectedTitle: 'Verification rejected',
305
305
  rejectedBody: 'This session could not be completed.',
306
306
  declineHeadline: 'We could not continue',
307
+ // Session cancelled by the backend (SESSION_CANCELLED / GET status CANCELLED),
308
+ // e.g. its workflow version was retired. Not a verdict on the user.
309
+ cancelledTitle: 'This session was closed',
310
+ cancelledBody:
311
+ 'This session is no longer active and cannot be continued. Start the verification again to begin a new one.',
307
312
  },
308
313
  // Retry dialog shown when the backend asks the SDK to re-present a failed step
309
314
  // (ROUTING_COMMAND / RETRY_STEP). Copy is derived from the step, not the
@@ -304,6 +304,11 @@ export const ES = {
304
304
  rejectedTitle: 'Verificación rechazada',
305
305
  rejectedBody: 'No se pudo completar esta sesión.',
306
306
  declineHeadline: 'No pudimos continuar',
307
+ // Session cancelled by the backend (SESSION_CANCELLED / GET status CANCELLED),
308
+ // e.g. its workflow version was retired. Not a verdict on the user.
309
+ cancelledTitle: 'Esta sesión se cerró',
310
+ cancelledBody:
311
+ 'La sesión ya no está activa y no podés continuarla. Volvé a iniciar la verificación para empezar de nuevo.',
307
312
  },
308
313
  // Retry dialog shown when the backend asks the SDK to re-present a failed step
309
314
  // (ROUTING_COMMAND / RETRY_STEP). Copy is derived from the step, not the
@@ -92,6 +92,7 @@ export function createApiCaller(
92
92
  let currentToken = sessionToken;
93
93
  let currentExpiresAt = expiresAt;
94
94
  let clockSkewWarned = false;
95
+ let closed = false;
95
96
  const appId = getAppId();
96
97
 
97
98
  function ensureTokenValid(): void {
@@ -136,11 +137,26 @@ export function createApiCaller(
136
137
  clockSkewWarned = false;
137
138
  }
138
139
 
140
+ /**
141
+ * Refuses every later request, which rejects with an `AbortError` like an
142
+ * aborted call. Used once the backend closed the session (SESSION_CANCELLED):
143
+ * the token is revoked, so any request would only earn a 401.
144
+ */
145
+ function close(): void {
146
+ closed = true;
147
+ }
148
+
139
149
  async function call<TResponse>(
140
150
  endpoint: string,
141
151
  init: RequestInit,
142
152
  options: ApiCallOptions = {},
143
153
  ): Promise<TResponse> {
154
+ if (closed) {
155
+ // Hermes has no DOMException; an Error named AbortError is what callers check.
156
+ const aborted = new Error(`Session closed; request to "${endpoint}" not sent.`);
157
+ aborted.name = 'AbortError';
158
+ throw aborted;
159
+ }
144
160
  ensureTokenValid();
145
161
  const url = `${baseUrl}${endpoint}`;
146
162
 
@@ -267,7 +283,7 @@ export function createApiCaller(
267
283
  );
268
284
  }
269
285
 
270
- return { get, post, postFormData, setSessionToken } as const;
286
+ return { get, post, postFormData, setSessionToken, close } as const;
271
287
  }
272
288
 
273
289
  /** The type of the object returned by `createApiCaller`. */
@@ -57,6 +57,7 @@ const KNOWN_EVENT_TYPES = [
57
57
  'SESSION_APPROVED',
58
58
  'SESSION_MANUAL_REVIEW',
59
59
  'SESSION_DECLINED',
60
+ 'SESSION_CANCELLED',
60
61
  'SESSION_TERMINATED',
61
62
  // Legacy/domain-event names emitted by `SseDomainEventConsumer` in the
62
63
  // Spring orchestrator. Listening to both lets the same SDK build talk to
@@ -66,6 +67,7 @@ const KNOWN_EVENT_TYPES = [
66
67
  'SessionApprovedEvent',
67
68
  'SessionManualReviewEvent',
68
69
  'SessionDeclinedEvent',
70
+ 'SessionCancelledEvent',
69
71
  'SessionTerminatedEvent',
70
72
  'OnboardingCreatedEvent',
71
73
  ] as const;
@@ -299,6 +299,15 @@ export enum SdkErrorCode {
299
299
  SESSION_FETCH_FAILED = 'SESSION_FETCH_FAILED',
300
300
  /** Backend sent SESSION_DECLINED over SSE; session ended before completion. */
301
301
  SESSION_DECLINED = 'SESSION_DECLINED',
302
+ /**
303
+ * The backend cancelled the session (`SESSION_CANCELLED` over SSE, or
304
+ * `status: CANCELLED` on `GET /sessions/:id`). Not a verdict on the person:
305
+ * the session was closed on Velion's side (e.g. `WORKFLOW_VERSION_RETIRED`
306
+ * when a new workflow version is published forcing it). The session token
307
+ * is revoked and the SDK sends no further requests; create a new session
308
+ * to let the person start again. `cancelReason` carries the backend reason.
309
+ */
310
+ SESSION_CANCELLED = 'SESSION_CANCELLED',
302
311
  /**
303
312
  * A step was completed but the backend did not route the session to the
304
313
  * next one within `routingTimeoutMs` (default 120 s): no `ROUTING_COMMAND`
@@ -384,16 +393,18 @@ export interface SdkError {
384
393
  */
385
394
  readonly stepCode?: string;
386
395
  /**
387
- * Localized headline resolved by the SDK for SESSION_DECLINED.
396
+ * Localized headline resolved by the SDK for SESSION_DECLINED and SESSION_CANCELLED.
388
397
  * Useful when hosts hide the built-in final result screen but still want
389
398
  * the same user-facing text in custom UI.
390
399
  */
391
400
  readonly declineTitle?: string;
392
401
  /**
393
- * Localized body message resolved by the SDK for SESSION_DECLINED.
402
+ * Localized body message resolved by the SDK for SESSION_DECLINED and SESSION_CANCELLED.
394
403
  * Mirrors the text shown in the built-in final result screen.
395
404
  */
396
405
  readonly declineMessage?: string;
406
+ /** Present when `code === SdkErrorCode.SESSION_CANCELLED` (backend `reason`, e.g. `WORKFLOW_VERSION_RETIRED`). */
407
+ readonly cancelReason?: string;
397
408
  /** Present when `code === SdkErrorCode.CAMERA_ERROR`. Provides camera-specific detail. */
398
409
  readonly cameraCode?: CameraErrorCode;
399
410
  /** HTTP status code when the error originated from an API call. */
@@ -485,6 +496,8 @@ export interface VelionFinalResultScreenTexts {
485
496
  rejected?: VelionFinalResultStatusCopy;
486
497
  /** Copy when {@link OnboardingResult.status} is `DECLINED`. */
487
498
  declined?: VelionFinalResultStatusCopy;
499
+ /** Copy for the screen shown when the backend cancels the session (`SESSION_CANCELLED`). */
500
+ cancelled?: VelionFinalResultStatusCopy;
488
501
  /** Primary button label (e.g. "Entendido" / "Got it"). */
489
502
  dismissLabel?: string;
490
503
  }
@@ -1021,6 +1034,9 @@ export interface OnboardingResult {
1021
1034
  * - `MANUAL_REVIEW`: Flagged for human review (common in AML flows). Backend `IN_REVIEW` maps here.
1022
1035
  * - `REJECTED`: Automatically rejected (fraud signals, liveness failure, etc.).
1023
1036
  * - `DECLINED`: Session ended in a declined state (matches GET session `status: DECLINED`).
1037
+ *
1038
+ * A cancelled session (`CANCELLED`) is not a verdict and never produces an
1039
+ * `OnboardingResult`: it reaches the host as `onError(SESSION_CANCELLED)`.
1024
1040
  */
1025
1041
  status: 'APPROVED' | 'MANUAL_REVIEW' | 'REJECTED' | 'DECLINED';
1026
1042
  /** An optional tracking reference for support and audit trails. */
@@ -1275,6 +1291,8 @@ export interface TermsAndConditionsSubmitPayload {
1275
1291
  * - SESSION_APPROVED — all checks passed; session_status = APPROVED
1276
1292
  * - SESSION_MANUAL_REVIEW — manual review required; session_status = MANUAL_REVIEW
1277
1293
  * - SESSION_DECLINED — session ended with decline (step_code, session_status DECLINED, reason)
1294
+ * - SESSION_CANCELLED — session cancelled by the backend, not a verdict (session_status CANCELLED,
1295
+ * reason e.g. WORKFLOW_VERSION_RETIRED). The stream closes and the session token is revoked.
1278
1296
  *
1279
1297
  * Reverse navigation ("back") arrives as a STEP_UPDATED (the re-opened step
1280
1298
  * moves to IN_PROGRESS) followed by a ROUTING_COMMAND with action PREVIOUS_STEP
@@ -1288,13 +1306,13 @@ export interface TermsAndConditionsSubmitPayload {
1288
1306
  export interface OnboardingSessionEvent {
1289
1307
  /** Onboarding session identifier (Long in backend). */
1290
1308
  session_id?: number;
1291
- /** Discriminator: STEP_UPDATED | ROUTING_COMMAND | SESSION_APPROVED | SESSION_MANUAL_REVIEW | SESSION_DECLINED */
1309
+ /** Discriminator: STEP_UPDATED | ROUTING_COMMAND | SESSION_APPROVED | SESSION_MANUAL_REVIEW | SESSION_DECLINED | SESSION_CANCELLED */
1292
1310
  event_type?: string;
1293
1311
  /** Present for STEP_UPDATED or ROUTING_COMMAND (next step code). */
1294
1312
  step_code?: string;
1295
1313
  /** Present for STEP_UPDATED; e.g. COMPLETED. */
1296
1314
  step_status?: string;
1297
- /** Present for terminal events; e.g. APPROVED | MANUAL_REVIEW | REJECTED. */
1315
+ /** Present for terminal events; e.g. APPROVED | MANUAL_REVIEW | REJECTED | DECLINED | CANCELLED. */
1298
1316
  session_status?: string;
1299
1317
  /**
1300
1318
  * For ROUTING_COMMAND: NEXT_STEP | PREVIOUS_STEP | RETRY_STEP (render step_code),
@@ -1302,7 +1320,7 @@ export interface OnboardingSessionEvent {
1302
1320
  * or TERMINATE (end flow).
1303
1321
  */
1304
1322
  action?: string;
1305
- /** For SESSION_DECLINED / SESSION_MANUAL_REVIEW or ROUTING_COMMAND TERMINATE; e.g. UNREADABLE_DOCUMENT. */
1323
+ /** For SESSION_DECLINED / SESSION_CANCELLED / SESSION_MANUAL_REVIEW or ROUTING_COMMAND TERMINATE; e.g. UNREADABLE_DOCUMENT. */
1306
1324
  reason?: string;
1307
1325
  /** Step-specific config sent with ROUTING_COMMAND NEXT_STEP / PREVIOUS_STEP. */
1308
1326
  step_config?: Record<string, unknown>;