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

package/src/lib/biometric-auth.ts

@@ -0,0 +1,52 @@
+import { KYCApiError } from '../services/api';
+import { KYCError } from '../types/verification';
+import type { BiometricAuthResponse } from '../services/api-types-biometric';
+
+// ---------------------------------------------------------------------------
+// Biometric re-authentication — the pure half. Mirrors the web SDK's
+// MyazaBiometricAuth error mapping and outcome shapes (keep in lockstep).
+// ---------------------------------------------------------------------------
+
+export type BiometricAuthOutcome =
+  | { kind: 'success'; result: BiometricAuthResponse }
+  | { kind: 'failed'; result: BiometricAuthResponse }
+  | { kind: 'error'; message: string };
+
+export interface BiometricAuthenticated {
+  attemptId: string;
+  confidence: number | null;
+  /** Single-use proof; verify from your backend at `/biometric/verify-proof`. */
+  token?: string;
+}
+
+export interface BiometricAuthFailed {
+  status: BiometricAuthResponse['status'];
+  attemptId: string;
+  confidence: number | null;
+}
+
+/** A technical failure, in the SDK's typed vocabulary + a message a person
+ *  can read. Never the server's own wording — that is an internal contract. */
+export function mapAuthError(err: unknown): KYCError {
+  if (err instanceof KYCApiError) {
+    if (err.statusCode === 404 && err.code === 'not_enrolled') {
+      return new KYCError('unknown', "You're not set up for face verification yet.");
+    }
+    if (err.statusCode === 402) {
+      return new KYCError('insufficient_credits', 'Face verification is temporarily unavailable.');
+    }
+    if (err.statusCode === 401 || err.statusCode === 403) {
+      return new KYCError('invalid_api_key', 'This app is not authorised for face verification.');
+    }
+  }
+  return new KYCError('network_error', 'Something went wrong. Please try again.');
+}
+
+/** The verdict as the callbacks and the result screen read it. */
+export function outcomeOf(result: BiometricAuthResponse): BiometricAuthOutcome {
+  return result.authenticated ? { kind: 'success', result } : { kind: 'failed', result };
+}
+
+export function defaultReauthLabel(companyName?: string): string {
+  return companyName ? `Verify it's you with ${companyName}` : "Verify it's you";
+}

package/src/lib/biometric-copy.ts

@@ -0,0 +1,51 @@
+import { configScope } from './scope';
+import { fillTokens } from '../utils/tokens';
+import type { BiometricCopy, BiometricCopyText } from '../config/biometricOptions';
+import type { MyazaKYCConfig } from '../types/config';
+
+// ─── The org's copy on the biometric screens, ready to render ───────────────
+//
+// Pure. Resolves `config.biometric.copy` for the screens: tokens filled from
+// `userData` exactly as the consent and success copy are, a field that empties
+// out once its tokens resolve treated as absent (the default shows rather than
+// a blank title), and everything null off the biometric scopes, where the
+// block never applies. The screens hand the result to describeWaiting /
+// describeOutcome (lib/result-copy.ts) as overrides. Mirrors the web SDK's
+// lib/biometric-copy.ts and Flutter's config/biometric_copy.dart; keep the
+// three in lockstep.
+
+export interface ResolvedBiometricCopy {
+  waiting: BiometricCopyText | null;
+  verified: BiometricCopyText | null;
+  declined: BiometricCopyText | null;
+}
+
+export const NO_BIOMETRIC_COPY: ResolvedBiometricCopy = { waiting: null, verified: null, declined: null };
+
+type CopyConfigLike = {
+  scope?: string;
+  biometric?: { copy?: BiometricCopy } | null;
+  userData?: MyazaKYCConfig['userData'];
+};
+
+export function biometricCopyFor(config: CopyConfigLike): ResolvedBiometricCopy {
+  const scope = configScope(config);
+  if (scope !== 'biometric-authentication' && scope !== 'biometric-enrollment') return NO_BIOMETRIC_COPY;
+  const copy = config.biometric?.copy;
+  if (!copy) return NO_BIOMETRIC_COPY;
+  const fill = (text: BiometricCopyText | undefined): BiometricCopyText | null => {
+    if (!text) return null;
+    const title = text.title ? fillTokens(text.title, config.userData) : '';
+    const description = text.description ? fillTokens(text.description, config.userData) : '';
+    const out: BiometricCopyText = {};
+    if (title) out.title = title;
+    if (description) out.description = description;
+    return Object.keys(out).length > 0 ? out : null;
+  };
+  return {
+    waiting: fill(copy.waiting),
+    // Enrolment shows no verdict, so a stray key there has no screen to land on.
+    verified: scope === 'biometric-authentication' ? fill(copy.verified) : null,
+    declined: scope === 'biometric-authentication' ? fill(copy.declined) : null,
+  };
+}

