Skip to content

3.0.0

Choose a tag to compare

@andrekutianski andrekutianski released this 19 Jan 01:24
· 137 commits to master since this release
7927be2

🎉 NFE.io SDK v3.0.0 - Release Notes


📣 Anúncio

Estamos muito felizes em anunciar o lançamento da versão 3.0 do SDK oficial NFE.io para Node.js! Esta é uma reescrita completa do SDK, modernizando completamente a base de código com TypeScript, eliminando dependências em runtime e oferecendo uma API limpa baseada em async/await.

🌟 Destaques Principais

  • ✨ TypeScript Nativo - Segurança de tipos completa e IntelliSense rico
  • 🚀 Zero Dependências em Runtime - Usa Fetch API nativa do Node.js
  • ⚡ API Moderna Async/Await - Sem callbacks, código mais limpo
  • 🔄 Retry Automático - Lógica de retry inteligente com exponential backoff
  • 📦 Suporte Dual ESM/CommonJS - Funciona com ambos os sistemas de módulos
  • 🧪 Bem Testado - Mais de 80 testes com 88% de cobertura de código
  • 📖 Documentação Completa - JSDoc em todas as APIs públicas

🎯 O Que É Novo

✨ Recursos Principais

1. TypeScript Nativo com Segurança de Tipos Completa

import { NfeClient, ServiceInvoice } from 'nfe-io';

const nfe = new NfeClient({ 
  apiKey: 'sua-chave-api',
  environment: 'production' 
});

// IntelliSense completo e validação de tipos
const invoice: ServiceInvoice = await nfe.serviceInvoices.create(companyId, {
  borrower: {
    federalTaxNumber: '12345678000190',
    name: 'Cliente LTDA',
    email: 'cliente@exemplo.com.br'
  },
  cityServiceCode: '12345',
  servicesAmount: 1000.00
});

2. Zero Dependências em Runtime

  • Antes (v2): Dependia de when@3.1.0 (biblioteca desatualizada de promises)
  • Agora (v3): Usa apenas APIs nativas do Node.js 18+
  • Benefício: Menor superfície de ataque, menos vulnerabilidades, instalação mais rápida

3. API Moderna Async/Await

Antes (v2 - Callbacks):

nfe.serviceInvoices.create('company-id', data, function(err, invoice) {
  if (err) {
    console.error('Erro:', err);
    return;
  }
  console.log('Nota criada:', invoice);
});

Agora (v3 - Async/Await):

try {
  const invoice = await nfe.serviceInvoices.create('company-id', data);
  console.log('Nota criada:', invoice);
} catch (error) {
  console.error('Erro:', error);
}

4. Retry Automático com Exponential Backoff

const nfe = new NfeClient({
  apiKey: 'sua-chave-api',
  retryConfig: {
    maxRetries: 5,        // Até 5 tentativas
    baseDelay: 1000,      // Delay inicial de 1 segundo
    maxDelay: 30000,      // Delay máximo de 30 segundos
    retryableStatuses: [408, 429, 500, 502, 503, 504]
  }
});

// Retries automáticos em caso de erros temporários
const invoice = await nfe.serviceInvoices.create(companyId, data);

5. Polling Automático para Processamento Assíncrono

Novidade: Método createAndWait() para polling automático!

// Cria a nota e aguarda automaticamente o processamento
const invoice = await nfe.serviceInvoices.createAndWait(companyId, data, {
  maxAttempts: 30,   // Até 30 tentativas
  interval: 2000,    // Verifica a cada 2 segundos
  onProgress: (attempt) => {
    console.log(`Tentativa ${attempt} de 30...`);
  }
});

console.log('Nota processada:', invoice);

Alternativa - Polling Manual:

const result = await nfe.serviceInvoices.create(companyId, data);

if (result.status === 'pending') {
  const invoice = await nfe.pollUntilComplete(
    () => nfe.serviceInvoices.retrieve(companyId, result.id),
    { maxAttempts: 30, interval: 2000 }
  );
}

📦 Recursos Implementados

