@smileid/usesmileid 12.0.0-beta01 → 12.0.0

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

@@ -30,48 +30,102 @@ 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, lets an assisting agent flip to the rear camera to capture
+   * the subject. Defaults to false.
+   */
   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 +135,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 +173,35 @@ 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;
+  /** Provides a custom continue button in place of the default. */
   continueButton?: ButtonSlot;
+  /** Provides a custom cancel button in place of the default. */
   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 +226,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));