package/src/lib/captureRing.ts

@@ -0,0 +1,83 @@
+import type { LivenessPhase } from '../liveness/types';
+
+// The liveness ring's arithmetic — a MIRROR of the web SDK's
+// components/CaptureRing.tsx and hooks/useLiveness.ts updateLivenessProgress
+// (and of the Flutter SDK's liveness/capture_ring.dart). Change a rule in one
+// and change it in all three in the same commit.
+//
+// Two numbers. The TARGET is where the test has actually got to and only ever
+// moves forward. The DISPLAY eases toward it on real elapsed time, critically
+// damped, so a gesture landing (a whole segment in one go) and the detector's
+// own frame rate both arrive as motion rather than cuts.
+
+/** Time constant of the display's approach, seconds. ~95% of a gap in three. */
+export const TAU = 0.09;
+
+/** How far a challenge segment may fill on its clock alone: time running out
+ *  is not progress, so the clock never completes a segment — the gesture
+ *  landing does. */
+export const CHALLENGE_SEGMENT_CAP = 0.85;
+
+/** The native still takes a beat after `capturing` begins; its segment fills
+ *  across this window. It never CLOSES on it: the clock is capped like a
+ *  challenge's, and only `complete` (the still in hand) reaches 1. On this
+ *  SDK the still is settle → native photo → compress, seconds on a slow
+ *  phone, and the ring used to sit closed for all of it. */
+export const CAPTURE_WINDOW_SEC = 0.4;
+
+const clamp01 = (n: number): number => (n < 0 ? 0 : n > 1 ? 1 : Number.isFinite(n) ? n : 0);
+
+export function advanceTarget(target: number, real: number): number {
+  return Math.max(target, clamp01(real));
+}
+
+export function easeToward(shown: number, target: number, dt: number): number {
+  if (dt <= 0) return shown;
+  return shown + (target - shown) * (1 - Math.exp(-dt / TAU));
+}
+
+export interface LivenessProgressInput {
+  phase: LivenessPhase;
+  /** Steps passed so far. On this SDK the count is bumped at
+   *  `challenge_passed` — read off the hook, not assumed. */
+  completedCount: number;
+  /** Every step the user performs: the gestures, plus the flash when it runs. */
+  totalCount: number;
+  /** Seconds since the current phase began. */
+  elapsedInPhase: number;
+  /** The running challenge's timeout, seconds. */
+  challengeTimeout: number;
+}
+
+/**
+ * Where the WHOLE test has got to, 0..1, in equal segments: positioning, each
+ * step, the capture. Each segment is measured by what actually gates it here —
+ * this SDK advances out of positioning the instant the face is framed and lit
+ * (no steady-frame counter), so that segment fills on the transition; a
+ * challenge fills on its clock; the capture fills across the still's window.
+ */
+export function livenessProgress(s: LivenessProgressInput): number {
+  const seg = 1 / (s.totalCount + 2);
+  const done = s.completedCount; // steps whose segments are complete
+  switch (s.phase) {
+    case 'challenge':
+    case 'flash':
+      return seg * (1 + done + Math.min(CHALLENGE_SEGMENT_CAP, s.elapsedInPhase / Math.max(s.challengeTimeout, 1)));
+    case 'challenge_passed':
+      return seg * (1 + done + 0);
+    case 'capturing':
+      return seg * (1 + s.totalCount + Math.min(CHALLENGE_SEGMENT_CAP, s.elapsedInPhase / CAPTURE_WINDOW_SEC));
+    case 'complete':
+      return 1;
+    default:
+      return 0;
+  }
+}
+
+/** Linear mix of two #rrggbb colours, for the close-to-green beat. */
+export function mixHex(a: string, b: string, t: number): string {
+  const k = clamp01(t);
+  const ch = (h: string, i: number) => parseInt(h.slice(i, i + 2), 16);
+  const out = [1, 3, 5].map((i) => Math.round(ch(a, i) + (ch(b, i) - ch(a, i)) * k));
+  return '#' + out.map((v) => v.toString(16).padStart(2, '0')).join('');
+}

