@smileid/usesmileid 12.0.1 → 12.1.0

package/src/presentation/flow/validation/job_type_validator.ts

@@ -1,669 +0,0 @@
-import type { MLConfig } from "../../../core/models/ml_config";
-import type { NetworkConfig } from "../../../core/models/network_config";
-import type {
-  BiometricKYCParams,
-  ConsentInformation,
-  DocumentVerificationParams,
-  EnhancedDocumentVerificationParams,
-  EnhancedKYCParams,
-  UserDetails,
-} from "../../../core/models/params";
-import { JobType } from "../../../core/models/job_type";
-import type { ScreenSpec } from "../dsl/builder/screens_builder";
-import { CaptureType } from "../dsl/builder/screens_builder";
-import { InvalidJobTypeScreenConfigException } from "../../../core/exception/job_validation_exceptions";
-import {
-  DuplicateScreenTypeException,
-  InvalidScreenOrderException,
-  MissingCaptureForPreviewException,
-} from "../../../core/exception/screen_config_validation_exceptions";
-import { IssueSeverity } from "../../../core/exception/issue_severity";
-import type { ValidationIssue } from "./validation_state";
-
-/**
- * Job-type-specific flow validation rules.
- *
- * Every rule that decides whether a flow's screen composition is valid
- * for the configured job lives in this module — duplicate screen types,
- * screen ordering, preview placement, ML analyzer dependencies, consent
- * presence, capture counts, processing, and per-job field requirements.
- * `FlowValidator` only owns the builder / job-agnostic concerns (empty
- * screens, per-screen config, ML / Network block presence, missing job
- * type) before dispatching to the matching validator.
- *
- * Adding a new job type requires only a new entry in
- * `FlowValidator`'s `jobTypeValidators` registry — `FlowValidator`
- * itself never changes.
- *
- * Each rule appends typed `InvalidJobTypeScreenConfigException` /
- * `DuplicateScreenTypeException` / `InvalidScreenOrderException` /
- * `MissingCaptureForPreviewException` instances so partner tooling can
- * pivot on `errorCode` or regex-match on the message text.
- */
-
-/**
- * A `JobTypeValidator` runs every composition rule for one job type and
- * appends any findings to `issues`. Implemented as a class per job-type
- * family so the registry can map a `JobType` to a single instance.
- */
-export interface JobTypeValidator {
-  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void;
-}
-
-/**
- * Inputs the job-type rules read. A subset of the `FlowValidator`
- * input — only the fields the per-`JobType` rules actually consume.
- */
-export type JobTypeValidatorInput = {
-  readonly steps: readonly ScreenSpec[];
-  readonly network?: NetworkConfig | undefined;
-  readonly ml?: MLConfig | undefined;
-  readonly consentInformation?: ConsentInformation | undefined;
-  readonly enhancedKYCParams?: EnhancedKYCParams | undefined;
-  readonly biometricKYCParams?: BiometricKYCParams | undefined;
-  readonly documentVerificationParams?: DocumentVerificationParams | undefined;
-  readonly enhancedDocumentVerificationParams?:
-    | EnhancedDocumentVerificationParams
-    | undefined;
-  readonly userDetails?: UserDetails | undefined;
-};
-
-/**
- * Stable display label for a `JobType` enum value, matching the
- * canonical name carried in the `Invalid configuration for {name}:`
- * message string. The DSL-facing `JobType` keys are camelCase; this map
- * supplies the PascalCase label used in partner-visible copy.
- */
-const JOB_TYPE_NAMES: ReadonlyMap<JobType, string> = new Map<JobType, string>([
-  [JobType.biometricKyc, "BiometricKyc"],
-  [JobType.smartSelfieAuthentication, "SmartSelfieAuthentication"],
-  [JobType.smartSelfieEnrollment, "SmartSelfieEnrollment"],
-  [JobType.enhancedKyc, "EnhancedKyc"],
-  [JobType.documentVerification, "DocumentVerification"],
-  [JobType.bvn, "BVN"],
-  [JobType.enhancedDocumentVerification, "EnhancedDocumentVerification"],
-  [JobType.unknown, "Unknown"],
-]);
-
-/**
- * Resolve the partner-visible label for a `JobType` value.
- */
-function jobTypeName(jobType: JobType): string {
-  return JOB_TYPE_NAMES.get(jobType) ?? "Unknown";
-}
-
-/**
- * Consent rule: exactly one form of consent is required — either a
- * Consent screen or pre-supplied `consentInformation`, never both and
- * never neither.
- */
-function appendConsentRule(
-  jobType: JobType,
-  input: JobTypeValidatorInput,
-  issues: ValidationIssue[],
-): void {
-  const hasConsentScreen = input.steps.some((s) => s.kind === "consent");
-  const hasConsentInformation = input.consentInformation !== undefined;
-  if (!hasConsentScreen && !hasConsentInformation) {
-    issues.push(
-      InvalidJobTypeScreenConfigException.forJob({
-        jobType,
-        reason:
-          "must include either a Consent screen or a pre-supplied consentInformation",
-        suggestedFix:
-          "Add a consent { } screen to your flow, or supply consentInformation via the builder",
-      }),
-    );
-  } else if (hasConsentScreen && hasConsentInformation) {
-    issues.push(
-      InvalidJobTypeScreenConfigException.forJob({
-        jobType,
-        reason:
-          "must not include both a Consent screen and a pre-supplied consentInformation — use one or the other",
-        suggestedFix:
-          "Remove the consent { } screen if supplying consentInformation, or clear consentInformation if using the consent screen",
-      }),
-    );
-  }
-}
-
-/**
- * Reject more than one screen of any non-Capture, non-Preview type.
- * Capture screens may repeat (selfie + document) and Preview screens are
- * governed by the per-job preview rule instead, so both are excluded.
- */
-function appendDuplicateScreenRule(
-  steps: readonly ScreenSpec[],
-  issues: ValidationIssue[],
-): void {
-  const indicesByKind = new Map<string, number[]>();
-  steps.forEach((step, index) => {
-    if (step.kind === "capture" || step.kind === "preview") return;
-    const list = indicesByKind.get(step.kind) ?? [];
-    list.push(index);
-    indicesByKind.set(step.kind, list);
-  });
-  for (const [kind, indices] of indicesByKind) {
-    if (indices.length > 1) {
-      issues.push(
-        new DuplicateScreenTypeException({ screenType: kind, indices }),
-      );
-    }
-  }
-}
-
-/**
- * Enforce consent-first, processing-last, and instructions-before-capture
- * ordering. Preview ordering is handled by `appendPreviewRule`.
- */
-function appendScreenOrderRule(
-  steps: readonly ScreenSpec[],
-  issues: ValidationIssue[],
-): void {
-  const consentIndex = steps.findIndex((s) => s.kind === "consent");
-  if (consentIndex > 0) {
-    issues.push(
-      new InvalidScreenOrderException({
-        description: "Consent screen must be the first screen in the flow",
-        severity: IssueSeverity.error,
-      }),
-    );
-  }
-  const processingIndex = steps.findIndex((s) => s.kind === "processing");
-  if (processingIndex !== -1 && processingIndex !== steps.length - 1) {
-    issues.push(
-      new InvalidScreenOrderException({
-        description: "Processing screen must be the last screen in the flow",
-        severity: IssueSeverity.error,
-      }),
-    );
-  }
-  let hasCaptureBeforeThisPoint = false;
-  steps.forEach((step, index) => {
-    if (step.kind === "capture") {
-      hasCaptureBeforeThisPoint = true;
-    } else if (step.kind === "instructions" && hasCaptureBeforeThisPoint) {
-      issues.push(
-        new InvalidScreenOrderException({
-          description: `Instructions screen at index ${index} must appear before the Capture screen`,
-          severity: IssueSeverity.error,
-        }),
-      );
-    }
-  });
-}
-
-/**
- * Preview rule for flows that allow at most `maxPreviews` preview
- * screens, each of which must follow a Capture screen. A preview with
- * no preceding capture emits `MissingCaptureForPreviewException`; an
- * extra preview beyond `maxPreviews` emits `InvalidScreenOrderException`.
- */
-function appendPreviewRule(
-  steps: readonly ScreenSpec[],
-  maxPreviews: number,
-  issues: ValidationIssue[],
-): void {
-  let hasCaptureBeforeThisPoint = false;
-  let previewCount = 0;
-  steps.forEach((step, index) => {
-    if (step.kind === "capture") {
-      hasCaptureBeforeThisPoint = true;
-    } else if (step.kind === "preview") {
-      previewCount += 1;
-      if (!hasCaptureBeforeThisPoint) {
-        issues.push(
-          new MissingCaptureForPreviewException({ previewIndex: index }),
-        );
-      } else if (previewCount > maxPreviews) {
-        issues.push(
-          new InvalidScreenOrderException({
-            description: `Preview screen at index ${index} exceeds the maximum of ${maxPreviews} preview screen(s) allowed for this flow`,
-            severity: IssueSeverity.error,
-          }),
-        );
-      }
-    }
-  });
-}
-
-/**
- * Processing screen is required for every job type. The companion
- * `network { }` block requirement is surfaced by `FlowValidator`
- * (job-agnostic) to keep a single emission point.
- */
-function appendProcessingRule(
-  jobType: JobType,
-  input: JobTypeValidatorInput,
-  issues: ValidationIssue[],
-): void {
-  const hasProcessingScreen = input.steps.some((s) => s.kind === "processing");
-  if (!hasProcessingScreen) {
-    issues.push(
-      InvalidJobTypeScreenConfigException.forJob({
-        jobType,
-        reason: "must include a Processing screen",
-        suggestedFix:
-          "Add a processing { } screen as the last screen in the flow",
-      }),
-    );
-  }
-}
-
-/**
- * Enforce exactly one selfie Capture screen.
- */
-function appendSelfieCaptureRule(
-  jobType: JobType,
-  input: JobTypeValidatorInput,
-  issues: ValidationIssue[],
-): void {
-  const selfieCaptures = input.steps.filter(
-    (s) => s.kind === "capture" && s.config.captureType === CaptureType.selfie,
-  );
-  if (selfieCaptures.length === 0) {
-    issues.push(
-      InvalidJobTypeScreenConfigException.forJob({
-        jobType,
-        reason:
-          "must include exactly one Capture screen with captureType = SELFIE",
-        suggestedFix:
-          "Add a capture { captureType = CaptureType.SELFIE } screen to your flow",
-      }),
-    );
-  } else if (selfieCaptures.length > 1) {
-    issues.push(
-      InvalidJobTypeScreenConfigException.forJob({
-        jobType,
-        reason: `must include exactly one Capture screen with captureType = SELFIE, but found ${selfieCaptures.length}`,
-        suggestedFix:
-          "Remove the extra selfie capture screens — only one is allowed",
-      }),
-    );
-  }
-}
-
-/**
- * Validate the selfie ML analyzer dependency. A Capture screen requires
- * an `ml { }` block, and that block must register analyzers for
- * `CaptureType.SELFIE`. The missing-block warning is owned by
- * `FlowValidator`; this rule emits only the error-severity
- * `InvalidJobTypeScreenConfigException`.
- */
-function appendSelfieMlRule(
-  jobType: JobType,
-  input: JobTypeValidatorInput,
-  missingMlSuggestedFix: string,
-  issues: ValidationIssue[],
-): void {
-  if (!input.ml) {
-    issues.push(
-      InvalidJobTypeScreenConfigException.forJob({
-        jobType,
-        reason:
-          "ml { } block is required and must register analyzers for CaptureType.SELFIE",
-        suggestedFix: missingMlSuggestedFix,
-      }),
-    );
-  } else if (!input.ml.analyzers.selfie) {
-    issues.push(
-      InvalidJobTypeScreenConfigException.forJob({
-        jobType,
-        reason: "ml { } block must register analyzers for CaptureType.SELFIE",
-        suggestedFix:
-          "Add forCaptureType(CaptureType.SELFIE) { } inside the ml { } block",
-      }),
-    );
-  }
-}
-
-/**
- * Validates selfie-only flows: BiometricKyc, SmartSelfieAuthentication,
- * SmartSelfieEnrollment.
- *
- * Allows at most one Preview screen, which must follow a Capture screen.
- */
-export class SelfieJobTypeValidator implements JobTypeValidator {
-  constructor(private readonly jobType: JobType) {}
-
-  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void {
-    appendDuplicateScreenRule(input.steps, issues);
-    appendScreenOrderRule(input.steps, issues);
-    appendPreviewRule(input.steps, 1, issues);
-    appendConsentRule(this.jobType, input, issues);
-
-    appendSelfieCaptureRule(this.jobType, input, issues);
-
-    const hasDocumentCapture = input.steps.some(
-      (s) =>
-        s.kind === "capture" && s.config.captureType === CaptureType.document,
-    );
-    if (hasDocumentCapture) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason: "must not include a Document capture screen",
-          suggestedFix: `Remove the Document capture screen — ${jobTypeName(this.jobType)} requires selfie capture only`,
-        }),
-      );
-    }
-
-    appendProcessingRule(this.jobType, input, issues);
-
-    appendSelfieMlRule(
-      this.jobType,
-      input,
-      "Add the ml { } block with forCaptureType(CaptureType.SELFIE) { } inside",
-      issues,
-    );
-    if (input.ml?.analyzers.document) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason:
-            "ml { } block must not register analyzers for CaptureType.DOCUMENT",
-          suggestedFix: `Remove forCaptureType(CaptureType.DOCUMENT) { } from the ml { } block — ${jobTypeName(this.jobType)} does not use document capture`,
-        }),
-      );
-    }
-
-    if (
-      this.jobType === JobType.biometricKyc &&
-      input.biometricKYCParams === undefined
-    ) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason: "biometricKYCParams is required for BiometricKyc jobs",
-          suggestedFix:
-            "Set builder.biometricKYCParams with the identity fields before building",
-        }),
-      );
-    }
-
-    if (input.userDetails === undefined) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason: `userDetails is required for ${jobTypeName(this.jobType)} jobs`,
-          suggestedFix:
-            "Set builder.userDetails with the end user PII before building",
-        }),
-      );
-    }
-  }
-}
-
-/**
- * Validates document flows: DocumentVerification,
- * EnhancedDocumentVerification.
- *
- * Allows up to two Preview screens (a selfie-step preview and a
- * document-step preview); each must follow a Capture screen. The
- * document analyzer is optional — the native pipeline falls back to a
- * noop document detector — but a selfie analyzer is required for the
- * biometric match against the document portrait.
- */
-export class DocumentJobTypeValidator implements JobTypeValidator {
-  constructor(private readonly jobType: JobType) {}
-
-  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void {
-    appendDuplicateScreenRule(input.steps, issues);
-    appendScreenOrderRule(input.steps, issues);
-    appendPreviewRule(input.steps, 2, issues);
-    appendConsentRule(this.jobType, input, issues);
-
-    appendSelfieCaptureRule(this.jobType, input, issues);
-
-    const documentCaptures = input.steps.filter(
-      (s) =>
-        s.kind === "capture" && s.config.captureType === CaptureType.document,
-    );
-    if (documentCaptures.length === 0) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason:
-            "must include exactly one Capture screen with captureType = DOCUMENT",
-          suggestedFix:
-            "Add a capture { captureType = CaptureType.DOCUMENT } screen to your flow",
-        }),
-      );
-    } else if (documentCaptures.length > 1) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason: `must include exactly one Capture screen with captureType = DOCUMENT, but found ${documentCaptures.length}`,
-          suggestedFix:
-            "Remove the extra document capture screens — only one is allowed",
-        }),
-      );
-    }
-
-    appendProcessingRule(this.jobType, input, issues);
-
-    // CaptureType.DOCUMENT uses a noop document detector by default — no
-    // explicit registration required.
-    appendSelfieMlRule(
-      this.jobType,
-      input,
-      "Add the ml { } block with forCaptureType(CaptureType.SELFIE) { } inside — document capture uses NoopDocumentDetectorAnalyzer by default",
-      issues,
-    );
-
-    this.appendParamsRule(input, issues);
-
-    // The South Africa Green Book carries no usable data on its back and is not
-    // supported by the Enhanced Document Verification ID-authority cross check.
-    // Reject it for that job type so the partner sees a build-time error instead
-    // of a server-side job failure.
-    if (
-      this.jobType === JobType.enhancedDocumentVerification &&
-      documentCaptures.some(
-        (s) =>
-          s.kind === "capture" &&
-          s.config.documentConfig?.documentType?.kind ===
-            "southAfricaGreenBook",
-      )
-    ) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason:
-            "South Africa Green Book is not supported for Enhanced Document Verification",
-          suggestedFix:
-            "Use JobType.documentVerification for the Green Book, or choose a supported document type for Enhanced Document Verification",
-        }),
-      );
-    }
-
-    if (input.userDetails === undefined) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason: `userDetails is required for ${jobTypeName(this.jobType)} jobs`,
-          suggestedFix:
-            "Set builder.userDetails with the end user PII before building",
-        }),
-      );
-    }
-  }
-
-  /**
-   * Require the params object for each document job. Per-field blank
-   * checks live in the standalone validators in `flow_validator.ts`.
-   */
-  private appendParamsRule(
-    input: JobTypeValidatorInput,
-    issues: ValidationIssue[],
-  ): void {
-    if (
-      this.jobType === JobType.documentVerification &&
-      input.documentVerificationParams === undefined
-    ) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason:
-            "documentVerificationParams is required for DocumentVerification jobs",
-          suggestedFix:
-            "Set builder.documentVerificationParams with the country (and optional idType) before building",
-        }),
-      );
-    }
-    if (
-      this.jobType === JobType.enhancedDocumentVerification &&
-      input.enhancedDocumentVerificationParams === undefined
-    ) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason:
-            "enhancedDocumentVerificationParams is required for EnhancedDocumentVerification jobs",
-          suggestedFix:
-            "Set builder.enhancedDocumentVerificationParams with the country and idType before building",
-        }),
-      );
-    }
-  }
-}
-
-/**
- * Validates non-capture flows: EnhancedKyc, BVN.
- *
- * No capture happens, so no Preview screen is permitted. The flow must
- * consist of consent (in-flow or pre-supplied) followed by processing.
- * Enhanced KYC additionally requires `enhancedKYCParams` and
- * `userDetails`.
- */
-export class NonCaptureJobTypeValidator implements JobTypeValidator {
-  constructor(private readonly jobType: JobType) {}
-
-  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void {
-    appendDuplicateScreenRule(input.steps, issues);
-    appendScreenOrderRule(input.steps, issues);
-    appendPreviewRule(input.steps, 0, issues);
-    appendConsentRule(this.jobType, input, issues);
-
-    appendProcessingRule(this.jobType, input, issues);
-
-    const disallowedScreens = input.steps.filter(
-      (s) => s.kind !== "consent" && s.kind !== "processing",
-    );
-    if (disallowedScreens.length > 0) {
-      const types = [...new Set(disallowedScreens.map((s) => s.kind))].join(
-        ", ",
-      );
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason: `must only contain consent and processing screens, but found: ${types}`,
-          suggestedFix:
-            "Remove all screens except consent { } and processing { } from your flow",
-        }),
-      );
-    }
-
-    if (
-      this.jobType === JobType.enhancedKyc &&
-      input.enhancedKYCParams === undefined
-    ) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason: "enhancedKYCParams is required for EnhancedKyc jobs",
-          suggestedFix:
-            "Set builder.enhancedKYCParams with the identity fields before building",
-        }),
-      );
-    }
-
-    if (
-      this.jobType === JobType.enhancedKyc &&
-      input.userDetails === undefined
-    ) {
-      issues.push(
-        InvalidJobTypeScreenConfigException.forJob({
-          jobType: this.jobType,
-          reason: "userDetails is required for EnhancedKyc jobs",
-          suggestedFix:
-            "Set builder.userDetails with the end user PII before building",
-        }),
-      );
-    }
-  }
-}
-
-/**
- * Generic structural validator used when no concrete `JobType` is
- * resolved yet (e.g. a UI-only flow without a `network { }` block). It
- * applies only the job-agnostic structural rules so partners still get
- * screen-order / duplicate / preview feedback while prototyping. A
- * single Preview following a Capture is permitted by default.
- */
-export class DefaultStructuralValidator implements JobTypeValidator {
-  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void {
-    appendDuplicateScreenRule(input.steps, issues);
-    appendScreenOrderRule(input.steps, issues);
-    appendPreviewRule(input.steps, 1, issues);
-  }
-}
-
-/**
- * Registry mapping each `JobType` to its validator instance. Adding a new job
- * type is a one-line registry change here; the validator runs the union of
- * the per-type rules (consent + selfie / document / etc.) declared above.
- */
-export const jobTypeValidators: ReadonlyMap<JobType, JobTypeValidator> =
-  new Map<JobType, JobTypeValidator>([
-    [JobType.biometricKyc, new SelfieJobTypeValidator(JobType.biometricKyc)],
-    [
-      JobType.smartSelfieAuthentication,
-      new SelfieJobTypeValidator(JobType.smartSelfieAuthentication),
-    ],
-    [
-      JobType.smartSelfieEnrollment,
-      new SelfieJobTypeValidator(JobType.smartSelfieEnrollment),
-    ],
-    [
-      JobType.documentVerification,
-      new DocumentJobTypeValidator(JobType.documentVerification),
-    ],
-    [
-      JobType.enhancedDocumentVerification,
-      new DocumentJobTypeValidator(JobType.enhancedDocumentVerification),
-    ],
-    [JobType.enhancedKyc, new NonCaptureJobTypeValidator(JobType.enhancedKyc)],
-    [JobType.bvn, new NonCaptureJobTypeValidator(JobType.bvn)],
-  ]);
-
-const defaultStructuralValidator = new DefaultStructuralValidator();
-
-/**
- * Resolve the validator for the configured job type, falling back to the
- * generic structural validator when the job type is unknown or
- * unregistered. Always returns a validator so the generic structural
- * rules run regardless of dispatch.
- */
-export function resolveJobTypeValidator(
-  jobType: JobType | undefined,
-): JobTypeValidator {
-  if (jobType === undefined || jobType === JobType.unknown) {
-    return defaultStructuralValidator;
-  }
-  return jobTypeValidators.get(jobType) ?? defaultStructuralValidator;
-}
-
-/**
- * Run the job-type-specific rules against the flow and append any issues
- * found. Called by `FlowValidator` after its generic builder pass. The
- * matching validator is resolved from the configured `jobType`, with the
- * generic structural validator as the fallback for unknown job types.
- */
-export function collectJobTypeIssues(
-  input: JobTypeValidatorInput,
-  issues: ValidationIssue[],
-): void {
-  const jobType = input.network?.config?.jobType;
-  resolveJobTypeValidator(jobType).validate(input, issues);
-}