@spare-technologies/spare-link 1.0.1 → 1.1.0

package/src/internal/telemetry/native-telemetry-reply.ts

@@ -0,0 +1,59 @@
+/**
+ * Delivers a telemetry reply into the hosted page.
+ *
+ * The WebView message channel is one-way, so the reply travels the other way:
+ * the page exposes `window.__spareLinkNativeTelemetry` before it asks, and the
+ * shell answers by injecting a call to it. A page without the callback — an
+ * older page, or one that already gave up waiting — receives nothing and the
+ * injected chunk evaluates to a harmless literal.
+ */
+
+/** Page-exposed global the shell invokes with its telemetry reply. */
+export const NATIVE_TELEMETRY_CALLBACK_NAME = '__spareLinkNativeTelemetry';
+
+/**
+ * Builds the script that hands [payload] to the page's telemetry callback.
+ *
+ * The payload is embedded as a JSON literal. U+2028 and U+2029 are legal inside
+ * a JSON string but terminate a statement when evaluated as script, so they are
+ * escaped; the result is a single expression that is inert on a page without
+ * the callback.
+ */
+export function buildNativeTelemetryReplyScript(payload: Record<string, unknown>): string {
+  const literal = JSON.stringify(payload)
+    .replaceAll('\u2028', '\\u2028')
+    .replaceAll('\u2029', '\\u2029');
+  return (
+    `window.${NATIVE_TELEMETRY_CALLBACK_NAME} && ` +
+    `window.${NATIVE_TELEMETRY_CALLBACK_NAME}(${literal}); true;`
+  );
+}
+
+/**
+ * Builds the handler the webview runs when the page asks for telemetry.
+ *
+ * Collection and injection are injected so the handler is a pure seam: the
+ * component wires the real collector and the WebView reference into it. A
+ * collector that answers nothing, or throws, injects nothing — the page's own
+ * timeout settles the request.
+ */
+export function createTelemetryRequestHandler(deps: {
+  collect: () => Promise<Record<string, unknown> | null>;
+  inject: (script: string) => void;
+}): () => Promise<void> {
+  return async () => {
+    let payload: Record<string, unknown> | null;
+    try {
+      payload = await deps.collect();
+    } catch {
+      payload = null;
+    }
+    if (payload == null) return;
+
+    try {
+      deps.inject(buildNativeTelemetryReplyScript(payload));
+    } catch {
+      // A torn-down webview cannot be injected into; the page's timeout answers.
+    }
+  };
+}

package/src/internal/telemetry/risk-telemetry-collector.ts

