@smileid/usesmileid 12.0.0-beta01 → 12.0.1

package/src/presentation/flow/__tests__/flow_navigation_manager.test.ts

@@ -602,6 +602,55 @@ describe("FlowNavigationManager — submission lifecycle", () => {
     expect(manager.jobSubmissionState.kind).toBe("success");
   });
 
+  it("retrySubmission double-trigger fires exactly one new submission", async () => {
+    // Concrete scenario: the processing screen's retry button is
+    // double-tapped after a failed submission. The second tap must not
+    // reset the in-flight `loading` latch and launch a duplicate job.
+    const repository = new StubRepository();
+    repository.result = failure(new Error("transient"));
+    const manager = makeManager(
+      buildScreens((screens) => screens.processing()),
+      vi.fn(),
+      {
+        enhancedKYCParams: {
+          idType: "BVN",
+          idNumber: "1",
+          country: "NG",
+        },
+        userDetails: SAMPLE_USER_DETAILS,
+        network: {
+          config: {
+            jobType: JobType.enhancedKyc,
+            token: "k",
+            partnerConfig: {
+              partnerId: "p",
+              callbackUrl: "",
+              useSandbox: true,
+            },
+          },
+        },
+      },
+      repository,
+    );
+
+    // Initial attempt fails, leaving the retry affordance visible.
+    manager.beginSubmissionIfNeeded();
+    await flushMicrotasks();
+    expect(manager.jobSubmissionState.kind).toBe("failure");
+    expect(repository.received).toHaveLength(1);
+
+    // The retried submission stays in flight so both taps land while
+    // the request is loading.
+    repository.manual = true;
+    manager.retrySubmission();
+    manager.retrySubmission(); // double-tap — ignored while in flight
+
+    await flushMicrotasks();
+    expect(manager.jobSubmissionState.kind).toBe("loading");
+    // Exactly one new submission: the initial failure plus one retry.
+    expect(repository.received).toHaveLength(2);
+  });
+
   it("does not update state if the manager is disposed mid-submission", async () => {
     const repository = new StubRepository();
     repository.manual = true;

package/src/presentation/flow/dsl/builder/__tests__/config_builder.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+import * as ScreenOrientation from "expo-screen-orientation";
+import { GlobalPrivacyControl } from "../../../../../core/models/global_privacy_control";
+import { UseSmileIDConfigBuilder } from "../config_builder";
+
+describe("UseSmileIDConfigBuilder", () => {
+  it("snapshots the documented defaults", () => {
+    expect(new UseSmileIDConfigBuilder().build()).toEqual({
+      enableCrashReporting: true,
+      enableDebugMode: false,
+      allowOfflineMode: false,
+      globalPrivacyControl: GlobalPrivacyControl.OptOut,
+      exitOrientations: ScreenOrientation.OrientationLock.PORTRAIT_UP,
+    });
+  });
+
+  it("carries an overridden exit orientation lock into the snapshot", () => {
+    const builder = new UseSmileIDConfigBuilder();
+    builder.exitOrientations = ScreenOrientation.OrientationLock.DEFAULT;
+
+    expect(builder.build().exitOrientations).toBe(
+      ScreenOrientation.OrientationLock.DEFAULT,
+    );
+  });
+});

package/src/presentation/flow/dsl/builder/config_builder.ts

@@ -1,4 +1,6 @@
+import * as ScreenOrientation from "expo-screen-orientation";
 import type { ConfigOptions } from "../../../../core/models/config";
+import { GlobalPrivacyControl } from "../../../../core/models/global_privacy_control";
 
 /**
  * `b.config((c) => { c.enableCrashReporting = false; ... })`
@@ -8,15 +10,48 @@ import type { ConfigOptions } from "../../../../core/models/config";
  * populated.
  */
 export class UseSmileIDConfigBuilder {
+  /**
+   * When true (the default), the SDK reports its own crashes to Smile ID's
+   * crash-reporting backend. Set false to opt out.
+   */
   enableCrashReporting = true;
+
+  /**
+   * When true, enables verbose SDK debug logging and on-device
+   * diagnostics. Defaults to false; leave off in production.
+   */
   enableDebugMode = false;
+
+  /**
+   * When true, captured images are written to disk so the job can be
+   * submitted later when connectivity returns. Defaults to false.
+   */
   allowOfflineMode = false;
 
+  /**
+   * Consent posture for every session (`global_privacy_control`). Defaults
+   * to `GlobalPrivacyControl.OptOut` — the opt-out consent layout is
+   * enforced universally and regional detection is ignored. Set
+   * `GlobalPrivacyControl.OptIn` to keep the legacy regional mechanics
+   * (opt-in inside the EU, opt-out elsewhere).
+   */
+  globalPrivacyControl: GlobalPrivacyControl = GlobalPrivacyControl.OptOut;
+
+  /**
+   * Orientation lock applied when a capture screen leaves the screen.
+   * Defaults to portrait-up; set `ScreenOrientation.OrientationLock.DEFAULT`
+   * if your app supports more than one orientation.
+   */
+  exitOrientations: ScreenOrientation.OrientationLock =
+    ScreenOrientation.OrientationLock.PORTRAIT_UP;
+
   build(): ConfigOptions {
     return Object.freeze({
       enableCrashReporting: this.enableCrashReporting,
       enableDebugMode: this.enableDebugMode,
       allowOfflineMode: this.allowOfflineMode,
+      globalPrivacyControl: this.globalPrivacyControl,
+      exitOrientations: this.exitOrientations,
     });
   }
 }

package/src/presentation/flow/dsl/builder/ml_builder.ts

@@ -34,7 +34,7 @@ import {
  */
 
 export class FaceAnalyzerScope {
-  /** Register the face analyzer for this scope. */
+  /** Registers a detection backend for this capture type. */
   add(analyzer: FaceAnalyzer): void {
     this._analyzer = analyzer;
   }
@@ -130,7 +130,7 @@ export class FaceAnalyzerScope {
 }
 
 export class DocumentAnalyzerScope {
-  /** Register the document analyzer for this scope. */
+  /** Registers a detection backend for this capture type. */
   add(analyzer: DocumentAnalyzer): void {
     this._analyzer = analyzer;
   }
@@ -143,12 +143,20 @@ export class AnalyzerRegistryBuilder {
   private _selfieConfig?: FaceConfig | undefined;
   private _document?: DocumentAnalyzer | undefined;
 
-  /** Open a selfie-analyzer registration scope. */
+  /**
+   * Registers and tunes the analyzer(s) for the selfie capture type.
+   * Calling it again for the same capture type replaces the previous
+   * registration.
+   */
   forCaptureType(
     captureType: CaptureType.selfie,
     block: (a: FaceAnalyzerScope) => void,
   ): void;
-  /** Open a document-analyzer registration scope. */
+  /**
+   * Registers and tunes the analyzer(s) for the document capture type.
+   * Calling it again for the same capture type replaces the previous
+   * registration.
+   */
   forCaptureType(
     captureType: CaptureType.document,
     block: (a: DocumentAnalyzerScope) => void,
@@ -188,6 +196,7 @@ export class AnalyzerRegistryBuilder {
 export class UseSmileIDMLBuilder {
   private _analyzers?: AnalyzerRegistryBuilder;
 
+  /** Registers the ML analyzers for the flow, keyed by capture type. */
   analyzers(block: (a: AnalyzerRegistryBuilder) => void): void {
     if (!this._analyzers) this._analyzers = new AnalyzerRegistryBuilder();
     block(this._analyzers);

package/src/presentation/flow/dsl/builder/screens_builder.ts

@@ -30,48 +30,103 @@ export type ButtonSlot = (props: {
 // --- Per-screen builders ---------------------------------------------------
 
 export class ConsentConfigBuilder {
+  /** Your company name, shown in the consent copy. */
   partnerName = "";
-  /** Partner brand mark rendered next to the Smile ID icon at the top of the consent screen. */
+  /**
+   * Optional partner logo shown on the consent screen, rendered next to
+   * the Smile ID icon at the top.
+   */
   partnerIcon?: ReactNode;
+  /** URL of your privacy policy, linked from the consent screen. */
   partnerPrivacyPolicyUrl?: string;
+  /**
+   * Whether to show the "Powered by Smile ID" attribution. Defaults to
+   * true.
+   */
   showAttribution = true;
+  /**
+   * Callback invoked with the `ConsentInformation` when the user grants
+   * consent.
+   */
   onConsentGranted?: (info: ConsentInformation) => void;
+  /** Provides a custom allow/agree button in place of the default. */
   allowButton?: ButtonSlot;
+  /** Provides a custom deny/cancel button in place of the default. */
   denyButton?: ButtonSlot;
 }
 
 export class InstructionsConfigBuilder {
-  /** Leading title text (title-text colour). Defaults to the localized prefix. */
+  /**
+   * The leading, non-emphasized part of the instructions screen title.
+   * Defaults to the localized prefix.
+   */
   titlePrefix?: string;
-  /** Emphasized word (primary colour, own line). Defaults to the localized "selfie". */
+  /**
+   * The emphasized (highlighted) part of the instructions screen title.
+   * Defaults to the localized "selfie".
+   */
   titleEmphasis?: string;
-  /** Lottie hero. Unset uses the selfie hero (or the ESS hero when enhanced liveness is on). */
+  /**
+   * Name of the hero animation asset shown at the top of the
+   * instructions screen. Unset uses the selfie hero (or the ESS hero
+   * when enhanced liveness is on).
+   */
   heroAnimation?: HeroAnimationSource;
-  /** Capture-guidelines section title (rendered uppercase). */
+  /** Heading for the list of capture guidelines (rendered uppercase). */
   guidelinesSectionTitle?: string;
-  /** Capture-guideline tiles; push to customize. Empty uses the defaults. */
+  /** The list of guideline items shown to the user. Empty uses the defaults. */
   guidelines: InstructionGuideline[] = [];
+  /**
+   * Whether to show the "Powered by Smile ID" attribution. Defaults to
+   * true.
+   */
   showAttribution = true;
-  /** Draw the face-oval ring around the hero animation. */
+  /** When true, draws the face-oval ring around the hero animation. */
   showHeroOval = true;
+  /** Provides a custom continue button in place of the default. */
   continueButton?: ButtonSlot;
 }
 
 export class SelfieCaptureConfigBuilder {
+  /**
+   * When true, the whole selfie session captures on the rear camera so an
+   * assisting agent can point it at the subject. Cannot be combined with
+   * {@link enableEnhancedLiveness}.
+   */
   allowAgentMode = false;
+  /**
+   * When true, uses the enhanced active-liveness capture path. Defaults
+   * to false.
+   */
   enableEnhancedLiveness = false;
 }
 
 export class DocumentCaptureConfigBuilder {
-  /** The document being captured. **Required** — missing it fails validation. */
+  /**
+   * The kind of document being captured, which drives the capture
+   * framing and aspect ratio. **Required** — missing it fails validation.
+   */
   documentType?: DocumentType;
-  /** When the photo is taken. Defaults to auto-capture with a 10s manual fallback. */
+  /**
+   * Whether the document is captured automatically when held steady, or
+   * manually by shutter. Defaults to auto-capture with a 10s manual
+   * fallback.
+   */
   captureMode: DocumentCaptureMode =
     DocumentCaptureMode.AutoCaptureWithManualFallback();
+  /**
+   * When true, lets the user pick an existing document image from the
+   * gallery. Defaults to false.
+   */
   allowGalleryUpload = false;
+  /** When true, captures both the front and back of the document. Defaults to true. */
   captureBothSides = true;
+  /** When true, lets the user skip capturing the back side. Defaults to false. */
   allowSkipBack = false;
-  /** Optional aspect ratio hint — e.g. CR-80 ID card = 1.586. */
+  /**
+   * Optional fixed aspect ratio for the document frame when the ID's
+   * dimensions are known in advance — e.g. CR-80 ID card = 1.586.
+   */
   knownIdAspectRatio?: number;
 
   /** The `documentType`'s aspect ratio when present, otherwise `knownIdAspectRatio`. */
@@ -81,17 +136,27 @@ export class DocumentCaptureConfigBuilder {
 }
 
 export class CaptureConfigBuilder {
+  /** What this screen captures — a selfie or a document. Required. */
   captureType?: CaptureType;
+  /** Provides a custom start/capture button in place of the default. */
   startButton?: ButtonSlot;
 
   private _selfie?: SelfieCaptureConfigBuilder;
   private _document?: DocumentCaptureConfigBuilder;
 
+  /**
+   * Configures selfie-specific capture options (agent mode, enhanced
+   * liveness).
+   */
   selfie(block: (s: SelfieCaptureConfigBuilder) => void): void {
     if (!this._selfie) this._selfie = new SelfieCaptureConfigBuilder();
     block(this._selfie);
   }
 
+  /**
+   * Configures document-specific capture options (document type, capture
+   * mode, gallery upload, two-sided capture).
+   */
   document(block: (d: DocumentCaptureConfigBuilder) => void): void {
     if (!this._document) this._document = new DocumentCaptureConfigBuilder();
     block(this._document);
@@ -109,17 +174,31 @@ export class CaptureConfigBuilder {
 }
 
 export class PreviewConfigBuilder {
+  /** Whether the preview screen offers a retake action. */
   allowRetake = true;
+  /**
+   * Whether to show the "Powered by Smile ID" attribution. Defaults to
+   * true.
+   */
   showAttribution = true;
-  continueButton?: ButtonSlot;
-  cancelButton?: ButtonSlot;
 }
 
 export class ProcessingConfigBuilder {
+  /**
+   * When true, shows a numeric progress percentage while the job is
+   * processing.
+   */
   showProgressPercentage = true;
+  /**
+   * Whether to show the "Powered by Smile ID" attribution. Defaults to
+   * true.
+   */
   showAttribution = true;
+  /** Provides a custom continue button in place of the default. */
   continueButton?: ButtonSlot;
+  /** Provides a custom retry button in place of the default. */
   retryButton?: ButtonSlot;
+  /** Provides a custom exit button in place of the default. */
   exitButton?: ButtonSlot;
 }
 
@@ -144,30 +223,49 @@ export type ScreensConfig = {
 export class ScreensBuilder {
   private _steps: ScreenSpec[] = [];
 
+  /**
+   * Adds a consent screen that collects the user's agreement to
+   * biometric data processing before capture.
+   */
   consent(block?: (c: ConsentConfigBuilder) => void): void {
     const config = new ConsentConfigBuilder();
     block?.(config);
     this._steps.push({ kind: "consent", config });
   }
 
+  /**
+   * Adds an instructions screen explaining what the user is about to do.
+   */
   instructions(block?: (i: InstructionsConfigBuilder) => void): void {
     const config = new InstructionsConfigBuilder();
     block?.(config);
     this._steps.push({ kind: "instructions", config });
   }
 
+  /**
+   * Adds a capture screen that runs the camera and on-device detection
+   * for a selfie or document.
+   */
   capture(block: (c: CaptureConfigBuilder) => void): void {
     const config = new CaptureConfigBuilder();
     block(config);
     this._steps.push({ kind: "capture", config });
   }
 
+  /**
+   * Adds a preview screen that lets the user review the captured image
+   * and optionally retake it.
+   */
   preview(block?: (p: PreviewConfigBuilder) => void): void {
     const config = new PreviewConfigBuilder();
     block?.(config);
     this._steps.push({ kind: "preview", config });
   }
 
+  /**
+   * Adds a processing screen shown while the job is submitted, displaying
+   * success, failure, or retry states.
+   */
   processing(block?: (p: ProcessingConfigBuilder) => void): void {
     const config = new ProcessingConfigBuilder();
     block?.(config);

package/src/presentation/flow/dsl/builder/theme_builder.ts

@@ -27,23 +27,40 @@ export type ThemeConfiguration = {
  * picks light or dark at mount time based on the active color scheme.
  */
 export class ThemeConfigBuilder {
+  /** Primary brand color used for key actions and accents. */
   primaryColor?: AdaptiveColor;
+
+  /**
+   * Foreground color used on top of the primary color (for example
+   * button text).
+   */
   primaryForeground?: AdaptiveColor;
+
+  /** Secondary color used for less prominent surfaces and actions. */
   secondaryColor?: AdaptiveColor;
+
+  /** Accent color used for highlights and selected states. */
   accentColor?: AdaptiveColor;
 
+  /** Optional font family applied to all SDK text. */
   fontFamily?: string;
 
+  /** Corner radius applied to buttons. */
   buttonShape?: number;
+
+  /** Corner radius applied to cards and surfaces. */
   cardShape?: number;
 
-  /** Helper to create an `AdaptiveColor` with explicit light/dark values. */
+  /**
+   * Builds an adaptive color that resolves to the light or dark value
+   * based on the active appearance.
+   */
   color(light: string, dark: string): AdaptiveColor {
     return Object.freeze({ light, dark });
   }
 
   /**
-   * Helper to create a button/card shape value. Returns the input
+   * Builds a corner-shape value from the given radius. Returns the input
    * radius unchanged — React Native resolves shape at render time via
    * `borderRadius`, so the `buttonShape` / `cardShape` properties are
    * plain numbers.

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

@@ -10,10 +10,12 @@ import {
 import type { FlowBuildResult } from "./flow_build_result";
 
 /**
- * Top-level partner entry point. Configures the flow declaratively
- * via the `builder` closure, then renders the result. The component
- * owns the build-and-dispatch lifecycle internally — partners never
- * touch the intermediate [FlowBuildResult].
+ * 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 (

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

@@ -97,20 +97,20 @@ export class UseSmileIDFlowBuilder {
   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.
+   * 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 =
     () => {};
 
   /**
-   * Optional. Notified for each analytics event during the flow.
-   * Stub note: orchestrator does not yet emit events — see
-   * `docs/Architecture.md § Rollout`.
+   * Invoked for every analytics event the SDK emits during the flow.
+   * Optional — leave unset to ignore analytics.
    */
   onAnalyticsEvent?: (event: UseSmileIDAnalyticsEvent) => void;
 
@@ -123,11 +123,12 @@ export class UseSmileIDFlowBuilder {
   private _screens?: ScreensBuilder;
 
   /**
-   * `b.config((c) => { c.enableCrashReporting = false; })`
+   * 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.
    *
-   * 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.
+   * `b.config((c) => { c.enableCrashReporting = false; })`
    */
   config(block: (c: UseSmileIDConfigBuilder) => void): void {
     if (!this._config) this._config = new UseSmileIDConfigBuilder();
@@ -135,7 +136,10 @@ export class UseSmileIDFlowBuilder {
   }
 
   /**
-   * `b.theme((t) => { t.primaryColor = '#1A73E8'; t.buttonShape = 12; })`
+   * 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
@@ -148,6 +152,10 @@ export class UseSmileIDFlowBuilder {
   }
 
   /**
+   * 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
@@ -160,6 +168,9 @@ export class UseSmileIDFlowBuilder {
   }
 
   /**
+   * 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 {
@@ -168,6 +179,10 @@ export class UseSmileIDFlowBuilder {
   }
 
   /**
+   * 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
@@ -179,10 +194,11 @@ export class UseSmileIDFlowBuilder {
   }
 
   /**
-   * 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.
+   * 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
@@ -190,6 +206,8 @@ export class UseSmileIDFlowBuilder {
    * 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(
@@ -198,35 +216,38 @@ export class UseSmileIDFlowBuilder {
   }
 
   /**
-   * 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`.
+   * 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));
   }
 
   /**
-   * 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`.
+   * 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));
   }
 
   /**
-   * Validate a `BiometricKYCParams` payload in isolation. Same
-   * semantics as `validateEnhancedKYCParams` — same field rules,
-   * different param shape.
+   * Validates a `BiometricKYCParams` payload in isolation and returns a
+   * `ValidationState`, without throwing.
    */
   validateBiometricKYCParams(params: BiometricKYCParams): ValidationState {
     return ValidationState.invalid(runBiometricKYCParamsValidation(params));
   }
 
-  /** Validate a `DocumentVerificationParams` payload in isolation. */
+  /**
+   * Validates a `DocumentVerificationParams` payload in isolation and
+   * returns a `ValidationState`, without throwing. Only `country` is
+   * required; `idType` is optional.
+   */
   validateDocumentVerificationParams(
     params: DocumentVerificationParams,
   ): ValidationState {
@@ -235,7 +256,11 @@ export class UseSmileIDFlowBuilder {
     );
   }
 
-  /** Validate an `EnhancedDocumentVerificationParams` payload in isolation. */
+  /**
+   * Validates an `EnhancedDocumentVerificationParams` payload in
+   * isolation and returns a `ValidationState`, without throwing. Both
+   * `country` and `idType` are required.
+   */
   validateEnhancedDocumentVerificationParams(
     params: EnhancedDocumentVerificationParams,
   ): ValidationState {
@@ -245,11 +270,12 @@ export class UseSmileIDFlowBuilder {
   }
 
   /**
-   * 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.
+   * 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));