@smileid/usesmileid 12.0.1 → 12.1.0

package/src/presentation/flow/dsl/use_smile_id_builder.tsx

@@ -1,125 +0,0 @@
-import { useMemo } from "react";
-import {
-  FlowInvalidDispatcher,
-  FlowSuccessRenderer,
-} from "../use_smile_id_flow";
-import {
-  UseSmileIDFlowBuilder,
-  type FlowConfigurationSnapshot,
-} from "./use_smile_id_flow_builder";
-import type { FlowBuildResult } from "./flow_build_result";
-
-/**
- * Entry point for a UseSmileID identity-verification flow. Host this in
- * your UI and configure the flow inside the builder closure — declare
- * the screens, network credentials, theme, and ML analyzers, then handle
- * the terminal outcome via `onResult`. The component owns the
- * build-and-dispatch lifecycle internally — partners never touch the
- * intermediate [FlowBuildResult].
- *
- *     export function VerifyScreen({ onComplete }) {
- *       return (
- *         <UseSmileIDBuilder
- *           builder={(b) => {
- *             b.network((n) => n.config((c) => {
- *               c.jobType = JobType.smartSelfieEnrollment;
- *               c.token = '...';
- *               c.partnerConfig((p) => { p.partnerId = '...'; });
- *             }));
- *             b.ml((m) => m.analyzers((a) => {
- *               a.forCaptureType(CaptureType.selfie, (face) => face.add(useSmileIDVisionFace));
- *             }));
- *             b.screens((screens) => {
- *               screens.instructions();
- *               screens.capture((c) => { c.captureType = CaptureType.selfie; });
- *               screens.preview();
- *             });
- *             b.onResult = (result) => { ... onComplete(); };
- *           }}
- *         />
- *       );
- *     }
- *
- * Validation outcomes:
- *   - Success → renders the configured screen flow.
- *   - Invalid → fires `b.onResult.failure` with a typed
- *     `BuilderValidationException`. Additionally renders a
- *     debug-only `ValidationErrorScreen` when
- *     `b.config((c) => c.enableDebugMode = true)` is set.
- *
- * The `builder` closure runs once when the component mounts. Partners
- * that need to recompute the flow on prop changes should remount via
- * a `key` prop on `<UseSmileIDBuilder>` rather than mutate the
- * closure's captures in place.
- */
-export type UseSmileIDBuilderProps = {
-  readonly builder: (b: UseSmileIDFlowBuilder) => void;
-};
-
-export function UseSmileIDBuilder({ builder }: UseSmileIDBuilderProps) {
-  // Builder closure intentionally runs once per mount — flow
-  // configuration is captured at first render and not meant to
-  // mutate after.
-  //
-  // `onResult` and `enableDebugMode` are snapshotted off the partial
-  // builder state into `invalidMeta` so the invalid-branch dispatcher
-  // can route the failure through the partner callback and decide
-  // whether to render the debug screen. Neither piece is recoverable
-  // from a malformed configuration alone, but they're not part of
-  // the partner-visible `FlowBuildResult` shape — that matches the
-  // single-field invalid case the other 3 SDKs ship.
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  const { result, invalidMeta } = useMemo(() => {
-    const flowBuilder = new UseSmileIDFlowBuilder();
-    builder(flowBuilder);
-    const built = flowBuilder.build();
-    return {
-      result: built,
-      invalidMeta: {
-        onResult: flowBuilder.onResult,
-        enableDebugMode:
-          (
-            flowBuilder as unknown as {
-              _config?: { build(): { enableDebugMode: boolean } };
-            }
-          )._config?.build().enableDebugMode === true,
-      },
-    };
-  }, []);
-  if (result.kind === "invalid") {
-    return (
-      <FlowInvalidDispatcher
-        result={result}
-        onResult={invalidMeta.onResult}
-        enableDebugMode={invalidMeta.enableDebugMode}
-      />
-    );
-  }
-  return <FlowSuccessRenderer configuration={result.configuration} />;
-}
-
-/**
- * Function form of the builder, retained for tests and any partner
- * code that wants to inspect the [FlowBuildResult] before rendering
- * (for example, a custom failure UI). Most partners should use the
- * `<UseSmileIDBuilder>` component instead.
- *
- * @internal
- */
-export function useSmileIDBuilder(
-  configure: (builder: UseSmileIDFlowBuilder) => void,
-): FlowBuildResult {
-  const builder = new UseSmileIDFlowBuilder();
-  configure(builder);
-  return builder.build();
-}
-
-export {
-  UseSmileIDFlowBuilder,
-  type FlowConfigurationSnapshot,
-} from "./use_smile_id_flow_builder";
-export type {
-  FlowBuildResult,
-  FlowBuildResultSuccess,
-  FlowBuildResultInvalid,
-} from "./flow_build_result";

