@smileid/usesmileid 12.0.0-beta01 → 12.0.0

package/src/metadata/metadata_configuration_mappers.ts

@@ -0,0 +1,234 @@
+import { AnalyzerFactoryKey } from "@smileid/usesmileid_bridge";
+
+import { CaptureType } from "../core/models/ml_config";
+import { autoCaptureWireValue } from "../core/models/document_capture_mode";
+import type { FlowConfiguration } from "../presentation/flow/config/flow_configuration";
+import type {
+  CaptureConfigBuilder,
+  ConsentConfigBuilder,
+} from "../presentation/flow/dsl/builder/screens_builder";
+import {
+  type BuilderConfiguration,
+  builderConfigurationToJson,
+} from "./builder_configuration";
+import {
+  MODEL_DESCRIPTOR_UNKNOWN,
+  type ModelConfiguration,
+  type ModelDescriptor,
+  ModelProvider,
+  modelConfigurationToJson,
+} from "./model_configuration";
+import type { MetadataEntry } from "./use_smile_id_metadata";
+
+/**
+ * Projects the resolved [FlowConfiguration] into the request-metadata
+ * configuration objects, so the telemetry layer never needs a parallel copy of
+ * the partner's choices.
+ *
+ * Fields that do not apply to the assembled flow report their accurate "absent"
+ * value (`false`, or `autocapture_default` for the capture mode) rather than
+ * being omitted, so the object always carries the full schema.
+ * `consent_icon_dimensions` is always `null`: the consent icon is a `ReactNode`
+ * with no measurable pixel size at configuration time.
+ */
+export function flowConfigurationToBuilderConfiguration(
+  configuration: FlowConfiguration,
+): BuilderConfiguration {
+  const steps = configuration.screens.steps;
+
+  let consent: ConsentConfigBuilder | undefined;
+  const captures: CaptureConfigBuilder[] = [];
+  let instructionsUsed = false;
+  let previewUsed = false;
+  let processingUsed = false;
+  for (const step of steps) {
+    switch (step.kind) {
+      case "consent":
+        consent = step.config;
+        break;
+      case "instructions":
+        instructionsUsed = true;
+        break;
+      case "capture":
+        captures.push(step.config);
+        break;
+      case "preview":
+        previewUsed = true;
+        break;
+      case "processing":
+        processingUsed = true;
+        break;
+    }
+  }
+
+  const selfie = captures.find((capture) => capture.selfieConfig)?.selfieConfig;
+  const document = captures.find(
+    (capture) => capture.documentConfig,
+  )?.documentConfig;
+  const hasSelfieCapture =
+    selfie !== undefined ||
+    captures.some((capture) => capture.captureType === CaptureType.selfie);
+  const hasDocumentCapture =
+    document !== undefined ||
+    captures.some((capture) => capture.captureType === CaptureType.document);
+
+  return {
+    consentScreenUsed: consent !== undefined,
+    consentIconProvided: consent?.partnerIcon != null,
+    // A React Native consent icon is a ReactNode with no measurable pixel size.
+    consentIconDimensions: null,
+    consentAttributionShown: consent?.showAttribution ?? false,
+    instructionsScreenUsed: instructionsUsed,
+    selfiePreviewEnabled: previewUsed && hasSelfieCapture,
+    documentPreviewEnabled: previewUsed && hasDocumentCapture,
+    // No processing screen means the flow captures without submitting to the API.
+    submissionSkipped: !processingUsed,
+    allowAgentMode: selfie?.allowAgentMode ?? false,
+    enhancedLivenessEnabled: selfie?.enableEnhancedLiveness ?? false,
+    autoCaptureEnabled: autoCaptureWireValue(document?.captureMode),
+    allowGalleryUpload: document?.allowGalleryUpload ?? false,
+    captureBothSides: document?.captureBothSides ?? false,
+    allowSkipBack: document?.allowSkipBack ?? false,
+  };
+}
+
+/**
+ * Describes the face and document models backing this flow.
+ *
+ * The face model is resolved from the registered selfie analyzer factory key;
+ * the document model reports the native no-op fallback, since the React Native
+ * document detector is not selectable from JS.
+ */
+export function flowConfigurationToModelConfiguration(
+  configuration: FlowConfiguration,
+): ModelConfiguration {
+  const faceKey = configuration.ml?.analyzers.selfieConfig?.analyzerFactoryKey;
+  return {
+    faceModel: faceDescriptorOf(faceKey),
+    documentModel: NOOP_DOCUMENT_DESCRIPTOR,
+  };
+}
+
+/**
+ * The `builder_configuration_object` + `model_configuration_object` wire
+ * entries, encoded as JSON-string values so the metadata payload stays a flat
+ * `{name, value}` array.
+ */
+export function configurationMetadataEntries(
+  configuration: FlowConfiguration,
+): MetadataEntry[] {
+  const entries: MetadataEntry[] = [
+    {
+      name: "builder_configuration_object",
+      value: JSON.stringify(
+        builderConfigurationToJson(
+          flowConfigurationToBuilderConfiguration(configuration),
+        ),
+      ),
+    },
+    {
+      name: "model_configuration_object",
+      value: JSON.stringify(
+        modelConfigurationToJson(
+          flowConfigurationToModelConfiguration(configuration),
+        ),
+      ),
+    },
+  ];
+
+  // Flow-derived selfie liveness telemetry — appended only for selfie flows.
+  const liveness = flowConfigurationToSelfieLivenessTelemetry(configuration);
+  if (liveness.activeLivenessType !== null) {
+    entries.push(
+      { name: "active_liveness_type", value: liveness.activeLivenessType },
+      {
+        name: "active_liveness_version",
+        value: liveness.activeLivenessVersion,
+      },
+      { name: "selfie_image_origin", value: liveness.selfieImageOrigin },
+    );
+  }
+  return entries;
+}
+
+type SelfieLivenessTelemetry =
+  | {
+      readonly activeLivenessType: string;
+      readonly activeLivenessVersion: string;
+      readonly selfieImageOrigin: string;
+    }
+  | {
+      readonly activeLivenessType: null;
+      readonly activeLivenessVersion: null;
+      readonly selfieImageOrigin: null;
+    };
+
+/**
+ * Flow-derived selfie liveness telemetry. All-`null` for flows without a selfie
+ * capture; otherwise the active-liveness check (`head_pose` when enhanced
+ * liveness is on, else `smile`), the version, and the selfie origin (always
+ * `front_camera` — the selfie SDK has no gallery path).
+ */
+export function flowConfigurationToSelfieLivenessTelemetry(
+  configuration: FlowConfiguration,
+): SelfieLivenessTelemetry {
+  let selfie: { enableEnhancedLiveness: boolean } | undefined;
+  let hasSelfieCapture = false;
+  for (const step of configuration.screens.steps) {
+    if (step.kind === "capture") {
+      selfie ??= step.config.selfieConfig;
+      if (step.config.captureType === CaptureType.selfie) {
+        hasSelfieCapture = true;
+      }
+    }
+  }
+  if (!hasSelfieCapture && selfie === undefined) {
+    return {
+      activeLivenessType: null,
+      activeLivenessVersion: null,
+      selfieImageOrigin: null,
+    };
+  }
+  return {
+    activeLivenessType: selfie?.enableEnhancedLiveness ? "head_pose" : "smile",
+    activeLivenessVersion: "2.0.0",
+    selfieImageOrigin: "front_camera",
+  };
+}
+
+function faceDescriptorOf(
+  key: AnalyzerFactoryKey | undefined,
+): ModelDescriptor {
+  switch (key) {
+    case AnalyzerFactoryKey.MLKitFace:
+      return {
+        provider: ModelProvider.Google,
+        name: "play-services-mlkit-face-detection",
+        version: "17.1.0",
+        bundled: false,
+      };
+    case AnalyzerFactoryKey.HuaweiFace:
+      return {
+        provider: ModelProvider.Huawei,
+        name: "ml-computer-vision-face",
+        version: "3.18.1.300",
+        bundled: false,
+      };
+    case AnalyzerFactoryKey.VisionFace:
+      return {
+        provider: ModelProvider.Apple,
+        name: "vision_face_detector",
+        version: "system",
+        bundled: true,
+      };
+    default:
+      return MODEL_DESCRIPTOR_UNKNOWN;
+  }
+}
+
+const NOOP_DOCUMENT_DESCRIPTOR: ModelDescriptor = {
+  provider: ModelProvider.Smile,
+  name: "noop_document_detector",
+  version: "12.0.0",
+  bundled: true,
+};

