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

package/src/screens/ProofOfAddressStep.tsx

@@ -0,0 +1,238 @@
+import React, { useCallback, useState } from 'react';
+import { ActivityIndicator, Image, Pressable, View } from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { useKyc, useKycConfig, useKycStore, useTheme } from '../components/runtime';
+import { MyazaText } from '../components/Typography';
+import { MyazaButton } from '../components/MyazaButton';
+import { Icon } from '../components/Icon';
+import { MediaSourceSheet } from '../components/MediaSourceSheet';
+import { MyazaSelect } from '../components/MyazaSelect';
+import { withRetry } from '../services/retry';
+import { compressDocumentImage } from '../services/mediaCompress';
+import { poaDocumentTypes, poaMaxAgeDays, poaTypeLabel } from '../config/proofOfAddress';
+import { usePoaAttach, type PoaPick } from './usePoaAttach';
+import type { PoaDocumentType } from '../types/workflow';
+
+// ---------------------------------------------------------------------------
+// Proof of Address — pick the kind of document, then supply it.
+//
+// Mirrors the web SDK: a DASHED drop zone that NAMES the document being asked
+// for ("Upload your utility bill") plus what's accepted, replaced after upload
+// by a row showing the file, its kind, and an X to remove it. A generic "choose
+// a file" hid which of the offered document kinds the user had to supply.
+//
+// The check itself is soft — the server reads the document and reports a
+// verdict, but never fails the verification over it — so nothing here blocks
+// beyond making sure a file was actually attached.
+// ---------------------------------------------------------------------------
+
+export function proofOfAddressMeta(maxAgeDays: number): { title: string; description: string } {
+  return {
+    title: 'Proof of address',
+    description: `Upload a document that shows your name and home address, issued within the last ${maxAgeDays} days.`,
+  };
+}
+
+export function ProofOfAddressStep(): React.ReactElement {
+  const config = useKycConfig();
+  const store = useKycStore();
+  const { colors } = useTheme();
+  const mediaId = useKyc((s) => s.mediaIds.proofOfAddress);
+  const fileName = useKyc((s) => s.poaFileName);
+  const storedType = useKyc((s) => s.poaDocumentType);
+
+  const types = poaDocumentTypes(config.proofOfAddress);
+  const [selectedType, setSelectedType] = useState<PoaDocumentType>(storedType ?? types[0]!);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // The picked file, kept for the thumbnail — the only way a user catches
+  // "wrong photo from the camera roll" before submitting.
+  const [preview, setPreview] = useState<{ uri: string; isPdf: boolean } | null>(null);
+
+  const typeLabel = poaTypeLabel(selectedType, config.proofOfAddress);
+
+  const upload = useCallback(
+    async ({ uri, mimeType, name }: PoaPick) => {
+      setBusy(true);
+      setError(null);
+      const isPdf = (mimeType ?? '').toLowerCase().startsWith('application/pdf');
+      setPreview({ uri, isPdf });
+      try {
+        // Photos are compressed like any other capture; a PDF is passed through
+        // untouched — re-encoding it would destroy the text the server reads.
+        const finalUri = isPdf ? uri : await compressDocumentImage(uri).catch(() => uri);
+        const id = await withRetry(() =>
+          store.getState().api.upload({ uri: finalUri, type: mimeType, name }, 'proof_of_address'),
+        );
+        store.getState().setProofOfAddress(id, selectedType, name);
+      } catch {
+        setPreview(null);
+        setError('We could not upload that document. Please try again.');
+      } finally {
+        setBusy(false);
+      }
+    },
+    [selectedType, store],
+  );
+
+  const { pick, sheetOpen, closeSheet, choosePhoto, takePhoto, chooseFile } = usePoaAttach(
+    upload,
+    setError,
+  );
+
+  const remove = useCallback(() => {
+    setPreview(null);
+    setError(null);
+    store.getState().clearProofOfAddress();
+  }, [store]);
+
+  const uploaded = Boolean(mediaId) && !busy;
+
+  return (
+    <View>
+      <MediaSourceSheet
+        open={sheetOpen}
+        onClose={closeSheet}
+        title="Upload your document"
+        options={[
+          {
+            icon: 'image',
+            label: 'Photo library',
+            caption: 'Pick a photo you already have',
+            onPress: () => void choosePhoto(),
+          },
+          {
+            icon: 'camera',
+            label: 'Take a photo',
+            caption: 'Photograph the document now',
+            onPress: () => void takePhoto(),
+          },
+          {
+            icon: 'file-text',
+            label: 'Choose a file',
+            caption: 'A PDF or image from your files',
+            onPress: () => void chooseFile(),
+          },
+        ]}
+      />
+      {types.length > 1 ? (
+        <>
+          <MyazaText variant="bodySmall" style={{ fontWeight: '600', marginBottom: spacing.xs }}>
+            Document type
+          </MyazaText>
+          <MyazaSelect<PoaDocumentType>
+            value={selectedType}
+            sheetTitle="Document type"
+            // Locked once a file is attached: switching the kind afterwards
+            // would mislabel the document already uploaded.
+            enabled={!uploaded && !busy}
+            options={types.map((type) => ({
+              value: type,
+              label: poaTypeLabel(type, config.proofOfAddress),
+            }))}
+            onChange={setSelectedType}
+          />
+          <View style={{ height: spacing.lg }} />
+        </>
+      ) : null}
+
+      {uploaded ? (
+        <View
+          style={{
+            flexDirection: 'row',
+            alignItems: 'center',
+            padding: spacing.md,
+            borderRadius: radius.md,
+            borderWidth: 1,
+            borderColor: colors.border,
+            backgroundColor: colors.backgroundSecondary,
+          }}
+        >
+          {preview && !preview.isPdf ? (
+            <Image
+              source={{ uri: preview.uri }}
+              style={{ width: 48, height: 48, borderRadius: radius.sm }}
+              resizeMode="cover"
+            />
+          ) : (
+            <View
+              style={{
+                width: 48,
+                height: 48,
+                borderRadius: radius.sm,
+                borderWidth: 1,
+                borderColor: colors.border,
+                alignItems: 'center',
+                justifyContent: 'center',
+              }}
+            >
+              <Icon name="file-text" size={22} color={colors.primary} />
+            </View>
+          )}
+          <View style={{ width: spacing.md, flexShrink: 0 }} />
+          <View style={{ flex: 1, minWidth: 0 }}>
+            <MyazaText variant="bodySmall" style={{ fontWeight: '600' }} numberOfLines={1}>
+              {fileName ?? 'Document uploaded'}
+            </MyazaText>
+            <MyazaText variant="bodySmall" color={colors.textSecondary} numberOfLines={1}>
+              {typeLabel}
+            </MyazaText>
+          </View>
+          <Pressable
+            onPress={remove}
+            accessibilityRole="button"
+            accessibilityLabel="Remove document"
+            hitSlop={8}
+          >
+            <Icon name="x" size={18} color={colors.textSecondary} />
+          </Pressable>
+        </View>
+      ) : (
+        <Pressable
+          onPress={() => {
+            if (!busy) void pick();
+          }}
+          accessibilityRole="button"
+          accessibilityLabel={`Upload your ${typeLabel.toLowerCase()}`}
+          style={{
+            alignItems: 'center',
+            justifyContent: 'center',
+            paddingVertical: spacing.xl,
+            paddingHorizontal: spacing.lg,
+            borderRadius: radius.md,
+            borderWidth: 1.5,
+            borderStyle: 'dashed',
+            borderColor: colors.border,
+          }}
+        >
+          {busy ? (
+            <ActivityIndicator size="small" color={colors.primary} />
+          ) : (
+            <Icon name="upload" size={30} color={colors.textSecondary} />
+          )}
+          <View style={{ height: spacing.sm }} />
+          <MyazaText variant="bodySmall" style={{ fontWeight: '600' }}>
+            {busy ? 'Uploading…' : `Upload your ${typeLabel.toLowerCase()}`}
+          </MyazaText>
+          <MyazaText variant="bodySmall" color={colors.textSecondary}>
+            Photo or PDF, up to 20MB
+          </MyazaText>
+        </Pressable>
+      )}
+
+      {error ? (
+        <MyazaText variant="bodySmall" color={colors.error} style={{ marginTop: spacing.sm }}>
+          {error}
+        </MyazaText>
+      ) : null}
+
+      <View style={{ height: spacing.lg }} />
+      <MyazaButton
+        label="Continue"
+        disabled={!mediaId || busy}
+        onPress={() => store.getState().nextStep()}
+      />
+    </View>
+  );
+}

