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

package/src/presence/background.ts

@@ -0,0 +1,165 @@
+// ---------------------------------------------------------------------------
+// The BACKGROUND presence tier — the OkHi model (user decision 2026-08-31):
+// one consent, then the OS wakes this SDK on geofence transitions and
+// residency keeps being confirmed with nobody in the loop, until revoked.
+//
+// Mechanics: `registerBackgroundPresence()` MUST run at app-root module scope
+// (Expo requires the task defined before the app registers; a task defined
+// inside a component never fires headlessly). `enableBackgroundPresence()`
+// then asks for the "allow all the time" permission and arms a 250m geofence
+// on the stored pin. ENTER stamps a timestamp; EXIT folds the span into
+// per-day aggregates (background-math.ts) and flushes them. Only the derived
+// day records ever leave the device — same contract as the foreground tier.
+//
+// The Android foreground-service tier (foreground-service.ts) rides the same
+// registration call and the same stored enterAt, so the two never
+// double-count a stay; see sampler.ts for the cooperation rule.
+//
+// expo-task-manager is an OPTIONAL module (the expo-file-system pattern): a
+// host without it simply has no background tier, never a crash. It is listed
+// as an optional peer, not a dependency — the host opts into the native
+// surface by installing it.
+// ---------------------------------------------------------------------------
+
+import * as Location from 'expo-location';
+import { foldSpanIntoDays } from './background-math';
+import { defineLocationTask } from './foreground-service';
+import { PRESENCE_GEOFENCE_TASK, armGeofence } from './geofence';
+import { postObservations } from './post';
+import { mergeObservations } from './sampler';
+import { loadPresencePin } from './store';
+import {
+  loadEnterAt,
+  loadReporterConfig,
+  pendingObservations,
+  queueObservations,
+  replacePending,
+  saveEnterAt,
+  saveReporterConfig,
+} from './background-store';
+
+// Kept exported from here for hosts (and status.ts) that imported it before
+// the primitive moved to geofence.ts.
+export { PRESENCE_GEOFENCE_TASK };
+
+interface TaskManagerLike {
+  defineTask(name: string, fn: (body: { data: unknown; error: unknown }) => void): void;
+  isTaskRegisteredAsync(name: string): Promise<boolean>;
+}
+
+function taskManager(): TaskManagerLike | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require('expo-task-manager') as Partial<TaskManagerLike>;
+    return typeof mod?.defineTask === 'function' ? (mod as TaskManagerLike) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function flushQueue(externalUserId: string): Promise<void> {
+  const cfg = loadReporterConfig(externalUserId);
+  if (!cfg) return;
+  const pending = pendingObservations(externalUserId);
+  if (pending.length === 0) return;
+  const ok = await postObservations(cfg.apiKey, cfg.devUrl, externalUserId, pending);
+  // The server ingest is idempotent per (watch, day, source) and MERGES, so a
+  // flush that half-landed is safe to retry whole next time.
+  if (ok) replacePending(externalUserId, []);
+}
+
+/**
+ * Define the background tasks (the geofence task AND the foreground-service
+ * location task). Call ONCE from the host app's root module (e.g. index.js),
+ * before the component tree mounts. Returns false when the optional
+ * expo-task-manager module is absent.
+ */
+export function registerBackgroundPresence(): boolean {
+  const tm = taskManager();
+  if (!tm) return false;
+  tm.defineTask(PRESENCE_GEOFENCE_TASK, (body) => {
+    if (body.error) return;
+    const data = body.data as
+      | { eventType?: number; region?: { identifier?: string } }
+      | undefined;
+    const userId = data?.region?.identifier;
+    if (!userId) return;
+    // expo-location: GeofencingEventType.Enter = 1, Exit = 2.
+    if (data?.eventType === 1) {
+      // A stay the foreground-service sampler already opened stays open;
+      // re-stamping would shorten it.
+      if (loadEnterAt(userId) == null) saveEnterAt(userId, Date.now());
+      return;
+    }
+    if (data?.eventType === 2) {
+      const enteredAt = loadEnterAt(userId);
+      saveEnterAt(userId, null);
+      if (enteredAt == null) return;
+      const days = foldSpanIntoDays(enteredAt, Date.now());
+      if (days.length === 0) return;
+      queueObservations(
+        userId,
+        days.map((d) => ({ ...d, source: 'geofence' as const, samples: 1 })),
+        mergeObservations,
+      );
+      void flushQueue(userId);
+    }
+  });
+  defineLocationTask(tm);
+  return true;
+}
+
+export interface EnableBackgroundResult {
+  enabled: boolean;
+  reason:
+    | 'enabled'
+    | 'module_missing'
+    | 'no_pin'
+    | 'foreground_denied'
+    | 'background_denied'
+    | 'start_failed';
+}
+
+/**
+ * Arm the geofence on the stored pin. Asks for foreground THEN background
+ * permission (the order the OSes require); a refusal leaves the foreground
+ * tier working exactly as before — the tiers degrade, never break.
+ */
+export async function enableBackgroundPresence(options: {
+  apiKey: string;
+  externalUserId: string;
+  devUrl?: string;
+}): Promise<EnableBackgroundResult> {
+  const tm = taskManager();
+  if (!tm) return { enabled: false, reason: 'module_missing' };
+  const pin = loadPresencePin(options.externalUserId);
+  if (!pin) return { enabled: false, reason: 'no_pin' };
+
+  const fg = await Location.requestForegroundPermissionsAsync().catch(() => null);
+  if (fg?.status !== 'granted') return { enabled: false, reason: 'foreground_denied' };
+  const bg = await Location.requestBackgroundPermissionsAsync().catch(() => null);
+  if (bg?.status !== 'granted') return { enabled: false, reason: 'background_denied' };
+
+  // The task handler runs with no React context, so the wire config it needs
+  // to flush is persisted beside the pin. The key is publishable by design.
+  saveReporterConfig(options.externalUserId, {
+    apiKey: options.apiKey,
+    ...(options.devUrl ? { devUrl: options.devUrl } : {}),
+  });
+
+  try {
+    await armGeofence(options.externalUserId, pin);
+    return { enabled: true, reason: 'enabled' };
+  } catch {
+    return { enabled: false, reason: 'start_failed' };
+  }
+}
+
+/** Disarm the geofence. Never throws; a host may call it defensively. */
+export async function disableBackgroundPresence(): Promise<void> {
+  try {
+    await Location.stopGeofencingAsync(PRESENCE_GEOFENCE_TASK);
+  } catch {
+    // Not armed, or the module is absent — either way, disarmed.
+  }
+}

