validation-br 2.0.0-next-10 → 2.0.0-next-11

package/dist/cjs/_helpers/expiration-factor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ExpirationFactor
+ * Converte entre o fator de vencimento do boleto bancário e a data que ele representa
+ *
+ * @doc
+ * O fator de vencimento é a quantidade de dias corridos entre uma data-base e o
+ * vencimento do boleto, representado em 4 dígitos (0000 a 9999). "0000" indica
+ * que o boleto não tem vencimento definido.
+ *
+ * Esse intervalo de 4 dígitos, contado a partir de 07/10/1997, esgotou em
+ * 21/02/2025 e, a partir de 22/02/2025, a Febraban reiniciou a contagem em
+ * 1000, usando 29/05/2022 como nova data-base. Como o fator sozinho não indica
+ * de qual era ele é, usamos 6000 como corte: fatores menores indicam a era
+ * nova (válida até 31/10/2038) e fatores maiores ou iguais indicam a era
+ * antiga (válida até 21/02/2025, quando ela se esgotou).
+ *
+ * Nota para o futuro: quando a era nova se esgotar (por volta de 2038), a
+ * data-base usada abaixo deixa de ser válida e um novo corte precisará ser
+ * calculado.
+ *
+ * Fonte: http://portalabbc.org.br/images/content/manual%20operacional.pdf
+ */
+export declare class ExpirationFactor {
+    private static readonly oldEraBaseDate;
+    private static readonly newEraBaseDate;
+    private static readonly newEraStartDate;
+    private static readonly newEraThreshold;
+    /**
+     * Converte o fator de vencimento em data. "0000" representa um boleto sem
+     * vencimento definido.
+     */
+    static toDate(factor: string): Date | null;
+    /**
+     * Converte uma data no fator de vencimento equivalente, escolhendo a era
+     * (ver acima) a partir da própria data: a era antiga só é usada para datas
+     * até 21/02/2025, quando ela se esgotou.
+     */
+    static fromDate(date: Date): string;
+}

package/dist/cjs/_helpers/expiration-factor.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExpirationFactor = void 0;
+/**
+ * ExpirationFactor
+ * Converte entre o fator de vencimento do boleto bancário e a data que ele representa
+ *
+ * @doc
+ * O fator de vencimento é a quantidade de dias corridos entre uma data-base e o
+ * vencimento do boleto, representado em 4 dígitos (0000 a 9999). "0000" indica
+ * que o boleto não tem vencimento definido.
+ *
+ * Esse intervalo de 4 dígitos, contado a partir de 07/10/1997, esgotou em
+ * 21/02/2025 e, a partir de 22/02/2025, a Febraban reiniciou a contagem em
+ * 1000, usando 29/05/2022 como nova data-base. Como o fator sozinho não indica
+ * de qual era ele é, usamos 6000 como corte: fatores menores indicam a era
+ * nova (válida até 31/10/2038) e fatores maiores ou iguais indicam a era
+ * antiga (válida até 21/02/2025, quando ela se esgotou).
+ *
+ * Nota para o futuro: quando a era nova se esgotar (por volta de 2038), a
+ * data-base usada abaixo deixa de ser válida e um novo corte precisará ser
+ * calculado.
+ *
+ * Fonte: http://portalabbc.org.br/images/content/manual%20operacional.pdf
+ */
+class ExpirationFactor {
+    /**
+     * Converte o fator de vencimento em data. "0000" representa um boleto sem
+     * vencimento definido.
+     */
+    static toDate(factor) {
+        if (factor === '0000')
+            return null;
+        const baseDate = factor < ExpirationFactor.newEraThreshold
+            ? ExpirationFactor.newEraBaseDate
+            : ExpirationFactor.oldEraBaseDate;
+        const msByDay = 1000 * 60 * 60 * 24;
+        const baseDays = baseDate.getTime() / msByDay;
+        return new Date((+factor + baseDays) * msByDay);
+    }
+    /**
+     * Converte uma data no fator de vencimento equivalente, escolhendo a era
+     * (ver acima) a partir da própria data: a era antiga só é usada para datas
+     * até 21/02/2025, quando ela se esgotou.
+     */
+    static fromDate(date) {
+        const baseDate = date < ExpirationFactor.newEraStartDate
+            ? ExpirationFactor.oldEraBaseDate
+            : ExpirationFactor.newEraBaseDate;
+        const msByDay = 1000 * 60 * 60 * 24;
+        const days = Math.round(date.getTime() / msByDay - baseDate.getTime() / msByDay);
+        return String(days).padStart(4, '0').slice(-4);
+    }
+}
+exports.ExpirationFactor = ExpirationFactor;
+ExpirationFactor.oldEraBaseDate = new Date('1997-10-07');
+ExpirationFactor.newEraBaseDate = new Date('2022-05-29');
+ExpirationFactor.newEraStartDate = new Date('2025-02-22');
+ExpirationFactor.newEraThreshold = '6000';

