@myazahq/kyc-sdk-react-native 2.4.0 → 2.6.0

package/src/presence/sampler.ts

@@ -0,0 +1,110 @@
+// ---------------------------------------------------------------------------
+// Pure state machine for the foreground-service tier. A geofence hands us
+// ENTER/EXIT moments; a periodic location sample hands us POSITIONS, and the
+// job here is to turn positions back into the same enter/exit spans the
+// geofence tier folds, on the SAME stored `enterAt`, so the two tiers
+// cooperate on one state rather than double-counting a stay:
+//
+//   inside,  no open stay  → open one (stamp enterAt)
+//   inside,  open stay     → nothing (the fence or an earlier sample did it)
+//   outside, open stay     → close it: fold the span into per-day aggregates
+//   outside, no open stay  → nothing (absence is never evidence)
+//   mocked                 → report the day FLAGGED, never open a stay
+//
+// Why this exists at all: on phones whose manufacturers kill background work
+// (the Tecno/Infinix/Xiaomi population that dominates our markets), geofence
+// transitions are dropped, silently. A foreground service keeps the process
+// alive and hands it fixes every few minutes; folding those through the same
+// span logic is what makes verification finish on those devices.
+//
+// Mirrors the Flutter plugin's PresenceSampler.kt — keep the two in lockstep.
+// ---------------------------------------------------------------------------
+
+import { foldSpanIntoDays } from './background-math';
+import { insideFence, localDayAndNight } from './math';
+import type { WireObservation } from './post';
+
+export interface SampleFix {
+  lat: number;
+  lng: number;
+  accuracy: number | null;
+  timestamp: number;
+  mocked: boolean | null;
+}
+
+export interface SamplerResult {
+  /** The open stay after these samples (null = none open). */
+  enterAt: number | null;
+  /** Per-day aggregates to queue (same-day entries already merged). */
+  observations: WireObservation[];
+}
+
+/** Merge day aggregates that landed on the same day (several spans a day):
+ *  sum dwell, OR night, sum samples. The geofence flush uses the same rule. */
+export function mergeObservations(
+  existing: WireObservation[],
+  fresh: WireObservation[],
+): WireObservation[] {
+  const byDay = new Map(existing.map((o) => [o.day, { ...o }]));
+  for (const o of fresh) {
+    const prior = byDay.get(o.day);
+    if (!prior) {
+      byDay.set(o.day, { ...o });
+      continue;
+    }
+    prior.dwellMinutes += o.dwellMinutes;
+    prior.nightPresent = prior.nightPresent || o.nightPresent;
+    prior.samples += o.samples;
+    if (o.integrity) prior.integrity = { ...prior.integrity, ...o.integrity };
+  }
+  return [...byDay.values()];
+}
+
+/**
+ * Apply a batch of fixes (any order; sorted here) to the open-stay state.
+ * `offsetMinutes` is the device's UTC offset for the fold; it defaults to the
+ * device's own, and is a parameter only so the maths is testable in any TZ.
+ */
+export function applyLocationSamples(
+  pin: { lat: number; lng: number },
+  samples: ReadonlyArray<SampleFix>,
+  enterAt: number | null,
+  offsetMinutes?: number,
+): SamplerResult {
+  let open = enterAt;
+  let observations: WireObservation[] = [];
+  const ordered = [...samples]
+    .filter((s) => Number.isFinite(s.timestamp))
+    .sort((a, b) => a.timestamp - b.timestamp);
+
+  for (const fix of ordered) {
+    if (fix.mocked === true) {
+      const { day, nightPresent } = localDayAndNight(new Date(fix.timestamp));
+      observations = mergeObservations(observations, [
+        {
+          day,
+          source: 'geofence',
+          dwellMinutes: 0,
+          nightPresent,
+          samples: 1,
+          integrity: { mockLocation: true },
+        },
+      ]);
+      continue;
+    }
+    const inside = insideFence(pin, fix);
+    if (inside) {
+      if (open == null) open = fix.timestamp;
+      continue;
+    }
+    if (open == null) continue;
+    const days = foldSpanIntoDays(open, fix.timestamp, offsetMinutes);
+    open = null;
+    if (days.length === 0) continue;
+    observations = mergeObservations(
+      observations,
+      days.map((d) => ({ ...d, source: 'geofence' as const, samples: 1 })),
+    );
+  }
+  return { enterAt: open, observations };
+}

package/src/presence/status.ts

