@gusnips/br 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Salomé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @gusnips/br
+
+Checks and formats Brazilian documents and phone numbers: CPF, CNPJ, phones and CEP. The same
+code runs on a server, in a browser and in React Native. No dependencies.
+
+```ts
+import { isValidCnpj } from "@gusnips/br";
+
+isValidCnpj("12.ABC.345/01DE-35"); // true
+```
+
+## CPF and CNPJ
+
+```ts
+import { formatCnpj, isValidCpf, maskDocument } from "@gusnips/br";
+
+isValidCpf("111.444.777-35"); // true
+formatCnpj("12abc34501de35"); // "12.ABC.345/01DE-35"
+maskDocument("1114447"); // "111.444.7", for a field as somebody types
+```
+
+**Since July 2026 a new CNPJ can have letters.** The first twelve characters can be A-Z as well as
+digits. The last two, the check digits, are still numbers. `isValidCnpj`, `formatCnpj` and
+`maskCnpj` accept both kinds. A checker that strips letters before it checks turns these CNPJs down,
+so a company registered this year can't sign up.
+
+Three kinds of function, and they do different jobs:
+
+- `formatCpf` and `formatCnpj` display a **complete** value. They add back the leading zeros a
+  number column drops (`1144477735` becomes `011.444.777-35`), and anything that isn't a document
+  comes back unchanged.
+- `maskCpf`, `maskCnpj` and `maskDocument` format **partial** input as it is typed, and never pad.
+  `maskDocument` switches from CPF to CNPJ after 11 digits, or at the first letter.
+- `isValidCpf` and `isValidCnpj` check the check digits. A value made of one repeated digit is always
+  refused, because the arithmetic alone would accept it.
+
+`classifyDocument` answers "is this a CPF or a CNPJ?" by shape alone, without checking the digits.
+Government datasets contain test CPFs whose check digits fail, and those are still people.
+
+`cpfCheckDigits` and `cnpjCheckDigits` compute the last two digits from the rest. Use them to build a
+valid document in a test, or to complete a head office's CNPJ from its 8-character root:
+`root + "0001"` plus the two digits.
+
+## Phones
+
+```ts
+import { brMobileVariants, formatBrPhone, toE164Br } from "@gusnips/br";
+
+toE164Br("(11) 98765-4321"); // "+5511987654321"
+formatBrPhone("5511987654321"); // "(11) 98765-4321"
+brMobileVariants("5511987654321"); // ["5511987654321", "551187654321"]
+```
+
+`parseBrPhone` reads a number however it was written: with or without `+55`, with punctuation, or
+with the trunk `0` people dial between cities. It returns `null` for anything it can't read. It
+checks the area code against the 67 in use, and it refuses a subscriber made of one repeated digit,
+like `99999-9999`.
+
+**Brazilian numbers only, on purpose.** A general phone library that reads bare digits guesses the
+country from the first few, and for a Brazilian mobile typed without `+55` it often guesses wrong:
+area code 31 reads as the Netherlands and 81 as Japan. If you also take foreign numbers, send the
+ones that start with `+` and aren't `+55` to an international library, and send the rest here.
+
+`55` is both the country code and an area code (Rio Grande do Sul), so length decides first. Eleven
+digits starting with 55 are a mobile in area 55. Only a 12- or 13-digit number carries the country
+code.
+
+`brMobileVariants` gives both forms a mobile may be registered under on WhatsApp: with the ninth
+digit and without it. An account created before the ninth digit existed can still use the short
+form. Look up both. Pass it an international number, so run `toE164Br` on user input first. Guessing
+that bare digits are Brazilian is how a foreign number gets matched to somebody else.
+
+## CEP
+
+```ts
+import { formatCep, normalizeCep } from "@gusnips/br";
+
+formatCep("01310100"); // "01310-100"
+normalizeCep("01310-100"); // "01310100", or null when it isn't eight digits
+```
+
+Looking a CEP up is a network call to a provider you choose, so it isn't here. A real CEP can also
+cover a whole small town with no street name, so a lookup that finds no street doesn't mean the CEP
+is wrong.
+
+## Not here
+
+- **Error messages.** Every function returns a boolean, a string or `null`. The sentence the reader
+  sees belongs in your own translations:
+  `isValidCpf(value) ? undefined : t("errors.cpfInvalid")`.
+- **zod.** Wrapping a check is one line, `z.string().refine(isValidCpf)`, and the message is yours.

package/dist/cep.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CEP, the Brazilian postal code: eight digits, shown as `01310-100`.
+ *
+ * Only the shape lives here. Looking a CEP up is a network call to a provider you choose, and a
+ * CEP can be real and still have no street — a whole small town can share one — so "the lookup
+ * found no street" is not "this CEP is invalid".
+ */
+/** The eight digits, or `null` when there are not eight. */
+export declare function normalizeCep(value: string): string | null;
+/** `01310-100`. Anything that is not eight digits comes back as it was. */
+export declare function formatCep(value: string): string;
+/** Formats a CEP as it is typed. Stops at eight digits. */
+export declare function maskCep(partial: string): string;
+//# sourceMappingURL=cep.d.ts.map

package/dist/cep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cep.d.ts","sourceRoot":"","sources":["../src/cep.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGzD;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED,2DAA2D;AAC3D,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG/C"}

package/dist/cep.js

@@ -0,0 +1,23 @@
+/**
+ * CEP, the Brazilian postal code: eight digits, shown as `01310-100`.
+ *
+ * Only the shape lives here. Looking a CEP up is a network call to a provider you choose, and a
+ * CEP can be real and still have no street — a whole small town can share one — so "the lookup
+ * found no street" is not "this CEP is invalid".
+ */
+/** The eight digits, or `null` when there are not eight. */
+export function normalizeCep(value) {
+    const digits = value.replace(/\D/g, "");
+    return digits.length === 8 ? digits : null;
+}
+/** `01310-100`. Anything that is not eight digits comes back as it was. */
+export function formatCep(value) {
+    const digits = normalizeCep(value);
+    return digits === null ? value : `${digits.slice(0, 5)}-${digits.slice(5)}`;
+}
+/** Formats a CEP as it is typed. Stops at eight digits. */
+export function maskCep(partial) {
+    const d = partial.replace(/\D/g, "").slice(0, 8);
+    return d.length <= 5 ? d : `${d.slice(0, 5)}-${d.slice(5)}`;
+}
+//# sourceMappingURL=cep.js.map

package/dist/cep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cep.js","sourceRoot":"","sources":["../src/cep.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4DAA4D;AAC5D,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9D,CAAC"}

package/dist/document.d.ts