package/dist/cjs/_helpers/random.js

@@ -41,7 +41,10 @@ class Random {
     static number(length, forceLength = false, isAlpha = false) {
         let value;
         if (isAlpha)
-            value = Math.round(Math.random() * 36 ** length)
+            // Math.floor (não Math.round) é essencial aqui: Math.random() nunca atinge 1, mas
+            // arredondar para cima pode levar o valor a 36 ** length exatamente, que em base 36
+            // vira '1' seguido de `length` zeros — um caractere a mais do que o esperado.
+            value = Math.floor(Math.random() * 36 ** length)
                 .toString(36)
                 .toLocaleUpperCase();
         else

package/dist/cjs/_helpers/utils.d.ts

@@ -6,7 +6,7 @@
  * @param {Integer} sum Soma
  * @returns {Integer}
  */
-export declare function sumToDV(sum: number): number;
+export declare function sumToDV(sum: number, restException?: 0 | 1): number;
 /**
  * Checa se o número repassado possui todos os digitos iguais
  *

package/dist/cjs/_helpers/utils.js

@@ -15,8 +15,8 @@ const ValidationBRError_1 = require("../_exceptions/ValidationBRError");
  * @param {Integer} sum Soma
  * @returns {Integer}
  */
-function sumToDV(sum) {
-    return sum % 11 < 2 ? 0 : 11 - (sum % 11);
+function sumToDV(sum, restException = 0) {
+    return sum % 11 < 2 ? restException : 11 - (sum % 11);
 }
 /**
  * Checa se o número repassado possui todos os digitos iguais

package/dist/cjs/base.d.ts

@@ -5,17 +5,17 @@ export declare abstract class Base {
      *
      */
     protected abstract _mask: string | null;
-    constructor(_value: string, fakeFn?: Function);
+    constructor(_value: string);
     get value(): string;
     toString(): string;
     /**
      * Deve remover apenas pontos e traços.
      */
-    protected abstract normalize(options?: any): void;
+    protected abstract normalize(options?: unknown): void;
     /**
      * Deve aplicar as regras de validação do dígito verificador do documento
      */
-    protected abstract validate(options?: any): boolean;
+    protected abstract validate(options?: unknown): boolean;
     /**
      * Deve devolver o número com a máscara
      */
@@ -25,9 +25,9 @@ export declare abstract class Base {
      * Calcula o dígito verificador de um número SEM o dígito incluído
      *
      */
-    static checksum(value: string): string | null;
+    static checksum(_value: string): string | null;
     /**
      * Deve gerar um número fake no padrão
      */
-    static fake(options?: any): any;
+    static fake(_options?: unknown): unknown;
 }

package/dist/cjs/base.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Base = void 0;
 const mask_1 = require("./_helpers/mask");
 class Base {
-    constructor(_value, fakeFn) {
+    constructor(_value) {
         this._value = _value;
     }
     get value() {
@@ -35,15 +35,14 @@ class Base {
      * Calcula o dígito verificador de um número SEM o dígito incluído
      *
      */
-    static checksum(value) {
+    static checksum(_value) {
         throw new Error('Should implement on child');
     }
     /**
      * Deve gerar um número fake no padrão
      */
-    static fake(options) {
+    static fake(_options) {
         throw new Error('Should implement on child');
-        // Base.fakeFn(options)
     }
 }
 exports.Base = Base;

package/dist/cjs/boleto.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Boleto
+ * Calcula, converte e mascara boletos bancários (linha digitável e código de barras)
+ *
+ * @doc
+ * O boleto bancário possui duas representações: o código de barras, com 44 dígitos,
+ * e a linha digitável, com 47 dígitos, que reorganiza o código de barras em 5 campos,
+ * 3 deles com um dígito verificador próprio (Módulo 10).
+ *
+ * Exemplo usado nos cálculos abaixo:
+ * Banco 001, moeda 9, fator de vencimento 9636, valor R$ 1.234,00 e campo livre
+ * "1234567890123456789012345".
+ *
+ * 1) Partes do código de barras (44 dígitos)
+ *  _____ ________ ______ ________________ ____________ ___________________________
+ * | Bco | Moeda  |  DV  | Fator vencto.  |    Valor    |        Campo livre        |
+ * | 001 |   9    |  1   |     9636       | 0000123400  | 1234567890123456789012345 |
+ * |_____|________|______|________________|_____________|___________________________|
+ *
+ * - Banco (3): código do banco emissor.
+ * - Moeda (1): sempre "9" (Real).
+ * - DV geral (1): dígito verificador Módulo 11, calculado no passo 2 abaixo.
+ * - Fator de vencimento (4): quantidade de dias corridos desde 07/10/1997. "0000" quando
+ *   o boleto não tem vencimento definido.
+ * - Valor (10): valor do boleto em centavos.
+ * - Campo livre (25): definido livremente por cada banco (agência, conta, nosso número
+ *   etc.), sem um padrão único entre eles. Por isso este validador não tenta decompor
+ *   esse trecho, apenas o mantém disponível como está.
+ *
+ * 2) Cálculo do DV geral (Módulo 11)
+ *
+ *  - Soma-se o produto dos 43 dígitos do código de barras SEM o DV geral (banco + moeda
+ *    + fator de vencimento + valor + campo livre) por pesos de 2 a 9, cíclicos, aplicados
+ *    da direita para a esquerda.
+ *
+ *    0  0  1  9  9  6  3  6  0  0  0  0  1  2  3  4  0  0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
+ *    x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x  x
+ *    4  3  2  9  8  7  6  5  4  3  2  9  8  7  6  5  4  3  2  9  8  7  6  5  4  3  2  9  8  7  6  5  4  3  2  9  8  7  6  5  4  3  2
+ *
+ *    Soma = 813
+ *
+ *  - O somatório encontrado é dividido por 11. O DV geral é 11 subtraído do resto da divisão.
+ *    813 / 11 tem resto 10. 11 - 10 = 1. DV geral é 1.
+ *    Obs.: Caso o cálculo do DV retorne 0, 10 ou 11, o resultado será 1.
+ *
+ * 3) Partes da linha digitável (47 dígitos), a partir do mesmo exemplo
+ *  ____________ _____________ _____________ _ ______________
+ * | Campo 1    |  Campo 2    |  Campo 3    |4|   Campo 5    |
+ * | 00191.23454| 67890.123457| 67890.123457|1|96360000123400|
+ * |____________|_____________|_____________|_|______________|
+ *
+ * - Campo 1 (10): banco (3) + moeda (1) + 5 primeiros dígitos do campo livre (5) + DV1
+ * - Campo 2 (11): dígitos 6 a 15 do campo livre (10) + DV2
+ * - Campo 3 (11): dígitos 16 a 25 do campo livre (10) + DV3
+ * - Campo 4 (1): DV geral, o mesmo calculado no passo 2
+ * - Campo 5 (14): fator de vencimento (4) + valor (10)
+ *
+ * 4) Cálculo do DV de cada campo da linha digitável (Módulo 10)
+ *
+ *  - Soma-se o produto dos dígitos do campo (sem o seu DV) por pesos alternados 2 e 1,
+ *    da direita para a esquerda. Quando o produto é maior que 9, somam-se os dois
+ *    algarismos do resultado (ex.: 5 x 2 = 10, que vira 1 + 0 = 1).
+ *
+ *    Campo 1 (001912345):
+ *
+ *    0   0   1   9   1   2   3   4   5
+ *    x   x   x   x   x   x   x   x   x
+ *    2   1   2   1   2   1   2   1   2
+ *  = 0  +0  +2  +9  +2  +2  +6  +4  +1 = 26
+ *
+ *  - O somatório encontrado é dividido por 10. O DV é 10 menos o resto da divisão.
+ *    26 / 10 tem resto 6. 10 - 6 = 4. DV1 é 4.
+ *    Obs.: Caso o resto seja 0, o DV será 0.
+ *
+ *  - O mesmo cálculo se aplica aos campos 2 e 3, usando os 10 dígitos de cada um.
+ *
+ * Fonte: Febraban - Layout do código de barras de cobrança
+ *
+ * @param {String} value Linha digitável (47) ou código de barras (44)
+ * @returns {Boolean}
+ */
+import { Base } from './base';
+export declare class Boleto extends Base {
+    protected _value: string;
+    protected _mask: string;
+    private static readonly generalChecksumWeights;
+    private _bank;
+    private _generalChecksum;
+    private _expirationFactor;
+    private _amount;
+    private _freeField;
+    constructor(_value: string);
+    /**
+     * Cria um Boleto a partir de um código de barras (44 dígitos).
+     * Equivalente a chamar o construtor diretamente, mas deixa a intenção explícita.
+     */
+    static fromBarcode(barcode: string): Boleto;
+    /**
+     * Código do banco emissor
+     */
+    get bank(): string;
+    /**
+     * Valor do boleto, em reais
+     */
+    get amount(): number;
+    /**
+     * Data de vencimento, ou null se o boleto não tiver vencimento definido
+     */
+    get expiresAt(): Date | null;
+    /**
+     * Campo livre (25 dígitos), definido livremente por cada banco.
+     * Não é decomposto por este validador por não seguir um padrão único.
+     */
+    get freeField(): string;
+    protected normalize(): void;
+    /**
+     * validate()
+     * Identifica se o valor é uma linha digitável (47) ou um código de barras (44)
+     * e delega para a validação específica de cada formato.
+     */
+    protected validate(): boolean;
+    /**
+     * Valida um código de barras (44 dígitos): recalcula o DV geral (Módulo 11)
+     * sobre os outros 43 dígitos e compara com o DV informado.
+     */
+    private validateBarcode;
+    /**
+     * Valida uma linha digitável (47 dígitos): recalcula o DV (Módulo 10) de cada
+     * um dos 3 campos e, a partir deles, o DV geral (Módulo 11), comparando ambos
+     * com os dígitos informados.
+     */
+    private validateLinhaDigitavel;
+    /**
+     * Preenche os campos comuns a partir do valor já validado, convertendo para
+     * o código de barras quando o valor recebido for uma linha digitável.
+     */
+    private parse;
+    /**
+     * Devolve sempre o código de barras (44 dígitos), independentemente do
+     * formato recebido no construtor.
+     */
+    toBarcode(): string;
+    /**
+     * Devolve sempre a linha digitável (47 dígitos, sem máscara), independentemente
+     * do formato recebido no construtor.
+     */
+    toString(): string;
+    /**
+     * Devolve a linha digitável mascarada, no formato
+     * 00000.00000 00000.000000 00000.000000 0 00000000000000
+     */
+    mask(): string;
+    /**
+     * checksum()
+     * Calcula o DV geral (Módulo 11) a partir dos 43 dígitos do código de
+     * barras SEM o DV geral (banco + moeda + fator de vencimento + valor + campo livre)
+     */
+    static checksum(value: string): string;
+    /**
+     * Gera um boleto fake válido
+     */
+    static fake(options?: Partial<FakeBoletoOptions>): Boleto;
+    /**
+     * Converte uma linha digitável (47) no código de barras (44) equivalente.
+     */
+    private static linhaDigitavelToBarcode;
+    /**
+     * Converte um código de barras (44) na linha digitável (47) equivalente,
+     * calculando o DV (Módulo 10) de cada um dos 3 campos.
+     */
+    private static barcodeToLinhaDigitavel;
+    /**
+     * Módulo 10: usado no DV de cada campo da linha digitável.
+     */
+    private static calculateModulo10;
+}
+interface FakeBoletoOptions {
+    bank: string;
+    amount: number;
+    expiresAt: Date;
+}
+export {};