@smileid/usesmileid 12.0.0-beta01

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

@@ -0,0 +1,402 @@
+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;
+
+  /**
+   * Notified when the flow completes (success or failure). Defaults
+   * to a no-op so partners who don't need result handling still get
+   * a valid configuration; in production set this to wire the
+   * server-issued `JobSubmissionResponse` (`userId` / `jobId` /
+   * `status` / `message` / `createdAt`) into the partner's job-status
+   * pipeline.
+   */
+  onResult: (result: UseSmileIDResult<JobSubmissionResponse>) => void =
+    () => {};
+
+  /**
+   * Optional. Notified for each analytics event during the flow.
+   * Stub note: orchestrator does not yet emit events — see
+   * `docs/Architecture.md § Rollout`.
+   */
+  onAnalyticsEvent?: (event: UseSmileIDAnalyticsEvent) => void;
+
+  // --- Internal block builders ---------------------------------------------
+
+  private _config?: UseSmileIDConfigBuilder;
+  private _theme?: ThemeConfigBuilder;
+  private _network?: UseSmileIDNetworkBuilder;
+  private _ml?: UseSmileIDMLBuilder;
+  private _screens?: ScreensBuilder;
+
+  /**
+   * `b.config((c) => { c.enableCrashReporting = false; })`
+   *
+   * Compose-friendly: repeated calls reuse the same builder, so
+   * `enableCrashReporting` set in one call and `enableDebugMode` set
+   * in another both end up on the final config.
+   */
+  config(block: (c: UseSmileIDConfigBuilder) => void): void {
+    if (!this._config) this._config = new UseSmileIDConfigBuilder();
+    block(this._config);
+  }
+
+  /**
+   * `b.theme((t) => { t.primaryColor = '#1A73E8'; 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);
+  }
+
+  /**
+   * `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);
+  }
+
+  /**
+   * `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);
+  }
+
+  /**
+   * `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);
+  }
+
+  /**
+   * Quick triage of the in-progress builder state. 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`.
+   */
+  validate(): ValidationState {
+    return ValidationState.invalid(
+      runBuilderValidation(this._screens?.build().steps ?? []),
+    );
+  }
+
+  /**
+   * Validate a `ConsentInformation` payload in isolation — useful
+   * when the source of truth is dynamic (e.g. a payload pulled from
+   * partner storage or a remote config) and the partner wants to
+   * pre-flight it before assigning to `b.consentInformation`.
+   */
+  validateConsent(consent: ConsentInformation): ValidationState {
+    return ValidationState.invalid(runConsentValidation(consent));
+  }
+
+  /**
+   * Validate an `EnhancedKYCParams` payload in isolation — 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));
+  }
+
+  /**
+   * Validate a `BiometricKYCParams` payload in isolation. Same
+   * semantics as `validateEnhancedKYCParams` — same field rules,
+   * different param shape.
+   */
+  validateBiometricKYCParams(params: BiometricKYCParams): ValidationState {
+    return ValidationState.invalid(runBiometricKYCParamsValidation(params));
+  }
+
+  /** Validate a `DocumentVerificationParams` payload in isolation. */
+  validateDocumentVerificationParams(
+    params: DocumentVerificationParams,
+  ): ValidationState {
+    return ValidationState.invalid(
+      runDocumentVerificationParamsValidation(params),
+    );
+  }
+
+  /** Validate an `EnhancedDocumentVerificationParams` payload in isolation. */
+  validateEnhancedDocumentVerificationParams(
+    params: EnhancedDocumentVerificationParams,
+  ): ValidationState {
+    return ValidationState.invalid(
+      runEnhancedDocumentVerificationParamsValidation(params),
+    );
+  }
+
+  /**
+   * Validate a `UserDetails` payload in isolation — 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

@@ -0,0 +1,50 @@
+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;
+}