@@ -0,0 +1,60 @@
+/**
+ * CPF and CNPJ: check digits, display, input masks.
+ *
+ * Three concerns sit side by side here, and the adopters that merged them kept them apart for a
+ * reason: a DISPLAY formatter works on a complete value and zero-pads it, a MASK formats partial
+ * input as somebody types and never pads, and a VALIDATOR says whether the check digits hold.
+ *
+ * The CNPJ is alphanumeric from July 2026 (Receita Federal, IN RFB 2.229/2024): the first twelve
+ * characters may be A-Z as well as digits, and the two check digits stay numeric. Every copy this
+ * package replaced stripped letters before it checked, so a company registered under the new
+ * format was refused everywhere — and one display formatter turned `12.ABC.345/01DE-35` into a
+ * different, numeric CNPJ. The check digits are the same mod-11 over the same weights, with each
+ * character counting as its ASCII code minus 48, so a digit counts as itself and `A` as 17.
+ */
+export type DocumentKind = "cpf" | "cnpj";
+/**
+ * Which document this is, by SHAPE only: 11 digits is a CPF, 14 CNPJ characters is a CNPJ.
+ *
+ * Deliberately not a validity check. Government datasets carry test CPFs that fail the check digit,
+ * and an adopter reading those has to know "this is a person" without calling the record invalid —
+ * keep "what is it" and "does it check" as two questions.
+ */
+export declare function classifyDocument(value: string): DocumentKind | null;
+/** The two check digits for the first nine digits of a CPF. */
+export declare function cpfCheckDigits(base9: string): string;
+/** The two check digits for the first twelve characters of a CNPJ, numeric or alphanumeric. */
+export declare function cnpjCheckDigits(base12: string): string;
+/** Whether a CPF's check digits hold. Formatted or bare. Eleven repeated digits never pass. */
+export declare function isValidCpf(value: string): boolean;
+/** Whether a CNPJ's check digits hold — numeric or alphanumeric, formatted or bare. */
+export declare function isValidCnpj(value: string): boolean;
+/**
+ * A complete CPF for display: `123.456.789-09`.
+ *
+ * Zero-pads, because government datasets store it as a number and drop the leading zeros. Anything
+ * that is not a CPF comes back as it was, so a bad row shows as itself rather than as "".
+ */
+export declare function formatCpf(value: string): string;
+/**
+ * A complete CNPJ for display: `12.345.678/0001-95` or `12.ABC.345/01DE-35`.
+ *
+ * Zero-pads a numeric value for the same reason {@link formatCpf} does. An alphanumeric one cannot
+ * have lost a zero to a number column, so it is never padded. Anything else comes back as it was.
+ */
+export declare function formatCnpj(value: string): string;
+/** A CPF for display with its middle hidden: `123.***.***-09`. Anything else comes back as it was. */
+export declare function redactCpf(value: string): string;
+/** Formats a CPF as it is typed. Never pads; stops at 11 digits. */
+export declare function maskCpf(partial: string): string;
+/**
+ * Formats a CNPJ as it is typed, letters included. Never pads; stops at 14 characters, and the last
+ * two only take digits, because the check digits stay numeric.
+ */
+export declare function maskCnpj(partial: string): string;
+/**
+ * One field for either document: a CPF mask up to 11 digits, a CNPJ mask past that — or as soon as
+ * a letter is typed, since only a CNPJ can carry one.
+ */
+export declare function maskDocument(partial: string): string;
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,CAAC;AAY1C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAGnE;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWpD;AAED,+FAA+F;AAC/F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAetD;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKjD;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKlD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED,sGAAsG;AACtG,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED,oEAAoE;AACpE,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/document.js