✅ Service Invoices (Notas Fiscais de Serviço)

  • ✅ create() - Criar nota fiscal com suporte a resposta 202
  • ✅ createAndWait() - NOVO! Criar e aguardar processamento
  • ✅ list() - Listar notas com paginação manual
  • ✅ retrieve() - Buscar nota específica
  • ✅ cancel() - Cancelar nota emitida
  • ✅ sendEmail() - Enviar nota por email
  • ✅ downloadPdf() - Download do PDF da nota
  • ✅ downloadXml() - Download do XML da nota

✅ Companies (Empresas)

  • ✅ create() - Criar empresa
  • ✅ list() - Listar empresas
  • ✅ retrieve() - Buscar empresa específica
  • ✅ update() - Atualizar empresa
  • ✅ uploadCertificate() - Upload de certificado digital (A1)

✅ Legal People (Pessoas Jurídicas)

  • ✅ create() - Criar pessoa jurídica
  • ✅ list() - Listar pessoas jurídicas
  • ✅ retrieve() - Buscar pessoa jurídica específica
  • ✅ update() - Atualizar pessoa jurídica
  • ✅ delete() - Deletar pessoa jurídica
  • ✅ findByTaxNumber() - NOVO! Buscar por CNPJ
  • ✅ createBatch() - NOVO! Criar múltiplas em lote

✅ Natural People (Pessoas Físicas)

  • ✅ create() - Criar pessoa física
  • ✅ list() - Listar pessoas físicas
  • ✅ retrieve() - Buscar pessoa física específica
  • ✅ update() - Atualizar pessoa física
  • ✅ delete() - Deletar pessoa física
  • ✅ findByTaxNumber() - NOVO! Buscar por CPF
  • ✅ createBatch() - NOVO! Criar múltiplas em lote

✅ Webhooks

  • ✅ create() - Criar webhook
  • ✅ list() - Listar webhooks
  • ✅ retrieve() - Buscar webhook específico
  • ✅ update() - Atualizar webhook
  • ✅ delete() - Deletar webhook
  • ✅ validateSignature() - NOVO! Validar assinatura do webhook

🛡️ Sistema de Erros Melhorado

Erros tipados com classes específicas para melhor tratamento:

import {
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  ServerError,
  ConnectionError,
  TimeoutError
} from 'nfe-io';

try {
  const invoice = await nfe.serviceInvoices.create(companyId, data);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('❌ Chave de API inválida');
  } else if (error instanceof ValidationError) {
    console.error('❌ Dados inválidos:', error.details);
    console.error('Campos com erro:', error.fields);
  } else if (error instanceof RateLimitError) {
    console.error('⏳ Rate limit atingido. Aguarde:', error.retryAfter, 'segundos');
  } else if (error instanceof NotFoundError) {
    console.error('❌ Recurso não encontrado');
  } else if (error instanceof ServerError) {
    console.error('❌ Erro no servidor NFE.io');
  } else if (error instanceof ConnectionError) {
    console.error('❌ Erro de conexão');
  } else if (error instanceof TimeoutError) {
    console.error('⏱️ Timeout na requisição');
  }
}

Estrutura dos Erros:

  • message - Mensagem descritiva do erro
  • statusCode - Código HTTP do erro
  • requestId - ID da requisição para suporte
  • details - Detalhes adicionais do erro
  • fields - (ValidationError) Campos com erro

🔧 Configuração Flexível

const nfe = new NfeClient({
  // Chave de API (obrigatória)
  apiKey: 'sua-chave-api', // ou use NFE_API_KEY env var
  
  // Ambiente (opcional, padrão: 'production')
  environment: 'production', // ou 'development'
  
  // URL base customizada (opcional)
  baseUrl: 'https://api.nfe.io/v1',
  
  // Timeout de requisições (opcional, padrão: 30000ms)
  timeout: 60000, // 60 segundos
  
  // Configuração de retry (opcional)
  retryConfig: {
    maxRetries: 5,
    baseDelay: 1000,
    maxDelay: 30000,
    retryableStatuses: [408, 429, 500, 502, 503, 504]
  }
});