@@ -0,0 +1,92 @@
+// ---------------------------------------------------------------------------
+// Tier visibility + recovery. A revoked permission silently downgrades the
+// presence tier, and "silently" is the defect: the host app cannot ask the
+// person to restore what it does not know is gone. presenceStatus() answers
+// "which tier is actually running for this user?", and openLocationSettings()
+// is the only honest recovery path — neither OS allows re-prompting in-app
+// after a denial, so the road back runs through Settings.
+//
+// The phone's LOCATION SERVICES toggle is checked as well as the permissions.
+// Permission granted with the toggle off produced `no_fix` on every report
+// and nothing said why; OkHi's integration guidance calls this out for the
+// same reason. It is a first-class input to the tier (tier.ts).
+// ---------------------------------------------------------------------------
+
+import { Linking, Platform } from 'react-native';
+import * as Location from 'expo-location';
+import { foregroundServiceRunning } from './foreground-service';
+import { geofenceArmed } from './geofence';
+import { loadPresencePin } from './store';
+import { resolvePresenceTier, type PermissionState, type PresenceTier } from './tier';
+
+export type { PresenceTier } from './tier';
+
+export interface PresenceStatus {
+  /** The tier that is ACTUALLY running, not the one that was asked for. */
+  tier: PresenceTier;
+  /** Whether a pin is stored for this user (without one, no tier can run). */
+  pinStored: boolean;
+  /** Whether the stored pin is the always-on arrangement. */
+  alwaysOn: boolean;
+  /** The phone's location services switch. Off, nothing can run whatever
+   *  the permissions say; `openLocationSettings('services')` is the road back. */
+  locationServicesEnabled: boolean;
+  foregroundPermission: PermissionState;
+  backgroundPermission: PermissionState;
+  /** The geofence is registered with the OS right now. */
+  geofenceArmed: boolean;
+  /** The Android foreground service is running right now (always false on iOS). */
+  foregroundServiceRunning: boolean;
+}
+
+function normalise(status: string | undefined): PermissionState {
+  if (status === 'granted') return 'granted';
+  if (status === 'denied') return 'denied';
+  return 'undetermined';
+}
+
+export async function presenceStatus(externalUserId: string): Promise<PresenceStatus> {
+  const pin = loadPresencePin(externalUserId);
+  const [fg, bg, armed, services, service] = await Promise.all([
+    Location.getForegroundPermissionsAsync().catch(() => null),
+    Location.getBackgroundPermissionsAsync().catch(() => null),
+    geofenceArmed(),
+    // An unanswerable check reads as ON: the permissions below still gate,
+    // and a false "off" would send people to Settings for nothing.
+    Location.hasServicesEnabledAsync().catch(() => true),
+    foregroundServiceRunning(),
+  ]);
+  const inputs = {
+    pinStored: pin != null,
+    locationServicesEnabled: services,
+    foregroundPermission: normalise(fg?.status),
+    backgroundPermission: normalise(bg?.status),
+    geofenceArmed: armed,
+    foregroundServiceRunning: service,
+  };
+  return {
+    tier: resolvePresenceTier(inputs),
+    alwaysOn: pin?.alwaysOn === true,
+    ...inputs,
+  };
+}
+
+/**
+ * Deep-link to Settings — the only road back after a denial or a switched-off
+ * toggle. `'app'` (default) opens the app's own settings page (permissions);
+ * `'services'` opens the phone's location-services screen on Android, which
+ * is where the toggle lives (iOS has no such deep link, so it falls back to
+ * the app page). Never throws; a host may call it straight from a button.
+ */
+export async function openLocationSettings(target: 'app' | 'services' = 'app'): Promise<void> {
+  try {
+    if (target === 'services' && Platform.OS === 'android') {
+      await Linking.sendIntent('android.settings.LOCATION_SOURCE_SETTINGS');
+      return;
+    }
+    await Linking.openSettings();
+  } catch {
+    // Nothing to do: the OS refused, and the host's copy already told the
+    // person where to go by hand.
+  }
+}