package/src/lib/country-adoption.ts

@@ -0,0 +1,89 @@
+// ---------------------------------------------------------------------------
+// Declared-country adoption.
+//
+// ONE table decides when evidence about where the applicant IS may change the
+// country they are DECLARING: a reverse-geocoded pin or current-location fix
+// (a geocode), or the address they picked from search (explicit). A mirror of
+// the web SDK's steps/address/country-adoption.ts and Flutter's
+// config/country_adoption.dart; the three run the shared vectors in
+// kyc-sdk-flutter/test/country_adoption_vectors.json, so a drift in any one
+// fails there.
+//
+// The rules, and why each exists:
+//  - GEOCODED EVIDENCE outranks every GUESS. The address scope's default is
+//    the IP country, and on a dev box that once declared US while the device
+//    sat in Calabar (the search returned California), so the fix's own
+//    geocode corrects a guess the moment it resolves.
+//  - An EXPLICIT declaration is never overridden by a geocode; a PICKED
+//    address replaces even that, since the pick is the applicant's newer and
+//    more specific statement, and is then itself explicit.
+//  - Outside the address scope `selectedCountry` is the ID-VERIFICATION
+//    country, and changing it resets the ID choice, so only a guessed value
+//    is ever corrected there, picked address or not.
+//  - The org's accepted list (proofOfAddress.countries) gates every path: a
+//    value the submission gate would refuse never becomes the declaration.
+// ---------------------------------------------------------------------------
+
+const ISO2 = /^[A-Z]{2}$/;
+
+/** A trimmed, upper-cased ISO-2, or null for anything that is not one. */
+export function normaliseIso2(raw: string | null | undefined): string | null {
+  const code = raw?.trim().toUpperCase();
+  return code && ISO2.test(code) ? code : null;
+}
+
+/** Whether the org's accepted-country list admits `code`. Null or empty
+ *  accepts everyone. */
+export function countryAccepted(accepted: readonly string[] | null | undefined, code: string): boolean {
+  if (!accepted?.length) return true;
+  return accepted.some((c) => c.trim().toUpperCase() === code);
+}
+
+export interface AdoptionInput {
+  /** The country the evidence named (a geocode's `parts.country`, a pick's own). */
+  country: string | null | undefined;
+  selectedCountry: string | null | undefined;
+  countryAutoPicked: boolean;
+  /** The workflow scope; null is a full verification. */
+  scope: string | null | undefined;
+  accepted: readonly string[] | null | undefined;
+  /** The country came from an address the applicant PICKED. */
+  explicit?: boolean;
+}
+
+export interface CountryAdoption {
+  /** The normalised ISO-2 to declare. */
+  country: string;
+  /** Declare it as a GUESS (later evidence may correct it) rather than as
+   *  the applicant's own explicit statement. */
+  auto: boolean;
+}
+
+/** The adoption rule. See the file header for what each guard is for. */
+export function adoptionDecision(input: AdoptionInput): CountryAdoption | null {
+  const code = normaliseIso2(input.country);
+  if (!code) return null;
+  const onAddressScope = input.scope === 'address';
+  const guessed = input.countryAutoPicked || (onAddressScope && input.selectedCountry == null);
+  if (!guessed && !(input.explicit && onAddressScope)) return null;
+  if (code === normaliseIso2(input.selectedCountry)) return null;
+  if (!countryAccepted(input.accepted, code)) return null;
+  return { country: code, auto: !input.explicit };
+}
+
+/**
+ * The address scope's default: the visitor's IP country, once, while nothing
+ * is declared, and only when the accepted list admits it. A full flow never
+ * defaults from the IP (there the country is the ID's).
+ */
+export function geoDefaultCountry(input: {
+  geoCountry: string | null | undefined;
+  selectedCountry: string | null | undefined;
+  scope: string | null | undefined;
+  accepted: readonly string[] | null | undefined;
+}): string | null {
+  if (input.scope !== 'address' || input.selectedCountry != null) return null;
+  const code = normaliseIso2(input.geoCountry);
+  if (!code || !countryAccepted(input.accepted, code)) return null;
+  return code;
+}

