client-nodejs: Instructions file for GitHub Copilot

NFE.io Node.js SDK - AI Coding Instructions

This repository contains the official NFE.io SDK for Node.js, currently in major transition from v2 (JavaScript/callbacks) to v3 (TypeScript/async-await). Understanding both the current architecture and modernization goals is critical for effective contributions.

🏗️ Current Architecture (v2.0.0)

Core Pattern: BaseResource Extension

• Main SDK: lib/nfe.js - Factory pattern that instantiates all resources
• Base Class: lib/BaseResource.js - HTTP client with when promises (v3.1.0)
• Method Factory: lib/BaseResource.Method.js - Converts specs into API methods
• Resources: lib/resources/*.js - Each extends BaseResource with REST method declarations

// Pattern: Resource definitions are declarative specs
module.exports = BaseResource.extend({
  path: '/companies/{company_id}/serviceinvoices',
  create: restMethod({ method: 'POST', urlParams: ['company_id'] }),
  retrieve: restMethod({ method: 'GET', path: '/{id}', urlParams: ['company_id', 'id'] })
});

Resource Organization

• ServiceInvoices (lib/resources/ServiceInvoices.js) - Core business functionality (create, list, retrieve, cancel, sendemail, downloadPdf/Xml)
• Companies (lib/resources/Companies.js) - CRUD + uploadCertificate with FormData
• LegalPeople/NaturalPeople - CRUD scoped by company_id
• Webhooks - Basic CRUD for webhook management

HTTP & Error Handling

• Authentication: Basic Auth with API key ('Basic ' + new Buffer(key))
• Async: Promise-based via when library (not native promises)
• Status Codes: Special handling for 201/202 (async invoice processing), 401 (auth errors)
• Error Hierarchy: lib/Error.js with specific types (AuthenticationError, BadRequestError, etc.)

Key Patterns to Preserve

1. Company-scoped resources: Most operations require company_id as first parameter
2. Async invoice processing: Create returns 202 + location header for polling
3. Certificate upload: Uses FormData for file uploads to /companies/{id}/certificate
4. Callback + Promise dual API: nfe.serviceInvoices.create(companyId, data, callback) or .then()