@myazahq/kyc-sdk-react-native 3.0.0 → 3.1.0

package/src/screens/consent/model.ts

@@ -5,6 +5,7 @@ import { fillTokens } from '../../utils/tokens';
 import { hasEmailVerificationStep, hasPhoneVerificationStep } from '../../config/contact';
 import { hasActiveQuestionnaire } from '../../config/questionnaire';
 import { hasProofOfAddressStep } from '../../config/proofOfAddress';
+import { mayAskSupportingDocuments } from '../../config/supportingDocuments';
 import { hasAddressCollectionStep } from '../../config/addressCollection';
 import {
   hasApplicantVerification,
@@ -70,11 +71,17 @@ const SCOPE_DESCRIPTIONS: Record<string, string> = {
     'We need to re-confirm the email address and phone number on your account. This takes a minute and is secure.',
 };
 
+// The address scope's bullets are NOT a fixed pair: it verifies an address by
+// the pin, by a document, or by both, so promising a map on a flow that only
+// asks for a document is a promise the flow never keeps. Gated below on the
+// same step-order predicate the flow itself walks; the document's own bullet is
+// appended by the shared post-capture block, like every other flow's.
+const ADDRESS_PIN_BULLETS: ConsentProcessStep[] = [
+  { icon: 'map-pin-house', label: 'Pin your home address on a map' },
+  { icon: 'badge-check', label: 'Confirm the details only you can know' },
+];
+
 const SCOPE_BULLETS: Record<string, ConsentProcessStep[]> = {
-  address: [
-    { icon: 'map-pin-house', label: 'Pin your home address on a map' },
-    { icon: 'badge-check', label: 'Confirm the details only you can know' },
-  ],
   'biometric-authentication': [
     { icon: 'scan-face', label: 'Take a quick selfie with liveness checks' },
     { icon: 'badge-check', label: 'We match it against your enrolled face' },
@@ -123,7 +130,11 @@ export function buildConsentModel(config: MyazaKYCConfig): ConsentModel {
     : scope
       ? // COPY the catalogue entry: pushing below would otherwise mutate the
         // shared constant, appending one more bullet per re-render.
-        [...(SCOPE_BULLETS[scope] ?? [])]
+        scope === 'address'
+          ? hasAddressCollectionStep(config.addressCollection)
+            ? [...ADDRESS_PIN_BULLETS]
+            : []
+          : [...(SCOPE_BULLETS[scope] ?? [])]
       : [
         { icon: 'badge-check', label: 'Verify your government-issued ID' },
         { icon: 'user', label: 'Collect basic personal information' },
@@ -153,6 +164,12 @@ export function buildConsentModel(config: MyazaKYCConfig): ConsentModel {
   // Post-capture features, in the order the flow runs them. Each is gated on
   // the flow that actually asks for it, and skipped where a scope's own
   // catalogue bullet already covers the same step.
+  // `mayAsk`, NOT the step-order predicate: that one resolves against the
+  // verified IDs and consent runs before an ID is picked, so every scoped
+  // document would answer "nothing to ask for" and go undisclosed.
+  if (!isBusiness && mayAskSupportingDocuments(config.supportingDocuments)) {
+    steps.push({ icon: 'file-text', label: 'Upload supporting documents' });
+  }
   if (!isBusiness && hasProofOfAddressStep(config.proofOfAddress)) {
     steps.push({ icon: 'file-text', label: 'Upload a proof of address document' });
   }

package/src/screens/liveness/CaptureRing.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useRef } from 'react';
-import Svg, { Circle } from 'react-native-svg';
+import Svg, { Circle, G } from 'react-native-svg';
 import { advanceTarget, easeToward, mixHex } from '../../lib/captureRing';
 
 // A single line traced around the camera circle's edge for the length of the
@@ -69,23 +69,37 @@ export function CaptureRing({
       style={{ position: 'absolute', top: 0, left: 0 }}
       width={size}
       height={size}
-      // Static origin, not motion: the arc starts at twelve o'clock.
-      rotation={-90}
-      originX={size / 2}
-      originY={size / 2}
     >
-      <Circle
-        ref={ref}
-        cx={size / 2}
-        cy={size / 2}
-        r={r}
-        fill="none"
-        stroke={color}
-        strokeWidth={STROKE}
-        strokeLinecap="butt"
-        strokeDasharray={[circumference]}
-        strokeDashoffset={circumference}
-      />
+      {/* Static origin, not motion: the arc starts AND closes at twelve
+          o'clock, matching Flutter's `drawArc(rect, -pi / 2, ...)`.
+
+          The rotation sits on a <G>, not on the root <Svg>. react-native-svg
+          silently drops transform props on the root: its render applies a
+          transform only `if (transform)` — a `rotation`/`originX`/`originY`
+          triple leaves that undefined, so the branch never runs — and the
+          inner group it wraps children in is built from style/fill/stroke
+          props alone, so nothing forwards them there either. `SvgProps
+          extends GProps`, so the compiler accepts it and the arc quietly
+          starts at three o'clock, which is where the web SDK's CSS
+          `-rotate-90` would have put it had CSS applied here.
+
+          It is also deliberately not on the <Circle>: that node takes a
+          setNativeProps write every frame, and the transform has no business
+          sharing a node with the animation. */}
+      <G rotation={-90} originX={size / 2} originY={size / 2}>
+        <Circle
+          ref={ref}
+          cx={size / 2}
+          cy={size / 2}
+          r={r}
+          fill="none"
+          stroke={color}
+          strokeWidth={STROKE}
+          strokeLinecap="butt"
+          strokeDasharray={[circumference]}
+          strokeDashoffset={circumference}
+        />
+      </G>
     </Svg>
   );
 }

package/src/screens/supportingDocumentParts.tsx

@@ -0,0 +1,126 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { useTheme } from '../components/runtime';
+import { MyazaText } from '../components/Typography';
+import { Icon } from '../components/Icon';
+
+// ---------------------------------------------------------------------------
+// The pieces of a supporting-document card.
+//
+// Split out of the card itself only for the file-length rule; they are that
+// card's own furniture and nothing else builds them. The Flutter SDK splits
+// the same three into supporting_document_parts.dart, for the same reason.
+// ---------------------------------------------------------------------------
+
+const MARKER = 28;
+
+/** A count while the document is outstanding, and a state anybody can read once
+ *  it is not. One document needs no number, so it wears a document glyph. */
+export function DocumentMarker({
+  done,
+  position,
+  total,
+}: {
+  done: boolean;
+  position: number;
+  total: number;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      style={{
+        width: MARKER,
+        height: MARKER,
+        borderRadius: radius.full,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: done ? colors.primary : colors.primary100,
+      }}
+    >
+      {done ? (
+        <Icon name="check" size={16} color={colors.onPrimary} />
+      ) : total > 1 ? (
+        <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '700' }}>
+          {String(position)}
+        </MyazaText>
+      ) : (
+        <Icon name="file-text" size={14} color={colors.primary} />
+      )}
+    </View>
+  );
+}
+
+/** Required or optional, in a word as well as a colour. */
+export function DocumentStatePill({ required }: { required: boolean }): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      style={{
+        paddingHorizontal: spacing.sm,
+        paddingVertical: 2,
+        borderRadius: radius.full,
+        backgroundColor: required ? colors.errorBg : colors.background,
+      }}
+    >
+      <MyazaText
+        variant="bodySmall"
+        color={required ? colors.error : colors.textSecondary}
+        style={{ fontWeight: '600' }}
+      >
+        {required ? 'Required' : 'Optional'}
+      </MyazaText>
+    </View>
+  );
+}
+
+/** What the server will take off this document, named as the author named it. */
+export function DocumentReads({ reads }: { reads: readonly string[] }): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      style={{
+        padding: spacing.sm + 4,
+        borderRadius: radius.sm,
+        backgroundColor: colors.background,
+      }}
+    >
+      <MyazaText
+        variant="bodySmall"
+        color={colors.textSecondary}
+        style={{ fontWeight: '600', letterSpacing: 0.5 }}
+      >
+        WHAT WE READ FROM IT
+      </MyazaText>
+      <View
+        style={{
+          marginTop: spacing.sm,
+          flexDirection: 'row',
+          flexWrap: 'wrap',
+          gap: spacing.xs + 2,
+        }}
+      >
+        {reads.map((read) => (
+          <View
+            key={read}
+            style={{
+              flexDirection: 'row',
+              alignItems: 'center',
+              paddingHorizontal: spacing.sm,
+              paddingVertical: 4,
+              borderRadius: radius.full,
+              borderWidth: 1,
+              borderColor: colors.border,
+              backgroundColor: colors.backgroundSecondary,
+            }}
+          >
+            <Icon name="check" size={12} color={colors.primary} />
+            <View style={{ width: 4 }} />
+            <MyazaText variant="bodySmall">{read}</MyazaText>
+          </View>
+        ))}
+      </View>
+    </View>
+  );
+}

