@myazahq/kyc-sdk-react-native 2.2.0 → 2.3.0

package/src/lib/step-log.ts

@@ -0,0 +1,43 @@
+// Session step log — records each SDK step the user reaches, with a
+// timestamp, so the server can reconstruct the journey on the verification
+// timeline ("consent opened → ID type chosen → document captured → …").
+// Rides the verify submission as metadata.device.stepLog — the same free-form
+// channel the Device Intelligence fingerprint uses: no extra network calls,
+// no new endpoint, and old SDKs simply never send it. `sentAt` is stamped at
+// collect time so the server can correct client-clock skew against its own
+// receipt time. Step names only — never PII. Mirrors the web SDK's
+// lib/step-log.ts; keep the two in lockstep.
+
+export interface StepLogEntry {
+  step: string;
+  at: string;
+}
+
+export interface StepLog {
+  steps: StepLogEntry[];
+  sentAt: string;
+}
+
+const MAX_ENTRIES = 40;
+
+let entries: StepLogEntry[] = [];
+
+/** Fresh slate per session (called from the store's reset — each modal open). */
+export function resetStepLog(): void {
+  entries = [];
+}
+
+/** Records a step visit. Consecutive duplicates are collapsed; back-and-forth
+ *  navigation is kept — repeat visits are honest journey data. */
+export function recordStep(step: string): void {
+  if (entries.length >= MAX_ENTRIES) return;
+  if (entries[entries.length - 1]?.step === step) return;
+  entries.push({ step, at: new Date().toISOString() });
+}
+
+/** Snapshot attached to the verify submission. Null when nothing was recorded
+ *  so the field is simply absent. */
+export function getStepLog(): StepLog | null {
+  if (entries.length === 0) return null;
+  return { steps: [...entries], sentAt: new Date().toISOString() };
+}

package/src/lib/step-window.ts

@@ -0,0 +1,96 @@
+/**
+ * Which step circles to draw, and when to start collapsing them.
+ *
+ * A KYB flow can reach FOURTEEN steps (consent → email → phone →
+ * business-details → key-people → documents → applicant-role → country-select →
+ * id-type → document-capture → nfc → liveness → questionnaire → submitted), and
+ * an individual flow eleven. The circles are a fixed size, so they cannot shrink
+ * to fit: on a 360dp Android with 16dp padding, ten steps leave 14dp TOTAL for
+ * nine connectors, and twelve steps overflow the row outright.
+ *
+ * COLLAPSING IS A LAST RESORT. The row fits as many real circles as the measured
+ * width allows and only windows once they would stop looking like a connected
+ * chain — which is what the minimum connector length below decides. A fixed cap
+ * would collapse a 9-step flow on a large phone that had room for all of it.
+ *
+ * When it does window, two rules keep the elision honest:
+ *
+ *   • The LAST step is always shown. Without it the ellipsis hides how much is
+ *     left, which is the one thing a progress indicator exists to answer.
+ *   • The FIRST step is always shown, so the row still reads as a whole journey
+ *     rather than a fragment floating in the middle.
+ *
+ *     1 ··· 5 6 7 ··· 10
+ */
+
+/** A rendered slot: a step index, or a collapsed run of them. */
+export type StepSlot = number | 'ellipsis';
+
+/**
+ * Shortest connector that still reads as a line joining two circles rather than
+ * a stray dash. Below this the "chain" metaphor is gone and the row just looks
+ * cramped — which is the state the 10-step screenshot was already in.
+ */
+export const MIN_CONNECTOR = 10;
+
+/** Horizontal margin a connector carries on each side (matches the component). */
+const CONNECTOR_MARGIN = 6;
+
+/**
+ * Never collapse below this many circles. At 5 the pattern still reads as
+ * first · gap · current · gap · last; below it the row says nothing useful.
+ */
+const MIN_CIRCLES = 5;
+
+const clamp = (v: number, lo: number, hi: number): number => Math.min(Math.max(v, lo), hi);
+
+/**
+ * How many circles fit across `width` before they stop looking like a chain.
+ *
+ *   n·size + (n−1)·(margins + minConnector) ≤ width
+ *
+ * Returns 0 when the width is not known yet, which the caller reads as "render
+ * them all" — an un-measured first frame should not flash a collapsed row.
+ */
+export function fitStepCircles(width: number, circleSize: number): number {
+  if (!Number.isFinite(width) || width <= 0) return 0;
+  const gap = CONNECTOR_MARGIN + MIN_CONNECTOR;
+  return Math.max(1, Math.floor((width + gap) / (circleSize + gap)));
+}
+
+/**
+ * @param total       how many steps the flow has
+ * @param active      0-based index of the current step
+ * @param maxCircles  how many circles fit (from `fitStepCircles`); 0 = unknown,
+ *                    render everything
+ */
+export function windowedSteps(total: number, active: number, maxCircles = 0): StepSlot[] {
+  if (total <= 0) return [];
+  const all = Array.from({ length: total }, (_, i) => i);
+  if (maxCircles <= 0 || total <= maxCircles) return all;
+
+  // A collapsed row also pays for up to TWO ellipses, each about as wide as a
+  // circle once its padding and connectors are counted. Reserving only one
+  // between them under-counted, and the row overflowed — which is invisible
+  // until you notice every `flex: 1` connector has collapsed to zero width.
+  const budget = Math.max(MIN_CIRCLES, maxCircles - 2);
+  if (total <= budget) return all;
+
+  const first = 0;
+  const last = total - 1;
+  const current = clamp(active, first, last);
+
+  // First and last are drawn unconditionally; the rest of the budget is a
+  // window centred on the current step.
+  const windowSize = Math.max(1, budget - 2);
+  const half = Math.floor((windowSize - 1) / 2);
+  const start = clamp(current - half, first + 1, Math.max(first + 1, last - windowSize));
+  const end = Math.min(start + windowSize - 1, last - 1);
+
+  const slots: StepSlot[] = [first];
+  if (start > first + 1) slots.push('ellipsis');
+  for (let i = start; i <= end; i += 1) slots.push(i);
+  if (end < last - 1) slots.push('ellipsis');
+  slots.push(last);
+  return slots;
+}

