Skip to content

Release v5.0.0#38

Merged
andrenfe merged 19 commits into
masterfrom
develop
Jul 1, 2026
Merged

Release v5.0.0#38
andrenfe merged 19 commits into
masterfrom
develop

Conversation

@andrenfe

@andrenfe andrenfe commented Jul 1, 2026

Copy link
Copy Markdown
Member

v5.0.0 — primeira release de funcionalidades desde a v3

A v4 foi apenas o bump de runtime (Node 22), sem mudanças de API. A v5 reúne os novos recursos e correções de contrato validadas contra a API ao vivo.

✨ Novidades

  • Emissão RTC (Reforma Tributária): serviceInvoicesRtc, productInvoicesRtc
  • NFC-e: consumerInvoices
  • Inscrições municipais: municipalTaxes
  • Certificados por thumbprint: certificates
  • Notificações: notifications
  • Webhooks de conta + fetchEventTypes()
  • companies.exists(), serviceInvoices.retrieveByExternalId(), serviceInvoices.cancelAndWait(), stateTaxes.switchAuthorizer()
  • Company enriquecido com campos do spec (opcionais); verbos HTTP patch/head

⚠️ Breaking changes (todas em superfícies que já estavam quebradas — ver MIGRATION.md#v4--v5)

  • addresses.lookupByPostalCode() retorna um Address (era envelope { addresses: [] })
  • addresses.search() / lookupByTerm() removidos (endpoints inexistentes / 404)
  • serviceInvoices.cancel() retorna união discriminada CancelInvoiceResponse (cancelamento é assíncrono) + novo cancelAndWait()
  • CertificateValidator.validate() não fabrica mais metadata

🐛 Corrigidos via smoke test ao vivo de toda a SDK

  • taxCodes.* usava a chave de dados → 403; agora usa a chave principal
  • consumerInvoices.list() exige environment (obrigatório pela API) + chave principal
  • webhooks de conta montavam /v1/v2/webhooks → 404; cliente dedicado em api.nfe.io/v2 + unwrap dos envelopes

✅ Verificação

  • typecheck 0 · 682 testes · build OK · lint 0 erros
  • Validado ao vivo: addresses 6/6, service-invoices 13/13, e os 3 fixes reconfirmados

Migração: MIGRATION.md#v4--v5

andrenfe added 14 commits June 27, 2026 00:37
@andrenfe
fix: corrigir bugs de repo (cert validator, updateConfig, README webh…
f1123f3 
…ook)

- CertificateValidator.validate() para de fabricar metadata e reportar
  validade falsa; vira pré-flight só de formato (verificação real é server-side)
- updateConfig() agora invalida TODOS os resources/HTTP clients via resetCaches()
  (antes deixava productInvoices/stateTaxes/lookups/query stale)
- README: header de webhook x-nfe-signature -> x-hub-signature (HMAC-SHA1)

OpenSpec change: fix-repo-bugs (11/11 tasks)
@andrenfe
feat(pipeline): fail-loud com allowlist + descoberta .json + remover …
be64ca9 
…placeholders mortos

- generate-types.ts: skip de spec não-allowlistado falha o build (antes do banner);
  os 5 Swagger 2.0 legados ficam num KNOWN_SKIPPED (não quebram) — review B1
- discoverSpecs aceita .json (contribuintes-v2.json deixaria de ser ignorado) — review B2
- índice gerado não emite mais placeholders { [key]: unknown } (tipos públicos vivem
  em core/types.ts) — review 0B/Task 1.3
- testes de geração alinhados ao allowlist + tipos públicos repontados p/ core/types.ts

OpenSpec: sync-openapi-specs-from-docs (Track A / Phase 1 parcial)
@andrenfe
feat(rtc): emissão RTC de NFS-e e NF-e/NFC-e (Reforma Tributária)
70e5119 
- serviceInvoicesRtc: NFS-e leiaute RTC (grupo ibsCbs) via api.nfe.io;
  create/createAndWait (polling) + downloadCancellationXml; path sem /v1
- productInvoicesRtc: NF-e/NFC-e leiaute RTC via api.nfse.io; create webhook-driven
  (espelha product-invoices, sem polling)
- tipos NFSeRtcRequest / ProductInvoiceRtcRequest (schemas nomeados das specs RTC)
- specs RTC sincronizadas em openapi/spec/ + geradas; proveniência em SOURCES.json
- getters lazy no NfeClient (+ resetCaches), exports no barrel, 8 testes novos

OpenSpec: add-rtc-invoice-emission (19/19 tasks)
@andrenfe
feat(types): adotar contribuintes-v2 + repoint aditivo de Company (se…
b02a86c 
…m major)

- contribuintes-v2.json adotado na geração (10/15); tipos de empresa/cert/endereço
- Company enriquecido aditivamente (& Partial<Omit<CompanyResourceItem,...>> + índice
  mantido): campos reais opcionais, federalTaxNumber segue number, create() intacto
- novos tipos opt-in: CompanyResourceItem/V1, CreateCompanyResourceItem,
  UpdateCompanyResourceItem, CertificateMetadataResource, CompanyAddress
- guard de tipo executável: npm run test:types (vitest typecheck) — company.test-d.ts
- SOURCES.json + CHANGELOG atualizados
- consolidação de enums (TaxRegime/SpecialTaxRegime) deferida (risco de quebra)

OpenSpec: sync-openapi-specs-from-docs (Phase 2 / Track B+C)
@andrenfe
feat(webhooks): operações de conta (/v2/webhooks) + fetchEventTypes a…
2b71d46 
…o vivo

- WebhooksResource estendido (mesma resource, não separada): list/create/retrieve/
  update/delete de conta, pingAccountWebhook, e deleteAllAccountWebhooks (nome
  distinto + JSDoc de destrutivo) — company-scoped inalterado
- fetchEventTypes() (GET /v2/webhooks/eventTypes, união aberta); getAvailableEvents()
  marcado @deprecated (lista hardcoded fazia drift)
- +6 testes

OpenSpec: add-missing-resources (Phase 1 / P1)
@andrenfe
feat(municipal-taxes): MunicipalTaxesResource + verbo HTTP PATCH
860fbea 
- nfe.municipalTaxes (api.nfse.io): CRUD de inscrições municipais (espelha stateTaxes),
  updatePrefecture (PATCH .../updateprefecture) e getSeries (.../series/{serie})
- HTTP client: novo verbo patch() com paridade de retry/timeout/erro (+2 testes)
- tipos MunicipalTax/CreateMunicipalTaxData/UpdateMunicipalTaxData (contribuintes-v2)
- getter lazy + resetCaches + barrel; 7 testes do resource

OpenSpec: add-missing-resources (Phase 2 / P3)
@andrenfe
feat(nfc-e): ConsumerInvoicesResource (emissão NFC-e + ciclo de vida)
a293789 
- nfe.consumerInvoices (api.nfse.io): create webhook-driven, list, retrieve, cancel,
  getItems, getEvents, downloadPdf/Xml/RejectionXml, disable (inutilização)
- distinto do consumerInvoiceQuery (consulta de cupom, read-only)
- tipos do nf-consumidor-v2 (ConsumerInvoiceRequest/InvoiceResource/DisablementResource)
- getter lazy + resetCaches + barrel; 6 testes

OpenSpec: add-missing-resources (Phase 3 / P4)
@andrenfe
feat(certificates): CertificatesResource (get/delete por thumbprint)
2093679 
- nfe.certificates (api.nfse.io / contribuintes-v2): list, getByThumbprint/
  deleteByThumbprint (v2) + variantes v1
- recurso DEDICADO (não estende companies) porque o cert API do contribuintes-v2
  está em host diferente (api.nfse.io) do companies.uploadCertificate (api.nfe.io)
  — desvio de design documentado no spec
- tipos CertificateMetadataResource/CertificatesMetadataResource; +4 testes

OpenSpec: add-missing-resources (Phase 4 / P2)
@andrenfe
feat(resources): companies.exists (HEAD) + notifications + external-i…
5774694 
…d + switch-authorizer

- HTTP client: verbo head() (corpo vazio ok); +2 testes
- companies.exists(id) via HEAD /v2/companies/{id} (api.nfse.io, client v2 opcional; 404->false)
- NotificationsResource (api.nfe.io): list/retrieve/delete/sendEmail
- serviceInvoices.retrieveByExternalId (GET .../serviceinvoices/external/{id})
- stateTaxes.switchAuthorizer (POST .../switch-authorizer)
- getters + resetCaches + barrel; +7 testes. Conclui add-missing (P6 batch deferido)

OpenSpec: add-missing-resources (Phase 5 / P5+P7) — change completa
@andrenfe
fix(resources): corrige address lookup e cancelamento async de NFS-e
9dc2707 
Correções descobertas testando contra a API ao vivo:

- addresses.lookupByPostalCode: desempacota o envelope { address } e retorna
  um Address único (antes retornava o envelope tipado como { addresses: [] },
  então result.addresses[0] vinha undefined).
- addresses.search/lookupByTerm removidos: os endpoints (/v2/addresses e
  /v2/addresses/{term}) respondem 404 no host real — nunca funcionaram.
  AddressSearchOptions removido; AddressLookupResponse agora descreve o
  envelope real { address: Address }.
- serviceInvoices.cancel: cancelamento e assincrono (202 + Location); passa a
  retornar a uniao discriminada CancelInvoiceResponse, espelhando create()
  (antes devolvia o stub de polling tipado como ServiceInvoiceData).
- serviceInvoices.cancelAndWait: novo helper que faz polling ate o
  cancelamento concluir. Tipos exportados: CreateInvoiceResponse,
  CancelInvoiceResponse.
- Testes de integracao corrigidos para os shapes reais; a suite de
  service-invoices auto-pula quando a empresa nao tem inscricao municipal.
  Validado ao vivo: addresses 6/6, service-invoices 13/13.
@andrenfe
chore(openspec): marca tasks concluidas (changes ja rastreadas)
64d4c10 
Atualiza o status das checkboxes nas tasks.md ja versionadas:
- generate-sdk-from-openapi: 89/89 (merge strategy + checklist final)
- implement-service-invoices: 157/157 (emissao validada ao vivo 13/13)
- implement-address-lookup: 45/45 (lookup live verificado pos-fix)

As changes novas (fix-address-lookup-api-mismatch,
fix-service-invoice-cancel-async) seguem fora do git por .gitignore.
@andrenfe
chore(release): v5.0.0
8d8100b 
Primeira release de funcionalidades desde a v3 (a v4 foi so o bump de Node 22).

- package.json: v4.0.0 -> 5.0.0 (corrige prefixo "v" malformado)
- Sincroniza constantes de versao que estavam stale em 3.0.0-beta.1
  (PACKAGE_VERSION, VERSION); getRuntimeInfo() passa a derivar de VERSION.
- CHANGELOG: secao [5.0.0] com BREAKING CHANGES promovidos ao topo.
- MIGRATION.md: guia v4 -> v5 (lookupByPostalCode, search/lookupByTerm
  removidos, cancel() discriminado + cancelAndWait, CertificateValidator).
- README: v4 -> v5 + blurb de novidades.
@andrenfe
chore(openspec): arquiva changes concluidas (move pro archive ignorado)
24443b0 
Move 4 changes 100% completas para openspec/changes/archive/ (gitignored):
- implement-companies-resource (121/121)
- generate-sdk-from-openapi (89/89)
- implement-address-lookup (45/45)
- implement-service-invoices (157/157)

Os arquivos seguem em disco no archive; deixam de ser rastreados, alinhando
com a politica de manter artefatos openspec fora do git. Sem sync de specs
(deltas preservados no archive; evita gravar address-lookup stale).
@andrenfe
fix(resources): corrige 3 bugs HIGH achados em smoke test ao vivo (v5)
fb3dfc1 
Smoke sweep read-only de toda a SDK contra a API real revelou 3 recursos
(novos na v5) inutilizaveis; todos verificados ao vivo apos o fix:

- taxCodes.*: usava o cliente CT-e (chave de dados) -> 403 com dataApiKey
  separada. Passa a usar a chave principal contra api.nfse.io (200).
- consumerInvoices: (1) list() omitia o param obrigatorio `environment`
  (-> 400); agora exige `{ environment }` e os reads aceitam env opcional.
  (2) usava chave de dados (-> 403); passa a usar a chave principal.
- webhooks de conta: caminho `/v1/v2/webhooks` (duplo prefixo) -> 404.
  Cliente dedicado em api.nfe.io/v2; paths sem `/v2`. Desempacota os
  envelopes {webHooks} e {eventTypes}.

Cada fix isolado por recurso (sem inverter resolveDataApiKey global).
Exporta CreateInvoiceResponse/CancelInvoiceResponse ja na v5;
ConsumerInvoiceListOptions/Environment. Suite 682 verde; lint 0 erros.
@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

  • calculo-impostos-v1.yaml - 27.90 KB, 853 lines
  • consulta-cnpj.yaml - 34.28 KB, 1128 lines
  • consulta-cpf.yaml - 3.39 KB, 83 lines
  • consulta-cte-v2.yaml - 18.33 KB, 578 lines
  • consulta-endereco.yaml - 11.17 KB, 343 lines
  • consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
  • consulta-nf.yaml - 137.87 KB, 3119 lines
  • consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
  • nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
  • nf-produto-v2.yaml - 309.41 KB, 8204 lines
  • nf-servico-v1.yaml - 257.42 KB, 6252 lines
  • nfeio.yaml - 15.86 KB, 630 lines
  • product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
  • service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.

@andrenfe
docs(skill,examples): alinha skill publicada e exemplos com a API v5
0fd314a 
A skill (publicada via package.json files) e os exemplos estavam com API antiga:

- skill Resource Map: remove addresses.search/lookupByTerm (removidos);
  adiciona serviceInvoicesRtc, productInvoicesRtc, consumerInvoices,
  municipalTaxes, certificates, notifications e webhooks de conta;
  serviceInvoices ganha cancelAndWait/retrieveByExternalId; companies.exists;
  stateTaxes.switchAuthorizer.
- skill data-services ref: addresses agora e so lookupByPostalCode -> Address
  (envelope desempacotado); tipo Address corrigido (postalCode com hifen,
  numberMin/Max opcionais, country alpha-3).
- examples/service-invoice-complete.js: cancelamento usa cancelAndWait()
  (cancel() agora retorna uniao discriminada).
@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

  • calculo-impostos-v1.yaml - 27.90 KB, 853 lines
  • consulta-cnpj.yaml - 34.28 KB, 1128 lines
  • consulta-cpf.yaml - 3.39 KB, 83 lines
  • consulta-cte-v2.yaml - 18.33 KB, 578 lines
  • consulta-endereco.yaml - 11.17 KB, 343 lines
  • consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
  • consulta-nf.yaml - 137.87 KB, 3119 lines
  • consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
  • nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
  • nf-produto-v2.yaml - 309.41 KB, 8204 lines
  • nf-servico-v1.yaml - 257.42 KB, 6252 lines
  • nfeio.yaml - 15.86 KB, 630 lines
  • product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
  • service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.

@andrenfe andrenfe self-assigned this Jul 1, 2026
@andrenfe
docs(examples,skill): adiciona cobertura dos recursos novos da v5
a392bb9 
Exemplos runnable (examples/) e reference doc (skill publicada) para os
recursos introduzidos na v5:

- examples: rtc-invoices, consumer-invoices, municipal-taxes, certificates,
  notifications, account-webhooks (assinaturas conferidas no código).
- examples/README: título v3 -> v5 + seção "Novos na v5".
- skills: nova reference rtc-nfce-and-account-resources.md (assinaturas RTC,
  NFC-e c/ environment, municipal, certificates, notifications, webhooks de
  conta, cancelAndWait/exists/switchAuthorizer) + registro no SKILL.md.
@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

  • calculo-impostos-v1.yaml - 27.90 KB, 853 lines
  • consulta-cnpj.yaml - 34.28 KB, 1128 lines
  • consulta-cpf.yaml - 3.39 KB, 83 lines
  • consulta-cte-v2.yaml - 18.33 KB, 578 lines
  • consulta-endereco.yaml - 11.17 KB, 343 lines
  • consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
  • consulta-nf.yaml - 137.87 KB, 3119 lines
  • consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
  • nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
  • nf-produto-v2.yaml - 309.41 KB, 8204 lines
  • nf-servico-v1.yaml - 257.42 KB, 6252 lines
  • nfeio.yaml - 15.86 KB, 630 lines
  • product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
  • service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.

@andrenfe
test: cobre branches do codigo novo da v5 (destrava threshold de 80%)
7eb0844 
O CI falhava em coverage (branches 76.55% < 80%) porque o codigo novo da v5
adicionou ramos sem teste. Adiciona:
- service-invoices-rtc: createAndWait (immediate/async/IssueFailed) + retrieve
- service-invoices: cancelAndWait (async/immediate/CancelFailed)
- consumer-invoices: forward de environment nos reads/downloads + filtros do list

Branches: 76.55% -> 80.74%. 692 testes verdes.
@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

  • calculo-impostos-v1.yaml - 27.90 KB, 853 lines
  • consulta-cnpj.yaml - 34.28 KB, 1128 lines
  • consulta-cpf.yaml - 3.39 KB, 83 lines
  • consulta-cte-v2.yaml - 18.33 KB, 578 lines
  • consulta-endereco.yaml - 11.17 KB, 343 lines
  • consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
  • consulta-nf.yaml - 137.87 KB, 3119 lines
  • consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
  • nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
  • nf-produto-v2.yaml - 309.41 KB, 8204 lines
  • nf-servico-v1.yaml - 257.42 KB, 6252 lines
  • nfeio.yaml - 15.86 KB, 630 lines
  • product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
  • service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.

andrenfe added 2 commits July 1, 2026 09:48
@andrenfe
chore(.gitignore): add dir to ignored files
93504a5
@andrenfe
docs: adiciona docs Docusaurus "copia-e-cola" pro nfeio-docs (estilo …
8103b03 
…client-ruby)

Conjunto de documentacao no padrao do client-ruby/docs, adaptado ao Node/v5 e
pronto pra colar no nfeio-docs (Docusaurus):

- 9 guias: getting-started, configuration, async-and-polling, multi-host-routing,
  pagination, downloads, webhooks, errors, rtc-emission.
- README (indice, slug /desenvolvedores/bibliotecas/node) + _category_.json.
- 19 recursos (cookbook) em docs/recursos/: service/product/consumer invoices,
  companies, municipal/state taxes, certificates, notifications, webhooks, rtc,
  addresses, lookups CNPJ/CPF, people PJ/PF, tax-codes, tax-calculation, CT-e,
  inbound, e as consultas por chave.

Frontmatter rico, admonitions, tabelas de metodos e exemplos em TypeScript;
API conferida no codigo da v5 (uniao discriminada, cancelAndWait, environment
na NFC-e, multi-host/chave). Links internos validados.
@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

  • calculo-impostos-v1.yaml - 27.90 KB, 853 lines
  • consulta-cnpj.yaml - 34.28 KB, 1128 lines
  • consulta-cpf.yaml - 3.39 KB, 83 lines
  • consulta-cte-v2.yaml - 18.33 KB, 578 lines
  • consulta-endereco.yaml - 11.17 KB, 343 lines
  • consulta-nf-consumidor.yaml - 43.41 KB, 1279 lines
  • consulta-nf.yaml - 137.87 KB, 3119 lines
  • consulta-nfe-distribuicao-v1.yaml - 53.07 KB, 1775 lines
  • nf-consumidor-v2.yaml - 293.87 KB, 7609 lines
  • nf-produto-v2.yaml - 309.41 KB, 8204 lines
  • nf-servico-v1.yaml - 257.42 KB, 6252 lines
  • nfeio.yaml - 15.86 KB, 630 lines
  • product-invoice-rtc-v1.yaml - 198.88 KB, 5084 lines
  • service-invoice-rtc-v1.yaml - 95.30 KB, 1728 lines

Generated types available as artifact in src/generated/.

@andrenfe andrenfe merged commit 881f3d4 into master Jul 1, 2026
13 checks passed
@andrenfe andrenfe deleted the develop branch July 1, 2026 18:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@andrenfe andrenfe

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@andrenfe