package/src/presence/store.ts

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// The on-device pin store. When a workflow enables presence verification, the
+// captured pin is saved LOCALLY (keyed by the org's user reference) so later
+// app opens can evaluate "am I at the address?" without the coordinates ever
+// leaving the phone. A small JSON file in the app's document directory via
+// expo-file-system — loaded through the SDK's optional-module pattern, so a
+// host app without the module simply has no presence tier (never a crash).
+// ---------------------------------------------------------------------------
+
+import { readJsonFile, writeJsonFile } from './fs';
+
+export interface StoredPin {
+  lat: number;
+  lng: number;
+  savedAt: string;
+  /** Always-on monitoring: the pin lives as long as the arrangement does
+   *  (cleared only by clearPresencePin — revoke or sign-out), because the
+   *  server keeps renewing the watch and reports must keep flowing. */
+  alwaysOn?: boolean;
+}
+
+const FILE_NAME = 'myaza-kyc-presence.json';
+
+/**
+ * How long a stored pin may drive reports. The watch it feeds resolves within
+ * its policy window (30 days at the longest) and the server discards reports
+ * for a resolved watch anyway — but the DEVICE kept sampling location on
+ * every app open forever, for a check that had finished. The server cannot
+ * say "stop" without breaking the ingest endpoint's enumeration safety (an
+ * unknown user and a resolved watch must answer identically), so the bound
+ * lives here: longest window plus resolution slack, then the pin self-expires
+ * and the reporter goes quiet before ever touching the GPS.
+ */
+export const PIN_TTL_DAYS = 45;
+
+export function pinExpired(pin: StoredPin, nowMs: number = Date.now()): boolean {
+  // An always-on pin has no end date by design (the OkHi model): monitoring
+  // continues until revoked, and the TTL below exists only for BOUNDED
+  // watches whose purpose has a deadline.
+  if (pin.alwaysOn === true) return false;
+  const saved = Date.parse(pin.savedAt);
+  // An unparseable stamp is treated as expired: both platforms have always
+  // written savedAt, so a missing one is corruption, and corrupt entries must
+  // age out rather than report forever.
+  if (Number.isNaN(saved)) return true;
+  // Strictly past the TTL — the Flutter mirror compares the same way.
+  return nowMs - saved > PIN_TTL_DAYS * 24 * 60 * 60 * 1000;
+}
+
+function readAll(): Record<string, StoredPin> {
+  return readJsonFile(FILE_NAME) as Record<string, StoredPin>;
+}
+
+function writeAll(pins: Record<string, StoredPin>): void {
+  writeJsonFile(FILE_NAME, pins as Record<string, unknown>);
+}
+
+/** Saves the captured pin for later foreground reports. Never throws. */
+export function savePresencePin(
+  externalUserId: string,
+  pin: { lat: number; lng: number },
+  opts?: { alwaysOn?: boolean },
+): void {
+  if (!externalUserId) return;
+  const pins = readAll();
+  pins[externalUserId] = {
+    lat: pin.lat,
+    lng: pin.lng,
+    savedAt: new Date().toISOString(),
+    ...(opts?.alwaysOn === true ? { alwaysOn: true } : {}),
+  };
+  writeAll(pins);
+}
+
+/** The stored pin for a user, or null (no store / never captured here /
+ *  aged out — an expired pin is cleared on the way through). */
+export function loadPresencePin(externalUserId: string): StoredPin | null {
+  const pin = readAll()[externalUserId];
+  if (!pin || typeof pin.lat !== 'number' || typeof pin.lng !== 'number') return null;
+  if (pinExpired(pin)) {
+    clearPresencePin(externalUserId);
+    return null;
+  }
+  return pin;
+}
+
+/** Drops a stored pin (e.g. after a watch resolves or the user signs out). */
+export function clearPresencePin(externalUserId: string): void {
+  const pins = readAll();
+  if (externalUserId in pins) {
+    delete pins[externalUserId];
+    writeAll(pins);
+  }
+}

package/src/presence/tier.ts

@@ -0,0 +1,36 @@
+// ---------------------------------------------------------------------------
+// Which presence tier is ACTUALLY running, as one pure decision — so the
+// answer presenceStatus() gives can be pinned without a device, and so the
+// Flutter mirror (presence_tier.dart) can be held to the same table.
+//
+// The location-services toggle sits ABOVE every permission: with services
+// off, a granted permission and an armed fence produce no fix and no
+// transition, so nothing is running whatever the grants say. That was the
+// silent case — permission granted, toggle off, `no_fix` forever — and it is
+// why the switch is a first-class input here rather than folded into one of
+// the permission states.
+// ---------------------------------------------------------------------------
+
+export type PresenceTier = 'background' | 'foreground' | 'none';
+
+export type PermissionState = 'granted' | 'denied' | 'undetermined';
+
+export interface TierInputs {
+  pinStored: boolean;
+  locationServicesEnabled: boolean;
+  foregroundPermission: PermissionState;
+  backgroundPermission: PermissionState;
+  /** The OS geofence is registered right now. */
+  geofenceArmed: boolean;
+  /** The Android foreground service is running right now. */
+  foregroundServiceRunning: boolean;
+}
+
+export function resolvePresenceTier(i: TierInputs): PresenceTier {
+  if (!i.pinStored || !i.locationServicesEnabled) return 'none';
+  if (i.backgroundPermission === 'granted' && (i.geofenceArmed || i.foregroundServiceRunning)) {
+    return 'background';
+  }
+  if (i.foregroundPermission === 'granted') return 'foreground';
+  return 'none';
+}

