feat(ibs-cbs): add the CST-IBS/CBS and cClassTrib validators and lookups

CONTRIBUTING.md

@@ -73,9 +73,9 @@ but the few rules below hold everywhere:
   they call.
 - `src/_internals/` holds the helpers shared between utilities (check-digit arithmetic, `mod10`/
   `mod11`, TLV parsing for Pix, sanitizers). `src/_internals/constants/` holds the datasets
-  (banks, municipalities, CNAE, CBO, CFOP, NCM, NBS, the LC 116/2003 service list, legal natures),
-  generated by the `scripts/` from their official sources and refreshed by the `Update datasets`
-  workflow through a pull request, never edited by hand.
+  (banks, municipalities, CNAE, CBO, CFOP, NCM, NBS, the LC 116/2003 service list, legal natures,
+  the IBS/CBS tables), generated by the `scripts/` from their official sources and refreshed by the
+  `Update datasets` workflow through a pull request, never edited by hand.
 - Utilities are synchronous, stateless and side-effect free: input in, value out, no globals, no
   environment access, no dynamic code. The two exceptions are `getAddressInfoByCep` and
   `getCepInfoByAddress`, the only utilities that do I/O: they query public CEP APIs (BrasilAPI,

context7.json

@@ -30,7 +30,7 @@
 	"rules": [
 		"The package has zero runtime dependencies and ships as ESM plus a UMD build; nothing else needs to be installed to use it.",
 		"Import from the root: import { isValidCpf } from '@brazilian-utils/brazilian-utils'. Every util is also a kebab-case subpath, e.g. '@brazilian-utils/brazilian-utils/is-valid-cpf'.",
-		"Use the subpaths to lazy-load the dataset-backed utils (getMunicipalities, getMunicipalityByCode, getCnae, getCbo, getCfop, isValidNcm, getBanks, getNbs, isValidNbs, getServiceItem, isValidServiceItem): each one embeds a large official table.",
+		"Use the subpaths to lazy-load the dataset-backed utils (getMunicipalities, getMunicipalityByCode, getCnae, getCbo, getCfop, getClassTrib, isValidNcm, getBanks, getNbs, isValidNbs, getServiceItem, isValidServiceItem): each one embeds a large official table.",
 		"Never import the same util from both the root and its subpath in one app: a bundler treats them as two unrelated modules and bundles the dataset twice.",
 		"Public functions never throw on bad input (null, undefined, wrong type): isValid* return false, format* and parse* return '', single-item getters return null, list getters return [].",
 		"The only utils that reject are the async getAddressInfoByCep (GetAddressInfoByCepError: NotFound, Validation, Service) and getCepInfoByAddress (GetCepInfoByAddressError: NotFound, Validation).",

docs/getting-started.md

@@ -75,6 +75,7 @@ A few utils embed an official dataset and weigh far more than everything else co
 | `isValidCnae` · `getCnae` | CNAE-Subclasses 2.3 | 93.9 KB | 21.2 KB |
 | `isValidNbs` · `getNbs` | NBS 2.0 (Nomenclatura Brasileira de Serviços) descriptions | 81.8 KB | 13.8 KB |
 | `isValidCfop` · `getCfop` | CFOP operation descriptions | 68.9 KB | 6.9 KB |
+| `getClassTrib` | cClassTrib (IBS/CBS) names and descriptions | 50.8 KB | 9.6 KB |
 | `getBanks` · `getBankByCode` · `getBankByIspb` | Banco Central STR participants (COMPE + ISPB) | 38.3 - 38.6 KB | 9.5 - 9.7 KB |
 | `isValidServiceItem` · `getServiceItem` | Service list of the Lei Complementar 116/2003 | 27.2 KB | 8.9 KB |
 

docs/pt-br/getting-started.md

@@ -75,6 +75,7 @@ Alguns utilitários embutem uma base de dados oficial e pesam muito mais que tod
 | `isValidCnae` · `getCnae` | CNAE-Subclasses 2.3 | 93,9 KB | 21,2 KB |
 | `isValidNbs` · `getNbs` | descrições da NBS 2.0 (Nomenclatura Brasileira de Serviços) | 81,8 KB | 13,8 KB |
 | `isValidCfop` · `getCfop` | descrições das operações do CFOP | 68,9 KB | 6,9 KB |
+| `getClassTrib` | nomes e descrições do cClassTrib (IBS/CBS) | 50,8 KB | 9,6 KB |
 | `getBanks` · `getBankByCode` · `getBankByIspb` | participantes do STR do Banco Central (COMPE + ISPB) | 38,3 - 38,6 KB | 9,5 - 9,7 KB |
 | `isValidServiceItem` · `getServiceItem` | lista de serviços da Lei Complementar 116/2003 | 27,2 KB | 8,9 KB |
 

docs/pt-br/utilities.md

@@ -3053,6 +3053,92 @@ isValidCsosn(-101); // false (não é um inteiro seguro não negativo)
 
 Fonte: [Anexo III-A consolidado do Convênio SINIEF s/nº 1970](https://www.confaz.fazenda.gov.br/legislacao/ajustes/sinief/cvsn_70) e [Ajuste SINIEF 03/2010](https://www.confaz.fazenda.gov.br/legislacao/ajustes/2010/aj_003_10).
 
+### isValidCstIbsCbs
+
+Valida um CST-IBS/CBS (Código de Situação Tributária do IBS e da CBS) contra a tabela oficial, o código que o campo `CST` do grupo `IBSCBS` leva nos documentos fiscais eletrônicos da reforma tributária (Lei Complementar nº 214/2025): NF-e, NFC-e, CT-e, NFS-e e os demais.
+
+- Os códigos vigentes são `000`, `010`, `011`, `200`, `220`, `221`, `222`, `400`, `410`, `510`, `515`, `550`, `620`, `800`, `810`, `811`, `820` e `830`.
+- É uma função própria, não um `tax` de `isValidCst`: IBS e CBS compartilham uma única tabela, seus códigos de 3 dígitos colidem com a forma origem + Tabela B do ICMS (`000`, `200`), e `isValidCst` sem `tax` aceita um código de qualquer tabela, então incluir esta mudaria o que esse padrão aceita.
+- Aceita uma string de dígitos puros, com espaços opcionais nas extremidades, ou um inteiro seguro não negativo. O campo é numérico com 3 dígitos e não tem máscara, então qualquer outra string é rejeitada em vez de ter os dígitos pinçados.
+- Um valor com menos de 3 dígitos é completado com zeros à esquerda, como string ou como número, já que os códigos começam com zeros que um campo numérico descarta: `0`, `'0'` e `'000'` são todos o código `000`.
+
+```javascript
+import { isValidCstIbsCbs } from '@brazilian-utils/brazilian-utils';
+
+isValidCstIbsCbs('000'); // true
+isValidCstIbsCbs(410); // true
+isValidCstIbsCbs(10); // true (completado para '010')
+isValidCstIbsCbs('100'); // false
+isValidCstIbsCbs('cst200'); // false (não é uma forma documentada)
+isValidCstIbsCbs(-200); // false (não é um inteiro seguro não negativo)
+```
+
+### getCstIbsCbs
+
+Busca um CST-IBS/CBS e retorna a descrição que a tabela oficial de CST dá a ele. O resultado é um registro `CstIbsCbs`: `{ code, description }`.
+
+- Valem a mesma tabela e as mesmas regras de entrada de `isValidCstIbsCbs`. Retorna `null` quando o código é desconhecido ou o valor não está em uma forma documentada.
+
+```javascript
+import { getCstIbsCbs } from '@brazilian-utils/brazilian-utils';
+
+getCstIbsCbs('000'); // { code: '000', description: 'Tributação integral' }
+getCstIbsCbs(410); // { code: '410', description: 'Imunidade e não incidência' }
+getCstIbsCbs(10); // { code: '010', description: 'Tributação com alíquotas uniformes' }
+getCstIbsCbs('100'); // null
+getCstIbsCbs('cst200'); // null (não é uma forma documentada)
+```
+
+### isValidClassTrib
+
+Valida um cClassTrib (Código de Classificação Tributária do IBS e da CBS) contra a tabela oficial, o código que o campo `cClassTrib` leva ao lado do CST-IBS/CBS.
+
+- **Opções** (`IsValidClassTribOptions`): `cst` é o CST-IBS/CBS que o documento leva, validado também contra a classificação. Omita-o para validar só o cClassTrib.
+- Toda classificação pertence a exatamente um CST-IBS/CBS, os 3 primeiros dígitos do seu código, e um documento que leva um cClassTrib com outro CST é rejeitado (rejeição 1024, "Classificação Tributária do IBS e da CBS incompatível com o CST informado"). Um `cst` informado que não seja o CST da classificação, seja ele qual for, torna o resultado `false`.
+- Só contam as classificações vigentes: o Informe Técnico 2025.002 exclui uma classificação encerrando sua vigência (`dFimVig`), como a v.1.60 fez com `220001`, `220002` e `220003`, e essas são rejeitadas. São 161 vigentes na versão publicada em 23/06/2026.
+- Aceita uma string de dígitos puros, com espaços opcionais nas extremidades, ou um inteiro seguro não negativo. O campo é numérico com 6 dígitos e não tem máscara, então qualquer outra string é rejeitada.
+- Um valor com menos de 6 dígitos é completado com zeros à esquerda: `1`, `'1'` e `'000001'` são todos o código `000001`. `cst` é lido da mesma forma, completado para 3 dígitos.
+- Só a lista de códigos entra no bundle com esta função, não as descrições que `getClassTrib` retorna.
+
+```javascript
+import { isValidClassTrib } from '@brazilian-utils/brazilian-utils';
+
+isValidClassTrib('200001'); // true
+isValidClassTrib(1); // true (completado para '000001')
+isValidClassTrib('200001', { cst: '200' }); // true
+isValidClassTrib('200001', { cst: '000' }); // false (a classificação pertence ao CST 200)
+isValidClassTrib('999999'); // false
+isValidClassTrib('220001'); // false (excluído pelo Informe Técnico 2025.002 v.1.60)
+isValidClassTrib('c200001'); // false (não é uma forma documentada)
+```
+
+### getClassTrib
+
+Busca um cClassTrib e retorna a sua classificação oficial. O resultado é um registro `ClassTrib`: `{ code, cst, name, description }`.
+
+- Valem a mesma tabela e as mesmas regras de leitura do código de `isValidClassTrib`. Retorna `null` quando o código é desconhecido ou o valor não está em uma forma documentada.
+- A opção `cst` existe só em `isValidClassTrib`, já que o registro retornado aqui já traz o seu CST em `cst`.
+- `cst` é o CST-IBS/CBS a que a classificação pertence, os 3 primeiros dígitos do seu código; `name` é o nome reduzido que a tabela oficial dá para apresentação (a coluna "Nome cClassTrib") e `description` a situação a que se refere (a coluna "Descrição cClassTrib").
+- A redação legal que a planilha também traz em cada linha (o artigo da Lei Complementar nº 214/2025 e dos dois regulamentos) não é distribuída.
+
+```javascript
+import { getClassTrib } from '@brazilian-utils/brazilian-utils';
+
+getClassTrib('000002');
+// {
+//   code: '000002',
+//   cst: '000',
+//   name: 'Exploração de via',
+//   description: 'Exploração de via, observado o art. 11 da Lei Complementar nº 214, de 2025.',
+// }
+getClassTrib(2)?.code; // '000002'
+getClassTrib('999999'); // null
+getClassTrib('220001'); // null (excluído pelo Informe Técnico 2025.002 v.1.60)
+getClassTrib('c200001'); // null (não é uma forma documentada)
+```
+
+Fonte: as abas CST e cClassTrib da planilha "Tabela de Classificação Tributária do IBS e CBS" que o [Portal Nacional da NF-e publica em "Documentos" > "Diversos"](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=/NJarYc9nus=) (a versão publicada em 23/06/2026), divulgada pelo [Informe Técnico 2025.002](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=hXzemuyNHW4=) (v.1.60), e a [Nota Técnica 2025.002-RTC](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=04BIflQt1aY=), campos UB13 e UB14.
+
 ## GTIN (código de barras de produto)
 
 ### isValidGtin

docs/utilities.md

@@ -3053,6 +3053,92 @@ isValidCsosn(-101); // false (not a non-negative safe integer)
 
 Source: [consolidated Anexo III-A of Convênio SINIEF s/nº 1970](https://www.confaz.fazenda.gov.br/legislacao/ajustes/sinief/cvsn_70) and [Ajuste SINIEF 03/2010](https://www.confaz.fazenda.gov.br/legislacao/ajustes/2010/aj_003_10).
 
+### isValidCstIbsCbs
+
+Check if a CST-IBS/CBS (Código de Situação Tributária do IBS e da CBS) exists in the official table, the code the field `CST` of the group `IBSCBS` carries in the electronic fiscal documents of the tax reform (Lei Complementar nº 214/2025): NF-e, NFC-e, CT-e, NFS-e and the others.
+
+- The codes in force are `000`, `010`, `011`, `200`, `220`, `221`, `222`, `400`, `410`, `510`, `515`, `550`, `620`, `800`, `810`, `811`, `820` and `830`.
+- It is a function of its own, not a `tax` of `isValidCst`: IBS and CBS share one table, its 3 digit codes collide with the ICMS origin plus Tabela B form (`000`, `200`), and `isValidCst` without a `tax` accepts a code of any table, so adding this one would change what that default accepts.
+- Accepts a string of bare digits with optional surrounding whitespace, or a non-negative safe integer. The field is numeric with 3 digits and has no mask, so any other string is rejected instead of having its digits picked out.
+- A value narrower than 3 digits is left padded with zeros, as a string or as a number, since the codes start with zeros a numeric field drops: `0`, `'0'` and `'000'` are all the code `000`.
+
+```javascript
+import { isValidCstIbsCbs } from '@brazilian-utils/brazilian-utils';
+
+isValidCstIbsCbs('000'); // true
+isValidCstIbsCbs(410); // true
+isValidCstIbsCbs(10); // true (padded to '010')
+isValidCstIbsCbs('100'); // false
+isValidCstIbsCbs('cst200'); // false (not a documented form)
+isValidCstIbsCbs(-200); // false (not a non-negative safe integer)
+```
+
+### getCstIbsCbs
+
+Look a CST-IBS/CBS up and get the description the official CST table gives it. The result is a `CstIbsCbs` record: `{ code, description }`.
+
+- Same table and input rules as `isValidCstIbsCbs`. Returns `null` when the code is unknown or the value is not in a documented form.
+
+```javascript
+import { getCstIbsCbs } from '@brazilian-utils/brazilian-utils';
+
+getCstIbsCbs('000'); // { code: '000', description: 'Tributação integral' }
+getCstIbsCbs(410); // { code: '410', description: 'Imunidade e não incidência' }
+getCstIbsCbs(10); // { code: '010', description: 'Tributação com alíquotas uniformes' }
+getCstIbsCbs('100'); // null
+getCstIbsCbs('cst200'); // null (not a documented form)
+```
+
+### isValidClassTrib
+
+Check if a cClassTrib (Código de Classificação Tributária do IBS e da CBS) exists in the official table, the code the field `cClassTrib` carries next to the CST-IBS/CBS.
+
+- **Options** (`IsValidClassTribOptions`): `cst` is the CST-IBS/CBS the document carries, checked against the classification as well. Omit it to check the cClassTrib alone.
+- Every classification belongs to exactly one CST-IBS/CBS, the first 3 digits of its code, and a document that carries a cClassTrib with another CST is rejected (rejection 1024, "Classificação Tributária do IBS e da CBS incompatível com o CST informado"). A `cst` that is given and is not the CST of the classification, whatever it is, makes the result `false`.
+- Only the classifications in force count: the Informe Técnico 2025.002 excludes a classification by closing its validity (`dFimVig`), as v.1.60 did with `220001`, `220002` and `220003`, and those are rejected. 161 are in force in the version published on 23/06/2026.
+- Accepts a string of bare digits with optional surrounding whitespace, or a non-negative safe integer. The field is numeric with 6 digits and has no mask, so any other string is rejected.
+- A value narrower than 6 digits is left padded with zeros: `1`, `'1'` and `'000001'` are all the code `000001`. `cst` is read the same way, padded to 3 digits.
+- Only the code list is bundled with this function, not the descriptions `getClassTrib` returns.
+
+```javascript
+import { isValidClassTrib } from '@brazilian-utils/brazilian-utils';
+
+isValidClassTrib('200001'); // true
+isValidClassTrib(1); // true (padded to '000001')
+isValidClassTrib('200001', { cst: '200' }); // true
+isValidClassTrib('200001', { cst: '000' }); // false (the classification belongs to CST 200)
+isValidClassTrib('999999'); // false
+isValidClassTrib('220001'); // false (excluded by Informe Técnico 2025.002 v.1.60)
+isValidClassTrib('c200001'); // false (not a documented form)
+```
+
+### getClassTrib
+
+Look a cClassTrib up and get its official classification. The result is a `ClassTrib` record: `{ code, cst, name, description }`.
+
+- Same table and the same rules for reading the code as `isValidClassTrib`. Returns `null` when the code is unknown or the value is not in a documented form.
+- The `cst` option exists only on `isValidClassTrib`, since the entry returned here already carries its CST as `cst`.
+- `cst` is the CST-IBS/CBS the classification belongs to, the first 3 digits of its code; `name` is the short name the official table gives for display (the column "Nome cClassTrib") and `description` the situation it refers to (the column "Descrição cClassTrib").
+- The legal wording the workbook also prints for each row (the article of Lei Complementar nº 214/2025 and of both regulations) is not shipped.
+
+```javascript
+import { getClassTrib } from '@brazilian-utils/brazilian-utils';
+
+getClassTrib('000002');
+// {
+//   code: '000002',
+//   cst: '000',
+//   name: 'Exploração de via',
+//   description: 'Exploração de via, observado o art. 11 da Lei Complementar nº 214, de 2025.',
+// }
+getClassTrib(2)?.code; // '000002'
+getClassTrib('999999'); // null
+getClassTrib('220001'); // null (excluded by Informe Técnico 2025.002 v.1.60)
+getClassTrib('c200001'); // null (not a documented form)
+```
+
+Source: the CST and cClassTrib sheets of the "Tabela de Classificação Tributária do IBS e CBS" workbook the [Portal Nacional da NF-e publishes under "Documentos" > "Diversos"](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=/NJarYc9nus=) (the version published on 23/06/2026), divulged by the [Informe Técnico 2025.002](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=hXzemuyNHW4=) (v.1.60), and the [Nota Técnica 2025.002-RTC](https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=04BIflQt1aY=), fields UB13 and UB14.
+
 ## GTIN (product barcode)
 
 ### isValidGtin

jsr.json

@@ -62,9 +62,11 @@
 		"./get-certidao-info": "./src/get-certidao-info/get-certidao-info.ts",
 		"./get-cfop": "./src/get-cfop/get-cfop.ts",
 		"./get-cities": "./src/get-cities/get-cities.ts",
+		"./get-class-trib": "./src/get-class-trib/get-class-trib.ts",
 		"./get-cnae": "./src/get-cnae/get-cnae.ts",
 		"./get-cnpj-info": "./src/get-cnpj-info/get-cnpj-info.ts",
 		"./get-cpf-info": "./src/get-cpf-info/get-cpf-info.ts",
+		"./get-cst-ibs-cbs": "./src/get-cst-ibs-cbs/get-cst-ibs-cbs.ts",
 		"./get-format-license-plate": "./src/get-format-license-plate/get-format-license-plate.ts",
 		"./get-gtin-info": "./src/get-gtin-info/get-gtin-info.ts",
 		"./get-holidays": "./src/get-holidays/get-holidays.ts",
@@ -100,6 +102,7 @@
 		"./is-valid-cep": "./src/is-valid-cep/is-valid-cep.ts",
 		"./is-valid-certidao": "./src/is-valid-certidao/is-valid-certidao.ts",
 		"./is-valid-cfop": "./src/is-valid-cfop/is-valid-cfop.ts",
+		"./is-valid-class-trib": "./src/is-valid-class-trib/is-valid-class-trib.ts",
 		"./is-valid-cnae": "./src/is-valid-cnae/is-valid-cnae.ts",
 		"./is-valid-cnh": "./src/is-valid-cnh/is-valid-cnh.ts",
 		"./is-valid-cno": "./src/is-valid-cno/is-valid-cno.ts",
@@ -109,6 +112,7 @@
 		"./is-valid-credit-card": "./src/is-valid-credit-card/is-valid-credit-card.ts",
 		"./is-valid-csosn": "./src/is-valid-csosn/is-valid-csosn.ts",
 		"./is-valid-cst": "./src/is-valid-cst/is-valid-cst.ts",
+		"./is-valid-cst-ibs-cbs": "./src/is-valid-cst-ibs-cbs/is-valid-cst-ibs-cbs.ts",
 		"./is-valid-email": "./src/is-valid-email/is-valid-email.ts",
 		"./is-valid-gtin": "./src/is-valid-gtin/is-valid-gtin.ts",
 		"./is-valid-iban": "./src/is-valid-iban/is-valid-iban.ts",