@myazahq/kyc-sdk-react-native 2.0.2 → 2.1.0

package/src/components/WorkflowGate.tsx

@@ -0,0 +1,128 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { spacing } from '../config/theme';
+import { KYCError } from '../types/verification';
+import type { MyazaKYCConfig } from '../types/config';
+import { MyazaThemeProvider, useTheme } from './theme-provider';
+import { MyazaPulseLoader } from './MyazaPulseLoader';
+import { MyazaText } from './Typography';
+import { MyazaButton } from './MyazaButton';
+import { Icon } from './Icon';
+import type { MountState, ResolvedMount } from './useWorkflowMount';
+
+export type { ResolvedMount } from './useWorkflowMount';
+
+// ---------------------------------------------------------------------------
+// What a `workflowId` mount shows once it is inside the modal.
+//
+// Resolution itself now happens BEFORE the modal is presented (see
+// `useWorkflowMount`), so in the normal case this renders `children` on the
+// first frame and no barrier is ever seen. The loader survives for the one case
+// the caller cannot pre-settle: a Retry after a failure, where the modal is
+// already on screen.
+//
+// A failure is a dead end for the flow — it does NOT fall back to the props,
+// because a workflow that cannot be loaded is not the same flow the props
+// describe, and silently running a different one is worse than not running: the
+// org configured those steps for a reason.
+//
+// Unlike the Flutter gate this one can be LEFT: the error state offers Retry
+// and Close.
+// ---------------------------------------------------------------------------
+
+export function WorkflowGate({
+  config,
+  state,
+  onRetry,
+  onClose,
+  children,
+}: {
+  config: MyazaKYCConfig;
+  state: MountState;
+  onRetry: () => void;
+  onClose: () => void;
+  children: (mount: ResolvedMount) => React.ReactElement;
+}): React.ReactElement {
+  if (state.status === 'ready') return children(state.mount);
+
+  // These render before there is a resolved config, so they carry their own
+  // theme from the props' appearance — the flow's own appearance is precisely
+  // the thing being waited on.
+  return (
+    <MyazaThemeProvider appearance={config.appearance}>
+      {state.status === 'resolving' ? (
+        <GateLoading />
+      ) : (
+        <GateError error={state.error} onRetry={onRetry} onClose={onClose} />
+      )}
+    </MyazaThemeProvider>
+  );
+}
+
+function GateLoading(): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      testID="kyc.workflow-gate.loading"
+      style={{
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: colors.background,
+        padding: spacing.xl,
+      }}
+    >
+      <MyazaPulseLoader size={64} />
+      <View style={{ height: spacing.md }} />
+      <MyazaText variant="bodySmall" color={colors.textMuted}>
+        Preparing your verification…
+      </MyazaText>
+    </View>
+  );
+}
+
+function GateError({
+  error,
+  onRetry,
+  onClose,
+}: {
+  error: KYCError;
+  onRetry: () => void;
+  onClose: () => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  // A bad key or an unpublished flow will fail identically on every attempt —
+  // offering Retry there would just invite the user to keep pressing it.
+  const retryable = error.code === 'network_error';
+  return (
+    <View
+      testID="kyc.workflow-gate.error"
+      style={{
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: colors.background,
+        padding: spacing.xl,
+      }}
+    >
+      <Icon name="alert" size={40} color={colors.error} />
+      <View style={{ height: spacing.md }} />
+      <MyazaText variant="heading3" style={{ textAlign: 'center' }}>
+        Verification unavailable
+      </MyazaText>
+      <View style={{ height: spacing.sm }} />
+      <MyazaText variant="bodySmall" color={colors.textMuted} style={{ textAlign: 'center' }}>
+        {error.message}
+      </MyazaText>
+      <View style={{ height: spacing.lg }} />
+      {retryable ? (
+        <>
+          <MyazaButton label="Try Again" onPress={onRetry} />
+          <View style={{ height: spacing.sm }} />
+        </>
+      ) : null}
+      <MyazaButton label="Close" variant="outline" onPress={onClose} />
+    </View>
+  );
+}

package/src/components/brand-font.ts

@@ -0,0 +1,113 @@
+import { useEffect, useState } from 'react';
+import * as Font from 'expo-font';
+import { BRAND_WEIGHTS, brandFamilyName } from '../config/font-resolve';
+
+export { BRAND_WEIGHTS, brandFamilyName };
+
+/**
+ * Load an org's brand font at runtime so a dashboard-picked family renders on
+ * mobile.
+ *
+ * WHY: React Native resolves `fontFamily` against families the app has
+ * REGISTERED — it never fetches. Setting `fontFamily: 'Poppins'` on a device
+ * where Poppins was never bundled silently falls back. The web SDK injects a
+ * stylesheet and Flutter has `google_fonts`; without this, RN was the one
+ * platform where a configured font quietly did nothing.
+ *
+ * ONE FILE PER WEIGHT, and that is the important part. Registering a single
+ * regular file and letting `fontWeight: '600'` ask the platform for a bolder
+ * face makes iOS SYNTHESISE the bold — it smears the glyphs wider AFTER the
+ * text has been measured, so the layout box is sized for the regular face and
+ * the rendered text overflows it. That is what truncated "Continue" to
+ * "Continu". Real weights are measured correctly, so nothing is clipped.
+ *
+ * This mirrors how the SDK's own Karla / Space Grotesk work: each weight is its
+ * own registered family and `fontWeight` is cleared at the call site.
+ *
+ * HOW: Google Fonts serves a different FORMAT per User-Agent — woff2 to
+ * browsers, TTF to anything it does not recognise. React Native's `fetch` sends
+ * no browser UA, so the request below returns TTF, the only format expo-font can
+ * load. Adding a browser-like UA here would return woff2 and break loading.
+ */
+
+/** One in-flight/settled attempt per family; the fetch is not free. */
+const attempted = new Map<string, Promise<boolean>>();
+
+async function loadGoogleFont(family: string): Promise<boolean> {
+  try {
+    const url =
+      `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family).replace(/%20/g, '+')}` +
+      `:wght@${BRAND_WEIGHTS.join(';')}&display=swap`;
+    const css = await fetch(url).then((r) => (r.ok ? r.text() : ''));
+    if (!css) return false;
+
+    // Each @font-face carries its own weight + url. Pair them in document order
+    // rather than assuming the response lists weights in the order requested.
+    const faces = css.split('@font-face');
+    const assets: Record<string, string> = {};
+    for (const face of faces) {
+      const weight = Number(/font-weight:\s*(\d+)/.exec(face)?.[1] ?? 0);
+      const src = /url\((https:\/\/[^)]+)\)/.exec(face)?.[1];
+      if (!weight || !src) continue;
+      if (!(BRAND_WEIGHTS as readonly number[]).includes(weight)) continue;
+      const name = brandFamilyName(family, weight);
+      if (!Font.isLoaded(name)) assets[name] = src;
+    }
+    // A family with no 400 face is not usable as body text.
+    if (!Font.isLoaded(family) && !assets[family]) return false;
+    if (Object.keys(assets).length > 0) await Font.loadAsync(assets);
+    return true;
+  } catch {
+    // A brand font is decoration on an identity flow — an offline device or a
+    // blocked CDN must never affect a verification.
+    return false;
+  }
+}
+
+function ensure(family: string): Promise<boolean> {
+  const existing = attempted.get(family);
+  if (existing) return existing;
+  const p = loadGoogleFont(family);
+  attempted.set(family, p);
+  return p;
+}
+
+/**
+ * Returns the families SAFE TO APPLY — i.e. actually registered right now.
+ *
+ * A name is only returned once its font exists. Applying it eagerly is what
+ * produced the silent fallback this fixes: RN needs the family to exist at the
+ * moment the style is set, so the order must be load → apply → re-render.
+ */
+export function useBrandFonts(
+  body?: string,
+  heading?: string,
+): { body?: string; heading?: string } {
+  const [ready, setReady] = useState<Record<string, boolean>>({});
+
+  useEffect(() => {
+    let cancelled = false;
+    const wanted = [body, heading].filter((f): f is string => Boolean(f && f.trim()));
+    if (wanted.length === 0) return;
+
+    for (const family of wanted) {
+      // Already bundled by the HOST APP (a self-hosted brand font) — usable
+      // immediately, no fetch.
+      if (Font.isLoaded(family)) {
+        setReady((r) => (r[family] ? r : { ...r, [family]: true }));
+        continue;
+      }
+      void ensure(family).then((ok) => {
+        if (!cancelled && ok) setReady((r) => ({ ...r, [family]: true }));
+      });
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [body, heading]);
+
+  return {
+    body: body && ready[body] ? body : undefined,
+    heading: heading && ready[heading] ? heading : undefined,
+  };
+}

package/src/components/flashHoleGeometry.ts

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// The shape of the flash's cut-out.
+//
+// Kept free of native imports so the geometry can be tested without a renderer.
+// The failure it guards against is purely visual — a wrong-shaped hole still
+// passes the liveness check, so nothing else would ever raise it.
+// ---------------------------------------------------------------------------
+
+/** The preview's position on screen, in window coordinates. */
+export interface FlashHole {
+  x: number;
+  y: number;
+  size: number;
+}
+
+/**
+ * The screen rectangle with the preview circle subtracted, as ONE path.
+ *
+ * Two subpaths, rendered with `fillRule="evenodd"` so the second is a hole
+ * rather than a second filled shape. The surround was originally four
+ * rectangles, which can only describe a rectangular gap — against a circular
+ * preview that left the corners painted over the user's face, which is the part
+ * they need to see to stay framed.
+ */
+export function holePath(width: number, height: number, hole: FlashHole): string {
+  const r = hole.size / 2;
+  const cx = hole.x + r;
+  const cy = hole.y + r;
+  // Two half-arcs rather than one: a single 360° arc has identical start and
+  // end points and renders as nothing.
+  return (
+    `M0 0 H${width} V${height} H0 Z ` +
+    `M${cx - r} ${cy} A${r} ${r} 0 1 0 ${cx + r} ${cy} A${r} ${r} 0 1 0 ${cx - r} ${cy} Z`
+  );
+}

package/src/components/flow/FatalConfigError.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../../config/theme';
+import { useTheme } from '../runtime';
+import { MyazaText } from '../Typography';
+import { MyazaButton } from '../MyazaButton';
+import { Icon } from '../Icon';
+import { KycSheet } from '../KycSheet';
+
+/**
+ * The flow cannot start — a bad API key, or a feature the org cannot use.
+ *
+ * Terminal by design: there is nothing the user can do about it and no step to
+ * fall back to, so the only action offered is Close. The consumer has already
+ * been told through `onError`; this is what the person holding the phone sees.
+ */
+export function FatalConfigError({
+  message,
+  onClose,
+}: {
+  message?: string | null;
+  onClose: () => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <KycSheet title="" onClose={onClose} hideBrand>
+      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
+        <View
+          style={{
+            width: 80,
+            height: 80,
+            borderRadius: radius.full,
+            backgroundColor: `${colors.error}1A`,
+            alignItems: 'center',
+            justifyContent: 'center',
+          }}
+        >
+          <Icon name="alert" size={40} color={colors.error} />
+        </View>
+        <View style={{ height: spacing.lg }} />
+        <MyazaText variant="heading2" style={{ textAlign: 'center' }}>
+          Unable to start verification
+        </MyazaText>
+        <View style={{ height: spacing.xs }} />
+        <MyazaText variant="bodyMedium" color={colors.textSecondary} style={{ textAlign: 'center' }}>
+          {message ?? 'Please check your API key and try again.'}
+        </MyazaText>
+        <View style={{ height: spacing.lg }} />
+        <View style={{ width: '100%' }}>
+          <MyazaButton label="Close" onPress={onClose} />
+        </View>
+      </View>
+    </KycSheet>
+  );
+}

package/src/components/fonts.ts

@@ -1,7 +1,8 @@
 import { useFonts } from 'expo-font';
 import { SpaceGrotesk_500Medium, SpaceGrotesk_600SemiBold, SpaceGrotesk_700Bold } from '@expo-google-fonts/space-grotesk';
 import { Karla_400Regular, Karla_500Medium, Karla_600SemiBold, Karla_700Bold } from '@expo-google-fonts/karla';
-import type { TextStyle } from 'react-native';
+export { fontFamilyFor, markFamilyName, brandFamilyName, BRAND_WEIGHTS } from '../config/font-resolve';
+
 
 // Typography fonts — the SAME families the Flutter SDK uses via google_fonts:
 // Space Grotesk for headings, Karla for body. Loaded at runtime through
@@ -29,21 +30,3 @@ export function useMyazaFonts(): boolean {
  * Returns `undefined` until fonts are loaded so text falls back to the system
  * font + `fontWeight` without triggering an "unrecognized font" warning.
  */
-export function fontFamilyFor(
-  isHeading: boolean,
-  weight: TextStyle['fontWeight'],
-  loaded: boolean,
-): string | undefined {
-  if (!loaded) return undefined;
-  const w = String(weight ?? '400');
-  const bold = w === '700' || w === '800' || w === '900' || w === 'bold';
-  if (isHeading) {
-    if (bold) return 'SpaceGrotesk_700Bold';
-    if (w === '500') return 'SpaceGrotesk_500Medium';
-    return 'SpaceGrotesk_600SemiBold'; // 600 default for headings
-  }
-  if (bold) return 'Karla_700Bold';
-  if (w === '600') return 'Karla_600SemiBold';
-  if (w === '500') return 'Karla_500Medium';
-  return 'Karla_400Regular';
-}

package/src/components/readyPrimerContent.ts

@@ -0,0 +1,52 @@
+import type { IconName } from './Icon';
+
+// ---------------------------------------------------------------------------
+// "Here's what happens next" copy.
+//
+// A port of the Flutter SDK's ready_primer_content.dart and the web SDK's
+// ready-primer-content.ts. Kept as data in ONE place per platform so the
+// document and liveness screens cannot drift from each other, and so the three
+// SDKs can be diffed string-for-string.
+//
+// Any change here must be mirrored in the other two — someone who starts on the
+// hosted web flow and finishes in a native app should read the same words.
+// ---------------------------------------------------------------------------
+
+export interface ReadyChecklistItem {
+  icon: IconName;
+  label: string;
+}
+
+export interface ReadyContent {
+  icon: IconName;
+  title: string;
+  body: string;
+  /** What to expect. Three at most; past that nobody reads it. */
+  checklist: ReadyChecklistItem[];
+}
+
+export const READY_DOCUMENT: ReadyContent = {
+  icon: 'scan-line',
+  title: "You're about to scan your ID",
+  body:
+    "We'll photograph your document and read it automatically. " +
+    'Nothing is shared until you submit.',
+  checklist: [
+    { icon: 'id-card', label: 'Have your physical document with you' },
+    { icon: 'sun', label: 'Find even lighting, avoid glare' },
+    { icon: 'timer', label: 'Takes about a minute' },
+  ],
+};
+
+export const READY_LIVENESS: ReadyContent = {
+  icon: 'scan-face',
+  title: "Let's confirm you're really here",
+  body:
+    "You'll follow a few short prompts on screen. This proves a real person " +
+    'is present, not a photo or a recording.',
+  checklist: [
+    { icon: 'user', label: 'Put your face in the circle' },
+    { icon: 'sun', label: 'Find even lighting, remove sunglasses' },
+    { icon: 'timer', label: 'Takes about 10 seconds' },
+  ],
+};

package/src/components/runtime.tsx

@@ -1,29 +1,25 @@
-import React, { createContext, useContext, useMemo, useRef, useState } from 'react';
+import React, { createContext, useContext, useMemo, useRef } from 'react';
 import { useStore } from 'zustand';
 
-import { createKycStore, type KycState, type KycStore } from '../store/kycStore';
-import { resolveColors, type MyazaColorScheme, type ThemeMode } from '../config/theme';
-import type { MyazaKYCConfig } from '../types/config';
-import { useMyazaFonts } from './fonts';
+import { createKycStore, effectiveCountry, type KycState, type KycStore } from '../store/kycStore';
+import type { ResolvedKYCConfig, SupportedCountry } from '../types/config';
+import type { ServerConfigState } from '../store/serverConfig';
+import { MyazaThemeProvider } from './theme-provider';
 
 // ---------------------------------------------------------------------------
-// Runtime context — owns the per-instance zustand store + theme mode. Mirrors
-// the Flutter SDK's ProviderScope + theme provider wiring.
+// Runtime context — owns the per-instance zustand store. Mirrors the Flutter
+// SDK's ProviderScope wiring.
+//
+// Theming moved to its own provider (theme-provider.tsx) because the two have
+// different lifetimes: the trigger button and the workflow-resolution barrier
+// need colours BEFORE there is a resolved config to build a store from. This
+// one composes it, so a resolved workflow's appearance takes over from the
+// props' appearance inside the flow.
 // ---------------------------------------------------------------------------
 
-interface ThemeValue {
-  mode: ThemeMode;
-  colors: MyazaColorScheme;
-  setMode: (mode: ThemeMode) => void;
-  toggle: () => void;
-  /** True once Space Grotesk + Karla are loaded (system font until then). */
-  fontsLoaded: boolean;
-}
-
 interface RuntimeValue {
   store: KycStore;
-  config: MyazaKYCConfig;
-  theme: ThemeValue;
+  config: ResolvedKYCConfig;
 }
 
 const RuntimeContext = createContext<RuntimeValue | null>(null);
@@ -38,38 +34,28 @@ function useRuntime(): RuntimeValue {
 
 export function KycRuntimeProvider({
   config,
+  serverConfig,
   children,
 }: {
-  config: MyazaKYCConfig;
+  config: ResolvedKYCConfig;
+  /** Preloaded from a resolved workflow — skips the flow's own `/config` call. */
+  serverConfig?: ServerConfigState;
   children: React.ReactNode;
 }): React.ReactElement {
   // The store is created once per provider instance (per modal launch).
   const storeRef = useRef<KycStore | null>(null);
   if (storeRef.current === null) {
-    storeRef.current = createKycStore(config);
+    storeRef.current = createKycStore(config, serverConfig);
   }
   const store = storeRef.current;
 
-  const [mode, setMode] = useState<ThemeMode>(config.appearance?.theme ?? 'light');
-  const colors = useMemo(() => resolveColors(mode, config.appearance), [mode, config.appearance]);
-  const fontsLoaded = useMyazaFonts();
+  const value = useMemo<RuntimeValue>(() => ({ store, config }), [store, config]);
 
-  const value = useMemo<RuntimeValue>(
-    () => ({
-      store,
-      config,
-      theme: {
-        mode,
-        colors,
-        setMode,
-        toggle: () => setMode((m) => (m === 'dark' ? 'light' : 'dark')),
-        fontsLoaded,
-      },
-    }),
-    [store, config, mode, colors, fontsLoaded],
+  return (
+    <RuntimeContext.Provider value={value}>
+      <MyazaThemeProvider appearance={config.appearance}>{children}</MyazaThemeProvider>
+    </RuntimeContext.Provider>
   );
-
-  return <RuntimeContext.Provider value={value}>{children}</RuntimeContext.Provider>;
 }
 
 /** Selects from the KYC store (re-renders only on selected-slice changes). */
@@ -82,12 +68,21 @@ export function useKycStore(): KycStore {
   return useRuntime().store;
 }
 
+/**
+ * The country this session is verifying against — the one picked on a
+ * multi-region flow, else the config's.
+ *
+ * Screens must use THIS, never `config.country`: on a multi-region flow the
+ * config carries only the primary, so reading it directly offers one country's
+ * IDs and validates against another's.
+ */
+export function useEffectiveCountry(): SupportedCountry {
+  return useKyc(effectiveCountry);
+}
+
 /** The resolved SDK config (props + callbacks) for this launch. */
-export function useKycConfig(): MyazaKYCConfig {
+export function useKycConfig(): ResolvedKYCConfig {
   return useRuntime().config;
 }
 
-/** Theme colors + light/dark mode controls. */
-export function useTheme(): ThemeValue {
-  return useRuntime().theme;
-}
+export { MyazaThemeProvider, useTheme, type ThemeValue } from './theme-provider';

package/src/components/stepHeaderMeta.tsx

@@ -0,0 +1,87 @@
+import { ID_TYPES } from '../config/idTypes';
+import { poaMaxAgeDays } from '../config/proofOfAddress';
+import { documentCaptureMeta } from '../screens/DocumentCaptureStep';
+import { questionnaireMeta } from '../screens/QuestionnaireStep';
+import { contactCodeLength, contactMeta, type ContactChallenge } from '../config/contact';
+
+import { proofOfAddressMeta } from '../screens/ProofOfAddressStep';
+import { countrySelectMeta } from '../screens/CountrySelectStep';
+import { businessDetailsMeta } from '../screens/BusinessDetailsStep';
+import { businessKeyPeopleMeta } from '../screens/BusinessKeyPeopleStep';
+import { businessDocumentsMeta } from '../screens/BusinessDocumentsStep';
+import { applicantRoleMeta } from '../screens/ApplicantRoleStep';
+import { nfcMeta } from '../screens/NfcStep';
+import type { DocumentCapturePhase } from '../store/state';
+import type { KYCStep, ResolvedKYCConfig, SupportedCountry } from '../types/config';
+
+// ---------------------------------------------------------------------------
+// The sheet header's title and description, per step.
+//
+// Split from KycFlow.tsx (200-line rule). Each step owns its own copy — the
+// screens export their `…Meta` — and this only chooses between them, so adding
+// a step means adding its meta beside the screen, not editing a shell.
+// ---------------------------------------------------------------------------
+
+function labelFor(country: SupportedCountry, idType: string | null): string {
+  if (!idType) return 'Document';
+  return Object.values(ID_TYPES).flat().find((t) => t.key === idType)?.label ?? 'Document';
+}
+
+export interface StepHeaderContext {
+  config: ResolvedKYCConfig;
+  country: SupportedCountry;
+  selectedIdType: string | null;
+  documentCapturePhase: DocumentCapturePhase;
+  /** Outstanding contact code — lets the header describe the OTP in flight. */
+  contactChallenge: ContactChallenge | null;
+}
+
+export function stepHeaderMeta(
+  currentStep: KYCStep,
+  { config, country, selectedIdType, documentCapturePhase, contactChallenge }: StepHeaderContext,
+): { title: string; description: string | null } {
+  const label = labelFor(country, selectedIdType);
+    switch (currentStep) {
+      case 'consent':
+        return { title: '', description: null as string | null };
+      case 'id-type':
+        return { title: 'Select ID Type', description: "Choose the type of identification document you'd like to use." };
+      case 'id-input':
+        return { title: 'Enter Your Details', description: `Provide your ${label} for verification.` };
+      case 'document-capture':
+        // Phase-aware title/description live in the header (synced from the
+        // capture screen via `documentCapturePhase`) — mirrors Flutter.
+        return documentCaptureMeta(documentCapturePhase, label);
+      case 'liveness':
+        return { title: 'Face Verification', description: 'Follow the on-screen instructions' };
+      case 'questionnaire':
+        return questionnaireMeta(config.questionnaire?.title, config.questionnaire?.description);
+      case 'email-verification':
+        return contactMeta('email', {
+          codeLength: contactCodeLength(config.emailVerification),
+          challenge: contactChallenge,
+        });
+      case 'phone-verification':
+        return contactMeta('phone', {
+          codeLength: contactCodeLength(config.phoneVerification),
+          challenge: contactChallenge,
+        });
+      case 'proof-of-address':
+        return proofOfAddressMeta(poaMaxAgeDays(config.proofOfAddress));
+      case 'country-select':
+        return countrySelectMeta;
+      case 'business-details':
+        return businessDetailsMeta;
+      case 'business-key-people':
+        return businessKeyPeopleMeta;
+      case 'business-documents':
+        return businessDocumentsMeta;
+      case 'applicant-role':
+        return applicantRoleMeta;
+      case 'nfc':
+        return nfcMeta;
+      case 'submitted':
+      default:
+        return { title: '', description: null };
+    }
+}