package/src/screens/useBusinessDocumentAttach.ts

@@ -14,19 +14,30 @@ import { loadDocumentPicker } from '../services/documentPicker';
 // the refusal names the file that was chosen (images 5 MB, PDFs 15 MB).
 // ---------------------------------------------------------------------------
 
-export type AttachBusinessDocument = (
-  slot: ResolvedBusinessDocumentType,
+/**
+ * The minimum a slot must carry for this hook: it reads the label for error
+ * copy and hands the slot straight back to the caller's uploader. Generalised
+ * so the supporting-documents step shares this picker rather than owning a
+ * second copy of three file sources and their size/MIME rules.
+ */
+export interface AttachableSlot {
+  key: string;
+  label: string;
+}
+
+export type AttachBusinessDocument<S extends AttachableSlot = ResolvedBusinessDocumentType> = (
+  slot: S,
   uri: string,
   mimeType: string | undefined,
   name: string,
 ) => Promise<void>;
 
-type Pick = (slot: ResolvedBusinessDocumentType) => Promise<void>;
+type Pick<S extends AttachableSlot> = (slot: S) => Promise<void>;
 
-export function useBusinessDocumentAttach(
-  attach: AttachBusinessDocument,
+export function useBusinessDocumentAttach<S extends AttachableSlot = ResolvedBusinessDocumentType>(
+  attach: AttachBusinessDocument<S>,
   setError: (message: string) => void,
-): { takePhoto: Pick; choosePhoto: Pick; chooseFile: Pick } {
+): { takePhoto: Pick<S>; choosePhoto: Pick<S>; chooseFile: Pick<S> } {
   const tooLarge = useCallback(
     (mime: string | undefined, size: number | undefined): boolean => {
       const message = uploadSizeError(mime, size);
@@ -36,7 +47,7 @@ export function useBusinessDocumentAttach(
     [setError],
   );
 
-  const takePhoto = useCallback<Pick>(
+  const takePhoto = useCallback<Pick<S>>(
     async (slot) => {
       const permission = await ImagePicker.requestCameraPermissionsAsync();
       if (!permission.granted) {
@@ -53,7 +64,7 @@ export function useBusinessDocumentAttach(
     [attach, setError, tooLarge],
   );
 
-  const choosePhoto = useCallback<Pick>(
+  const choosePhoto = useCallback<Pick<S>>(
     async (slot) => {
       const result = await ImagePicker.launchImageLibraryAsync({ mediaTypes: ['images'], quality: 1 });
       const asset = result.canceled ? undefined : result.assets[0];
@@ -63,7 +74,7 @@ export function useBusinessDocumentAttach(
     [attach, tooLarge],
   );
 
-  const chooseFile = useCallback<Pick>(
+  const chooseFile = useCallback<Pick<S>>(
     async (slot) => {
       const picker = loadDocumentPicker();
       if (!picker) {

package/src/services/api-types.ts

@@ -24,6 +24,9 @@ export type MediaUploadType =
   // downloaded statement, and company paperwork is almost always a scan.
   | 'proof_of_address'
   | 'business_document'
+  // Artefacts held on file, named by the organisation — not the
+  // identity evidence the verification is decided on. Images + PDF.
+  | 'supporting_document'
   // Address Intelligence door / premises photo (image only).
   | 'address_photo';
 

package/src/services/deviceMetadata.ts

@@ -15,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 = '3.0.0';
+export const SDK_VERSION = '3.1.0';
 
 export interface ReactNativeDeviceMetadata {
   sdkType: 'react-native';

package/src/store/derive.ts

@@ -8,6 +8,7 @@
 // ---------------------------------------------------------------------------
 
 import { configScope } from '../lib/scope';
+import { hasSupportingDocumentsStep, verifiedIdsFor } from '../config/supportingDocuments';
 import { requiresDocumentCapture, supportsNfcChip } from '../config/idTypes';
 import {
   buildStepOrder,
@@ -83,6 +84,16 @@ export function stepOrderOptions(state: KycState): StepOrderOptions {
     hasEmailVerification: config.emailVerification?.enabled === true,
     hasPhoneVerification: config.phoneVerification?.enabled === true,
     hasPoa: hasProofOfAddressStep(config.proofOfAddress),
+    // Resolved against the ID actually picked — that is what decides whether
+    // the step has anything to ask for.
+    hasSupportingDocuments: hasSupportingDocumentsStep(
+      config.supportingDocuments,
+      verifiedIdsFor({
+        country: state.selectedCountry ?? config.country,
+        idType: state.selectedIdType,
+        multiIdSlots: state.multiIdSlots,
+      }),
+    ),
     hasAddressCollection: hasAddressCollectionStep(config.addressCollection),
     // An absent search flag means no search SCREEN, never an error: the
     // applicant places the pin by hand, the fallback every address failure

package/src/store/kycStore.ts

@@ -126,6 +126,7 @@ export function createKycStore(
       contactChallenge: null,
       business: EMPTY_BUSINESS,
       businessApplication: EMPTY_BUSINESS_APPLICATION,
+      supportingDocuments: [],
       applicantKeyPersonId: null,
       keyPeopleInvites: [],
       captureIntegrity: null,
@@ -423,6 +424,20 @@ export function createKycStore(
         }));
       },
 
+      setSupportingDocument(doc) {
+        set((s) => ({
+          // One upload per document, like the business slots: re-uploading
+          // replaces rather than appends.
+          supportingDocuments: [...s.supportingDocuments.filter((d) => d.type !== doc.type), doc],
+        }));
+      },
+
+      removeSupportingDocument(type) {
+        set((s) => ({
+          supportingDocuments: s.supportingDocuments.filter((d) => d.type !== type),
+        }));
+      },
+
       removeBusinessDocument(type) {
         set((s) => ({
           businessApplication: {

package/src/store/session.ts

@@ -90,6 +90,17 @@ export function restoreAttemptProgress(
   const s = store.getState();
   const d = (progress.data ?? {}) as Record<string, unknown>;
 
+  // Validate-and-drop: a snapshot written by an older build must degrade to
+  // restoring less, never to breaking the flow.
+  const restoredDocs = Array.isArray(d['supportingDocuments'])
+    ? (d['supportingDocuments'] as unknown[]).filter(
+        (doc): doc is { type: string; mediaId: string } =>
+          !!doc &&
+          typeof doc === 'object' &&
+          typeof (doc as { type?: unknown }).type === 'string' &&
+          typeof (doc as { mediaId?: unknown }).mediaId === 'string',
+      )
+    : null;
   const app = d['businessApplication'] as
     | (Partial<KycState['businessApplication']> & { keyPeople?: Array<Record<string, unknown>> })
     | undefined;
@@ -116,6 +127,7 @@ export function restoreAttemptProgress(
     ...(d['business'] && typeof d['business'] === 'object'
       ? { business: { ...s.business, ...(d['business'] as object) } }
       : {}),
+    ...(restoredDocs ? { supportingDocuments: restoredDocs } : {}),
     ...(app
       ? {
           businessApplication: {
@@ -180,6 +192,12 @@ export function progressFromState(s: ReturnType<KycStore['getState']>): Record<s
       idNumber: s.idNumber || undefined,
       business: s.business,
       businessApplication: s.businessApplication,
+      // The uploads without their preview names: a restored attempt shows the
+      // slot as uploaded, which is what the mediaId is for.
+      supportingDocuments:
+        s.supportingDocuments.length > 0
+          ? s.supportingDocuments.map((d) => ({ type: d.type, mediaId: d.mediaId }))
+          : undefined,
       contact: s.contact,
       questionnaireAnswers: s.questionnaireAnswers,
       address: s.address ?? undefined,

package/src/store/state.ts

@@ -402,6 +402,24 @@ export interface KycState {
   business: BusinessState;
   /** The rest of the KYB application: people, documents, applicant role. */
   businessApplication: BusinessApplicationState;
+
+  /**
+   * Supporting documents the person uploaded — artefacts the org holds on
+   * file, not the identity evidence this verification is decided on.
+   * `fileName` is display only and never rides the wire or session progress.
+   */
+  supportingDocuments: Array<{
+    type: string;
+    mediaId: string;
+    fileName?: string;
+    /**
+     * Local URI of the picked image, for the card's thumbnail. Display only,
+     * like `fileName`: it never rides the wire or session progress, so a
+     * restored attempt shows the slot uploaded without a preview.
+     */
+    previewUri?: string;
+    isPdf?: boolean;
+  }>;
   /**
    * Set by a KYB submission that requires applicant verification — the
    * KeyPerson id the applicant's own individual check links back to.
@@ -500,6 +518,14 @@ export interface KycState {
   setUboUnidentifiable: (checked: boolean) => void;
   setBusinessDocument: (doc: BusinessDocumentUpload) => void;
   removeBusinessDocument: (type: string) => void;
+  setSupportingDocument: (doc: {
+    type: string;
+    mediaId: string;
+    fileName?: string;
+    previewUri?: string;
+    isPdf?: boolean;
+  }) => void;
+  removeSupportingDocument: (type: string) => void;
   setApplicant: (role: ApplicantRole, name: string, keyPersonIndex?: number | null) => void;
   setCaptureIntegrity: (integrity: CaptureIntegrity) => void;
   setMrzScan: (scan: MrzScan) => void;

package/src/store/submit.ts

@@ -99,6 +99,17 @@ export function buildVerifyRequest(
       : state.mediaIds,
   ...(state.config.workflowId ? { workflowId: state.config.workflowId } : {}),
   ...(state.poaDocumentType ? { proofOfAddressType: state.poaDocumentType } : {}),
+  // Supporting documents — artefacts held on file. The server validates them
+  // against the resolved workflow's request list and drops anything it did
+  // not ask for. File names are display only and never ride the wire.
+  ...(state.supportingDocuments.length > 0
+    ? {
+        supportingDocuments: state.supportingDocuments.map((d) => ({
+          type: d.type,
+          mediaId: d.mediaId,
+        })),
+      }
+    : {}),
   // The smart address, when the step gathered one. Sent on individual AND
   // business submissions (a KYB flow's pin is the business premises) — the
   // server validates it against the workflow either way.

package/src/types/config.ts

@@ -22,6 +22,7 @@ import type {
   NfcConfig,
   PhoneVerificationConfig,
   ProofOfAddressConfig,
+  SupportingDocumentsConfig,
   QuestionnaireConfig,
   WorkflowCountry,
   MultiIdConfig,
@@ -57,6 +58,7 @@ export type KYCStep =
   | 'applicant-role'
   | 'liveness'
   | 'proof-of-address'
+  | 'supporting-documents'
   // The address flow, in order: find it (search) → confirm it (the PIN step,
   // which keeps the original 'address-collection' wire name so older session
   // progress restores cleanly) → show it (entrance photo) → commit it.
@@ -246,6 +248,14 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /** Proof-of-address document check, after capture. */
   proofOfAddress?: ProofOfAddressConfig;
 
+  /**
+   * Supporting documents: artefacts the org holds ON FILE, which are NOT the
+   * identity evidence the verification is decided on. The org names each one
+   * and writes the guidance under it; the result of any check never changes
+   * the verification's own status.
+   */
+  supportingDocuments?: SupportingDocumentsConfig;
+
   /** Address Intelligence: a map-pin smart address (+ optional door photo and
    *  directions), corroborated server-side. KYC AND KYB (premises pin). */
   addressCollection?: AddressCollectionConfig;

package/src/types/workflow.ts

@@ -24,6 +24,45 @@ export type PoaDocumentType =
  *  server; read here only to word the step. */
 export type PoaNameRule = 'required' | 'optional' | 'off';
 
+/**
+ * One requested supporting document. There is no catalogue: the organisation
+ * names its own, so the SDK renders the title and guidance the workflow sent.
+ */
+export interface SupportingDocumentRequest {
+  /** The organisation's own slug — the wire `type` this upload submits as. */
+  key: string;
+  /** The title the applicant reads. A document without one is not asked for. */
+  label?: string;
+  /** Guidance under the slot: which document, and what it has to show. */
+  description?: string;
+  /** Server-side only: what the document is corroborated against. */
+  checks?: Array<'id_number' | 'name'>;
+  /**
+   * The named values the server will read off it. The SDK reads the NAMES
+   * alone, to tell the applicant what the document is being taken for; the
+   * reading itself is entirely server-side.
+   */
+  fields?: Array<{ key: string; label?: string }>;
+  required?: boolean;
+  /** Which verified IDs it is asked for, as "CC/idType". Absent = every ID. */
+  idTypes?: string[];
+  /**
+   * Offer it on every flow, whatever ID was verified, so `idTypes` decides only
+   * who MUST provide it rather than who sees the slot. Absent = the scope hides
+   * it from everybody else, which is the default.
+   */
+  alwaysAsk?: boolean;
+}
+
+export interface SupportingDocumentsConfig {
+  enabled?: boolean;
+  types?: SupportingDocumentRequest[];
+  /** Server-side only. */
+  retentionDays?: number;
+  /** Server-side only. */
+  returnedData?: string[];
+}
+
 export interface ProofOfAddressConfig {
   /** Adds the Proof of Address step (after capture, before the questionnaire). */
   enabled?: boolean;