package/src/presence/foreground-service.ts

@@ -0,0 +1,193 @@
+// ---------------------------------------------------------------------------
+// The Android FOREGROUND SERVICE tier — the OkHi reliability move. A geofence
+// alone is not reliable on Android 8+ once a manufacturer's battery manager
+// decides an app is idle: transitions are dropped and nothing says so, the
+// watch quietly lapses to inconclusive, and the phones on that list (Tecno,
+// Infinix, itel, Xiaomi, Oppo, Vivo) are the ones our markets carry.
+//
+// A foreground service, with its persistent notification, is the one thing
+// those managers leave alone. expo-location runs one for location updates;
+// this file drives it: periodic low-power fixes arrive in a headless task,
+// sampler.ts turns them into the same enter/exit spans the geofence tier
+// folds (on the SAME stored enterAt, so the two cooperate), the queue flushes
+// while the process is alive, and a dropped fence is re-armed.
+//
+// Android only, opt-in, and the notification is the HOST's to word — its
+// title and body reach the person's status bar. On iOS the geofence tier is
+// reliable on its own; asking for continuous background updates there would
+// be the heavier posture for nothing, so enable() answers unsupported.
+// ---------------------------------------------------------------------------
+
+import { Platform } from 'react-native';
+import * as Location from 'expo-location';
+import { armGeofence, geofenceArmed } from './geofence';
+import { applyLocationSamples, mergeObservations } from './sampler';
+import { postObservations } from './post';
+import { loadPresencePin } from './store';
+import {
+  loadEnterAt,
+  loadReporterConfig,
+  loadServiceUser,
+  pendingObservations,
+  queueObservations,
+  replacePending,
+  saveEnterAt,
+  saveReporterConfig,
+  saveServiceUser,
+} from './background-store';
+
+export const PRESENCE_LOCATION_TASK = 'myaza-kyc-presence-location';
+
+/** Low-power cadence: a fix every ten minutes or hundred metres is plenty to
+ *  bracket a stay to the dwell floor, and cheap enough to run for a week. */
+const SAMPLE_INTERVAL_MS = 10 * 60 * 1000;
+const SAMPLE_DISTANCE_M = 100;
+
+export interface PresenceNotification {
+  /** e.g. "Address verification in progress" */
+  title: string;
+  /** e.g. "Check the app to see your progress" */
+  body: string;
+  /** `#RRGGBB`; the notification accent. */
+  color?: string;
+}
+
+interface TaskManagerLike {
+  defineTask(name: string, fn: (body: { data: unknown; error: unknown }) => void): void;
+}
+
+type LocationLike = {
+  coords: { latitude: number; longitude: number; accuracy?: number | null };
+  timestamp?: number;
+  mocked?: boolean;
+};
+
+async function flushQueue(userId: string): Promise<void> {
+  const cfg = loadReporterConfig(userId);
+  if (!cfg) return;
+  const pending = pendingObservations(userId);
+  if (pending.length === 0) return;
+  const ok = await postObservations(cfg.apiKey, cfg.devUrl, userId, pending);
+  if (ok) replacePending(userId, []);
+}
+
+/** Define the location task. Called by registerBackgroundPresence(), so the
+ *  host's one root-level call covers both background tiers. */
+export function defineLocationTask(tm: TaskManagerLike): void {
+  tm.defineTask(PRESENCE_LOCATION_TASK, (body) => {
+    if (body.error) return;
+    const locations = (body.data as { locations?: LocationLike[] } | undefined)?.locations;
+    if (!Array.isArray(locations) || locations.length === 0) return;
+    const userId = loadServiceUser();
+    if (!userId) return;
+    const pin = loadPresencePin(userId);
+    if (!pin) return;
+
+    const result = applyLocationSamples(
+      pin,
+      locations.map((l) => ({
+        lat: l.coords.latitude,
+        lng: l.coords.longitude,
+        accuracy: typeof l.coords.accuracy === 'number' ? l.coords.accuracy : null,
+        timestamp: l.timestamp ?? Date.now(),
+        mocked: typeof l.mocked === 'boolean' ? l.mocked : null,
+      })),
+      loadEnterAt(userId),
+    );
+    saveEnterAt(userId, result.enterAt);
+    if (result.observations.length > 0) {
+      queueObservations(userId, result.observations, mergeObservations);
+    }
+    // A live process is the one moment a stuck queue (an EXIT flush that met
+    // no network) can drain, and a dropped fence can come back.
+    void flushQueue(userId);
+    void geofenceArmed().then((armed) => {
+      if (!armed) armGeofence(userId, pin).catch(() => undefined);
+    });
+  });
+}
+
+export interface EnableForegroundServiceResult {
+  enabled: boolean;
+  reason:
+    | 'enabled'
+    | 'unsupported_platform'
+    | 'module_missing'
+    | 'no_pin'
+    | 'foreground_denied'
+    | 'background_denied'
+    | 'start_failed';
+}
+
+/**
+ * Start the service on the stored pin. Asks for foreground THEN background
+ * permission (the order the OSes require); a refusal leaves whichever tier
+ * was running exactly as before — the tiers degrade, never break.
+ */
+export async function enableForegroundService(options: {
+  apiKey: string;
+  externalUserId: string;
+  devUrl?: string;
+  notification: PresenceNotification;
+}): Promise<EnableForegroundServiceResult> {
+  if (Platform.OS !== 'android') return { enabled: false, reason: 'unsupported_platform' };
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require('expo-task-manager');
+  } catch {
+    return { enabled: false, reason: 'module_missing' };
+  }
+  const pin = loadPresencePin(options.externalUserId);
+  if (!pin) return { enabled: false, reason: 'no_pin' };
+
+  const fg = await Location.requestForegroundPermissionsAsync().catch(() => null);
+  if (fg?.status !== 'granted') return { enabled: false, reason: 'foreground_denied' };
+  const bg = await Location.requestBackgroundPermissionsAsync().catch(() => null);
+  if (bg?.status !== 'granted') return { enabled: false, reason: 'background_denied' };
+
+  saveReporterConfig(options.externalUserId, {
+    apiKey: options.apiKey,
+    ...(options.devUrl ? { devUrl: options.devUrl } : {}),
+  });
+  saveServiceUser(options.externalUserId);
+
+  try {
+    await Location.startLocationUpdatesAsync(PRESENCE_LOCATION_TASK, {
+      accuracy: Location.Accuracy.Balanced,
+      timeInterval: SAMPLE_INTERVAL_MS,
+      distanceInterval: SAMPLE_DISTANCE_M,
+      deferredUpdatesInterval: SAMPLE_INTERVAL_MS,
+      foregroundService: {
+        notificationTitle: options.notification.title,
+        notificationBody: options.notification.body,
+        ...(options.notification.color ? { notificationColor: options.notification.color } : {}),
+        // The service outliving a swipe-away is the whole point.
+        killServiceOnDestroy: false,
+      },
+    });
+    return { enabled: true, reason: 'enabled' };
+  } catch {
+    saveServiceUser(null);
+    return { enabled: false, reason: 'start_failed' };
+  }
+}
+
+/** Stop the service and its notification. Never throws. */
+export async function disableForegroundService(): Promise<void> {
+  saveServiceUser(null);
+  try {
+    await Location.stopLocationUpdatesAsync(PRESENCE_LOCATION_TASK);
+  } catch {
+    // Not running, or the module is absent — either way, stopped.
+  }
+}
+
+/** Whether the service is running right now. Never throws. */
+export async function foregroundServiceRunning(): Promise<boolean> {
+  if (Platform.OS !== 'android') return false;
+  try {
+    return await Location.hasStartedLocationUpdatesAsync(PRESENCE_LOCATION_TASK);
+  } catch {
+    return false;
+  }
+}