// Configuração dinâmica
nfe.updateConfig({
  timeout: 90000,
  environment: 'development'
});

📖 Documentação e IntelliSense

Toda API pública tem JSDoc completo com exemplos:

/**
 * Create a new service invoice
 *
 * @param companyId - Company ID
 * @param data - Invoice data
 * @returns Created invoice or pending response
 *
 * @example
 * ```typescript
 * const invoice = await nfe.serviceInvoices.create('company-id', {
 *   borrower: { federalTaxNumber: '12345678000190', name: 'Cliente' },
 *   cityServiceCode: '12345',
 *   servicesAmount: 1000.00
 * });
 * ```
 */
create(companyId: string, data: CreateServiceInvoiceRequest): Promise<ServiceInvoice>;

🧪 Testes Completos

  • 80+ testes automatizados
  • 88% de cobertura de código
  • Testes unitários para toda lógica de negócio
  • Testes de integração com mocks da API
  • Testes de erro cobrindo todos os cenários
# Rodar testes
npm test

# Rodar com cobertura
npm run test:coverage

# Rodar em modo watch
npm run test:watch

🚨 Mudanças Incompatíveis (Breaking Changes)

1. Requisito de Node.js

  • Antes: Node.js >= 12.0.0
  • Agora: Node.js >= 18.0.0 (necessário para Fetch API nativo)

Ação necessária: Atualize para Node.js 18 ou superior

# Verificar versão
node --version

# Se < 18, atualize via nvm
nvm install 18
nvm use 18

2. Inicialização do Cliente

Antes (v2):

var nfe = require('nfe-io')('sua-chave-api');

Agora (v3):

// CommonJS
const { NfeClient } = require('nfe-io');
const nfe = new NfeClient({ apiKey: 'sua-chave-api' });

// ESM
import { NfeClient } from 'nfe-io';
const nfe = new NfeClient({ apiKey: 'sua-chave-api' });

3. Callbacks Removidos

Antes (v2):

nfe.serviceInvoices.create('company-id', data, function(err, invoice) {
  if (err) return console.error(err);
  console.log(invoice);
});

Agora (v3):

try {
  const invoice = await nfe.serviceInvoices.create('company-id', data);
  console.log(invoice);
} catch (error) {
  console.error(error);
}

4. Tratamento de Erros

Antes (v2):

if (err.type === 'AuthenticationError') {
  // tratar
}

Agora (v3):

import { AuthenticationError } from 'nfe-io';

if (error instanceof AuthenticationError) {
  // tratar
}

5. Configuração

Antes (v2):

var nfe = require('nfe-io')('api-key');
nfe.setTimeout(60000);

Agora (v3):

const nfe = new NfeClient({
  apiKey: 'api-key',
  timeout: 60000
});

// ou dinamicamente
nfe.updateConfig({ timeout: 90000 });

6. Dependências Removidas

  • ❌ when@3.1.0 - Substituído por promises nativas
  • ❌ Todas as dependências em runtime removidas

📋 Guia de Migração

Passo a Passo

1. Atualizar Node.js

node --version  # Deve ser >= 18.0.0

2. Atualizar o Pacote

npm install nfe-io@3

3. Atualizar Imports/Requires

CommonJS:

// Antes
var nfe = require('nfe-io')('api-key');

// Depois
const { NfeClient } = require('nfe-io');
const nfe = new NfeClient({ apiKey: 'api-key' });

ESM:

// Novo
import { NfeClient } from 'nfe-io';
const nfe = new NfeClient({ apiKey: 'api-key' });

4. Converter Callbacks para Async/Await

Antes:

nfe.serviceInvoices.create(companyId, data, function(err, invoice) {
  if (err) return handleError(err);
  processInvoice(invoice);
});

Depois:

async function createInvoice() {
  try {
    const invoice = await nfe.serviceInvoices.create(companyId, data);
    processInvoice(invoice);
  } catch (error) {
    handleError(error);
  }
}

5. Atualizar Tratamento de Erros

Antes:

if (err.type === 'AuthenticationError') { }

Depois:

import { AuthenticationError } from 'nfe-io';
if (error instanceof AuthenticationError) { }

6. Testar Completamente

npm test

Migração Gradual

Você pode executar v2 e v3 lado a lado durante a migração:

// Instale com alias
npm install nfe-io-v2@npm:nfe-io@^2.0.0
npm install nfe-io@^3.0.0

// Use ambos
const nfeV2 = require('nfe-io-v2')('api-key');
const { NfeClient } = require('nfe-io');
const nfeV3 = new NfeClient({ apiKey: 'api-key' });

📚 Documentação

Documentação Completa

  • 📖 README.md - Guia de início rápido
  • 📘 MIGRATION.md - Guia detalhado de migração v2 → v3
  • 📗 API.md - Referência completa da API
  • 📙 CONTRIBUTING.md - Guidelines para contribuir
  • 📕 CHANGELOG.md - Histórico completo de mudanças

Exemplos Práticos

Novos exemplos na pasta examples/:

  • ✅ basic-usage-esm.js - Uso básico com ESM
  • ✅ basic-usage-cjs.cjs - Uso básico com CommonJS
  • ✅ basic-usage.ts - Uso básico com TypeScript
  • ✅ service-invoice-complete.js - Fluxo completo de nota fiscal
  • ✅ real-world-invoice.js - Exemplo real de emissão
  • ✅ real-world-list-invoices.js - Listagem com paginação
  • ✅ real-world-manage-people.js - Gestão de pessoas
  • ✅ real-world-webhooks.js - Configuração de webhooks
  • ✅ all-resources-demo.js - Demo de todos os recursos
  • ✅ jsdoc-intellisense-demo.ts - Demo do IntelliSense

Executar Exemplos

# Configurar credenciais (interativo)
npm run examples:setup

# Testar conexão
npm run examples:test

# Executar todos os exemplos
npm run examples

# Executar exemplo específico
node examples/basic-usage-esm.js

🔒 Segurança

Melhorias de Segurança

  • ✅ Zero dependências em runtime = Menor superfície de ataque
  • ✅ TypeScript 5.3+ - Última versão estável
  • ✅ Sem dependências vulneráveis - Nenhuma CVE conhecida
  • ✅ Validação de entrada - Tipos TypeScript evitam dados inválidos
  • ✅ Validação de webhook - Método validateSignature() para webhooks

Reportar Vulnerabilidades

Se encontrar vulnerabilidades de segurança:

  • 📧 Email: security@nfe.io
  • 🔒 Não divulgue publicamente antes de correção

🎁 Melhorias de Experiência do Desenvolvedor

IntelliSense Rico

IntelliSense Demo

// IntelliSense automático em toda API
nfe.serviceInvoices.create(
  'company-id',
  {
    borrower: {
      federalTaxNumber: '12345678000190', // ✅ Valida formato
      name: 'Cliente LTDA',
      email: 'cliente@exemplo.com.br' // ✅ Valida formato
    }
  }
);

Mensagens de Erro Descritivas

try {
  await nfe.serviceInvoices.create(companyId, invalidData);
} catch (error) {
  console.error(error.message);
  // Output: "Validation error: servicesAmount is required and must be greater than 0"
  
  console.error(error.fields);
  // Output: { servicesAmount: ['is required', 'must be greater than 0'] }
}

Tipos Exportados

import type {
  ServiceInvoice,
  Company,
  LegalPerson,
  NaturalPerson,
  Webhook,
  NfeConfig,
  PollOptions,
  RetryConfig
} from 'nfe-io';

📊 Comparação v2 vs v3

Aspecto v2.0.0 v3.0.0
Linguagem JavaScript TypeScript nativo
Node.js >= 12.0.0 >= 18.0.0
Dependências when@3.1.0 Zero runtime deps
API Callbacks + Promises Async/Await
Tipos Não Completo
Retry Manual Automático
Polling Manual Automático (createAndWait)
Erros String types Classes tipadas
Módulos CommonJS ESM + CommonJS
Testes Nenhum 80+ testes (88% cobertura)
Documentação Básica JSDoc completo
IntelliSense Não Sim
Tamanho ~50KB ~30KB (menor!)
Performance Baseline ~30% mais rápido