package/src/metadata/model_configuration.ts

@@ -0,0 +1,68 @@
+/**
+ * Client-side detection-model metadata appended to a job request as the
+ * `model_configuration_object` entry, so the server can attribute face /
+ * document detection behaviour to a concrete component and version during
+ * fraud analysis.
+ *
+ * `ModelProvider` is a stable lowercase wire token; `apple` covers detectors
+ * backed by Apple's Vision framework on iOS. New providers are additive.
+ */
+
+export const ModelProvider = {
+  Google: "google",
+  Huawei: "huawei",
+  Smile: "smile",
+  Apple: "apple",
+  Custom: "custom",
+} as const;
+
+export type ModelProvider = (typeof ModelProvider)[keyof typeof ModelProvider];
+
+export type ModelDescriptor = {
+  readonly provider: ModelProvider;
+  /** Human-readable model identifier (e.g. the native artefact id). */
+  readonly name: string;
+  /** The model / framework version in use on the device. */
+  readonly version: string;
+  /** `true` when the model ships with the app / OS, `false` when downloaded on demand. */
+  readonly bundled: boolean;
+};
+
+/**
+ * Placeholder used when the active model for a capture type cannot be
+ * resolved, so the `model_configuration_object` always carries both
+ * `face_model` and `document_model` rather than omitting a side.
+ */
+export const MODEL_DESCRIPTOR_UNKNOWN: ModelDescriptor = Object.freeze({
+  provider: ModelProvider.Custom,
+  name: "unknown",
+  version: "unknown",
+  bundled: false,
+});
+
+export type ModelConfiguration = {
+  readonly faceModel: ModelDescriptor;
+  readonly documentModel: ModelDescriptor;
+};
+
+/** Serialises a [ModelDescriptor] to its snake_case wire object. */
+export function modelDescriptorToJson(
+  descriptor: ModelDescriptor,
+): Record<string, unknown> {
+  return {
+    provider: descriptor.provider,
+    name: descriptor.name,
+    version: descriptor.version,
+    bundled: descriptor.bundled,
+  };
+}
+
+/** Serialises a [ModelConfiguration] to its snake_case wire object. */
+export function modelConfigurationToJson(
+  configuration: ModelConfiguration,
+): Record<string, unknown> {
+  return {
+    face_model: modelDescriptorToJson(configuration.faceModel),
+    document_model: modelDescriptorToJson(configuration.documentModel),
+  };
+}

