V3 #10
Merged
V3 #10
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add configuration, documentation, OpenAPI specs, TypeScript source files, build/test configs, and example/test files for the NFE.io Node.js SDK v3. Includes linting and formatting configs, core client/resources implementation, error handling, and modernized architecture for TypeScript/async-await. Sets up the foundation for further development and extensibility.
- Add complete JSDoc to all public APIs in src/index.ts and src/core/client.ts - Document all 5 resources with examples and parameter descriptions - Create comprehensive API reference (docs/API.md - 1200+ lines) - Create extensibility guide (docs/EXTENDING.md - 650+ lines) - Add IntelliSense demo example showing IDE integration - Document all utility functions, error classes, and factory methods - Include 40+ code examples across documentation - Add MCP and n8n integration patterns - Create extensibility summary documenting 100% coverage This completes Task #12: Extensibility preparation with full API documentation
- Updated createNfeClient to remove the version parameter for v3 compatibility. - Adjusted default export function nfe accordingly. fix: update package version and retry logic in HttpClient - Changed package version from '3.0.0-beta.1' to '3.0.0'. - Modified retry logic to not retry any 4xx client errors. fix: enhance runtime info detection for browser environment - Improved platform detection in getRuntimeInfo to check for navigator presence. test: add mock data helpers and constants for testing - Introduced constants and mock data creation functions for companies, invoices, webhooks, and persons in tests.
- Implement comprehensive unit tests for HttpClient covering GET, POST, PUT, DELETE requests, authentication, error handling, and retry logic. - Create tests for LegalPeopleResource, NaturalPeopleResource, and ServiceInvoicesResource to validate CRUD operations and error propagation. - Introduce tests for NfeClient to ensure proper configuration and resource instantiation. - Validate response parsing for different content types (JSON, PDF, XML). - Ensure headers are correctly set in requests and responses.
…reate, update, delete, and error handling
…PM ignore to standardize project settings
…pport, modernize examples, and enhance documentation structure
…ntation against OpenAPI specification
- Update package.json name from @nfe-io/sdk to nfe-io - Fix test assertions to match actual implementation (getConfig, environment) - Add complete openspec/project.md with project context and conventions This change preserves the existing npm package history at https://www.npmjs.com/package/nfe-io
….0.0 - Introduced `RELEASE_COMMANDS.ps1` for Windows PowerShell and `RELEASE_COMMANDS.sh` for Linux/macOS, providing step-by-step release commands. - Implemented validation steps including TypeScript checks, build verification, and package content checks. - Added Git commit and tagging functionality with detailed commit messages. - Included NPM publish instructions with dry-run options and user confirmations. - Created `scripts/release.ps1` and `scripts/release.sh` for automated release processes with options to skip tests and Git operations. - Documented the comparison between interactive and automated scripts in `RELEASE_SCRIPTS_COMPARISON.md`.
- Add comprehensive tests for NfeClient.pollUntilComplete() (19 tests) * Test successful polling with multiple attempts * Test URL path extraction from full URLs and relative paths * Test timeout handling and error detection * Test recovery from temporary network errors * Test polling options validation - Add createAndWait() tests to ServiceInvoicesResource (15 tests) * Test synchronous response (201) without polling * Test async response (202) with automatic polling * Test polling timeout and processing failures * Test custom polling options * Add getStatus() and createBatch() tests - Add uploadCertificate() tests to CompaniesResource (15 tests) * Test certificate upload with Buffer and password * Test FormData creation and usage * Test custom filename handling * Test error propagation * Add getCertificateStatus(), findByTaxNumber(), and batch tests - Add client-polling integration tests (12 tests) * Test end-to-end invoice creation workflow * Test progressive status changes * Test network error recovery during polling * Test concurrent invoice creation * Test real-world NFE.io scenarios Coverage: ~50 new tests covering critical business logic Status: 78 passing / 79 total (98.7%) Impact: Eliminates critical gaps in polling and certificate upload
- Update environment type from 'sandbox' to 'development' in types - Both environments use same API endpoint (https://api.nfe.io/v1) - NFE.io API differentiates by API key, not by URL - Update validation logic to accept 'development' instead of 'sandbox' - Update all related unit tests
- Update README.md with new environment nomenclature - Update API.md documentation and examples - Update MIGRATION.md guide - Clarify that both environments use the same API endpoint
- Update basic-usage.ts, basic-usage-esm.js, basic-usage-cjs.cjs - Update all-resources-demo.js and jsdoc-intellisense-demo.ts - Change comments from 'sandbox' to 'development'
- Update setup.ts to default to 'development' instead of 'sandbox' - Update integration test README with new environment nomenclature - Update all test comments and documentation - Clarify that both environments use the same API endpoint
BREAKING CHANGE: Authentication format changed - Remove Base64 encoding of API key in Authorization header - NFE.io API expects: 'Basic <api_key>' directly, not Base64 encoded - This matches the v2 SDK behavior and API documentation - Fixes authentication failures with valid API keys Previously: Authorization: Basic <base64(api_key)> Now: Authorization: Basic <api_key> Tested against production API and confirmed working.
- Add test-auth.js and debug-auth.mjs to gitignore - These are temporary debugging scripts not meant for version control
- Add scripts/validate-spec.ts to validate OpenAPI 3.0 specs - Add scripts/generate-types.ts to generate TypeScript types - Support for multiple OpenAPI specs with namespace organization - Automatic detection and skipping of Swagger 2.0 specs - Generate 7 type files from OpenAPI 3.0 specs Part of generate-sdk-from-openapi implementation (Phase 1)
- Add scripts/validate-spec.ts to validate OpenAPI 3.0 specs - Add scripts/generate-types.ts to generate TypeScript types - Support for multiple OpenAPI specs with namespace organization - Automatic detection and skipping of Swagger 2.0 specs - Generate 7 type files from OpenAPI 3.0 specs in src/generated/ Part of generate-sdk-from-openapi (Phase 1)
- Add 'generate' script to generate types from OpenAPI - Add 'generate:watch' for development watch mode - Add 'validate:spec' to validate OpenAPI specifications - Add 'download:spec' to download specs from API (optional) - Update 'build' to include generation step - Add 'prebuild' hook to validate specs before build Part of generate-sdk-from-openapi (Phase 1)
- Update src/core/types.ts to re-export generated types - Migrate ServiceInvoices resource to use generated types - Migrate LegalPeople resource to use generated types - Migrate NaturalPeople resource to use generated types - Update field names: status→flowStatus, number→rpsNumber - Update enum values to PascalCase (Issued, WaitingSend, etc.) BREAKING CHANGE: Field names changed to match OpenAPI spec Part of generate-sdk-from-openapi (Phase 2)
- Added Certificate Management specification including upload, validation, status retrieval, and replacement of digital certificates. - Introduced Company CRUD Operations specification with create, list, retrieve, update, and delete functionalities. - Developed tasks for implementing the Companies Resource, organized into phases for core enhancements, certificate management, search helpers, and documentation. - Completed unit and integration tests for all new functionalities, ensuring high coverage and reliability. - Updated documentation to reflect new capabilities and usage examples.
…ure documentation for multi-repo architecture
…of 'Authorization'
…koff and timeout handling
…sync handling and detailed responses
…date regex for invoice ID extraction
…cesResource methods
…with CRUD, async processing, and document downloads
…ice operations with detailed usage
…led descriptions, examples, and error handling
…r service invoice operations
… processing, and document downloads - Added ServiceInvoicesResource class with methods for creating, retrieving, listing, canceling, and sending invoices via email. - Implemented createAndWait() for automatic polling of async invoice creation. - Developed downloadPdf() and downloadXml() methods for retrieving invoice documents in PDF and XML formats. - Created a polling utility for handling async operations with exponential backoff. - Comprehensive unit and integration tests added, achieving 100% pass rate. - Updated API documentation and README with examples and usage instructions. - Documented changes in CHANGELOG for version 3.0.0.
…ning in polling function
…ponse and enhance async handling in tests
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Esta solicitação de pull introduz um conjunto abrangente de arquivos de configuração para padronizar o estilo de código, a verificação de código (linting) e o comportamento do repositório para o SDK Node.js da NFE.io. As alterações focam na aplicação de formatação consistente, regras de linting e fluxos de trabalho de desenvolvimento, além de fornecer documentação clara e diretrizes de codificação com IA para colaboradores.
As mudanças mais importantes incluem:
Configuração de Repositório e Estilo de Código
Adicionado o arquivo
.editorconfigpara impor indentação, quebras de linha e formatação consistentes em vários tipos de arquivo, garantindo um estilo de código uniforme independentemente do editor ou sistema operacional.Adicionado o arquivo
.gitattributespara padronizar quebras de linha, configurações de diff e regras de exportação ignoradas, prevenindo problemas de compatibilidade entre plataformas e melhorando a higiene do repositório.Verificação de Código e Garantia de Qualidade
.eslintrc.cjscom suporte a TypeScript, regras ESLint recomendadas e configurações específicas do projeto para garantir a qualidade do código e detectar problemas comuns durante o desenvolvimento.Documentação e Guia do Colaborador
.github/copilot-instructions.mdpara fornecer informações detalhadas sobre a arquitetura, objetivos de modernização e melhores práticas para a manutenção da versão 2 e o desenvolvimento da versão 3, com suporte tanto para colaboradores humanos quanto para IA.Modelos de Instruções para IA no Fluxo de Trabalho do OpenSpec
.github/prompts/para os fluxos de trabalho de proposta, aplicação e arquivamento do OpenSpec, orientando colaboradores e agentes de IA em um gerenciamento estruturado de mudanças e atualizações de especificações. [1] [2] [3]