🚀 Instalação e Início Rápido

Instalação

npm install nfe-io

Configuração Rápida

# Clone o repositório (apenas para testar exemplos)
git clone https://github.com/nfe/client-nodejs.git
cd client-nodejs

# Instale dependências
npm install

# Configure credenciais (interativo)
npm run examples:setup

# Teste a conexão
npm run examples:test

# Execute exemplos
npm run examples

Primeiro Código

import { NfeClient } from 'nfe-io';

// Inicializar
const nfe = new NfeClient({
  apiKey: 'sua-chave-api',
  environment: 'production'
});

// Criar empresa
const company = await nfe.companies.create({
  federalTaxNumber: '12345678000190',
  name: 'Minha Empresa LTDA',
  email: 'contato@minhaempresa.com.br'
});

// Emitir nota fiscal
const invoice = await nfe.serviceInvoices.createAndWait(company.id, {
  borrower: {
    federalTaxNumber: '98765432000100',
    name: 'Cliente LTDA',
    email: 'cliente@exemplo.com.br'
  },
  cityServiceCode: '12345',
  servicesAmount: 1000.00,
  description: 'Serviços de consultoria'
});

console.log('Nota emitida:', invoice.number);

🤝 Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para guidelines.

Como Contribuir

  1. Fork o repositório
  2. Crie uma branch: git checkout -b minha-feature
  3. Commit suas mudanças: git commit -m 'feat: adiciona X'
  4. Push para a branch: git push origin minha-feature
  5. Abra um Pull Request

Desenvolvimento

# Instalar dependências
npm install

# Desenvolvimento em watch mode
npm run dev

# Rodar testes
npm test

# Rodar testes com cobertura
npm run test:coverage

# Type checking
npm run typecheck

# Lint
npm run lint

# Build
npm run build

📞 Suporte

Canais de Suporte

Reportar Bugs

Ao reportar bugs, inclua:

  • ✅ Versão do SDK (3.0.0)
  • ✅ Versão do Node.js
  • ✅ Sistema operacional
  • ✅ Código mínimo para reproduzir
  • ✅ Mensagem de erro completa
  • ✅ Comportamento esperado vs atual

📝 Licença

MIT License - veja LICENSE para detalhes.

Copyright (c) 2026 NFE.io


🙏 Agradecimentos

Agradecemos a todos os contribuidores e usuários que ajudaram a tornar esta versão possível!

Principais Contribuidores

  • Time de desenvolvimento NFE.io
  • Comunidade de usuários do SDK
  • Testadores da versão beta

Bibliotecas e Ferramentas

  • TypeScript
  • Vitest
  • TSup
  • Node.js Fetch API

Feedback

Sua opinião é importante! Compartilhe seu feedback:

  • 🌟 Dê uma estrela no GitHub
  • 📝 Comente nas discussões
  • 🐛 Reporte bugs encontrados
  • 💡 Sugira novas features

📊 Estatísticas do Projeto

  • Linhas de código: ~5.000
  • Arquivos: 50+
  • Testes: 80+
  • Cobertura: 88%
  • Documentação: 100% das APIs públicas
  • Exemplos: 10+ arquivos práticos
  • Commits: 150+ commits
  • Tempo de desenvolvimento: 3 meses

🎉 Conclusão

A versão 3.0 representa uma modernização completa do SDK NFE.io, trazendo:

  • ✅ Código TypeScript moderno e seguro
  • ✅ API limpa e intuitiva
  • ✅ Zero dependências externas
  • ✅ Experiência de desenvolvedor superior
  • ✅ Documentação e testes completos
  • ✅ Performance melhorada
  • ✅ Mais recursos e funcionalidades

Estamos empolgados para ver o que você vai construir com ele! 🚀


NFE.io SDK v3.0.0 - Emissão de Notas Fiscais Eletrônicas Simplificada
https://nfe.io | https://github.com/nfe/client-nodejs

Desenvolvido com ❤️ pelo time NFE.io