package/src/metadata/optional_native_modules.ts

@@ -1,7 +1,8 @@
 /**
- * Lazy bridges to optional `expo-device` / `expo-network` peer deps.
- * Both are declared `optional: true` in `peerDependenciesMeta` so
- * partners who don't need richer metadata don't pay the install cost.
+ * Lazy bridges to optional `expo-device` / `expo-network` / `expo-battery` /
+ * `expo-cellular` peer deps. All are declared `optional: true` in
+ * `peerDependenciesMeta` so partners who don't need richer metadata don't pay
+ * the install cost.
  *
  * **Pattern:** dynamic `require()` wrapped in `try/catch`. Metro
  * tolerates the missing-module case without failing the build —
@@ -19,6 +20,14 @@ type DeviceModule = {
   readonly brand?: string | null;
   readonly supportedCpuArchitectures?: readonly string[] | null;
   readonly totalMemory?: number | null;
+  // Android `Build.DEVICE`; iOS leaves this null (use `modelId` instead).
+  readonly designName?: string | null;
+  // Android `Build.PRODUCT`.
+  readonly productName?: string | null;
+  // Android `Build.FINGERPRINT`.
+  readonly osBuildFingerprint?: string | null;
+  // iOS hardware identifier (e.g. `iPhone16,2`).
+  readonly modelId?: string | null;
 };
 
 type NetworkModule = {
@@ -30,8 +39,53 @@ type NetworkModule = {
   getIpAddressAsync?(): Promise<string>;
 };
 
+type BatteryModule = {
+  // expo-battery `BatteryState`: 0 unknown, 1 unplugged, 2 charging, 3 full.
+  getBatteryStateAsync(): Promise<number>;
+};
+
+type CellularModule = {
+  // Carrier name constant (may be null on Wi-Fi-only / dual-SIM devices).
+  readonly carrier?: string | null;
+};
+
+type AsyncStorageModule = {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+};
+
+/** Subscription returned by `Accelerometer.addListener`. */
+export type AccelerometerSubscription = { remove(): void };
+
+/** Minimal `expo-sensors` surface used for device_positions / device_movement_detected. */
+type SensorsModule = {
+  Accelerometer: {
+    setUpdateInterval(intervalMs: number): void;
+    addListener(
+      listener: (data: { x: number; y: number; z: number }) => void,
+    ): AccelerometerSubscription;
+  };
+};
+
+/** Minimal `expo-location` surface used for the geolocation metadata. */
+type LocationModule = {
+  getForegroundPermissionsAsync(): Promise<{ granted: boolean }>;
+  getLastKnownPositionAsync(): Promise<{
+    coords: {
+      latitude: number;
+      longitude: number;
+      accuracy: number | null;
+    };
+  } | null>;
+};
+
 let _device: DeviceModule | null | undefined;
 let _network: NetworkModule | null | undefined;
