refactor(config): unifica addressApiKey e cteApiKey em dataApiKey

Consolida as chaves de API separadas para serviços de consulta
(addressApiKey e cteApiKey) em uma única propriedade dataApiKey,
simplificando a configuração do SDK e refletindo a arquitetura
real da API NFE.io (duas categorias: fiscal e consulta).

Motivação:
- A API NFE.io utiliza apenas duas categorias de chave: uma para
  operações fiscais (NFS-e, Companies, etc.) e outra para todos
  os serviços de consulta (Endereços, CT-e, CNPJ, CPF)
- Ter chaves separadas (addressApiKey, cteApiKey) adicionava
  complexidade desnecessária sem benefício real
- A unificação prepara o SDK para futuros serviços de consulta
  que usarão a mesma chave

Alterações em tipos (src/core/types.ts):
- NfeConfig: remove addressApiKey e cteApiKey, adiciona dataApiKey
- RequiredNfeConfig: idem, mantendo tipagem string | undefined

Alterações no client (src/core/client.ts):
- Remove resolveAddressApiKey() e resolveCteApiKey()
- Adiciona resolveDataApiKey() com cadeia de fallback:
  config.dataApiKey → config.apiKey → NFE_DATA_API_KEY → NFE_API_KEY
- getAddressHttpClient() e getCteHttpClient() usam resolveDataApiKey()
- validateAndNormalizeConfig() normaliza dataApiKey ao invés de duas
- updateConfig() preserva cache de dataApiKey ao invés de duas
- Mensagens de erro atualizadas para referenciar dataApiKey
- JSDoc atualizado nos getters addresses e transportationInvoices

Alterações em resources:
- addresses.ts: JSDoc atualizado para referenciar dataApiKey
- transportation-invoices.ts: JSDoc atualizado para referenciar dataApiKey

Alterações em testes:
- tests/unit/client-multikey.test.ts: reescrito (38 testes)
  - Testa cadeia de fallback para Addresses e CT-e via dataApiKey
  - Testa que ambos services resolvem a mesma chave
  - Testa uso isolado de dataApiKey sem apiKey
  - Testa que NFE_ADDRESS_API_KEY e NFE_CTE_API_KEY não são mais
    reconhecidas (breaking change documentada)
- tests/integration/addresses.integration.test.ts: atualizado

Alterações em documentação:
- README.md: config examples, tabela env vars (2 vars ao invés de 3),
  notas sobre Address API e CT-e
- docs/API.md: NfeConfig type, nota do recurso CT-e

Alterações em exemplos:
- examples/setup.js: template .env.test usa NFE_DATA_API_KEY
- examples/address-lookup.js: config e env vars atualizados
- examples/transportation-invoices.js: config e env vars atualizados

Arquivos gerados (src/generated/):
- Timestamps atualizados pela regeneração do openapi-typescript

Validação:
- TypeScript: zero erros (npx tsc --noEmit)
- Testes: 381 passed, 47 skipped (integration)
- Build: ESM + CJS + DTS gerados com sucesso

BREAKING CHANGE: addressApiKey e cteApiKey foram removidos de NfeConfig.
Use dataApiKey para configurar a chave de serviços de consulta.
As variáveis de ambiente NFE_ADDRESS_API_KEY e NFE_CTE_API_KEY foram
substituídas por NFE_DATA_API_KEY.

Author: andrekutianski

README.md

@@ -360,7 +360,7 @@ const filtrado = await nfe.addresses.search({
 });
 ```
 
-> **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.
+> **Nota:** A API de Endereços usa um host separado (`address.api.nfe.io`). Você pode configurar uma chave API específica com `dataApiKey`, ou o SDK usará `apiKey` como fallback.
 
 #### 🚚 Notas de Transporte - CT-e (`nfe.transportationInvoices`)
 
@@ -420,7 +420,7 @@ const eventoXml = await nfe.transportationInvoices.downloadEventXml(
 );
 ```
 
-> **Nota:** A API de CT-e usa um host separado (`api.nfse.io`). Você pode configurar uma chave API específica com `cteApiKey`, ou o SDK usará `apiKey` como fallback.
+> **Nota:** A API de CT-e usa um host separado (`api.nfse.io`). Você pode configurar uma chave API específica com `dataApiKey`, ou o SDK usará `apiKey` como fallback.
 
 **Pré-requisitos:**
 - Empresa deve estar cadastrada com certificado digital A1 válido