@@ -0,0 +1,155 @@
+/**
+ * CPF and CNPJ: check digits, display, input masks.
+ *
+ * Three concerns sit side by side here, and the adopters that merged them kept them apart for a
+ * reason: a DISPLAY formatter works on a complete value and zero-pads it, a MASK formats partial
+ * input as somebody types and never pads, and a VALIDATOR says whether the check digits hold.
+ *
+ * The CNPJ is alphanumeric from July 2026 (Receita Federal, IN RFB 2.229/2024): the first twelve
+ * characters may be A-Z as well as digits, and the two check digits stay numeric. Every copy this
+ * package replaced stripped letters before it checked, so a company registered under the new
+ * format was refused everywhere — and one display formatter turned `12.ABC.345/01DE-35` into a
+ * different, numeric CNPJ. The check digits are the same mod-11 over the same weights, with each
+ * character counting as its ASCII code minus 48, so a digit counts as itself and `A` as 17.
+ */
+/** Digits only. A CPF is numeric and stays numeric, so a pasted label or letter is noise. */
+function cpfCharacters(value) {
+    return value.replace(/\D/g, "");
+}
+/** Digits and A-Z, uppercased — the characters a CNPJ can hold. */
+function cnpjCharacters(value) {
+    return value.toUpperCase().replace(/[^0-9A-Z]/g, "");
+}
+/**
+ * Which document this is, by SHAPE only: 11 digits is a CPF, 14 CNPJ characters is a CNPJ.
+ *
+ * Deliberately not a validity check. Government datasets carry test CPFs that fail the check digit,
+ * and an adopter reading those has to know "this is a person" without calling the record invalid —
+ * keep "what is it" and "does it check" as two questions.
+ */
+export function classifyDocument(value) {
+    if (cpfCharacters(value).length === 11 && !/[A-Za-z]/.test(value))
+        return "cpf";
+    return /^[0-9A-Z]{12}\d{2}$/.test(cnpjCharacters(value)) ? "cnpj" : null;
+}
+/** The two check digits for the first nine digits of a CPF. */
+export function cpfCheckDigits(base9) {
+    const digits = cpfCharacters(base9);
+    if (digits.length !== 9)
+        throw new RangeError("A CPF base is 9 digits.");
+    const next = (source) => {
+        let sum = 0;
+        for (let i = 0; i < source.length; i++)
+            sum += Number(source[i]) * (source.length + 1 - i);
+        const rest = (sum * 10) % 11;
+        return rest === 10 ? 0 : rest;
+    };
+    const first = next(digits);
+    return `${first}${next(`${digits}${first}`)}`;
+}
+/** The two check digits for the first twelve characters of a CNPJ, numeric or alphanumeric. */
+export function cnpjCheckDigits(base12) {
+    const chars = cnpjCharacters(base12);
+    if (!/^[0-9A-Z]{12}$/.test(chars))
+        throw new RangeError("A CNPJ base is 12 characters.");
+    const next = (source) => {
+        let sum = 0;
+        // The weights run 2, 3 … 9 from the RIGHT and wrap, which is the 5→2, 9→2 walk read backwards.
+        for (let i = 0; i < source.length; i++) {
+            const weight = ((source.length - 1 - i) % 8) + 2;
+            sum += (source.charCodeAt(i) - 48) * weight;
+        }
+        const rest = sum % 11;
+        return rest < 2 ? 0 : 11 - rest;
+    };
+    const first = next(chars);
+    return `${first}${next(`${chars}${first}`)}`;
+}
+/** Whether a CPF's check digits hold. Formatted or bare. Eleven repeated digits never pass. */
+export function isValidCpf(value) {
+    const digits = cpfCharacters(value);
+    if (digits.length !== 11 || /[A-Za-z]/.test(value))
+        return false;
+    if (/^(\d)\1{10}$/.test(digits))
+        return false;
+    return cpfCheckDigits(digits.slice(0, 9)) === digits.slice(9);
+}
+/** Whether a CNPJ's check digits hold — numeric or alphanumeric, formatted or bare. */
+export function isValidCnpj(value) {
+    const chars = cnpjCharacters(value);
+    if (!/^[0-9A-Z]{12}\d{2}$/.test(chars))
+        return false;
+    if (/^(.)\1{13}$/.test(chars))
+        return false;
+    return cnpjCheckDigits(chars.slice(0, 12)) === chars.slice(12);
+}
+/**
+ * A complete CPF for display: `123.456.789-09`.
+ *
+ * Zero-pads, because government datasets store it as a number and drop the leading zeros. Anything
+ * that is not a CPF comes back as it was, so a bad row shows as itself rather than as "".
+ */
+export function formatCpf(value) {
+    const digits = cpfCharacters(value);
+    if (digits.length === 0 || digits.length > 11 || /[A-Za-z]/.test(value))
+        return value;
+    return digits.padStart(11, "0").replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, "$1.$2.$3-$4");
+}
+/**
+ * A complete CNPJ for display: `12.345.678/0001-95` or `12.ABC.345/01DE-35`.
+ *
+ * Zero-pads a numeric value for the same reason {@link formatCpf} does. An alphanumeric one cannot
+ * have lost a zero to a number column, so it is never padded. Anything else comes back as it was.
+ */
+export function formatCnpj(value) {
+    let chars = cnpjCharacters(value);
+    if (/^\d{1,13}$/.test(chars))
+        chars = chars.padStart(14, "0");
+    if (!/^[0-9A-Z]{12}\d{2}$/.test(chars))
+        return value;
+    return `${chars.slice(0, 2)}.${chars.slice(2, 5)}.${chars.slice(5, 8)}/${chars.slice(8, 12)}-${chars.slice(12)}`;
+}
+/** A CPF for display with its middle hidden: `123.***.***-09`. Anything else comes back as it was. */
+export function redactCpf(value) {
+    const digits = cpfCharacters(value);
+    if (digits.length !== 11 || /[A-Za-z]/.test(value))
+        return value;
+    return `${digits.slice(0, 3)}.***.***-${digits.slice(9)}`;
+}
+/** Formats a CPF as it is typed. Never pads; stops at 11 digits. */
+export function maskCpf(partial) {
+    const d = cpfCharacters(partial).slice(0, 11);
+    if (d.length <= 3)
+        return d;
+    if (d.length <= 6)
+        return `${d.slice(0, 3)}.${d.slice(3)}`;
+    if (d.length <= 9)
+        return `${d.slice(0, 3)}.${d.slice(3, 6)}.${d.slice(6)}`;
+    return `${d.slice(0, 3)}.${d.slice(3, 6)}.${d.slice(6, 9)}-${d.slice(9)}`;
+}
+/**
+ * Formats a CNPJ as it is typed, letters included. Never pads; stops at 14 characters, and the last
+ * two only take digits, because the check digits stay numeric.
+ */
+export function maskCnpj(partial) {
+    const all = cnpjCharacters(partial);
+    const c = all.slice(0, 12) + all.slice(12).replace(/\D/g, "").slice(0, 2);
+    if (c.length <= 2)
+        return c;
+    if (c.length <= 5)
+        return `${c.slice(0, 2)}.${c.slice(2)}`;
+    if (c.length <= 8)
+        return `${c.slice(0, 2)}.${c.slice(2, 5)}.${c.slice(5)}`;
+    if (c.length <= 12)
+        return `${c.slice(0, 2)}.${c.slice(2, 5)}.${c.slice(5, 8)}/${c.slice(8)}`;
+    return `${c.slice(0, 2)}.${c.slice(2, 5)}.${c.slice(5, 8)}/${c.slice(8, 12)}-${c.slice(12)}`;
+}
+/**
+ * One field for either document: a CPF mask up to 11 digits, a CNPJ mask past that — or as soon as
+ * a letter is typed, since only a CNPJ can carry one.
+ */
+export function maskDocument(partial) {
+    const chars = cnpjCharacters(partial);
+    return chars.length <= 11 && /^\d*$/.test(chars) ? maskCpf(chars) : maskCnpj(chars);
+}
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { classifyDocument, cnpjCheckDigits, cpfCheckDigits, formatCnpj, formatCpf, isValidCnpj, isValidCpf, maskCnpj, maskCpf, maskDocument, redactCpf, } from "./document.ts";
+export type { DocumentKind } from "./document.ts";
+export { brMobileVariants, formatBrPhone, isValidBrPhone, maskBrPhone, parseBrPhone, toE164Br, } from "./phone.ts";
+export type { BrPhone } from "./phone.ts";
+export { formatCep, maskCep, normalizeCep } from "./cep.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,YAAY,EACZ,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,WAAW,EACX,YAAY,EACZ,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { classifyDocument, cnpjCheckDigits, cpfCheckDigits, formatCnpj, formatCpf, isValidCnpj, isValidCpf, maskCnpj, maskCpf, maskDocument, redactCpf, } from "./document.js";
+export { brMobileVariants, formatBrPhone, isValidBrPhone, maskBrPhone, parseBrPhone, toE164Br, } from "./phone.js";
+export { formatCep, maskCep, normalizeCep } from "./cep.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,YAAY,EACZ,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,WAAW,EACX,YAAY,EACZ,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/phone.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Brazilian phone numbers: read, check, format, and the two forms of an older mobile.
+ *
+ * Brazilian only, on purpose. A number that is not Brazilian comes back as `null`, never as a
+ * guess: a general parser reading bare digits guesses a country from the first ones, and for a
+ * Brazilian mobile typed without `+55` that guess is wrong often — area code 31 reads as the
+ * Netherlands and 81 as Japan. If you take international numbers too, send the ones that start
+ * with `+` and are not `+55` to a real international library, and keep this for the rest.
+ */
+export interface BrPhone {
+    /** The two-digit area code. */
+    ddd: string;
+    /** Everything after it: nine digits for a mobile, eight for a landline. */
+    subscriber: string;
+    kind: "mobile" | "landline";
+}
+/**
+ * Reads a Brazilian number in whatever shape a person or a system wrote it — `(11) 98765-4321`,
+ * `+55 11 98765-4321`, `5511987654321`, `011 3456-7890` — or returns `null`.
+ *
+ * **Length decides before the prefix does**, because `55` is ambiguous: it is the country code and
+ * also a DDD (Rio Grande do Sul). Eleven digits starting with 55 are a gaúcho mobile, not a country
+ * code in front of nine digits; only 12 or 13 digits carry the country. The copy that tested the
+ * prefix first also left every São Paulo-state mobile (DDDs 11-19) without its `55`, because it
+ * read an 11-digit number starting with 1 as North American.
+ *
+ * Strict about what it accepts: a real DDD; a mobile is nine digits starting with 9 (every mobile
+ * has had the ninth digit since 2016); a landline is eight starting with 2-5; and a subscriber of
+ * one repeated digit is a placeholder somebody typed to get past a form.
+ */
+export declare function parseBrPhone(input: string): BrPhone | null;
+/** Whether {@link parseBrPhone} reads it. */
+export declare function isValidBrPhone(input: string): boolean;
+/** `+5511987654321`, or `null` when it is not a Brazilian number. Drop the `+` for WhatsApp. */
+export declare function toE164Br(input: string): string | null;
+/** `(11) 98765-4321` or `(11) 3456-7890`. Anything it cannot read comes back as it was. */
+export declare function formatBrPhone(input: string): string;
+/**
+ * Formats a number as it is typed: `(41) 98822-9199`. Stops at 11 digits, the longest DDD plus
+ * mobile, because a longer string would render as a broken Brazilian number rather than a
+ * readable foreign one.
+ */
+export declare function maskBrPhone(partial: string): string;
+/**
+ * Both forms a Brazilian mobile may be registered under, the given one first: with the ninth
+ * digit and without it. Anything else comes back alone.
+ *
+ * An account created before the ninth digit can still be registered without it, and WhatsApp no
+ * longer reliably bridges the two, so a lookup that tries one form misses the person — or opens a
+ * second conversation with somebody already in one. Which form an account uses cannot be known
+ * from the number, so this gives candidates to look up, never a rewrite.
+ *
+ * Takes an INTERNATIONAL number (`5511987654321`, `+55 11 98765-4321`), not a bare national one:
+ * guessing that ten or eleven bare digits are Brazilian is exactly how a foreign number gets a
+ * "twin" that belongs to somebody else. Use {@link toE164Br} first for user input.
+ */
+export declare function brMobileVariants(international: string): string[];
+//# sourceMappingURL=phone.d.ts.map

