@stll/stdnum 0.0.1

package/src/gb/utr.ts

@@ -0,0 +1,81 @@
+/**
+ * UTR (Unique Taxpayer Reference).
+ *
+ * UK 10-digit tax reference number. The first
+ * digit is a check digit computed using a
+ * weighted sum with lookup table.
+ *
+ * @see https://www.gov.uk/find-utr-number
+ */
+
+import { weightedSum } from "#checksums/weighted-sum";
+import { clean } from "#util/clean";
+import { randomDigits } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type { ValidateResult, Validator } from "../types";
+
+const WEIGHTS = [6, 7, 8, 9, 10, 5, 4, 3, 2] as const;
+const CHECK_LOOKUP = "21987654321";
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "UK UTR must be exactly 10 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "UK UTR must contain only digits",
+    );
+  }
+  const sum = weightedSum(v.slice(1), WEIGHTS, 11);
+  const expected = CHECK_LOOKUP[sum];
+  if (expected !== v[0]) {
+    return err(
+      "INVALID_CHECKSUM",
+      "UK UTR check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 5)} ${v.slice(5)}`;
+};
+
+/** Generate a random valid UK UTR. */
+const generate = (): string => {
+  for (;;) {
+    const c = randomDigits(10);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** UK Unique Taxpayer Reference. */
+const utr: Validator = {
+  name: "UK Unique Taxpayer Reference",
+  localName: "Unique Taxpayer Reference",
+  abbreviation: "UTR",
+  aliases: ["Unique Taxpayer Reference", "UTR"] as const,
+  candidatePattern: "\\d{10}",
+  country: "GB",
+  entityType: "any",
+  sourceUrl: "https://www.gov.uk/find-utr-number",
+  examples: ["1955839661"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default utr;
+export { compact, format, validate, generate };

package/src/gb/vat.ts

@@ -0,0 +1,158 @@
+/**
+ * VAT (Value Added Tax registration number).
+ *
+ * UK VAT number. Multiple formats: 9 or 12
+ * digit standard, GD+3 (government), HA+3
+ * (health authority). Standard numbers use a
+ * weighted checksum mod 97.
+ *
+ * @see https://www.gov.uk/vat-registration
+ */
+
+import { weightedSum } from "#checksums/weighted-sum";
+import { clean } from "#util/clean";
+import { randomDigits } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type { ValidateResult, Validator } from "../types";
+
+const WEIGHTS = [8, 7, 6, 5, 4, 3, 2] as const;
+
+const compact = (value: string): string => {
+  let v = clean(value, " -.");
+  if (v.startsWith("GB") || v.startsWith("gb")) {
+    v = v.slice(2);
+  }
+  return v.toUpperCase();
+};
+
+const validateStandard = (v: string): ValidateResult => {
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "UK VAT must contain only digits",
+    );
+  }
+  // Weighted sum of first 7 digits
+  const sum = weightedSum(v.slice(0, 7), WEIGHTS, 97);
+  // Check digits are digits 8-9
+  const checkPart = Number(v.slice(7, 9));
+  const total = (sum + checkPart) % 97;
+
+  const prefix = Number(v.slice(0, 3));
+  if (prefix >= 100) {
+    // Numbers >= 100 000 000: remainder must be
+    // 0, 42, or 55
+    if (total !== 0 && total !== 42 && total !== 55) {
+      return err(
+        "INVALID_CHECKSUM",
+        "UK VAT check digits mismatch",
+      );
+    }
+  } else {
+    if (total !== 0) {
+      return err(
+        "INVALID_CHECKSUM",
+        "UK VAT check digits mismatch",
+      );
+    }
+  }
+  return { valid: true, compact: v };
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  // Government departments: GD + 3 digits (< 500)
+  if (v.startsWith("GD")) {
+    const num = v.slice(2);
+    if (num.length !== 3 || !isdigits(num)) {
+      return err(
+        "INVALID_FORMAT",
+        "UK VAT GD number must be GD + 3 digits",
+      );
+    }
+    if (Number(num) >= 500) {
+      return err(
+        "INVALID_COMPONENT",
+        "UK VAT GD number must be < 500",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  // Health authorities: HA + 3 digits (>= 500)
+  if (v.startsWith("HA")) {
+    const num = v.slice(2);
+    if (num.length !== 3 || !isdigits(num)) {
+      return err(
+        "INVALID_FORMAT",
+        "UK VAT HA number must be HA + 3 digits",
+      );
+    }
+    if (Number(num) < 500) {
+      return err(
+        "INVALID_COMPONENT",
+        "UK VAT HA number must be >= 500",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  // Standard: 9 or 12 digits
+  if (v.length !== 9 && v.length !== 12) {
+    return err(
+      "INVALID_LENGTH",
+      "UK VAT must be 9 or 12 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "UK VAT must contain only digits",
+    );
+  }
+  const result = validateStandard(v.slice(0, 9));
+  if (!result.valid) return result;
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.startsWith("GD") || v.startsWith("HA")) {
+    return `GB${v}`;
+  }
+  return `GB ${v.slice(0, 3)} ${v.slice(3, 7)} ${v.slice(7)}`;
+};
+
+/** Generate a random valid UK VAT number. */
+const generate = (): string => {
+  for (;;) {
+    const c = randomDigits(9);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** UK VAT Registration Number. */
+const vat: Validator = {
+  name: "UK VAT Number",
+  localName: "VAT Registration Number",
+  abbreviation: "VAT",
+  aliases: [
+    "VAT registration number",
+    "VAT number",
+  ] as const,
+  candidatePattern: "GB\\d{9,12}",
+  country: "GB",
+  entityType: "company",
+  sourceUrl: "https://www.gov.uk/vat-registration",
+  examples: ["980780684"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default vat;
+export { compact, format, validate, generate };

package/src/ge/mod.ts

@@ -0,0 +1 @@
+export { default as pin } from "./pin";

package/src/ge/pin.ts

@@ -0,0 +1,71 @@
+/** Generate a random valid Georgian PIN (11-digit). */
+const generate = (): string => randomDigits(11);
+
+/**
+ * PIN (Personal Identification Number, პირადი ნომერი).
+ *
+ * Georgian personal identification number issued by the
+ * Public Service Development Agency. Citizens receive an
+ * 11-digit number (also used as TIN); non-citizens and
+ * entities receive a 9-digit number. The number is a
+ * serial with no embedded semantics and no publicly
+ * documented checksum algorithm.
+ *
+ * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Georgia-TIN.pdf
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type { ValidateResult, Validator } from "../types";
+
+const compact = (value: string): string =>
+  clean(value, " -").trim();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 9 && v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "Georgian PIN must be 9 or 11 digits",
+    );
+  }
+
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Georgian PIN must contain only digits",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Georgian Personal Identification Number. */
+const pin: Validator = {
+  name: "Georgian Personal ID",
+  localName: "პირადი ნომერი",
+  abbreviation: "PIN",
+  aliases: ["პირადი ნომერი", "PIN"] as const,
+  candidatePattern: "\\d{11}",
+  country: "GE",
+  entityType: "any",
+  lengths: [9, 11] as const,
+  examples: ["010043120", "01024030303"] as const,
+  compact,
+  format,
+  validate,
+  sourceUrl:
+    "https://www.oecd.org/tax/automatic-exchange/" +
+    "crs-implementation-and-assistance/" +
+    "tax-identification-numbers/Georgia-TIN.pdf",
+  generate,
+};
+
+export default pin;
+export { compact, format, validate, generate };

package/src/gh/mod.ts

@@ -0,0 +1 @@
+export { default as tin } from "./tin";

package/src/gh/tin.ts

@@ -0,0 +1,100 @@
+/**
+ * TIN (Tax Identification Number, Ghana).
+ *
+ * 11-character alphanumeric identifier. Structure:
+ *   - Position 1: type prefix (P/C/G/Q/V)
+ *   - Positions 2-3: always "00"
+ *   - Positions 4-10: digits
+ *   - Position 11: check digit (0-9 or X)
+ *
+ * Prefixes: P = individual, C = company,
+ * G = government, Q = foreign mission,
+ * V = public institution / trust.
+ *
+ * @see https://gra.gov.gh/
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+const FORMAT_RE = /^[PCGQV]00[0-9]{7}[0-9X]$/;
+
+const compact = (value: string): string =>
+  clean(value, " ").toUpperCase();
+
+/**
+ * Calculate the expected check digit.
+ * Uses positions 1-9 (0-indexed) with weights 1-9,
+ * mod 11. Returns "X" when the remainder is 10.
+ */
+const calcCheckDigit = (value: string): string => {
+  let sum = 0;
+  for (let i = 1; i <= 9; i++) {
+    sum += i * Number(value[i]);
+  }
+  const check = sum % 11;
+  return check === 10 ? "X" : String(check);
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "Ghanaian TIN must be exactly 11 characters",
+    );
+  }
+  if (!FORMAT_RE.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Ghanaian TIN must match [PCGQV]00 + " +
+        "7 digits + check digit",
+    );
+  }
+  if (v[10] !== calcCheckDigit(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Ghanaian TIN check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Ghana TIN. */
+const generate = (): string => {
+  const prefixes = ["P", "C", "G", "Q", "V"] as const;
+  for (;;) {
+    const p = prefixes[randomInt(0, 4)]!;
+    const d = randomDigits(9);
+    const partial = p + d;
+    const c = partial + calcCheckDigit(partial);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Ghanaian Tax Identification Number. */
+const tin: Validator = {
+  name: "Ghanaian Tax Identification Number",
+  localName: "Tax Identification Number",
+  abbreviation: "TIN",
+  aliases: ["TIN", "Tax Identification Number"] as const,
+  candidatePattern: "[A-Z]\\d{9,10}",
+  country: "GH",
+  entityType: "any",
+  compact,
+  format,
+  validate,
+  description: "Ghanaian tax identification number",
+  sourceUrl: "https://gra.gov.gh/",
+  lengths: [11] as const,
+  examples: ["C0000803561"] as const,
+  generate,
+};
+
+export default tin;
+export { compact, format, validate, generate };

package/src/gr/amka.ts

@@ -0,0 +1,104 @@
+/**
+ * AMKA (Αριθμός Μητρώου Κοινωνικής Ασφάλισης).
+ *
+ * Greek social security number. 11 digits where the
+ * first 6 are DDMMYY, followed by 4-digit serial and
+ * a Luhn check digit.
+ *
+ * @see https://www.amka.gr/
+ */
+
+import {
+  luhnValidate,
+  luhnChecksum,
+} from "#checksums/luhn";
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type { ValidateResult, Validator } from "../types";
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "AMKA must be exactly 11 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "AMKA must contain only digits",
+    );
+  }
+
+  const dd = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const yy = Number(v.slice(4, 6));
+
+  // AMKA doesn't encode century explicitly;
+  // validate the date for both 1900s and 2000s
+  const valid1900 = isValidDate(1900 + yy, mm, dd);
+  const valid2000 = isValidDate(2000 + yy, mm, dd);
+  if (!valid1900 && !valid2000) {
+    return err(
+      "INVALID_COMPONENT",
+      "AMKA contains an invalid date",
+    );
+  }
+
+  if (!luhnValidate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "AMKA Luhn check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Greek AMKA. */
+const generate = (): string => {
+  for (;;) {
+    const dd = String(randomInt(1, 28)).padStart(2, "0");
+    const mm = String(randomInt(1, 12)).padStart(2, "0");
+    const yy = String(randomInt(50, 99)).padStart(2, "0");
+    const serial = randomDigits(4);
+    const payload = dd + mm + yy + serial;
+    const cs = luhnChecksum(payload + "0");
+    const c = payload + String((10 - cs) % 10);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Greek Social Security Number. */
+const amka: Validator = {
+  name: "Greek Social Security Number",
+  localName: "Αριθμός Μητρώου Κοινωνικής Ασφάλισης",
+  abbreviation: "ΑΜΚΑ",
+  aliases: [
+    "ΑΜΚΑ",
+    "Αριθμός Μητρώου Κοινωνικής Ασφάλισης",
+    "AMKA",
+  ] as const,
+  candidatePattern: "\\d{11}",
+  country: "GR",
+  entityType: "person",
+  sourceUrl: "https://www.amka.gr/",
+  examples: ["01013099997"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default amka;
+export { compact, format, validate, generate };

package/src/gr/mod.ts

@@ -0,0 +1,2 @@
+export { default as amka } from "./amka";
+export { default as vat } from "./vat";

package/src/gr/vat.ts

@@ -0,0 +1,96 @@
+/**
+ * ΑΦΜ (Greek VAT number).
+ *
+ * 9 digits. 8-digit numbers are zero-padded.
+ * Iterative checksum: cs = 0; for each d[0..7]:
+ * cs = cs*2 + d; check = (cs*2) % 11 % 10 == d[8].
+ *
+ * @see https://www.vatify.eu/greece-vat-number.html
+ * @see https://www.aade.gr/
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type { ValidateResult, Validator } from "../types";
+
+const compact = (value: string): string => {
+  let v = clean(value, " -/.");
+  if (v.startsWith("EL") || v.startsWith("el")) {
+    v = v.slice(2);
+  }
+  if (v.startsWith("GR") || v.startsWith("gr")) {
+    v = v.slice(2);
+  }
+  // Zero-pad 8-digit numbers
+  if (v.length === 8) {
+    v = `0${v}`;
+  }
+  return v;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "Greek VAT number must be 9 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Greek VAT number must contain only digits",
+    );
+  }
+  let cs = 0;
+  for (let i = 0; i < 8; i++) {
+    cs = cs * 2 + Number(v[i]);
+  }
+  const check = ((cs * 2) % 11) % 10;
+  if (check !== Number(v[8])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Greek VAT number check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string =>
+  `EL${compact(value)}`;
+
+/** Generate a random valid Greek VAT number. */
+const generate = (): string => {
+  const payload = randomDigits(8);
+  let cs = 0;
+  for (let i = 0; i < 8; i++)
+    cs = cs * 2 + Number(payload[i]);
+  return payload + String(((cs * 2) % 11) % 10);
+};
+
+/** Greek VAT Number. */
+const vat: Validator = {
+  name: "Greek VAT Number",
+  localName: "Αριθμός Φορολογικού Μητρώου",
+  abbreviation: "ΑΦΜ",
+  aliases: [
+    "ΑΦΜ",
+    "Αριθμός Φορολογικού Μητρώου",
+    "AFM",
+  ] as const,
+  candidatePattern: "EL\\d{9}",
+  country: "GR",
+  entityType: "any",
+  sourceUrl: "https://www.aade.gr/",
+  examples: ["094259216"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default vat;
+export { compact, format, validate, generate };

package/src/gt/mod.ts

@@ -0,0 +1 @@
+export { default as nit } from "./nit";