feat: add AddressesResource for address lookup and search functionality

- Implemented AddressesResource to handle address lookup operations via the Address API.
- Added methods for looking up addresses by postal code and searching by term or filter.
- Introduced validation for postal codes and search terms.
- Updated NfeConfig to support separate API keys for Address API.
- Created integration tests for AddressesResource to ensure functionality.
- Added unit tests for AddressesResource covering various scenarios and validations.
- Updated types to include address-related interfaces and response structures.
- Enhanced error handling for invalid inputs and API responses.

Author: andrekutianski

README.md

@@ -337,13 +337,42 @@ const ehValido = nfe.webhooks.validateSignature(
 );
 ```
 
+#### 📍 Endereços (`nfe.addresses`)
+
+Consultar endereços brasileiros por CEP ou termo de busca:
+
+```typescript
+// Buscar endereço por CEP
+const endereco = await nfe.addresses.lookupByPostalCode('01310-100');
+console.log(endereco.street);   // 'Avenida Paulista'
+console.log(endereco.city.name); // 'São Paulo'
+console.log(endereco.state);     // 'SP'
+
+// Buscar por termo (nome de rua, bairro, etc.)
+const resultado = await nfe.addresses.lookupByTerm('Paulista');
+for (const end of resultado.addresses) {
+  console.log(`${end.postalCode}: ${end.street}, ${end.city.name}`);
+}
+
+// Buscar com filtro OData
+const filtrado = await nfe.addresses.search({
+  filter: "city.name eq 'São Paulo'"
+});
+```
+
+> **Nota:** A API de Endereços usa um host separado (`address.api.nfe.io`). Você pode configurar uma chave API específica com `addressApiKey`, ou o SDK usará `apiKey` como fallback.
+
 ### Opções de Configuração
 
 ```typescript
 const nfe = new NfeClient({
-  // Obrigatório: Sua chave API do NFE.io
+  // Chave API principal do NFE.io (opcional se usar apenas Addresses com addressApiKey)
   apiKey: 'sua-chave-api',
 
+  // Opcional: Chave API específica para consulta de endereços
+  // Se não fornecida, usa apiKey como fallback
+  addressApiKey: 'sua-chave-address-api',
+  
   // Opcional: Ambiente (padrão: 'production')
   environment: 'production', // ou 'sandbox'
 
@@ -363,6 +392,24 @@ const nfe = new NfeClient({
 });
 ```
 
+#### Variáveis de Ambiente
+
+O SDK suporta as seguintes variáveis de ambiente:
+
+| Variável | Descrição |
+|----------|-----------|
+| `NFE_API_KEY` | Chave API principal (fallback para `apiKey`) |
+| `NFE_ADDRESS_API_KEY` | Chave API para endereços (fallback para `addressApiKey`) |
+
+```bash
+# Configurar via ambiente
+export NFE_API_KEY="sua-chave-api"
+export NFE_ADDRESS_API_KEY="sua-chave-address"
+
+# Usar SDK sem passar chaves no código
+const nfe = new NfeClient({});
+```
+
 ### Tratamento de Erros
 
 O SDK fornece classes de erro tipadas:

examples/address-lookup.js

@@ -0,0 +1,187 @@
+/**
+ * NFE.io SDK v3 - Address Lookup Examples
+ *
+ * This example demonstrates how to use the Addresses API for looking up
+ * Brazilian addresses (CEP/postal code lookups).
+ *
+ * Prerequisites:
+ *   - Set NFE_ADDRESS_API_KEY or NFE_API_KEY environment variable
+ *   - Or pass the API key directly in the configuration
+ *
+ * Run this example:
+ *   node examples/address-lookup.js
+ */
+
+import { NfeClient } from '../dist/index.js';
+
+// Configuration with separate address API key (optional)
+const client = new NfeClient({
+  // You can use a separate API key for address lookups
+  // addressApiKey: process.env.NFE_ADDRESS_API_KEY,
+
+  // Or use the main API key (will be used as fallback for addresses)
+  apiKey: process.env.NFE_API_KEY,
+
+  // Environment: 'production' or 'development'
+  environment: 'production',
+});
+
+/**
+ * Example 1: Basic postal code lookup
+ */
+async function lookupByPostalCode() {
+  console.log('\n📮 Example 1: Postal Code Lookup');
+  console.log('='.repeat(50));
+
+  try {
+    // Lookup a São Paulo CEP (Avenida Paulista)
+    const result = await client.addresses.lookupByPostalCode('01310-100');
+
+    console.log('CEP:', result.postalCode);
+    console.log('Street:', result.street);
+    console.log('District:', result.district);
+    console.log('City:', result.city?.name);
+    console.log('State:', result.state);
+    console.log('Country:', result.country);
+
+    // Works with or without hyphen
+    const result2 = await client.addresses.lookupByPostalCode('01310100');
+    console.log('\nSame CEP without hyphen:', result2.postalCode);
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+/**
+ * Example 2: Search addresses by term
+ */
+async function lookupByTerm() {
+  console.log('\n🔍 Example 2: Search by Term');
+  console.log('='.repeat(50));
+
+  try {
+    const result = await client.addresses.lookupByTerm('Avenida Paulista');
+
+    console.log('Search results:');
+    if (result.addresses && result.addresses.length > 0) {
+      for (const address of result.addresses.slice(0, 3)) {
+        console.log(`  - ${address.postalCode}: ${address.street}, ${address.city?.name}/${address.state}`);
+      }
+      if (result.addresses.length > 3) {
+        console.log(`  ... and ${result.addresses.length - 3} more`);
+      }
+    } else {
+      console.log('  No addresses found');
+    }
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+/**
+ * Example 3: Search with OData filter
+ */
+async function searchWithFilter() {
+  console.log('\n🎯 Example 3: Search with Filter');
+  console.log('='.repeat(50));
+
+  try {
+    // Search addresses in São Paulo
+    const result = await client.addresses.search({
+      filter: "city.name eq 'São Paulo'",
+    });
+
+    console.log('Filtered search results:');
+    if (result.addresses && result.addresses.length > 0) {
+      console.log(`  Found ${result.addresses.length} addresses in São Paulo`);
+    } else {
+      console.log('  No addresses found');
+    }
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+/**
+ * Example 4: Using only addressApiKey (isolated usage)
+ */
+async function isolatedAddressUsage() {
+  console.log('\n🔐 Example 4: Isolated Address API Usage');
+  console.log('='.repeat(50));
+
+  // Create a client with ONLY addressApiKey
+  // This is useful when you only have access to the Address API
+  const addressOnlyClient = new NfeClient({
+    addressApiKey: process.env.NFE_ADDRESS_API_KEY || process.env.NFE_API_KEY,
+  });
+
+  try {
+    // Addresses work
+    const result = await addressOnlyClient.addresses.lookupByPostalCode('20040-020');
+    console.log('Rio de Janeiro CEP lookup succeeded!');
+    console.log(`  ${result.street}, ${result.city?.name}/${result.state}`);
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+
+  // Other resources will throw an error (commented out to avoid runtime error)
+  // This would throw: "API key required for this resource"
+  // await addressOnlyClient.serviceInvoices.list('company-id');
+}
+
+/**
+ * Example 5: Error handling
+ */
+async function errorHandling() {
+  console.log('\n⚠️  Example 5: Error Handling');
+  console.log('='.repeat(50));
+
+  try {
+    // Invalid CEP format
+    await client.addresses.lookupByPostalCode('invalid');
+  } catch (error) {
+    console.log('ValidationError for invalid CEP:', error.message);
+  }
+
+  try {
+    // Empty search term
+    await client.addresses.lookupByTerm('');
+  } catch (error) {
+    console.log('ValidationError for empty term:', error.message);
+  }
+
+  try {
+    // Non-existent CEP (will get NotFoundError from API)
+    await client.addresses.lookupByPostalCode('00000000');
+  } catch (error) {
+    console.log('API error for non-existent CEP:', error.message);
+  }
+}
+
+/**
+ * Main function to run all examples
+ */
+async function main() {
+  console.log('🏠 NFE.io Address Lookup Examples');
+  console.log('━'.repeat(50));
+
+  if (!process.env.NFE_API_KEY && !process.env.NFE_ADDRESS_API_KEY) {
+    console.error('\n❌ No API key found!');
+    console.error('Please set NFE_API_KEY or NFE_ADDRESS_API_KEY environment variable.');
+    console.error('\nExample:');
+    console.error('  export NFE_API_KEY="your-api-key"');
+    console.error('  node examples/address-lookup.js');
+    process.exit(1);
+  }
+
+  await lookupByPostalCode();
+  await lookupByTerm();
+  await searchWithFilter();
+  await isolatedAddressUsage();
+  await errorHandling();
+
+  console.log('\n✅ All examples completed!');
+}
+
+// Run main function
+main().catch(console.error);

openspec/changes/implement-address-lookup/tasks.md

@@ -1,71 +1,72 @@
 ## 1. Types & Generated Code
 
-- [ ] 1.1 Generate TypeScript types from `openapi/spec/consulta-endereco.yaml` using openapi-typescript
-- [ ] 1.2 Create `src/generated/consulta-endereco.ts` with generated types
-- [ ] 1.3 Export Address-related types from `src/generated/index.ts`
+- [x] 1.1 Generate TypeScript types from `openapi/spec/consulta-endereco.yaml` using openapi-typescript
+  - Note: Swagger 2.0 not supported by openapi-typescript v6+, types created manually
+- [x] 1.2 Create `src/generated/consulta-endereco.ts` with generated types
+- [x] 1.3 Export Address-related types from `src/generated/index.ts`
 
 ## 2. Core Types Extension
 
-- [ ] 2.1 Add `addressApiKey?: string` to `NfeConfig` interface in `src/core/types.ts`
-- [ ] 2.2 Add `Address` and `AddressLookupResponse` types to `src/core/types.ts`
-- [ ] 2.3 Add `AddressSearchOptions` type with `filter` field
+- [x] 2.1 Add `addressApiKey?: string` to `NfeConfig` interface in `src/core/types.ts`
+- [x] 2.2 Add `Address` and `AddressLookupResponse` types to `src/core/types.ts`
+- [x] 2.3 Add `AddressSearchOptions` type with `filter` field
 
 ## 3. Multi-API Support Infrastructure
 
-- [ ] 3.1 Refactor `NfeClient` constructor to not require `apiKey` (make it optional)
-- [ ] 3.2 Add `resolveAddressApiKey()` private method with fallback chain logic
-- [ ] 3.3 Add `resolveMainApiKey()` private method for existing resources
-- [ ] 3.4 Add `getEnvironmentVariable()` helper method for reading `NFE_ADDRESS_API_KEY`
-- [ ] 3.5 Convert `serviceInvoices`, `companies`, `legalPeople`, `naturalPeople`, `webhooks` to lazy getters with validation
+- [x] 3.1 Refactor `NfeClient` constructor to not require `apiKey` (make it optional)
+- [x] 3.2 Add `resolveAddressApiKey()` private method with fallback chain logic
+- [x] 3.3 Add `resolveMainApiKey()` private method for existing resources
+- [x] 3.4 Add `getEnvironmentVariable()` helper method for reading `NFE_ADDRESS_API_KEY`
+- [x] 3.5 Convert `serviceInvoices`, `companies`, `legalPeople`, `naturalPeople`, `webhooks` to lazy getters with validation
 
 ## 4. Addresses Resource Implementation
 
-- [ ] 4.1 Create `src/core/resources/addresses.ts` with `AddressesResource` class
-- [ ] 4.2 Implement `lookupByPostalCode(postalCode: string)` method
-- [ ] 4.3 Implement `search(options: AddressSearchOptions)` method with `$filter` query param
-- [ ] 4.4 Implement `lookupByTerm(term: string)` method
-- [ ] 4.5 Add input validation for postal code format (8 digits, with or without hyphen)
-- [ ] 4.6 Add input validation for empty term
-- [ ] 4.7 Export `AddressesResource` from `src/core/resources/index.ts`
+- [x] 4.1 Create `src/core/resources/addresses.ts` with `AddressesResource` class
+- [x] 4.2 Implement `lookupByPostalCode(postalCode: string)` method
+- [x] 4.3 Implement `search(options: AddressSearchOptions)` method with `$filter` query param
+- [x] 4.4 Implement `lookupByTerm(term: string)` method
+- [x] 4.5 Add input validation for postal code format (8 digits, with or without hyphen)
+- [x] 4.6 Add input validation for empty term
+- [x] 4.7 Export `AddressesResource` from `src/core/resources/index.ts`
 
 ## 5. Client Integration
 
-- [ ] 5.1 Add lazy `addresses` getter to `NfeClient` class
-- [ ] 5.2 Create separate `HttpClient` instance for addresses with `https://address.api.nfe.io/v2` base URL
-- [ ] 5.3 Throw `ConfigurationError` with descriptive message when no API key available
-- [ ] 5.4 Export Address types from `src/index.ts`
+- [x] 5.1 Add lazy `addresses` getter to `NfeClient` class
+- [x] 5.2 Create separate `HttpClient` instance for addresses with `https://address.api.nfe.io/v2` base URL
+- [x] 5.3 Throw `ConfigurationError` with descriptive message when no API key available
+- [x] 5.4 Export Address types from `src/index.ts`
 
 ## 6. Unit Tests
 
-- [ ] 6.1 Create `tests/unit/resources/addresses.test.ts`
-- [ ] 6.2 Test `lookupByPostalCode()` with valid CEP returns correct response
-- [ ] 6.3 Test `lookupByPostalCode()` with invalid CEP throws `ValidationError`
-- [ ] 6.4 Test `lookupByTerm()` with empty term throws `ValidationError`
-- [ ] 6.5 Test `search()` passes filter to query params correctly
-- [ ] 6.6 Create `tests/unit/client-multikey.test.ts` for multi-API key tests
-- [ ] 6.7 Test lazy getter throws when no key available
-- [ ] 6.8 Test fallback chain: `addressApiKey` → `apiKey` → env vars
-- [ ] 6.9 Test isolated resource usage (only addresses, no apiKey)
+- [x] 6.1 Create `tests/unit/resources/addresses.test.ts`
+- [x] 6.2 Test `lookupByPostalCode()` with valid CEP returns correct response
+- [x] 6.3 Test `lookupByPostalCode()` with invalid CEP throws `ValidationError`
+- [x] 6.4 Test `lookupByTerm()` with empty term throws `ValidationError`
+- [x] 6.5 Test `search()` passes filter to query params correctly
+- [x] 6.6 Create `tests/unit/client-multikey.test.ts` for multi-API key tests
+- [x] 6.7 Test lazy getter throws when no key available
+- [x] 6.8 Test fallback chain: `addressApiKey` → `apiKey` → env vars
+- [x] 6.9 Test isolated resource usage (only addresses, no apiKey)
 
 ## 7. Integration Tests
 
-- [ ] 7.1 Create `tests/integration/addresses.integration.test.ts`
-- [ ] 7.2 Test real API call to lookup by postal code (requires test API key)
-- [ ] 7.3 Test real API call to search by term
-- [ ] 7.4 Test 404 response handling for non-existent CEP
+- [x] 7.1 Create `tests/integration/addresses.integration.test.ts`
+- [x] 7.2 Test real API call to lookup by postal code (requires test API key)
+- [x] 7.3 Test real API call to search by term
+- [x] 7.4 Test 404 response handling for non-existent CEP
 
 ## 8. Documentation & Examples
 
-- [ ] 8.1 Create `examples/address-lookup.js` with usage examples
-- [ ] 8.2 Update `README.md` with Addresses resource documentation
-- [ ] 8.3 Document `addressApiKey` configuration option
-- [ ] 8.4 Document environment variables `NFE_ADDRESS_API_KEY`
-- [ ] 8.5 Add JSDoc comments to all public methods in `AddressesResource`
+- [x] 8.1 Create `examples/address-lookup.js` with usage examples
+- [x] 8.2 Update `README.md` with Addresses resource documentation
+- [x] 8.3 Document `addressApiKey` configuration option
+- [x] 8.4 Document environment variables `NFE_ADDRESS_API_KEY`
+- [x] 8.5 Add JSDoc comments to all public methods in `AddressesResource`
 
 ## 9. Final Validation
 
-- [ ] 9.1 Run `npm run typecheck` - ensure zero errors
-- [ ] 9.2 Run `npm run lint` - ensure zero warnings
-- [ ] 9.3 Run `npm test` - ensure all tests pass
-- [ ] 9.4 Run `npm run build` - ensure successful build
+- [x] 9.1 Run `npm run typecheck` - ensure zero errors
+- [x] 9.2 Run `npm run lint` - ensure zero warnings (only pre-existing `any` warnings)
+- [x] 9.3 Run `npm test` - ensure all tests pass (322 passing, 47 skipped)
+- [x] 9.4 Run `npm run build` - ensure successful build
 - [ ] 9.5 Test examples manually against sandbox/production API