package/dist/phone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phone.d.ts","sourceRoot":"","sources":["../src/phone.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,MAAM,WAAW,OAAO;IACtB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAuB1D;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrD;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,CAchE"}

package/dist/phone.js

@@ -0,0 +1,122 @@
+/**
+ * Brazilian phone numbers: read, check, format, and the two forms of an older mobile.
+ *
+ * Brazilian only, on purpose. A number that is not Brazilian comes back as `null`, never as a
+ * guess: a general parser reading bare digits guesses a country from the first ones, and for a
+ * Brazilian mobile typed without `+55` that guess is wrong often — area code 31 reads as the
+ * Netherlands and 81 as Japan. If you take international numbers too, send the ones that start
+ * with `+` and are not `+55` to a real international library, and keep this for the rest.
+ */
+/**
+ * The 67 area codes (DDD) in use. Anything else — 00, 20, 23, 30, 90 — is a typo or a placeholder,
+ * never a number somebody can answer.
+ */
+const AREA_CODES = new Set("11 12 13 14 15 16 17 18 19 21 22 24 27 28 31 32 33 34 35 37 38 41 42 43 44 45 46 47 48 49 51 53 54 55 61 62 63 64 65 66 67 68 69 71 73 74 75 77 79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96 97 98 99".split(" "));
+/**
+ * Reads a Brazilian number in whatever shape a person or a system wrote it — `(11) 98765-4321`,
+ * `+55 11 98765-4321`, `5511987654321`, `011 3456-7890` — or returns `null`.
+ *
+ * **Length decides before the prefix does**, because `55` is ambiguous: it is the country code and
+ * also a DDD (Rio Grande do Sul). Eleven digits starting with 55 are a gaúcho mobile, not a country
+ * code in front of nine digits; only 12 or 13 digits carry the country. The copy that tested the
+ * prefix first also left every São Paulo-state mobile (DDDs 11-19) without its `55`, because it
+ * read an 11-digit number starting with 1 as North American.
+ *
+ * Strict about what it accepts: a real DDD; a mobile is nine digits starting with 9 (every mobile
+ * has had the ninth digit since 2016); a landline is eight starting with 2-5; and a subscriber of
+ * one repeated digit is a placeholder somebody typed to get past a form.
+ */
+export function parseBrPhone(input) {
+    const trimmed = input.trim();
+    let digits = trimmed.replace(/\D/g, "");
+    if (trimmed.startsWith("+")) {
+        // A number written with + says its country, and only +55 is ours.
+        if (!digits.startsWith("55"))
+            return null;
+        digits = digits.slice(2);
+    }
+    else if (digits.startsWith("0") && (digits.length === 11 || digits.length === 12)) {
+        // The trunk 0 people dial between cities. No DDD starts with 0, so this cannot be anything else.
+        // ponytail: the carrier code form (0 + 2-digit carrier + DDD) is not read; it comes back null.
+        digits = digits.slice(1);
+    }
+    else if (digits.length === 12 || digits.length === 13) {
+        if (!digits.startsWith("55"))
+            return null;
+        digits = digits.slice(2);
+    }
+    if (digits.length !== 10 && digits.length !== 11)
+        return null;
+    const ddd = digits.slice(0, 2);
+    const subscriber = digits.slice(2);
+    if (!AREA_CODES.has(ddd) || /^(\d)\1+$/.test(subscriber))
+        return null;
+    if (subscriber.length === 9)
+        return subscriber.startsWith("9") ? { ddd, subscriber, kind: "mobile" } : null;
+    return /^[2-5]/.test(subscriber) ? { ddd, subscriber, kind: "landline" } : null;
+}
+/** Whether {@link parseBrPhone} reads it. */
+export function isValidBrPhone(input) {
+    return parseBrPhone(input) !== null;
+}
+/** `+5511987654321`, or `null` when it is not a Brazilian number. Drop the `+` for WhatsApp. */
+export function toE164Br(input) {
+    const phone = parseBrPhone(input);
+    return phone === null ? null : `+55${phone.ddd}${phone.subscriber}`;
+}
+/** `(11) 98765-4321` or `(11) 3456-7890`. Anything it cannot read comes back as it was. */
+export function formatBrPhone(input) {
+    const phone = parseBrPhone(input);
+    if (phone === null)
+        return input;
+    const { ddd, subscriber } = phone;
+    return `(${ddd}) ${subscriber.slice(0, -4)}-${subscriber.slice(-4)}`;
+}
+/**
+ * Formats a number as it is typed: `(41) 98822-9199`. Stops at 11 digits, the longest DDD plus
+ * mobile, because a longer string would render as a broken Brazilian number rather than a
+ * readable foreign one.
+ */
+export function maskBrPhone(partial) {
+    const d = partial.replace(/\D/g, "").slice(0, 11);
+    if (d.length === 0)
+        return "";
+    if (d.length <= 2)
+        return `(${d}`;
+    if (d.length <= 6)
+        return `(${d.slice(0, 2)}) ${d.slice(2)}`;
+    if (d.length <= 10)
+        return `(${d.slice(0, 2)}) ${d.slice(2, 6)}-${d.slice(6)}`;
+    return `(${d.slice(0, 2)}) ${d.slice(2, 7)}-${d.slice(7)}`;
+}
+/**
+ * Both forms a Brazilian mobile may be registered under, the given one first: with the ninth
+ * digit and without it. Anything else comes back alone.
+ *
+ * An account created before the ninth digit can still be registered without it, and WhatsApp no
+ * longer reliably bridges the two, so a lookup that tries one form misses the person — or opens a
+ * second conversation with somebody already in one. Which form an account uses cannot be known
+ * from the number, so this gives candidates to look up, never a rewrite.
+ *
+ * Takes an INTERNATIONAL number (`5511987654321`, `+55 11 98765-4321`), not a bare national one:
+ * guessing that ten or eleven bare digits are Brazilian is exactly how a foreign number gets a
+ * "twin" that belongs to somebody else. Use {@link toE164Br} first for user input.
+ */
+export function brMobileVariants(international) {
+    const digits = international.replace(/\D/g, "");
+    const match = /^55(\d{2})(\d{8,9})$/.exec(digits);
+    if (match === null)
+        return [digits];
+    const [, ddd = "", subscriber = ""] = match;
+    if (!AREA_CODES.has(ddd))
+        return [digits];
+    if (subscriber.length === 9 && subscriber.startsWith("9")) {
+        return [digits, `55${ddd}${subscriber.slice(1)}`];
+    }
+    // Eight digits starting 6-9 is a mobile from before the ninth digit; 2-5 is a landline, which
+    // never had one.
+    if (subscriber.length === 8 && /^[6-9]/.test(subscriber))
+        return [digits, `55${ddd}9${subscriber}`];
+    return [digits];
+}
+//# sourceMappingURL=phone.js.map

