How victors1681/dgii-ecf works
Project Type and Purpose
• This is a server-side Node.js library/package focused on electronic invoicing.
• Its primary responsibilities include authentication using digital certificates, signing XML documents, interacting (sending/receiving) with DGII API endpoints, and providing utilities for processing and validating electronic invoices.
• The README makes it clear this package is to be used only on server-side applications due to sensitive information handling.
Key Components from the File Structure
• Core Modules:
• P12Reader (src/P12Reader.ts): Handles reading and extracting the certificate (P12) details.
• Signature (located in src/Signature/): Manages signing of XML documents and contains custom implementations as well as tests.
• ECF (src/ecf/ECF.ts): Central class for authentication with DGII, sending invoices, inquiring status, and handling the overall eCF flow.
• CustomAuthentication (src/customAuthentication/CustomAuthentication.ts): Provides endpoints to generate seeds, verify signed seeds, and handle JWT tokens.
• Transformer (src/transformers/Transformer.ts): Converts JSON objects into their XML representations.
• SenderReceiver (src/senderReceiver/SenderReceiver.ts): Formats the responses for message communications between sender and receiver systems.
• Networking (src/networking/): Contains modules that produce and invoke REST API calls towards the DGII or related external endpoints.
• Utilities (src/utils/): Helper functions like generating QR codes, formatting dates, validating XML certificates, and other common tasks.
• Certification modules (src/certification/): Might include specialized functions for handling commercial approvals.
• Tests are thoroughly spread among the components (look for __tests__ directories), showing a commitment to integration/unit testing.
Identifying Relationships and Data Flow
• A client (Node.js application) will use this package. The flow typically starts by:
• Using P12Reader to extract the certificate and key from a .p12 file.
• Passing the credentials to the Signature class to sign XML or to the ECF class for authentication.
• The ECF class then utilizes components from networking to send signed XML documents, authenticate, check statuses, and handle responses from DGII.
• For custom authentication, the CustomAuthentication module handles generating and verifying seeds, and issuing tokens.
• Transformer is used when the data for invoices is provided as JSON and needs conversion to XML before being signed.
• The SenderReceiver module formats responses and handles communication details once data is sent/received.
• External dependency is the DGII API, which is communicated with via REST calls (handled in networking).
Architectural Patterns and Principles
• Separation of Concerns:
• Each module addresses a distinct aspect: certificate handling, XML signing, REST communication, transformation, etc.
• Layered Architecture:
• The lower layers (utilities and networking) support the higher-level operations (ECF and CustomAuthentication).
• Integration with External Systems:
• Clear demarcation between internal components and external DGII endpoints along with optional buyer endpoints.
• Test Driven:
• The presence of extensive __tests__ directories encourages depicting testability as an aspect of the design.
Technology and Integration Details
• Node.js/TypeScript is used, with configuration files (.babelrc, tsconfig.json) for build and linting.
• Testing is set up via Jest.
• External integrations include DGII endpoints, which are handled in the ECF and networking modules.
Additional Details
• Boundaries between server-side components (the library) and external systems (DGII API, optional buyer endpoints) distinctly.
• Annotations for data flow steps—especially the authentication process using a seed XML, signing process, and subsequent API calls.