package/src/screens/QuestionnaireField.tsx

@@ -0,0 +1,219 @@
+import React from 'react';
+import { Pressable, View } from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { useTheme } from '../components/runtime';
+import { MyazaText } from '../components/Typography';
+import { MyazaDateField } from '../components/MyazaDateField';
+import { MyazaInput } from '../components/MyazaInput';
+import { MyazaSelect } from '../components/MyazaSelect';
+import { OptionRow } from '../components/OptionRow';
+import { MoneyField as QuestionnaireMoneyField } from './QuestionnaireMoneyField';
+import { currencyKeyFor } from '../config/questionnaire';
+import type { QuestionnaireAnswerValue, QuestionnaireField as FieldDef } from '../types/workflow';
+
+// ---------------------------------------------------------------------------
+// One questionnaire question.
+//
+// Mirrors the Flutter SDK field-for-field, because a questionnaire is authored
+// once and rendered on every platform — a question that looks like a different
+// control per platform reads as a different question:
+//
+//   label        the question, with a RED * when required (not "(optional)" on
+//                the ones that aren't — most questions are required, so marking
+//                the exception is quieter than marking the rule)
+//   select       a select field that opens a sheet
+//   multiselect  tappable cards with square checks (the choices are the point)
+//   boolean      two centred Yes / No cards
+//   money        amount + currency on ONE row
+//   text/number  a plain input
+// ---------------------------------------------------------------------------
+
+export function QuestionnaireFieldView({
+  field,
+  value,
+  currencyValue,
+  error,
+  onChange,
+  onCurrencyChange,
+}: {
+  field: FieldDef;
+  value: QuestionnaireAnswerValue | undefined;
+  /** money only: the `<key>_currency` companion answer. */
+  currencyValue?: string;
+  error?: string;
+  onChange: (value: QuestionnaireAnswerValue | undefined) => void;
+  onCurrencyChange: (currency: string) => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+
+  const isPlainInput = field.type === 'text' || field.type === 'number';
+
+  return (
+    <View style={{ marginBottom: spacing.lg }}>
+      <FieldLabel
+        text={field.label}
+        required={field.required === true}
+        helpText={
+          field.helpText ??
+          (field.type === 'multiselect' ? 'Choose all that apply.' : undefined)
+        }
+      />
+
+      {isPlainInput ? (
+        <MyazaInput
+          value={value === undefined ? '' : String(value)}
+          onChangeText={(text) => onChange(text === '' ? undefined : text)}
+          placeholder={field.placeholder}
+          error={error ?? null}
+          keyboardType={field.type === 'number' ? 'numeric' : 'default'}
+          autoCapitalize="none"
+        />
+      ) : null}
+
+      {field.type === 'date' ? (
+        // A real calendar, not a "type YYYY-MM-DD" text box — same picker
+        // contract as the Flutter SDK's _DateField / showMyazaDatePicker.
+        <MyazaDateField
+          value={typeof value === 'string' ? value : undefined}
+          onChange={(iso) => onChange(iso)}
+          placeholder={field.placeholder}
+          error={error ?? null}
+        />
+      ) : null}
+
+      {field.type === 'money' ? (
+        <QuestionnaireMoneyField
+          field={field}
+          value={value}
+          currencyValue={currencyValue}
+          error={error}
+          onChange={onChange}
+          onCurrencyChange={onCurrencyChange}
+        />
+      ) : null}
+
+      {field.type === 'boolean' ? (
+        <View style={{ flexDirection: 'row', gap: spacing.sm }}>
+          {[true, false].map((option) => (
+            <View key={String(option)} style={{ flex: 1 }}>
+              <BooleanChoice
+                label={option ? 'Yes' : 'No'}
+                selected={value === option}
+                // Re-tapping the chosen answer clears it — the only way to
+                // un-answer an optional yes/no.
+                onPress={() => onChange(value === option ? undefined : option)}
+              />
+            </View>
+          ))}
+        </View>
+      ) : null}
+
+      {field.type === 'select' ? (
+        <MyazaSelect<string>
+          value={typeof value === 'string' ? value : null}
+          hint={field.placeholder ?? 'Select an option'}
+          sheetTitle={field.label}
+          options={(field.options ?? []).map((option) => ({
+            value: option.value,
+            label: option.label,
+          }))}
+          onChange={(next) => onChange(next)}
+        />
+      ) : null}
+
+      {field.type === 'multiselect'
+        ? (field.options ?? []).map((option) => {
+            const selected = Array.isArray(value) && value.includes(option.value);
+            return (
+              <OptionRow
+                key={option.value}
+                label={option.label}
+                selected={selected}
+                multi
+                onPress={() => {
+                  const current = Array.isArray(value) ? value : [];
+                  const next = selected
+                    ? current.filter((v) => v !== option.value)
+                    : [...current, option.value];
+                  onChange(next.length > 0 ? next : undefined);
+                }}
+              />
+            );
+          })
+        : 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 }}>
+          {error}
+        </MyazaText>
+      ) : null}
+    </View>
+  );
+}
+
+/** A centred Yes / No card — no radio mark; the label IS the choice. */
+function BooleanChoice({
+  label,
+  selected,
+  onPress,
+}: {
+  label: string;
+  selected: boolean;
+  onPress: () => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <Pressable
+      onPress={onPress}
+      accessibilityRole="radio"
+      accessibilityState={{ checked: selected }}
+      accessibilityLabel={label}
+      style={{
+        height: 48,
+        alignItems: 'center',
+        justifyContent: 'center',
+        borderRadius: radius.md,
+        borderWidth: selected ? 1.5 : 1,
+        borderColor: selected ? colors.primary : colors.border,
+        backgroundColor: selected ? colors.primary50 : 'transparent',
+      }}
+    >
+      <MyazaText
+        variant="body"
+        color={selected ? colors.primary : undefined}
+        style={{ fontWeight: '600' }}
+      >
+        {label}
+      </MyazaText>
+    </Pressable>
+  );
+}
+
+function FieldLabel({
+  text,
+  required,
+  helpText,
+}: {
+  text: string;
+  required: boolean;
+  helpText?: string;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View style={{ marginBottom: spacing.xs }}>
+      <MyazaText variant="body" style={{ fontWeight: '600' }}>
+        {text}
+        {required ? <MyazaText color={colors.error}> *</MyazaText> : null}
+      </MyazaText>
+      {helpText ? (
+        <MyazaText variant="bodySmall" color={colors.textSecondary}>
+          {helpText}
+        </MyazaText>
+      ) : null}
+    </View>
+  );
+}
+
+export { currencyKeyFor };