package/dist/phone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phone.js","sourceRoot":"","sources":["../src/phone.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@gusnips/br",
+  "version": "0.1.0",
+  "description": "Brazilian documents and phone numbers: CPF and CNPJ (the alphanumeric CNPJ too), phones, CEP. Check digits, display, input masks. Zero dependencies, no framework.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Gustavo Salomé",
+  "homepage": "https://github.com/gusnips/frontkit/tree/main/br#readme",
+  "bugs": {
+    "url": "https://github.com/gusnips/frontkit/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "brazil",
+    "cpf",
+    "cnpj",
+    "cep",
+    "phone",
+    "validation",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "sync:docs": "cp ../LICENSE .",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build && bun run sync:docs",
+    "release:patch": "bun pm version patch && bun publish --access public",
+    "release:minor": "bun pm version minor && bun publish --access public",
+    "release:major": "bun pm version major && bun publish --access public"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gusnips/frontkit.git",
+    "directory": "br"
+  }
+}

package/src/cep.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { formatCep, maskCep, normalizeCep } from "./cep.ts";
+
+describe("CEP", () => {
+  it("reads eight digits in any punctuation", () => {
+    expect(normalizeCep("01310-100")).toBe("01310100");
+    expect(normalizeCep("01.310-100")).toBe("01310100");
+    expect(normalizeCep("1310100")).toBe(null);
+  });
+
+  it("formats a complete one and leaves the rest alone", () => {
+    expect(formatCep("01310100")).toBe("01310-100");
+    expect(formatCep("1310100")).toBe("1310100");
+  });
+
+  it("masks as it is typed", () => {
+    expect(["013", "01310", "013101", "0131010099"].map(maskCep)).toEqual([
+      "013",
+      "01310",
+      "01310-1",
+      "01310-100",
+    ]);
+  });
+});

package/src/cep.ts

@@ -0,0 +1,25 @@
+/**
+ * CEP, the Brazilian postal code: eight digits, shown as `01310-100`.
+ *
+ * Only the shape lives here. Looking a CEP up is a network call to a provider you choose, and a
+ * CEP can be real and still have no street — a whole small town can share one — so "the lookup
+ * found no street" is not "this CEP is invalid".
+ */
+
+/** The eight digits, or `null` when there are not eight. */
+export function normalizeCep(value: string): string | null {
+  const digits = value.replace(/\D/g, "");
+  return digits.length === 8 ? digits : null;
+}
+
+/** `01310-100`. Anything that is not eight digits comes back as it was. */
+export function formatCep(value: string): string {
+  const digits = normalizeCep(value);
+  return digits === null ? value : `${digits.slice(0, 5)}-${digits.slice(5)}`;
+}
+
+/** Formats a CEP as it is typed. Stops at eight digits. */
+export function maskCep(partial: string): string {
+  const d = partial.replace(/\D/g, "").slice(0, 8);
+  return d.length <= 5 ? d : `${d.slice(0, 5)}-${d.slice(5)}`;
+}

package/src/document.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import {
+  classifyDocument,
+  cnpjCheckDigits,
+  cpfCheckDigits,
+  formatCnpj,
+  formatCpf,
+  isValidCnpj,
+  isValidCpf,
+  maskCnpj,
+  maskCpf,
+  maskDocument,
+  redactCpf,
+} from "./document.ts";
+
+// The Receita Federal's own example of the alphanumeric format.
+const ALPHANUMERIC = "12.ABC.345/01DE-35";
+
+describe("CPF", () => {
+  it("accepts real check digits, formatted or bare", () => {
+    expect(isValidCpf("111.444.777-35")).toBe(true);
+    expect(isValidCpf("52998224725")).toBe(true);
+    expect(cpfCheckDigits("111444777")).toBe("35");
+  });
+
+  it("refuses a wrong digit, a wrong length, a letter, and one repeated digit", () => {
+    expect(isValidCpf("111.444.777-36")).toBe(false);
+    expect(isValidCpf("1114447773")).toBe(false);
+    expect(isValidCpf("111.444.777-3A5")).toBe(false);
+    // Every repeated digit passes the arithmetic, which is why it is refused on its own.
+    for (let d = 0; d <= 9; d++) expect(isValidCpf(String(d).repeat(11))).toBe(false);
+  });
+
+  it("zero-pads for display, because datasets store it as a number", () => {
+    expect(formatCpf("1144477735")).toBe("011.444.777-35");
+    expect(formatCpf("not a cpf")).toBe("not a cpf");
+    expect(redactCpf("111.444.777-35")).toBe("111.***.***-35");
+  });
+
+  it("masks as it is typed, without padding", () => {
+    expect(["1", "1114", "1114447", "1114447773", "111444777356"].map(maskCpf)).toEqual([
+      "1",
+      "111.4",
+      "111.444.7",
+      "111.444.777-3",
+      "111.444.777-35",
+    ]);
+  });
+});
+
+describe("CNPJ", () => {
+  it("checks the alphanumeric CNPJ that every copy it replaces refused", () => {
+    expect(isValidCnpj(ALPHANUMERIC)).toBe(true);
+    expect(isValidCnpj("12abc34501de35")).toBe(true);
+    expect(cnpjCheckDigits("12ABC34501DE")).toBe("35");
+    expect(isValidCnpj("12.ABC.345/01DE-36")).toBe(false);
+    // The check digits stay numeric.
+    expect(isValidCnpj("12.ABC.345/01DE-3A")).toBe(false);
+  });
+
+  it("checks a numeric CNPJ the way it always did", () => {
+    expect(isValidCnpj("11.222.333/0001-81")).toBe(true);
+    expect(isValidCnpj("11222333000182")).toBe(false);
+    for (let d = 0; d <= 9; d++) expect(isValidCnpj(String(d).repeat(14))).toBe(false);
+  });
+
+  // An independent derivation of the numeric weights — the left-to-right 5→2, 9→2 walk the old
+  // copies used — so a mistake in the right-to-left formula cannot agree with itself.
+  it("agrees with the classic numeric walk on 2,000 random bases", () => {
+    const classic = (base: string): string => {
+      const next = (s: string): number => {
+        let sum = 0;
+        let weight = s.length === 12 ? 5 : 6;
+        for (const c of s) {
+          sum += Number(c) * weight;
+          weight = weight === 2 ? 9 : weight - 1;
+        }
+        return sum % 11 < 2 ? 0 : 11 - (sum % 11);
+      };
+      const first = next(base);
+      return `${first}${next(base + first)}`;
+    };
+    for (let i = 0; i < 2000; i++) {
+      const base = Array.from({ length: 12 }, () => Math.floor(Math.random() * 10)).join("");
+      expect(cnpjCheckDigits(base)).toBe(classic(base));
+    }
+  });
+
+  it("keeps the letters when it formats, and pads only a numeric value", () => {
+    // One copy stripped the letters here and displayed a different, numeric CNPJ.
+    expect(formatCnpj("12abc34501de35")).toBe(ALPHANUMERIC);
+    expect(formatCnpj("1222333000181")).toBe("01.222.333/0001-81");
+    expect(formatCnpj("nope")).toBe("nope");
+  });
+
+  it("masks letters as they are typed and keeps the last two numeric", () => {
+    expect(maskCnpj("12abc")).toBe("12.ABC");
+    expect(maskCnpj("12ABC34501DE")).toBe("12.ABC.345/01DE");
+    expect(maskCnpj("12ABC34501DEX3")).toBe("12.ABC.345/01DE-3");
+    expect(maskCnpj("12ABC34501DE35999")).toBe(ALPHANUMERIC);
+  });
+});
+
+describe("either document", () => {
+  it("classifies by shape, not by check digits", () => {
+    // A dataset's test CPF fails the check digit and is still a person.
+    expect(classifyDocument("111.444.777-00")).toBe("cpf");
+    expect(classifyDocument(ALPHANUMERIC)).toBe("cnpj");
+    expect(classifyDocument("11.222.333/0001-81")).toBe("cnpj");
+    expect(classifyDocument("123")).toBe(null);
+  });
+
+  it("switches from the CPF mask to the CNPJ mask past 11 digits, or at the first letter", () => {
+    expect(maskDocument("11144477735")).toBe("111.444.777-35");
+    expect(maskDocument("112223330001")).toBe("11.222.333/0001");
+    expect(maskDocument("12A")).toBe("12.A");
+  });
+});

