@smileid/usesmileid 12.0.0-beta01

package/src/presentation/flow/use_smile_id_flow.tsx

@@ -0,0 +1,338 @@
+import { useEffect, useMemo, useReducer, useRef } from "react";
+import { Text, useColorScheme, View } from "react-native";
+import type { FlowConfiguration } from "./config/flow_configuration";
+import type { FlowBuildResult } from "./dsl/flow_build_result";
+import {
+  FlowNavigationManager,
+  type FlowExitReason,
+} from "./flow_navigation_manager";
+import { FlowNavigationProvider } from "./flow_navigation_context";
+import { ScreenRenderer } from "./graph/screen_renderer";
+import { defaultDarkTheme, defaultLightTheme } from "../theme/theme";
+import { UseSmileIDThemeProvider } from "../theme/theme_context";
+import { useUseSmileIDFonts } from "../theme/use_use_smile_id_fonts";
+import { UseSmileIDCrashReporting } from "@smileid/usesmileid_bridge";
+import { generateSessionId } from "../../metadata/use_smile_id_metadata_factory";
+import { UseSmileIDLocalizationsProvider } from "../../l10n/use_smile_id_localizations_provider";
+import { UseSmileIDLocalizations } from "../../l10n/use_smile_id_localizations";
+import {
+  cancelled,
+  failure,
+  success,
+  type UseSmileIDResult,
+} from "../../core/models/result";
+import type { JobSubmissionResponse } from "../../data/model/job_submission_response";
+import { ValidationErrorScreen } from "./screen/validation_error_screen";
+import { BuilderValidationException } from "../../core/exception/builder_validation_exception";
+import { makeNetworkingFactory } from "../../data/factory/networking_factory";
+import { UseSmileIDRepositoryImpl } from "../../data/repository/use_smile_id_repository_impl";
+import type { UseSmileIDRepository } from "../../data/repository/use_smile_id_repository";
+import type { MetadataProvider } from "../../metadata/use_smile_id_metadata_factory";
+import {
+  RetryStrategy,
+  type RetryConfig,
+} from "../../core/models/network_config";
+
+/**
+ * Default retry policy when partner omits `b.network((n) => n.retry(...))`.
+ * Matches the `RetryConfigBuilder` defaults so behaviour stays consistent
+ * whether the partner constructs `network.retry` explicitly or not.
+ */
+const DEFAULT_RETRY: RetryConfig = Object.freeze({
+  maxAttempts: 3,
+  strategy: RetryStrategy.exponential,
+  initialDelay: 1,
+  multiplier: 2,
+  maxDelay: 32,
+  jitter: 0.2,
+  fixedDelay: 1,
+});
+
+export type FlowInvalidDispatcherProps = {
+  readonly result: Extract<FlowBuildResult, { kind: "invalid" }>;
+  readonly onResult: (result: UseSmileIDResult<JobSubmissionResponse>) => void;
+  readonly enableDebugMode: boolean;
+};
+
+/**
+ * Routes the validation failure through the partner's `onResult`
+ * after first paint. When `enableDebugMode` is set on the builder,
+ * additionally renders [ValidationErrorScreen] with every failed
+ * rule so the partner has a complete picture during development.
+ * Production renders nothing — `onResult.failure` is the only
+ * surface partners see.
+ *
+ * `onResult` and `enableDebugMode` are passed in as separate props
+ * (sourced from the builder reference by `<UseSmileIDBuilder>`) rather
+ * than embedded on the `result`.
+ *
+ * @internal Used by `<UseSmileIDBuilder>`.
+ */
+export function FlowInvalidDispatcher({
+  result,
+  onResult,
+  enableDebugMode,
+}: FlowInvalidDispatcherProps) {
+  const onResultRef = useRef(onResult);
+  onResultRef.current = onResult;
+  const validationRef = useRef(result.validation);
+  validationRef.current = result.validation;
+
+  useEffect(() => {
+    // Wrap the typed validation state in a BuilderValidationException
+    // so partner code receiving the failure via onResult.failure can
+    // inspect every rule that failed via `error.validationState.issues`,
+    // not only the first. The exception itself extends Error, so
+    // `instanceof Error` checks keep working.
+    const error = new BuilderValidationException(validationRef.current);
+    try {
+      onResultRef.current(failure(error));
+    } catch (handlerError) {
+      UseSmileIDCrashReporting.captureException(handlerError);
+    }
+  }, []);
+
+  if (enableDebugMode) {
+    return <ValidationErrorScreen validationState={result.validation} />;
+  }
+  return null;
+}
+
+export type FlowSuccessRendererProps = {
+  readonly configuration: FlowConfiguration;
+};
+
+/**
+ * Walks the partner through the configured screen list, dispatches
+ * frames to the chosen analyzer, submits the resulting artifacts, and
+ * notifies the partner via `configuration.onResult`.
+ *
+ * **What's wired today:**
+ *   - `FlowNavigationManager` cursor — `navigateToNext()` /
+ *     `navigateBack()` advance the screen index and subscribers re-render.
+ *   - Crash reporting lifecycle — `enable()` on mount when
+ *     `configuration.config.enableCrashReporting !== false`, `disable()`
+ *     on unmount.
+ *   - Localizations resolution — explicit override → device-locale
+ *     auto-resolve → English defaults.
+ *   - Exit handling — converts `FlowExitReason` to `UseSmileIDResult`
+ *     and calls `configuration.onResult` (wrapped in try/catch routing
+ *     partner-handler exceptions through crash reporting).
+ *
+ * **Still stub:** the screen visuals themselves (see `screens/*.tsx`)
+ * and the analyzer-dispatch + job-submission pipeline. Cursor moves
+ * end-to-end today; analyzer wire-up is the next milestone.
+ *
+ * @internal Used by `<UseSmileIDBuilder>`.
+ */
+export function FlowSuccessRenderer({
+  configuration,
+}: FlowSuccessRendererProps) {
+  // System color-scheme picks the variant. The partner-supplied theme
+  // bundle carries both light and dark resolved tokens; SDK defaults
+  // are used when the partner skips `b.theme((t) => …)`.
+  const systemScheme = useColorScheme();
+  const isDark = systemScheme === "dark";
+  const theme = configuration.theme
+    ? isDark
+      ? configuration.theme.dark
+      : configuration.theme.light
+    : isDark
+      ? defaultDarkTheme
+      : defaultLightTheme;
+
+  // Registers the bundled DM Sans faces (no-op after the first flow).
+  // Rendering does not wait on this — text re-renders into DM Sans the
+  // moment registration completes.
+  useUseSmileIDFonts();
+  const enableCrashReporting =
+    configuration.config?.enableCrashReporting !== false;
+
+  // Per-flow session id used as the Sentry user-id so every event
+  // captured during this verification flow correlates under one issue
+  // thread. Generated once per mount; survives re-renders via `useRef`
+  // — useMemo would re-run if React decided to swap the inner element
+  // identity, but the id must outlive any render churn.
+  const flowSessionIdRef = useRef<string | null>(null);
+  if (flowSessionIdRef.current === null) {
+    flowSessionIdRef.current = generateSessionId();
+  }
+
+  useEffect(() => {
+    if (enableCrashReporting) {
+      UseSmileIDCrashReporting.enable();
+      UseSmileIDCrashReporting.setUserId(flowSessionIdRef.current!);
+      UseSmileIDCrashReporting.captureBreadcrumb({
+        category: "flow.navigation",
+        message: "flow mounted",
+      });
+    }
+    return () => {
+      UseSmileIDCrashReporting.disable();
+    };
+  }, [enableCrashReporting]);
+
+  // `onResult` lives in a ref so the manager's `onExit` closure
+  // captures the latest partner callback without recreating the
+  // manager on every parent render.
+  const onResultRef = useRef(configuration.onResult);
+  onResultRef.current = configuration.onResult;
+
+  // Force-update reducer drives re-renders when the manager's cursor
+  // or captured artifacts change. Cheaper than mirroring state into
+  // React state — the manager is the single source of truth.
+  const [, forceUpdate] = useReducer((x: number) => x + 1, 0);
+
+  // Repository is built once per `network` config — partner-supplied
+  // `partnerConfig` is required (the auth interceptor stamps the
+  // partner-supplied `token` and `partnerId` onto every request).
+  // When omitted, the
+  // manager surfaces a `failure` state from `_assembleJob` rather
+  // than crashing on construction; this lets capture-only / UI-only
+  // smoke harnesses mount `<UseSmileIDBuilder>` without network.
+  // Repository + the per-flow metadata provider are built together
+  // from a single `makeNetworkingFactory` call so they share one
+  // metadata factory (stable `session_id` across every submission).
+  // The provider is handed to the manager, which stamps a fresh
+  // snapshot onto each assembled `JobRequest`; the repository's API
+  // layer then serializes `request.metadata` as the `metadata`
+  // multipart part.
+  const submission = useMemo<
+    | { repository: UseSmileIDRepository; metadataProvider: MetadataProvider }
+    | undefined
+  >(() => {
+    const network = configuration.network;
+    if (!network?.config?.partnerConfig) return undefined;
+    const { api, metadata } = makeNetworkingFactory(network);
+    const retry = network.retry ?? DEFAULT_RETRY;
+    return {
+      repository: new UseSmileIDRepositoryImpl(api, retry),
+      metadataProvider: metadata,
+    };
+  }, [configuration.network]);
+
+  const manager = useMemo(() => {
+    const handleExit = (reason: FlowExitReason) => {
+      const onResult = onResultRef.current;
+      try {
+        if (reason.kind === "completed") {
+          // `reason.job` carries the full `JobSubmissionResponse` from
+          // the successful submission. When the flow completes without
+          // a successful submission (e.g. no processing screen wired),
+          // string fields are empty.
+          onResult(success(reason.job));
+        } else if (reason.kind === "cancelled") {
+          // User deliberately exited (e.g. back out of the first screen).
+          // A distinct cancelled result — not a failure.
+          onResult(cancelled());
+        } else {
+          onResult(failure(reason.error));
+        }
+      } catch (handlerError) {
+        // Concrete scenario: partner's `onResult` throws (e.g. their
+        // navigation stack is in an invalid state). Don't let that
+        // crash the SDK — capture and continue.
+        UseSmileIDCrashReporting.captureException(handlerError);
+      }
+    };
+    return new FlowNavigationManager({
+      configuration,
+      onExit: handleExit,
+      // Conditional spread — `exactOptionalPropertyTypes: true` rejects
+      // an explicit `undefined` for the optional `repository` /
+      // `metadataProvider` fields. Both come from the same memoized
+      // `submission` object so the metadata factory backing requests
+      // is the same one the API serializes.
+      ...(submission
+        ? {
+            repository: submission.repository,
+            metadataProvider: submission.metadataProvider,
+          }
+        : {}),
+    });
+    // Manager is intentionally instantiated once per `configuration` /
+    // `submission` reference. Partners should memoize `configuration` via
+    // `useMemo<FlowConfiguration>(...)`; if they swap to a new flow they
+    // should remount `<UseSmileIDBuilder>`.
+  }, [configuration, submission]);
+
+  useEffect(() => {
+    const unsubscribe = manager.subscribe(forceUpdate);
+    return () => {
+      unsubscribe();
+      manager.dispose();
+    };
+  }, [manager]);
+
+  // Resolve localizations:
+  //   1. Explicit `configuration.localizations` (partner-set on the
+  //      builder) — wins over everything.
+  //   2. Auto-resolved from the registry via the device locale
+  //      (`UseSmileIDLocalizations.forActiveLocale()`) when partners
+  //      registered locales with `UseSmileIDLocalizations.register(...)`.
+  //   3. English defaults — no provider mounted, screens read from
+  //      the context's default English-only instance.
+  const resolved = useMemo(() => {
+    if (configuration.localizations) return configuration.localizations;
+    if (UseSmileIDLocalizations.hasRegisteredLocales()) {
+      return UseSmileIDLocalizations.forActiveLocale();
+    }
+    return null;
+  }, [configuration.localizations]);
+
+  const step = manager.currentScreen;
+
+  // Empty-screens sentinel: a partner who forgot to call
+  // `b.screens(...)` would otherwise see a blank screen with no clue
+  // why. Render an explicit hint instead.
+  const inner = step ? (
+    <FlowNavigationProvider manager={manager}>
+      <ScreenRenderer
+        key={`${manager.currentDepth}:${step.kind}`}
+        step={step}
+      />
+    </FlowNavigationProvider>
+  ) : (
+    <View
+      style={{
+        flex: 1,
+        alignItems: "center",
+        justifyContent: "center",
+        backgroundColor: theme.colors.background,
+        padding: theme.spacing.large,
+      }}
+    >
+      <Text
+        style={{
+          ...theme.typography.pageHeading,
+          color: theme.colors.titleText,
+        }}
+      >
+        UseSmileID
+      </Text>
+      <Text style={{ ...theme.typography.body, color: theme.colors.cardText }}>
+        {
+          "No screens configured — call `b.screens((screens) => screens.instructions(); ...)`"
+        }
+      </Text>
+    </View>
+  );
+
+  // Theme provider always mounts so deep partner widgets can read
+  // via `useUseSmileIDTheme()` without having to wrap manually.
+  // Localizations provider only mounts when registered locales
+  // resolve — the context default (English) covers the no-provider
+  // path without an extra wrapper.
+  const themed = (
+    <UseSmileIDThemeProvider value={theme}>{inner}</UseSmileIDThemeProvider>
+  );
+
+  if (resolved) {
+    return (
+      <UseSmileIDLocalizationsProvider value={resolved}>
+        {themed}
+      </UseSmileIDLocalizationsProvider>
+    );
+  }
+  return themed;
+}