indycheck 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# indycheck
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offline Indian ID validator — mobile, PAN, Aadhaar, GSTIN, IFSC, UPI, PIN code, TAN, CIN, LLPIN, Voter ID / EPIC and vehicle registration. Format + checksum only, no network, no government database.
+
+```bash
+npm install indycheck
+```
+
+```ts
+import { validatePan, validateMobile, validateTan, generatePan } from "indycheck";
+
+validatePan("ABCPE1234F"); // { valid: true, code: "VALID", parsed: { entity: "Individual", entity_code: "P" } }
+validateMobile("+91 98765 43210"); // { valid: true, parsed: { normalized: "9876543210" } }
+validateTan("AAAA12345B"); // { valid: true, parsed: { tan: "AAAA12345B" } }
+generatePan("P"); // e.g. "XKQPW4821M" — mock test data only, never a real PAN
+```
+
+Every validator returns `{ valid, code, reason_en, reason_hi, parsed }` and
+never throws on bad input. `reason_hi` is Roman-script Hinglish, exactly
+as the Rust core returns it.
+
+## Validators (12)
+
+| Function | Checks | `parsed` on success |
+|---|---|---|
+| `validateMobile` | 10 digits, first digit 6–9; `+91` / `91` / `0` prefix, spaces and hyphens allowed | `{ normalized }` |
+| `validatePan` | `^[A-Z]{5}[0-9]{4}[A-Z]$` | `{ entity, entity_code }` |
+| `validateAadhaar` | 12 digits, first digit 2–9, Verhoeff checksum | `{ masked }` |
+| `validateGstin` | 15 chars: state code + PAN + entity char + `Z` + Mod-36 check digit | `{ state, state_code, pan }` |
+| `validateIfsc` | `^[A-Z]{4}0[A-Z0-9]{6}$` — format only, no checksum | `{ bank_code, branch_code }` |
+| `validateUpi` | `name@handle`, handle from a built-in list | `{ handle }` |
+| `validatePincode` | 6 digits, first digit 1–9 | `{ pincode }` |
+| `validateTan` | 4 letters + 5 digits + 1 letter — format only, no checksum | `{ tan }` |
+| `validateCin` | 21 chars: `L`/`U` + 5 digits + 2 letters + 4 digits + 3 letters + 6 digits — format only, no checksum | `{ cin, listing, industry_code, state_code, year, company_type, registration_number }` |
+| `validateLlpin` | 3 letters + 4 digits — format only, no checksum | `{ llpin }` |
+| `validateVoterId` / `validateEpic` | 3 letters + 7 digits — format only, no checksum | `{ epic }` |
+| `validateVehicle` / `validateVehicleRegistration` | e.g. `DL01AB1234`, `DL01A1234` — format only, no checksum | `{ registration, state_code, district, series, number }` |
+
+Also available: `detect` (the Rust detect string in `parsed.type`) and
+`validateMany`, and optional Zod schemas (`indycheck/zod`: `panSchema`,
+`aadhaarSchema`, `tanSchema`, `cinSchema`, `llpinSchema`, `voterSchema` /
+`epicSchema`, `vehicleSchema`, …).
+
+## Options
+
+`validateMobileWithOptions`, `validatePanWithOptions`,
+`validateAadhaarWithOptions` and `validateGstinWithOptions` take an
+optional partial `Options` object (`{ strict, allow_spaces_hyphens,
+normalise_plus91, uppercase }`, all defaulting to `true`):
+
+```ts
+import { validateMobileWithOptions, lenientOptions } from "indycheck";
+
+validateMobileWithOptions("5876543210", lenientOptions()); // valid: first-digit rule skipped
+validateMobileWithOptions("+91 98765 43210", { normalise_plus91: false }); // INVALID_FORMAT
+validatePanWithOptions("abcde1234f", { uppercase: false }); // INVALID_FORMAT
+```
+
+Helpers: `defaultOptions()`, `lenientOptions()` (format only — skips
+first-digit and checksum checks) and `noSpacesHyphensOptions()`. The
+other validators have no options variants, in the Rust core either.
+
+## Format / mask
+
+```ts
+import { formatPan, formatGstin, maskPan, maskMobile } from "indycheck";
+
+formatPan("abcde 1234f"); // "ABCDE1234F" (null when the pattern does not match)
+formatGstin("18aaapl1234c1zd"); // "18AAAPL1234C1ZD" — check digit NOT verified here
+maskPan("ABCDE1234F"); // "ABCDE****F"
+maskMobile("+91 98765 43210"); // "******3210"
+```
+
+`formatMobile` and `maskAadhaar` keep their older behaviour and return
+a `ValidationResult` (same as `validateMobile` / `validateAadhaar`).
+A non-empty mask result is **not** proof of validity — use the matching
+`validate*` for that.
+
+## Generators — TEST DATA ONLY
+
+```ts
+import { generatePan, generateAadhaar, generateGstin, generateMobile } from "indycheck";
+
+generatePan("C"); // syntactically valid PAN, entity Company (unknown char -> "P")
+generateAadhaar(); // 12 digits, correct Verhoeff check digit
+generateGstin("18"); // syntactically valid GSTIN for Assam (unknown code -> "18")
+generateMobile(); // 10 digits, first digit 6-9
+```
+
+**Warning: generated values are syntactically valid, not real issued
+IDs.** They pass this library's own validators but were never issued
+by UIDAI, Income Tax, GSTN or anyone else. Use them only in tests,
+demos and form previews — never present them as a real person's ID.
+Generators are intentionally unseeded: each call may return a
+different value.
+
+Note: PAN entity reporting is lenient — the 4th character is reported in
+`parsed.entity`, or `"Unknown"` when it is not in the published entity
+list (P, C, H, F, A, T, B, L, J, G), and the PAN is still format-valid.
+So `ABCDE1234F` is valid with entity `"Unknown"`, not an error.
+
+## Honest limits
+
+- **Format + checksum only.** A `valid: true` result means the value is
+  well-formed and its checksum is correct — not that the ID exists or
+  belongs to anyone.
+- No checks against UIDAI (Aadhaar), NSDL / Income Tax (PAN), GSTN
+  (GSTIN), any bank (IFSC), or any UPI provider. This package makes no
+  network requests at all.
+- **PAN, IFSC, TAN, CIN, LLPIN, Voter ID and vehicle registration
+  numbers have no public checksum.** Only their format is checked.
+  The vehicle state-code letters are not checked against a list of
+  states, and a format-valid vehicle number does not prove the vehicle
+  exists.
+- IFSC validation is format-only: it cannot tell you whether a branch
+  code really exists.
+- UPI validation checks the handle against a built-in list of common
+  handles; a new or rare handle may be reported as unknown.

