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

package/src/services/api.ts

@@ -1,13 +1,19 @@
 import { SDK_VERSION } from './deviceMetadata';
 import type {
+  AddressReverseResult,
+  AddressSearchHit,
   BusinessRegionsResponse,
   BusinessSearchResponse,
   BusinessSelectResponse,
   ContactCheckResponse,
+  DocumentCaptureCheckRequest,
+  DocumentCaptureCheckResponse,
   NfcChallengeResponse,
   ContactSendResponse,
   HealthResponse,
   MediaUploadType,
+  PlaceSuggestion,
+  ResolvedPlace,
   SdkConfigResponse,
   SessionStartResponse,
   SessionSummaryResponse,
@@ -70,9 +76,14 @@ function uriToBlob(uri: string, mimeType: string): Promise<Blob> {
     xhr.onload = () => {
       const blob = xhr.response as Blob | null;
       if (blob) {
-        // Ensure the part carries the right content-type even if the platform
-        // didn't infer one from the URI.
-        resolve(blob.type ? blob : blob.slice(0, blob.size, mimeType));
+        // ALWAYS re-type the part, never only when the platform inferred
+        // nothing. Its guess comes from the URI's extension and describes the
+        // file we PICKED, not the one we are sending: an iPhone gallery photo
+        // arrives as HEIC, gets transcoded to JPEG on the way here, and the
+        // part still went out labelled image/heic — which the server refuses,
+        // so most camera-roll uploads failed with a message that blamed the
+        // document. `mimeType` is the normalised type the bytes actually are.
+        resolve(blob.type === mimeType ? blob : blob.slice(0, blob.size, mimeType));
       } else {
         reject(new Error(`Could not read file at ${uri}`));
       }
@@ -197,6 +208,23 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       return mediaId;
     },
 
+    /**
+     * Ask whether an uploaded document side will be readable: a face on the
+     * printed photo, a barcode that decodes. Best-effort by contract at the
+     * call site (lib/documentCaptureCheck runCaptureChecks): a failure or a
+     * timeout reads as "no problem" and never blocks the flow.
+     */
+    async checkDocumentCapture(
+      body: DocumentCaptureCheckRequest,
+      signal?: AbortSignal,
+    ): Promise<DocumentCaptureCheckResponse> {
+      return request<DocumentCaptureCheckResponse>('/document-capture/check', {
+        method: 'POST',
+        body: JSON.stringify(body),
+        ...(signal ? { signal } : {}),
+      });
+    },
+
     async verify(body: VerifyRequest): Promise<VerifyResponse> {
       return request<VerifyResponse>('/verify', {
         method: 'POST',
@@ -279,6 +307,10 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       workflowId?: string;
       /** Persistent device id — the anonymous-mount resume fallback. */
       deviceRef?: string;
+      /** The same device block the submission sends, so the dashboard's
+       *  in-progress row shows the device and SDK from the moment the SDK
+       *  loads rather than after the applicant finishes (2026-09-08). */
+      device?: Record<string, unknown>;
     }): Promise<SessionStartResponse> {
       return request<SessionStartResponse>('/session/start', {
         method: 'POST',
@@ -354,6 +386,120 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       });
     },
 
+    /**
+     * Forward address search for the address step's search box.
+     *
+     * EXPLICIT SUBMIT ONLY — never call this per keystroke. The server's map
+     * source forbids autocomplete, and the request budget has to be spent on
+     * the query the person actually meant rather than on every prefix of it.
+     */
+    async addressSearch(
+      query: string,
+      country?: string | null,
+    ): Promise<{ results: AddressSearchHit[] }> {
+      const qs = new URLSearchParams({ q: query });
+      if (country) qs.set('country', country);
+      return request<{ results: AddressSearchHit[] }>(`/address/search?${qs.toString()}`);
+    },
+
+    /**
+     * The framed Street View entrance, as an image SOURCE the review card can
+     * hand straight to <Image>.
+     *
+     * The browser key never reaches this SDK (the framed page holds it), so
+     * the picture comes through the server, which does. Returned as a URL plus
+     * the auth header rather than fetched bytes: React Native's Image carries
+     * headers itself, which keeps Blob, FileReader and base64 out of a path
+     * that only has to draw a thumbnail. Mirrors the web SDK's
+     * addressStreetViewPreview, which returns a Blob because a browser <img>
+     * cannot send an Authorization header.
+     */
+    /**
+     * The pinned location as a PICTURE, for the review card.
+     *
+     * A confirmation screen wants a photograph of the place, not a second
+     * instrument: a live map there invites a drag that goes nowhere and
+     * carries the vendor's own controls over the SDK's chrome. Same shape as
+     * the Street View source above, and the same reason for it: the key lives
+     * on the server. lib/authed-image fetches it with the header — an <Image>
+     * given `source.headers` drops them on Android.
+     */
+    staticMapSource(view: {
+      lat: number;
+      lng: number;
+      zoom?: number;
+      width?: number;
+      height?: number;
+    }): { uri: string; headers: Record<string, string> } {
+      const qs = new URLSearchParams({
+        lat: String(view.lat),
+        lng: String(view.lng),
+        zoom: String(view.zoom ?? 16),
+        width: String(Math.round(view.width ?? 640)),
+        height: String(Math.round(view.height ?? 360)),
+      });
+      return { uri: `${base}/address/static-map?${qs.toString()}`, headers };
+    },
+
+    streetViewPreviewSource(frame: {
+      panoId: string;
+      heading: number;
+      pitch: number;
+      fov: number;
+    }): { uri: string; headers: Record<string, string> } {
+      const qs = new URLSearchParams({
+        panoId: frame.panoId,
+        heading: String(frame.heading),
+        pitch: String(frame.pitch),
+        fov: String(frame.fov),
+      });
+      return {
+        uri: `${base}/address/street-view-preview?${qs.toString()}`,
+        headers,
+      };
+    },
+
+    /** The street line for a pin, for the summary card after a locate or a
+     *  drag. Display only — it never decides anything. */
+    async addressReverse(lat: number, lng: number): Promise<AddressReverseResult> {
+      const qs = new URLSearchParams({ lat: String(lat), lng: String(lng) });
+      return request<AddressReverseResult>(`/address/reverse?${qs.toString()}`);
+    },
+
+    /**
+     * Places-backed as-you-type suggestions.
+     *
+     * `session` is ONE token per typing session: it is the billing unit, so
+     * Google bills per session rather than per keystroke. Mint it when the
+     * search screen opens, reuse it for every keystroke, and mint a fresh one
+     * after a details call — that call closes the session.
+     */
+    async addressAutocomplete(
+      query: string,
+      session: string,
+      country?: string | null,
+      near?: { lat: number; lng: number } | null,
+    ): Promise<{ suggestions: PlaceSuggestion[] }> {
+      const qs = new URLSearchParams({ q: query, session });
+      if (country) qs.set('country', country);
+      // The device fix, a RANKING bias so nearby streets come first: without
+      // it "Awolowo Road" in Calabar ranks against every Awolowo Road in the
+      // country. Mirrors the web SDK's api.addressAutocomplete.
+      if (near) {
+        qs.set('lat', String(near.lat));
+        qs.set('lng', String(near.lng));
+      }
+      return request<{ suggestions: PlaceSuggestion[] }>(`/address/autocomplete?${qs.toString()}`);
+    },
+
+    /** Resolve a picked suggestion to coordinates + structured pieces. */
+    async addressPlace(placeId: string, session: string): Promise<{ place: ResolvedPlace }> {
+      const qs = new URLSearchParams({ session });
+      return request<{ place: ResolvedPlace }>(
+        `/address/place/${encodeURIComponent(placeId)}?${qs.toString()}`,
+      );
+    },
+
     async health(): Promise<HealthResponse> {
       // Public endpoint — no auth needed, but the shared headers are harmless.
       return request<HealthResponse>('/health');

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

package/src/services/location.ts

@@ -0,0 +1,234 @@
+// ---------------------------------------------------------------------------
+// One-shot geolocation for the address-collection step.
+//
+// Best-effort BY CONTRACT, mirroring the web SDK's address-helpers: a denied
+// permission, a device with location off, or a slow fix costs the `attested`
+// tier (or the recentre convenience) — never the flow. The attest fix resolves
+// to null / {} on any failure; the PIN's fix says WHY it failed, so the copy
+// can send the person to the right remedy (see lib/address-current-location).
+// ---------------------------------------------------------------------------
+
+import * as Location from 'expo-location';
+
+const FIX_TIMEOUT_MS = 8_000;
+
+/** Accuracy at which a fix is good enough to stop waiting for the GPS. */
+const PRECISE_ENOUGH_M = 25;
+const PRECISE_WINDOW_MS = 8_000;
+/**
+ * Once ANY fix exists, wait only this much longer for a better one. An indoor
+ * or wifi-derived fix never reaches 25m, and sitting out the whole window for
+ * an accuracy that is not coming reads as "it keeps loading".
+ */
+const FIRST_FIX_GRACE_MS = 3_000;
+
+export interface DeviceFix {
+  lat: number;
+  lng: number;
+  accuracy: number | null;
+  timestamp: number;
+  /** Android reports a mock-location provider; iOS has no equivalent (null). */
+  mocked: boolean | null;
+}
+
+/**
+ * Why a fix could not be taken. A refused permission, a phone that cannot
+ * place itself (location switched off, no provider), and a fix that took
+ * longer than the window are three different problems with three different
+ * remedies. Mirrors the web SDK's LocationFailure and Flutter's enum.
+ */
+export type LocationFailure = 'denied' | 'unavailable' | 'timeout' | 'unsupported';
+
+export type PreciseFixOutcome = { fix: DeviceFix } | { failure: LocationFailure };
+
+function toFix(pos: Location.LocationObject): DeviceFix {
+  return {
+    lat: pos.coords.latitude,
+    lng: pos.coords.longitude,
+    accuracy: typeof pos.coords.accuracy === 'number' ? pos.coords.accuracy : null,
+    timestamp: pos.timestamp || Date.now(),
+    mocked: typeof pos.mocked === 'boolean' ? pos.mocked : null,
+  };
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('location timeout')), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+// The most recent fix ANY read produced, kept so the confirm-time attest read
+// can fall back on it (see deviceFixFields).
+let lastGoodFix: DeviceFix | null = null;
+function remember(fix: DeviceFix): DeviceFix {
+  lastGoodFix = fix;
+  return fix;
+}
+
+/** A fix older than this no longer says where the phone is NOW. */
+export const LAST_KNOWN_MAX_AGE_MS = 10 * 60_000;
+
+/**
+ * One fix for a presence report, or null. Asks for foreground permission on
+ * first use.
+ *
+ * Resolves the way the pin step's precise read learned to, in three rungs:
+ * a fresh read at BALANCED accuracy (the fence is 250m or wider, so a 100m
+ * fix is plenty; Expo's iOS read waits for a fix that MEETS the requested
+ * accuracy, and a High request indoors never delivered one inside the
+ * window, so every RN report on the iPhone came back `no_fix` while
+ * Flutter's Geolocator, which returns the first update, reported fine,
+ * 2026-09-08), then the platform's last known position, then the last fix
+ * this module itself took (the pin step's, minutes earlier), each accepted
+ * only within LAST_KNOWN_MAX_AGE_MS. Flutter's reporter carries the same
+ * last-known fallback.
+ */
+export async function currentPosition(): Promise<DeviceFix | null> {
+  try {
+    const { status } = await Location.requestForegroundPermissionsAsync();
+    if (status !== 'granted') return null;
+  } catch {
+    return null;
+  }
+  const fresh = await withTimeout(
+    Location.getCurrentPositionAsync({ accuracy: Location.Accuracy.Balanced }),
+    FIX_TIMEOUT_MS,
+  ).then(toFix, () => null);
+  if (fresh) return remember(fresh);
+  const known = await Location.getLastKnownPositionAsync({ maxAge: LAST_KNOWN_MAX_AGE_MS }).then(
+    (pos) => (pos ? toFix(pos) : null),
+    () => null,
+  );
+  if (known) return remember(known);
+  if (lastGoodFix && Date.now() - lastGoodFix.timestamp <= LAST_KNOWN_MAX_AGE_MS) return lastGoodFix;
+  return null;
+}
+
+/**
+ * A PRECISE fix: watch the position for up to ~8s, keep the most accurate
+ * reading, and resolve early once it is within 25m.
+ *
+ * A single `getCurrentPositionAsync` routinely answers with the first coarse
+ * wifi/cell reading — hundreds of metres out, before the GPS has warmed up —
+ * which is exactly the pin landing on the wrong compound. A WATCH also never
+ * hands back a cached fix, which is the other half of what a pin needs.
+ *
+ * Never throws: every failure is CLASSIFIED, and every caller falls back to
+ * placing the pin by hand.
+ */
+export async function precisePositionOutcome(): Promise<PreciseFixOutcome> {
+  let granted = false;
+  try {
+    const { status } = await Location.requestForegroundPermissionsAsync();
+    granted = status === 'granted';
+  } catch {
+    // No location module behind the call: nothing on this device can answer.
+    return { failure: 'unsupported' };
+  }
+  if (!granted) return { failure: 'denied' };
+  try {
+    // Permission granted with the toggle OFF is the failure people hit most,
+    // and it is the one "allow location access" sends them the wrong way on.
+    if (!(await Location.hasServicesEnabledAsync())) return { failure: 'unavailable' };
+  } catch {
+    // An older module without the probe: let the watch decide.
+  }
+
+  return new Promise<PreciseFixOutcome>((resolve) => {
+    let best: Location.LocationObject | null = null;
+    let settled = false;
+    let watchFailed = false;
+    let sub: Location.LocationSubscription | null = null;
+    let grace: ReturnType<typeof setTimeout> | null = null;
+
+    const finish = (): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(windowTimer);
+      if (grace) clearTimeout(grace);
+      sub?.remove();
+      if (best) resolve({ fix: remember(toFix(best)) });
+      else resolve({ failure: watchFailed ? 'unavailable' : 'timeout' });
+    };
+
+    const windowTimer = setTimeout(finish, PRECISE_WINDOW_MS);
+
+    Location.watchPositionAsync(
+      { accuracy: Location.Accuracy.BestForNavigation, distanceInterval: 0 },
+      (pos) => {
+        const acc = pos.coords.accuracy ?? Infinity;
+        if (!best || acc < (best.coords.accuracy ?? Infinity)) best = pos;
+        if (acc <= PRECISE_ENOUGH_M) {
+          finish();
+          return;
+        }
+        if (!grace) grace = setTimeout(finish, FIRST_FIX_GRACE_MS);
+      },
+    )
+      .then((subscription) => {
+        // The window may already have elapsed while the watch was starting —
+        // hold no subscription nobody will ever remove.
+        if (settled) subscription.remove();
+        else sub = subscription;
+      })
+      .catch(() => {
+        watchFailed = true;
+        finish();
+      });
+  });
+}
+
+/**
+ * The attest-presence device fix, as the fields the verify body carries.
+ * Empty when no fix could be taken — the submission simply goes without the
+ * `attested` tier.
+ */
+/** How old a fix from earlier in the SAME address flow may be and still stand
+ *  in for the confirm-time read. Placing a pin takes a minute or two; a fix
+ *  from that window still says the device was here, and the server judges it
+ *  by its own `capturedAt` anyway. */
+export const RECENT_FIX_MAX_AGE_MS = 3 * 60_000;
+
+/** The reading the attest step should send: a fresh one when the read
+ *  answered, else the recent one the flow already took, else nothing. Pure,
+ *  so the rule is testable without a GPS. */
+export function pickDeviceFix(
+  fresh: DeviceFix | null,
+  recent: DeviceFix | null,
+  now: number = Date.now(),
+): DeviceFix | null {
+  if (fresh) return fresh;
+  if (recent && now - recent.timestamp <= RECENT_FIX_MAX_AGE_MS && recent.mocked !== true) return recent;
+  return null;
+}
+
+export async function deviceFixFields(): Promise<{
+  deviceLat?: number;
+  deviceLng?: number;
+  deviceAccuracy?: number;
+  capturedAt?: string;
+}> {
+  // A single getCurrentPositionAsync at confirm routinely times out on iOS
+  // while the GPS is still settling, and the submission then went out with
+  // no fix at all even though "Use my location" had just placed the pin on
+  // one (iPhone 16 Pro Max, 2026-09-07: every address run read "No device
+  // fix taken"). The fix the flow already holds is the fallback.
+  const fix = pickDeviceFix(await currentPosition(), lastGoodFix);
+  if (!fix) return {};
+  return {
+    deviceLat: fix.lat,
+    deviceLng: fix.lng,
+    ...(fix.accuracy != null ? { deviceAccuracy: fix.accuracy } : {}),
+    capturedAt: new Date(fix.timestamp).toISOString(),
+  };
+}

package/src/services/mediaCompress.ts

@@ -1,4 +1,3 @@
-import { Image } from 'react-native';
 import * as ImageManipulator from 'expo-image-manipulator';
 import { Video } from 'react-native-compressor';
 
@@ -41,10 +40,29 @@ export async function compressVideo(uri: string): Promise<string> {
 //   • SELFIE   — moderate: JPEG q0.8, capped to ~1280 px.
 // Runs natively via expo-image-manipulator (off the JS thread).
 
-export function imageSize(uri: string): Promise<{ width: number; height: number }> {
-  return new Promise((resolve, reject) =>
-    Image.getSize(uri, (width, height) => resolve({ width, height }), reject),
-  );
+/**
+ * The image's TRUE pixel dimensions.
+ *
+ * Measured through expo-image-manipulator — the same native module that does
+ * the cropping — because the two must agree, and they did not.
+ *
+ * This used `Image.getSize`, which on Android reports DP (pixels ÷ display
+ * density), while ImageManipulator crops in real pixels. On a density-2 phone
+ * a 3048x4064 photo measured 1524x2032, so a crop rect computed as "centred"
+ * was applied at half scale and landed in the UPPER-LEFT QUADRANT of the real
+ * image. Every Android document capture cropped the wrong region — the card
+ * the applicant framed was simply not in the stored photo. iOS was unaffected
+ * (getSize returns pixels there), which is how an iPhone-led test history
+ * never saw it. Found on a TECNO KM5 (density 320 → scale 2.0), 2026-09-20:
+ * reported 1524x2032 against a true 3048x4064, a factor of exactly 2.
+ *
+ * Correcting by `PixelRatio.get()` would also work on today's devices, but it
+ * re-states the cropper's units somewhere else and leaves the same class of
+ * bug one refactor away. Asking the cropper itself cannot drift from it.
+ */
+export async function imageSize(uri: string): Promise<{ width: number; height: number }> {
+  const ref = await ImageManipulator.ImageManipulator.manipulate(uri).renderAsync();
+  return { width: ref.width, height: ref.height };
 }
 
 /**

package/src/services/uploadErrors.ts

@@ -0,0 +1,30 @@
+import { KYCApiError } from './api';
+import { UPLOAD_HINT } from '../config/uploadLimits';
+
+// ---------------------------------------------------------------------------
+// Why an upload failed, in words the person can act on.
+//
+// Every upload used to fail as "we could not upload that document", which tells
+// the applicant nothing about whether to pick a smaller file, a different
+// format, or simply try again on better signal. The server already says which
+// it is; this reads its answer and hands back the sentence that matches.
+// ---------------------------------------------------------------------------
+
+/** The refusal, as something the applicant can do something about. */
+export function uploadFailureMessage(error: unknown): string {
+  const status = error instanceof KYCApiError ? error.statusCode : null;
+  const raw = error instanceof Error ? error.message.toLowerCase() : '';
+
+  if (status === 413 || raw.includes('too large')) {
+    return `That file is too large. ${UPLOAD_HINT}`;
+  }
+  if (raw.includes('mimetype') || raw.includes('mime type') || raw.includes('unsupported')) {
+    return `That file type is not supported. ${UPLOAD_HINT}`;
+  }
+  // A 4xx we have no better words for still says the file is the problem, so
+  // the person retries with a DIFFERENT one rather than the same one twice.
+  if (status !== null && status >= 400 && status < 500) {
+    return `We could not read that file. ${UPLOAD_HINT}`;
+  }
+  return 'We could not upload that document. Please check your connection and try again.';
+}

package/src/services/workflowGate.ts

@@ -103,6 +103,13 @@ export async function resolveWorkflow(
         idTypes: res.idTypes,
         branding: res.branding,
         geoCountry: res.geoCountry,
+        // The resolution route does not serve these yet, so a workflow mount
+        // reads undefined and the address flow offers no search screen. That
+        // degrades correctly, and the passthrough means it starts working the
+        // day the server carries them.
+        addressSearch: res.addressSearch,
+        addressSearchMode: res.addressSearchMode,
+        mapsFrameUrl: res.mapsFrameUrl ?? null,
         environment: res.environment,
         fatal: false,
       },

package/src/specs/MyazaTextRecognizer.nitro.ts

@@ -45,4 +45,33 @@ export interface MyazaTextRecognizer extends HybridObject<{ ios: 'swift'; androi
    * crop as the frame version.
    */
   recognizeTextInImage(uri: string, bottomFraction: number): Promise<TextResult>;
+
+  /**
+   * Whether the recogniser can run RIGHT NOW.
+   *
+   * Android fetches ML Kit's text model through Google Play Services rather
+   * than bundling it (see android/build.gradle), so there is a window — first
+   * launch, or a device with no GMS at all — where recognition cannot work.
+   * This MUST be checked before the camera opens: `recognizeText` can only
+   * answer in `TextResult`, where "model missing" and "no text in frame" are
+   * both an empty `lines` array, so relying on it would leave auto-capture
+   * silently never firing and the MRZ never producing a chip key, with nothing
+   * shown to explain why.
+   *
+   * iOS is always true — Apple Vision is a system framework with nothing to
+   * fetch.
+   */
+  isModelReady(): boolean;
+
+  /**
+   * Ask Play Services to download the model, resolving `true` once it is usable
+   * and `false` if it cannot be obtained (no GMS, no network, user declined).
+   *
+   * Call this EARLY — the SDK primes it at flow start, so the download overlaps
+   * the consent and ID-type screens and the model is warm by the time the
+   * document step runs.
+   *
+   * Safe to call repeatedly; resolves immediately when already ready.
+   */
+  prepareModel(): Promise<boolean>;
 }

package/src/store/address.ts

@@ -0,0 +1,97 @@
+import type { AddressState } from './state';
+
+// ---------------------------------------------------------------------------
+// Restoring a saved address pin.
+//
+// The whole address object is written into session progress verbatim, so the
+// snapshot was written by WHATEVER build saved it: coerce every field back to
+// its declared type and degrade to restoring less, never to breaking the flow.
+//
+// Deliberately does NOT restore the device fix (deviceLat / deviceLng /
+// deviceAccuracy / capturedAt). That is the attest-presence reading, and it is
+// taken fresh at confirm — a stale one would claim the applicant stood at the
+// address on a day they did not.
+//
+// Split from session.ts per the 200-line rule. A MIRROR of the web SDK's
+// RESTORE_PROGRESS address branch and the Flutter port.
+// ---------------------------------------------------------------------------
+
+function str(v: unknown): string | null {
+  return typeof v === 'string' ? v : null;
+}
+
+/** The `parts` breakdown, when the snapshot carries an object for it. */
+function restoreParts(v: unknown): Pick<AddressState, 'parts'> {
+  if (!v || typeof v !== 'object') return {};
+  const p = v as Record<string, unknown>;
+  return {
+    parts: {
+      street: str(p['street']),
+      area: str(p['area']),
+      city: str(p['city']),
+      state: str(p['state']),
+      postcode: str(p['postcode']),
+      country: str(p['country']),
+    },
+  };
+}
+
+/** The picked-label anchor, only when it is a real coordinate pair. */
+function restorePickedAt(v: unknown): Pick<AddressState, 'pickedAt'> {
+  if (!v || typeof v !== 'object') return {};
+  const p = v as Record<string, unknown>;
+  return typeof p['lat'] === 'number' && typeof p['lng'] === 'number'
+    ? { pickedAt: { lat: p['lat'], lng: p['lng'] } }
+    : {};
+}
+
+/** The Street View frame, only when every field of it survived. A partial
+ *  frame cannot be re-rendered, and half of one is not a capture. */
+function restoreStreetView(v: unknown): Pick<AddressState, 'streetView'> {
+  if (!v || typeof v !== 'object') return {};
+  const sv = v as Record<string, unknown>;
+  return typeof sv['panoId'] === 'string' &&
+    typeof sv['heading'] === 'number' &&
+    typeof sv['pitch'] === 'number' &&
+    typeof sv['fov'] === 'number'
+    ? {
+        streetView: {
+          panoId: sv['panoId'],
+          heading: sv['heading'],
+          pitch: sv['pitch'],
+          fov: sv['fov'],
+        },
+      }
+    : {};
+}
+
+/**
+ * Rebuild the address from a progress snapshot. The caller has already checked
+ * that `lat` and `lng` are numbers — without those there is no pin, and there
+ * is nothing to restore.
+ */
+export function restoreAddress(a: Record<string, unknown>): AddressState {
+  return {
+    lat: a['lat'] as number,
+    lng: a['lng'] as number,
+    accuracy: typeof a['accuracy'] === 'number' ? a['accuracy'] : null,
+    directions: typeof a['directions'] === 'string' ? a['directions'] : '',
+    propertyName: typeof a['propertyName'] === 'string' ? a['propertyName'] : '',
+    propertyNumber: typeof a['propertyNumber'] === 'string' ? a['propertyNumber'] : '',
+    // The resolved line and its breakdown survive a restart too. Dropping them
+    // is why a resumed session showed raw coordinates where the applicant had
+    // picked an address.
+    ...(typeof a['label'] === 'string' ? { label: a['label'] } : {}),
+    ...(typeof a['street'] === 'string' ? { street: a['street'] } : {}),
+    // The edit-details claims survive a restart like every other typed field.
+    ...(typeof a['unit'] === 'string' ? { unit: a['unit'] } : {}),
+    ...(typeof a['neighbourhood'] === 'string' ? { neighbourhood: a['neighbourhood'] } : {}),
+    ...(typeof a['city'] === 'string' ? { city: a['city'] } : {}),
+    ...(typeof a['state'] === 'string' ? { state: a['state'] } : {}),
+    ...(typeof a['postcode'] === 'string' ? { postcode: a['postcode'] } : {}),
+    ...(a['labelKept'] === true ? { labelKept: true } : {}),
+    ...restorePickedAt(a['pickedAt']),
+    ...restoreParts(a['parts']),
+    ...restoreStreetView(a['streetView']),
+  };
+}