Feature/consulta endereco

[andrekutianski]

📝 Descrição

Esta PR adiciona suporte completo para a API de Consulta de Endereços da NFE.io, permitindo que usuários do SDK realizem buscas de endereços por CEP ou termos de pesquisa.

✨ Principais Mudanças

🆕 Nova Funcionalidade: AddressesResource

• Lookup por CEP: Busca endereços completos usando código postal brasileiro
• Busca por termo: Pesquisa flexível por logradouro, cidade, etc.
• Validação robusta: Validação de CEP e parâmetros de busca
• Tipos TypeScript: Interfaces completas para requests/responses

🔑 Suporte Multi-API Key

• Configuração separada de API keys para diferentes serviços NFE.io
• Suporte para addressApiKey opcional no NfeConfig
• Permite usar chaves específicas para Address API vs Service Invoice API

🧪 Testes Completos

• Testes unitários: 254+ linhas em addresses.test.ts
• Testes de integração: 145+ linhas em addresses.integration.test.ts
• Teste multi-key: 239+ linhas validando configuração de múltiplas chaves

📚 Exemplos e Documentação

• Novo exemplo prático: address-lookup.js (187 linhas)
• Documentação atualizada no README.md
• Types exportados em index.ts

🛠️ Infraestrutura OpenSpec

• Skills para gerenciamento estruturado de mudanças
• Onboarding, sync, verify, archive workflows
• Melhor rastreabilidade de implementações

📊 Estatísticas

57 arquivos modificados
+5805 linhas adicionadas
-627 linhas removidas

🔧 Breaking Changes

Nenhum. Esta é uma adição retrocompatível - código existente continua funcionando sem alterações.

💡 Exemplo de Uso

import { NfeClient } from 'nfe-io';

const client = new NfeClient({
  apiKey: 'sua-chave-principal',
  addressApiKey: 'sua-chave-address-api' // opcional
});

// Buscar por CEP
const result = await client.addresses.lookup('01310-100');
console.log(result.address); // { street: 'Av. Paulista', city: 'São Paulo', ... }

// Buscar por termo
const results = await client.addresses.search('Av Paulista, São Paulo');
for await (const address of results) {
  console.log(address);
}

🚀 Deploy Notes

Não requer ações especiais. Após merge:

1. Atualizar version em package.json
2. Rodar npm run build
3. Publicar no NPM: npm publish

[github-actions]

📋 OpenAPI Spec Validation

✅ All specs validated and types generated successfully

Specs processed:

• calculo-impostos-v1.yaml - 27.88 KB, 852 lines
• consulta-cnpj.yaml - 34.28 KB, 1128 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
• cpf-api.yaml - 3.39 KB, 83 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

Generated types available as artifact in src/generated/.