@smileid/usesmileid 12.0.2 → 12.1.1

package/src/__tests__/dsl.test.ts

@@ -1,1165 +0,0 @@
-import { GlobalPrivacyControl } from "../core/models/global_privacy_control";
-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("global privacy control defaults to opt-out", () => {
-      const config = buildOk((b) => {
-        withMinimalScreens(b);
-        b.config(() => {});
-      });
-      expect(config.config?.globalPrivacyControl).toBe(
-        GlobalPrivacyControl.OptOut,
-      );
-    });
-
-    it("global privacy control opt-in flows from the config block", () => {
-      const config = buildOk((b) => {
-        withMinimalScreens(b);
-        b.config((c) => {
-          c.globalPrivacyControl = GlobalPrivacyControl.OptIn;
-        });
-      });
-      expect(config.config?.globalPrivacyControl).toBe(
-        GlobalPrivacyControl.OptIn,
-      );
-    });
-
-    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;
-            // Mutually exclusive, so the closure is exercised one flag at a time.
-            cap.selfie((sel) => {
-              sel.allowAgentMode = 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(
-          false,
-        );
-      }
-    });
-
-    it("capture(...) plumbs enableEnhancedLiveness through the selfie 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.enableEnhancedLiveness = true;
-            });
-          });
-        });
-      });
-      const captureStep = config.screens.steps[0];
-      if (captureStep?.kind === "capture") {
-        expect(captureStep.config.selfieConfig?.enableEnhancedLiveness).toBe(
-          true,
-        );
-        expect(captureStep.config.selfieConfig?.allowAgentMode).toBe(false);
-      }
-    });
-  });
-
-  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);
-    });
-  });
-});