tempest-react-sdk 0.35.0 → 0.36.0

package/dist/br.d.ts

@@ -3,6 +3,162 @@ import { JSX } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 
+/**
+ * Move a date by a number of working days.
+ *
+ * `n` days forward means `n` calls to {@link nextBusinessDay}; a negative `n`
+ * walks backwards the same way. `n === 0` returns the day unchanged **even when it
+ * is not a working day** — snapping silently would hide the case a caller most
+ * needs to see.
+ *
+ * @param date - `YYYY-MM-DD` or a `Date`.
+ * @param days - Working days to add. May be negative.
+ * @param options - See {@link BusinessDayOptions}.
+ * @returns Local midnight of the resulting day.
+ * @throws {RangeError} On a malformed input, or on a calendar with no working days.
+ *
+ * @example
+ * addBusinessDays("2026-04-01", 2); // 2026-04-06 — skips Good Friday and the weekend
+ */
+export declare function addBusinessDays(date: DateInput, days: number, options?: BusinessDayOptions): Date;
+
+/** What the two parsers return. Narrow on `kind`. */
+export declare type Boleto = BoletoBanco | BoletoArrecadacao;
+
+/** An arrecadação/convênio slip — utilities, taxes, traffic fines. */
+export declare interface BoletoArrecadacao {
+    kind: "arrecadacao";
+    /** 44 digits, always starting with `8`. */
+    codigoBarras: string;
+    /** 48 digits, in four blocks of twelve. */
+    linhaDigitavel: string;
+    /** Position 2. See {@link segmentoLabel}. */
+    segmento: number;
+    /** Human label, or `null` for a value the layout does not define. */
+    segmentoLabel: string | null;
+    /** Position 3: `6`/`8` mean real money, `7`/`9` mean a reference quantity. */
+    identificacaoValor: number;
+    /** Which modulo position 3 selects for the general check digit. */
+    dvModulo: 10 | 11;
+    /** The general check digit, position 4. */
+    dv: string;
+    /** Reais, or `null` when position 3 says the field is a reference, not money. */
+    valor: number | null;
+    /** The raw 11-digit value field, useful when {@link valor} is `null`. */
+    valorRaw: string;
+    /**
+     * Positions 16-19 — the 4-digit code FEBRABAN assigns the company — or, on
+     * segmento 6, positions 16-23, which are the first eight CNPJ digits.
+     */
+    empresa: string;
+    /** `true` when {@link empresa} is a CNPJ prefix rather than a FEBRABAN code. */
+    empresaIsCnpj: boolean;
+    /** 25 digits, or 21 when the CNPJ took four of them. Issuer-defined. */
+    campoLivre: string;
+    /**
+     * Due date read from the first eight digits of the campo livre.
+     *
+     * The layout says a due date, **if present**, must sit there as `AAAAMMDD` —
+     * but the field is optional and nothing marks its presence, so a campo livre
+     * that merely looks like a date lands here too. Treat it as a hint for a UI,
+     * never as the date a payment settles against.
+     */
+    vencimentoCampoLivre: Date | null;
+}
+
+/** A cobrança boleto — the kind a bank issues against an invoice. */
+export declare interface BoletoBanco {
+    kind: "banco";
+    /** 44 digits. */
+    codigoBarras: string;
+    /** 47 digits. */
+    linhaDigitavel: string;
+    /** 3-digit bank code in the clearing house, e.g. `"341"`. */
+    banco: string;
+    /** 1 digit. `"9"` is BRL; nothing else is in use. */
+    moeda: string;
+    /** `"Real"` for `"9"`, `null` for anything else. */
+    moedaLabel: string | null;
+    /** The general check digit, position 5 of the barcode. */
+    dv: string;
+    /** Raw 4-digit field. `0` means the boleto carries no due date. */
+    fatorVencimento: number;
+    /** Due date, or `null` when the fator is `0`. */
+    vencimento: Date | null;
+    /** Which epoch {@link vencimento} was resolved under. `null` when there is none. */
+    vencimentoEpoch: Exclude<BoletoEpoch, "auto"> | null;
+    /** Reais. `0` when the issuer left the amount for the payer to fill in. */
+    valor: number;
+    /** 25 digits the issuing bank defines. Not interpretable without its manual. */
+    campoLivre: string;
+}
+
+/**
+ * Resolve a fator de vencimento to a calendar date.
+ *
+ * The field is four digits of days since a base date, and it has had **two** base
+ * dates: 1997-10-07 until the counter saturated at 9999 on 2025-02-21, then
+ * 2022-05-29 from 2025-02-22, when FEBRABAN restarted it at 1000.
+ *
+ * !!! danger "The two epochs are genuinely ambiguous"
+ *     Every fator from 1000 to 9999 has a reading under each base — 1997-10-07
+ *     gives a date in `2000-07-03 … 2025-02-21`, 2022-05-29 gives one in
+ *     `2025-02-22 … 2049-10-14`. Nothing in the barcode says which. `"auto"`
+ *     picks whichever lands nearer `reference`, which is right for the case that
+ *     matters (a slip being paid now) and wrong for an archive sweep. Pass
+ *     `"legacy"` or `"current"` when you know.
+ *
+ * @param fator - The raw 4-digit field as a number. `0` means "no due date".
+ * @param options - Epoch selection. Default `"auto"` against `new Date()`.
+ * @returns Local midnight of the due date, or `null` when `fator` is `0`.
+ *
+ * @example
+ * boletoDueDate(1000, { epoch: "legacy" });  // 2000-07-03
+ * boletoDueDate(1000, { epoch: "current" }); // 2025-02-22
+ */
+export declare function boletoDueDate(fator: number, options?: BoletoOptions): {
+    date: Date;
+    epoch: Exclude<BoletoEpoch, "auto">;
+} | null;
+
+/** Which base date the fator de vencimento counts from. See {@link boletoDueDate}. */
+export declare type BoletoEpoch = "auto" | "legacy" | "current";
+
+/**
+ * A boleto string could not be read, or failed a check digit.
+ *
+ * Its own class so a scanner screen can tell "this is not a boleto" apart from a
+ * bug, and so the message can be shown to the operator as-is.
+ */
+export declare class BoletoError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * The two incompatible layouts that share the 44-digit barcode.
+ *
+ * `"banco"` is the cobrança boleto every bank issues; `"arrecadacao"` is the
+ * concessionária/tributo slip, which starts with `8` and lays out its 44 digits
+ * completely differently — same length, different meaning for every field.
+ */
+export declare type BoletoKind = "banco" | "arrecadacao";
+
+/**
+ * Which layout a string is in, without throwing.
+ *
+ * @param value - A barcode or typed line, masked or not.
+ * @returns The layout, or `null` when the length is not 44, 47 or 48.
+ */
+export declare function boletoKind(value: string): BoletoKind | null;
+
+/** Options shared by every parser here. */
+export declare interface BoletoOptions {
+    /** Fator de vencimento epoch. Default `"auto"`. */
+    epoch?: BoletoEpoch;
+    /** Date `"auto"` measures proximity against. Default `new Date()`. */
+    reference?: Date;
+}
+
 /**
  * Clickable choropleth map of Brazil's 27 federative units. Renders the bundled
  * simplified UF GeoJSON as SVG paths — **no external tiles or paid API**. Click
@@ -226,6 +382,85 @@ export declare interface BrUfGeometry {
     coordinates: Ring[] | Ring[][];
 }
 
+/** Options shared by the calendar helpers. */
+export declare interface BusinessDayOptions {
+    /**
+     * Which kinds count as non-working. Default `["national", "banking"]`, i.e.
+     * the Bacen calendar — the right default for anything money moves through.
+     * Pass `["national"]` for a labour-law calendar.
+     */
+    kinds?: readonly HolidayKind[];
+    /**
+     * Extra non-working days, as `YYYY-MM-DD` or `Date`. This is where state and
+     * municipal holidays go: they are **not** in the built-in table and never will
+     * be — there are 5 570 municipalities, each free to declare its own.
+     */
+    extra?: readonly DateInput[];
+    /**
+     * Days of the week that are not worked, `0` = Sunday. Default `[0, 6]`.
+     */
+    weekend?: readonly number[];
+}
+
+/** A fiscal access key taken apart. */
+export declare interface ChaveNFe {
+    /** Federative unit of the issuer, resolved from {@link cUF}. */
+    uf: UF;
+    /** The raw 2-digit IBGE code, positions 1-2. */
+    cUF: string;
+    /** Positions 3-6, `AAMM` — the two-digit year and the month of issue. */
+    anoMes: string;
+    /** Four-digit year derived from {@link anoMes}. */
+    ano: number;
+    /** Month of issue, 1-12. */
+    mes: number;
+    /** Positions 7-20, the issuer's CNPJ. */
+    cnpj: string;
+    /** Positions 21-22, `mod`. `"55"` is an NF-e, `"65"` an NFC-e. */
+    modelo: string;
+    /** Human label for {@link modelo}, or `null` for a model outside the table. */
+    modeloLabel: string | null;
+    /** Positions 23-25. */
+    serie: string;
+    /** Positions 26-34, `nNF`. */
+    numero: string;
+    /** Position 35, `tpEmis`. */
+    tipoEmissao: string;
+    /** Human label for {@link tipoEmissao}, or `null` for a value outside the table. */
+    tipoEmissaoLabel: string | null;
+    /** Positions 36-43, `cNF` — the issuer's random code. */
+    codigoNumerico: string;
+    /** Position 44, `cDV`. */
+    dv: string;
+}
+
+/**
+ * The check digit a 43-digit key body requires.
+ *
+ * Módulo 11: each digit is multiplied by weights cycling `2…9` from right to
+ * left, the products are summed, and the digit is `11 - (sum mod 11)` — except
+ * that a remainder of `0` or `1` yields `0`, since `11` and `10` do not fit one
+ * position.
+ *
+ * Note this is the **fiscal** flavour of módulo 11. The cobrança boleto resolves
+ * those same remainders to `1`; see `mod11DacCobranca` in `./boleto`.
+ *
+ * @param body - The first 43 digits of the key.
+ * @returns The check digit, 0-9.
+ * @throws {ChaveNFeError} When `body` is not exactly 43 digits.
+ */
+export declare function chaveNFeCheckDigit(body: string): number;
+
+/**
+ * A 44-digit fiscal access key could not be read.
+ *
+ * Its own class so a scanner screen can tell a bad key apart from a bug and show
+ * the message to the operator unchanged.
+ */
+export declare class ChaveNFeError extends Error {
+    constructor(message: string);
+}
+
 /** A `{ value, label }` option, handy for `<Select>` / `<Combobox>`. */
 export declare interface Choice {
     value: string;
@@ -241,6 +476,16 @@ export declare function citiesByUf(uf: string): string[];
 /** `{ value, label }` options for every city in a UF (value === label). */
 export declare function cityChoices(uf: string): Choice[];
 
+/**
+ * Convert a 44-digit barcode to its typed line — 47 digits, or 48 for `8…`.
+ *
+ * @param value - 44 digits.
+ * @returns The typed line, check digits included.
+ * @throws {BoletoError} On a bad length or a general check digit that does not
+ * recompute.
+ */
+export declare function codigoBarrasToLinhaDigitavel(value: string): string;
+
 /** Maps a numeric value to a CSS color string. */
 export declare type ColorScale = (value: number) => string;
 
@@ -256,9 +501,43 @@ declare interface Coordinate {
     longitude: number;
 }
 
+/** Anything these helpers accept as a day. */
+export declare type DateInput = Date | string;
+
 /** Diverging palette (red ↔ neutral ↔ blue), for signed metrics. */
 export declare const DIVERGING_RDBU: readonly ["#b2182b", "#ef8a62", "#fddbc7", "#d1e5f0", "#67a9cf", "#2166ac"];
 
+/**
+ * Easter Sunday in the Gregorian calendar.
+ *
+ * The anonymous Gregorian computus (Meeus/Jones/Butcher): pure integer
+ * arithmetic over the year, no tables and no dependency. It is exact for every
+ * Gregorian year, which is why the four movable Brazilian holidays are derived
+ * from it rather than listed.
+ *
+ * @param year - Gregorian year.
+ * @returns Local midnight of Easter Sunday.
+ *
+ * @example
+ * easterSunday(2026); // 2026-04-05
+ */
+export declare function easterSunday(year: number): Date;
+
+/**
+ * Invert {@link boletoDueDate}: the fator that encodes a due date.
+ *
+ * @param date - The due date. Only its local calendar day is used.
+ * @param epoch - Base date to count from. Default `"current"`, the epoch in force
+ * since 2025-02-22 and therefore the one a boleto issued today must use.
+ * @returns The 4-digit fator.
+ * @throws {BoletoError} When the date falls outside the 1000-9999 window of that
+ * epoch, because no fator can represent it.
+ *
+ * @example
+ * fatorVencimento(new Date(2025, 1, 22)); // 1000
+ */
+export declare function fatorVencimento(date: Date, epoch?: Exclude<BoletoEpoch, "auto">): number;
+
 /** A ready-to-use mapping from coordinates to viewport pixels. */
 declare interface FittedProjection {
     /** Project a coordinate to a pixel inside the viewport. */
@@ -271,6 +550,35 @@ declare interface FittedProjection {
     height: number;
 }
 
+/**
+ * Group a key in blocks of four, the way a DANFE prints it.
+ *
+ * @param chave - The key, masked or not.
+ * @returns Eleven groups of four digits separated by spaces, or the input
+ * unchanged when it is not 44 digits — this is a display helper, not a validator.
+ *
+ * @example
+ * formatChaveNFe("35260112345678000195550010000001231123456784");
+ * // "3526 0112 3456 7800 0195 5500 1000 0001 2311 2345 6784"
+ */
+export declare function formatChaveNFe(chave: string): string;
+
+/**
+ * Group a typed line the way it is printed, so a human can read it back.
+ *
+ * 47 digits become `AAABC.CCCCD EEEEE.EEEEEF GGGGG.GGGGGH I JJJJKKKKKKKKKK`;
+ * 48 digits become four blocks of twelve. Anything else is returned untouched —
+ * this is a display helper, not a validator.
+ *
+ * @param value - A typed line, masked or not.
+ * @returns The grouped string.
+ *
+ * @example
+ * formatLinhaDigitavel("34191090086459218110900000463074184410000002000");
+ * // "34191.09008 64592.181109 00000.463074 1 84410000002000"
+ */
+export declare function formatLinhaDigitavel(value: string): string;
+
 /**
  * Forward-geocode a municipality by name (accent-insensitive), optionally scoped
  * to a UF. Returns every exact-name match — the same name can occur in several
@@ -301,12 +609,98 @@ export declare interface GeoMarker extends Coordinate {
 /** Look up a single state by acronym (case-insensitive). Returns `null` if unknown. */
 export declare function getState(uf: string): BrazilState | null;
 
+/** One non-working day in a given year. */
+export declare interface Holiday {
+    /** `YYYY-MM-DD` in the local calendar. */
+    date: string;
+    /** Portuguese name, as the law or the Bacen calendar spells it. */
+    name: string;
+    kind: HolidayKind;
+    /** `true` when the date is derived from Easter rather than fixed. */
+    movable: boolean;
+}
+
+/**
+ * How binding a non-working day is.
+ *
+ * - `"national"` — a feriado nacional in federal law. Nobody works, and a
+ *   deadline that lands here moves.
+ * - `"banking"` — not a statutory holiday, but a day the national financial
+ *   system does not operate: Carnaval (Monday and Tuesday), Sexta-feira da
+ *   Paixão and Corpus Christi. Bank branches are shut and compensation does not
+ *   run, so a boleto or a TED dated here settles later — but an employer may
+ *   legally require work, which is why the two kinds are separate.
+ */
+export declare type HolidayKind = "national" | "banking";
+
+/**
+ * Every national non-working day in a year, ordered by date.
+ *
+ * **What is here:** the nine feriados nacionais in federal law (Lei 662/1949 as
+ * amended by Lei 10.607/2002, Lei 6.802/1980 for 12 October, and Lei 14.759/2023
+ * for 20 November, which is why that one only appears from 2024), plus the four
+ * movable days the national financial system observes.
+ *
+ * **What is deliberately not here**, and will not be:
+ *
+ * - **State and municipal holidays.** A data magna varies by state and each of the
+ *   5 570 municipalities may declare its own, including up to four religious
+ *   days. No table can be both complete and current; pass them through
+ *   `options.extra`.
+ * - **Ponto facultativo.** A federal decree that lets public servants off is not a
+ *   holiday and binds nobody else, so it changes no deadline.
+ * - **Pre-2002 history.** The table encodes the law as it stands today. Asking for
+ *   1998 returns today's set shifted to 1998, not what was in force then.
+ *
+ * Carnaval, Sexta-feira da Paixão and Corpus Christi are the interesting case:
+ * none of them is a feriado nacional in federal law, yet CMN Resolução 4.880/2020
+ * closes the banks on all four days, so a payment cannot settle. They are returned
+ * with `kind: "banking"` — counted by default, and excluded by passing
+ * `kinds: ["national"]`.
+ *
+ * @param year - Gregorian year.
+ * @returns The holidays of that year, ascending by date.
+ *
+ * @example
+ * holidaysFor(2026).filter((holiday) => holiday.kind === "national").length; // 9
+ */
+export declare function holidaysFor(year: number): Holiday[];
+
 /**
  * Interpolate a palette at `t ∈ [0, 1]`, blending between the two nearest
  * stops. `t <= 0` → first color, `t >= 1` → last.
  */
 export declare function interpolatePalette(palette: readonly string[], t: number): string;
 
+/**
+ * Whether a date is a working day: not a weekend, not a holiday.
+ *
+ * @param date - `YYYY-MM-DD` or a `Date`.
+ * @param options - See {@link BusinessDayOptions}.
+ * @returns `true` when work happens on that day.
+ * @throws {RangeError} On a malformed string or an Invalid Date.
+ *
+ * @example
+ * isBusinessDay("2026-04-03"); // false — Sexta-feira da Paixão
+ */
+export declare function isBusinessDay(date: DateInput, options?: BusinessDayOptions): boolean;
+
+/**
+ * Whether a date is a national holiday.
+ *
+ * @param date - `YYYY-MM-DD` or a `Date`. Only the local calendar day matters.
+ * @param options - See {@link BusinessDayOptions}. `weekend` is ignored here — a
+ * Sunday is not a holiday, it is a Sunday.
+ * @returns `true` when the day is in the table (or in `extra`).
+ * @throws {RangeError} On a malformed string or an Invalid Date.
+ *
+ * @example
+ * isHoliday("2026-11-20"); // true
+ * isHoliday("2026-02-17"); // true — Carnaval
+ * isHoliday("2026-02-17", { kinds: ["national"] }); // false
+ */
+export declare function isHoliday(date: DateInput, options?: BusinessDayOptions): boolean;
+
 /** True when `city` exists within `uf` (both case-insensitive). */
 export declare function isValidCity(uf: string, city: string): boolean;
 
@@ -319,6 +713,15 @@ export declare interface LegendItem {
     label: ReactNode;
 }
 
+/**
+ * Convert a typed line to its 44-digit barcode.
+ *
+ * @param value - 47 or 48 digits.
+ * @returns The 44-digit barcode.
+ * @throws {BoletoError} On a bad length or a check digit that does not recompute.
+ */
+export declare function linhaDigitavelToCodigoBarras(value: string): string;
+
 /** All 27 federative units, sorted by name. */
 export declare function listStates(): readonly BrazilState[];
 
@@ -398,6 +801,58 @@ export declare interface MapMarkersProps {
     onMarkerClick?: (marker: GeoMarker, index: number) => void;
 }
 
+/**
+ * DAC módulo 10, FEBRABAN flavour.
+ *
+ * Multipliers cycle `2, 1, 2, 1, …` from right to left; the **digits** of each
+ * product are summed individually (so `6 × 2 = 12` contributes `1 + 2`); the DAC
+ * is `10 - (sum mod 10)`, and `0` when that remainder is `0`.
+ *
+ * Ported from "Layout Padrão de Arrecadação/Recebimento com Utilização do Código
+ * de Barras", FEBRABAN version 07 (effective 2023-03-01), section 07 — whose own
+ * worked example gives `01230067896 → 3`.
+ *
+ * @param value - Digits only.
+ * @returns The check digit, 0-9.
+ * @throws {BoletoError} When `value` is empty or holds a non-digit.
+ */
+export declare function mod10Dac(value: string): number;
+
+/**
+ * DAC módulo 11 for an **arrecadação** barcode — position 4 of a `8…` slip.
+ *
+ * Same weights and same subtraction as {@link mod11DacCobranca}, but a remainder
+ * of `0` or `1` resolves to **`0`**.
+ *
+ * Ported from the FEBRABAN version 07 layout, section 10, and pinned by that
+ * document's own worked example: the 43-digit sequence
+ * `8220000215048200974123220154098290108605940` sums to 705, `705 mod 11 = 1`,
+ * and the barcode the spec prints carries `0` in position 4.
+ *
+ * @param value - The 43 digits of the barcode with position 4 removed.
+ * @returns The check digit, 0 or 2-9.
+ * @throws {BoletoError} When `value` is empty or holds a non-digit.
+ */
+export declare function mod11DacArrecadacao(value: string): number;
+
+/**
+ * DAC módulo 11 for a **cobrança** barcode — position 5 of a bank boleto.
+ *
+ * Weights cycle `2…9` from right to left, the products are summed whole, and the
+ * DAC is `11 - (sum mod 11)`. A remainder of `0`, `1` or `10` would put `11`, `10`
+ * or `1` in a one-digit field, and FEBRABAN resolves all three to **`1`**.
+ *
+ * That last rule is where cobrança and arrecadação disagree — see
+ * {@link mod11DacArrecadacao}, which resolves the same remainders to `0`. Using
+ * one flavour on the other layout produces a check digit that is wrong exactly
+ * 3 times in 11, which is why they are separate functions here.
+ *
+ * @param value - The 43 digits of the barcode with position 5 removed.
+ * @returns The check digit, 1-9.
+ * @throws {BoletoError} When `value` is empty or holds a non-digit.
+ */
+export declare function mod11DacCobranca(value: string): number;
+
 /** A municipality identified for selection callbacks. */
 export declare interface Municipality {
     /** 7-digit IBGE code. */
@@ -493,18 +948,408 @@ export declare interface NearestMunicipality extends MunicipalityCentroid {
  */
 export declare function nearestMunicipality(coord: Coordinate): Promise<NearestMunicipality | null>;
 
+/**
+ * The first working day strictly after a date.
+ *
+ * Strictly after: calling it on a Wednesday returns Thursday, never the same
+ * Wednesday. That is what a "prazo de D+1" means, and it makes the function safe
+ * to call in a loop.
+ *
+ * @param date - `YYYY-MM-DD` or a `Date`.
+ * @param options - See {@link BusinessDayOptions}.
+ * @returns Local midnight of the next working day.
+ * @throws {RangeError} On a malformed input, or when `options` marked so many days
+ * off that no working day exists within {@link MAX_WALK_DAYS}.
+ *
+ * @example
+ * nextBusinessDay("2026-12-24"); // 2026-12-28 — the 25th is Natal, then a weekend
+ */
+export declare function nextBusinessDay(date: DateInput, options?: BusinessDayOptions): Date;
+
+/** A key after normalisation, ready to go into the payload. */
+export declare interface NormalizedPixKey {
+    type: PixKeyType;
+    /** The exact string written into the BR Code. */
+    value: string;
+}
+
+/**
+ * Validate a Pix key and return the exact string to write into the payload.
+ *
+ * Normalisation per type: CPF and CNPJ lose their mask, a phone becomes E.164
+ * with the `+55` country code, an EVP is lower-cased, and an e-mail is
+ * lower-cased because DICT stores it that way — a key that differs only in case
+ * would otherwise fail to resolve.
+ *
+ * All validation lives in {@link pixKeyType}; past that gate the normalisation is
+ * total, which is why the phone branch strips a country code purely on length
+ * rather than re-checking the shape.
+ *
+ * @param key - Raw key, masked or not.
+ * @returns The type and the normalised value.
+ * @throws {PixError} When the key matches no accepted format, or when a document
+ * key fails its check digits.
+ *
+ * @example
+ * normalizePixKey("123.456.789-09"); // { type: "cpf", value: "12345678909" }
+ * normalizePixKey("(11) 98765-4321"); // { type: "phone", value: "+5511987654321" }
+ */
+export declare function normalizePixKey(key: string): NormalizedPixKey;
+
 /**
  * Normalize an acronym to canonical uppercase form, or `null` if it is not a
  * valid UF. `"sp"` → `"SP"`, `"xx"` → `null`.
  */
 export declare function normalizeUf(value: string): UF | null;
 
+/**
+ * Read a 44-digit fiscal access key into its fields.
+ *
+ * The layout is fixed and shared by every document type that carries a key —
+ * NF-e, NFC-e, CT-e, MDF-e — so `modelo` is what tells you which one you are
+ * holding, not the length.
+ *
+ * ```text
+ * 35 2601 12345678000195 55 001 000000123 1 12345678 4
+ * cUF AAMM CNPJ           mod série nNF    tp cNF     cDV
+ * ```
+ *
+ * @param chave - The key, with or without the spaces a DANFE prints.
+ * @returns The parsed key.
+ * @throws {ChaveNFeError} On a length other than 44, an unknown `cUF`, a month
+ * outside 1-12, or a check digit that does not recompute.
+ *
+ * @example
+ * const { uf, cnpj, numero, modeloLabel } = parseChaveNFe(scanned);
+ */
+export declare function parseChaveNFe(chave: string): ChaveNFe;
+
+/**
+ * Read a 44-digit barcode — either layout — into its fields.
+ *
+ * The first digit picks the layout: `8` is an arrecadação/convênio slip, anything
+ * else is a cobrança boleto. They are **not** variants of one format; every field
+ * moves. Narrow the result on `kind` before touching it.
+ *
+ * @param value - 44 digits. Spaces and punctuation are ignored.
+ * @param options - Fator de vencimento epoch. See {@link boletoDueDate}.
+ * @returns The parsed boleto, with the matching typed line filled in.
+ * @throws {BoletoError} On a length other than 44, on a general check digit that
+ * does not recompute, or on an arrecadação slip whose position 3 is out of spec.
+ *
+ * @example
+ * const boleto = parseCodigoBarras(scanned);
+ * if (boleto.kind === "banco") console.log(boleto.valor, boleto.vencimento);
+ */
+export declare function parseCodigoBarras(value: string, options?: BoletoOptions): Boleto;
+
+/**
+ * Read a typed line — 47 digits for a bank boleto, 48 for an arrecadação slip.
+ *
+ * Both layouts interleave check digits with the data, so the function rebuilds the
+ * 44-digit barcode as it goes and every DV is verified: the three (bank) or four
+ * (arrecadação) block digits, plus the general one.
+ *
+ * @param value - 47 or 48 digits. The usual `.`, ` ` and `-` are ignored.
+ * @param options - Fator de vencimento epoch. See {@link boletoDueDate}.
+ * @returns The parsed boleto, with the barcode filled in.
+ * @throws {BoletoError} On a length other than 47 or 48, or on any check digit
+ * that does not recompute.
+ *
+ * @example
+ * const boleto = parseLinhaDigitavel("34191.09008 64592.181109 00000.463074 1 84410000002000");
+ */
+export declare function parseLinhaDigitavel(value: string, options?: BoletoOptions): Boleto;
+
+/** Options for {@link parsePixPayload}. */
+export declare interface ParsePixOptions {
+    /**
+     * Throw when the checksum does not match. Default `true`.
+     *
+     * Turn it off only to inspect a payload you already know is broken: a BR Code
+     * whose CRC fails has been corrupted in transit, and the account it now points
+     * at is not the account the payee published.
+     */
+    requireCrc?: boolean;
+}
+
+/**
+ * Read a Pix "Copia e Cola" payload back into its parts.
+ *
+ * Tolerant by design: tags the SDK does not know about are kept verbatim in
+ * {@link PixData.fields} instead of raising, because PSPs do add their own
+ * templates and a reader that rejects them is useless in production. What is
+ * *not* tolerated is a broken frame — a length prefix that runs off the end, a
+ * missing tag 63 — or a checksum mismatch, which means the string was corrupted
+ * and no longer names the account the payee published.
+ *
+ * @param payload - The copia-e-cola string. Surrounding whitespace is ignored.
+ * @param options - See {@link ParsePixOptions}.
+ * @returns The decoded payload.
+ * @throws {PixError} On a malformed frame, a missing CRC tag, a tag 26 that is
+ * not a Pix account, or — unless `requireCrc` is `false` — a CRC mismatch.
+ *
+ * @example
+ * const data = parsePixPayload(copied);
+ * console.log(data.key, data.amount, data.txid);
+ */
+export declare function parsePixPayload(payload: string, options?: ParsePixOptions): PixData;
+
+/**
+ * CRC-16/CCITT-FALSE of a string, as four upper-case hex characters.
+ *
+ * Bitwise rather than table-driven: 200-odd characters at 8 shifts each is
+ * nothing, and a 256-entry table is 2 KB of payload every consumer of the `/br`
+ * entry would carry.
+ *
+ * The input is taken as UTF-8 bytes. A Pix payload is ASCII by construction —
+ * {@link pixPayload} rejects anything else — but the function is exported and a
+ * caller may hand it arbitrary text, and hashing UTF-16 code units would then
+ * disagree with every other implementation.
+ *
+ * @param input - Bytes to run through the register.
+ * @returns Four upper-case hex characters, zero-padded.
+ *
+ * @example
+ * pixCrc16("123456789"); // "29B1" — the catalogue check value
+ */
+export declare function pixCrc16(input: string): string;
+
+/** A payload taken apart again. */
+export declare interface PixData {
+    /** `"dynamic"` when tag 26 carried a URL instead of a key. */
+    kind: "static" | "dynamic";
+    /** Present on a static payload. */
+    key?: string;
+    keyType?: PixKeyType;
+    /** Present on a dynamic payload. */
+    url?: string;
+    merchantName: string;
+    merchantCity: string;
+    /** Reais. `undefined` when the payer chooses the amount. */
+    amount?: number;
+    /** ISO 4217 numeric. `"986"` for BRL. */
+    currency: string;
+    countryCode: string;
+    merchantCategoryCode: string;
+    /** `"***"` on a reusable static QR that identifies no single transaction. */
+    txid?: string;
+    description?: string;
+    postalCode?: string;
+    /** Tag 01 read as `"12"`. */
+    oneTime: boolean;
+    /** The four hex characters that closed the payload. */
+    crc: string;
+    /** Whether those four characters match a recomputed CRC. */
+    crcValid: boolean;
+    /** Every top-level TLV, in payload order, unknown tags included. */
+    fields: PixField[];
+}
+
+/** A BR Code that carries a URL the wallet fetches to learn the amount. */
+export declare interface PixDynamicInput {
+    kind: "dynamic";
+    /**
+     * `payloadLocation` — the https URL the wallet GETs, **without** the scheme,
+     * exactly as BACEN specifies (`pix.example.com/qr/v2/abc`).
+     */
+    url: string;
+    merchantName: string;
+    merchantCity: string;
+    postalCode?: string;
+    /** Single-use QR. Defaults to `true`, which is what a dynamic QR normally is. */
+    oneTime?: boolean;
+}
+
 /** A pixel coordinate inside the plotting viewport. */
 declare interface PixelPoint {
     x: number;
     y: number;
 }
 
+/**
+ * A Pix payload could not be built or read.
+ *
+ * Its own class so a caller can tell "the operator typed a bad key" apart from a
+ * bug, and so an `ErrorBoundary` can render a form error instead of a crash.
+ */
+export declare class PixError extends Error {
+    constructor(message: string);
+}
+
+/** One TLV as it appeared in a payload, unknown tags included. */
+export declare interface PixField {
+    /** Two-character tag, e.g. `"59"`. */
+    id: string;
+    /** Raw value, still encoded when the tag is itself a template. */
+    value: string;
+}
+
+/** Everything `pixPayload` accepts. */
+export declare type PixInput = PixStaticInput | PixDynamicInput;
+
+/** The five key formats DICT accepts. */
+export declare type PixKeyType = "cpf" | "cnpj" | "email" | "phone" | "evp";
+
+/**
+ * Classify a Pix key, or `null` when it matches no accepted format.
+ *
+ * !!! warning "CPF and a national phone number are both eleven digits"
+ *     `"11987654321"` is a valid mobile number and could be a CPF. The check
+ *     digits break the tie: an 11-digit string is a CPF when its DV validates and
+ *     a phone otherwise. Pass phone keys as `+5511987654321` to remove the guess
+ *     entirely.
+ *
+ * @param key - Raw key, masked or not.
+ * @returns The key type, or `null`.
+ */
+export declare function pixKeyType(key: string): PixKeyType | null;
+
+/**
+ * Build a Pix "Copia e Cola" payload — the string behind a Pix QR code.
+ *
+ * The format is EMVCo MPM: a flat list of `ID + 2-digit length + value` triples,
+ * closed by tag 63 holding a CRC-16/CCITT-FALSE over **everything before it,
+ * including the literal `6304` header of tag 63 itself**. That last detail is the
+ * one implementations get wrong; see {@link pixCrc16}.
+ *
+ * Two shapes come out of here:
+ *
+ * - **static** — tag 26 carries the key, so the QR is self-contained and can be
+ *   printed. Amount optional; a txid of `"***"` means "identifies no single
+ *   transaction", which is what a reusable poster QR wants.
+ * - **dynamic** — tag 26 carries a URL instead, and the wallet fetches the amount
+ *   and payee from the PSP. Use it when the value is per-order. Defaults to
+ *   single-use (tag 01 = `12`).
+ *
+ * The distinction matters and is not cosmetic: a static QR settles against
+ * whatever the payer typed, a dynamic one against what the PSP served, so a
+ * charge that must reconcile to a cent needs the dynamic form.
+ *
+ * @param input - Static or dynamic payload description.
+ * @returns The full payload, CRC included, ready to render as a QR or to copy.
+ * @throws {PixError} On an unrecognised key, a field over its length cap, a
+ * non-positive amount, or text that is not representable in the BR Code.
+ *
+ * @example
+ * pixPayload({
+ *   key: "12345678909",
+ *   merchantName: "Loja Tempest",
+ *   merchantCity: "São Paulo",
+ *   amount: 25.5,
+ *   txid: "PEDIDO123",
+ * });
+ */
+export declare function pixPayload(input: PixInput): string;
+
+/**
+ * A Pix QR code with the copia-e-cola string next to it.
+ *
+ * The two affordances belong together: a QR is unusable on the device that is
+ * *showing* it, which is exactly where a mobile checkout puts it, so every real
+ * Pix screen ends up needing the copyable string as well. Rendering only the
+ * symbol is the single most common mistake in a Pix flow.
+ *
+ * Everything is computed locally — {@link pixPayload} builds the string and the
+ * SDK's own encoder draws the symbol — so the key, the amount and the txid never
+ * leave the page. A QR-image service would receive all three.
+ *
+ * @throws {PixError} When neither `pix` nor `payload` is given, when both are, or
+ * when `pix` fails validation. A bad key is a programming or data error rather
+ * than a state to render, so it surfaces; wrap the screen in `ErrorBoundary` when
+ * the values come from user input.
+ *
+ * @example
+ * <PixQRCode
+ *   pix={{
+ *     key: "loja@tempest.dev",
+ *     merchantName: "Loja Tempest",
+ *     merchantCity: "São Paulo",
+ *     amount: 25.5,
+ *     txid: "PEDIDO123",
+ *   }}
+ *   amountLabel="R$ 25,50"
+ *   payeeLabel="Loja Tempest"
+ * />
+ *
+ * @example
+ * <PixQRCode payload={charge.brcode} level="Q" size={220} />
+ */
+export declare function PixQRCode({ pix, payload, size, level, showCopy, amountLabel, payeeLabel, labels, onCopied, className, ...rest }: PixQRCodeProps): JSX.Element;
+
+/** Strings the component renders, so an app can translate them. */
+export declare interface PixQRCodeLabels {
+    /** Accessible name of the symbol. */
+    qr: string;
+    /** Copy button, idle. */
+    copy: string;
+    /** Copy button, just clicked. */
+    copied: string;
+}
+
+export declare interface PixQRCodeProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /**
+     * Build the payload from its parts. Mutually exclusive with {@link payload}.
+     */
+    pix?: PixInput;
+    /**
+     * A payload your PSP already produced, used verbatim.
+     *
+     * Prefer this for a dynamic charge: the PSP signed that string, and rebuilding
+     * it here from parsed parts would only add a way to get it wrong.
+     */
+    payload?: string;
+    /** Rendered side of the symbol in px, quiet zone included. Default `192`. */
+    size?: number;
+    /**
+     * Error-correction level. Default `"M"`.
+     *
+     * A printed QR that will be photographed at an angle scans better at `"Q"` or
+     * `"H"`; the cost is a denser symbol, so raise the size with it.
+     */
+    level?: QRErrorCorrection;
+    /** Render the copia-e-cola line and its copy button. Default `true`. */
+    showCopy?: boolean;
+    /** Amount caption, e.g. `"R$ 25,50"`. Rendered above the symbol when set. */
+    amountLabel?: string;
+    /** Payee caption. Rendered under the amount when set. */
+    payeeLabel?: string;
+    labels?: Partial<PixQRCodeLabels>;
+    /** Called after the payload reaches the clipboard. */
+    onCopied?: () => void;
+}
+
+/** A BR Code that carries the key — the one you print on a poster. */
+export declare interface PixStaticInput {
+    kind?: "static";
+    /** CPF, CNPJ, e-mail, phone or EVP. Validated and normalised. */
+    key: string;
+    /** Payee name. Truncated by the spec at 25 characters — longer throws. */
+    merchantName: string;
+    /** Payee city. Truncated by the spec at 15 characters — longer throws. */
+    merchantCity: string;
+    /** Amount in BRL. Omit for a payer-chooses-the-value QR. */
+    amount?: number;
+    /** Reference the PSP echoes back, `[A-Za-z0-9]{1,25}`. Defaults to `"***"`. */
+    txid?: string;
+    /** Free text shown by some wallets. Goes into tag 26, sub-tag 02. */
+    description?: string;
+    /** CEP, digits only. Optional tag 61. */
+    postalCode?: string;
+    /** Single-use QR: sets tag 01 to `"12"` instead of `"11"`. */
+    oneTime?: boolean;
+}
+
+/**
+ * The fixed tables of ISO/IEC 18004, transcribed.
+ *
+ * They are data, not logic: the standard specifies them and there is nothing to
+ * derive. They live apart from {@link ./qr-encode} so the algorithm reads as
+ * algorithm and a typo in a table stays findable.
+ */
+/** Error correction level, by how much of the symbol it can lose and survive. */
+declare type QRErrorCorrection = "L" | "M" | "Q" | "H";
+
 /**
  * Discrete scale: split `[min, max]` into `palette.length` equal buckets and
  * return the bucket's color (a classic choropleth "quantize" scale).
@@ -618,4 +1463,37 @@ export declare type UF = "AC" | "AL" | "AP" | "AM" | "BA" | "CE" | "DF" | "ES" |
 /** `{ value: uf, label: name }` options for every state, for a `<Select>`. */
 export declare function ufChoices(): Choice[];
 
+/**
+ * Whether a boleto string is internally consistent.
+ *
+ * Checks every digit the layout can check — the block DVs of a typed line and the
+ * general DV in both representations. It says nothing about whether the boleto
+ * exists, is registered, or is still payable: only a bank can answer that. What it
+ * *does* catch is the common failure, a mistyped or truncated line.
+ *
+ * @param value - A barcode (44) or typed line (47/48), masked or not.
+ * @returns `true` when everything recomputes.
+ *
+ * @example
+ * if (!validateBoleto(input)) setError("Confira a linha digitável.");
+ */
+export declare function validateBoleto(value: string): boolean;
+
+/**
+ * Whether a fiscal access key is well formed.
+ *
+ * Three things have to hold: 44 digits, a `cUF` that is a real federative unit,
+ * and a check digit that recomputes. It says nothing about whether the document
+ * exists or was authorised — only SEFAZ can answer that — but it catches the
+ * failure that actually happens, a key transcribed by hand or truncated by a
+ * spreadsheet.
+ *
+ * @param chave - The key, with or without the spaces a DANFE prints.
+ * @returns `true` when all three hold.
+ *
+ * @example
+ * if (!validateChaveNFe(input)) setError("Chave inválida.");
+ */
+export declare function validateChaveNFe(chave: string): boolean;
+
 export { }