@smileid/usesmileid 12.0.0-beta01

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

@@ -0,0 +1,433 @@
+import type { MLConfig } from "../../../core/models/ml_config";
+import { CaptureType } 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";
+
+type ConsentScreenStep = Extract<ScreenSpec, { kind: "consent" }>;
+import { IssueSeverity } from "../../../core/exception/issue_severity";
+import {
+  InvalidConsentConfigException,
+  InvalidConsentInformationException,
+} from "../../../core/exception/consent_validation_exceptions";
+import {
+  InvalidFieldValueException,
+  MissingJobTypeException,
+  MissingMLConfigurationBlockException,
+  MissingNetworkConfigurationBlockException,
+} from "../../../core/exception/job_validation_exceptions";
+import {
+  InvalidDocumentCaptureConfigException,
+  InvalidMissingCaptureTypeException,
+} from "../../../core/exception/capture_validation_exceptions";
+import { EmptyScreensBlockException } from "../../../core/exception/screen_config_validation_exceptions";
+import { ValidationState, type ValidationIssue } from "./validation_state";
+import { collectJobTypeIssues } from "./job_type_validator";
+
+/**
+ * Pure flow validator — returns typed `UseSmileIDValidationException`
+ * instances. The same instances are exposed via `b.validate()` and
+ * thrown by `b.build()` (after picking the first `error`-severity
+ * issue), so partner regex-matchers and `instanceof` checks see the
+ * same object whether they're inspecting validate-state or catching
+ * a thrown error.
+ *
+ * `runFlowValidation` owns only the builder / job-agnostic concerns:
+ * empty screens, per-screen capture / consent config, ML / Network
+ * block presence, missing job type, the standalone param validators,
+ * and the consent-mutex check. Every flow-composition rule — screen
+ * ordering, duplicate screen types, preview placement, analyzer
+ * dependencies, and per-job field requirements — is owned by the
+ * per-`JobType` validators in `job_type_validator.ts`, dispatched via
+ * `collectJobTypeIssues`.
+ *
+ * Rule order, message wording, severity, and `errorCode` values are
+ * the contract surface partners see. Don't reword existing rules
+ * without a coordinated change — partner tooling regex-matches on
+ * the message text and pivots on the `errorCode`.
+ */
+
+type FlowValidatorInput = {
+  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;
+};
+
+/**
+ * Quick triage of the in-progress builder state. Today the only rule
+ * surfaced is the empty-screens-block error — `b.screens(...)` must
+ * register at least one screen before the builder can produce a flow.
+ * `b.validate()` calls this; the full rule set runs inside `build()`.
+ */
+export function runBuilderValidation(
+  steps: readonly ScreenSpec[],
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  if (steps.length === 0) {
+    issues.push(new EmptyScreensBlockException());
+  }
+  return issues;
+}
+
+/**
+ * Run every flow-level validation rule and return the collected
+ * issues. Empty array means valid.
+ *
+ * Rule order is deterministic so callers diffing two outputs see
+ * stable output. `build()` returns `{kind: 'invalid'}` carrying these
+ * issues when any are `error`-severity.
+ */
+export function runFlowValidation(
+  input: FlowValidatorInput,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (input.steps.length === 0) {
+    issues.push(new EmptyScreensBlockException());
+    // Without screens, every other rule is vacuous — short-circuit
+    // to avoid producing follow-on noise.
+    return issues;
+  }
+
+  // Capture screens must declare a captureType. Partners set this inside
+  // the configure block; if they forget, surface the typed exception so
+  // it routes through `onResult.failure` like every other validation issue.
+  for (const step of input.steps) {
+    if (step.kind === "capture") {
+      if (step.config.captureType === undefined) {
+        issues.push(new InvalidMissingCaptureTypeException());
+      }
+      // Document captures carry required config: surface at most one issue per
+      // step (missing block > missing type > bad aspect ratio).
+      if (step.config.captureType === CaptureType.document) {
+        const documentConfig = step.config.documentConfig;
+        if (documentConfig === undefined) {
+          issues.push(
+            new InvalidDocumentCaptureConfigException({
+              reason: "document is required when mode is Document",
+            }),
+          );
+        } else if (documentConfig.documentType === undefined) {
+          issues.push(
+            new InvalidDocumentCaptureConfigException({
+              reason: "documentType is required for document capture",
+            }),
+          );
+        } else if (
+          documentConfig.knownIdAspectRatio !== undefined &&
+          documentConfig.knownIdAspectRatio <= 0
+        ) {
+          issues.push(
+            new InvalidDocumentCaptureConfigException({
+              reason: "knownIdAspectRatio must be > 0 if provided",
+            }),
+          );
+        }
+      }
+    }
+  }
+
+  const hasCaptureScreen = input.steps.some((s) => s.kind === "capture");
+  const hasProcessingScreen = input.steps.some((s) => s.kind === "processing");
+
+  if (hasCaptureScreen && !input.ml) {
+    issues.push(new MissingMLConfigurationBlockException());
+  }
+  if (hasProcessingScreen && !input.network) {
+    issues.push(new MissingNetworkConfigurationBlockException());
+  }
+  // A processing screen always requires a resolved jobType. Fail the
+  // build (ERROR) whenever it's missing — whether or not a network
+  // block was provided. The missing-network WARNING above still fires
+  // alongside this when the block is absent.
+  if (hasProcessingScreen) {
+    const jobType = input.network?.config?.jobType;
+    if (jobType === undefined || jobType === JobType.unknown) {
+      issues.push(new MissingJobTypeException());
+    }
+  }
+
+  // Consent screen config validation — partnerName must be non-empty
+  // when a consent screen is in the flow. The consent screen's
+  // attribution line renders blank without it, which partners
+  // typically don't notice until QA.
+  const consentStep = input.steps.find(
+    (s): s is ConsentScreenStep => s.kind === "consent",
+  );
+  if (
+    consentStep &&
+    (!consentStep.config.partnerName || !consentStep.config.partnerName.trim())
+  ) {
+    issues.push(
+      new InvalidConsentConfigException({
+        reason: "partnerName cannot be empty",
+      }),
+    );
+  }
+  if (consentStep && consentStep.config.partnerIcon === undefined) {
+    issues.push(
+      new InvalidConsentConfigException({
+        reason: "partnerIcon is required for the consent screen",
+      }),
+    );
+  }
+  if (
+    consentStep &&
+    (consentStep.config.partnerPrivacyPolicyUrl === undefined ||
+      !consentStep.config.partnerPrivacyPolicyUrl.trim())
+  ) {
+    issues.push(
+      new InvalidConsentConfigException({
+        reason: "partnerPrivacyPolicyUrl is required for the consent screen",
+      }),
+    );
+  }
+
+  const hasConsentScreen = consentStep !== undefined;
+  if (hasConsentScreen && input.consentInformation !== undefined) {
+    issues.push(
+      new InvalidConsentConfigException({
+        reason:
+          "Exactly one form of consent is required — remove the consent { } screen if using consentInformation, or clear consentInformation if using the consent screen",
+      }),
+    );
+  }
+
+  if (input.consentInformation) {
+    issues.push(...runConsentValidation(input.consentInformation));
+  }
+  if (input.enhancedKYCParams) {
+    issues.push(...runEnhancedKYCParamsValidation(input.enhancedKYCParams));
+  }
+  if (input.biometricKYCParams) {
+    issues.push(...runBiometricKYCParamsValidation(input.biometricKYCParams));
+  }
+  if (input.documentVerificationParams) {
+    issues.push(
+      ...runDocumentVerificationParamsValidation(
+        input.documentVerificationParams,
+      ),
+    );
+  }
+  if (input.enhancedDocumentVerificationParams) {
+    issues.push(
+      ...runEnhancedDocumentVerificationParamsValidation(
+        input.enhancedDocumentVerificationParams,
+      ),
+    );
+  }
+  if (input.userDetails) {
+    issues.push(...runUserDetailsValidation(input.userDetails));
+  }
+
+  // Every flow-composition rule (screen ordering, duplicate screens,
+  // preview placement, analyzer dependencies, per-job field
+  // requirements) lives in job_type_validator.ts. FlowValidator owns
+  // only the builder / job-agnostic concerns above and delegates the
+  // per-jobType pass here. The dispatch resolves a validator from the
+  // configured jobType, falling back to a generic structural validator
+  // when the jobType is unknown so prototyping flows still get
+  // ordering / duplicate / preview feedback.
+  collectJobTypeIssues(input, issues);
+
+  return issues;
+}
+
+/**
+ * Validate an `EnhancedKYCParams` payload in isolation. Used by
+ * `b.validateEnhancedKYCParams(params)` so partners can pre-flight a
+ * payload before assigning it to the builder.
+ */
+export function runEnhancedKYCParamsValidation(
+  params: EnhancedKYCParams,
+): ValidationIssue[] {
+  return runKYCParamsValidation(params);
+}
+
+/**
+ * Validate a `BiometricKYCParams` payload in isolation. Used by
+ * `b.validateBiometricKYCParams(params)`.
+ */
+export function runBiometricKYCParamsValidation(
+  params: BiometricKYCParams,
+): ValidationIssue[] {
+  return runKYCParamsValidation(params);
+}
+
+/**
+ * Validate a `DocumentVerificationParams` payload in isolation. `country`
+ * must be non-blank; `idType` is optional, but a present-but-blank value
+ * is rejected.
+ */
+export function runDocumentVerificationParamsValidation(
+  params: DocumentVerificationParams,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  if (!params.country || !params.country.trim()) {
+    issues.push(
+      new InvalidFieldValueException({
+        fieldName: "country",
+        reason: "must not be blank",
+      }),
+    );
+  }
+  if (params.idType !== undefined && !params.idType.trim()) {
+    issues.push(
+      new InvalidFieldValueException({
+        fieldName: "idType",
+        reason: "must not be blank",
+      }),
+    );
+  }
+  return issues;
+}
+
+/**
+ * Validate an `EnhancedDocumentVerificationParams` payload in isolation.
+ * Both `country` and `idType` are required and must be non-blank.
+ */
+export function runEnhancedDocumentVerificationParamsValidation(
+  params: EnhancedDocumentVerificationParams,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  for (const field of ["country", "idType"] as const) {
+    const value = params[field];
+    if (!value || !value.trim()) {
+      issues.push(
+        new InvalidFieldValueException({
+          fieldName: field,
+          reason: "must not be blank",
+        }),
+      );
+    }
+  }
+  return issues;
+}
+
+/**
+ * Validate a `ConsentInformation` payload in isolation. Used by
+ * `b.validateConsent(consent)` so partners can pre-flight a payload
+ * pulled from their own storage before assigning it to the builder.
+ */
+export function runConsentValidation(
+  consent: ConsentInformation,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  if (!consent.granted) {
+    issues.push(
+      new InvalidConsentInformationException({
+        detail: "granted must be true",
+      }),
+    );
+  }
+  for (const field of [
+    "grantedAt",
+    "noticeLanguage",
+    "noticePrivacyPolicyUrl",
+  ] as const) {
+    if (!consent[field] || !consent[field].trim()) {
+      issues.push(
+        new InvalidConsentInformationException({
+          detail: `${field} must not be blank`,
+        }),
+      );
+    }
+  }
+  return issues;
+}
+
+function runKYCParamsValidation(
+  params: EnhancedKYCParams | BiometricKYCParams,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // Top-level required fields on the params object.
+  for (const field of ["idType", "idNumber", "country"] as const) {
+    const value = params[field];
+    if (!value || !value.trim()) {
+      issues.push(
+        new InvalidFieldValueException({
+          fieldName: field,
+          reason: "must not be blank",
+        }),
+      );
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Validate a top-level `UserDetails` payload. Required fields use the
+ * dotted path (`userDetails.givenNames`) so partner regex-matchers
+ * keep working unchanged after the consolidation away from nesting
+ * `userDetails` inside the KYC param shapes.
+ *
+ * Exposed via `b.validateUserDetails(payload)` so partners can
+ * pre-flight a payload before assigning to `b.userDetails`, mirroring
+ * the existing `b.validateConsent` / `b.validateEnhancedKYCParams`
+ * pattern.
+ */
+export function runUserDetailsValidation(
+  userDetails: UserDetails,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  for (const field of ["givenNames", "lastName"] as const) {
+    const value = userDetails[field];
+    if (!value || !value.trim()) {
+      issues.push(
+        new InvalidFieldValueException({
+          fieldName: `userDetails.${field}`,
+          reason: "must not be blank",
+        }),
+      );
+    }
+  }
+  // At-least-one-of contact rule: email and phoneNumber are each
+  // optional, but the partner must supply one of them.
+  const hasEmail = !!userDetails.email && userDetails.email.trim().length > 0;
+  const hasPhone =
+    !!userDetails.phoneNumber && userDetails.phoneNumber.trim().length > 0;
+  if (!hasEmail && !hasPhone) {
+    issues.push(
+      new InvalidFieldValueException({
+        fieldName: "userDetails",
+        reason: "at least one of email or phoneNumber must be non blank",
+      }),
+    );
+  }
+  return issues;
+}
+
+/**
+ * Find the first `error`-severity issue in a state. Returns
+ * `undefined` for a valid state, or for a state whose only issues
+ * are `warning`-severity (which never block `build()`).
+ *
+ * `build()` calls this to convert validator output into a thrown
+ * `Error` (the issue itself, since every issue is also an exception
+ * class). Partner regex on the message keeps working across the
+ * refactor.
+ */
+export function firstErrorIssue(
+  state: ValidationState,
+): ValidationIssue | undefined {
+  if (state.valid) return undefined;
+  return state.issues.find((i) => i.severity === IssueSeverity.error);
+}