package/src/lib/inferred-country.ts

@@ -0,0 +1,65 @@
+import { tryRequire } from '../services/fingerprint-sources';
+
+// ---------------------------------------------------------------------------
+// The visitor's most likely country, for DEFAULTS only (never evidence). A
+// mirror of the web SDK's lib/inferred-country.ts — keep the three in
+// lockstep.
+//
+// Two tiers: the server's IP-derived `geoCountry` when it exists, else the
+// device's own locale region (en-NG → NG). The second tier is what makes
+// inference work where the IP cannot answer at all — a dev server on a
+// loopback address, a carrier GeoLite2 cannot place — from a signal the
+// device already carries. Both are guesses a person can correct; nothing
+// recorded branches on them.
+// ---------------------------------------------------------------------------
+
+const ISO2 = /^[A-Z]{2}$/;
+
+interface LocalizationLike {
+  getLocales?: () => Array<{ regionCode?: string | null; languageTag?: string | null }>;
+}
+
+/** The region subtag of a BCP-47 tag (`en-NG`, `en_NG`, `yo-Latn-NG`). The
+ *  first subtag is the LANGUAGE ("en"), never a region, so it is skipped. */
+export function regionOfLocaleTag(tag: string | null | undefined): string | null {
+  if (!tag) return null;
+  const [, ...rest] = tag.split(/[-_]/);
+  const region = rest.find((part) => /^[A-Za-z]{2}$/.test(part))?.toUpperCase();
+  return region && ISO2.test(region) ? region : null;
+}
+
+/** The device's locale tags, best first. expo-localization when the host
+ *  installed it (it carries an explicit region), else the JS runtime's. */
+export function deviceLocaleTags(): string[] {
+  const tags: string[] = [];
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const localization = tryRequire<LocalizationLike>(() => require('expo-localization'));
+  try {
+    for (const locale of localization?.getLocales?.() ?? []) {
+      if (locale.regionCode) tags.push(`und-${locale.regionCode}`);
+      else if (locale.languageTag) tags.push(locale.languageTag);
+    }
+  } catch {
+    // A partial module; fall through to the runtime.
+  }
+  try {
+    const runtime = Intl.DateTimeFormat().resolvedOptions().locale;
+    if (runtime) tags.push(runtime);
+  } catch {
+    // No Intl on this runtime.
+  }
+  return tags;
+}
+
+export function inferredCountry(
+  geoCountry?: string | null,
+  localeTags: string[] = deviceLocaleTags(),
+): string | null {
+  const geo = geoCountry?.trim().toUpperCase();
+  if (geo && ISO2.test(geo)) return geo;
+  for (const tag of localeTags) {
+    const region = regionOfLocaleTag(tag);
+    if (region) return region;
+  }
+  return null;
+}

package/src/lib/livenessLayout.ts

@@ -0,0 +1,49 @@
+import { spacing } from '../config/theme';
+
+// ─── How big the selfie circle and the gesture avatar may be ────────────────
+//
+// The circle used to be sized from the window's WIDTH alone (capped at 300),
+// which is the web SDK's rule and is right on a tall phone. On a Samsung S24
+// (360×780 dp, 176 dp shorter than an iPhone 16 Pro Max) the width still gave
+// 296, the circle owned most of the sheet, and the avatar demonstrating the
+// gesture sat below the fold — the one thing the step exists to show. So the
+// HEIGHT bounds it too: whatever the chrome, the instruction, the step dots,
+// the avatar and the footer leave over is what the circle may take, and when
+// it is the height that bound the circle, the avatar shrinks with it.
+//
+// Mirrored in Flutter's liveness/liveness_layout.dart; the real phones below
+// are the shared vectors. Change a number in one and change both.
+
+/** The web's phone circle is 256 and its desktop one 320; 300 is where this
+ *  SDK has always capped, and the tall phones keep it. */
+export const CIRCLE_MAX = 300;
+/** A face is still usable at 200; below that the ring and the oval guide start
+ *  to crowd it, so a very short screen scrolls a little instead. */
+export const CIRCLE_MIN = 200;
+/** Everything on the sheet that is NOT the circle, measured on device:
+ *  banner + brand row + title + step bar (~250), the instruction line, the
+ *  dots, the large avatar, three gaps, the step padding and the footer. */
+export const CIRCLE_HEIGHT_BUDGET = 540;
+/** The circle keeps the step's own side padding on both sides. */
+export const CIRCLE_SIDE_GUTTER = spacing.md * 4;
+
+const clamp = (n: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, n));
+
+export interface LivenessLayout {
+  /** Diameter of the camera circle, dp. */
+  circle: number;
+  /** Diameter of the gesture avatar badge, dp. */
+  avatar: number;
+  /** The fallback icon inside the avatar when the GIF cannot load. */
+  avatarIcon: number;
+}
+
+export function livenessLayout(window: { width: number; height: number }): LivenessLayout {
+  const byWidth = window.width - CIRCLE_SIDE_GUTTER;
+  const byHeight = window.height - CIRCLE_HEIGHT_BUDGET;
+  const circle = clamp(Math.min(byWidth, byHeight, CIRCLE_MAX), CIRCLE_MIN, CIRCLE_MAX);
+  // Only a SHORT screen shrinks the avatar: a narrow one that is tall enough
+  // has the room for it whatever the width did to the circle.
+  const large = byHeight >= CIRCLE_MAX;
+  return { circle, avatar: large ? 96 : 72, avatarIcon: large ? 40 : 30 };
+}