package/src/screens/QuestionnaireMoneyField.tsx

@@ -0,0 +1,134 @@
+import React, { useState } from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { useTheme } from '../components/runtime';
+import { MyazaText } from '../components/Typography';
+import { MyazaInput } from '../components/MyazaInput';
+import { MyazaSelect } from '../components/MyazaSelect';
+import { CountryFlag } from '../components/CountryFlag';
+import { currencyFlagCountry, currencyName } from '../config/currencyFlags';
+import { formatGroupedAmount, parseGroupedAmount } from '../utils/amountFormat';
+import type { QuestionnaireAnswerValue, QuestionnaireField as FieldDef } from '../types/workflow';
+
+// ---------------------------------------------------------------------------
+// A money question: an amount plus the currency it is in.
+//
+// Two answer keys, not one — `<key>` and `<key>_currency`. Keeping them as
+// separate scalars is what lets a decision graph compare the amount with `gt`
+// and `lt`; a `{amount, currency}` object would not compare at all.
+//
+// Laid out as ONE row — amount, then the currency beside it — mirroring the
+// Flutter SDK. Currencies stacked below the field read as a second question
+// rather than a unit attached to the number above them.
+// ---------------------------------------------------------------------------
+
+/** Matches MyazaInput's single-line height so the two controls line up. */
+const CONTROL_HEIGHT = 48;
+
+/** Flag for a currency code — blank for supranational codes (XOF, XAU…). */
+function CurrencyFlag({ code }: { code: string }): React.ReactElement | null {
+  const country = currencyFlagCountry(code);
+  if (!country) return null;
+  return <CountryFlag country={country} size={18} />;
+}
+
+export function MoneyField({
+  field,
+  value,
+  currencyValue,
+  error,
+  onChange,
+  onCurrencyChange,
+}: {
+  field: FieldDef;
+  value: QuestionnaireAnswerValue | undefined;
+  currencyValue?: string;
+  error?: string;
+  onChange: (value: QuestionnaireAnswerValue | undefined) => void;
+  onCurrencyChange: (currency: string) => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const currencies = field.currencies ?? [];
+  // The showing currency is the answer when the user never opens the picker,
+  // which is why the payload defaults to the definition's first.
+  const currency = currencyValue ?? currencies[0];
+
+  // The field shows a GROUPED string while the answer stays a number. Seeded
+  // once from any previously entered answer (returning to the step via back),
+  // then owned by the input — same as Flutter's controller.
+  const [display, setDisplay] = useState(() =>
+    value === undefined ? '' : formatGroupedAmount(String(value)),
+  );
+
+  const onAmountText = (text: string): void => {
+    const grouped = formatGroupedAmount(text);
+    setDisplay(grouped);
+    const amount = parseGroupedAmount(grouped);
+    onChange(amount === null ? undefined : amount);
+  };
+
+  return (
+    // Currency FIRST, then the amount — it reads as a unit prefix
+    // ("NGN 250,000"), the way a currency is actually written.
+    // TOP-aligned, not centered: the amount column grows taller when its
+    // validation error renders under it, and centering would drag the
+    // currency select down out of line with the input box. Both controls are
+    // CONTROL_HEIGHT tall, so top alignment keeps them level always.
+    <View style={{ flexDirection: 'row', alignItems: 'flex-start' }}>
+      {currencies.length > 1 ? (
+        <>
+          {/* Height is pinned so the select matches MyazaInput's single-line
+              box exactly; without it the select renders short and the two
+              controls sit at different heights. */}
+          <View style={{ height: CONTROL_HEIGHT }}>
+            <MyazaSelect<string>
+              value={currency}
+              sheetTitle="Currency"
+              height={CONTROL_HEIGHT}
+              compact
+              options={currencies.map((code) => ({
+                value: code,
+                label: code,
+                description: currencyName(code) ?? undefined,
+                leading: <CurrencyFlag code={code} />,
+              }))}
+              onChange={onCurrencyChange}
+            />
+          </View>
+          <View style={{ width: spacing.sm }} />
+        </>
+      ) : currency ? (
+        <>
+          <View
+            style={{
+              height: CONTROL_HEIGHT,
+              flexDirection: 'row',
+              alignItems: 'center',
+              paddingHorizontal: spacing.md,
+              borderRadius: radius.sm,
+              backgroundColor: colors.primary50,
+            }}
+          >
+            <CurrencyFlag code={currency} />
+            <View style={{ width: spacing.xs }} />
+            <MyazaText variant="body" style={{ fontWeight: '600' }}>
+              {currency}
+            </MyazaText>
+          </View>
+          <View style={{ width: spacing.sm }} />
+        </>
+      ) : null}
+
+      <View style={{ flex: 1 }}>
+        <MyazaInput
+          value={display}
+          onChangeText={onAmountText}
+          placeholder={field.placeholder ?? '0.00'}
+          error={error ?? null}
+          keyboardType="decimal-pad"
+        />
+      </View>
+    </View>
+  );
+}

package/src/screens/QuestionnaireStep.tsx

@@ -0,0 +1,76 @@
+import React, { useState } from 'react';
+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 { QuestionnaireFieldView } from './QuestionnaireField';
+import type { QuestionnaireAnswerValue } from '../types/workflow';
+
+// ---------------------------------------------------------------------------
+// Extra-info questionnaire — compliance declarations asked after capture and
+// just before submission.
+//
+// Questions come from the workflow; answers ride the /verify submission and are
+// re-validated server-side against the PUBLISHED definition, so what happens
+// here is purely about telling the user before they spend a round trip.
+//
+// The step's title/description live in the sheet header (KycFlow reads them),
+// matching every other step.
+// ---------------------------------------------------------------------------
+
+/** Header title/description for the questionnaire step. Used by KycFlow. */
+export function questionnaireMeta(
+  title: string | undefined,
+  description: string | undefined,
+): { title: string; description: string } {
+  return {
+    title: title ?? 'A few more questions',
+    description:
+      description ??
+      'This information is required for compliance and helps keep your account safe.',
+  };
+}
+
+export function QuestionnaireStep(): React.ReactElement {
+  const config = useKycConfig();
+  const store = useKycStore();
+  const answers = useKyc((s) => s.questionnaireAnswers);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const fields = config.questionnaire?.fields ?? [];
+
+  const setAnswer = (key: string, value: QuestionnaireAnswerValue | undefined): void => {
+    store.getState().setQuestionnaireAnswer(key, value);
+    // Clear this field's error as soon as it is touched — leaving it up while
+    // the user is fixing it reads as though the fix didn't take.
+    setErrors((prev) => (prev[key] ? { ...prev, [key]: '' } : prev));
+  };
+
+  const handleContinue = (): void => {
+    const nextErrors = validateQuestionnaire(fields, answers);
+    setErrors(nextErrors);
+    if (Object.keys(nextErrors).length > 0) return;
+    store.getState().nextStep();
+  };
+
+  return (
+    <View>
+      {fields.map((field) => (
+        <QuestionnaireFieldView
+          key={field.key}
+          field={field}
+          value={answers[field.key]}
+          currencyValue={answers[currencyKeyFor(field)] as string | undefined}
+          error={errors[field.key] || undefined}
+          onChange={(value) => setAnswer(field.key, value)}
+          onCurrencyChange={(currency) => setAnswer(currencyKeyFor(field), currency)}
+        />
+      ))}
+
+      <View style={{ height: spacing.sm }} />
+      <MyazaButton label="Continue" onPress={handleContinue} />
+    </View>
+  );
+}

package/src/screens/SubmittedStep.tsx

@@ -11,6 +11,7 @@ import { MyazaAlert } from '../components/MyazaAlert';
 import { MyazaPulseLoader } from '../components/MyazaPulseLoader';
 import { Icon } from '../components/Icon';
 import { fillTokens } from '../utils/tokens';
+import { KeyPeopleInviteLinks } from './KeyPeopleInviteLinks';
 
 // Terminal screen — 1:1 with the Flutter SDK's SubmittedScreen. Calls
 // submitAsync on mount; renders submitting / success / error views with the same
@@ -135,6 +136,9 @@ export function SubmittedStep({ onClose }: { onClose: () => void }): React.React
   const description = config.success?.description
     ? fillTokens(config.success.description, config.userData)
     : DEFAULT_SUCCESS_DESCRIPTION;
+  // KYB: per-person verification links for full-KYC key people — rendered so
+  // the applicant can send each one immediately.
+  const invites = store.getState().keyPeopleInvites; // set before phase flips to success
 
   return (
     <View style={{ flex: 1, justifyContent: 'space-between' }}>
@@ -151,6 +155,7 @@ export function SubmittedStep({ onClose }: { onClose: () => void }): React.React
         <MyazaText variant="bodyMedium" style={{ textAlign: 'center' }}>
           {description}
         </MyazaText>
+        <KeyPeopleInviteLinks invites={invites} />
       </View>
       <MyazaButton label="Done" onPress={onClose} />
     </View>