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

package/src/presence/background-math.ts

@@ -0,0 +1,100 @@
+// ---------------------------------------------------------------------------
+// Pure maths for the background (OS geofence) presence tier. A geofence hands
+// us ENTER/EXIT moments; the watch wants per-day aggregates — so a dwell SPAN
+// is folded into the local calendar days it touched, each with its minutes
+// and whether the span overlapped that day's night hours (20:00 to 05:59,
+// the same definition the foreground reporter and the server use).
+//
+// THREE implementations of this fold exist — this file, the Flutter plugin's
+// PresenceFold.kt (Android) and PresenceFold.swift (iOS) — because the
+// killed-app flush must fold natively. All three are pinned to ONE vector
+// file, packages/kyc-sdk-flutter/test/presence_fold_vectors.json, which is
+// why the maths is integer arithmetic on an EXPLICIT UTC offset rather than
+// platform date APIs: identical inputs must fold identically in every
+// language. The offset is captured once per fold (east-positive minutes), a
+// fixed-offset approximation that ignores a DST transition inside one span —
+// at most an hour of dwell attribution shifts, and cross-platform parity is
+// worth more than that edge.
+// ---------------------------------------------------------------------------
+
+export interface DayAggregate {
+  day: string;
+  dwellMinutes: number;
+  nightPresent: boolean;
+}
+
+/**
+ * The longest span one fold will credit. A missed EXIT event (the OS dropped
+ * it, the app was killed mid-fence) would otherwise fabricate days of dwell
+ * from one stale ENTER timestamp — a fence can fail to close, so the credit
+ * from any single span is bounded to one day's worth.
+ */
+export const MAX_SPAN_MS = 24 * 60 * 60 * 1000;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+const NIGHT_END_H = 6;
+const NIGHT_START_H = 20;
+
+/** The device's UTC offset in east-positive minutes (Lagos = +60). JS's
+ *  getTimezoneOffset() is west-positive, hence the sign flip. */
+export const deviceUtcOffsetMinutes = (atMs: number): number =>
+  -new Date(atMs).getTimezoneOffset();
+
+/** Civil date for a day index (days since 1970-01-01), as YYYY-MM-DD.
+ *  Howard Hinnant's civil_from_days — pure integers, no date API, so the
+ *  Kotlin and Swift mirrors are line-for-line identical. */
+export function civilFromDays(z: number): string {
+  const zz = z + 719468;
+  const era = Math.floor(zz / 146097);
+  const doe = zz - era * 146097;
+  const yoe = Math.floor((doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365);
+  const y = yoe + era * 400;
+  const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100));
+  const mp = Math.floor((5 * doy + 2) / 153);
+  const d = doy - Math.floor((153 * mp + 2) / 5) + 1;
+  const m = mp < 10 ? mp + 3 : mp - 9;
+  const year = m <= 2 ? y + 1 : y;
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${year}-${pad(m)}-${pad(d)}`;
+}
+
+/**
+ * Fold one dwell span into per-local-day aggregates. `offsetMinutes` is the
+ * device's UTC offset (east-positive); it defaults to the device's own so
+ * ordinary callers never think about it. An inverted span yields nothing.
+ */
+export function foldSpanIntoDays(
+  enterMs: number,
+  exitMs: number,
+  offsetMinutes: number = deviceUtcOffsetMinutes(enterMs),
+): DayAggregate[] {
+  if (!Number.isFinite(enterMs) || !Number.isFinite(exitMs)) return [];
+  if (exitMs <= enterMs) return [];
+  const offsetMs = offsetMinutes * 60_000;
+  const cappedExit = Math.min(exitMs, enterMs + MAX_SPAN_MS);
+
+  const out: DayAggregate[] = [];
+  let cursor = enterMs;
+  while (cursor < cappedExit) {
+    const shifted = cursor + offsetMs;
+    const dayIndex = Math.floor(shifted / DAY_MS);
+    // The real-clock moment this local day ends.
+    const dayEnd = (dayIndex + 1) * DAY_MS - offsetMs;
+    const sliceEnd = Math.min(dayEnd, cappedExit);
+    // Night = [00:00, 06:00) plus [20:00, 24:00) of this local day. Exact
+    // interval overlap — no sampling — so all three languages agree at the
+    // boundaries: a slice ENDING exactly at 20:00 has not touched the night.
+    const dayStartShifted = dayIndex * DAY_MS;
+    const nightPresent =
+      shifted < dayStartShifted + NIGHT_END_H * HOUR_MS ||
+      sliceEnd + offsetMs > dayStartShifted + NIGHT_START_H * HOUR_MS;
+    out.push({
+      day: civilFromDays(dayIndex),
+      dwellMinutes: Math.max(1, Math.round((sliceEnd - cursor) / 60_000)),
+      nightPresent,
+    });
+    cursor = sliceEnd;
+  }
+  return out;
+}

package/src/presence/background-store.ts

@@ -0,0 +1,82 @@
+// Persistence for the background geofence tier: the open ENTER timestamp,
+// the unflushed per-day queue, and the wire config the headless task needs
+// (it runs with no React context, so apiKey/devUrl are persisted beside the
+// pin — the key is publishable by design). Kept apart from the pin store so
+// each file stays small and the pin's own lifecycle rules stay untangled
+// from flush bookkeeping.
+
+import { readJsonFile, writeJsonFile } from './fs';
+import type { WireObservation } from './post';
+
+const FILE_NAME = 'myaza-kyc-presence-bg.json';
+
+interface BgRecord {
+  enterAt?: number | null;
+  pending?: WireObservation[];
+  config?: { apiKey: string; devUrl?: string };
+  serviceUser?: string;
+}
+
+/** The foreground-service tier serves ONE user at a time (one notification,
+ *  one location stream), and its task carries no region identifier the way a
+ *  geofence event does — so the user it samples for is remembered under this
+ *  reserved key, which no org user reference can collide with. */
+const SERVICE_USER_KEY = '__service_user__';
+
+function readAll(): Record<string, BgRecord> {
+  return readJsonFile(FILE_NAME) as Record<string, BgRecord>;
+}
+
+function write(userId: string, patch: Partial<BgRecord>): void {
+  const all = readAll();
+  all[userId] = { ...all[userId], ...patch };
+  writeJsonFile(FILE_NAME, all as Record<string, unknown>);
+}
+
+export function saveEnterAt(userId: string, at: number | null): void {
+  write(userId, { enterAt: at });
+}
+
+export function loadEnterAt(userId: string): number | null {
+  const at = readAll()[userId]?.enterAt;
+  return typeof at === 'number' ? at : null;
+}
+
+export function pendingObservations(userId: string): WireObservation[] {
+  const pending = readAll()[userId]?.pending;
+  return Array.isArray(pending) ? pending : [];
+}
+
+export function replacePending(userId: string, next: WireObservation[]): void {
+  write(userId, { pending: next });
+}
+
+/** Append fresh aggregates through the caller's merge (same-day spans fold). */
+export function queueObservations(
+  userId: string,
+  fresh: WireObservation[],
+  merge: (existing: WireObservation[], fresh: WireObservation[]) => WireObservation[],
+): void {
+  write(userId, { pending: merge(pendingObservations(userId), fresh) });
+}
+
+export function saveReporterConfig(userId: string, config: { apiKey: string; devUrl?: string }): void {
+  write(userId, { config });
+}
+
+export function loadReporterConfig(userId: string): { apiKey: string; devUrl?: string } | null {
+  const cfg = readAll()[userId]?.config;
+  return cfg && typeof cfg.apiKey === 'string' ? cfg : null;
+}
+
+export function saveServiceUser(userId: string | null): void {
+  const all = readAll();
+  if (userId == null) delete all[SERVICE_USER_KEY];
+  else all[SERVICE_USER_KEY] = { serviceUser: userId };
+  writeJsonFile(FILE_NAME, all as Record<string, unknown>);
+}
+
+export function loadServiceUser(): string | null {
+  const id = readAll()[SERVICE_USER_KEY]?.serviceUser;
+  return typeof id === 'string' && id.length > 0 ? id : null;
+}

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 };
+}