@br-validators/cli 1.9.0 → 1.10.0

package/README.md

@@ -4,7 +4,7 @@
 [![MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/open-data-brazil/br-validators/blob/main/LICENSE)
 [![GitHub release](https://img.shields.io/github/v/release/open-data-brazil/br-validators)](https://github.com/open-data-brazil/br-validators/releases)
 
-Terminal CLI for all Brazilian document validators in [@br-validators/core](https://www.npmjs.com/package/@br-validators/core) **v1.9.0**.
+Terminal CLI for all Brazilian document validators in [@br-validators/core](https://www.npmjs.com/package/@br-validators/core) **v1.10.0**.
 
 **Repo:** [github.com/open-data-brazil/br-validators](https://github.com/open-data-brazil/br-validators)
 
@@ -78,7 +78,7 @@ br-validators ie validate P-01100424.3/002 --uf SP   # SP produtor rural (auto-d
 | `sanitize <type> [value]` | ETL fixes + validate; `--uf` for `inscricao-estadual` |
 | `mask <type> [value]` | Unified display mask; `--uf` for IE / RG |
 | `compare <type> <valueA> <valueB>` | Normalized equality; `--uf` for IE / RG / título |
-| `batch <type>` | Bulk validate (stdin or `--file`); `--uf`, `--limit` |
+| `batch <type>` | Bulk validate (stdin or `--file`, or CSV with `--col`); `--delimiter`, `--skip-header`; `--uf`, `--limit` |
 | `diff <type> <valueA> <valueB>` | Field-level diff; `--uf` for IE / RG / título |
 | `generate <type>` | Synthetic test document; `--seed`, `--masked`, `--format` |
 
@@ -91,6 +91,9 @@ br-validators mask cpf 12345678909 --json
 br-validators mask inscricao-estadual 110042490114 --uf SP --json
 br-validators compare cpf '123.456.789-09' 12345678909 --json
 br-validators batch cpf --file values.txt --json
+br-validators batch cpf --file payroll.csv --col cpf --json
+br-validators sanitize pix ' PIX@BCB.GOV.BR ' --json
+br-validators csosn lookup 102 --json
 br-validators diff cpf 12345678909 12345678901 --json
 br-validators generate cpf --seed 42 --masked --json
 br-validators generate cnpj --format alphanumeric --seed 7 --json
@@ -127,6 +130,17 @@ br-validators cbo lookup 212405 --json
 br-validators cbo search analista --limit 5
 ```
 
+### Fiscal reference (33o–34)
+
+```bash
+br-validators iss-municipal lookup 3550308 --json
+br-validators iss-municipal list --uf SP --limit 10 --json
+br-validators iss-municipal search campinas --uf SP --limit 5 --json
+br-validators iss-municipal resolve SP "São Paulo" --verbose
+```
+
+Partial embed (~500 municipalities). **Estimation / quoting only — not NFSe emission.**
+
 ### Geography & calendar (27d)
 
 ```bash
@@ -145,8 +159,22 @@ br-validators ddd lookup 11 --verbose
 br-validators moedas lookup BRL --json
 br-validators paises-bacen lookup 1058 --verbose
 br-validators incoterms lookup FOB --json
+br-validators ptax lookup USD --verbose
+br-validators ptax lookup USD 2026-06-20 --json --verbose
+br-validators ptax historico USD 2026-06-01 2026-06-26 --json --verbose
 ```
 
+**PTAX:** offline embed — last **90 business days** (`janelaDiasUteis: 90`; not live Bacen). `--verbose` prints `dataReferencia`, `isStale`, and `warning` when stale. `ptax historico` lists all embedded rows in a date range.
+
+### Finance (SELIC)
+
+```bash
+br-validators selic --verbose
+br-validators selic --date 2026-06-18 --json --verbose
+```
+
+`--verbose` includes `dataReferencia`, `isStale`, and dataset `capturadoEm` (same pattern as PTAX).
+
 ### Logistics (26e)
 
 ```bash
@@ -169,9 +197,10 @@ br-validators aeroportos lookup SBGR --json
 |------|-------------|
 | `--json` | JSON output |
 | `--quiet` / `-q` | Exit code only (CI) |
+| `--verbose` | PTAX / SELIC: `dataReferencia`, `isStale`, `warning`; other lookups: dataset metadata |
 | `--file` / `-f` | Read value from file |
 | `--source` | Print official source URL (per-type) |
-| `--uf` | Required for IE / detect / sanitize IE; optional filter for `ibge list municipios` |
+| `--uf` | Required for IE / detect / sanitize IE; filter for `ibge list municipios`, `iss-municipal list`, and `iss-municipal search` |
 
 ### CI
 

package/dist/index.js

@@ -150,6 +150,10 @@ import {
   CFOP_DATA_VERSION,
   lookupCfopPorCodigo
 } from "@br-validators/core/cfop";
+import {
+  CSOSN_DATA_VERSION,
+  lookupCsosnPorCodigo
+} from "@br-validators/core/csosn";
 import { NCM_DATA_VERSION, lookupNcmPorCodigo } from "@br-validators/core/ncm";
 import { CBO_DATA_VERSION, lookupCboPorCodigo } from "@br-validators/core/cbo";
 import {
@@ -162,6 +166,7 @@ var REFERENCE_LOOKUP_COMMANDS = [
   "cest",
   "cnae",
   "cfop",
+  "csosn",
   "ncm",
   "cbo",
   "moedas",
@@ -170,7 +175,7 @@ var REFERENCE_LOOKUP_COMMANDS = [
   "portos",
   "aeroportos"
 ];
-var REFERENCE_SEARCH_COMMANDS = ["cnae", "cfop", "ncm", "cbo"];
+var REFERENCE_SEARCH_COMMANDS = ["cnae", "cfop", "csosn", "ncm", "cbo"];
 function lookupAeroporto(input) {
   const normalized = input.trim().toUpperCase();
   if (normalized.length === 0) {
@@ -240,6 +245,17 @@ var REFERENCE_LOOKUP_MODULES = {
       return `${row.codigo} \u2014 ${row.descricao}`;
     }
   },
+  csosn: {
+    command: "csosn",
+    description: "CONFAZ CSOSN Simples Nacional \u2014 offline lookup",
+    resultKey: "csosn",
+    capturadoEm: CSOSN_DATA_VERSION.capturadoEm,
+    lookup: (input) => lookupCsosnPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.descricao}`;
+    }
+  },
   ncm: {
     command: "ncm",
     description: "Siscomex NCM Mercosur codes \u2014 offline lookup",
@@ -380,6 +396,7 @@ function runReferenceLookup(command, value, options, io = { stdout: [], stderr:
 import { searchCbo } from "@br-validators/core/cbo";
 import { searchCnaes } from "@br-validators/core/cnaes";
 import { searchCfop } from "@br-validators/core/cfop";
+import { searchCsosn } from "@br-validators/core/csosn";
 import { searchNcm } from "@br-validators/core/ncm";
 function runSearch(command, query, limit) {
   switch (command) {
@@ -387,6 +404,8 @@ function runSearch(command, query, limit) {
       return searchCnaes(query, { limit });
     case "cfop":
       return searchCfop(query, { limit });
+    case "csosn":
+      return searchCsosn(query, { limit });
     case "ncm":
       return searchNcm(query, { limit });
     case "cbo":
@@ -444,15 +463,18 @@ function runReferenceSearch(command, query, options, io = { stdout: [], stderr:
 
 // src/commands/reference-lookup/validate.ts
 import { validateCfop } from "@br-validators/core/cfop";
+import { validateCsosn } from "@br-validators/core/csosn";
 import { validateNcm } from "@br-validators/core/ncm";
-var REFERENCE_VALIDATE_COMMANDS = ["ncm", "cfop"];
+var REFERENCE_VALIDATE_COMMANDS = ["ncm", "cfop", "csosn"];
 var VALIDATORS = {
   ncm: validateNcm,
-  cfop: validateCfop
+  cfop: validateCfop,
+  csosn: validateCsosn
 };
 var CAPTURED_AT = {
   ncm: "ncm",
-  cfop: "cfop"
+  cfop: "cfop",
+  csosn: "csosn"
 };
 function emitFailure(result, options, io) {
   if (options.json) {
@@ -1297,12 +1319,19 @@ function runSelicCommand(options, io = { stdout: [], stderr: [] }) {
 
 // src/commands/iss-municipal/index.ts
 import {
-  getIssMunicipalPorIbge,
+  getIssMunicipalPorUf,
   getIssMunicipalPorUfMunicipio,
   ISS_MUNICIPAL_DATA_VERSION,
   ISS_MUNICIPAL_ESTIMATION_WARNING,
+  lookupIssMunicipalPorIbge,
   searchIssMunicipal
 } from "@br-validators/core/iss-municipal";
+function sliceRows2(rows, limit) {
+  if (limit === void 0 || !Number.isFinite(limit) || limit <= 0) {
+    return rows;
+  }
+  return rows.slice(0, limit);
+}
 function formatIssMunicipalHuman(row) {
   return `${row.nome}/${row.uf} \u2014 ISS ${String(row.aliquotaMin)}%\u2013${String(row.aliquotaMax)}%`;
 }
@@ -1318,7 +1347,7 @@ function runIssMunicipalLookup(codigo, options, io = { stdout: [], stderr: [] })
     io.stderr.push("Missing IBGE code. Usage: br-validators iss-municipal lookup <codigoIbge>");
     return EXIT.USAGE;
   }
-  const result = getIssMunicipalPorIbge(trimmed);
+  const result = lookupIssMunicipalPorIbge(trimmed);
   if (result === void 0) {
     io.stderr.push(`ISS municipal row not found for IBGE code ${trimmed}`);
     return EXIT.INVALID;
@@ -1336,6 +1365,7 @@ function runIssMunicipalLookup(codigo, options, io = { stdout: [], stderr: [] })
     return EXIT.OK;
   }
   io.stdout.push(formatIssMunicipalHuman(result));
+  io.stdout.push(`fonte: ${result.fonte}`);
   io.stdout.push(`warning: ${result.warning}`);
   if (options.verbose) {
     io.stdout.push(`leiUrl: ${result.leiUrl}`);
@@ -1344,13 +1374,49 @@ function runIssMunicipalLookup(codigo, options, io = { stdout: [], stderr: [] })
   }
   return EXIT.OK;
 }
+function runIssMunicipalList(options, io = { stdout: [], stderr: [] }) {
+  const uf = options.uf?.trim() ?? "";
+  if (uf.length === 0) {
+    io.stderr.push("Missing UF. Usage: br-validators iss-municipal list --uf <UF>");
+    return EXIT.USAGE;
+  }
+  const rows = sliceRows2(getIssMunicipalPorUf(uf), options.limit);
+  emitDisclaimer(options, io);
+  if (options.json) {
+    const payload = {
+      ok: true,
+      uf: uf.toUpperCase(),
+      total: rows.length,
+      results: rows
+    };
+    if (options.verbose) {
+      payload.capturadoEm = ISS_MUNICIPAL_DATA_VERSION.capturadoEm;
+    }
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  if (rows.length === 0) {
+    io.stdout.push(`No ISS municipal rows embedded for UF ${uf.toUpperCase()}.`);
+    return EXIT.OK;
+  }
+  for (const row of rows) {
+    io.stdout.push(formatIssMunicipalHuman(row));
+  }
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${ISS_MUNICIPAL_DATA_VERSION.capturadoEm}`);
+  }
+  return EXIT.OK;
+}
 function runIssMunicipalSearch(query, options, io = { stdout: [], stderr: [] }) {
   const trimmed = query?.trim() ?? "";
   if (trimmed.length === 0) {
     io.stderr.push("Missing query. Usage: br-validators iss-municipal search <query>");
     return EXIT.USAGE;
   }
-  const rows = searchIssMunicipal(trimmed, { limit: options.limit });
+  const rows = searchIssMunicipal(trimmed, {
+    limit: options.limit,
+    ...options.uf !== void 0 && options.uf.trim().length > 0 ? { uf: options.uf } : {}
+  });
   emitDisclaimer(options, io);
   if (options.json) {
     io.stdout.push(JSON.stringify({ ok: true, results: rows }, null, 2));
@@ -1429,6 +1495,73 @@ function runPtaxLookup(moeda, data, options, io = { stdout: [], stderr: [] }) {
   return runPtaxLookupCommand(moeda.trim(), data?.trim(), options, io);
 }
 
+// src/commands/ptax/historico.ts
+import {
+  getPtaxHistorico,
+  PTAX_DATA_VERSION as PTAX_DATA_VERSION2
+} from "@br-validators/core/ptax";
+function formatPtaxHistoricoHuman(results) {
+  return results.map(
+    (cotacao) => `${cotacao.dataReferencia} \u2014 compra ${String(cotacao.cotacaoCompra)} / venda ${String(cotacao.cotacaoVenda)}`
+  );
+}
+function runPtaxHistoricoCommand(moeda, desde, ate, options, io = { stdout: [], stderr: [] }) {
+  const trimmedMoeda = moeda.trim();
+  const trimmedDesde = desde.trim();
+  const trimmedAte = ate.trim();
+  if (trimmedMoeda.length === 0) {
+    io.stderr.push("Missing currency code. Pass a 3-letter ISO code (e.g. USD).");
+    return EXIT.USAGE;
+  }
+  if (trimmedDesde.length === 0 || trimmedAte.length === 0) {
+    io.stderr.push("Missing date range. Pass desde and ate as YYYY-MM-DD.");
+    return EXIT.USAGE;
+  }
+  const results = getPtaxHistorico(trimmedMoeda, { desde: trimmedDesde, ate: trimmedAte });
+  if (results.length === 0) {
+    io.stderr.push(
+      `No PTAX quotes in embed for ${trimmedMoeda} between ${trimmedDesde} and ${trimmedAte}`
+    );
+    return EXIT.INVALID;
+  }
+  if (options.json) {
+    const payload = {
+      ok: true,
+      moeda: trimmedMoeda.toUpperCase(),
+      desde: trimmedDesde,
+      ate: trimmedAte,
+      total: results.length,
+      cotacoes: results
+    };
+    if (options.verbose) {
+      payload.capturadoEm = PTAX_DATA_VERSION2.capturadoEm;
+      payload.janelaDiasUteis = PTAX_DATA_VERSION2.janelaDiasUteis;
+    }
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  io.stdout.push(`${trimmedMoeda.toUpperCase()} PTAX historico (${String(results.length)} rows)`);
+  for (const line of formatPtaxHistoricoHuman(results)) {
+    io.stdout.push(line);
+  }
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${PTAX_DATA_VERSION2.capturadoEm}`);
+    io.stdout.push(`janelaDiasUteis: ${String(PTAX_DATA_VERSION2.janelaDiasUteis)}`);
+  }
+  return EXIT.OK;
+}
+function runPtaxHistorico(moeda, desde, ate, options, io = { stdout: [], stderr: [] }) {
+  if (!moeda?.trim()) {
+    io.stderr.push("Missing currency code. Usage: ptax historico <moeda> <desde> <ate>");
+    return EXIT.USAGE;
+  }
+  if (!desde?.trim() || !ate?.trim()) {
+    io.stderr.push("Missing date range. Usage: ptax historico <moeda> <desde> <ate>");
+    return EXIT.USAGE;
+  }
+  return runPtaxHistoricoCommand(moeda.trim(), desde.trim(), ate.trim(), options, io);
+}
+
 // src/commands/brcode.ts
 import {
   BRCODE_OFFICIAL_SOURCE_URL,
@@ -2900,7 +3033,8 @@ var SANITIZABLE_TYPES = [
   "cartao-credito",
   "ean",
   "inscricao-estadual",
-  "inscricao-estadual-produtor-rural"
+  "inscricao-estadual-produtor-rural",
+  "pix"
 ];
 function isSanitizableType(type) {
   return SANITIZABLE_TYPES.includes(type);
@@ -3038,19 +3172,35 @@ function runCompare(type, valueA, valueB, options, io = { stdout: [], stderr: []
 }
 
 // src/commands/batch.ts
-import { batch } from "@br-validators/core";
+import { batch, parseBatchCsv } from "@br-validators/core";
 function parseBatchLines(raw) {
   return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
 }
 function resolveBatchInputs(options) {
   if (options.lines === void 0) {
-    return null;
+    return { ok: false, reason: "missing_input" };
+  }
+  let parsed;
+  if (options.col !== void 0) {
+    const csv = parseBatchCsv(options.lines, {
+      col: options.col,
+      delimiter: options.delimiter,
+      skipHeader: options.skipHeader
+    });
+    if (!csv.ok) {
+      return { ok: false, reason: "parse_error", message: csv.message };
+    }
+    parsed = csv.values;
+  } else {
+    parsed = parseBatchLines(options.lines);
+  }
+  if (parsed.length === 0) {
+    return { ok: false, reason: "empty" };
   }
-  const parsed = parseBatchLines(options.lines);
   if (options.limit !== void 0 && options.limit > 0) {
-    return parsed.slice(0, options.limit);
+    return { ok: true, values: parsed.slice(0, options.limit) };
   }
-  return parsed;
+  return { ok: true, values: parsed };
 }
 function printBatch(result, options, io = { stdout: [], stderr: [] }) {
   if (options.json) {
@@ -3076,18 +3226,20 @@ function runBatch(type, options, io = { stdout: [], stderr: [] }) {
     io.stderr.push(`Unsupported batch type: ${type}`);
     return EXIT.USAGE;
   }
-  const inputs = resolveBatchInputs(options);
-  if (inputs === null) {
-    io.stderr.push("Missing input. Pass --file <path> or pipe one value per line on stdin.");
-    return EXIT.USAGE;
-  }
-  if (inputs.length === 0) {
-    io.stderr.push("No values to validate.");
+  const resolved = resolveBatchInputs(options);
+  if (!resolved.ok) {
+    if (resolved.reason === "missing_input") {
+      io.stderr.push("Missing input. Pass --file <path> or pipe one value per line on stdin.");
+    } else if (resolved.reason === "empty") {
+      io.stderr.push("No values to validate.");
+    } else {
+      io.stderr.push(resolved.message);
+    }
     return EXIT.USAGE;
   }
   const uf = options.uf?.toUpperCase();
   const platformOptions = uf ? { uf } : {};
-  const result = batch(inputs, type, platformOptions);
+  const result = batch(resolved.values, type, platformOptions);
   return printBatch(result, options, io);
 }
 
@@ -3762,7 +3914,10 @@ function handleBatchCli(type, opts, io = { stdout: [], stderr: [] }) {
       quiet: Boolean(opts.quiet),
       uf: opts.uf,
       lines,
-      limit: opts.limit
+      limit: opts.limit,
+      col: opts.col,
+      delimiter: opts.delimiter,
+      skipHeader: opts.skipHeader
     },
     io
   );
@@ -3924,6 +4079,14 @@ function handleSelicCli(opts, io = { stdout: [], stderr: [] }) {
     date: opts.date
   }, io);
 }
+function handleIssMunicipalListCli(opts, io = { stdout: [], stderr: [] }) {
+  return runIssMunicipalList({
+    json: Boolean(opts.json),
+    verbose: Boolean(opts.verbose),
+    uf: opts.uf,
+    limit: opts.limit
+  }, io);
+}
 function handleIssMunicipalLookupCli(codigo, opts, io = { stdout: [], stderr: [] }) {
   return runIssMunicipalLookup(codigo, { json: Boolean(opts.json), verbose: Boolean(opts.verbose) }, io);
 }
@@ -3931,7 +4094,8 @@ function handleIssMunicipalSearchCli(query, opts, io = { stdout: [], stderr: []
   return runIssMunicipalSearch(query, {
     json: Boolean(opts.json),
     verbose: Boolean(opts.verbose),
-    limit: opts.limit
+    limit: opts.limit,
+    uf: opts.uf
   }, io);
 }
 function handleIssMunicipalResolveCli(uf, nome, opts, io = { stdout: [], stderr: [] }) {
@@ -3940,6 +4104,15 @@ function handleIssMunicipalResolveCli(uf, nome, opts, io = { stdout: [], stderr:
 function handlePtaxLookupCli(moeda, data, opts, io = { stdout: [], stderr: [] }) {
   return runPtaxLookup(moeda, data, { json: Boolean(opts.json), verbose: Boolean(opts.verbose) }, io);
 }
+function handlePtaxHistoricoCli(moeda, desde, ate, opts, io = { stdout: [], stderr: [] }) {
+  return runPtaxHistorico(
+    moeda,
+    desde,
+    ate,
+    { json: Boolean(opts.json), verbose: Boolean(opts.verbose) },
+    io
+  );
+}
 function writeCliIo(io) {
   for (const line of io.stdout) console.log(line);
   for (const line of io.stderr) console.error(line);
@@ -4263,6 +4436,11 @@ function createProgram() {
     writeCliIo(io);
   });
   const issMunicipal = program.command("iss-municipal").description("Municipal ISS al\xEDquotas \u2014 partial embed (estimation only, not NFSe)");
+  issMunicipal.command("list").description("List embedded municipalities for a UF").requiredOption("--uf <uf>", "UF sigla (2 letters)").option("--json", "JSON output").option("--verbose", "Include dataset capture date in JSON responses").option("--limit <n>", "Maximum rows", (value) => Number(value)).action((opts) => {
+    const io = { stdout: [], stderr: [] };
+    process.exitCode = handleIssMunicipalListCli(opts, io);
+    writeCliIo(io);
+  });
   issMunicipal.command("lookup").description("Resolve ISS band by IBGE municipality code").argument("<codigoIbge>", "IBGE municipality code (7 digits)").option("--json", "JSON output").option("--verbose", "Include leiUrl, estimativa flag, and dataset capture date").action((codigoIbge, opts) => {
     const io = { stdout: [], stderr: [] };
     process.exitCode = handleIssMunicipalLookupCli(codigoIbge, opts, io);
@@ -4273,7 +4451,7 @@ function createProgram() {
     process.exitCode = handleIssMunicipalResolveCli(uf, nome, opts, io);
     writeCliIo(io);
   });
-  issMunicipal.command("search").description("Search embedded municipalities by name, UF, or IBGE code fragment").argument("<query>", "Search query").option("--json", "JSON output").option("--verbose", "Include dataset capture date in JSON responses").option("--limit <n>", "Maximum rows", (value) => Number(value)).action((query, opts) => {
+  issMunicipal.command("search").description("Search embedded municipalities by name, UF, or IBGE code fragment").argument("<query>", "Search query").option("--uf <uf>", "Scope search to a UF").option("--json", "JSON output").option("--verbose", "Include dataset capture date in JSON responses").option("--limit <n>", "Maximum rows", (value) => Number(value)).action((query, opts) => {
     const io = { stdout: [], stderr: [] };
     process.exitCode = handleIssMunicipalSearchCli(query, opts, io);
     writeCliIo(io);
@@ -4284,6 +4462,13 @@ function createProgram() {
     process.exitCode = handlePtaxLookupCli(moeda, data, opts, io);
     writeCliIo(io);
   });
+  ptax.command("historico").description("List embedded Fechamento PTAX rows for a currency and date range").argument("<moeda>", "ISO 4217 currency code (e.g. USD)").argument("<desde>", "Range start \u2014 YYYY-MM-DD or MM-DD-YYYY").argument("<ate>", "Range end \u2014 YYYY-MM-DD or MM-DD-YYYY").option("--json", "JSON output").option("--verbose", "Include capturadoEm and janelaDiasUteis in JSON responses").action(
+    (moeda, desde, ate, opts) => {
+      const io = { stdout: [], stderr: [] };
+      process.exitCode = handlePtaxHistoricoCli(moeda, desde, ate, opts, io);
+      writeCliIo(io);
+    }
+  );
   const cst = program.command("cst").description("RFB SPED CST \u2014 offline ICMS, IPI, PIS, COFINS tables");
   cst.command("lookup").description("Resolve CST by code and tax").argument("<codigo>", "CST code").requiredOption("--tax <tax>", "Tax table: icms | ipi | pis | cofins").option("--json", "JSON output").option("--verbose", "Include dataset capture date").action((codigo, opts) => {
     const io = { stdout: [], stderr: [] };
@@ -4326,7 +4511,7 @@ function createProgram() {
     process.exitCode = handleCompareCli(type, valueA, valueB.join(" ") || void 0, opts, io);
     writeCliIo(io);
   });
-  program.command("batch <type>").description("Bulk validate values from stdin or --file").option("--uf <uf>", "State code (required for inscricao-estadual, rg, titulo-eleitor)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("-f, --file <path>", "Read values from file (one per line)").option("--limit <n>", "Max number of values to process", (v) => Number(v)).action((type, opts) => {
+  program.command("batch <type>").description("Bulk validate values from stdin or --file").option("--uf <uf>", "State code (required for inscricao-estadual, rg, titulo-eleitor)").option("--json", "JSON output").option("-q, --quiet", "Exit code only").option("-f, --file <path>", "Read values from file (one per line, or CSV with --col)").option("--col <name>", "CSV column name or zero-based index (requires --file)").option("--delimiter <char>", "CSV delimiter (default: comma)").option("--skip-header", "Treat first CSV row as header (default: true)", true).option("--no-skip-header", "Parse CSV without header row").option("--limit <n>", "Max number of values to process", (v) => Number(v)).action((type, opts) => {
     const io = { stdout: [], stderr: [] };
     process.exitCode = handleBatchCli(type, opts, io);
     writeCliIo(io);

package/dist/run-captured.js

@@ -42,6 +42,10 @@ import {
   CFOP_DATA_VERSION,
   lookupCfopPorCodigo
 } from "@br-validators/core/cfop";
+import {
+  CSOSN_DATA_VERSION,
+  lookupCsosnPorCodigo
+} from "@br-validators/core/csosn";
 import { NCM_DATA_VERSION, lookupNcmPorCodigo } from "@br-validators/core/ncm";
 import { CBO_DATA_VERSION, lookupCboPorCodigo } from "@br-validators/core/cbo";
 import {
@@ -54,6 +58,7 @@ var REFERENCE_LOOKUP_COMMANDS = [
   "cest",
   "cnae",
   "cfop",
+  "csosn",
   "ncm",
   "cbo",
   "moedas",
@@ -62,7 +67,7 @@ var REFERENCE_LOOKUP_COMMANDS = [
   "portos",
   "aeroportos"
 ];
-var REFERENCE_SEARCH_COMMANDS = ["cnae", "cfop", "ncm", "cbo"];
+var REFERENCE_SEARCH_COMMANDS = ["cnae", "cfop", "csosn", "ncm", "cbo"];
 function lookupAeroporto(input) {
   const normalized = input.trim().toUpperCase();
   if (normalized.length === 0) {
@@ -132,6 +137,17 @@ var REFERENCE_LOOKUP_MODULES = {
       return `${row.codigo} \u2014 ${row.descricao}`;
     }
   },
+  csosn: {
+    command: "csosn",
+    description: "CONFAZ CSOSN Simples Nacional \u2014 offline lookup",
+    resultKey: "csosn",
+    capturadoEm: CSOSN_DATA_VERSION.capturadoEm,
+    lookup: (input) => lookupCsosnPorCodigo(input),
+    formatHuman: (result) => {
+      const row = result;
+      return `${row.codigo} \u2014 ${row.descricao}`;
+    }
+  },
   ncm: {
     command: "ncm",
     description: "Siscomex NCM Mercosur codes \u2014 offline lookup",
@@ -221,15 +237,18 @@ function isReferenceSearchCommand(value) {
 
 // src/commands/reference-lookup/validate.ts
 import { validateCfop } from "@br-validators/core/cfop";
+import { validateCsosn } from "@br-validators/core/csosn";
 import { validateNcm } from "@br-validators/core/ncm";
-var REFERENCE_VALIDATE_COMMANDS = ["ncm", "cfop"];
+var REFERENCE_VALIDATE_COMMANDS = ["ncm", "cfop", "csosn"];
 var VALIDATORS = {
   ncm: validateNcm,
-  cfop: validateCfop
+  cfop: validateCfop,
+  csosn: validateCsosn
 };
 var CAPTURED_AT = {
   ncm: "ncm",
-  cfop: "cfop"
+  cfop: "cfop",
+  csosn: "csosn"
 };
 function emitFailure(result, options, io) {
   if (options.json) {
@@ -438,6 +457,7 @@ function runReferenceLookup(command, value, options, io = { stdout: [], stderr:
 import { searchCbo } from "@br-validators/core/cbo";
 import { searchCnaes } from "@br-validators/core/cnaes";
 import { searchCfop } from "@br-validators/core/cfop";
+import { searchCsosn } from "@br-validators/core/csosn";
 import { searchNcm } from "@br-validators/core/ncm";
 function runSearch(command, query, limit) {
   switch (command) {
@@ -445,6 +465,8 @@ function runSearch(command, query, limit) {
       return searchCnaes(query, { limit });
     case "cfop":
       return searchCfop(query, { limit });
+    case "csosn":
+      return searchCsosn(query, { limit });
     case "ncm":
       return searchNcm(query, { limit });
     case "cbo":
@@ -1292,12 +1314,19 @@ function runSelicCommand(options, io = { stdout: [], stderr: [] }) {
 
 // src/commands/iss-municipal/index.ts
 import {
-  getIssMunicipalPorIbge,
+  getIssMunicipalPorUf,
   getIssMunicipalPorUfMunicipio,
   ISS_MUNICIPAL_DATA_VERSION,
   ISS_MUNICIPAL_ESTIMATION_WARNING,
+  lookupIssMunicipalPorIbge,
   searchIssMunicipal
 } from "@br-validators/core/iss-municipal";
+function sliceRows2(rows, limit) {
+  if (limit === void 0 || !Number.isFinite(limit) || limit <= 0) {
+    return rows;
+  }
+  return rows.slice(0, limit);
+}
 function formatIssMunicipalHuman(row) {
   return `${row.nome}/${row.uf} \u2014 ISS ${String(row.aliquotaMin)}%\u2013${String(row.aliquotaMax)}%`;
 }
@@ -1313,7 +1342,7 @@ function runIssMunicipalLookup(codigo, options, io = { stdout: [], stderr: [] })
     io.stderr.push("Missing IBGE code. Usage: br-validators iss-municipal lookup <codigoIbge>");
     return EXIT.USAGE;
   }
-  const result = getIssMunicipalPorIbge(trimmed);
+  const result = lookupIssMunicipalPorIbge(trimmed);
   if (result === void 0) {
     io.stderr.push(`ISS municipal row not found for IBGE code ${trimmed}`);
     return EXIT.INVALID;
@@ -1331,6 +1360,7 @@ function runIssMunicipalLookup(codigo, options, io = { stdout: [], stderr: [] })
     return EXIT.OK;
   }
   io.stdout.push(formatIssMunicipalHuman(result));
+  io.stdout.push(`fonte: ${result.fonte}`);
   io.stdout.push(`warning: ${result.warning}`);
   if (options.verbose) {
     io.stdout.push(`leiUrl: ${result.leiUrl}`);
@@ -1339,13 +1369,49 @@ function runIssMunicipalLookup(codigo, options, io = { stdout: [], stderr: [] })
   }
   return EXIT.OK;
 }
+function runIssMunicipalList(options, io = { stdout: [], stderr: [] }) {
+  const uf = options.uf?.trim() ?? "";
+  if (uf.length === 0) {
+    io.stderr.push("Missing UF. Usage: br-validators iss-municipal list --uf <UF>");
+    return EXIT.USAGE;
+  }
+  const rows = sliceRows2(getIssMunicipalPorUf(uf), options.limit);
+  emitDisclaimer(options, io);
+  if (options.json) {
+    const payload = {
+      ok: true,
+      uf: uf.toUpperCase(),
+      total: rows.length,
+      results: rows
+    };
+    if (options.verbose) {
+      payload.capturadoEm = ISS_MUNICIPAL_DATA_VERSION.capturadoEm;
+    }
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  if (rows.length === 0) {
+    io.stdout.push(`No ISS municipal rows embedded for UF ${uf.toUpperCase()}.`);
+    return EXIT.OK;
+  }
+  for (const row of rows) {
+    io.stdout.push(formatIssMunicipalHuman(row));
+  }
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${ISS_MUNICIPAL_DATA_VERSION.capturadoEm}`);
+  }
+  return EXIT.OK;
+}
 function runIssMunicipalSearch(query, options, io = { stdout: [], stderr: [] }) {
   const trimmed = query?.trim() ?? "";
   if (trimmed.length === 0) {
     io.stderr.push("Missing query. Usage: br-validators iss-municipal search <query>");
     return EXIT.USAGE;
   }
-  const rows = searchIssMunicipal(trimmed, { limit: options.limit });
+  const rows = searchIssMunicipal(trimmed, {
+    limit: options.limit,
+    ...options.uf !== void 0 && options.uf.trim().length > 0 ? { uf: options.uf } : {}
+  });
   emitDisclaimer(options, io);
   if (options.json) {
     io.stdout.push(JSON.stringify({ ok: true, results: rows }, null, 2));
@@ -1424,6 +1490,73 @@ function runPtaxLookup(moeda, data, options, io = { stdout: [], stderr: [] }) {
   return runPtaxLookupCommand(moeda.trim(), data?.trim(), options, io);
 }
 
+// src/commands/ptax/historico.ts
+import {
+  getPtaxHistorico,
+  PTAX_DATA_VERSION as PTAX_DATA_VERSION2
+} from "@br-validators/core/ptax";
+function formatPtaxHistoricoHuman(results) {
+  return results.map(
+    (cotacao) => `${cotacao.dataReferencia} \u2014 compra ${String(cotacao.cotacaoCompra)} / venda ${String(cotacao.cotacaoVenda)}`
+  );
+}
+function runPtaxHistoricoCommand(moeda, desde, ate, options, io = { stdout: [], stderr: [] }) {
+  const trimmedMoeda = moeda.trim();
+  const trimmedDesde = desde.trim();
+  const trimmedAte = ate.trim();
+  if (trimmedMoeda.length === 0) {
+    io.stderr.push("Missing currency code. Pass a 3-letter ISO code (e.g. USD).");
+    return EXIT.USAGE;
+  }
+  if (trimmedDesde.length === 0 || trimmedAte.length === 0) {
+    io.stderr.push("Missing date range. Pass desde and ate as YYYY-MM-DD.");
+    return EXIT.USAGE;
+  }
+  const results = getPtaxHistorico(trimmedMoeda, { desde: trimmedDesde, ate: trimmedAte });
+  if (results.length === 0) {
+    io.stderr.push(
+      `No PTAX quotes in embed for ${trimmedMoeda} between ${trimmedDesde} and ${trimmedAte}`
+    );
+    return EXIT.INVALID;
+  }
+  if (options.json) {
+    const payload = {
+      ok: true,
+      moeda: trimmedMoeda.toUpperCase(),
+      desde: trimmedDesde,
+      ate: trimmedAte,
+      total: results.length,
+      cotacoes: results
+    };
+    if (options.verbose) {
+      payload.capturadoEm = PTAX_DATA_VERSION2.capturadoEm;
+      payload.janelaDiasUteis = PTAX_DATA_VERSION2.janelaDiasUteis;
+    }
+    io.stdout.push(JSON.stringify(payload, null, 2));
+    return EXIT.OK;
+  }
+  io.stdout.push(`${trimmedMoeda.toUpperCase()} PTAX historico (${String(results.length)} rows)`);
+  for (const line of formatPtaxHistoricoHuman(results)) {
+    io.stdout.push(line);
+  }
+  if (options.verbose) {
+    io.stdout.push(`capturadoEm: ${PTAX_DATA_VERSION2.capturadoEm}`);
+    io.stdout.push(`janelaDiasUteis: ${String(PTAX_DATA_VERSION2.janelaDiasUteis)}`);
+  }
+  return EXIT.OK;
+}
+function runPtaxHistorico(moeda, desde, ate, options, io = { stdout: [], stderr: [] }) {
+  if (!moeda?.trim()) {
+    io.stderr.push("Missing currency code. Usage: ptax historico <moeda> <desde> <ate>");
+    return EXIT.USAGE;
+  }
+  if (!desde?.trim() || !ate?.trim()) {
+    io.stderr.push("Missing date range. Usage: ptax historico <moeda> <desde> <ate>");
+    return EXIT.USAGE;
+  }
+  return runPtaxHistoricoCommand(moeda.trim(), desde.trim(), ate.trim(), options, io);
+}
+
 // src/commands/brcode.ts
 import {
   BRCODE_OFFICIAL_SOURCE_URL,
@@ -2895,7 +3028,8 @@ var SANITIZABLE_TYPES = [
   "cartao-credito",
   "ean",
   "inscricao-estadual",
-  "inscricao-estadual-produtor-rural"
+  "inscricao-estadual-produtor-rural",
+  "pix"
 ];
 function isSanitizableType(type) {
   return SANITIZABLE_TYPES.includes(type);
@@ -3033,19 +3167,35 @@ function runCompare(type, valueA, valueB, options, io = { stdout: [], stderr: []
 }
 
 // src/commands/batch.ts
-import { batch } from "@br-validators/core";
+import { batch, parseBatchCsv } from "@br-validators/core";
 function parseBatchLines(raw) {
   return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
 }
 function resolveBatchInputs(options) {
   if (options.lines === void 0) {
-    return null;
+    return { ok: false, reason: "missing_input" };
+  }
+  let parsed;
+  if (options.col !== void 0) {
+    const csv = parseBatchCsv(options.lines, {
+      col: options.col,
+      delimiter: options.delimiter,
+      skipHeader: options.skipHeader
+    });
+    if (!csv.ok) {
+      return { ok: false, reason: "parse_error", message: csv.message };
+    }
+    parsed = csv.values;
+  } else {
+    parsed = parseBatchLines(options.lines);
+  }
+  if (parsed.length === 0) {
+    return { ok: false, reason: "empty" };
   }
-  const parsed = parseBatchLines(options.lines);
   if (options.limit !== void 0 && options.limit > 0) {
-    return parsed.slice(0, options.limit);
+    return { ok: true, values: parsed.slice(0, options.limit) };
   }
-  return parsed;
+  return { ok: true, values: parsed };
 }
 function printBatch(result, options, io = { stdout: [], stderr: [] }) {
   if (options.json) {
@@ -3071,18 +3221,20 @@ function runBatch(type, options, io = { stdout: [], stderr: [] }) {
     io.stderr.push(`Unsupported batch type: ${type}`);
     return EXIT.USAGE;
   }
-  const inputs = resolveBatchInputs(options);
-  if (inputs === null) {
-    io.stderr.push("Missing input. Pass --file <path> or pipe one value per line on stdin.");
-    return EXIT.USAGE;
-  }
-  if (inputs.length === 0) {
-    io.stderr.push("No values to validate.");
+  const resolved = resolveBatchInputs(options);
+  if (!resolved.ok) {
+    if (resolved.reason === "missing_input") {
+      io.stderr.push("Missing input. Pass --file <path> or pipe one value per line on stdin.");
+    } else if (resolved.reason === "empty") {
+      io.stderr.push("No values to validate.");
+    } else {
+      io.stderr.push(resolved.message);
+    }
     return EXIT.USAGE;
   }
   const uf = options.uf?.toUpperCase();
   const platformOptions = uf ? { uf } : {};
-  const result = batch(inputs, type, platformOptions);
+  const result = batch(resolved.values, type, platformOptions);
   return printBatch(result, options, io);
 }
 
@@ -3757,7 +3909,10 @@ function handleBatchCli(type, opts, io = { stdout: [], stderr: [] }) {
       quiet: Boolean(opts.quiet),
       uf: opts.uf,
       lines,
-      limit: opts.limit
+      limit: opts.limit,
+      col: opts.col,
+      delimiter: opts.delimiter,
+      skipHeader: opts.skipHeader
     },
     io
   );
@@ -3919,6 +4074,14 @@ function handleSelicCli(opts, io = { stdout: [], stderr: [] }) {
     date: opts.date
   }, io);
 }
+function handleIssMunicipalListCli(opts, io = { stdout: [], stderr: [] }) {
+  return runIssMunicipalList({
+    json: Boolean(opts.json),
+    verbose: Boolean(opts.verbose),
+    uf: opts.uf,
+    limit: opts.limit
+  }, io);
+}
 function handleIssMunicipalLookupCli(codigo, opts, io = { stdout: [], stderr: [] }) {
   return runIssMunicipalLookup(codigo, { json: Boolean(opts.json), verbose: Boolean(opts.verbose) }, io);
 }
@@ -3926,7 +4089,8 @@ function handleIssMunicipalSearchCli(query, opts, io = { stdout: [], stderr: []
   return runIssMunicipalSearch(query, {
     json: Boolean(opts.json),
     verbose: Boolean(opts.verbose),
-    limit: opts.limit
+    limit: opts.limit,
+    uf: opts.uf
   }, io);
 }
 function handleIssMunicipalResolveCli(uf, nome, opts, io = { stdout: [], stderr: [] }) {
@@ -3935,6 +4099,15 @@ function handleIssMunicipalResolveCli(uf, nome, opts, io = { stdout: [], stderr:
 function handlePtaxLookupCli(moeda, data, opts, io = { stdout: [], stderr: [] }) {
   return runPtaxLookup(moeda, data, { json: Boolean(opts.json), verbose: Boolean(opts.verbose) }, io);
 }
+function handlePtaxHistoricoCli(moeda, desde, ate, opts, io = { stdout: [], stderr: [] }) {
+  return runPtaxHistorico(
+    moeda,
+    desde,
+    ate,
+    { json: Boolean(opts.json), verbose: Boolean(opts.verbose) },
+    io
+  );
+}
 
 // src/argv-dispatch.ts
 var STANDARD_ACTIONS = ["validate", "format", "strip"];
@@ -4054,7 +4227,7 @@ function dispatchArgv(tokens, io) {
   if (tokens.length === 0 || tokens.includes("--help") || tokens.includes("-h")) {
     io.stdout.push("br-validators \u2014 100% open-source Brazilian document validators");
     io.stdout.push("Usage: br-validators <command> ...");
-    io.stdout.push("Commands: list \xB7 cpf \xB7 cnpj \xB7 cep \xB7 telefone \xB7 cnh \xB7 renavam \xB7 titulo-eleitor \xB7 processo-judicial \xB7 rg \xB7 nfe-chave \xB7 brcode \xB7 placa \xB7 pis-pasep \xB7 cnis \xB7 pix \xB7 boleto \xB7 cartao \xB7 cartao-credito \xB7 ean \xB7 ie \xB7 bancos \xB7 ibge \xB7 feriados \xB7 inss \xB7 irpf \xB7 tse-municipios \xB7 ddd \xB7 nfe-cuf \xB7 selic \xB7 iss-municipal \xB7 ptax \xB7 cst \xB7 natureza-juridica \xB7 nbs \xB7 cest \xB7 cnae \xB7 cfop \xB7 ncm \xB7 cbo \xB7 moedas \xB7 paises-bacen \xB7 incoterms \xB7 portos \xB7 aeroportos \xB7 detect \xB7 sanitize \xB7 mask \xB7 compare \xB7 batch \xB7 diff \xB7 generate");
+    io.stdout.push("Commands: list \xB7 cpf \xB7 cnpj \xB7 cep \xB7 telefone \xB7 cnh \xB7 renavam \xB7 titulo-eleitor \xB7 processo-judicial \xB7 rg \xB7 nfe-chave \xB7 brcode \xB7 placa \xB7 pis-pasep \xB7 cnis \xB7 pix \xB7 boleto \xB7 cartao \xB7 cartao-credito \xB7 ean \xB7 ie \xB7 bancos \xB7 ibge \xB7 feriados \xB7 inss \xB7 irpf \xB7 tse-municipios \xB7 ddd \xB7 nfe-cuf \xB7 selic \xB7 iss-municipal \xB7 ptax \xB7 cst \xB7 csosn \xB7 natureza-juridica \xB7 nbs \xB7 cest \xB7 cnae \xB7 cfop \xB7 ncm \xB7 cbo \xB7 moedas \xB7 paises-bacen \xB7 incoterms \xB7 portos \xB7 aeroportos \xB7 detect \xB7 sanitize \xB7 mask \xB7 compare \xB7 batch \xB7 diff \xB7 generate");
     return EXIT.OK;
   }
   if (tokens.includes("--version") || tokens.includes("-V")) {
@@ -4287,6 +4460,9 @@ function dispatchArgv(tokens, io) {
         const value = rest[1];
         return handleIssMunicipalLookupCli(value, opts, io);
       }
+      if (action === "list") {
+        return handleIssMunicipalListCli(opts, io);
+      }
       if (action === "resolve") {
         const uf = rest[1];
         const nome = rest.slice(2).join(" ") || void 0;
@@ -4296,7 +4472,7 @@ function dispatchArgv(tokens, io) {
         const value = rest.slice(1).join(" ") || void 0;
         return handleIssMunicipalSearchCli(value, opts, io);
       }
-      return usage(io, "Expected: iss-municipal lookup|resolve|search <args>");
+      return usage(io, "Expected: iss-municipal lookup|list|resolve|search <args>");
     }
     case "ptax": {
       const action = rest[0];
@@ -4305,7 +4481,13 @@ function dispatchArgv(tokens, io) {
         const data = rest.slice(2).join(" ") || void 0;
         return handlePtaxLookupCli(moeda, data, opts, io);
       }
-      return usage(io, "Expected: ptax lookup <moeda> [data]");
+      if (action === "historico") {
+        const moeda = rest[1];
+        const desde = rest[2];
+        const ate = rest[3];
+        return handlePtaxHistoricoCli(moeda, desde, ate, opts, io);
+      }
+      return usage(io, "Expected: ptax lookup <moeda> [data] | ptax historico <moeda> <desde> <ate>");
     }
     case "cst": {
       const action = rest[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@br-validators/cli",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "CLI for @br-validators/core — CPF, CNPJ, NF-e, IE, PIX, boleto + detect/sanitize/generate",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "commander": "^13.1.0",
-    "@br-validators/core": "1.9.0"
+    "@br-validators/core": "1.10.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.21",