@smileid/usesmileid 12.0.0-beta01

package/src/__tests__/dsl.test.ts

@@ -0,0 +1,1115 @@
+import { describe, expect, it, vi } from "vitest";
+import { AnalyzerFactoryKey } from "@smileid/usesmileid_bridge";
+import type {
+  FaceAnalyzer,
+  DocumentAnalyzer,
+} from "@smileid/usesmileid_platform_interface";
+import {
+  useSmileIDBuilder,
+  UseSmileIDFlowBuilder,
+} from "../presentation/flow/dsl/use_smile_id_builder";
+import {
+  CaptureConfigBuilder,
+  CaptureType,
+} from "../presentation/flow/dsl/builder/screens_builder";
+import { JobType } from "../core/models/job_type";
+import { DocumentType } from "../core/models/document_type";
+import { LogLevel } from "../core/models/network_config";
+import type { FlowConfigurationSnapshot } from "../presentation/flow/dsl/use_smile_id_flow_builder";
+
+// Test helper: invokes useSmileIDBuilder, asserts kind === 'success'
+// and returns the configuration. Throws with a descriptive message
+// when the builder reports invalid — keeps test bodies focused on
+// the surface under test instead of ceremony.
+function buildOk(
+  configure: (b: UseSmileIDFlowBuilder) => void,
+): FlowConfigurationSnapshot {
+  const result = useSmileIDBuilder(configure);
+  if (result.kind === "invalid") {
+    throw new Error(
+      `Expected build() success, got invalid: ${result.validation.issues.map((i) => i.message).join("; ")}`,
+    );
+  }
+  return result.configuration;
+}
+
+// Test helper: invokes useSmileIDBuilder and expects an invalid
+// result whose first issue's message matches `pattern`. The
+// canonical migration target for the legacy `expect(() =>
+// useSmileIDBuilder(...)).toThrow(/regex/)` pattern.
+function expectBuildInvalid(
+  configure: (b: UseSmileIDFlowBuilder) => void,
+  pattern: RegExp,
+): void {
+  const result = useSmileIDBuilder(configure);
+  expect(result.kind).toBe("invalid");
+  if (result.kind === "invalid") {
+    const matched = result.validation.issues.some((i) =>
+      pattern.test(i.message),
+    );
+    if (!matched) {
+      throw new Error(
+        `Expected an invalid issue matching ${pattern} but got: ${result.validation.issues.map((i) => i.message).join(", ")}`,
+      );
+    }
+  }
+}
+
+const stubFaceAnalyzer: FaceAnalyzer = {
+  kind: "face",
+  key: AnalyzerFactoryKey.VisionFace,
+  frameProcessorPluginName: "UseSmileIDVisionFaceFrameProcessor",
+  configure: vi.fn(),
+  reset: vi.fn(),
+  flush: vi.fn(),
+  close: vi.fn(),
+};
+
+const stubDocumentAnalyzer: DocumentAnalyzer = {
+  kind: "document",
+  frameProcessorPluginName: "UseSmileIDVisionDocumentFrameProcessor",
+  configure: vi.fn(),
+  reset: vi.fn(),
+  flush: vi.fn(),
+  close: vi.fn(),
+};
+
+/**
+ * Add the minimum screens block needed to satisfy `build()`'s
+ * non-empty-screens invariant — used by tests that exercise other
+ * surfaces (config, theme, network, ml) and don't otherwise care
+ * about the screens block.
+ */
+function withMinimalScreens(b: UseSmileIDFlowBuilder): void {
+  b.screens((screens) => {
+    screens.instructions();
+  });
+}
+
+/**
+ * Add the screens / ml / consent state needed to satisfy the
+ * `documentVerification` job-type rules — used by tests that exercise
+ * the network-config surface for a real job type and don't otherwise
+ * care about the screens block. The caller still supplies its own
+ * `network { }` block.
+ */
+function withValidDocumentFlow(b: UseSmileIDFlowBuilder): void {
+  b.consentInformation = {
+    granted: true,
+    grantedAt: "2026-04-30T00:00:00.000Z",
+    noticeLanguage: "EN",
+    noticePrivacyPolicyUrl: "https://example.test/p",
+  };
+  // Document Verification requires its params + the shared user_details.
+  b.documentVerificationParams = { country: "KE", idType: "NATIONAL_ID" };
+  b.userDetails = {
+    givenNames: "Ada",
+    lastName: "Lovelace",
+    email: "ada@example.com",
+  };
+  b.screens((screens) => {
+    screens.capture((c) => {
+      c.captureType = CaptureType.selfie;
+    });
+    screens.capture((c) => {
+      c.captureType = CaptureType.document;
+      c.document((d) => {
+        d.documentType = DocumentType.GenericDocument();
+      });
+    });
+    screens.processing();
+  });
+  b.ml((m) => {
+    m.analyzers((a) => {
+      a.forCaptureType(CaptureType.selfie, (face) => {
+        face.add(stubFaceAnalyzer);
+      });
+    });
+  });
+}
+
+describe("useSmileIDBuilder — closure-based DSL", () => {
+  it("produces a frozen FlowConfiguration when at least one screen is configured", () => {
+    const config = buildOk((b) => {
+      withMinimalScreens(b);
+    });
+    expect(Object.isFrozen(config)).toBe(true);
+    expect(config.screens.steps).toHaveLength(1);
+    expect(typeof config.onResult).toBe("function");
+  });
+
+  it("rejects an empty screens block at build time", () => {
+    // The error message reads "The screens { } block is empty …".
+    // Match across the literal `{ }` between "screens" and "block"
+    // so the assertion isn't tied to that formatting detail.
+    expectBuildInvalid(() => {}, /screens.*block is empty/i);
+  });
+
+  describe("config block", () => {
+    it("captures enableCrashReporting through the closure", () => {
+      const config = buildOk((b) => {
+        withMinimalScreens(b);
+        b.config((c) => {
+          c.enableCrashReporting = false;
+        });
+      });
+      expect(config.config?.enableCrashReporting).toBe(false);
+    });
+
+    it("composes across multiple config() calls", () => {
+      // Concrete scenario: a partner extracts theme + flag setup into
+      // separate helper functions that each call b.config(...). With
+      // composing semantics, both calls' state lands on the same
+      // ConfigBuilder. Without it, the second would overwrite the
+      // first.
+      const config = buildOk((b) => {
+        withMinimalScreens(b);
+        b.config((c) => {
+          c.enableCrashReporting = false;
+        });
+        b.config((c) => {
+          c.enableDebugMode = true;
+        });
+      });
+      expect(config.config?.enableCrashReporting).toBe(false);
+      expect(config.config?.enableDebugMode).toBe(true);
+    });
+  });
+
+  describe("network block (3-level closure nesting)", () => {
+    it("captures partnerConfig and logging via nested closures", () => {
+      const config = buildOk((b) => {
+        withValidDocumentFlow(b);
+        b.network((n) => {
+          n.config((c) => {
+            c.jobType = JobType.documentVerification;
+            c.token = "api-key";
+            c.partnerConfig((p) => {
+              p.partnerId = "partner-id";
+              p.callbackUrl = "https://example.com/cb";
+              p.useSandbox = true;
+            });
+            c.logging((l) => {
+              l.enabled = true;
+              l.level = LogLevel.body;
+            });
+          });
+          // TimeoutConfigBuilder takes seconds (matching the rest of
+          // the SDK's HTTP-config surface — Dio, Axios, OkHttp all
+          // express timeouts as seconds at this layer). Fields are
+          // `connect / read / write / call`, no `Ms` suffix.
+          n.timeouts((t) => {
+            t.connect = 30;
+            t.call = 120;
+          });
+        });
+      });
+      expect(config.network?.config?.jobType).toBe(
+        JobType.documentVerification,
+      );
+      expect(config.network?.config?.partnerConfig?.partnerId).toBe(
+        "partner-id",
+      );
+      expect(config.network?.config?.token).toBe("api-key");
+      expect(config.network?.config?.partnerConfig?.useSandbox).toBe(true);
+      expect(config.network?.config?.logging?.level).toBe("body");
+      expect(config.network?.timeouts?.connect).toBe(30);
+      expect(config.network?.timeouts?.call).toBe(120);
+    });
+
+    it("captures partnerParams on PartnerConfig and preserves the value shape", () => {
+      // Concrete scenario: partners attach a custom job-correlation
+      // map (e.g. internal session id) via `p.partnerParams = { ... }`
+      // so the lambda webhook can de-duplicate on the partner side.
+      // The DSL must forward the field onto `PartnerConfig.partnerParams`
+      // unchanged so the API layer can serialize it as the
+      // `partner_params` JSON multipart part.
+      const config = buildOk((b) => {
+        withValidDocumentFlow(b);
+        b.network((n) => {
+          n.config((c) => {
+            c.jobType = JobType.documentVerification;
+            c.token = "api-key";
+            c.partnerConfig((p) => {
+              p.partnerId = "partner-id";
+              p.callbackUrl = "https://example.com/cb";
+              p.useSandbox = true;
+              p.partnerParams = { jobRef: "ref-42", sessionId: "s-1" };
+            });
+          });
+        });
+      });
+      expect(config.network?.config?.partnerConfig?.partnerParams).toEqual({
+        jobRef: "ref-42",
+        sessionId: "s-1",
+      });
+    });
+
+    it("omits partnerParams from the built PartnerConfig when never set", () => {
+      // exactOptionalPropertyTypes contract — the field is absent on
+      // the built object (not present-and-undefined) so partners doing
+      // `Object.keys(partnerConfig)` don't observe the key.
+      const config = buildOk((b) => {
+        withValidDocumentFlow(b);
+        b.network((n) => {
+          n.config((c) => {
+            c.jobType = JobType.documentVerification;
+            c.token = "k";
+            c.partnerConfig((p) => {
+              p.partnerId = "p";
+              p.callbackUrl = "";
+              p.useSandbox = true;
+            });
+          });
+        });
+      });
+      expect(
+        Object.prototype.hasOwnProperty.call(
+          config.network!.config!.partnerConfig!,
+          "partnerParams",
+        ),
+      ).toBe(false);
+    });
+  });
+
+  describe("ml block", () => {
+    it("registers face and document analyzers via forCaptureType scopes", () => {
+      const config = buildOk((b) => {
+        withMinimalScreens(b);
+        b.ml((m) => {
+          m.analyzers((a) => {
+            a.forCaptureType(CaptureType.selfie, (face) => {
+              face.add(stubFaceAnalyzer);
+            });
+            a.forCaptureType(CaptureType.document, (doc) => {
+              doc.add(stubDocumentAnalyzer);
+            });
+          });
+        });
+      });
+      expect(config.ml?.analyzers.selfie).toBe(stubFaceAnalyzer);
+      expect(config.ml?.analyzers.document).toBe(stubDocumentAnalyzer);
+    });
+
+    it("type-narrows the scope per captureType — concrete scenario test", () => {
+      // Concrete scenario: the FaceAnalyzerScope has `add(FaceAnalyzer)`
+      // and the DocumentAnalyzerScope has `add(DocumentAnalyzer)`. A
+      // copy-paste typo where the partner adds a document analyzer
+      // inside a 'face' scope would fail to compile (TS function-
+      // overload narrowing). This test pins the runtime value so a
+      // future refactor that drops the overloads would still surface
+      // the wrong-slot drop here.
+      const builder = new UseSmileIDFlowBuilder();
+      withMinimalScreens(builder);
+      builder.ml((m) => {
+        m.analyzers((a) => {
+          a.forCaptureType(CaptureType.selfie, (face) =>
+            face.add(stubFaceAnalyzer),
+          );
+        });
+      });
+      // `build()` returns a discriminated union — unwrap the
+      // success branch before reading the configuration. A
+      // `kind === "invalid"` here would mean the validator
+      // rejected `withMinimalScreens` + a single selfie analyzer,
+      // which would be the real bug worth surfacing.
+      const built = builder.build();
+      expect(built.kind).toBe("success");
+      if (built.kind !== "success") return;
+      expect(built.configuration.ml?.analyzers.selfie).toBe(stubFaceAnalyzer);
+      expect(built.configuration.ml?.analyzers.document).toBeUndefined();
+    });
+  });
+
+  describe("screens block", () => {
+    it("records steps in declaration order", () => {
+      const config = buildOk((b) => {
+        b.network((n) => {
+          n.config((c) => {
+            c.jobType = JobType.smartSelfieEnrollment;
+            c.token = "k";
+            c.partnerConfig((p) => {
+              p.partnerId = "p";
+              p.callbackUrl = "";
+              p.useSandbox = true;
+            });
+          });
+        });
+        // smartSelfieEnrollment requires userDetails (the v3 wire
+        // path carries `user_details` as a multipart part).
+        b.userDetails = {
+          givenNames: "Ada",
+          lastName: "Lovelace",
+          email: "ada@example.test",
+        };
+        b.ml((m) => {
+          m.analyzers((a) => {
+            a.forCaptureType(CaptureType.selfie, (face) =>
+              face.add(stubFaceAnalyzer),
+            );
+          });
+        });
+        b.screens((screens) => {
+          screens.consent((c) => {
+            c.partnerName = "Acme";
+            c.partnerIcon = "icon";
+            c.partnerPrivacyPolicyUrl = "https://acme.com/privacy";
+          });
+          screens.instructions();
+          screens.capture((c) => {
+            c.captureType = CaptureType.selfie;
+          });
+          screens.preview();
+          screens.processing();
+        });
+      });
+      const steps = config.screens.steps;
+      expect(steps.map((s) => s.kind)).toEqual([
+        "consent",
+        "instructions",
+        "capture",
+        "preview",
+        "processing",
+      ]);
+    });
+
+    it("capture(...) accepts a nested selfie config closure", () => {
+      const config = buildOk((b) => {
+        b.ml((m) => {
+          m.analyzers((a) => {
+            a.forCaptureType(CaptureType.selfie, (face) =>
+              face.add(stubFaceAnalyzer),
+            );
+          });
+        });
+        b.screens((screens) => {
+          screens.capture((cap) => {
+            cap.captureType = CaptureType.selfie;
+            cap.selfie((sel) => {
+              sel.allowAgentMode = true;
+              sel.enableEnhancedLiveness = true;
+            });
+          });
+        });
+      });
+      const captureStep = config.screens.steps[0];
+      expect(captureStep?.kind).toBe("capture");
+      if (captureStep?.kind === "capture") {
+        expect(captureStep.config.selfieConfig?.allowAgentMode).toBe(true);
+        expect(captureStep.config.selfieConfig?.enableEnhancedLiveness).toBe(
+          true,
+        );
+      }
+    });
+  });
+
+  describe("build-time validations", () => {
+    it("does NOT throw when an ml block is missing — capture-without-ml is severity warning, not error", () => {
+      // Severity discipline: capture-without-ml is a warning, not an
+      // error. The flow builds, but the analyzer slot is empty so
+      // capture won't actually do ML at runtime. Partners surface
+      // this via b.validate().
+      buildOk((b) => {
+        b.screens((screens) =>
+          screens.capture((c) => {
+            c.captureType = CaptureType.selfie;
+          }),
+        );
+      });
+    });
+
+    it("runFlowValidation surfaces missing ml block as a warning issue", async () => {
+      // The full validator surfaces the warning. `b.validate()` is
+      // intentionally narrowed to empty-screens triage; the warning
+      // surface is internal to `build()` and consumed via the
+      // dispatcher's logging.
+      const { MissingMLConfigurationBlockException } =
+        await import("../core/exception/job_validation_exceptions");
+      const { runFlowValidation } =
+        await import("../presentation/flow/validation/flow_validator");
+      const captureConfig = new CaptureConfigBuilder();
+      captureConfig.captureType = CaptureType.selfie;
+      const issues = runFlowValidation({
+        steps: [
+          {
+            kind: "capture",
+            config: captureConfig,
+          },
+        ],
+      });
+      const issue = issues.find(
+        (i) => i instanceof MissingMLConfigurationBlockException,
+      );
+      expect(issue).toBeDefined();
+      expect(issue?.severity).toBe("warning");
+    });
+
+    it("fails the build when a processing screen has no network block (strict: jobType is required)", () => {
+      // Strict contract (parity with Android/Flutter): a processing screen
+      // always requires a resolved jobType, so a no-network flow fails with
+      // the jobType error (alongside the missing-network warning).
+      expectBuildInvalid((b) => {
+        b.screens((screens) => screens.processing());
+      }, /jobType is not set/i);
+    });
+
+    it("requires a configured `jobType` when a processing screen is present", () => {
+      expectBuildInvalid((b) => {
+        b.screens((screens) => screens.processing());
+        b.network((n) => {
+          n.config((c) => {
+            c.token = "k";
+            c.partnerConfig((p) => {
+              p.partnerId = "p";
+              p.callbackUrl = "";
+              p.useSandbox = true;
+            });
+          });
+        });
+      }, /jobType is not set/i);
+    });
+
+    it("rejects consent screen + pre-supplied consentInformation as mutually exclusive", () => {
+      expectBuildInvalid((b) => {
+        b.consentInformation = {
+          granted: true,
+          grantedAt: "2026-01-01T00:00:00.000Z",
+          noticeLanguage: "EN",
+          noticePrivacyPolicyUrl: "https://example.test/p",
+        };
+        b.screens((screens) => {
+          screens.consent();
+          screens.instructions();
+        });
+      }, /Exactly one form of consent is required/);
+    });
+
+    it("rejects consent that has not been granted", () => {
+      expectBuildInvalid((b) => {
+        b.consentInformation = {
+          granted: false,
+          grantedAt: "2026-01-01T00:00:00.000Z",
+          noticeLanguage: "EN",
+          noticePrivacyPolicyUrl: "https://example.test/p",
+        };
+        withMinimalScreens(b);
+      }, /granted must be true/i);
+    });
+
+    it("rejects EnhancedKYCParams with blank required fields", () => {
+      expectBuildInvalid((b) => {
+        b.enhancedKYCParams = {
+          idType: "NATIONAL_ID",
+          idNumber: "",
+          country: "KE",
+        };
+        b.userDetails = {
+          givenNames: "John",
+          lastName: "Doe",
+          email: "x@y",
+          phoneNumber: "+254000000000",
+        };
+        withMinimalScreens(b);
+      }, /Invalid value for field 'idNumber': must not be blank/i);
+    });
+
+    it("rejects userDetails (top-level) with blank givenNames", () => {
+      expectBuildInvalid((b) => {
+        b.enhancedKYCParams = {
+          idType: "NATIONAL_ID",
+          idNumber: "1",
+          country: "KE",
+        };
+        b.userDetails = {
+          givenNames: " ",
+          lastName: "Doe",
+          email: "x@y",
+        };
+        withMinimalScreens(b);
+      }, /Invalid value for field 'userDetails\.givenNames': must not be blank/i);
+    });
+
+    it("rejects userDetails missing both email and phoneNumber", () => {
+      expectBuildInvalid((b) => {
+        b.biometricKYCParams = {
+          idType: "NATIONAL_ID",
+          idNumber: "1",
+          country: "KE",
+          useEnrolledImage: false,
+        };
+        b.userDetails = {
+          givenNames: "John",
+          lastName: "Doe",
+        };
+        withMinimalScreens(b);
+      }, /at least one of email or phoneNumber/i);
+    });
+
+    it("rejects consent screen appearing after the first slot", () => {
+      expectBuildInvalid((b) => {
+        b.screens((screens) => {
+          screens.instructions();
+          screens.consent();
+        });
+      }, /consent screen must be the first/i);
+    });
+
+    it("rejects preview without a preceding capture", () => {
+      expectBuildInvalid((b) => {
+        b.screens((screens) => {
+          screens.preview();
+        });
+      }, /Preview screen at index \d+ has no preceding Capture screen/i);
+    });
+
+    it("rejects empty partnerName when a consent screen is in the flow", () => {
+      // partnerName feeds the consent attribution line; an empty
+      // value renders blank, which partners typically don't notice
+      // until QA. The rule fails the build instead.
+      expectBuildInvalid((b) => {
+        b.screens((screens) => {
+          screens.consent();
+          screens.instructions();
+        });
+      }, /partnerName cannot be empty/i);
+    });
+
+    it("rejects missing partnerIcon when a consent screen is in the flow", () => {
+      expectBuildInvalid((b) => {
+        b.screens((screens) => {
+          screens.consent((c) => {
+            c.partnerName = "Acme";
+            c.partnerPrivacyPolicyUrl = "https://acme.com/privacy";
+          });
+          screens.instructions();
+        });
+      }, /partnerIcon is required for the consent screen/i);
+    });
+
+    it("rejects missing partnerPrivacyPolicyUrl when a consent screen is in the flow", () => {
+      expectBuildInvalid((b) => {
+        b.screens((screens) => {
+          screens.consent((c) => {
+            c.partnerName = "Acme";
+            c.partnerIcon = "icon";
+          });
+          screens.instructions();
+        });
+      }, /partnerPrivacyPolicyUrl is required for the consent screen/i);
+    });
+
+    describe("non-capture jobType screen restrictions", () => {
+      // Concrete scenario: Enhanced KYC and BVN are non-biometric job
+      // types — they collect identity fields, not selfies / documents.
+      // The validator therefore rejects any capture-pipeline screen
+      // (capture / preview / instructions) when one of those job types
+      // is configured, and requires a consent step plus a processing
+      // step. Enhanced KYC additionally requires `enhancedKYCParams`.
+
+      const VALID_CONSENT = Object.freeze({
+        granted: true,
+        grantedAt: "2026-04-30T00:00:00.000Z",
+        noticeLanguage: "EN",
+        noticePrivacyPolicyUrl: "https://example.test/p",
+      });
+
+      const VALID_ENHANCED_KYC_PARAMS = Object.freeze({
+        idType: "NATIONAL_ID",
+        idNumber: "1",
+        country: "KE",
+      });
+
+      const VALID_USER_DETAILS = Object.freeze({
+        givenNames: "John",
+        lastName: "Doe",
+        email: "john@example.test",
+      });
+
+      function withNonCaptureNetwork(
+        b: UseSmileIDFlowBuilder,
+        jobType: JobType,
+      ): void {
+        b.network((n) => {
+          n.config((c) => {
+            c.jobType = jobType;
+            c.token = "k";
+            c.partnerConfig((p) => {
+              p.partnerId = "p";
+              p.callbackUrl = "";
+              p.useSandbox = true;
+            });
+          });
+        });
+      }
+
+      it("rejects a Capture screen when jobType is enhancedKyc", () => {
+        expectBuildInvalid((b) => {
+          b.consentInformation = VALID_CONSENT;
+          b.enhancedKYCParams = VALID_ENHANCED_KYC_PARAMS;
+          b.userDetails = VALID_USER_DETAILS;
+          b.screens((screens) => {
+            screens.capture((c) => {
+              c.captureType = CaptureType.selfie;
+            });
+            screens.processing();
+          });
+          withNonCaptureNetwork(b, JobType.enhancedKyc);
+        }, /must only contain consent and processing screens, but found: capture/i);
+      });
+
+      it("rejects a Preview screen when jobType is enhancedKyc", () => {
+        expectBuildInvalid((b) => {
+          b.consentInformation = VALID_CONSENT;
+          b.enhancedKYCParams = VALID_ENHANCED_KYC_PARAMS;
+          b.userDetails = VALID_USER_DETAILS;
+          b.screens((screens) => {
+            screens.capture((c) => {
+              c.captureType = CaptureType.selfie;
+            });
+            screens.preview();
+            screens.processing();
+          });
+          withNonCaptureNetwork(b, JobType.enhancedKyc);
+        }, /must only contain consent and processing screens, but found: capture, preview/i);
+      });
+
+      it("rejects an Instructions screen when jobType is enhancedKyc", () => {
+        expectBuildInvalid((b) => {
+          b.consentInformation = VALID_CONSENT;
+          b.enhancedKYCParams = VALID_ENHANCED_KYC_PARAMS;
+          b.userDetails = VALID_USER_DETAILS;
+          b.screens((screens) => {
+            screens.instructions();
+            screens.processing();
+          });
+          withNonCaptureNetwork(b, JobType.enhancedKyc);
+        }, /must only contain consent and processing screens, but found: instructions/i);
+      });
+
+      it("rejects a Capture screen when jobType is bvn", () => {
+        expectBuildInvalid((b) => {
+          b.consentInformation = VALID_CONSENT;
+          b.enhancedKYCParams = VALID_ENHANCED_KYC_PARAMS;
+          b.userDetails = VALID_USER_DETAILS;
+          b.screens((screens) => {
+            screens.capture((c) => {
+              c.captureType = CaptureType.selfie;
+            });
+            screens.processing();
+          });
+          withNonCaptureNetwork(b, JobType.bvn);
+        }, /must only contain consent and processing screens, but found: capture/i);
+      });
+
+      it("requires a processing() screen for enhancedKyc", () => {
+        expectBuildInvalid((b) => {
+          b.consentInformation = VALID_CONSENT;
+          b.enhancedKYCParams = VALID_ENHANCED_KYC_PARAMS;
+          b.userDetails = VALID_USER_DETAILS;
+          b.screens((screens) => {
+            // Intentionally no processing screen; the validator
+            // surfaces a separate processing-required issue.
+            screens.consent((c) => {
+              c.partnerName = "Acme";
+              c.partnerIcon = "icon";
+              c.partnerPrivacyPolicyUrl = "https://acme.test/p";
+            });
+          });
+          withNonCaptureNetwork(b, JobType.enhancedKyc);
+        }, /Invalid configuration for EnhancedKyc: must include a Processing screen/i);
+      });
+
+      it("requires a consent step (screen or pre-supplied) for enhancedKyc", () => {
+        expectBuildInvalid((b) => {
+          b.enhancedKYCParams = VALID_ENHANCED_KYC_PARAMS;
+          b.screens((screens) => {
+            screens.processing();
+          });
+          withNonCaptureNetwork(b, JobType.enhancedKyc);
+        }, /must include either a Consent screen or a pre-supplied consentInformation/i);
+      });
+
+      it("requires `enhancedKYCParams` when jobType is enhancedKyc", () => {
+        expectBuildInvalid((b) => {
+          b.consentInformation = VALID_CONSENT;
+          b.screens((screens) => {
+            screens.processing();
+          });
+          withNonCaptureNetwork(b, JobType.enhancedKyc);
+        }, /enhancedKYCParams is required for EnhancedKyc jobs/i);
+      });
+
+      it("does NOT require enhancedKYCParams when jobType is bvn", () => {
+        // BVN reuses the EnhancedKYC params shape but the validator
+        // does not surface the missing-enhancedKYCParams rule for
+        // bvn — the repository rejects the variant up front with an
+        // "unsupported" error before params are inspected.
+        const result = useSmileIDBuilder((b) => {
+          b.consentInformation = VALID_CONSENT;
+          b.screens((screens) => {
+            screens.processing();
+          });
+          withNonCaptureNetwork(b, JobType.bvn);
+        });
+        const messages =
+          result.kind === "invalid"
+            ? result.validation.issues.map((i) => i.message).join(" || ")
+            : "";
+        expect(/enhancedKYCParams is required/i.test(messages)).toBe(false);
+      });
+    });
+  });
+
+  describe("validateConsent() in isolation", () => {
+    // Partners pre-flight a `ConsentInformation` payload pulled from
+    // their own storage before assigning it to `b.consentInformation`.
+    // The method runs the same rules as the in-flow consent
+    // validation but without requiring the rest of the builder state
+    // to be set.
+
+    it("returns Valid for a well-formed payload", () => {
+      const builder = new UseSmileIDFlowBuilder();
+      const state = builder.validateConsent({
+        granted: true,
+        grantedAt: "2026-01-01T00:00:00.000Z",
+        noticeLanguage: "EN",
+        noticePrivacyPolicyUrl: "https://example.test/privacy",
+      });
+      expect(state.valid).toBe(true);
+    });
+
+    it("returns Invalid with typed issues for malformed payload", async () => {
+      const { InvalidConsentInformationException } =
+        await import("../core/exception/consent_validation_exceptions");
+      const builder = new UseSmileIDFlowBuilder();
+      const state = builder.validateConsent({
+        granted: false,
+        // whitespace-only grantedAt — must trigger the non-blank
+        // rule. A naive `!value` check would let this through and
+        // the malformed payload would silently flow downstream.
+        grantedAt: "   ",
+        noticeLanguage: "EN",
+        noticePrivacyPolicyUrl: "https://example.test/p",
+      });
+      expect(state.valid).toBe(false);
+      if (!state.valid) {
+        const details = state.issues
+          .filter(
+            (e): e is InstanceType<typeof InvalidConsentInformationException> =>
+              e instanceof InvalidConsentInformationException,
+          )
+          .map((e) => e.message);
+        expect(details).toContain(
+          "Invalid consent information: granted must be true",
+        );
+        expect(details).toContain(
+          "Invalid consent information: grantedAt must not be blank",
+        );
+      }
+    });
+
+    it("does not depend on builder state — runs against the supplied payload only", () => {
+      const builder = new UseSmileIDFlowBuilder();
+      // Builder state is otherwise empty (would fail full validate()
+      // on the empty-screens rule), but validateConsent() inspects
+      // only the payload argument.
+      const state = builder.validateConsent({
+        granted: true,
+        grantedAt: "2026-01-01T00:00:00.000Z",
+        noticeLanguage: "EN",
+        noticePrivacyPolicyUrl: "https://example.test/privacy",
+      });
+      expect(state.valid).toBe(true);
+    });
+  });
+
+  describe("validateEnhancedKYCParams() / validateBiometricKYCParams() / validateUserDetails() in isolation", () => {
+    // Partners pre-flight payloads (e.g. pulled from a form or a
+    // remote config) before assigning to `b.enhancedKYCParams` /
+    // `b.biometricKYCParams` / `b.userDetails`. KYC param rules cover
+    // ID + country non-blank; UserDetails rules cover name fields
+    // non-blank, and at least one of email / phoneNumber.
+
+    it("validateEnhancedKYCParams accepts a well-formed payload", () => {
+      const builder = new UseSmileIDFlowBuilder();
+      const state = builder.validateEnhancedKYCParams({
+        idType: "NATIONAL_ID",
+        idNumber: "1234567890",
+        country: "KE",
+      });
+      expect(state.valid).toBe(true);
+    });
+
+    it("validateEnhancedKYCParams rejects blank required fields", async () => {
+      const { InvalidFieldValueException } =
+        await import("../core/exception/job_validation_exceptions");
+      const builder = new UseSmileIDFlowBuilder();
+      const state = builder.validateEnhancedKYCParams({
+        idType: "",
+        idNumber: "",
+        country: "",
+      });
+      expect(state.valid).toBe(false);
+      if (!state.valid) {
+        const reasons = state.issues
+          .filter(
+            (e): e is InstanceType<typeof InvalidFieldValueException> =>
+              e instanceof InvalidFieldValueException,
+          )
+          .map((e) => e.message);
+        // Each blank top-level field surfaces its own typed issue.
+        expect(reasons.some((m) => /idType/.test(m))).toBe(true);
+        expect(reasons.some((m) => /idNumber/.test(m))).toBe(true);
+        expect(reasons.some((m) => /country/.test(m))).toBe(true);
+      }
+    });
+
+    it("validateUserDetails rejects payload missing both email and phoneNumber", () => {
+      const builder = new UseSmileIDFlowBuilder();
+      const state = builder.validateUserDetails({
+        givenNames: "Ada",
+        lastName: "Lovelace",
+      });
+      expect(state.valid).toBe(false);
+      if (!state.valid) {
+        const matched = state.issues.some((i) =>
+          /at least one of email or phoneNumber/.test(i.message),
+        );
+        expect(matched).toBe(true);
+      }
+    });
+
+    it("validateUserDetails accepts a well-formed payload", () => {
+      const builder = new UseSmileIDFlowBuilder();
+      const state = builder.validateUserDetails({
+        givenNames: "Ada",
+        lastName: "Lovelace",
+        email: "ada@example.test",
+      });
+      expect(state.valid).toBe(true);
+    });
+
+    it("validateBiometricKYCParams accepts a well-formed payload (no userDetails on the params type)", () => {
+      // userDetails moved to a top-level builder field — params no
+      // longer carries it.
+      const builder = new UseSmileIDFlowBuilder();
+      const state = builder.validateBiometricKYCParams({
+        idType: "NATIONAL_ID",
+        idNumber: "1234567890",
+        country: "KE",
+        useEnrolledImage: false,
+      });
+      expect(state.valid).toBe(true);
+    });
+
+    it("validateDocumentVerificationParams accepts a country-only payload (idType optional)", () => {
+      const builder = new UseSmileIDFlowBuilder();
+      expect(
+        builder.validateDocumentVerificationParams({ country: "KE" }).valid,
+      ).toBe(true);
+    });
+
+    it("validateDocumentVerificationParams rejects a blank country", () => {
+      const builder = new UseSmileIDFlowBuilder();
+      expect(
+        builder.validateDocumentVerificationParams({ country: " " }).valid,
+      ).toBe(false);
+    });
+
+    it("validateEnhancedDocumentVerificationParams requires both country and idType", () => {
+      const builder = new UseSmileIDFlowBuilder();
+      expect(
+        builder.validateEnhancedDocumentVerificationParams({
+          country: "KE",
+          idType: "",
+        }).valid,
+      ).toBe(false);
+      expect(
+        builder.validateEnhancedDocumentVerificationParams({
+          country: "KE",
+          idType: "NATIONAL_ID",
+        }).valid,
+      ).toBe(true);
+    });
+  });
+
+  describe("typed exception hierarchy", () => {
+    it("build() returns the typed exception itself in validation, not a wrapping Error", async () => {
+      const { EmptyScreensBlockException } =
+        await import("../core/exception/screen_config_validation_exceptions");
+      const result = useSmileIDBuilder(() => {});
+      expect(result.kind).toBe("invalid");
+      if (result.kind === "invalid") {
+        expect(result.validation.issues[0]).toBeInstanceOf(
+          EmptyScreensBlockException,
+        );
+      }
+    });
+
+    it("validation exceptions extend UseSmileIDBuilderException → UseSmileIDValidationException → UseSmileIDException", async () => {
+      const { UseSmileIDBuilderException } =
+        await import("../core/exception/use_smile_id_builder_exception");
+      const { UseSmileIDValidationException } =
+        await import("../core/exception/use_smile_id_validation_exception");
+      const { UseSmileIDException } =
+        await import("../core/exception/use_smile_id_exception");
+      const result = useSmileIDBuilder(() => {});
+      expect(result.kind).toBe("invalid");
+      if (result.kind === "invalid") {
+        const issue = result.validation.issues[0];
+        expect(issue).toBeInstanceOf(UseSmileIDBuilderException);
+        expect(issue).toBeInstanceOf(UseSmileIDValidationException);
+        expect(issue).toBeInstanceOf(UseSmileIDException);
+        expect(issue).toBeInstanceOf(Error);
+      }
+    });
+
+    it("validation exceptions carry typed errorCode + severity + suggestedFix + name", async () => {
+      const { EmptyScreensBlockException } =
+        await import("../core/exception/screen_config_validation_exceptions");
+      const { UseSmileIDErrorCode } =
+        await import("../core/exception/use_smile_id_error_code");
+      const result = useSmileIDBuilder(() => {});
+      expect(result.kind).toBe("invalid");
+      if (result.kind === "invalid") {
+        const issue = result.validation.issues[0];
+        if (!(issue instanceof EmptyScreensBlockException))
+          throw new Error("wrong type");
+        expect(issue.errorCode).toBe(
+          UseSmileIDErrorCode.Builder.EmptyScreensBlock,
+        );
+        expect(issue.severity).toBe("error");
+        expect(typeof issue.suggestedFix).toBe("string");
+        expect(issue.name).toBe("EmptyScreensBlockException");
+      }
+    });
+
+    it("validate() returns issues as the same typed exception instances build() would throw", async () => {
+      const { EmptyScreensBlockException } =
+        await import("../core/exception/screen_config_validation_exceptions");
+      const builder = new UseSmileIDFlowBuilder();
+      const state = builder.validate();
+      expect(state.valid).toBe(false);
+      if (!state.valid) {
+        expect(state.issues[0]).toBeInstanceOf(EmptyScreensBlockException);
+      }
+    });
+  });
+
+  describe("top-level mutable properties", () => {
+    it("captures consentInformation, onResult, onAnalyticsEvent", () => {
+      const onResult = vi.fn();
+      const onAnalyticsEvent = vi.fn();
+      const consentInformation = {
+        granted: true,
+        grantedAt: "2024-01-01T00:00:00.000Z",
+        noticeLanguage: "EN",
+        noticePrivacyPolicyUrl: "https://example.test/privacy",
+      };
+      const config = buildOk((b) => {
+        b.consentInformation = consentInformation;
+        b.onResult = onResult;
+        b.onAnalyticsEvent = onAnalyticsEvent;
+        withMinimalScreens(b);
+      });
+      expect(config.consentInformation).toEqual(consentInformation);
+      expect(config.onResult).toBe(onResult);
+      expect(config.onAnalyticsEvent).toBe(onAnalyticsEvent);
+    });
+
+    it("defaults onResult to a no-op when the partner does not set it", () => {
+      const config = buildOk((b) => {
+        withMinimalScreens(b);
+      });
+      // onResult is non-nullable on the snapshot, so calling it must
+      // never throw. Concrete scenario: the SDK invokes onResult on
+      // every flow exit; a partner who skipped wiring a handler would
+      // have crashed before this default.
+      expect(() =>
+        config.onResult({
+          status: "success",
+          value: { userId: "", jobId: "", status: "", message: "" },
+        }),
+      ).not.toThrow();
+    });
+  });
+
+  it("omits absent optional blocks entirely — exactOptionalPropertyTypes contract", () => {
+    // Concrete scenario: with `exactOptionalPropertyTypes: true`,
+    // omitting `b.network(...)` must NOT result in
+    // `snapshot.network = undefined` — the key must be absent
+    // outright. A future refactor that emits `undefined` would
+    // silently break partners running TS strict.
+    const config = buildOk((b) => {
+      withMinimalScreens(b);
+    });
+    expect("network" in config).toBe(false);
+    expect("ml" in config).toBe(false);
+    expect("config" in config).toBe(false);
+    expect("theme" in config).toBe(false);
+    expect("consentInformation" in config).toBe(false);
+    expect("enhancedKYCParams" in config).toBe(false);
+    expect("biometricKYCParams" in config).toBe(false);
+    expect("onAnalyticsEvent" in config).toBe(false);
+    // `screens` and `onResult` are always present (build() guarantees).
+    expect("screens" in config).toBe(true);
+    expect("onResult" in config).toBe(true);
+  });
+
+  describe("BuilderValidationException", () => {
+    it("carries the full ValidationStateInvalid for partner inspection", async () => {
+      const { BuilderValidationException } =
+        await import("../core/exception/builder_validation_exception");
+      const { EmptyScreensBlockException } =
+        await import("../core/exception/screen_config_validation_exceptions");
+      const { UseSmileIDBuilderException } =
+        await import("../core/exception/use_smile_id_builder_exception");
+      const { UseSmileIDValidationException } =
+        await import("../core/exception/use_smile_id_validation_exception");
+
+      const exception = new BuilderValidationException({
+        valid: false,
+        issues: [new EmptyScreensBlockException()],
+      });
+
+      // Hierarchy assertions — partners catching one of the abstract
+      // bases must see this concrete exception.
+      expect(exception).toBeInstanceOf(UseSmileIDBuilderException);
+      expect(exception).toBeInstanceOf(UseSmileIDValidationException);
+      expect(exception).toBeInstanceOf(Error);
+
+      // Payload — full state, not just primaryIssue.
+      expect(exception.validationState.issues).toHaveLength(1);
+      expect(exception.validationState.issues[0]).toBeInstanceOf(
+        EmptyScreensBlockException,
+      );
+      expect(exception.message).toMatch(/Flow validation failed/i);
+    });
+  });
+
+  describe("UseSmileIDFlowBuilder.validate — builder-only scope", () => {
+    it("reports empty-screens as the only triage rule", async () => {
+      const { EmptyScreensBlockException } =
+        await import("../core/exception/screen_config_validation_exceptions");
+      const builder = new UseSmileIDFlowBuilder();
+      const state = builder.validate();
+      expect(state.valid).toBe(false);
+      if (!state.valid) {
+        expect(state.issues[0]).toBeInstanceOf(EmptyScreensBlockException);
+      }
+    });
+
+    it("returns Valid when at least one screen is registered — even with missing-ml warnings", () => {
+      // Full validator would flag missing-ml as a warning here, but
+      // builder.validate() is intentionally narrowed to the
+      // empty-screens triage. Full validation runs inside build().
+      const builder = new UseSmileIDFlowBuilder();
+      builder.screens((screens) =>
+        screens.capture((c) => {
+          c.captureType = CaptureType.selfie;
+        }),
+      );
+      expect(builder.validate().valid).toBe(true);
+    });
+  });
+});