@stll/stdnum 0.0.1

package/src/iban.ts

@@ -0,0 +1,340 @@
+/**
+ * IBAN (International Bank Account Number).
+ *
+ * ISO 13616. Format: 2-letter country code +
+ * 2 check digits + up to 30 alphanumeric BBAN
+ * characters. Validated using ISO 7064 Mod 97-10.
+ */
+
+import { mod97 } from "#checksums/mod97";
+import { clean } from "#util/clean";
+import { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { charValue, isalnum } from "#util/strings";
+
+import type { ValidateResult, Validator } from "./types";
+
+/**
+ * BBAN format regex by country code.
+ * Sourced from SWIFT IBAN Registry.
+ */
+const BBAN_FORMAT: Record<string, RegExp> = {
+  AD: /^\d{8}[A-Z0-9]{12}$/,
+  AE: /^\d{19}$/,
+  AL: /^\d{8}[A-Z0-9]{16}$/,
+  AT: /^\d{16}$/,
+  AZ: /^[A-Z]{4}[A-Z0-9]{20}$/,
+  BA: /^\d{16}$/,
+  BE: /^\d{12}$/,
+  BG: /^[A-Z]{4}\d{6}[A-Z0-9]{8}$/,
+  BH: /^[A-Z]{4}[A-Z0-9]{14}$/,
+  BR: /^\d{23}[A-Z]{1}[A-Z0-9]{1}$/,
+  BY: /^[A-Z0-9]{4}\d{20}$/,
+  CH: /^\d{17}$/,
+  CR: /^0\d{17}$/,
+  CY: /^\d{8}[A-Z0-9]{16}$/,
+  CZ: /^\d{20}$/,
+  DE: /^\d{18}$/,
+  DK: /^\d{14}$/,
+  DO: /^[A-Z0-9]{4}\d{20}$/,
+  EE: /^\d{16}$/,
+  EG: /^\d{25}$/,
+  ES: /^\d{20}$/,
+  FI: /^\d{14}$/,
+  FO: /^\d{14}$/,
+  FR: /^\d{10}[A-Z0-9]{11}\d{2}$/,
+  GB: /^[A-Z]{4}\d{14}$/,
+  GE: /^[A-Z]{2}\d{16}$/,
+  GI: /^[A-Z]{4}[A-Z0-9]{15}$/,
+  GL: /^\d{14}$/,
+  GR: /^\d{7}[A-Z0-9]{16}$/,
+  GT: /^[A-Z0-9]{24}$/,
+  HR: /^\d{17}$/,
+  HU: /^\d{24}$/,
+  IE: /^[A-Z]{4}\d{14}$/,
+  IL: /^\d{19}$/,
+  IQ: /^[A-Z]{4}\d{15}$/,
+  IS: /^\d{22}$/,
+  IT: /^[A-Z]\d{10}[A-Z0-9]{12}$/,
+  JO: /^[A-Z]{4}\d{22}$/,
+  KW: /^[A-Z]{4}[A-Z0-9]{22}$/,
+  KZ: /^\d{16}$/,
+  LB: /^\d{4}[A-Z0-9]{20}$/,
+  LC: /^[A-Z]{4}[A-Z0-9]{24}$/,
+  LI: /^\d{17}$/,
+  LT: /^\d{16}$/,
+  LU: /^\d{16}$/,
+  LV: /^[A-Z]{4}[A-Z0-9]{13}$/,
+  MC: /^\d{10}[A-Z0-9]{11}\d{2}$/,
+  MD: /^[A-Z0-9]{20}$/,
+  ME: /^\d{18}$/,
+  MK: /^\d{3}[A-Z0-9]{10}\d{2}$/,
+  MR: /^\d{23}$/,
+  MT: /^[A-Z]{4}\d{5}[A-Z0-9]{18}$/,
+  MU: /^[A-Z]{4}\d{19}[A-Z]{3}$/,
+  NI: /^[A-Z]{4}\d{24}$/,
+  NL: /^[A-Z]{4}\d{10}$/,
+  NO: /^\d{11}$/,
+  PK: /^[A-Z]{4}[A-Z0-9]{16}$/,
+  PL: /^\d{24}$/,
+  PS: /^[A-Z]{4}[A-Z0-9]{21}$/,
+  PT: /^\d{21}$/,
+  QA: /^[A-Z]{4}[A-Z0-9]{21}$/,
+  RO: /^[A-Z]{4}[A-Z0-9]{16}$/,
+  RS: /^\d{18}$/,
+  SA: /^\d{20}$/,
+  SC: /^[A-Z]{4}\d{20}[A-Z]{3}$/,
+  SD: /^\d{14}$/,
+  SE: /^\d{20}$/,
+  SI: /^\d{15}$/,
+  SK: /^\d{20}$/,
+  SM: /^[A-Z]\d{10}[A-Z0-9]{12}$/,
+  ST: /^\d{21}$/,
+  SV: /^[A-Z]{4}\d{20}$/,
+  TL: /^\d{19}$/,
+  TN: /^\d{20}$/,
+  TR: /^\d{6}[A-Z0-9]{16}$/,
+  UA: /^\d{6}[A-Z0-9]{19}$/,
+  VA: /^\d{18}$/,
+  VG: /^[A-Z]{4}\d{16}$/,
+  XK: /^\d{16}$/,
+};
+
+/** IBAN total length by country code. */
+const LENGTHS: Record<string, number> = {
+  AD: 24,
+  AE: 23,
+  AL: 28,
+  AT: 20,
+  AZ: 28,
+  BA: 20,
+  BE: 16,
+  BG: 22,
+  BH: 22,
+  BI: 27,
+  BR: 29,
+  BY: 28,
+  CH: 21,
+  CR: 22,
+  CY: 28,
+  CZ: 24,
+  DE: 22,
+  DJ: 27,
+  DK: 18,
+  DO: 28,
+  EE: 20,
+  EG: 29,
+  ES: 24,
+  FI: 18,
+  FO: 18,
+  FR: 27,
+  GB: 22,
+  GE: 22,
+  GI: 23,
+  GL: 18,
+  GR: 27,
+  GT: 28,
+  HR: 21,
+  HU: 28,
+  IE: 22,
+  IL: 23,
+  IQ: 23,
+  IS: 26,
+  IT: 27,
+  JO: 30,
+  KW: 30,
+  KZ: 20,
+  LB: 28,
+  LC: 32,
+  LI: 21,
+  LT: 20,
+  LU: 20,
+  LV: 21,
+  LY: 25,
+  MC: 27,
+  MD: 24,
+  ME: 22,
+  MK: 19,
+  MN: 20,
+  MR: 27,
+  MT: 31,
+  MU: 30,
+  NI: 28,
+  NL: 18,
+  NO: 15,
+  PK: 24,
+  PL: 28,
+  PS: 29,
+  PT: 25,
+  QA: 29,
+  RO: 24,
+  RS: 22,
+  RU: 33,
+  SA: 24,
+  SC: 31,
+  SD: 18,
+  SE: 24,
+  SI: 19,
+  SK: 24,
+  SM: 27,
+  SN: 28,
+  SO: 23,
+  ST: 25,
+  SV: 28,
+  TL: 23,
+  TN: 24,
+  TR: 26,
+  UA: 29,
+  VA: 22,
+  VG: 24,
+  XK: 20,
+};
+
+const compact = (value: string): string =>
+  clean(value, " -").toUpperCase();
+
+/**
+ * Convert letters to numbers (A=10, ..., Z=35)
+ * and rearrange for mod-97 check.
+ */
+const toNumeric = (iban: string): string => {
+  const rearranged = iban.slice(4) + iban.slice(0, 4);
+  let result = "";
+  for (let i = 0; i < rearranged.length; i++) {
+    const ch = rearranged[i];
+    if (ch !== undefined) {
+      result += String(charValue(ch));
+    }
+  }
+  return result;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length < 5) {
+    return err("INVALID_LENGTH", "IBAN is too short");
+  }
+  if (!isalnum(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "IBAN must contain only letters and digits",
+    );
+  }
+  const cc = v.slice(0, 2);
+  if (!/^[A-Z]{2}$/.test(cc)) {
+    return err(
+      "INVALID_COMPONENT",
+      "IBAN must start with a 2-letter country code",
+    );
+  }
+  const expectedLen = LENGTHS[cc];
+  if (
+    expectedLen !== undefined &&
+    v.length !== expectedLen
+  ) {
+    return err(
+      "INVALID_LENGTH",
+      `IBAN for ${cc} must be ${String(expectedLen)} characters`,
+    );
+  }
+  // Validate BBAN format (country-specific)
+  const bban = v.slice(4);
+  const bbanRegex = BBAN_FORMAT[cc];
+  if (bbanRegex !== undefined && !bbanRegex.test(bban)) {
+    return err(
+      "INVALID_FORMAT",
+      `IBAN BBAN format is invalid for ${cc}`,
+    );
+  }
+  const numeric = toNumeric(v);
+  if (mod97(numeric) !== 1) {
+    return err(
+      "INVALID_CHECKSUM",
+      "IBAN check digits are incorrect",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  const groups: string[] = [];
+  for (let i = 0; i < v.length; i += 4) {
+    groups.push(v.slice(i, i + 4));
+  }
+  return groups.join(" ");
+};
+
+/**
+ * Countries supported by generate(). All have
+ * all-digit BBANs for simplicity.
+ */
+const GENERATE_COUNTRIES = ["CZ", "DE", "SK"] as const;
+
+type GenerateCountry = (typeof GENERATE_COUNTRIES)[number];
+
+/** BBAN lengths for generate()-supported countries. */
+const BBAN_LENGTHS: Record<GenerateCountry, number> = {
+  CZ: 20,
+  DE: 18,
+  SK: 20,
+};
+
+/**
+ * Compute IBAN check digits for a country code
+ * and BBAN. Returns a 2-character string.
+ */
+const computeCheckDigits = (
+  cc: string,
+  bban: string,
+): string => {
+  const placeholder = `${bban}${cc}00`;
+  let numeric = "";
+  for (let i = 0; i < placeholder.length; i++) {
+    const ch = placeholder[i];
+    if (ch !== undefined) {
+      numeric += String(charValue(ch));
+    }
+  }
+  const remainder = mod97(numeric);
+  const check = 98 - remainder;
+  return String(check).padStart(2, "0");
+};
+
+/**
+ * Generate a random valid IBAN for CZ, DE, or SK.
+ */
+const generate = (): string => {
+  const idx = randomInt(0, GENERATE_COUNTRIES.length - 1);
+  const cc = GENERATE_COUNTRIES[idx] as GenerateCountry;
+  const bbanLen = BBAN_LENGTHS[cc];
+  const bban = randomDigits(bbanLen);
+  const checkDigits = computeCheckDigits(cc, bban);
+  return `${cc}${checkDigits}${bban}`;
+};
+
+/** International Bank Account Number. */
+const iban: Validator = {
+  name: "IBAN",
+  localName: "IBAN",
+  abbreviation: "IBAN",
+  aliases: ["IBAN"] as const,
+  candidatePattern:
+    "[A-Z]{2}\\d{2}[\\s]?[A-Z0-9]{4}[\\s]?(?:[A-Z0-9]{4}[\\s]?){2,7}[A-Z0-9]{1,4}",
+  entityType: "any",
+  description:
+    "International bank account number per ISO 13616",
+  sourceUrl:
+    "https://www.swift.com/standards/data-standards/iban-international-bank-account-number",
+  examples: [
+    "GB29NWBK60161331926819",
+    "DE89370400440532013000",
+  ] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default iban;
+export { compact, format, generate, validate };

package/src/id/mod.ts

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

package/src/id/npwp.ts

@@ -0,0 +1,187 @@
+/**
+ * NPWP (Nomor Pokok Wajib Pajak, Indonesian tax ID).
+ *
+ * 15 or 16 digits. The 15-digit (legacy) format has a
+ * Luhn check on the first 9 digits. The 16-digit format
+ * is either a NIK (starts with non-zero) validated as a
+ * province-code and birth-date checks, or the legacy
+ * format prefixed with 0 (Luhn on first 10 digits).
+ *
+ * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Indonesia-TIN.pdf
+ */
+
+import {
+  luhnValidate,
+  luhnChecksum,
+} from "#checksums/luhn";
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+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, " .-");
+
+/**
+ * Valid 2-digit province codes for NIK, sourced from
+ * python-stdnum's id/loc numdb.
+ */
+const NIK_PROVINCES = new Set([
+  "11",
+  "12",
+  "13",
+  "14",
+  "15",
+  "16",
+  "17",
+  "18",
+  "19",
+  "21",
+  "31",
+  "32",
+  "33",
+  "34",
+  "35",
+  "36",
+  "51",
+  "52",
+  "53",
+  "61",
+  "62",
+  "63",
+  "64",
+  "71",
+  "72",
+  "73",
+  "74",
+  "75",
+  "76",
+  "81",
+  "82",
+  "91",
+  "94",
+]);
+
+/**
+ * Validate a 16-digit NIK (Nomor Induk Kependudukan).
+ * Format: PPRRSSDDMMYYXXXX where PP = province,
+ * RRSS = regency/city + sub-district,
+ * DDMMYY = birth date (DD+40 for females),
+ * XXXX = serial.
+ */
+const validateNik = (v: string): ValidateResult => {
+  // Province code check
+  if (!NIK_PROVINCES.has(v.slice(0, 2))) {
+    return err(
+      "INVALID_COMPONENT",
+      "NIK province code is invalid",
+    );
+  }
+  let day = Number(v.slice(6, 8));
+  const month = Number(v.slice(8, 10));
+  const year = Number(v.slice(10, 12));
+  // Females have 40 added to the day
+  if (day > 40) day -= 40;
+  // Validate the date (century is ambiguous in NIK)
+  if (
+    !isValidDate(1900 + year, month, day) &&
+    !isValidDate(2000 + year, month, day)
+  ) {
+    return err(
+      "INVALID_COMPONENT",
+      "NIK contains an invalid date",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "NPWP must contain only digits",
+    );
+  }
+  if (v.length === 15) {
+    // Legacy 15-digit format: Luhn on first 9 digits
+    if (!luhnValidate(v.slice(0, 9))) {
+      return err(
+        "INVALID_CHECKSUM",
+        "NPWP Luhn check on first 9 digits failed",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+  if (v.length === 16) {
+    if (v[0] !== "0") {
+      // NIK format
+      return validateNik(v);
+    }
+    // 0-prefixed legacy: Luhn on first 10 digits
+    if (!luhnValidate(v.slice(0, 10))) {
+      return err(
+        "INVALID_CHECKSUM",
+        "NPWP Luhn check on first 10 digits failed",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+  return err(
+    "INVALID_LENGTH",
+    "NPWP must be 15 or 16 digits",
+  );
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length === 16) {
+    // NIK or 0-prefixed legacy: no standard mask
+    return v;
+  }
+  return (
+    `${v.slice(0, 2)}.${v.slice(2, 5)}.` +
+    `${v.slice(5, 8)}.${v.slice(8, 9)}` +
+    `-${v.slice(9, 12)}.${v.slice(12)}`
+  );
+};
+
+/** Generate a random valid 15-digit NPWP. */
+const generate = (): string => {
+  for (;;) {
+    const p = randomDigits(8);
+    const cs = luhnChecksum(p + "0");
+    const c = p + String((10 - cs) % 10) + randomDigits(6);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Indonesian Taxpayer Identification Number. */
+const npwp: Validator = {
+  name: "Indonesian Taxpayer Identification Number",
+  localName: "Nomor Pokok Wajib Pajak",
+  abbreviation: "NPWP",
+  aliases: ["NPWP", "Nomor Pokok Wajib Pajak"] as const,
+  candidatePattern:
+    "\\d{2}\\.?\\d{3}\\.?\\d{3}\\.?\\d-?\\d{3}\\.?\\d{3}",
+  country: "ID",
+  entityType: "any",
+  lengths: [15, 16],
+  examples: ["013000666091000", "016090524017000"],
+  description:
+    "15 or 16-digit tax identification number issued by " +
+    "the Directorate General of Taxes",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/" +
+    "Tax_identification_number#Indonesia",
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default npwp;
+export { compact, format, validate, generate };

package/src/ie/mod.ts

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

package/src/ie/pps.ts

@@ -0,0 +1,105 @@
+/**
+ * PPS (Personal Public Service Number).
+ *
+ * Irish personal identification number. 7 digits
+ * followed by a check letter and an optional second
+ * letter (new format). Uses a weighted sum with
+ * alphabet "WABCDEFGHIJKLMNOPQRSTUV".
+ *
+ * @see https://www.gov.ie/en/service/12e6de-get-a-personal-public-service-pps-number/
+ */
+
+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 ALPHABET = "WABCDEFGHIJKLMNOPQRSTUV";
+
+const compact = (value: string): string =>
+  clean(value, " -").toUpperCase();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length < 8 || v.length > 9) {
+    return err(
+      "INVALID_LENGTH",
+      "PPS must be 8 or 9 characters",
+    );
+  }
+
+  const digits = v.slice(0, 7);
+  if (!isdigits(digits)) {
+    return err(
+      "INVALID_FORMAT",
+      "PPS must start with 7 digits",
+    );
+  }
+
+  const checkLetter = v[7];
+  const secondLetter = v.length >= 9 ? v[8] : undefined;
+
+  // Compute weighted sum: weights 8..2 for digits
+  let sum = 0;
+  for (let i = 0; i < 7; i++) {
+    sum += Number(digits[i]) * (8 - i);
+  }
+
+  // New format: add 9 * index of 2nd letter
+  if (secondLetter !== undefined && secondLetter !== "W") {
+    const idx = ALPHABET.indexOf(secondLetter);
+    if (idx === -1) {
+      return err(
+        "INVALID_FORMAT",
+        "PPS second letter is invalid",
+      );
+    }
+    sum += 9 * idx;
+  }
+
+  const remainder = sum % 23;
+  const expected = ALPHABET[remainder];
+  if (checkLetter !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "PPS check letter does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Irish PPS number. */
+const generate = (): string => {
+  for (;;) {
+    for (let c = 65; c <= 90; c++) {
+      const cand = randomDigits(7) + String.fromCharCode(c);
+      if (validate(cand).valid) return compact(cand);
+    }
+  }
+};
+
+/** Irish Personal Public Service Number. */
+const pps: Validator = {
+  name: "Irish Personal ID",
+  localName: "Personal Public Service Number",
+  abbreviation: "PPS",
+  aliases: ["PPS number", "PPSN", "RSI number"] as const,
+  candidatePattern: "\\d{7}[A-Z]{1,2}",
+  country: "IE",
+  entityType: "person",
+  sourceUrl:
+    "https://www.gov.ie/en/service/12e6de-get-a-personal-public-service-pps-number/",
+  examples: ["6433435F"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default pps;
+export { compact, format, validate, generate };