package/src/presence/fs.ts

@@ -0,0 +1,51 @@
+// The presence tier's tiny JSON persistence, via expo-file-system loaded
+// through the SDK's optional-module pattern — a host without the module
+// simply has no presence tier, never a crash. Shared by the pin store and
+// the background tier's own store so the shim exists once.
+
+interface FileLike {
+  exists: boolean;
+  create(options?: { intermediates?: boolean; overwrite?: boolean }): void;
+  write(content: string): void;
+  textSync(): string;
+}
+
+interface FileSystemModule {
+  File: new (directory: unknown, name: string) => FileLike;
+  Paths: { document: unknown };
+}
+
+function fsModule(): FileSystemModule | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require('expo-file-system') as Partial<FileSystemModule>;
+    return mod?.File && mod?.Paths ? (mod as FileSystemModule) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readJsonFile(name: string): Record<string, unknown> {
+  const fs = fsModule();
+  if (!fs) return {};
+  try {
+    const file = new fs.File(fs.Paths.document, name);
+    if (!file.exists) return {};
+    const parsed = JSON.parse(file.textSync()) as unknown;
+    return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function writeJsonFile(name: string, value: Record<string, unknown>): void {
+  const fs = fsModule();
+  if (!fs) return;
+  try {
+    const file = new fs.File(fs.Paths.document, name);
+    if (!file.exists) file.create({ intermediates: true, overwrite: true });
+    file.write(JSON.stringify(value));
+  } catch {
+    // Best-effort: a failed save costs the presence tier, never the flow.
+  }
+}

package/src/presence/geofence.ts

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// The one geofence primitive both background tiers share. The OS-geofence
+// tier arms it at enable time; the foreground-service tier re-arms it when a
+// location batch finds the fence has been dropped (a location-services toggle
+// clears every registered fence on Android, silently). Kept apart from
+// background.ts so foreground-service.ts can import it without a cycle.
+// ---------------------------------------------------------------------------
+
+import * as Location from 'expo-location';
+
+export const PRESENCE_GEOFENCE_TASK = 'myaza-kyc-presence-geofence';
+
+/** The server's at-address rule: 250m, so the fence and the scorer agree on
+ *  what counts as "at the address". */
+export const GEOFENCE_RADIUS_M = 250;
+
+/** Registers the fence on the pin. Throws on failure; callers decide. */
+export function armGeofence(
+  externalUserId: string,
+  pin: { lat: number; lng: number },
+): Promise<void> {
+  return Location.startGeofencingAsync(PRESENCE_GEOFENCE_TASK, [
+    {
+      identifier: externalUserId,
+      latitude: pin.lat,
+      longitude: pin.lng,
+      radius: GEOFENCE_RADIUS_M,
+      notifyOnEnter: true,
+      notifyOnExit: true,
+    },
+  ]);
+}
+
+/** Whether the fence is registered with the OS right now. Never throws. */
+export async function geofenceArmed(): Promise<boolean> {
+  try {
+    return await Location.hasStartedGeofencingAsync(PRESENCE_GEOFENCE_TASK);
+  } catch {
+    return false;
+  }
+}

package/src/presence/math.ts

@@ -0,0 +1,44 @@
+// ---------------------------------------------------------------------------
+// Presence math — the pure half of the foreground reporter. On-device
+// evaluation is the contract: the phone decides "inside the fence?" and "what
+// local day/night is it?", and only the derived record (day + flag) ever
+// leaves the device. Raw coordinates never travel after capture.
+//
+// Mirrors the Flutter SDK's presence_math.dart — keep the two in lockstep.
+// ---------------------------------------------------------------------------
+
+const EARTH_RADIUS_M = 6_371_000;
+
+export function haversineMeters(
+  lat1: number,
+  lng1: number,
+  lat2: number,
+  lng2: number,
+): number {
+  const rad = (d: number) => (d * Math.PI) / 180;
+  const dLat = rad(lat2 - lat1);
+  const dLng = rad(lng2 - lng1);
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(rad(lat1)) * Math.cos(rad(lat2)) * Math.sin(dLng / 2) ** 2;
+  return 2 * EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(a)));
+}
+
+/** The server's at-address rule, applied on-device: 250 m, widened to the
+ *  fix's reported accuracy, capped at 1 km. */
+export function insideFence(
+  pin: { lat: number; lng: number },
+  fix: { lat: number; lng: number; accuracy: number | null },
+): boolean {
+  const radius = Math.min(1000, Math.max(250, fix.accuracy ?? 0));
+  return haversineMeters(pin.lat, pin.lng, fix.lat, fix.lng) <= radius;
+}
+
+/** The observation's day + night flag, from the DEVICE's local clock — that is
+ *  the whole point of on-device evaluation. Night = 20:00–05:59 local. */
+export function localDayAndNight(now = new Date()): { day: string; nightPresent: boolean } {
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const day = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+  const hour = now.getHours();
+  return { day, nightPresent: hour >= 20 || hour < 6 };
+}