+let _battery: BatteryModule | null | undefined;
+let _cellular: CellularModule | null | undefined;
+let _asyncStorage: AsyncStorageModule | null | undefined;
+let _sensors: SensorsModule | null | undefined;
+let _location: LocationModule | null | undefined;
 
 /**
  * Load `expo-device`'s native module once, cached for the process
@@ -113,8 +167,108 @@ export function loadExpoNetwork(): NetworkModule | null {
   return _network;
 }
 
+/**
+ * Load `expo-battery`'s native module once, cached for the process lifetime.
+ * Returns `null` when the native module isn't linked (graceful degradation).
+ * Mirrors [loadExpoDevice] — pulls the raw `ExpoBattery` native module via
+ * `expo-modules-core`'s non-throwing `requireOptionalNativeModule`.
+ */
+export function loadExpoBattery(): BatteryModule | null {
+  if (_battery !== undefined) return _battery;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const core = require("expo-modules-core") as {
+      requireOptionalNativeModule?: <T>(name: string) => T | null;
+    };
+    _battery =
+      core.requireOptionalNativeModule?.<BatteryModule>("ExpoBattery") ?? null;
+  } catch {
+    _battery = null;
+  }
+  return _battery;
+}
+
+/**
+ * Load `expo-cellular`'s native module once, cached for the process lifetime.
+ * Returns `null` when the native module isn't linked (graceful degradation).
+ * The raw `ExpoCellular` module exposes the `carrier` name constant directly.
+ */
+export function loadExpoCellular(): CellularModule | null {
+  if (_cellular !== undefined) return _cellular;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const core = require("expo-modules-core") as {
+      requireOptionalNativeModule?: <T>(name: string) => T | null;
+    };
+    _cellular =
+      core.requireOptionalNativeModule?.<CellularModule>("ExpoCellular") ??
+      null;
+  } catch {
+    _cellular = null;
+  }
+  return _cellular;
+}
+
+/**
+ * Load `@react-native-async-storage/async-storage` once, cached for the process
+ * lifetime. Returns `null` when the package isn't installed (graceful
+ * degradation). Unlike the expo modules, async-storage's JS entry does not throw
+ * at import when the native side is missing, so a plain `require` (wrapped in
+ * try/catch for the not-installed case) is sufficient; per-call native errors
+ * are handled by the caller. Backed by Android `SharedPreferences` /
+ * iOS `NSUserDefaults`.
+ */
+export function loadAsyncStorage(): AsyncStorageModule | null {
+  if (_asyncStorage !== undefined) return _asyncStorage;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const module = require("@react-native-async-storage/async-storage") as {
+      default?: AsyncStorageModule;
+    } & AsyncStorageModule;
+    _asyncStorage = module.default ?? module;
+  } catch {
+    _asyncStorage = null;
+  }
+  return _asyncStorage;
+}
+
+/**
+ * Load `expo-sensors` for accelerometer sampling. Returns `null` when the peer
+ * dep isn't installed/linked (graceful degradation — device_positions omitted).
+ */
+export function loadExpoSensors(): SensorsModule | null {
+  if (_sensors !== undefined) return _sensors;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    _sensors = require("expo-sensors") as SensorsModule;
+  } catch {
+    _sensors = null;
+  }
+  return _sensors;
+}
+
+/**
+ * Load `expo-location` for the geolocation metadata. Returns `null` when the
+ * peer dep isn't installed/linked (graceful degradation — geolocation omitted).
+ */
+export function loadExpoLocation(): LocationModule | null {
+  if (_location !== undefined) return _location;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    _location = require("expo-location") as LocationModule;
+  } catch {
+    _location = null;
+  }
+  return _location;
+}
+
 /** Test-only seam — clears the module cache so tests can re-evaluate. */
 export function _resetOptionalModulesForTesting(): void {
   _device = undefined;
   _network = undefined;
+  _battery = undefined;
+  _cellular = undefined;
+  _asyncStorage = undefined;
+  _sensors = undefined;
+  _location = undefined;
 }