package/src/presence/watch-wait.ts

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// Waiting for the watch. The server mints an AddressWatch in the post-terminal
+// hook chain, seconds AFTER a submission is accepted, and its ingest is
+// enumeration-safe by contract: an observation for a user with no live watch
+// answers `accepted: 0` exactly as an unknown user would, and is dropped. So
+// a report made the moment onSubmit fires — the natural place for a host to
+// make one — landed on nothing (iPhone + S24, 2026-09-07: three watches in a
+// row lapsed INCONCLUSIVE with zero observations while both phones sat at the
+// pin). The reporter therefore asks where the watch stands before it posts,
+// and when the pin was captured minutes ago it WAITS for the watch to appear,
+// bounded, rather than posting into the gap. Mirrors the Flutter SDK's
+// presence_watch_wait.dart — keep the two in lockstep.
+// ---------------------------------------------------------------------------
+
+import { resolveBaseUrl } from '../services/resolveUrl';
+
+/** A pin saved this recently was captured by a flow whose watch may still be minting. */
+export const FRESH_PIN_MS = 15 * 60 * 1000;
+/** How long a submit-time report waits for its watch before giving up. */
+export const WATCH_WAIT_MS = 90 * 1000;
+export const WATCH_POLL_MS = 3 * 1000;
+
+export type WatchPresence = 'live' | 'absent' | 'unknown';
+
+export function pinIsFresh(pin: { savedAt: string }, nowMs: number = Date.now()): boolean {
+  const saved = Date.parse(pin.savedAt);
+  return !Number.isNaN(saved) && nowMs - saved <= FRESH_PIN_MS;
+}
+
+/** The server's public status for the user's watch, or null when it could not be read. */
+export async function fetchWatchStatus(
+  apiKey: string,
+  devUrl: string | undefined,
+  externalUserId: string,
+): Promise<string | null> {
+  try {
+    const base = resolveBaseUrl(apiKey, devUrl);
+    const response = await fetch(
+      `${base}/api/kyc/address/presence/${encodeURIComponent(externalUserId)}`,
+      { headers: { Authorization: `Bearer ${apiKey}` } },
+    );
+    if (!response.ok) return null;
+    const body = (await response.json()) as { status?: unknown };
+    return typeof body.status === 'string' ? body.status : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface AwaitWatchDeps {
+  fetchStatus: () => Promise<string | null>;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  waitMs?: number;
+  pollMs?: number;
+}
+
+const realSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Whether a live watch exists to receive a report. Only `in_progress` is
+ * live: a resolved cycle, or none at all, drops what is posted. An
+ * unreadable status is `unknown`, and the post goes ahead — a network doubt
+ * must not silence a report the server might accept. A FRESH pin changes the
+ * rule: its watch is probably still being minted (or the previous cycle has
+ * just lapsed and the new one is about to replace it), so the status is
+ * re-read until it turns live or the wait runs out.
+ */
+export async function awaitWatch(fresh: boolean, deps: AwaitWatchDeps): Promise<WatchPresence> {
+  const sleep = deps.sleep ?? realSleep;
+  const now = deps.now ?? Date.now;
+  const deadline = now() + (deps.waitMs ?? WATCH_WAIT_MS);
+  const pollMs = deps.pollMs ?? WATCH_POLL_MS;
+  for (;;) {
+    const status = await deps.fetchStatus();
+    if (status === 'in_progress') return 'live';
+    if (!fresh) return status === null ? 'unknown' : 'absent';
+    if (now() >= deadline) return status === null ? 'unknown' : 'absent';
+    await sleep(pollMs);
+  }
+}

package/src/screens/AddressCountryControl.tsx

@@ -0,0 +1,115 @@
+import React, { useMemo } from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { useKyc, useKycConfig, useKycStore, useTheme } from '../components/runtime';
+import { MyazaText } from '../components/Typography';
+import { CountryField } from '../components/CountryField';
+import { CountryFlag } from '../components/CountryFlag';
+import { ALL_REGION_CODES, regionCountryName } from '../config/regions';
+import { configScope } from '../lib/scope';
+import { inferredCountry } from '../lib/inferred-country';
+import type { SupportedCountry } from '../types/config';
+
+// ---------------------------------------------------------------------------
+// The declared-country control for ADDRESS-SCOPED flows — mounted on the
+// Proof of Address step (the Didit PoA model: the applicant names their
+// market, then uploads the document). Mirrors the web SDK's
+// steps/address/AddressCountryControl: the pick drives the document kinds on
+// offer, the search filter, the map's opening view, the PoA vendor market,
+// and rides the submission as the verification's country. The pin stays the
+// ground truth regardless.
+//
+// The picker is the house country sheet (CountryField) in its region-grouped
+// mode, with the inferred country (server geo first, device locale second)
+// pinned on top as "Your location" — the web's region menu, in the sheet the
+// rest of the mobile flow uses (user decision 2026-09-06).
+// ---------------------------------------------------------------------------
+
+/** What the picker offers: the org's accepted list, else every country. */
+export function poaOfferedCountries(configured: string[] | undefined): string[] {
+  const list = (configured ?? [])
+    .map((c) => c.toUpperCase())
+    .filter((c) => ALL_REGION_CODES.includes(c));
+  return list.length > 0 ? list : ALL_REGION_CODES;
+}
+
+export function AddressCountryControl(): React.ReactElement | null {
+  const config = useKycConfig();
+  const store = useKycStore();
+  const { colors } = useTheme();
+  const selected = useKyc((s) => s.selectedCountry);
+  const geo = useKyc((s) => s.serverConfig.geoCountry);
+
+  const scoped = configScope(config) === 'address';
+  const offered = useMemo(
+    () => poaOfferedCountries(config.proofOfAddress?.countries),
+    [config.proofOfAddress?.countries],
+  );
+  const options = useMemo(
+    () => offered.map((code) => ({ code, name: regionCountryName(code) })),
+    [offered],
+  );
+
+  if (!scoped) return null;
+
+  // Only a country the applicant PICKED shows as selected: the address scope
+  // has no seeded country to show (web's AddressCountryControl, same rule), and
+  // showing config.country here while the attachment area's flag read
+  // `selectedCountry` had the control and the drop zone disagreeing.
+  const value = selected ?? null;
+  const pick = (code: string) => store.getState().setCountry(code as SupportedCountry);
+
+  // One accepted country = nothing to pick. Show it as a settled fact rather
+  // than a sheet that could only ever re-answer itself.
+  if (offered.length === 1) {
+    const only = offered[0]!;
+    // The label sits ABOVE the field, as it does on every other input (user
+    // decision 2026-09-05) — the read-only box is CountryField's trigger
+    // without the chevron, so the settled and pickable states line up.
+    return (
+      <View style={{ marginBottom: spacing.lg }}>
+        <MyazaText variant="bodySmall" style={{ fontWeight: '600', marginBottom: spacing.xs }}>
+          Country
+        </MyazaText>
+        <View
+          style={{
+            flexDirection: 'row',
+            alignItems: 'center',
+            paddingHorizontal: spacing.md,
+            paddingVertical: spacing.md,
+            borderRadius: radius.sm,
+            borderWidth: 1,
+            borderColor: colors.border,
+            backgroundColor: colors.backgroundSecondary,
+          }}
+        >
+          <CountryFlag country={only} size={20} />
+          <View style={{ width: spacing.sm }} />
+          <MyazaText variant="body" style={{ flex: 1 }} numberOfLines={1}>
+            {regionCountryName(only)}
+          </MyazaText>
+        </View>
+      </View>
+    );
+  }
+
+  return (
+    <View style={{ marginBottom: spacing.lg }}>
+      <MyazaText variant="bodySmall" style={{ fontWeight: '600', marginBottom: spacing.xs }}>
+        Country
+      </MyazaText>
+      <CountryField
+        value={value}
+        options={options}
+        onChange={pick}
+        // The inferred country pinned on top of the sheet; the sheet itself
+        // drops it when the org's list does not carry it.
+        geoCountry={inferredCountry(geo)}
+        grouped
+        placeholder="Select country"
+        searchPlaceholder="Search countries"
+      />
+    </View>
+  );
+}

package/src/screens/ApplicantRoleStep.tsx

@@ -50,11 +50,13 @@ export function ApplicantRoleStep(): React.ReactElement {
   const { colors } = useTheme();
   const stored = useKyc((s) => s.businessApplication);
 
-  // The valid entered people, keeping their ORIGINAL index — the payload flag
-  // is index-based, so the list and the submission can never disagree.
+  // The valid entered PEOPLE, keeping their ORIGINAL index — the payload flag
+  // is index-based, so the list and the submission can never disagree. A
+  // corporate shareholder is excluded: "which of these is you?" is a question
+  // about humans, and a company can never be the person filling in the form.
   const people = stored.keyPeople
     .map((row, index) => ({ row, index }))
-    .filter(({ row }) => isKeyPersonRowValid(row));
+    .filter(({ row }) => !row.isCorporate && isKeyPersonRowValid(row));
   const hasPeople = people.length > 0;
 
   const propName = [config.userData?.firstName, config.userData?.lastName]
@@ -63,13 +65,15 @@ export function ApplicantRoleStep(): React.ReactElement {
 
   // Tri-state: a person's index, 'other', or nothing chosen yet. First arrival
   // pre-selects the applicant's own entry when the userData name matches
-  // (they still confirm) — a stored choice always wins.
+  // (they still confirm) — and when the name matches NOBODY listed, "I'm not
+  // one of these people" is what that fact means, so it is pre-selected
+  // instead (mirrors the web SDK). A stored choice always wins.
   const [selection, setSelection] = useState<number | 'other' | null>(() => {
     if (stored.applicantKeyPersonIndex !== null) return stored.applicantKeyPersonIndex;
     if (stored.applicantRole) return 'other';
     if (propName) {
       const match = people.find(({ row }) => namesLooselyMatch(propName, row.name));
-      if (match) return match.index;
+      return match ? match.index : people.length > 0 ? 'other' : null;
     }
     return null;
   });

package/src/screens/BusinessCheckPanel.tsx

@@ -0,0 +1,89 @@
+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 { MyazaAlert } from '../components/MyazaAlert';
+import type { BusinessCheckState } from '../store/state';
+
+// ---------------------------------------------------------------------------
+// What the register said, when it was NOT a plain yes.
+//
+// The check is a paid, deliberate step, so it is shown rather than run
+// invisibly: the applicant sees a company that is not on the register caught
+// HERE instead of after documents and a selfie. Nothing is shown for a company
+// that WAS found — the register's answer is already in the form the applicant
+// is looking at, editable, and its officers are the next step. Mirrors the web
+// SDK's BusinessCheckPanel.
+// ---------------------------------------------------------------------------
+
+export function BusinessCheckPanel({
+  check,
+}: {
+  check: BusinessCheckState;
+}): React.ReactElement | null {
+  // `skipped` shows nothing on purpose. The organisation could not be charged,
+  // which is not the applicant's problem and not something they can act on;
+  // the check simply happens at submission instead. `checking` shows nothing
+  // either — the loader lives inside the Continue button they just pressed.
+  if (
+    check.status === 'idle' ||
+    check.status === 'skipped' ||
+    check.status === 'found' ||
+    check.status === 'checking'
+  ) {
+    return null;
+  }
+
+  if (check.status === 'not_found') {
+    return (
+      <MyazaAlert
+        variant="warning"
+        title="We could not find this business on the register"
+        message="Check the registration number and try again."
+      />
+    );
+  }
+
+  if (check.status === 'limit_reached') {
+    // Not a failure: the submission still runs its own check. What it says is
+    // "stop re-picking and look at the number", which is the only thing left
+    // that helps.
+    return (
+      <NeutralPanel
+        title="We have stopped looking this up for now"
+        body="This application has searched the register several times. Check the registration number is right; your details will still be verified when you submit."
+      />
+    );
+  }
+
+  // unavailable — deliberately not "we could not find it": an outage is not
+  // evidence that a business is unregistered.
+  return (
+    <NeutralPanel
+      title="The register is temporarily unavailable"
+      body="You can continue, and we will check it shortly."
+    />
+  );
+}
+
+function NeutralPanel({ title, body }: { title: string; body: string }): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      style={{
+        borderWidth: 1,
+        borderColor: colors.border,
+        borderRadius: radius.sm,
+        backgroundColor: colors.backgroundSecondary,
+        padding: spacing.md,
+      }}
+    >
+      <MyazaText variant="label">{title}</MyazaText>
+      <MyazaText variant="bodySmall" color={colors.textSecondary} style={{ marginTop: 2 }}>
+        {body}
+      </MyazaText>
+    </View>
+  );
+}