package/dist/index.d.ts

@@ -0,0 +1,302 @@
+/**
+ * indycheck — offline Indian ID validator (pure-TypeScript mirror).
+ *
+ * This file mirrors the Rust core in crates/indycheck/src/ exactly:
+ * same validators, same order of checks, same stable `code` values, same
+ * `reason_en` / `reason_hi` strings, same `parsed` shapes (see
+ * shared/spec.md). Behaviour is defined by shared/test-vectors.json
+ * together with the Rust code; as of the last check the two agree on all
+ * 245 vectors (verified by emulating the Rust source over the file), so
+ * the vector test below asserts every entry directly with no exceptions.
+ * If the Rust side drifts again, that test fails loudly instead of
+ * silently picking a side.
+ *
+ * The 12 validators are: mobile, PAN, Aadhaar, GSTIN, IFSC, UPI, PIN
+ * code, TAN, CIN, LLPIN, Voter ID / EPIC and vehicle registration.
+ * TAN, CIN, LLPIN, Voter ID, vehicle and IFSC have no public checksum:
+ * only their format is checked (say so wherever these are documented).
+ * `validate*WithOptions` exists only where the Rust core has it — mobile,
+ * PAN, Aadhaar and GSTIN (options.rs); the other validators take no
+ * options in Rust either. `formatPan` / `formatGstin` return
+ * `string | null` and `maskPan` / `maskMobile` return a plain string
+ * ("" when the format is invalid), exactly like the Rust functions —
+ * unlike the legacy `formatMobile` / `maskAadhaar` wrappers, which keep
+ * returning a `ValidationResult` for backwards compatibility.
+ * The `generate*` functions produce mock test data only: syntactically
+ * valid, never a real issued ID — see generate.rs and the README.
+ *
+ * Notes on the Rust contract reproduced here:
+ * - Success code is `VALID` (not `OK`). The full code set is:
+ *   VALID, EMPTY, INVALID_LENGTH, INVALID_FORMAT, INVALID_CHECKSUM,
+ *   INVALID_FIRST_DIGIT, INVALID_STATE_CODE, INVALID_ENTITY,
+ *   INVALID_HANDLE, UNKNOWN_TYPE. `INVALID_TYPE` (non-string input) and
+ *   `SOME_INVALID` (validateMany batch result) exist only in the JS/Python
+ *   wrappers — Rust takes `&str` and returns a bare `Vec` for batches.
+ * - `reason_hi` is Roman-script Hinglish in the Rust core (e.g.
+ *   "PAN khaali hai"), not Devanagari — reproduced verbatim, even though
+ *   spec.md calls it Devanagari Hindi.
+ * - PAN entity checking is lenient by design (pan.rs, spec.md): the 4th
+ *   character is reported in `parsed` (entity name, or "Unknown" when it
+ *   is not in the published list) and the PAN is still format-valid.
+ *   The canonical example ABCDE1234F is valid with entity "Unknown"
+ *   (4th char D). `INVALID_ENTITY` is a reserved stable code, not
+ *   emitted in v0.1.
+ * - `detect` returns the Rust detect string ("pan" | "aadhaar" | "gstin" |
+ *   "ifsc" | "upi" | "mobile" | "pincode" | "tan" | "cin" | "llpin" |
+ *   "voter" | "vehicle" | "unknown") in `parsed.type`.
+ *   It is shape-based, not validity-based: detection can succeed while
+ *   validation of the same input fails. Its order is fixed by lib.rs:
+ *   `@` -> upi first; then a Verhoeff-valid 12-digit number -> aadhaar
+ *   (including spaced / hyphenated Aadhaar, digits-only); then any
+ *   normalisable mobile -> mobile; then CIN (21 chars); then by length
+ *   (15 -> gstin, 12 digits -> aadhaar, 11 IFSC-pattern -> ifsc,
+ *   10 PAN-pattern -> pan, 10 TAN-pattern -> tan, 10 voter-pattern ->
+ *   voter, 10 digits -> mobile, 7 LLPIN-pattern -> llpin, 6 digits ->
+ *   pincode); then formatted mobiles, then PAN / TAN / voter / IFSC /
+ *   LLPIN patterns, then vehicle. Note the code's order, not spec.md's
+ *   one-line summary of it.
+ * - `formatMobile` returns the validateMobile result (parsed.normalized
+ *   is the 10-digit string, Rust's `format_mobile` return). `maskAadhaar`
+ *   returns the validateAadhaar result (parsed.masked). Unlike the Rust
+ *   `mask_aadhaar` string function — which masks any 12-digit string,
+ *   even one with a bad checksum — the JS/Python maskAadhaar only
+ *   succeeds for a fully valid Aadhaar number.
+ * - UPI handle list, GSTIN state names (incl. 25/26) and PAN entity
+ *   names are copied verbatim from crates/indycheck/src/data.rs and
+ *   pan.rs (note: B -> "BODY", H -> "HUF", A -> "AOP").
+ *
+ * Honest limits: format + checksum only. Nothing here checks a number
+ * against UIDAI, NSDL / Income Tax, GSTN, a bank, or any other live
+ * database. A `valid: true` result means "well-formed and checksum-correct",
+ * not "this ID really exists / belongs to this person".
+ *
+ * Every validator returns `{ valid, code, reason_en, reason_hi, parsed }`
+ * and never throws on bad input.
+ */
+export interface ValidationResult<TParsed = unknown> {
+    valid: boolean;
+    code: string;
+    reason_en: string;
+    reason_hi: string;
+    parsed: TParsed | null;
+}
+/** Validation options — verbatim from crates/indycheck/src/options.rs.
+ *  All fields default to `true`. Only mobile, PAN, Aadhaar and GSTIN
+ *  have `validate*WithOptions` variants in the Rust core; the other
+ *  validators take no options. */
+export interface Options {
+    /** Enforce every rule, including first-digit rules and checksums.
+     *  `false` skips those (format only). */
+    strict: boolean;
+    /** Strip spaces and hyphens before validating; `false` makes any
+     *  space or hyphen an INVALID_FORMAT error. */
+    allow_spaces_hyphens: boolean;
+    /** A mobile may carry a `+91` / `91` / `0` prefix; `false` accepts
+     *  only a bare 10-digit number. */
+    normalise_plus91: boolean;
+    /** Upper-case letter input before validating; `false` makes a
+     *  lower-case letter fail the format check instead. */
+    uppercase: boolean;
+}
+/** parsed shapes follow shared/spec.md exactly. */
+export interface MobileParsed {
+    normalized: string;
+}
+export interface PanParsed {
+    entity: string;
+    entity_code: string;
+}
+export interface AadhaarParsed {
+    masked: string;
+}
+export interface GstinParsed {
+    state: string;
+    state_code: string;
+    pan: string;
+}
+export interface IfscParsed {
+    bank_code: string;
+    branch_code: string;
+}
+export interface UpiParsed {
+    handle: string;
+}
+export interface PincodeParsed {
+    pincode: string;
+}
+export interface TanParsed {
+    tan: string;
+}
+export interface CinParsed {
+    cin: string;
+    listing: string;
+    industry_code: string;
+    state_code: string;
+    year: string;
+    company_type: string;
+    registration_number: string;
+}
+export interface LlpinParsed {
+    llpin: string;
+}
+export interface VoterParsed {
+    epic: string;
+}
+export interface VehicleParsed {
+    registration: string;
+    series_type: "state" | "bharat";
+    state_code?: string;
+    district?: string;
+    series: string;
+    number: string;
+    year?: string;
+    suffix?: string;
+}
+export interface DetectParsed {
+    type: string | null;
+    value: string | null;
+    result: ValidationResult | null;
+}
+export interface ValidateManyItemResult {
+    input: unknown;
+    type: string | null;
+    valid: boolean;
+    code: string;
+    reason_en: string;
+    reason_hi: string;
+    parsed: unknown;
+}
+export interface ValidateManyParsed {
+    results: ValidateManyItemResult[];
+    total: number;
+    validCount: number;
+    invalidCount: number;
+}
+export declare const PAN_ENTITY_TYPES: Record<string, string>;
+export declare const GSTIN_STATE_NAMES: Record<string, string>;
+/** Common UPI handles, verbatim from crates/indycheck/src/data.rs. */
+export declare const UPI_HANDLES: string[];
+export declare const DEFAULT_OPTIONS: Options;
+/** Strict validation (the default): every rule enforced. */
+export declare function defaultOptions(): Options;
+/** Lenient validation: format only — first-digit and checksum checks
+ *  are skipped. */
+export declare function lenientOptions(): Options;
+/** Start from the defaults and turn off space/hyphen tolerance. */
+export declare function noSpacesHyphensOptions(): Options;
+export declare function validateMobile(input: unknown): ValidationResult<MobileParsed>;
+/** Same as `validateMobile`, with caller-controlled `Options`.
+ *  With `strict: false` the first-digit rule is skipped (format only). */
+export declare function validateMobileWithOptions(input: unknown, options?: Partial<Options>): ValidationResult<MobileParsed>;
+export declare function formatMobile(input: unknown): ValidationResult<MobileParsed>;
+export declare function formatMobileWithOptions(input: unknown, options?: Partial<Options>): ValidationResult<MobileParsed>;
+/** Masks a mobile number as `******3210` (6 asterisks + last 4 digits).
+ *  Returns an empty string when the input is not a valid-format mobile
+ *  number. A non-empty result is not proof of validity. */
+export declare function maskMobile(input: unknown): string;
+export declare function validatePan(input: unknown): ValidationResult<PanParsed>;
+/** Same as `validatePan`, with caller-controlled `Options`.
+ *  For PAN, `strict`/`lenient` make no difference (there is no checksum or
+ *  first-digit rule to skip); `uppercase` and `allow_spaces_hyphens` do. */
+export declare function validatePanWithOptions(input: unknown, options?: Partial<Options>): ValidationResult<PanParsed>;
+/** Formats a PAN: upper-cases it and strips spaces/hyphens.
+ *  Returns `"ABCDE1234F"` when the result matches the PAN pattern,
+ *  otherwise `null`. */
+export declare function formatPan(input: unknown): string | null;
+/** Masks a PAN as `ABCDE****F` (first 5 chars, 4 asterisks, last char).
+ *  Returns an empty string when the input is not a valid-format PAN.
+ *  A non-empty result is not proof of validity — use `validatePan`. */
+export declare function maskPan(input: unknown): string;
+export declare function maskAadhaarString(input: string): string;
+export declare function validateAadhaar(input: unknown): ValidationResult<AadhaarParsed>;
+/** Same as `validateAadhaar`, with caller-controlled `Options`.
+ *  With `strict: false` the first-digit and Verhoeff checksum checks are
+ *  skipped (12 digits only). With `allow_spaces_hyphens: false`, spaces
+ *  or hyphens in the input are an `INVALID_FORMAT` error. */
+export declare function validateAadhaarWithOptions(input: unknown, options?: Partial<Options>): ValidationResult<AadhaarParsed>;
+export declare function maskAadhaar(input: unknown): ValidationResult<AadhaarParsed>;
+export declare function validateGstin(input: unknown): ValidationResult<GstinParsed>;
+/** Same as `validateGstin`, with caller-controlled `Options`.
+ *  With `strict: false` the Mod-36 check-digit check is skipped (format
+ *  and state code still checked). With `allow_spaces_hyphens: false`,
+ *  spaces or hyphens in the input are an `INVALID_FORMAT` error. */
+export declare function validateGstinWithOptions(input: unknown, options?: Partial<Options>): ValidationResult<GstinParsed>;
+/** Formats a GSTIN: upper-cases it and strips spaces/hyphens.
+ *  Returns the formatted GSTIN when its structure is in place (state
+ *  code, PAN part and `Z`); the check digit is NOT verified here —
+ *  so a `formatGstin` result can still fail `validateGstin`.
+ *  Returns `null` otherwise. */
+export declare function formatGstin(input: unknown): string | null;
+export declare function validateIfsc(input: unknown): ValidationResult<IfscParsed>;
+export declare function validateUpi(input: unknown): ValidationResult<UpiParsed>;
+export declare function validatePincode(input: unknown): ValidationResult<PincodeParsed>;
+export declare function validateTan(input: unknown): ValidationResult<TanParsed>;
+export declare function validateCin(input: unknown): ValidationResult<CinParsed>;
+export declare function validateLlpin(input: unknown): ValidationResult<LlpinParsed>;
+export declare function validateVoterId(input: unknown): ValidationResult<VoterParsed>;
+/** Alias for `validateVoterId`: EPIC is the name printed on the card. */
+export declare function validateEpic(input: unknown): ValidationResult<VoterParsed>;
+export declare function validateVehicle(input: unknown): ValidationResult<VehicleParsed>;
+/** Alias for `validateVehicle`. */
+export declare function validateVehicleRegistration(input: unknown): ValidationResult<VehicleParsed>;
+/** Generates a syntactically valid PAN for the given entity character
+ *  (`P`, `C`, `H`, `F`, `A`, `T`, `B`, `L`, `J` or `G`).
+ *  An unknown entity character falls back to `P` (Individual).
+ *  TEST DATA ONLY — not a real issued PAN. */
+export declare function generatePan(entity?: unknown): string;
+/** Generates a syntactically valid 12-digit Aadhaar number (first digit
+ *  2-9, correct Verhoeff check digit).
+ *  TEST DATA ONLY — not a real issued Aadhaar number. */
+export declare function generateAadhaar(): string;
+/** Generates a syntactically valid GSTIN for the given 2-digit state code
+ *  (e.g. `"18"` for Assam). An unknown state code falls back to `"18"`.
+ *  TEST DATA ONLY — not a real issued GSTIN. */
+export declare function generateGstin(stateCode?: unknown): string;
+/** Generates a syntactically valid Indian mobile number (10 digits,
+ *  first digit 6-9). TEST DATA ONLY — not a real person's number. */
+export declare function generateMobile(): string;
+/** The Rust `detect` string for a trimmed input (lib.rs order). */
+export declare function detectType(input: string): string;
+export declare function detect(input: unknown): ValidationResult<DetectParsed>;
+export declare function validateMany(inputs: unknown): ValidationResult<ValidateManyParsed>;
+declare const _default: {
+    validateMobile: typeof validateMobile;
+    validatePan: typeof validatePan;
+    validateAadhaar: typeof validateAadhaar;
+    validateGstin: typeof validateGstin;
+    validateIfsc: typeof validateIfsc;
+    validateUpi: typeof validateUpi;
+    validatePincode: typeof validatePincode;
+    validateTan: typeof validateTan;
+    validateCin: typeof validateCin;
+    validateLlpin: typeof validateLlpin;
+    validateVoterId: typeof validateVoterId;
+    validateEpic: typeof validateEpic;
+    validateVehicle: typeof validateVehicle;
+    validateVehicleRegistration: typeof validateVehicleRegistration;
+    validateMobileWithOptions: typeof validateMobileWithOptions;
+    validatePanWithOptions: typeof validatePanWithOptions;
+    validateAadhaarWithOptions: typeof validateAadhaarWithOptions;
+    validateGstinWithOptions: typeof validateGstinWithOptions;
+    formatMobile: typeof formatMobile;
+    formatMobileWithOptions: typeof formatMobileWithOptions;
+    formatPan: typeof formatPan;
+    formatGstin: typeof formatGstin;
+    maskAadhaar: typeof maskAadhaar;
+    maskPan: typeof maskPan;
+    maskMobile: typeof maskMobile;
+    generatePan: typeof generatePan;
+    generateAadhaar: typeof generateAadhaar;
+    generateGstin: typeof generateGstin;
+    generateMobile: typeof generateMobile;
+    defaultOptions: typeof defaultOptions;
+    lenientOptions: typeof lenientOptions;
+    noSpacesHyphensOptions: typeof noSpacesHyphensOptions;
+    detect: typeof detect;
+    detectType: typeof detectType;
+    validateMany: typeof validateMany;
+    UPI_HANDLES: string[];
+    PAN_ENTITY_TYPES: Record<string, string>;
+    GSTIN_STATE_NAMES: Record<string, string>;
+};
+export default _default;