package/src/presence/post.ts

@@ -0,0 +1,40 @@
+// ---------------------------------------------------------------------------
+// The one wire path for presence observations — shared by the foreground
+// reporter and the background geofence flush, so the two tiers can never
+// drift on the request shape. Best-effort by contract: a failure returns
+// false and the caller keeps its queue.
+// ---------------------------------------------------------------------------
+
+import { resolveBaseUrl } from '../services/resolveUrl';
+
+export interface WireObservation {
+  day: string;
+  source: 'geofence' | 'foreground';
+  dwellMinutes: number;
+  nightPresent: boolean;
+  samples: number;
+  integrity?: { mockLocation?: boolean; emulator?: boolean };
+}
+
+export async function postObservations(
+  apiKey: string,
+  devUrl: string | undefined,
+  externalUserId: string,
+  observations: WireObservation[],
+): Promise<boolean> {
+  if (observations.length === 0) return true;
+  try {
+    const base = resolveBaseUrl(apiKey, devUrl);
+    const response = await fetch(`${base}/api/kyc/address/observations`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({ externalUserId, observations }),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}

package/src/presence/report.ts

@@ -0,0 +1,87 @@
+// ---------------------------------------------------------------------------
+// The FOREGROUND presence reporter — the default tier, no background
+// permission. The host app calls reportAddressPresence() on app open, or the
+// moment the flow submits (watch-wait.ts makes that safe: the watch is minted
+// seconds after the submission is accepted, and a fresh pin waits for it);
+// the SDK takes one while-in-use fix, evaluates the fence ON-DEVICE against
+// the pin stored at capture, and posts a single per-day aggregate. Everything is best-effort: a denied permission, a missing pin, or
+// a network fault returns a reason, never a throw — a presence report must
+// never break the host app's startup path.
+// ---------------------------------------------------------------------------
+
+import * as Location from 'expo-location';
+import { currentPosition } from '../services/location';
+import { insideFence, localDayAndNight } from './math';
+import { postObservations } from './post';
+import { loadPresencePin } from './store';
+import { awaitWatch, fetchWatchStatus, pinIsFresh } from './watch-wait';
+
+export interface ReportPresenceOptions {
+  /** The org's PUBLISHABLE key (the same one the KYC flow mounts with). */
+  apiKey: string;
+  /** The org's user reference — must match the KYC flow's `userId`. */
+  externalUserId: string;
+  /** Dev-server override, exactly like the SDK config's `devUrl`. */
+  devUrl?: string;
+}
+
+export interface ReportPresenceResult {
+  reported: boolean;
+  /** Whether the fix landed inside the fence (null when nothing was reported). */
+  inside: boolean | null;
+  reason:
+    | 'reported'
+    | 'no_pin'
+    | 'services_off'
+    | 'no_fix'
+    | 'outside_fence'
+    /** Nothing is monitoring this user right now, so a report would be dropped. */
+    | 'no_watch'
+    | 'network_error';
+}
+
+export async function reportAddressPresence(
+  options: ReportPresenceOptions,
+): Promise<ReportPresenceResult> {
+  const pin = loadPresencePin(options.externalUserId);
+  if (!pin) return { reported: false, inside: null, reason: 'no_pin' };
+
+  // The phone's location toggle, checked before the permission dance: off,
+  // every fix fails, and `no_fix` told the host nothing about why.
+  const services = await Location.hasServicesEnabledAsync().catch(() => true);
+  if (!services) return { reported: false, inside: null, reason: 'services_off' };
+
+  const fix = await currentPosition();
+  if (!fix) return { reported: false, inside: null, reason: 'no_fix' };
+
+  const inside = insideFence(pin, fix);
+  // An outside fix is NOT evidence of absence (people go to work) — the server
+  // scores presence, never absence — so there is nothing worth sending.
+  if (!inside && fix.mocked !== true) {
+    return { reported: false, inside: false, reason: 'outside_fence' };
+  }
+
+  // The watch is minted seconds after a submission is accepted, and the
+  // ingest drops a report that arrives before it (watch-wait.ts).
+  const watch = await awaitWatch(pinIsFresh(pin), {
+    fetchStatus: () => fetchWatchStatus(options.apiKey, options.devUrl, options.externalUserId),
+  });
+  if (watch === 'absent') return { reported: false, inside, reason: 'no_watch' };
+
+  const { day, nightPresent } = localDayAndNight();
+  // One wire path for both tiers (post.ts) — the request shape cannot fork.
+  const ok = await postObservations(options.apiKey, options.devUrl, options.externalUserId, [
+    {
+      day,
+      source: 'foreground',
+      dwellMinutes: 0,
+      nightPresent,
+      samples: 1,
+      // A mocked fix is REPORTED, flagged — evidence OF fraud is worth
+      // more to the watch than silence.
+      ...(fix.mocked === true ? { integrity: { mockLocation: true } } : {}),
+    },
+  ]);
+  if (!ok) return { reported: false, inside, reason: 'network_error' };
+  return { reported: true, inside, reason: 'reported' };
+}