package/src/presentation/flow/dsl/use_smile_id_flow_builder.ts

@@ -1,428 +0,0 @@
-import type { ConfigOptions } from "../../../core/models/config";
-import type { ThemeConfiguration } from "./builder/theme_builder";
-import type { NetworkConfig } from "../../../core/models/network_config";
-import type { MLConfig } from "../../../core/models/ml_config";
-import type {
-  ConsentInformation,
-  EnhancedKYCParams,
-  BiometricKYCParams,
-  DocumentVerificationParams,
-  EnhancedDocumentVerificationParams,
-  UserDetails,
-} from "../../../core/models/params";
-import type { UseSmileIDAnalyticsEvent } from "../analytics/use_smile_id_analytics_event";
-import type { JobSubmissionResponse } from "../../../data/model/job_submission_response";
-import type { UseSmileIDResult } from "../../../core/models/result";
-import type { ScreensConfig } from "./builder/screens_builder";
-import { UseSmileIDConfigBuilder } from "./builder/config_builder";
-import { ThemeConfigBuilder } from "./builder/theme_builder";
-import { UseSmileIDNetworkBuilder } from "../../../data/dsl/use_smile_id_network_builder";
-import { UseSmileIDMLBuilder } from "./builder/ml_builder";
-import { ScreensBuilder } from "./builder/screens_builder";
-import type { UseSmileIDLocalizations } from "../../../l10n/use_smile_id_localizations";
-import {
-  firstErrorIssue,
-  runBiometricKYCParamsValidation,
-  runBuilderValidation,
-  runConsentValidation,
-  runDocumentVerificationParamsValidation,
-  runEnhancedDocumentVerificationParamsValidation,
-  runEnhancedKYCParamsValidation,
-  runFlowValidation,
-  runUserDetailsValidation,
-} from "../validation/flow_validator";
-import { ValidationState } from "../validation/validation_state";
-import type { FlowBuildResult } from "./flow_build_result";
-
-/**
- * Top-level DSL builder.
- *
- * Closure-based block methods (`config`, `theme`, `network`, `ml`,
- * `screens`) configure each section; mutable top-level properties
- * (`consentInformation`, `enhancedKYCParams`, `biometricKYCParams`,
- * `onResult`, `onAnalyticsEvent`) are assigned directly. The server
- * issues `userId` / `jobId` and returns them in the submission
- * response — partners receive them via `onResult`.
- */
-export class UseSmileIDFlowBuilder {
-  /**
-   * Optional. Pre-supplied consent — if set, the consent screen is
-   * skipped.
-   */
-  consentInformation?: ConsentInformation;
-
-  /** Optional. Required only for `JobType.enhancedKyc`. */
-  enhancedKYCParams?: EnhancedKYCParams;
-
-  /** Optional. Required only for `JobType.biometricKyc`. */
-  biometricKYCParams?: BiometricKYCParams;
-
-  /** Optional. Required only for `JobType.documentVerification`. */
-  documentVerificationParams?: DocumentVerificationParams;
-
-  /** Optional. Required only for `JobType.enhancedDocumentVerification`. */
-  enhancedDocumentVerificationParams?: EnhancedDocumentVerificationParams;
-
-  /**
-   * Required for any job that submits the `user_details` multipart
-   * part — `JobType.enhancedKyc`, `JobType.biometricKyc`,
-   * `JobType.smartSelfieEnrollment`, `JobType.smartSelfieAuthentication`
-   * (plus the two Enhanced selfie aliases). The same shape is sent on
-   * the wire as a JSON multipart part with snake_case keys.
-   *
-   * Previously carried inside `enhancedKYCParams` / `biometricKYCParams`
-   * — consolidated here so the smartSelfie* endpoints can carry it too
-   * (their v3 wire format also requires `user_details`).
-   */
-  userDetails?: UserDetails;
-
-  /**
-   * Required for `JobType.smartSelfieAuthentication` (and its enhanced
-   * alias). The v3 `/v3/authentication` endpoint requires the partner to
-   * pass the `user_id` returned from a prior enrollment so the server
-   * can match the authentication attempt to the existing enrollment.
-   * Sent on the wire as a `user_id` multipart text form field.
-   */
-  userId?: string;
-
-  /**
-   * Optional. Locale-resolved string overrides. The flow component
-   * wraps its tree with `<UseSmileIDLocalizationsProvider>` when this
-   * is set so all SDK screens read from it. Partners use any i18n
-   * stack to pick the right map and pass it here.
-   *
-   * If unset, screens render the canonical English defaults bundled
-   * with `strings_en.ts`.
-   */
-  localizations?: UseSmileIDLocalizations;
-
-  /**
-   * Invoked once when the flow terminates — with the submitted job on
-   * success, a typed error on failure, or a cancellation when the user
-   * exits before completing. Wire the returned user id / job id into
-   * your job-status pipeline. Defaults to a no-op so partners who don't
-   * need result handling still get a valid configuration; the
-   * server-issued `JobSubmissionResponse` carries `userId` / `jobId` /
-   * `status` / `message` / `createdAt`.
-   */
-  onResult: (result: UseSmileIDResult<JobSubmissionResponse>) => void =
-    () => {};
-
-  /**
-   * Invoked for every analytics event the SDK emits during the flow.
-   * Optional — leave unset to ignore analytics.
-   */
-  onAnalyticsEvent?: (event: UseSmileIDAnalyticsEvent) => void;
-
-  // --- Internal block builders ---------------------------------------------
-
-  private _config?: UseSmileIDConfigBuilder;
-  private _theme?: ThemeConfigBuilder;
-  private _network?: UseSmileIDNetworkBuilder;
-  private _ml?: UseSmileIDMLBuilder;
-  private _screens?: ScreensBuilder;
-
-  /**
-   * Configures global SDK feature flags (debug mode, offline mode, crash
-   * reporting). Repeated calls compose against the same configuration —
-   * `enableCrashReporting` set in one call and `enableDebugMode` set in
-   * another both end up on the final config.
-   *
-   * `b.config((c) => { c.enableCrashReporting = false; })`
-   */
-  config(block: (c: UseSmileIDConfigBuilder) => void): void {
-    if (!this._config) this._config = new UseSmileIDConfigBuilder();
-    block(this._config);
-  }
-
-  /**
-   * Configures the visual theme — colors, fonts, and corner shapes —
-   * applied to every SDK screen in the flow.
-   *
-   * `b.theme((t) => { t.primaryColor = t.color('#1A73E8', '#4DA3FF'); t.buttonShape = 12; })`
-   *
-   * Each call replaces the prior theme builder — partners typically
-   * configure the theme in one place, and accumulating across helpers
-   * tends to surface as a fight over which call wrote `primaryColor`
-   * last. Replace semantics make the precedence local and obvious.
-   */
-  theme(block: (t: ThemeConfigBuilder) => void): void {
-    this._theme = new ThemeConfigBuilder();
-    block(this._theme);
-  }
-
-  /**
-   * Configures the network stack: partner credentials, job type,
-   * timeouts, retry policy, response cache, and custom interceptors.
-   * Required for any flow that submits a job.
-   *
-   * `b.network((n) => { n.config((c) => { c.partnerConfig((p) => { p.partnerId = ...; }); }); })`
-   *
-   * Each call replaces the prior network builder. Network config
-   * carries credentials and a job type, so partial composition across
-   * helpers is more likely to mask configuration errors than to help.
-   */
-  network(block: (n: UseSmileIDNetworkBuilder) => void): void {
-    this._network = new UseSmileIDNetworkBuilder();
-    block(this._network);
-  }
-
-  /**
-   * Registers the on-device ML analyzers used for face and document
-   * detection, keyed by capture type.
-   *
-   * `b.ml((m) => { m.analyzers((a) => { a.forCaptureType(CaptureType.selfie, (face) => face.add(useSmileIDVisionFace)); }); })`
-   */
-  ml(block: (m: UseSmileIDMLBuilder) => void): void {
-    if (!this._ml) this._ml = new UseSmileIDMLBuilder();
-    block(this._ml);
-  }
-
-  /**
-   * Declares the ordered sequence of screens the flow presents. Screens
-   * render in the order they are added; the same screen type may be
-   * added more than once.
-   *
-   * `b.screens((screens) => { screens.instructions(); screens.capture((c) => { c.captureType = CaptureType.selfie; }); })`
-   *
-   * Each screen-builder call appends a step to the orchestrator's
-   * flow list in declaration order.
-   */
-  screens(block: (s: ScreensBuilder) => void): void {
-    if (!this._screens) this._screens = new ScreensBuilder();
-    block(this._screens);
-  }
-
-  /**
-   * Runs a pre-flight check of the current builder configuration and
-   * returns a `ValidationState` describing any blocking issues, without
-   * throwing. Today the only rule it surfaces is the empty-screens-block
-   * error — `b.screens` must register at least one screen before the
-   * builder can produce a flow.
-   *
-   * The full rule set (screen ordering, dependency rules, KYC and
-   * consent payload validation, etc.) runs inside `build()` and is
-   * reflected in the [FlowBuildResult] surface; partners that want
-   * the full picture during configuration should call
-   * `useSmileIDBuilder(...)` and pattern-match on the returned
-   * `result.kind`.
-   *
-   * @returns a `ValidationState` describing any blocking issues.
-   */
-  validate(): ValidationState {
-    return ValidationState.invalid(
-      runBuilderValidation(this._screens?.build().steps ?? []),
-    );
-  }
-
-  /**
-   * Validates a `ConsentInformation` payload in isolation and returns a
-   * `ValidationState`, without throwing. Useful when the payload comes
-   * from dynamic partner storage or remote config — pre-flight it before
-   * assigning to `b.consentInformation`.
-   */
-  validateConsent(consent: ConsentInformation): ValidationState {
-    return ValidationState.invalid(runConsentValidation(consent));
-  }
-
-  /**
-   * Validates an `EnhancedKYCParams` payload in isolation and returns a
-   * `ValidationState`, without throwing. Useful when the partner pulls
-   * KYC fields from a form or remote config and wants to pre-flight them
-   * before assigning to `b.enhancedKYCParams`.
-   */
-  validateEnhancedKYCParams(params: EnhancedKYCParams): ValidationState {
-    return ValidationState.invalid(runEnhancedKYCParamsValidation(params));
-  }
-
-  /**
-   * Validates a `BiometricKYCParams` payload in isolation and returns a
-   * `ValidationState`, without throwing.
-   */
-  validateBiometricKYCParams(params: BiometricKYCParams): ValidationState {
-    return ValidationState.invalid(runBiometricKYCParamsValidation(params));
-  }
-
-  /**
-   * Validates a `DocumentVerificationParams` payload in isolation and
-   * returns a `ValidationState`, without throwing. Only `country` is
-   * required; `idType` is optional.
-   */
-  validateDocumentVerificationParams(
-    params: DocumentVerificationParams,
-  ): ValidationState {
-    return ValidationState.invalid(
-      runDocumentVerificationParamsValidation(params),
-    );
-  }
-
-  /**
-   * Validates an `EnhancedDocumentVerificationParams` payload in
-   * isolation and returns a `ValidationState`, without throwing. Both
-   * `country` and `idType` are required.
-   */
-  validateEnhancedDocumentVerificationParams(
-    params: EnhancedDocumentVerificationParams,
-  ): ValidationState {
-    return ValidationState.invalid(
-      runEnhancedDocumentVerificationParamsValidation(params),
-    );
-  }
-
-  /**
-   * Validates a `UserDetails` payload in isolation and returns a
-   * `ValidationState`, without throwing. Useful when the partner pulls
-   * user PII from a form or remote config and wants to pre-flight it
-   * before assigning to `b.userDetails`. Surfaces the same dotted-path
-   * field names (`userDetails.givenNames` etc.) that the in-build
-   * validator emits.
-   */
-  validateUserDetails(userDetails: UserDetails): ValidationState {
-    return ValidationState.invalid(runUserDetailsValidation(userDetails));
-  }
-
-  /**
-   * Snapshot the current builder state and report the validation
-   * outcome as a [FlowBuildResult]. Returns `{kind: 'success', ...}`
-   * when every rule passed, or `{kind: 'invalid', ...}` carrying the
-   * issues, the partner's `onResult` callback, and the resolved
-   * `enableDebugMode` flag so the wrapper can route the failure
-   * through `onResult.failure` and decide whether to render the
-   * debug screen.
-   *
-   * Internal — partners use `<UseSmileIDBuilder>`, which calls this
-   * method and dispatches on `kind` (success → render flow, invalid →
-   * fire `onResult.failure(BuilderValidationException)` and optionally
-   * render the debug screen).
-   *
-   * Validation rules (see `validate()` for non-throwing access from
-   * inside a builder closure):
-   *   1. The screens list must not be empty.
-   *   2. Screen ordering: consent must be first if present; processing
-   *      must be last if present; instructions must come before any
-   *      capture; every preview must be preceded by a capture.
-   *   3. Duplicate screen types are rejected (capture is exempt — a
-   *      flow may have both selfie and document capture).
-   *   4. ML configuration is required when any capture screen is
-   *      present.
-   *   5. Network configuration is required when a processing screen
-   *      is present.
-   *   6. The configured `jobType` may not be `unknown` once a
-   *      processing screen is wired.
-   *   7. Pre-supplied `consentInformation` and an in-flow consent
-   *      screen are mutually exclusive — exactly one source.
-   *   8. When set, `consentInformation` must have `granted: true`,
-   *      non-blank `grantedAt`, `noticeLanguage`, and
-   *      `noticePrivacyPolicyUrl`, and `grantedAt` must not parse to
-   *      a future timestamp.
-   *   9. When set, `EnhancedKYCParams` and `BiometricKYCParams` must
-   *      have non-blank `idType`, `idNumber`, `country`, and a
-   *      `userDetails` whose `givenNames` and `lastName` are non-blank
-   *      and whose `email` or `phoneNumber` (at least one) is set.
-   *
-   * @internal
-   */
-  build(): FlowBuildResult {
-    const screens = this._screens?.build();
-    const network = this._network?.build();
-    const mlConfig = this._ml?.build();
-
-    const issues = runFlowValidation({
-      steps: screens?.steps ?? [],
-      network,
-      ml: mlConfig,
-      consentInformation: this.consentInformation,
-      enhancedKYCParams: this.enhancedKYCParams,
-      biometricKYCParams: this.biometricKYCParams,
-      documentVerificationParams: this.documentVerificationParams,
-      enhancedDocumentVerificationParams:
-        this.enhancedDocumentVerificationParams,
-      userDetails: this.userDetails,
-    });
-    const state = ValidationState.invalid(issues);
-    const blocking = firstErrorIssue(state);
-
-    if (blocking) {
-      // `state.valid` is `false` here: `blocking` is non-null only when
-      // the validator surfaced an error-severity issue, which forces
-      // `state` into the invalid branch.
-      const invalid = state as Extract<typeof state, { valid: false }>;
-      return {
-        kind: "invalid",
-        validation: invalid,
-      };
-    }
-
-    // The validator's "screens not empty" rule is the only source of
-    // truth that guarantees `screens` is non-undefined here. Keep the
-    // invariant local rather than hiding it behind a `!` assertion so
-    // a future refactor that loosens the rule fails loudly with a
-    // descriptive error instead of silently returning a malformed
-    // snapshot.
-    if (!screens) {
-      throw new Error(
-        "UseSmileIDFlowBuilder: internal invariant violated — screens missing after validation passed.",
-      );
-    }
-
-    const configuration: FlowConfigurationSnapshot = Object.freeze({
-      ...(this.consentInformation
-        ? { consentInformation: this.consentInformation }
-        : {}),
-      ...(this.enhancedKYCParams
-        ? { enhancedKYCParams: this.enhancedKYCParams }
-        : {}),
-      ...(this.biometricKYCParams
-        ? { biometricKYCParams: this.biometricKYCParams }
-        : {}),
-      ...(this.documentVerificationParams
-        ? { documentVerificationParams: this.documentVerificationParams }
-        : {}),
-      ...(this.enhancedDocumentVerificationParams
-        ? {
-            enhancedDocumentVerificationParams:
-              this.enhancedDocumentVerificationParams,
-          }
-        : {}),
-      ...(this.userDetails ? { userDetails: this.userDetails } : {}),
-      ...(this.userId ? { userId: this.userId } : {}),
-      ...(this._config ? { config: this._config.build() } : {}),
-      ...(this._theme ? { theme: this._theme.build() } : {}),
-      ...(network ? { network } : {}),
-      ...(mlConfig ? { ml: mlConfig } : {}),
-      screens,
-      ...(this.localizations ? { localizations: this.localizations } : {}),
-      onResult: this.onResult,
-      ...(this.onAnalyticsEvent
-        ? { onAnalyticsEvent: this.onAnalyticsEvent }
-        : {}),
-    });
-
-    return { kind: "success", configuration };
-  }
-}
-
-/**
- * Frozen snapshot produced by `UseSmileIDFlowBuilder.build()`.
- *
- * `screens` is non-optional because `build()` rejects an empty
- * screens block. `onResult` is non-optional because the builder
- * defaults it to a no-op.
- */
-export type FlowConfigurationSnapshot = {
-  readonly consentInformation?: ConsentInformation;
-  readonly enhancedKYCParams?: EnhancedKYCParams;
-  readonly biometricKYCParams?: BiometricKYCParams;
-  readonly documentVerificationParams?: DocumentVerificationParams;
-  readonly enhancedDocumentVerificationParams?: EnhancedDocumentVerificationParams;
-  readonly userDetails?: UserDetails;
-  readonly userId?: string;
-  readonly config?: ConfigOptions;
-  readonly theme?: ThemeConfiguration;
-  readonly network?: NetworkConfig;
-  readonly ml?: MLConfig;
-  readonly screens: ScreensConfig;
-  readonly localizations?: UseSmileIDLocalizations;
-  readonly onResult: (result: UseSmileIDResult<JobSubmissionResponse>) => void;
-  readonly onAnalyticsEvent?: (event: UseSmileIDAnalyticsEvent) => void;
-};

