# CURP Validation Module

<WebSDK2 />

The CURP Validation module verifies a Mexican CURP (Clave Única de Registro de Población) — either by accepting the user's CURP and validating it server-side, or by generating one from the user's identity data when missing.

> Follows the [form-based pattern](doc:web-sdk-2-module-patterns#1-form-based-modules) with three input variants (enter, confirm, generate). See the patterns page for the shared lifecycle.

## Tag

`<incode-curp-validation>` is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

```ts
import '@incodetech/web/curp-validation';
import '@incodetech/web/curp-validation/styles.css';
```

## Properties

| Property   | Type                      | Required | Description                      |
| ---------- | ------------------------- | -------- | -------------------------------- |
| `config`   | `CurpValidationConfig`    | ❌        | Configuration options            |
| `onFinish` | `() => void`              | ❌        | Called when validation completes |
| `onError`  | `(error: string) => void` | ❌        | Called when an error occurs      |

## Configuration

`CurpValidationConfig` extends `FlowModuleConfig['CURP_VALIDATION']` with two manager-level options:

```typescript
type CurpValidationConfig = FlowModuleConfig['CURP_VALIDATION'] & {
  maxRetries?: number; // Maximum validation retries before auto-advancing (default: 1)
  prefillFromOcr?: boolean; // Attempt OCR pre-fill on load (default: true)
};
```

| Option           | Type      | Required | Description                                                                    |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `maxRetries`     | `number`  | ❌        | Auto-advance after this many failed validation attempts. Default `1`.          |
| `prefillFromOcr` | `boolean` | ❌        | Pre-fill the CURP field from prior ID OCR data when available. Default `true`. |

Plus the dashboard-driven fields from `FlowModuleConfig['CURP_VALIDATION']`.

## State machine

`CurpValidationState` is a discriminated union over `status`:

| Status          | Description                                                                       |
| --------------- | --------------------------------------------------------------------------------- |
| `idle`          | Initial state.                                                                    |
| `loading`       | Loading prior OCR data (when `prefillFromOcr` is `true`).                         |
| `enterCurp`     | User enters their CURP.                                                           |
| `verifying`     | Backend verifying the entered CURP.                                               |
| `confirmCurp`   | Backend returned an OCR'd CURP candidate; user confirms or rejects.               |
| `generateCurp`  | No CURP available; user fills the generate form (name, DOB, gender, birth state). |
| `generating`    | Backend generating a CURP from the form.                                          |
| `generateError` | Generate failed; user can retry.                                                  |
| `success`       | CURP validated.                                                                   |
| `failure`       | Validation failed (deceased status, mismatch, etc.).                              |
| `finished`      | Terminal.                                                                         |
| `closed`        | User dismissed.                                                                   |

## See also

* [Module Patterns → form-based](doc:web-sdk-2-module-patterns#1-form-based-modules)
* [Module: ID OCR](doc:web-sdk-2-module-id-ocr): provides the OCR data this module pre-fills from
* [Individual Modules](doc:web-sdk-2-individual-modules)