package/src/liveness/useLiveness.ts

@@ -562,7 +562,7 @@ export function useLiveness(opts: UseLivenessOptions = {}): UseLivenessReturn {
     setState((s) => ({
       ...s,
       phase: 'complete',
-      instruction: 'Verification complete',
+      instruction: 'Capture complete',
       activeChallenge: null,
       positionGuidance: null,
     }));

package/src/screens/IdTypeStep.tsx

@@ -99,6 +99,19 @@ export function IdTypeStep(): React.ReactElement {
     return (table[country.toUpperCase()] ?? []).filter((t) => allowed(t.key));
   }, [country, config.idTypes, config.countries, serverConfig]);
 
+  // Document Intelligence off ⇒ number-only IDs only (there is no document
+  // capture step), so drop every document-scanned ID from the picker. This is
+  // what makes the disabled step actually disappear from the live flow rather
+  // than still offering passports and licences that then have nowhere to be
+  // captured. Mirrors the web SDK's IdTypeStep.
+  const visible = useMemo<IdTypeDefinition[]>(
+    () =>
+      config.enableDocumentCapture === false
+        ? available.filter((t) => !t.requiresDocumentCapture)
+        : available,
+    [available, config.enableDocumentCapture],
+  );
+
   if (serverConfig.status === 'loading') {
     return (
       <View style={{ paddingVertical: spacing.xl, alignItems: 'center' }}>
@@ -107,7 +120,7 @@ export function IdTypeStep(): React.ReactElement {
     );
   }
 
-  if (serverConfig.status === 'ready' && available.length === 0) {
+  if (serverConfig.status === 'ready' && visible.length === 0) {
     return (
       <View
         style={{
@@ -127,7 +140,7 @@ export function IdTypeStep(): React.ReactElement {
 
   return (
     <View>
-      {available.map((t) => {
+      {visible.map((t) => {
         const selected = selectedIdType === t.key;
         return (
           <Pressable

package/src/screens/NfcStep.tsx

@@ -151,6 +151,18 @@ export function NfcStep(): React.ReactElement {
         },
       );
       if (!liveRef.current || seq !== readSeqRef.current) return;
+      // Which access protocol opened the session, and why. PACE is new here and
+      // reads over BAC by default, so this line is what distinguishes "the chip
+      // never offered PACE" from "our PACE was attempted and failed" while it
+      // is being proven against real documents. Dev builds only — it is
+      // diagnostics, never user-facing.
+      if (__DEV__) {
+        console.log(
+          `[kyc.nfc] session opened over ${result.chipAuth}` +
+            (result.paceOutcome ? ` (pace: ${result.paceOutcome}` : '') +
+            (result.paceDetail ? ` — ${result.paceDetail})` : result.paceOutcome ? ')' : ''),
+        );
+      }
       store.getState().setChipData(result);
       setResult(result);
       setPhase('done');

package/src/screens/QuestionnaireField.tsx

@@ -33,22 +33,35 @@ export function QuestionnaireFieldView({
   field,
   value,
   currencyValue,
+  detailValue,
   error,
   onChange,
   onCurrencyChange,
+  onDetailChange,
 }: {
   field: FieldDef;
   value: QuestionnaireAnswerValue | undefined;
   /** money only: the `<key>_currency` companion answer. */
   currencyValue?: string;
+  /** choice fields only: the `<key>_other` companion answer. */
+  detailValue?: string;
   error?: string;
   onChange: (value: QuestionnaireAnswerValue | undefined) => void;
   onCurrencyChange: (currency: string) => void;
+  onDetailChange?: (detail: string | undefined) => void;
 }): React.ReactElement {
   const { colors } = useTheme();
 
   const isPlainInput = field.type === 'text' || field.type === 'number';
 
+  // The chosen option that is not an answer on its own ("Other"). Covers both
+  // select (a single value) and multiselect (a list).
+  const detailOption = (field.options ?? []).find(
+    (o) =>
+      o.requiresDetail &&
+      (Array.isArray(value) ? value.includes(o.value) : value === o.value),
+  );
+
   return (
     <View style={{ marginBottom: spacing.lg }}>
       <FieldLabel
@@ -143,6 +156,23 @@ export function QuestionnaireFieldView({
           })
         : null}
 
+      {/* Free text behind an "Other" choice. Always required once that option
+          is picked: an unexplained "Other" is the answer a compliance reviewer
+          most needs spelled out. */}
+      {detailOption ? (
+        <View style={{ marginTop: spacing.sm }}>
+          <MyazaInput
+            label={detailOption.detailLabel || 'Please specify'}
+            value={detailValue ?? ''}
+            maxLength={200}
+            placeholder={
+              detailOption.detailPlaceholder || `Tell us more about "${detailOption.label}"`
+            }
+            onChangeText={(text: string) => onDetailChange?.(text || undefined)}
+          />
+        </View>
+      ) : null}
+
       {/* Inputs draw their own error; the rest need one underneath. */}
       {error && !isPlainInput && field.type !== 'money' ? (
         <MyazaText variant="bodySmall" color={colors.error} style={{ marginTop: spacing.xs }}>

package/src/screens/QuestionnaireStep.tsx

@@ -4,7 +4,7 @@ import { View } from 'react-native';
 import { spacing } from '../config/theme';
 import { useKyc, useKycConfig, useKycStore } from '../components/runtime';
 import { MyazaButton } from '../components/MyazaButton';
-import { currencyKeyFor, validateQuestionnaire } from '../config/questionnaire';
+import { currencyKeyFor, otherKeyFor, validateQuestionnaire } from '../config/questionnaire';
 import { QuestionnaireFieldView } from './QuestionnaireField';
 import type { QuestionnaireAnswerValue } from '../types/workflow';
 
@@ -63,9 +63,11 @@ export function QuestionnaireStep(): React.ReactElement {
           field={field}
           value={answers[field.key]}
           currencyValue={answers[currencyKeyFor(field)] as string | undefined}
+          detailValue={answers[otherKeyFor(field)] as string | undefined}
           error={errors[field.key] || undefined}
           onChange={(value) => setAnswer(field.key, value)}
           onCurrencyChange={(currency) => setAnswer(currencyKeyFor(field), currency)}
+          onDetailChange={(detail) => setAnswer(otherKeyFor(field), detail)}
         />
       ))}
 

package/src/screens/nfc/NfcSuccessPanel.tsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react';
+import React, { useMemo, useState } from 'react';
 import { Image, View } from 'react-native';
 
 import { spacing } from '../../config/theme';
@@ -8,7 +8,7 @@ import { MyazaButton } from '../../components/MyazaButton';
 import { Icon } from '../../components/Icon';
 import { useChipPortrait } from './useChipPortrait';
 import { NfcScannedSummary } from './NfcScannedSummary';
-import type { EmrtdReadResult } from '../../emrtd';
+import { parseDg1, type EmrtdReadResult } from '../../emrtd';
 import type { MrzScan } from '../../mrz/parse';
 
 // ---------------------------------------------------------------------------
@@ -41,7 +41,12 @@ export function NfcSuccessPanel({
   // component rejects) must degrade to the generic mark, not an empty circle.
   const [portraitBroken, setPortraitBroken] = useState(false);
   const portrait = portraitBroken ? null : portraitUri;
-  const name = [mrz?.firstName, mrz?.lastName].filter(Boolean).join(' ');
+  // Once the chip has been read, IT is the source — see emrtd/dg1.ts. The
+  // camera scan stays as the fallback for a chip whose DG1 we could not parse,
+  // so a read that otherwise worked still shows something.
+  const chip = useMemo(() => parseDg1(result.dg1), [result.dg1]);
+  const holder = chip ?? mrz;
+  const name = [holder?.firstName, holder?.lastName].filter(Boolean).join(' ');
 
   return (
     <View style={{ alignItems: 'center' }}>
@@ -132,12 +137,14 @@ export function NfcSuccessPanel({
       ) : null}
 
       {/* What was read, shown back — the same card the pre-read screen uses, so
-          the user checks the same two fields against the printed page. */}
-      {mrz ? (
+          the user checks the same two fields against the printed page. Before
+          the read that card can only show the camera's guess; here it shows the
+          chip's own values, which is both correct and a stronger check. */}
+      {holder ? (
         <>
           <View style={{ height: spacing.lg }} />
           <View style={{ alignSelf: 'stretch' }}>
-            <NfcScannedSummary scan={mrz} />
+            <NfcScannedSummary scan={holder} />
           </View>
         </>
       ) : null}

package/src/services/deviceMetadata.ts

@@ -4,6 +4,7 @@
 // `utils/device-metadata.ts` and the Flutter SDK's `device_metadata_service.dart`.
 
 import { OS } from '../utils/platform';
+import { getStepLog } from '../lib/step-log';
 
 export const SDK_TYPE = 'react-native' as const;
 
@@ -14,7 +15,7 @@ export type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
  * Single source of truth for the SDK version — also used by `services/api.ts`
  * for the `X-SDK-Version` header. Keep in sync with `package.json`.
  */
-export const SDK_VERSION = '2.2.0';
+export const SDK_VERSION = '2.3.0';
 
 export interface ReactNativeDeviceMetadata {
   sdkType: 'react-native';
@@ -181,5 +182,12 @@ export function collectDeviceMetadata(): ReactNativeDeviceMetadata {
     meta.locale = locales[0]?.languageTag;
   }
 
+  // Step journey recorded during the session — powers the dashboard's
+  // verification timeline. See lib/step-log.
+  const stepLog = getStepLog();
+  if (stepLog) {
+    (meta as ReactNativeDeviceMetadata & { stepLog?: unknown }).stepLog = stepLog;
+  }
+
   return meta;
 }

package/src/store/derive.ts

@@ -29,6 +29,13 @@ import type { KYCStep, SupportedCountry } from '../types/config';
 import type { KycState } from './state';
 
 export function livenessEnabled(state: KycState): boolean {
+  // Presence Intelligence off ⇒ no selfie step at all. This is the builder's
+  // "Presence Intelligence step" switch (`enableSelfie`), and it outranks the
+  // liveness-gesture question below: with no selfie there is nothing to run
+  // gestures against. Checked first for that reason, and because omitting it
+  // was why turning the step off in the workflow changed nothing here while it
+  // worked on web.
+  if (state.config.enableSelfie === false) return false;
   // Consumer baseline: liveness is on unless explicitly disabled.
   if (state.config.enableLiveness === false) return false;
   const idType = state.selectedIdType;

package/src/store/kycStore.ts

@@ -27,6 +27,7 @@ import {
   type KycStore,
 } from './state';
 import { nextStepAfter, nfcDecision, previousStepBefore } from './derive';
+import { recordStep, resetStepLog } from '../lib/step-log';
 import { buildVerifyRequest } from './submit';
 import { applicantMediaCaptured, buildApplicantVerifyRequest } from './submitApplicant';
 
@@ -54,7 +55,7 @@ export function createKycStore(
   const baseUrl = resolveBaseUrl(config.apiKey, config.devUrl);
   const api = createKYCApi(baseUrl, config.apiKey);
 
-  return createStore<KycState>((set, get) => {
+  const store = createStore<KycState>((set, get) => {
     function emitStepChange(step: KYCStep): void {
       config.onStepChange?.(step);
     }
@@ -354,6 +355,11 @@ export function createKycStore(
       },
 
       reset() {
+        // Fresh step journey per session; the explicit record covers a store
+        // already sitting on 'consent' (the subscribe below only fires on
+        // change, and recordStep dedupes if it fires too).
+        resetStepLog();
+        recordStep('consent');
         set({
           currentStep: 'consent',
           selectedCountry: null,
@@ -383,6 +389,24 @@ export function createKycStore(
       },
     };
   });
+
+  // Step journey log — records every step the user reaches (the subscription
+  // catches ALL currentStep writes, whatever action made them; recordStep
+  // collapses consecutive duplicates). Rides the submission as
+  // metadata.device.stepLog for the dashboard timeline.
+  store.subscribe((s, prev) => {
+    if (s.currentStep !== prev.currentStep) recordStep(s.currentStep);
+  });
+
+  // A fresh store IS a fresh session: the runtime provider creates one per
+  // modal launch and reset() is NOT part of the open path, so the journey
+  // starts here — and the opening step must be recorded explicitly (the
+  // subscription above only fires on CHANGE, and a new store already sits on
+  // 'consent').
+  resetStepLog();
+  recordStep(store.getState().currentStep);
+
+  return store;
 }
 
 // Re-export the flow helpers for tests + screens that need to reason about

package/src/types/config.ts

@@ -61,6 +61,9 @@ export type KYCStep =
 // Client-side SDK config  (MyazaKYC.show() / useMyazaKYC options)
 // ---------------------------------------------------------------------------
 
+/** How flow progress is drawn — see {@link MyazaKYCConfig.progressStyle}. */
+export type ProgressStyle = 'steps' | 'bar';
+
 export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /**
    * Bearer token. The key prefix is the single source of truth for the
@@ -203,6 +206,20 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /** Show a light/dark mode toggle button inside the modal header. Default `true`. */
   showThemeToggle?: boolean;
 
+  /**
+   * How progress through the flow is drawn in the header.
+   *
+   *   • `'steps'` (default) — numbered circles, one per step, connected. Shows
+   *     WHICH step you are on and how many there are, and collapses to a window
+   *     when they no longer fit.
+   *   • `'bar'` — a single thin bar pinned to the bottom edge of the header.
+   *     Quieter, and unaffected by step count, so it suits long flows and hosts
+   *     who would rather the chrome said less.
+   *
+   * Both convey the same fraction; the choice is how much room it takes.
+   */
+  progressStyle?: ProgressStyle;
+
   /**
    * Hide the close (X) button and block all user-initiated dismissal of the
    * sheet — the X button, Android hardware back, and the iOS swipe-down drag.

package/src/types/workflow.ts

@@ -82,6 +82,16 @@ export interface PhoneVerificationConfig {
 export interface QuestionnaireFieldOption {
   value: string;
   label: string;
+  /**
+   * Marks a choice that is not an answer on its own — an "Other". Selecting it
+   * reveals a required free-text input, stored as the `<key>_other` companion
+   * answer (the same shape as a money field's `<key>_currency`).
+   */
+  requiresDetail?: boolean;
+  /** Label for the detail input (default "Please specify"). */
+  detailLabel?: string;
+  /** Placeholder for the detail input (default `Tell us more about "<label>"`). */
+  detailPlaceholder?: string;
 }
 
 export interface QuestionnaireField {