@@ -432,16 +432,12 @@ const eventoXml = await nfe.transportationInvoices.downloadEventXml(
 
 ```typescript
 const nfe = new NfeClient({
-  // Chave API principal do NFE.io (opcional se usar apenas Addresses com addressApiKey)
+  // Chave API principal do NFE.io (operações com documentos fiscais)
   apiKey: 'sua-chave-api',
 
-  // Opcional: Chave API específica para consulta de endereços
+  // Opcional: Chave API para serviços de consulta (Endereços, CT-e, CNPJ, CPF)
   // Se não fornecida, usa apiKey como fallback
-  addressApiKey: 'sua-chave-address-api',
-  
-  // Opcional: Chave API específica para consulta de CT-e
-  // Se não fornecida, usa apiKey como fallback
-  cteApiKey: 'sua-chave-cte-api',
+  dataApiKey: 'sua-chave-data-api',
 
   // Opcional: Ambiente (padrão: 'production')
   environment: 'production', // ou 'sandbox'
@@ -469,14 +465,12 @@ 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`) |
-| `NFE_CTE_API_KEY` | Chave API para CT-e (fallback para `cteApiKey`) |
+| `NFE_DATA_API_KEY` | Chave API para serviços de consulta (fallback para `dataApiKey`) |
 
 ```bash
 # Configurar via ambiente
 export NFE_API_KEY="sua-chave-api"
-export NFE_ADDRESS_API_KEY="sua-chave-address"
-export NFE_CTE_API_KEY="sua-chave-cte"
+export NFE_DATA_API_KEY="sua-chave-data"
 
 # Usar SDK sem passar chaves no código
 const nfe = new NfeClient({});

docs/API.md

@@ -1513,7 +1513,7 @@ const events = await nfe.webhooks.getAvailableEvents();
 
 Manage CT-e (Conhecimento de Transporte Eletrônico) documents via SEFAZ Distribuição DFe.
 
-> **Note:** This resource uses a separate API host (`api.nfse.io`). You can configure a specific API key with `cteApiKey`, or the SDK will use `apiKey` as fallback.
+> **Note:** This resource uses a separate API host (`api.nfse.io`). You can configure a specific API key with `dataApiKey`, or the SDK will use `apiKey` as fallback.
 
 **Prerequisites:**
 - Company must be registered with a valid A1 digital certificate
@@ -1651,8 +1651,7 @@ fs.writeFileSync('cte-event.xml', eventXml);
 ```typescript
 interface NfeConfig {
   apiKey?: string;
-  addressApiKey?: string;  // Specific API key for address lookups
-  cteApiKey?: string;      // Specific API key for CT-e (transportation invoices)
+  dataApiKey?: string;     // API key for data/query services (Addresses, CT-e, CNPJ, CPF)
   environment?: 'production' | 'development';
   baseUrl?: string;
   timeout?: number;

examples/address-lookup.js

@@ -5,7 +5,7 @@
  * Brazilian addresses (CEP/postal code lookups).
  *
  * Prerequisites:
- *   - Set NFE_ADDRESS_API_KEY or NFE_API_KEY environment variable
+ *   - Set NFE_DATA_API_KEY or NFE_API_KEY environment variable
  *   - Or pass the API key directly in the configuration
  *
  * Run this example:
@@ -14,12 +14,12 @@
 
 import { NfeClient } from '../dist/index.js';
 
-// Configuration with separate address API key (optional)
+// Configuration with separate data API key (optional)
 const client = new NfeClient({
-  // You can use a separate API key for address lookups
-  // addressApiKey: process.env.NFE_ADDRESS_API_KEY,
+  // You can use a separate API key for data/query services (addresses, CT-e)
+  // dataApiKey: process.env.NFE_DATA_API_KEY,
 
-  // Or use the main API key (will be used as fallback for addresses)
+  // Or use the main API key (will be used as fallback for data services)
   apiKey: process.env.NFE_API_KEY,
 
   // Environment: 'production' or 'development'
@@ -103,21 +103,21 @@ async function searchWithFilter() {
 }
 
 /**
- * Example 4: Using only addressApiKey (isolated usage)
+ * Example 4: Using only dataApiKey (isolated usage)
  */
 async function isolatedAddressUsage() {
-  console.log('\n🔐 Example 4: Isolated Address API Usage');
+  console.log('\n🔐 Example 4: Isolated Data 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,
+  // Create a client with ONLY dataApiKey
+  // This is useful when you only have access to data/query services
+  const dataOnlyClient = new NfeClient({
+    dataApiKey: process.env.NFE_DATA_API_KEY || process.env.NFE_API_KEY,
   });
 
   try {
     // Addresses work
-    const result = await addressOnlyClient.addresses.lookupByPostalCode('20040-020');
+    const result = await dataOnlyClient.addresses.lookupByPostalCode('20040-020');
     console.log('Rio de Janeiro CEP lookup succeeded!');
     console.log(`  ${result.street}, ${result.city?.name}/${result.state}`);
   } catch (error) {
@@ -165,9 +165,9 @@ 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) {
+  if (!process.env.NFE_API_KEY && !process.env.NFE_DATA_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('Please set NFE_API_KEY or NFE_DATA_API_KEY environment variable.');
     console.error('\nExample:');
     console.error('  export NFE_API_KEY="your-api-key"');
     console.error('  node examples/address-lookup.js');

examples/setup.js

@@ -113,10 +113,9 @@ ${companyId ? `NFE_COMPANY_ID=${companyId}` : '# NFE_COMPANY_ID=seu-company-id-a
 # Timeout em ms (opcional)
 # NFE_TIMEOUT=30000
 
-# Chaves de API específicas (opcional)
-# Se não definidas, usa NFE_API_KEY como fallback
-# NFE_ADDRESS_API_KEY=sua-chave-address-aqui
-# NFE_CTE_API_KEY=sua-chave-cte-aqui
+# Chave de API para serviços de consulta (opcional)
+# Se não definida, usa NFE_API_KEY como fallback
+# NFE_DATA_API_KEY=sua-chave-data-aqui
 `;
 
   try {

examples/transportation-invoices.js

@@ -11,12 +11,12 @@
  *
  * Configuration:
  * Set one of the following environment variables:
- * - NFE_CTE_API_KEY - Specific CT-e API key (recommended)
+ * - NFE_DATA_API_KEY - Data/query API key (recommended)
  * - NFE_API_KEY - Main API key (will be used as fallback)
  *
  * Or configure in code:
  * const nfe = new NfeClient({
- *   cteApiKey: 'your-cte-api-key',  // Or use apiKey if you have unified access
+ *   dataApiKey: 'your-data-api-key',  // Or use apiKey if you have unified access
  * });
  *
  * Usage:
@@ -34,12 +34,12 @@ import { NfeClient } from 'nfe-io';
 // ============================================================================
 
 // Create client - API key fallback chain:
-// 1. cteApiKey (config)
+// 1. dataApiKey (config)
 // 2. apiKey (config)
-// 3. NFE_CTE_API_KEY (env)
+// 3. NFE_DATA_API_KEY (env)
 // 4. NFE_API_KEY (env)
 const nfe = new NfeClient({
-  // cteApiKey: process.env.NFE_CTE_API_KEY,  // Uncomment for explicit configuration
+  // dataApiKey: process.env.NFE_DATA_API_KEY,  // Uncomment for explicit configuration
 });
 
 // ============================================================================
@@ -277,7 +277,7 @@ async function main() {
   } catch (error) {
     console.error('\n❌ Error:', error.message);
     if (error.name === 'ConfigurationError') {
-      console.error('   Make sure you have set NFE_CTE_API_KEY or NFE_API_KEY');
+      console.error('   Make sure you have set NFE_DATA_API_KEY or NFE_API_KEY');
     }
     if (error.name === 'ValidationError') {
       console.error('   Check your input parameters');

src/core/client.ts

@@ -285,10 +285,10 @@ export class NfeClient {
    * - Search by generic term
    *
    * **Note:** This resource uses a different API host (address.api.nfe.io).
-   * Configure `addressApiKey` for a separate key, or it will fallback to `apiKey`.
+   * Configure `dataApiKey` for a separate key, or it will fallback to `apiKey`.
    *
    * @see {@link AddressesResource}
-   * @throws {ConfigurationError} If no API key is configured (addressApiKey or apiKey)
+   * @throws {ConfigurationError} If no API key is configured (dataApiKey or apiKey)
    *
    * @example
    * ```typescript
@@ -318,10 +318,10 @@ export class NfeClient {
    * - Webhook must be configured to receive CT-e notifications
    *
    * **Note:** This resource uses a different API host (api.nfse.io).
-   * Configure `cteApiKey` for a separate key, or it will fallback to `apiKey`.
+   * Configure `dataApiKey` for a separate key, or it will fallback to `apiKey`.
    *
    * @see {@link TransportationInvoicesResource}
-   * @throws {ConfigurationError} If no API key is configured (cteApiKey or apiKey)
+   * @throws {ConfigurationError} If no API key is configured (dataApiKey or apiKey)
    *
    * @example
    * ```typescript
@@ -379,11 +379,11 @@ export class NfeClient {
    * });
    * ```
    *
-   * @example With only address API key
+   * @example With only data API key
    * ```typescript
-   * // Only use address lookup, no main API access
+   * // Only use data services (address lookup, CT-e), no main API access
    * const nfe = new NfeClient({
-   *   addressApiKey: 'address-api-key'
+   *   dataApiKey: 'data-api-key'
    * });
    * await nfe.addresses.lookupByPostalCode('01310-100');
    * ```
@@ -431,10 +431,10 @@ export class NfeClient {
    */
   private getAddressHttpClient(): HttpClient {
     if (!this._addressHttp) {
-      const apiKey = this.resolveAddressApiKey();
+      const apiKey = this.resolveDataApiKey();
       if (!apiKey) {
         throw new ConfigurationError(
-          'API key required for Addresses. Set "addressApiKey" or "apiKey" in config, or NFE_ADDRESS_API_KEY/NFE_API_KEY environment variable.'
+          'API key required for data services. Set "dataApiKey" or "apiKey" in config, or NFE_DATA_API_KEY/NFE_API_KEY environment variable.'
         );
       }
       const httpConfig = buildHttpConfig(
@@ -459,27 +459,14 @@ export class NfeClient {
   }
 
   /**
-   * Resolve the Address API key using fallback chain
-   * Order: addressApiKey → apiKey → NFE_ADDRESS_API_KEY → NFE_API_KEY
+   * Resolve the data API key using fallback chain
+   * Order: dataApiKey → apiKey → NFE_DATA_API_KEY → NFE_API_KEY
    */
-  private resolveAddressApiKey(): string | undefined {
+  private resolveDataApiKey(): string | undefined {
     return (
-      this.config.addressApiKey ||
+      this.config.dataApiKey ||
       this.config.apiKey ||
-      this.getEnvironmentVariable('NFE_ADDRESS_API_KEY') ||
-      this.getEnvironmentVariable('NFE_API_KEY')
-    );
-  }
-
-  /**
-   * Resolve the CT-e API key using fallback chain
-   * Order: cteApiKey → apiKey → NFE_CTE_API_KEY → NFE_API_KEY
-   */
-  private resolveCteApiKey(): string | undefined {
-    return (
-      this.config.cteApiKey ||
-      this.config.apiKey ||
-      this.getEnvironmentVariable('NFE_CTE_API_KEY') ||
+      this.getEnvironmentVariable('NFE_DATA_API_KEY') ||
       this.getEnvironmentVariable('NFE_API_KEY')
     );
   }
@@ -490,10 +477,10 @@ export class NfeClient {
    */
   private getCteHttpClient(): HttpClient {
     if (!this._cteHttp) {
-      const apiKey = this.resolveCteApiKey();
+      const apiKey = this.resolveDataApiKey();
       if (!apiKey) {
         throw new ConfigurationError(
-          'API key required for Transportation Invoices (CT-e). Set "cteApiKey" or "apiKey" in config, or NFE_CTE_API_KEY/NFE_API_KEY environment variable.'
+          'API key required for data services. Set "dataApiKey" or "apiKey" in config, or NFE_DATA_API_KEY/NFE_API_KEY environment variable.'
         );
       }
       const httpConfig = buildHttpConfig(
@@ -514,8 +501,7 @@ export class NfeClient {
   private validateAndNormalizeConfig(config: NfeConfig): RequiredNfeConfig {
     // API keys are now optional - validated lazily when resources are accessed
     const apiKey = config.apiKey?.trim() || undefined;
-    const addressApiKey = config.addressApiKey?.trim() || undefined;
-    const cteApiKey = config.cteApiKey?.trim() || undefined;
+    const dataApiKey = config.dataApiKey?.trim() || undefined;
 
     // Normalize environment
     const environment = config.environment || 'production';
@@ -534,8 +520,7 @@ export class NfeClient {
 
     const normalizedConfig: RequiredNfeConfig = {
       apiKey,
-      addressApiKey,
-      cteApiKey,
+      dataApiKey,
       environment,
       baseUrl: config.baseUrl || this.getDefaultBaseUrl(),
       timeout: config.timeout || 30000,
@@ -632,11 +617,8 @@ export class NfeClient {
     if (normalizedConfig.apiKey === undefined && this.config.apiKey !== undefined && newConfig.apiKey === undefined) {
       normalizedConfig.apiKey = this.config.apiKey;
     }
-    if (normalizedConfig.addressApiKey === undefined && this.config.addressApiKey !== undefined && newConfig.addressApiKey === undefined) {
-      normalizedConfig.addressApiKey = this.config.addressApiKey;
-    }
-    if (normalizedConfig.cteApiKey === undefined && this.config.cteApiKey !== undefined && newConfig.cteApiKey === undefined) {
-      normalizedConfig.cteApiKey = this.config.cteApiKey;
+    if (normalizedConfig.dataApiKey === undefined && this.config.dataApiKey !== undefined && newConfig.dataApiKey === undefined) {
+      normalizedConfig.dataApiKey = this.config.dataApiKey;
     }
 
     // Update internal config

src/core/resources/addresses.ts

@@ -68,7 +68,7 @@ function normalizePostalCode(postalCode: string): string {
  * Data is sourced from Correios DNE (Diretório Nacional de Endereços) integrated with IBGE city codes.
  *
  * **Note:** This resource uses a different API host (address.api.nfe.io) and may require
- * a separate API key configured via `addressApiKey` in the client configuration.
+ * a separate API key configured via `dataApiKey` in the client configuration.
  *
  * @example Basic postal code lookup
  * ```typescript

src/core/resources/transportation-invoices.ts

@@ -73,7 +73,7 @@ function validateCompanyId(companyId: string): void {
  * - Webhook must be configured to receive CT-e notifications
  *
  * **Note:** This resource uses a different API host (api.nfse.io) and may require
- * a separate API key configured via `cteApiKey` in the client configuration.
+ * a separate API key configured via `dataApiKey` in the client configuration.
  * If not set, it falls back to `apiKey`.
  *
  * @example Enable automatic CT-e search

src/core/types.ts

@@ -17,10 +17,8 @@
 export interface NfeConfig {
   /** NFE.io API Key for main resources (companies, invoices, etc.) */
   apiKey?: string;
-  /** NFE.io API Key specifically for Address API (optional, falls back to apiKey) */
-  addressApiKey?: string;
-  /** NFE.io API Key specifically for CT-e API (optional, falls back to apiKey) */
-  cteApiKey?: string;
+  /** NFE.io API Key for data/query services: Addresses, CT-e, CNPJ, CPF (optional, falls back to apiKey) */
+  dataApiKey?: string;
   /** Environment to use (both use same endpoint, differentiated by API key) */
   environment?: 'production' | 'development';
   /** Custom base URL (overrides environment) */
@@ -296,12 +294,10 @@ export interface PollOptions {
  * API keys remain optional since validation is done lazily when resources are accessed.
  */
 export interface RequiredNfeConfig {
-  /** Main API key (may be undefined if only using address API) */
+  /** Main API key (may be undefined if only using data services) */
   apiKey: string | undefined;
-  /** Address API key (may be undefined, will fallback to apiKey) */
-  addressApiKey: string | undefined;
-  /** CT-e API key (may be undefined, will fallback to apiKey) */
-  cteApiKey: string | undefined;
+  /** Data API key for query services: Addresses, CT-e, CNPJ, CPF (may be undefined, will fallback to apiKey) */
+  dataApiKey: string | undefined;
   /** Environment */
   environment: 'production' | 'development';
   /** Base URL for main API */

src/generated/calculo-impostos-v1.ts

@@ -4,7 +4,7 @@
  * Do not edit this file directly.
  *
  * To regenerate: npm run generate
- * Last generated: 2026-02-03T01:51:28.320Z
+ * Last generated: 2026-02-14T00:32:45.806Z
  * Generator: openapi-typescript
  */