@@ -0,0 +1,128 @@
+/**
+ * Collects this device's native risk facts for the hosted payment page.
+ *
+ * Every probe is injected, so the collector runs under Jest with fakes and the
+ * module wiring lives in `risk-telemetry-probes`. Every probe is also allowed to
+ * fail or hang: a throwing or slow reading leaves its fact absent, because a risk
+ * reading must never delay or break a payment.
+ *
+ * The payload mirrors the page's own risk contract: camelCase keys under a
+ * `deviceInformation` block, facts only, nothing fabricated.
+ */
+
+/** How long any single probe may take before its fact is given up on. */
+export const TELEMETRY_PROBE_BUDGET_MS = 800;
+
+/** Identity and build facts read from the platform. */
+export interface RiskDeviceSnapshot {
+  readonly operatingSystem: string | null;
+  readonly operatingSystemVersion: string | null;
+  readonly model: string | null;
+  readonly manufacturer: string | null;
+  /** A per-vendor install-stable identifier, when the platform offers one. */
+  readonly vendorIdentifier: string | null;
+  /** False on simulators and emulators. */
+  readonly isPhysicalDevice: boolean | null;
+}
+
+/** A battery reading, with the level as a 0 to 1 fraction. */
+export interface RiskBatteryReading {
+  readonly levelFraction: number | null;
+  readonly isCharging: boolean | null;
+}
+
+/** The network medium classes the risk payload distinguishes. */
+export type RiskConnectionKind = 'wifi' | 'cellular' | 'other';
+
+/** The probes the collector runs. Each may answer null, throw, or hang. */
+export interface RiskTelemetryProbes {
+  loadDeviceSnapshot(): Promise<RiskDeviceSnapshot | null>;
+  loadBattery(): Promise<RiskBatteryReading | null>;
+  loadConnection(): Promise<RiskConnectionKind | null>;
+  localeTag(): string | null;
+  localDateTime(): string | null;
+}
+
+const CONNECTION_LABELS: Record<RiskConnectionKind, string> = {
+  wifi: 'WiFi',
+  cellular: 'Cellular',
+  other: 'Other',
+};
+
+/** Runs a probe under the budget, yielding null on failure or timeout. */
+async function guarded<T>(probe: () => Promise<T | null>): Promise<T | null> {
+  try {
+    return await Promise.race<T | null>([
+      probe(),
+      new Promise<null>((resolve) => setTimeout(() => resolve(null), TELEMETRY_PROBE_BUDGET_MS)),
+    ]);
+  } catch {
+    return null;
+  }
+}
+
+function read<T>(reader: () => T | null): T | null {
+  try {
+    return reader();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collects whatever the device answered within the per-probe budget.
+ *
+ * Returns null when nothing answered, so a caller hands the page nothing rather
+ * than an empty block.
+ */
+export async function collectRiskTelemetry(
+  probes: RiskTelemetryProbes,
+): Promise<Record<string, unknown> | null> {
+  const [snapshot, battery, connection] = await Promise.all([
+    guarded(probes.loadDeviceSnapshot),
+    guarded(probes.loadBattery),
+    guarded(probes.loadConnection),
+  ]);
+  const localeTag = read(probes.localeTag);
+  const localDateTime = read(probes.localDateTime);
+
+  const deviceInformation: Record<string, unknown> = {};
+
+  if (snapshot?.operatingSystem != null) {
+    deviceInformation.deviceOperatingSystem = snapshot.operatingSystem;
+  }
+  if (snapshot?.operatingSystemVersion != null) {
+    deviceInformation.deviceOperatingSystemVersion = snapshot.operatingSystemVersion;
+  }
+
+  const manufacturer: Record<string, unknown> = {};
+  if (snapshot?.model != null) manufacturer.model = snapshot.model;
+  if (snapshot?.manufacturer != null) manufacturer.manufacturer = snapshot.manufacturer;
+  if (Object.keys(manufacturer).length > 0) {
+    deviceInformation.deviceManufacturer = manufacturer;
+  }
+
+  if (snapshot?.vendorIdentifier != null) {
+    deviceInformation.alternativeDeviceId = snapshot.vendorIdentifier;
+  }
+  if (localeTag != null) deviceInformation.deviceLanguage = localeTag;
+  if (localDateTime != null) deviceInformation.deviceLocalDateTime = localDateTime;
+  if (connection != null) deviceInformation.connectionType = CONNECTION_LABELS[connection];
+
+  const batteryStatus: Record<string, unknown> = {};
+  const level = battery?.levelFraction;
+  if (level != null && level >= 0 && level <= 1) batteryStatus.level = level;
+  if (battery?.isCharging != null) batteryStatus.isCharging = battery.isCharging;
+  if (Object.keys(batteryStatus).length > 0) {
+    deviceInformation.batteryStatus = batteryStatus;
+  }
+
+  const environmentContext: string[] = [];
+  if (snapshot?.isPhysicalDevice === false) environmentContext.push('EmulatorDetected');
+  if (environmentContext.length > 0) {
+    deviceInformation.deviceEnvironmentContext = environmentContext;
+  }
+
+  if (Object.keys(deviceInformation).length === 0) return null;
+  return { deviceInformation };
+}

package/src/internal/telemetry/risk-telemetry-probes.ts

@@ -0,0 +1,159 @@
+/**
+ * The real device probes behind `collectRiskTelemetry`.
+ *
+ * Every expo module here is an optional peer, loaded lazily inside a try/catch:
+ * a host app that ships without one simply reports that fact as absent, and no
+ * import of this file can throw for want of a native module. Structural `*Like`
+ * types keep this file honest about how little of each module it relies on.
+ */
+
+import { Platform } from 'react-native';
+import type {
+  RiskBatteryReading,
+  RiskConnectionKind,
+  RiskDeviceSnapshot,
+  RiskTelemetryProbes,
+} from './risk-telemetry-collector';
+
+interface DeviceModuleLike {
+  modelName?: string | null;
+  manufacturer?: string | null;
+  osVersion?: string | null;
+  isDevice?: boolean;
+}
+
+interface BatteryModuleLike {
+  getBatteryLevelAsync(): Promise<number>;
+  getBatteryStateAsync(): Promise<number>;
+  BatteryState?: { CHARGING?: number; FULL?: number };
+}
+
+interface NetworkModuleLike {
+  getNetworkStateAsync(): Promise<{ type?: string | null }>;
+}
+
+interface ApplicationModuleLike {
+  getIosIdForVendorAsync(): Promise<string | null>;
+}
+
+function load<T>(moduleName: string): T | null {
+  try {
+    // Resolved at call time so a host app without the optional peer never pays
+    // for it — bundlers keep the require because the name is static.
+    switch (moduleName) {
+      case 'expo-device':
+        return require('expo-device') as T;
+      case 'expo-battery':
+        return require('expo-battery') as T;
+      case 'expo-network':
+        return require('expo-network') as T;
+      case 'expo-application':
+        return require('expo-application') as T;
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
+async function loadDeviceSnapshot(): Promise<RiskDeviceSnapshot | null> {
+  const device = load<DeviceModuleLike>('expo-device');
+  if (device == null) return null;
+
+  // The vendor identifier is iOS-only by design: Android offers no equivalent
+  // scoped identifier worth persisting against a payment.
+  let vendorIdentifier: string | null = null;
+  if (Platform.OS === 'ios') {
+    const application = load<ApplicationModuleLike>('expo-application');
+    if (application != null) {
+      try {
+        vendorIdentifier = await application.getIosIdForVendorAsync();
+      } catch {
+        vendorIdentifier = null;
+      }
+    }
+  }
+
+  return {
+    operatingSystem: Platform.OS === 'ios' ? 'iOS' : 'Android',
+    operatingSystemVersion: device.osVersion ?? null,
+    model: device.modelName ?? null,
+    manufacturer: device.manufacturer ?? null,
+    vendorIdentifier,
+    isPhysicalDevice: typeof device.isDevice === 'boolean' ? device.isDevice : null,
+  };
+}
+
+async function loadBattery(): Promise<RiskBatteryReading | null> {
+  const battery = load<BatteryModuleLike>('expo-battery');
+  if (battery == null) return null;
+
+  const level = await battery.getBatteryLevelAsync();
+  const state = await battery.getBatteryStateAsync();
+  const charging = battery.BatteryState?.CHARGING;
+  const full = battery.BatteryState?.FULL;
+
+  return {
+    // The module reports -1 when the level cannot be read; the collector's 0..1
+    // bound would drop it anyway, made explicit here.
+    levelFraction: level >= 0 && level <= 1 ? level : null,
+    isCharging: charging != null ? state === charging || state === full : null,
+  };
+}
+
+async function loadConnection(): Promise<RiskConnectionKind | null> {
+  const network = load<NetworkModuleLike>('expo-network');
+  if (network == null) return null;
+
+  const state = await network.getNetworkStateAsync();
+  const type = state.type?.toUpperCase() ?? null;
+  if (type == null || type === 'NONE' || type === 'UNKNOWN') return null;
+  if (type === 'WIFI') return 'wifi';
+  if (type === 'CELLULAR') return 'cellular';
+  return 'other';
+}
+
+function localeTag(): string | null {
+  try {
+    const tag = Intl.DateTimeFormat().resolvedOptions().locale;
+    return typeof tag === 'string' && tag.length > 0 ? tag : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Formats a date as local-time ISO 8601 with a numeric UTC offset, e.g.
+ * `2026-08-25T10:45:46.319+05:30` — never the UTC `Z` form. This keeps the
+ * timestamp on the payer's own clock so it reads the same as the device shows,
+ * and matches the Flutter SDK's `deviceLocalDateTime`.
+ */
+export function formatLocalIsoWithOffset(date: Date): string {
+  const pad = (value: number, width = 2): string => String(value).padStart(width, '0');
+
+  // getTimezoneOffset is minutes behind UTC, so east-of-UTC zones are negative;
+  // flip the sign to render the conventional offset.
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absOffset = Math.abs(offsetMinutes);
+
+  const localDate = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+  const localTime = `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
+  const offset = `${sign}${pad(Math.floor(absOffset / 60))}:${pad(absOffset % 60)}`;
+
+  return `${localDate}T${localTime}${offset}`;
+}
+
+function localDateTime(): string | null {
+  try {
+    return formatLocalIsoWithOffset(new Date());
+  } catch {
+    return null;
+  }
+}
+
+/** The production probe set, ready for `collectRiskTelemetry`. */
+export function createRiskTelemetryProbes(): RiskTelemetryProbes {
+  return { loadDeviceSnapshot, loadBattery, loadConnection, localeTag, localDateTime };
+}

package/src/ui/hosted/hosted-payment-page.tsx

@@ -2,6 +2,8 @@ import { useCallback, useEffect, useRef } from 'react';
 import { ActivityIndicator, StyleSheet, Text, View } from 'react-native';
 import type { HostedFlowController } from '../../core/services/hosted-flow-controller';
 import { isTerminalPhase } from '../../core/services/hosted-flow-state';
+import { collectRiskTelemetry } from '../../internal/telemetry/risk-telemetry-collector';
+import { createRiskTelemetryProbes } from '../../internal/telemetry/risk-telemetry-probes';
 import { useHostedFlowState } from '../hooks/use-hosted-flow-state';
 import { PageUnavailableScreen } from '../screens/page-unavailable-screen';
 import { RedirectHandoffScreen } from '../screens/redirect-handoff-screen';
@@ -70,6 +72,11 @@ export function HostedPaymentPage(props: HostedPaymentPageProps): JSX.Element {
     [controller],
   );
 
+  // One probe set for the page's lifetime; collection itself runs per request.
+  const handleTelemetryRequest = useCallback(() => {
+    return collectRiskTelemetry(createRiskTelemetryProbes());
+  }, []);
+
   const handleLoadFailure = useCallback(() => {
     controller.failToLoad();
   }, [controller]);
@@ -105,6 +112,7 @@ export function HostedPaymentPage(props: HostedPaymentPageProps): JSX.Element {
               baseUrl={baseUrl}
               reference={controller.reference}
               onBridgeMessage={handleBridgeMessage}
+              onTelemetryRequest={handleTelemetryRequest}
               onLoadFailure={handleLoadFailure}
               onMounted={handlePageMounted}
             />

package/src/ui/hosted/hosted-payment-webview.tsx

@@ -1,8 +1,10 @@
-import { useCallback, useEffect } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { StyleSheet, View } from 'react-native';
 import { WebView, type WebViewMessageEvent } from 'react-native-webview';
+import { parseHostedBridgeMessage } from '../../internal/hosted/bridge-message';
 import { buildHostedPaymentUrl, isHostedOriginUrl } from '../../internal/hosted/hosted-url';
 import { createLogger } from '../../internal/logger';
+import { createTelemetryRequestHandler } from '../../internal/telemetry/native-telemetry-reply';
 import { parseUrlParts } from '../../internal/url-parts';
 import { Colors } from '../theme';
 
@@ -44,6 +46,15 @@ export interface HostedPaymentWebViewProps {
    * this component stays a transport.
    */
   onBridgeMessage: (message: unknown) => void;
+  /**
+   * Answers the page's telemetry request with this device's native risk facts.
+   *
+   * The reply travels back by injected script rather than a return value, so it
+   * is handled here where the webview reference lives, and the message never
+   * reaches [onBridgeMessage]. Absent, or answering null, means the page
+   * proceeds with what the browser alone can see.
+   */
+  onTelemetryRequest?: () => Promise<Record<string, unknown> | null>;
   /** Called when the page itself could not be loaded. */
   onLoadFailure?: () => void;
   /**
@@ -63,8 +74,10 @@ export interface HostedPaymentWebViewProps {
  * the page reports, and refuses to navigate anywhere else.
  */
 export function HostedPaymentWebView(props: HostedPaymentWebViewProps): JSX.Element {
-  const { baseUrl, reference, onBridgeMessage, onLoadFailure, onMounted } = props;
+  const { baseUrl, reference, onBridgeMessage, onTelemetryRequest, onLoadFailure, onMounted } =
+    props;
   const uri = buildHostedPaymentUrl({ baseUrl, reference });
+  const webViewRef = useRef<WebView>(null);
 
   // This reports that *this* webview exists, and a retry mounts a fresh instance
   // which reports itself anew. Re-running on a new callback identity would
@@ -76,9 +89,23 @@ export function HostedPaymentWebView(props: HostedPaymentWebViewProps): JSX.Elem
 
   const handleMessage = useCallback(
     (event: WebViewMessageEvent) => {
-      onBridgeMessage(event.nativeEvent.data);
+      const raw = event.nativeEvent.data;
+
+      // The telemetry request is answered here, where the webview reference
+      // lives, because the reply is delivered by injecting script — a channel
+      // only this component holds. Everything else stays the caller's.
+      if (onTelemetryRequest && parseHostedBridgeMessage(raw)?.type === 'telemetryRequest') {
+        const respond = createTelemetryRequestHandler({
+          collect: onTelemetryRequest,
+          inject: (script) => webViewRef.current?.injectJavaScript(script),
+        });
+        void respond();
+        return;
+      }
+
+      onBridgeMessage(raw);
     },
-    [onBridgeMessage],
+    [onBridgeMessage, onTelemetryRequest],
   );
 
   // Every navigation is routed through here rather than through `originWhitelist`.
@@ -99,6 +126,7 @@ export function HostedPaymentWebView(props: HostedPaymentWebViewProps): JSX.Elem
     // modal, so this fills what it is given.
     <View style={styles.container} testID="hosted-payment-webview">
       <WebView
+        ref={webViewRef}
         source={{ uri }}
         onMessage={handleMessage}
         originWhitelist={ALLOW_ALL_ORIGINS}
@@ -141,6 +169,16 @@ export function HostedPaymentWebView(props: HostedPaymentWebViewProps): JSX.Elem
         style={styles.webview}
         javaScriptEnabled
         domStorageEnabled
+        // Lets the page's consent screen ask for a coarse location fix, which it
+        // attaches to the payment as a risk signal. Android only; iOS raises its
+        // own per-origin system prompt, gated by the host app's usage-description
+        // entry. This toggle is frame-wide — the platform offers no per-origin
+        // answer here — so the scope rests on `handleShouldStartLoad` above
+        // refusing every off-origin document in this frame. The toggle alone also
+        // reveals nothing: the host application must hold the user-facing location
+        // permission, and without it the page's request fails and the payment
+        // proceeds without the signal.
+        geolocationEnabled
         // The page holds a payment in progress and nothing else should share its
         // storage, on this device or between payers on it.
         incognito

package/src/version.ts

@@ -6,4 +6,4 @@
  * `changeset version`). The src/index.ts smoke test asserts this matches
  * package.json's version.
  */
-export const SDK_VERSION = '1.0.1' as const;
+export const SDK_VERSION = '1.1.0' as const;