@stll/stdnum 0.0.1

package/src/br/cnpj.ts

@@ -0,0 +1,152 @@
+/**
+ * CNPJ (Cadastro Nacional da Pessoa Jurídica).
+ *
+ * Brazilian company tax identification number assigned by
+ * the Receita Federal (Federal Revenue Service). The
+ * number consists of 14 characters: 8 identifying the
+ * company, 4 identifying the establishment (0001 for
+ * headquarters), and 2 check digits computed using a
+ * weighted modulo 11 algorithm.
+ *
+ * As of July 2026 the Receita Federal will begin issuing
+ * alphanumeric CNPJs (letters A-Z in place of some
+ * digits). The check digit algorithm uses ordinal values
+ * (0-9 = 0-9, A-Z = 17-42) to support this.
+ *
+ * Format: NN.NNN.NNN/NNNN-DD (14 characters).
+ *
+ * @see https://www.gov.br/en/categories/finance-taxes-and-public-management/cpf-cnpj-and-other-records
+ * @see https://en.wikipedia.org/wiki/CNPJ
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+const CNPJ_RE = /^[\dA-Z]+$/;
+
+const compact = (value: string): string =>
+  clean(value, " -./").trim().toUpperCase();
+
+/**
+ * Convert a CNPJ character to its numeric value.
+ * Digits 0-9 map to 0-9; letters A-Z map to their
+ * char code minus 48 (matching python-stdnum's
+ * `ord(n) - 48` convention: A=17, B=18, ..., Z=42).
+ */
+const charToValue = (ch: string): number =>
+  ch.charCodeAt(0) - 48;
+
+/**
+ * Calculate the two CNPJ check digits using the
+ * Receita Federal modulo 11 algorithm.
+ *
+ * First check digit: weights [5,4,3,2,9,8,7,6,5,4,3,2]
+ * applied to the first 12 characters.
+ *
+ * Second check digit: weights [6,5,4,3,2,9,8,7,6,5,4,3,2]
+ * applied to the first 12 characters plus the first
+ * check digit.
+ */
+const calcCheckDigits = (number: string): string => {
+  const w1 = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+  let sum = 0;
+  for (let i = 0; i < 12; i++) {
+    sum += (w1[i] ?? 0) * charToValue(number.charAt(i));
+  }
+  const d1 = ((11 - (sum % 11)) % 11) % 10;
+
+  const w2 = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+  sum = 0;
+  for (let i = 0; i < 12; i++) {
+    sum += (w2[i] ?? 0) * charToValue(number.charAt(i));
+  }
+  // Use the computed d1 (not the stored digit at
+  // number[12]) so both check digits are derived
+  // from the base alone.
+  sum += (w2[12] ?? 0) * d1;
+  const d2 = ((11 - (sum % 11)) % 11) % 10;
+
+  return `${d1}${d2}`;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 14) {
+    return err(
+      "INVALID_LENGTH",
+      "CNPJ must be 14 characters",
+    );
+  }
+  if (!CNPJ_RE.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "CNPJ must contain only digits and uppercase letters",
+    );
+  }
+  // Reject all-zero base (first 12 chars).
+  // Unlike CPF, we do not reject all-same-digit CNPJs;
+  // python-stdnum only blocks the all-zero base, and
+  // there is no official Receita Federal list of
+  // blocked same-digit CNPJ sequences.
+  if (v.startsWith("000000000000")) {
+    return err(
+      "INVALID_FORMAT",
+      "CNPJ base must not be all zeros",
+    );
+  }
+  if (calcCheckDigits(v) !== v.slice(12)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "CNPJ check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 2)}.${v.slice(2, 5)}.${v.slice(5, 8)}/${v.slice(8, 12)}-${v.slice(12)}`;
+};
+
+/** Generate a random valid CNPJ. */
+const generate = (): string => {
+  for (;;) {
+    const base = randomDigits(12);
+    if (base === "000000000000") continue;
+    return base + calcCheckDigits(base);
+  }
+};
+
+/**
+ * Brazilian CNPJ (company tax ID).
+ *
+ * Examples sourced from publicly available Brazilian
+ * corporate registries:
+ * - Petrobras: 33.000.167/0001-01
+ * - Banco do Brasil: 00.000.000/0001-91
+ */
+const cnpj: Validator = {
+  name: "Brazilian CNPJ",
+  localName: "Cadastro Nacional da Pessoa Jurídica",
+  abbreviation: "CNPJ",
+  aliases: [
+    "CNPJ",
+    "Cadastro Nacional da Pessoa Jurídica",
+  ] as const,
+  candidatePattern:
+    "\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2}",
+  country: "BR",
+  entityType: "company",
+  sourceUrl: "https://www.gov.br/receitafederal/",
+  examples: ["33000167000101", "00000000000191"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default cnpj;
+export { compact, format, validate, generate };

package/src/br/cpf.ts

@@ -0,0 +1,114 @@
+/**
+ * CPF (Cadastro de Pessoas Físicas).
+ *
+ * Brazilian personal tax identification number assigned
+ * by the Receita Federal (Federal Revenue Service) to
+ * individuals. The number consists of 11 digits: 9 base
+ * digits followed by 2 check digits computed using a
+ * weighted modulo 11 algorithm.
+ *
+ * Format: NNN.NNN.NNN-DD (11 digits, purely numeric).
+ *
+ * @see https://www.gov.br/en/categories/finance-taxes-and-public-management/cpf-cnpj-and-other-records
+ * @see https://en.wikipedia.org/wiki/CPF_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 compact = (value: string): string =>
+  clean(value, " -.").trim();
+
+/**
+ * Calculate the two CPF check digits using the
+ * Receita Federal modulo 11 algorithm.
+ *
+ * First check digit: multiply digits 0..8 by weights
+ * 10..2, sum, then (11 - sum % 11) % 11 % 10.
+ *
+ * Second check digit: multiply digits 0..8 by weights
+ * 11..3, add 2 * first check digit, then
+ * (11 - sum % 11) % 11 % 10.
+ */
+const calcCheckDigits = (number: string): string => {
+  let sum = 0;
+  for (let i = 0; i < 9; i++) {
+    sum += (10 - i) * Number(number[i]);
+  }
+  const d1 = ((11 - (sum % 11)) % 11) % 10;
+
+  sum = 0;
+  for (let i = 0; i < 9; i++) {
+    sum += (11 - i) * Number(number[i]);
+  }
+  sum += 2 * d1;
+  const d2 = ((11 - (sum % 11)) % 11) % 10;
+
+  return `${d1}${d2}`;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err("INVALID_LENGTH", "CPF must be 11 digits");
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "CPF must contain only digits",
+    );
+  }
+  // All-same-digit CPFs (e.g. 000.000.000-00) pass the
+  // checksum but are not valid registrations.
+  if (/^(\d)\1{10}$/.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "CPF must not be a repeated digit sequence",
+    );
+  }
+  if (calcCheckDigits(v) !== v.slice(9)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "CPF check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 3)}.${v.slice(3, 6)}.${v.slice(6, 9)}-${v.slice(9)}`;
+};
+
+/** Generate a random valid CPF. */
+const generate = (): string => {
+  for (;;) {
+    const base = randomDigits(9);
+    if (/^(\d)\1{8}$/.test(base)) continue;
+    return base + calcCheckDigits(base);
+  }
+};
+
+/** Brazilian CPF (personal tax ID). */
+const cpf: Validator = {
+  name: "Brazilian CPF",
+  localName: "Cadastro de Pessoas Físicas",
+  abbreviation: "CPF",
+  aliases: ["CPF", "Cadastro de Pessoas Físicas"] as const,
+  candidatePattern: "\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}",
+  country: "BR",
+  entityType: "person",
+  sourceUrl: "https://www.gov.br/receitafederal/",
+  examples: ["39053344705"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default cpf;
+export { compact, format, validate, generate };

package/src/br/mod.ts

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

package/src/by/mod.ts

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

package/src/by/unp.ts

@@ -0,0 +1,153 @@
+/**
+ * UNP (Учётный номер плательщика, Belarus tax number).
+ *
+ * 9 characters: the first two identify the region (numeric
+ * for organisations, letters from ABCEHKMOPT for
+ * individuals), followed by 7 digits. The last digit is a
+ * weighted check digit (mod 11; if remainder > 9 the
+ * number is invalid).
+ *
+ * @see https://be.wikipedia.org/wiki/Уліковы_нумар_плацельшчыка
+ * @see https://www.nalog.gov.by/
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type { ValidateResult, Validator } from "../types";
+
+/** Cyrillic to Latin mapping for the letter positions. */
+const CYRILLIC_TO_LATIN: Record<string, string> = {
+  А: "A",
+  В: "B",
+  Е: "E",
+  К: "K",
+  М: "M",
+  Н: "H",
+  О: "O",
+  Р: "P",
+  С: "C",
+  Т: "T",
+};
+
+const WEIGHTS = [29, 23, 19, 17, 13, 7, 5, 3] as const;
+const ALPHA_SET = "ABCEHKMOPT";
+const VALID_FIRST = "1234567ABCEHKM";
+const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+const compact = (value: string): string => {
+  let v = clean(value, " ").toUpperCase().trim();
+  if (v.startsWith("УНП")) {
+    v = v.slice(3);
+  } else if (v.startsWith("UNP")) {
+    v = v.slice(3);
+  }
+  return [...v]
+    .map((ch) => CYRILLIC_TO_LATIN[ch] ?? ch)
+    .join("");
+};
+
+const calcCheckDigit = (number: string): number | null => {
+  let work = number;
+  if (!isdigits(number)) {
+    const idx = ALPHA_SET.indexOf(number[1]!);
+    if (idx === -1) return null;
+    work = number[0] + String(idx) + number.slice(2);
+  }
+  let sum = 0;
+  for (let i = 0; i < 8; i++) {
+    const ch = work[i]!;
+    const val = ALPHABET.indexOf(ch);
+    if (val === -1) return null;
+    sum += (WEIGHTS[i] ?? 0) * val;
+  }
+  const remainder = sum % 11;
+  if (remainder > 9) return null;
+  return remainder;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "Belarus UNP must be 9 characters",
+    );
+  }
+  if (!isdigits(v.slice(2))) {
+    return err(
+      "INVALID_FORMAT",
+      "Belarus UNP positions 3-9 must be digits",
+    );
+  }
+  const first2 = v.slice(0, 2);
+  if (
+    !isdigits(first2) &&
+    ![...first2].every((ch) => ALPHA_SET.includes(ch))
+  ) {
+    return err(
+      "INVALID_FORMAT",
+      "Belarus UNP first two characters must be" +
+        " digits or letters from ABCEHKMOPT",
+    );
+  }
+  if (!VALID_FIRST.includes(v[0]!)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Belarus UNP has an invalid region prefix",
+    );
+  }
+  const expected = calcCheckDigit(v);
+  if (expected === null) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Belarus UNP check digit is invalid" +
+        " (mod 11 remainder > 9)",
+    );
+  }
+  if (v[8] !== String(expected)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Belarus UNP check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Belarus UNP. */
+const generate = (): string => {
+  for (let i = 0; i < 100; i++) {
+    const prefix = String(randomInt(1, 7));
+    const rest = randomDigits(7);
+    const payload = prefix + rest;
+    const check = calcCheckDigit(payload);
+    if (check === null) continue;
+    const c = payload.slice(0, 8) + String(check);
+    if (validate(c).valid) return c;
+  }
+  throw new Error("Failed to generate valid UNP");
+};
+
+/** Belarus UNP (Учётный номер плательщика). */
+const unp: Validator = {
+  name: "Belarus Tax Number",
+  localName: "Учётный номер плательщика",
+  abbreviation: "УНП",
+  aliases: ["УНП", "UNP"] as const,
+  candidatePattern: "\\d{9}",
+  country: "BY",
+  entityType: "any",
+  sourceUrl: "https://www.nalog.gov.by/",
+  examples: ["200988541", "MA1953684"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default unp;
+export { compact, format, validate, generate };

package/src/bz/mod.ts

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

package/src/bz/tin.ts

@@ -0,0 +1,107 @@
+/**
+ * TIN (Belize Tax Identification Number).
+ *
+ * Issued by the Belize Tax Service Department to
+ * individuals, sole proprietors, partnerships, and
+ * companies. The base number is 6 digits generated
+ * by the Revenue Management System. A 2-digit
+ * suffix code may be appended to indicate entity
+ * type:
+ *   - 10: individual
+ *   - 13: company
+ *   - 66: company (alternate)
+ *
+ * The OECD spec mentions a 7th check digit that is
+ * not visible to the taxpayer; in practice the
+ * number circulates as 6 or 8 digits (6 + suffix).
+ *
+ * Formatted as NNNNNN-SS (when suffix is present).
+ *
+ * Source: OECD CRS TIN information sheet; Belize
+ * Tax Service (https://bts.gov.bz/).
+ *
+ * PERSON/ENTITY
+ *
+ * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Belize-TIN.pdf
+ */
+
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+/** Valid 2-digit suffix codes. */
+const SUFFIX_CODES = ["10", "13", "66"] as const;
+
+const compact = (value: string): string => {
+  return clean(value, " -").trim();
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 6 && v.length !== 8) {
+    return err(
+      "INVALID_LENGTH",
+      "Belize TIN must be 6 or 8 digits",
+    );
+  }
+
+  if (!/^\d+$/.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Belize TIN must contain only digits",
+    );
+  }
+
+  if (v.length === 8) {
+    const suffix = v.slice(6);
+    if (
+      !SUFFIX_CODES.includes(
+        suffix as (typeof SUFFIX_CODES)[number],
+      )
+    ) {
+      return err(
+        "INVALID_COMPONENT",
+        "Belize TIN suffix must be 10, 13, or 66",
+      );
+    }
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length <= 6) {
+    return v;
+  }
+  return `${v.slice(0, 6)}-${v.slice(6)}`;
+};
+
+/**
+ * Belize Tax Identification Number.
+ *
+ * Examples derived from stdnum-js test suite.
+ */
+const tin: Validator = {
+  name: "Belize Tax Identification Number",
+  localName: "Tax Identification Number",
+  abbreviation: "TIN",
+  aliases: ["TIN"] as const,
+  candidatePattern: "\\d{6}",
+  country: "BZ",
+  entityType: "any",
+  lengths: [6, 8] as const,
+  examples: ["000005", "00000510", "00000513"] as const,
+  compact,
+  format,
+  validate,
+  description:
+    "Belize tax number issued by the Belize Tax Service Department",
+  sourceUrl:
+    "https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Belize-TIN.pdf",
+};
+
+export default tin;
+export { compact, format, validate };

package/src/ca/bn.ts

@@ -0,0 +1,107 @@
+/**
+ * BN (Canadian Business Number).
+ *
+ * 9-digit BN root (Luhn checksum) optionally
+ * followed by a 2-letter program type (RC, RM,
+ * RP, RT) and a 4-digit reference number (BN15).
+ *
+ * @see https://www.canada.ca/en/services/taxes/business-number.html
+ */
+
+import {
+  luhnValidate,
+  luhnChecksum,
+} from "#checksums/luhn";
+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 VALID_PROGRAMS = new Set(["RC", "RM", "RP", "RT"]);
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9 && v.length !== 15) {
+    return err(
+      "INVALID_LENGTH",
+      "BN must be 9 or 15 characters",
+    );
+  }
+  if (!isdigits(v.slice(0, 9))) {
+    return err(
+      "INVALID_FORMAT",
+      "BN root must contain only digits",
+    );
+  }
+  if (!luhnValidate(v.slice(0, 9))) {
+    return err(
+      "INVALID_CHECKSUM",
+      "BN Luhn check digit mismatch",
+    );
+  }
+  if (v.length === 15) {
+    const program = v.slice(9, 11);
+    if (!VALID_PROGRAMS.has(program)) {
+      return err(
+        "INVALID_COMPONENT",
+        "BN program type must be RC, RM, RP, or RT",
+      );
+    }
+    if (!isdigits(v.slice(11))) {
+      return err(
+        "INVALID_FORMAT",
+        "BN reference number must be digits",
+      );
+    }
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length === 15) {
+    return `${v.slice(0, 3)} ${v.slice(3, 6)} ${v.slice(6, 9)} ${v.slice(9, 11)} ${v.slice(11)}`;
+  }
+  if (v.length === 9) {
+    return `${v.slice(0, 3)} ${v.slice(3, 6)} ${v.slice(6)}`;
+  }
+  return v;
+};
+
+/** Generate a random valid Canadian BN. */
+const generate = (): string => {
+  const payload = randomDigits(8);
+  const cs = luhnChecksum(payload + "0");
+  return payload + String((10 - cs) % 10);
+};
+
+/** Canadian Business Number. */
+const bn: Validator = {
+  name: "Business Number",
+  localName: "Business Number",
+  abbreviation: "BN",
+  aliases: [
+    "BN",
+    "Business Number",
+    "numéro d'entreprise",
+  ] as const,
+  candidatePattern: "\\d{9}\\s?[A-Z]{2}\\s?\\d{4}",
+  country: "CA",
+  entityType: "company",
+  sourceUrl:
+    "https://www.canada.ca/en/services/taxes/business-number.html",
+  examples: ["123026635", "123026635RC0001"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default bn;
+export { compact, format, validate, generate };

package/src/ca/mod.ts

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