package/src/document.ts

@@ -0,0 +1,150 @@
+/**
+ * CPF and CNPJ: check digits, display, input masks.
+ *
+ * Three concerns sit side by side here, and the adopters that merged them kept them apart for a
+ * reason: a DISPLAY formatter works on a complete value and zero-pads it, a MASK formats partial
+ * input as somebody types and never pads, and a VALIDATOR says whether the check digits hold.
+ *
+ * The CNPJ is alphanumeric from July 2026 (Receita Federal, IN RFB 2.229/2024): the first twelve
+ * characters may be A-Z as well as digits, and the two check digits stay numeric. Every copy this
+ * package replaced stripped letters before it checked, so a company registered under the new
+ * format was refused everywhere — and one display formatter turned `12.ABC.345/01DE-35` into a
+ * different, numeric CNPJ. The check digits are the same mod-11 over the same weights, with each
+ * character counting as its ASCII code minus 48, so a digit counts as itself and `A` as 17.
+ */
+
+export type DocumentKind = "cpf" | "cnpj";
+
+/** Digits only. A CPF is numeric and stays numeric, so a pasted label or letter is noise. */
+function cpfCharacters(value: string): string {
+  return value.replace(/\D/g, "");
+}
+
+/** Digits and A-Z, uppercased — the characters a CNPJ can hold. */
+function cnpjCharacters(value: string): string {
+  return value.toUpperCase().replace(/[^0-9A-Z]/g, "");
+}
+
+/**
+ * Which document this is, by SHAPE only: 11 digits is a CPF, 14 CNPJ characters is a CNPJ.
+ *
+ * Deliberately not a validity check. Government datasets carry test CPFs that fail the check digit,
+ * and an adopter reading those has to know "this is a person" without calling the record invalid —
+ * keep "what is it" and "does it check" as two questions.
+ */
+export function classifyDocument(value: string): DocumentKind | null {
+  if (cpfCharacters(value).length === 11 && !/[A-Za-z]/.test(value)) return "cpf";
+  return /^[0-9A-Z]{12}\d{2}$/.test(cnpjCharacters(value)) ? "cnpj" : null;
+}
+
+/** The two check digits for the first nine digits of a CPF. */
+export function cpfCheckDigits(base9: string): string {
+  const digits = cpfCharacters(base9);
+  if (digits.length !== 9) throw new RangeError("A CPF base is 9 digits.");
+  const next = (source: string): number => {
+    let sum = 0;
+    for (let i = 0; i < source.length; i++) sum += Number(source[i]) * (source.length + 1 - i);
+    const rest = (sum * 10) % 11;
+    return rest === 10 ? 0 : rest;
+  };
+  const first = next(digits);
+  return `${first}${next(`${digits}${first}`)}`;
+}
+
+/** The two check digits for the first twelve characters of a CNPJ, numeric or alphanumeric. */
+export function cnpjCheckDigits(base12: string): string {
+  const chars = cnpjCharacters(base12);
+  if (!/^[0-9A-Z]{12}$/.test(chars)) throw new RangeError("A CNPJ base is 12 characters.");
+  const next = (source: string): number => {
+    let sum = 0;
+    // The weights run 2, 3 … 9 from the RIGHT and wrap, which is the 5→2, 9→2 walk read backwards.
+    for (let i = 0; i < source.length; i++) {
+      const weight = ((source.length - 1 - i) % 8) + 2;
+      sum += (source.charCodeAt(i) - 48) * weight;
+    }
+    const rest = sum % 11;
+    return rest < 2 ? 0 : 11 - rest;
+  };
+  const first = next(chars);
+  return `${first}${next(`${chars}${first}`)}`;
+}
+
+/** Whether a CPF's check digits hold. Formatted or bare. Eleven repeated digits never pass. */
+export function isValidCpf(value: string): boolean {
+  const digits = cpfCharacters(value);
+  if (digits.length !== 11 || /[A-Za-z]/.test(value)) return false;
+  if (/^(\d)\1{10}$/.test(digits)) return false;
+  return cpfCheckDigits(digits.slice(0, 9)) === digits.slice(9);
+}
+
+/** Whether a CNPJ's check digits hold — numeric or alphanumeric, formatted or bare. */
+export function isValidCnpj(value: string): boolean {
+  const chars = cnpjCharacters(value);
+  if (!/^[0-9A-Z]{12}\d{2}$/.test(chars)) return false;
+  if (/^(.)\1{13}$/.test(chars)) return false;
+  return cnpjCheckDigits(chars.slice(0, 12)) === chars.slice(12);
+}
+
+/**
+ * A complete CPF for display: `123.456.789-09`.
+ *
+ * Zero-pads, because government datasets store it as a number and drop the leading zeros. Anything
+ * that is not a CPF comes back as it was, so a bad row shows as itself rather than as "".
+ */
+export function formatCpf(value: string): string {
+  const digits = cpfCharacters(value);
+  if (digits.length === 0 || digits.length > 11 || /[A-Za-z]/.test(value)) return value;
+  return digits.padStart(11, "0").replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, "$1.$2.$3-$4");
+}
+
+/**
+ * A complete CNPJ for display: `12.345.678/0001-95` or `12.ABC.345/01DE-35`.
+ *
+ * Zero-pads a numeric value for the same reason {@link formatCpf} does. An alphanumeric one cannot
+ * have lost a zero to a number column, so it is never padded. Anything else comes back as it was.
+ */
+export function formatCnpj(value: string): string {
+  let chars = cnpjCharacters(value);
+  if (/^\d{1,13}$/.test(chars)) chars = chars.padStart(14, "0");
+  if (!/^[0-9A-Z]{12}\d{2}$/.test(chars)) return value;
+  return `${chars.slice(0, 2)}.${chars.slice(2, 5)}.${chars.slice(5, 8)}/${chars.slice(8, 12)}-${chars.slice(12)}`;
+}
+
+/** A CPF for display with its middle hidden: `123.***.***-09`. Anything else comes back as it was. */
+export function redactCpf(value: string): string {
+  const digits = cpfCharacters(value);
+  if (digits.length !== 11 || /[A-Za-z]/.test(value)) return value;
+  return `${digits.slice(0, 3)}.***.***-${digits.slice(9)}`;
+}
+
+/** Formats a CPF as it is typed. Never pads; stops at 11 digits. */
+export function maskCpf(partial: string): string {
+  const d = cpfCharacters(partial).slice(0, 11);
+  if (d.length <= 3) return d;
+  if (d.length <= 6) return `${d.slice(0, 3)}.${d.slice(3)}`;
+  if (d.length <= 9) return `${d.slice(0, 3)}.${d.slice(3, 6)}.${d.slice(6)}`;
+  return `${d.slice(0, 3)}.${d.slice(3, 6)}.${d.slice(6, 9)}-${d.slice(9)}`;
+}
+
+/**
+ * Formats a CNPJ as it is typed, letters included. Never pads; stops at 14 characters, and the last
+ * two only take digits, because the check digits stay numeric.
+ */
+export function maskCnpj(partial: string): string {
+  const all = cnpjCharacters(partial);
+  const c = all.slice(0, 12) + all.slice(12).replace(/\D/g, "").slice(0, 2);
+  if (c.length <= 2) return c;
+  if (c.length <= 5) return `${c.slice(0, 2)}.${c.slice(2)}`;
+  if (c.length <= 8) return `${c.slice(0, 2)}.${c.slice(2, 5)}.${c.slice(5)}`;
+  if (c.length <= 12) return `${c.slice(0, 2)}.${c.slice(2, 5)}.${c.slice(5, 8)}/${c.slice(8)}`;
+  return `${c.slice(0, 2)}.${c.slice(2, 5)}.${c.slice(5, 8)}/${c.slice(8, 12)}-${c.slice(12)}`;
+}
+
+/**
+ * One field for either document: a CPF mask up to 11 digits, a CNPJ mask past that — or as soon as
+ * a letter is typed, since only a CNPJ can carry one.
+ */
+export function maskDocument(partial: string): string {
+  const chars = cnpjCharacters(partial);
+  return chars.length <= 11 && /^\d*$/.test(chars) ? maskCpf(chars) : maskCnpj(chars);
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+export {
+  classifyDocument,
+  cnpjCheckDigits,
+  cpfCheckDigits,
+  formatCnpj,
+  formatCpf,
+  isValidCnpj,
+  isValidCpf,
+  maskCnpj,
+  maskCpf,
+  maskDocument,
+  redactCpf,
+} from "./document.ts";
+export type { DocumentKind } from "./document.ts";
+export {
+  brMobileVariants,
+  formatBrPhone,
+  isValidBrPhone,
+  maskBrPhone,
+  parseBrPhone,
+  toE164Br,
+} from "./phone.ts";
+export type { BrPhone } from "./phone.ts";
+export { formatCep, maskCep, normalizeCep } from "./cep.ts";

package/src/phone.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import {
+  brMobileVariants,
+  formatBrPhone,
+  isValidBrPhone,
+  maskBrPhone,
+  parseBrPhone,
+  toE164Br,
+} from "./phone.ts";
+
+describe("parseBrPhone", () => {
+  it("reads a number in every shape it gets written in", () => {
+    for (const input of [
+      "(11) 98765-4321",
+      "11987654321",
+      "5511987654321",
+      "+55 11 98765-4321",
+      "011 98765-4321",
+    ]) {
+      expect(toE164Br(input)).toBe("+5511987654321");
+    }
+    expect(parseBrPhone("(11) 3456-7890")).toEqual({
+      ddd: "11",
+      subscriber: "34567890",
+      kind: "landline",
+    });
+  });
+
+  // One copy tested an 11-digit number starting with 1 as North American before it tested for
+  // Brazil, so every mobile in DDDs 11-19 was stored without its 55 and inbound lookups missed.
+  it("keeps São Paulo-state mobiles Brazilian", () => {
+    for (let ddd = 11; ddd <= 19; ddd++) {
+      expect(toE164Br(`${ddd}987654321`)).toBe(`+55${ddd}987654321`);
+    }
+  });
+
+  // 55 is the country code AND a DDD. Length decides first.
+  it("reads 11 digits starting with 55 as DDD 55, and 13 as the country code", () => {
+    expect(toE164Br("55987654321")).toBe("+5555987654321");
+    expect(toE164Br("5555987654321")).toBe("+5555987654321");
+    expect(toE164Br("5534567890")).toBe("+555534567890");
+  });
+
+  // A general parser guessed a country from bare digits: 31 became the Netherlands, 81 Japan.
+  it("never guesses a foreign country", () => {
+    expect(toE164Br("31987654321")).toBe("+5531987654321");
+    expect(toE164Br("81987654321")).toBe("+5581987654321");
+    expect(parseBrPhone("+1 415 555 0100")).toBe(null);
+    expect(parseBrPhone("+351 912 345 678")).toBe(null);
+    expect(parseBrPhone("14155550100")).toBe(null);
+  });
+
+  it("refuses what nobody can answer", () => {
+    expect(isValidBrPhone("(20) 98765-4321")).toBe(false); // no such DDD
+    expect(isValidBrPhone("(11) 99999-9999")).toBe(false); // a placeholder
+    expect(isValidBrPhone("(31) 61234-5678")).toBe(false); // nine digits, not a mobile
+    expect(isValidBrPhone("(11) 8765-4321")).toBe(false); // a mobile from before the ninth digit
+    expect(isValidBrPhone("12345")).toBe(false);
+  });
+});
+
+describe("display", () => {
+  it("formats what it can read and leaves the rest alone", () => {
+    expect(formatBrPhone("5511987654321")).toBe("(11) 98765-4321");
+    expect(formatBrPhone("1134567890")).toBe("(11) 3456-7890");
+    expect(formatBrPhone("+1 415 555 0100")).toBe("+1 415 555 0100");
+  });
+
+  it("masks as it is typed", () => {
+    expect(
+      ["4", "41", "41988", "4198822919", "41988229199", "419882291990"].map(maskBrPhone),
+    ).toEqual(["(4", "(41", "(41) 988", "(41) 9882-2919", "(41) 98822-9199", "(41) 98822-9199"]);
+  });
+});
+
+describe("brMobileVariants", () => {
+  it("gives both forms of a mobile, the given one first", () => {
+    expect(brMobileVariants("5511987654321")).toEqual(["5511987654321", "551187654321"]);
+    expect(brMobileVariants("+55 11 8765-4321")).toEqual(["551187654321", "5511987654321"]);
+  });
+
+  it("gives a landline, a foreign number and an unknown DDD alone", () => {
+    expect(brMobileVariants("551134567890")).toEqual(["551134567890"]);
+    expect(brMobileVariants("14155550100")).toEqual(["14155550100"]);
+    expect(brMobileVariants("5520987654321")).toEqual(["5520987654321"]);
+  });
+
+  // Guessing that bare digits are Brazilian is how a foreign number got a twin that belongs to
+  // someone else.
+  it("does not treat a bare national number as international", () => {
+    expect(brMobileVariants("11987654321")).toEqual(["11987654321"]);
+  });
+});

package/src/phone.ts

@@ -0,0 +1,128 @@
+/**
+ * Brazilian phone numbers: read, check, format, and the two forms of an older mobile.
+ *
+ * Brazilian only, on purpose. A number that is not Brazilian comes back as `null`, never as a
+ * guess: a general parser reading bare digits guesses a country from the first ones, and for a
+ * Brazilian mobile typed without `+55` that guess is wrong often — area code 31 reads as the
+ * Netherlands and 81 as Japan. If you take international numbers too, send the ones that start
+ * with `+` and are not `+55` to a real international library, and keep this for the rest.
+ */
+
+/**
+ * The 67 area codes (DDD) in use. Anything else — 00, 20, 23, 30, 90 — is a typo or a placeholder,
+ * never a number somebody can answer.
+ */
+const AREA_CODES = new Set(
+  "11 12 13 14 15 16 17 18 19 21 22 24 27 28 31 32 33 34 35 37 38 41 42 43 44 45 46 47 48 49 51 53 54 55 61 62 63 64 65 66 67 68 69 71 73 74 75 77 79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96 97 98 99".split(
+    " ",
+  ),
+);
+
+export interface BrPhone {
+  /** The two-digit area code. */
+  ddd: string;
+  /** Everything after it: nine digits for a mobile, eight for a landline. */
+  subscriber: string;
+  kind: "mobile" | "landline";
+}
+
+/**
+ * Reads a Brazilian number in whatever shape a person or a system wrote it — `(11) 98765-4321`,
+ * `+55 11 98765-4321`, `5511987654321`, `011 3456-7890` — or returns `null`.
+ *
+ * **Length decides before the prefix does**, because `55` is ambiguous: it is the country code and
+ * also a DDD (Rio Grande do Sul). Eleven digits starting with 55 are a gaúcho mobile, not a country
+ * code in front of nine digits; only 12 or 13 digits carry the country. The copy that tested the
+ * prefix first also left every São Paulo-state mobile (DDDs 11-19) without its `55`, because it
+ * read an 11-digit number starting with 1 as North American.
+ *
+ * Strict about what it accepts: a real DDD; a mobile is nine digits starting with 9 (every mobile
+ * has had the ninth digit since 2016); a landline is eight starting with 2-5; and a subscriber of
+ * one repeated digit is a placeholder somebody typed to get past a form.
+ */
+export function parseBrPhone(input: string): BrPhone | null {
+  const trimmed = input.trim();
+  let digits = trimmed.replace(/\D/g, "");
+  if (trimmed.startsWith("+")) {
+    // A number written with + says its country, and only +55 is ours.
+    if (!digits.startsWith("55")) return null;
+    digits = digits.slice(2);
+  } else if (digits.startsWith("0") && (digits.length === 11 || digits.length === 12)) {
+    // The trunk 0 people dial between cities. No DDD starts with 0, so this cannot be anything else.
+    // ponytail: the carrier code form (0 + 2-digit carrier + DDD) is not read; it comes back null.
+    digits = digits.slice(1);
+  } else if (digits.length === 12 || digits.length === 13) {
+    if (!digits.startsWith("55")) return null;
+    digits = digits.slice(2);
+  }
+  if (digits.length !== 10 && digits.length !== 11) return null;
+
+  const ddd = digits.slice(0, 2);
+  const subscriber = digits.slice(2);
+  if (!AREA_CODES.has(ddd) || /^(\d)\1+$/.test(subscriber)) return null;
+  if (subscriber.length === 9)
+    return subscriber.startsWith("9") ? { ddd, subscriber, kind: "mobile" } : null;
+  return /^[2-5]/.test(subscriber) ? { ddd, subscriber, kind: "landline" } : null;
+}
+
+/** Whether {@link parseBrPhone} reads it. */
+export function isValidBrPhone(input: string): boolean {
+  return parseBrPhone(input) !== null;
+}
+
+/** `+5511987654321`, or `null` when it is not a Brazilian number. Drop the `+` for WhatsApp. */
+export function toE164Br(input: string): string | null {
+  const phone = parseBrPhone(input);
+  return phone === null ? null : `+55${phone.ddd}${phone.subscriber}`;
+}
+
+/** `(11) 98765-4321` or `(11) 3456-7890`. Anything it cannot read comes back as it was. */
+export function formatBrPhone(input: string): string {
+  const phone = parseBrPhone(input);
+  if (phone === null) return input;
+  const { ddd, subscriber } = phone;
+  return `(${ddd}) ${subscriber.slice(0, -4)}-${subscriber.slice(-4)}`;
+}
+
+/**
+ * Formats a number as it is typed: `(41) 98822-9199`. Stops at 11 digits, the longest DDD plus
+ * mobile, because a longer string would render as a broken Brazilian number rather than a
+ * readable foreign one.
+ */
+export function maskBrPhone(partial: string): string {
+  const d = partial.replace(/\D/g, "").slice(0, 11);
+  if (d.length === 0) return "";
+  if (d.length <= 2) return `(${d}`;
+  if (d.length <= 6) return `(${d.slice(0, 2)}) ${d.slice(2)}`;
+  if (d.length <= 10) return `(${d.slice(0, 2)}) ${d.slice(2, 6)}-${d.slice(6)}`;
+  return `(${d.slice(0, 2)}) ${d.slice(2, 7)}-${d.slice(7)}`;
+}
+
+/**
+ * Both forms a Brazilian mobile may be registered under, the given one first: with the ninth
+ * digit and without it. Anything else comes back alone.
+ *
+ * An account created before the ninth digit can still be registered without it, and WhatsApp no
+ * longer reliably bridges the two, so a lookup that tries one form misses the person — or opens a
+ * second conversation with somebody already in one. Which form an account uses cannot be known
+ * from the number, so this gives candidates to look up, never a rewrite.
+ *
+ * Takes an INTERNATIONAL number (`5511987654321`, `+55 11 98765-4321`), not a bare national one:
+ * guessing that ten or eleven bare digits are Brazilian is exactly how a foreign number gets a
+ * "twin" that belongs to somebody else. Use {@link toE164Br} first for user input.
+ */
+export function brMobileVariants(international: string): string[] {
+  const digits = international.replace(/\D/g, "");
+  const match = /^55(\d{2})(\d{8,9})$/.exec(digits);
+  if (match === null) return [digits];
+  const [, ddd = "", subscriber = ""] = match;
+  if (!AREA_CODES.has(ddd)) return [digits];
+  if (subscriber.length === 9 && subscriber.startsWith("9")) {
+    return [digits, `55${ddd}${subscriber.slice(1)}`];
+  }
+  // Eight digits starting 6-9 is a mobile from before the ninth digit; 2-5 is a landline, which
+  // never had one.
+  if (subscriber.length === 8 && /^[6-9]/.test(subscriber))
+    return [digits, `55${ddd}9${subscriber}`];
+  return [digits];
+}