package/src/presentation/flow/flow_navigation_context.tsx

@@ -1,50 +0,0 @@
-import { createContext, useContext, type ReactNode } from "react";
-import type { FlowNavigationManager } from "./flow_navigation_manager";
-
-/**
- * React Context bridge for the flow navigation manager. Partner
- * screens or custom widgets call `useFlowNavigation()` to read the
- * manager without prop-drilling.
- *
- * Concrete scenario: a partner ships a custom button slot
- * (`screens.consent.allowButton`) that needs to advance the flow on
- * press. They write `useFlowNavigation().navigateToNext()` instead of having
- * to receive an `onPress` prop from N levels up.
- */
-const FlowNavigationContext = createContext<FlowNavigationManager | null>(null);
-
-export type FlowNavigationProviderProps = {
-  readonly manager: FlowNavigationManager;
-  readonly children: ReactNode;
-};
-
-export function FlowNavigationProvider({
-  manager,
-  children,
-}: FlowNavigationProviderProps) {
-  return (
-    <FlowNavigationContext.Provider value={manager}>
-      {children}
-    </FlowNavigationContext.Provider>
-  );
-}
-
-/**
- * Read the active `FlowNavigationManager` from context. Throws if
- * called outside a `<FlowNavigationProvider>` — concrete scenario
- * this catches: a partner mounts a SDK screen directly (e.g.
- * `<UseSmileIDConsentScreen>`) without `<UseSmileIDBuilder>` wrapping
- * it. The throw makes the misuse loud at first render rather than
- * silently no-op-ing on `navigateToNext()` / `navigateBack()` calls.
- */
-export function useFlowNavigation(): FlowNavigationManager {
-  const manager = useContext(FlowNavigationContext);
-  if (!manager) {
-    throw new Error(
-      "useFlowNavigation: called outside <UseSmileIDBuilder> — wrap the " +
-        "consuming screen with <FlowNavigationProvider> or render it " +
-        "inside <UseSmileIDBuilder>.",
-    );
-  }
-  return manager;
-}