package/src/lib/map-frame.ts

@@ -0,0 +1,159 @@
+import type { LatLng } from './map-tiles';
+
+// The framed Google-map picker's client half, for a WebView (the OkHi model):
+// the SDK loads OUR hosted /embed/map page TOP-LEVEL in a WebView and talks to
+// it over the WebView's own bridge. A mirror of the web SDK's lib/map-frame.ts
+// and the Flutter SDK's config/map_frame.dart — keep the three in lockstep.
+//
+// Message shapes (add-only; the page mirrors them):
+//   page -> app: { source: 'myaza-map', type: 'ready' | 'failed' }
+//                { source: 'myaza-map', type: 'pin', lat, lng }
+//   app -> page: window.__myazaMapCommand(JSON of
+//                { source: 'myaza-sdk', type: 'center', lat, lng, zoom? })
+
+export const MAP_FRAME_SOURCE = 'myaza-map';
+export const MAP_PARENT_SOURCE = 'myaza-sdk';
+
+/** How long to wait for `ready` before falling back to the OSM picker.
+ *  Generous: the page loads Google's script on a cold cache. */
+export const MAP_FRAME_READY_TIMEOUT_MS = 8000;
+
+export interface MapFrameOptions {
+  center: LatLng;
+  zoom: number;
+  /** Recentre-and-zoom-in when the app already holds a pin. */
+  hasPin: boolean;
+  theme?: 'light' | 'dark';
+  primaryColor?: string;
+}
+
+/** The full page URL: the server-minted frame URL (which already carries the
+ *  signed APP grant and `mode=app`) plus the render-time parameters. There is
+ *  no `origin` — an app has none, and the page proves that instead. */
+export function buildMapFrameSrc(frameUrl: string, opts: MapFrameOptions): string {
+  const url = new URL(frameUrl);
+  url.searchParams.set('lat', String(opts.center.lat));
+  url.searchParams.set('lng', String(opts.center.lng));
+  url.searchParams.set('zoom', String(opts.hasPin ? 16 : opts.zoom));
+  if (opts.theme) url.searchParams.set('theme', opts.theme);
+  if (opts.primaryColor) url.searchParams.set('primary', opts.primaryColor);
+  return url.toString();
+}
+
+export type MapFrameMessage =
+  | { type: 'ready' }
+  | { type: 'failed' }
+  | { type: 'pin'; lat: number; lng: number };
+
+const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+
+/** Validate-and-drop: the bridge delivers strings, so a JSON string is
+ *  accepted too; anything not shaped exactly like a frame message is null. */
+export function parseMapFrameMessage(data: unknown): MapFrameMessage | null {
+  let msg: unknown = data;
+  if (typeof data === 'string') {
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  if (!msg || typeof msg !== 'object') return null;
+  const m = msg as Record<string, unknown>;
+  if (m.source !== MAP_FRAME_SOURCE) return null;
+  if (m.type === 'ready') return { type: 'ready' };
+  if (m.type === 'failed') return { type: 'failed' };
+  if (m.type === 'pin' && finite(m.lat) && finite(m.lng)) {
+    if (Math.abs(m.lat) > 90 || Math.abs(m.lng) > 180) return null;
+    return { type: 'pin', lat: m.lat, lng: m.lng };
+  }
+  return null;
+}
+
+/** The recentre command as the script the WebView injects (Use my location,
+ *  restored progress). Ends in `true` because injected scripts must resolve to
+ *  something serialisable on iOS. */
+export function centerCommandScript(pin: LatLng): string {
+  const command = JSON.stringify({ source: MAP_PARENT_SOURCE, type: 'center', lat: pin.lat, lng: pin.lng, zoom: 16 });
+  return `window.__myazaMapCommand && window.__myazaMapCommand(${JSON.stringify(command)}); true;`;
+}
+
+export function samePin(a: LatLng | null, b: LatLng): boolean {
+  return !!a && Math.abs(a.lat - b.lat) < 1e-7 && Math.abs(a.lng - b.lng) < 1e-7;
+}
+
+// ── The framed STREET VIEW page (the entrance framing) ──────────────────────
+//
+// Same origin, same APP grant, sibling page: /embed/street-view lives beside
+// /embed/map and the grant unlocks the key for either, so the SDK DERIVES its
+// URL from the server-minted mapsFrameUrl by swapping the path — the two
+// pages ship together with this SDK, and the coupling is recorded on both
+// sides. The page is deliberately dumb: it renders the panorama and streams
+// the current view (`sv-pov`) over the same bridge the map uses; the framing
+// chrome, the frame-subtended fov maths and the capture decision stay in the
+// SDK, so hosted, embedded and native applicants meet the identical
+// instrument. Mirror of the web SDK's street-view half; keep in lockstep.
+//
+//   page -> app: { source: 'myaza-map', type: 'sv-ready' | 'sv-unavailable' }
+//                { source: 'myaza-map', type: 'sv-pov', panoId, heading, pitch, viewFov }
+
+/** The street-view page's URL derived from the map frame's, or null when the
+ *  frame URL is not the page family this SDK knows. */
+export function streetViewFrameUrlOf(mapsFrameUrl: string): string | null {
+  try {
+    const url = new URL(mapsFrameUrl);
+    if (!url.pathname.endsWith('/embed/map')) return null;
+    url.pathname = url.pathname.replace(/\/embed\/map$/, '/embed/street-view');
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+/** The full page URL: the derived page (carrying the signed APP grant and
+ *  `mode=app`) plus the pin the panorama should look from. No `origin`: an
+ *  app has none, and the page proves that instead. */
+export function buildStreetViewFrameSrc(
+  frameUrl: string,
+  opts: { pin: LatLng; theme?: 'light' | 'dark' },
+): string {
+  const url = new URL(frameUrl);
+  url.searchParams.set('lat', String(opts.pin.lat));
+  url.searchParams.set('lng', String(opts.pin.lng));
+  if (opts.theme) url.searchParams.set('theme', opts.theme);
+  return url.toString();
+}
+
+export type StreetViewFrameMessage =
+  | { type: 'sv-ready' }
+  | { type: 'sv-unavailable' }
+  | { type: 'sv-pov'; panoId: string; heading: number; pitch: number; viewFov: number };
+
+/** Validate-and-drop for the street-view page's messages; a JSON string is
+ *  accepted too, since the bridge delivers strings. */
+export function parseStreetViewFrameMessage(data: unknown): StreetViewFrameMessage | null {
+  let msg: unknown = data;
+  if (typeof data === 'string') {
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  if (!msg || typeof msg !== 'object') return null;
+  const m = msg as Record<string, unknown>;
+  if (m.source !== MAP_FRAME_SOURCE) return null;
+  if (m.type === 'sv-ready') return { type: 'sv-ready' };
+  if (m.type === 'sv-unavailable') return { type: 'sv-unavailable' };
+  if (
+    m.type === 'sv-pov' &&
+    typeof m.panoId === 'string' &&
+    m.panoId.length > 0 &&
+    finite(m.heading) &&
+    finite(m.pitch) &&
+    finite(m.viewFov)
+  ) {
+    return { type: 'sv-pov', panoId: m.panoId, heading: m.heading, pitch: m.pitch, viewFov: m.viewFov };
+  }
+  return null;
+}