feat: add funcionality for composite emv #32
Conversation
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
WalkthroughThe changes introduce support for a new "COMPOSITE" Pix element type across the codebase, including type definitions, creation, parsing, validation, and EMV code generation. New methods and interfaces enable conditional payload fetching and error handling for composite Pix objects. Tests are expanded to cover composite Pix scenarios, and new exported constants and functions are added for public API and testing. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant API
participant CompositePix
participant PayloadService
User->>API: createCompositePix(params)
API->>CompositePix: Validate and assemble composite Pix object
CompositePix-->>API: CompositePixObject
User->>CompositePix: fetchPayload() or fetchRecPayload()
CompositePix->>PayloadService: fetchPayload/fetchRecPayload (with URL)
PayloadService-->>CompositePix: PIXFetchResults or PixError
CompositePix-->>User: Payload data or error
Poem
Note ⚡️ AI Code Reviews for VS Code, Cursor, WindsurfCodeRabbit now has a plugin for VS Code, Cursor and Windsurf. This brings AI code reviews directly in the code editor. Each commit is reviewed immediately, finding bugs before the PR is raised. Seamless context handoff to your AI code agent ensures that you can easily incorporate review feedback. Note ⚡️ Faster reviews with cachingCodeRabbit now supports caching for code and dependencies, helping speed up reviews. This means quicker feedback, reduced wait times, and a smoother review experience overall. Cached data is encrypted and stored securely. This feature will be automatically enabled for all accounts on May 30th. To opt out, configure 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
✨ Finishing Touches
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
src/types/pixEmvSchema.ts (1)
11-12: Consider adding comments about tag purposes.The new tags would benefit from comments explaining their purpose and relationship to composite PIX functionality, similar to how some other parts of the code have explanatory comments.
- TAG_POSTAL_CODE = 61, - TAG_UNRESERVED_TEMPLATE = 80, + TAG_POSTAL_CODE = 61, // Postal code of the merchant + TAG_UNRESERVED_TEMPLATE = 80, // Contains reconciliation data for composite PIXtests/creator.test.ts (1)
154-167: Test name doesn't match implementation.The test name suggests it's testing composite Pix creation, but it's actually testing static Pix creation with a reconciliation URL.
Consider renaming this test to better reflect what it's testing:
- it('should be able to create a composite pix from mandatory fields', () => { + it('should be able to create a static pix with reconciliation URL', () => {src/types/pixDynamicPayload.ts (1)
79-106: Consider standardizing status handling across payload typesThe
PIXRecPayloadtype is well-structured and provides the necessary fields for recurring payment information. However, unlikePIXInstantPayloadandPIXFuturePayloadwhich have astatusfield of typePixDynamicStatusenum, the new type has status inside theatualizacaoarray as a plain string.Consider creating an enum for the possible status values in
atualizacao.statusand aligning the status handling pattern with other payload types for consistency:+export enum PixRecStatus { + ATIVO = 'ATIVO', + CONCLUIDO = 'CONCLUIDO', + REMOVIDO = 'REMOVIDO', + // Add other possible status values +} export type PIXRecPayload = { // other fields... readonly atualizacao: { - readonly status: string; + readonly status: PixRecStatus; readonly data: string; }[]; };tests/extractor.test.ts (1)
57-57: Fix incorrect test descriptionThe test description states it's for a dynamic PIX, but it's actually testing a composite PIX.
- it('should be able to extract basic elements from a dynamic pix', () => { + it('should be able to extract basic elements from a composite pix', () => {
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (16)
src/assembler.ts(2 hunks)src/create.ts(2 hunks)src/dynamicPayload.ts(3 hunks)src/emvHandler.ts(3 hunks)src/index.ts(1 hunks)src/parser.ts(2 hunks)src/types/pixCreate.ts(1 hunks)src/types/pixDynamicPayload.ts(1 hunks)src/types/pixElements.ts(4 hunks)src/types/pixEmvSchema.ts(2 hunks)src/types/pixFunctions.ts(3 hunks)src/validate.ts(4 hunks)tests/creator.test.ts(2 hunks)tests/emvCodes.ts(1 hunks)tests/extractor.test.ts(3 hunks)tests/parser.test.ts(4 hunks)
🧰 Additional context used
🧬 Code Graph Analysis (8)
src/create.ts (6)
src/types/pixElements.ts (1)
CompositePixEmvElements(29-33)src/assembler.ts (1)
generatePixObject(15-54)src/index.ts (2)
createCompositePix(4-4)PixError(13-13)src/types/pixCreate.ts (1)
CreateCompositePixParams(22-28)src/types/pixError.ts (1)
PixError(1-5)src/utils/generateErrorObject.ts (1)
generateErrorObject(3-11)
tests/creator.test.ts (4)
src/index.ts (3)
createCompositePix(4-4)hasError(8-8)createStaticPix(3-3)src/create.ts (2)
createCompositePix(77-96)createStaticPix(31-53)src/validate.ts (1)
hasError(48-52)tests/emvCodes.ts (3)
COMPOSITE_DYNAMIC_UNRESERVED_EMV(30-31)COMPOSITE_STATIC_UNRESERVED_EMV2(27-28)COMPOSITE_REC_ONLY(36-37)
src/assembler.ts (2)
src/utils/qrcodeGenerator.ts (1)
toBase64(3-5)src/dynamicPayload.ts (2)
fetchRecPayload(61-87)fetchPayload(25-59)
src/validate.ts (2)
src/index.ts (1)
isCompositePix(11-11)src/types/pixElements.ts (2)
PixObjects(68-68)PixCompositeObject(74-74)
src/types/pixFunctions.ts (3)
src/dynamicPayload.ts (1)
PIXFetchResults(8-17)src/types/pixError.ts (1)
PixError(1-5)src/types/pixElements.ts (1)
PixCompositeObject(74-74)
src/dynamicPayload.ts (3)
src/types/pixError.ts (1)
PixError(1-5)src/utils/generateErrorObject.ts (1)
generateErrorObject(3-11)src/types/pixDynamicPayload.ts (1)
PIXRecPayload(79-106)
src/types/pixElements.ts (2)
src/types/helpers.ts (1)
ValueOf(1-1)src/types/pixFunctions.ts (3)
PixStaticFn(14-17)PixDynamicFn(24-29)PixCompositeFn(31-37)
src/parser.ts (1)
src/validate.ts (1)
isPix(12-46)
🔇 Additional comments (50)
src/types/pixEmvSchema.ts (3)
11-12: Clear addition of new EMV tags.New tags for postal code and unreserved template support the composite PIX functionality.
40-43: Good addition of TAG_UT to TagsWithSubTags.The unreserved template tag is correctly added to the tags with subtags enum, allowing for nested structures within the unreserved template.
36-36:❓ Verification inconclusive
Verify if making TAG_POSTAL_CODE mandatory is intentional.
Adding
TAG_POSTAL_CODEto theEmvMandatoryenum makes it a required field. Please confirm this is intentional, as it could potentially be a breaking change if existing code doesn't provide a postal code.
🏁 Script executed:
#!/bin/bash # Check if there are any existing functions that create PIX codes without postal code rg -n "createStaticPix|createDynamicPix" --type tsLength of output: 1461
🏁 Script executed:
#!/bin/bash # Locate the EmvMandatory enum declaration and its usages in create.ts rg -n "enum EmvMandatory" --type ts rg -n "EmvMandatory" -n src/create.tsLength of output: 131
🏁 Script executed:
#!/bin/bash # Search for references to EmvMandatory across entire repository rg -n "EmvMandatory" -n . # Display the beginning of src/create.ts to inspect how mandatory tags are handled sed -n '1,200p' src/create.tsLength of output: 4051
Confirm intentional addition of TAG_POSTAL_CODE to EmvMandatory
You’ve added
src/types/pixEmvSchema.ts:36TAG_POSTAL_CODE = EmvSchema.TAG_POSTAL_CODE, // EL61to the
EmvMandatoryenum, which now makes the postal code a required EMV field. However:
- None of the
createStaticPix,createDynamicPix, orcreateCompositePixfunctions in src/create.ts set a defaultpostalCode.- Existing parser tests in tests/parser.test.ts weren’t updated to expect a postal code tag.
Please confirm this breaking change is intentional. If so, you’ll need to:
- Populate
postalCode(via defaults or required params) in allcreate*Pixfunctions.- Update parser and creation tests to include
TAG_POSTAL_CODE.If not, consider removing
TAG_POSTAL_CODEfromEmvMandatoryor making it optional.src/create.ts (2)
69-69: Good explicit initialization of urlRec fieldSetting
urlRec: undefinedexplicitly in the DynamicPixEmvElements ensures consistency with the new composite type handling and makes it clear that dynamic PIX codes don't have reconciliation URLs by default.
77-96: Implementation correctly follows established patternsThe
createCompositePixfunction correctly follows the same structure and validation patterns as the existing PIX creation functions. It properly validates the merchant name and city with appropriate error messages and uses the same default fields as other PIX types.The function effectively creates a composite PIX object with both the standard fields and the required
urlRecparameter, which is essential for the recurring payment functionality.src/emvHandler.ts (3)
28-31: Logical extension of conditional for composite PIX supportThe updated condition correctly handles both DYNAMIC and COMPOSITE PIX types with the same MAI elements, which is appropriate since both types use the URL-based approach rather than the key-based approach of STATIC PIX.
45-51: Valid type check properly extended for composite PIXThe validation logic has been properly updated to include COMPOSITE as a valid PixElementType, ensuring that the createEmv function will process composite PIX codes correctly.
87-95: Correct implementation of unreserved template for recurring paymentsThe conditional block correctly adds an unreserved template with the
urlRecvalue when present. This implementation follows the EMV QR code specification for adding custom data in unreserved templates.The implementation uses the same pattern as the main MAI block, generating both GUI and URL tags within the unreserved template, which maintains consistency in the EMV structure.
src/parser.ts (5)
54-54: Effective detection of composite PIX codesUsing
isPix(emvElements, 'composite')is a clean way to detect composite PIX elements without duplicating the detection logic, leveraging the existing validation function.
75-80: Correctly handles urlRec for static PIX typesThe implementation properly extracts the
urlRecfrom the unreserved template when dealing with static PIX types that are also composite, which enables support for static PIX codes with recurring payment information.
85-95: Proper handling of composite dynamic PIX codesThis block correctly handles the case where a dynamic PIX code also contains recurring payment information, returning a COMPOSITE type with both the
urlandurlRecfields.
101-101: Explicit initialization maintains consistencySetting
urlRec: undefinedexplicitly for dynamic PIX codes that aren't composite ensures consistent behavior and matches the initialization in the creation function.
105-114: Handles pure composite PIX type correctlyThis new conditional properly handles PIX codes that only contain recurring payment information without being static or dynamic, returning a COMPOSITE type with just the
urlRecfield.This covers the case where a PIX code is used solely for recurring payments without immediate transaction information.
tests/emvCodes.ts (1)
24-37: Comprehensive test cases for composite PIX functionalityThe added test EMV codes provide excellent coverage for the new composite PIX functionality:
- Static PIX with recurring information (two variants)
- Dynamic PIX with recurring information
- Dynamic PIX specifically for recurring payments
- PIX with only recurring payment information
These test cases will ensure that all combinations of the composite PIX functionality can be properly tested, which is essential for maintaining reliability of the library.
src/types/pixFunctions.ts (3)
2-6: Added import for PixCompositeObject to support new composite PIX typeThe import statement was expanded to include
PixCompositeObjectalongside the existingPixDynamicObjectandPixStaticObject. This addition properly supports the new composite PIX type being introduced.
16-16: Added optional fetchRecPayload method to PixStaticFnAdding an optional
fetchRecPayloadmethod to thePixStaticFninterface allows static PIX codes to handle reconciliation payloads when needed. This is a good extension of functionality.
31-37: New PixCompositeFn interface for composite PIX handlingThe new
PixCompositeFninterface properly extendsPixFnDefaultwith appropriate methods for handling composite PIX elements. The interface correctly makesfetchPayloadoptional butfetchRecPayloadrequired, reflecting that composite PIX elements always have reconciliation URLs but may not always have dynamic payment URLs.src/validate.ts (6)
2-2: Added import for PixCompositeObjectThe import statement correctly includes
PixCompositeObjectto support the new validation functions.
14-14: Extended test parameter to include 'composite'The
testparameter for theisPixfunction has been properly extended to include 'composite' as a valid option, consistent with the new PIX type being introduced.
27-30: Added detection for composite PIX elementsThe code adds a check for composite PIX elements by looking for
EmvMaiSchema.TAG_MAI_URLunderEmvSchema.TAG_UNRESERVED_TEMPLATE. This correctly identifies composite PIX elements according to the EMV specification.
36-36: Updated 'valid' case to include composite PIXThe 'valid' case has been correctly updated to also check for composite PIX elements, ensuring that the validation logic is comprehensive.
41-42: Added 'composite' case to isPix functionThe new 'composite' case correctly returns the result of the composite PIX check, maintaining consistency with the existing pattern for static and dynamic PIX elements.
72-76: Added isCompositePix type guard functionThe new
isCompositePixtype guard function follows the same pattern as the existingisStaticPixandisDynamicPixfunctions, providing a consistent way to check if a PIX element is of the composite type.src/types/pixCreate.ts (2)
11-11: Added optional urlRec to CreateStaticPixParamsAdding an optional
urlRecproperty toCreateStaticPixParamsallows static PIX codes to include reconciliation URLs when needed, which is a good extension of functionality.
22-28: Added CreateCompositePixParams typeThe new
CreateCompositePixParamstype correctly defines the parameters needed for creating composite PIX elements. It requires the essential fields (merchantName,merchantCity,urlRec) and makes others optional (oneTime,url).This aligns with the interface definition in
pixFunctions.tswherefetchRecPayloadis required butfetchPayloadis optional for composite PIX elements.src/dynamicPayload.ts (2)
3-3: Added import for PIXRecPayloadThe import statement has been updated to include
PIXRecPayload, which is necessary for the newfetchRecPayloadfunction.
25-25: Changed default export to named exportThe function has been changed from a default export to a named export, which is a good practice for consistency and makes imports more explicit.
src/assembler.ts (3)
1-1: Good addition of the fetchRecPayload import.The import statement now includes the new fetchRecPayload function, which is used for retrieving reconciliation payloads. This aligns well with the new composite Pix functionality.
28-32: Well-structured extension for static Pix with reconciliation URL.This conditional addition of the fetchRecPayload method for static Pix elements with a defined urlRec parameter is clean and follows the established pattern in the codebase.
39-47: Good implementation of composite Pix functionality.The conditional logic for composite Pix elements is well-designed:
- fetchPayload is conditionally added only when url exists
- fetchRecPayload is always added as it's mandatory for composite Pix
This implementation correctly supports all three scenarios mentioned in the PR description: dynamic payments with recurring info, static payments with recurring info, and recurring-only payments.
tests/parser.test.ts (6)
2-7: Good import of the necessary components.The imports have been properly updated to include PixCompositeObject, which is needed for the new tests.
16-23: Good import of composite test EMV constants.The import of the composite EMV constants is appropriate for the new test cases.
38-54: Comprehensive test for parsing composite static EMV code.This test effectively verifies that the parser can extract the expected fields from a composite static EMV code with unreserved template, including the reconciliation URL.
141-154: Good test coverage for static Pix with reconciliation URL.This test properly validates parsing a static Pix with additional reconciliation data, checking for the correct type, fields, and urlRec value.
156-173: Good test coverage for composite dynamic Pix.This test effectively validates that a composite Pix object with both url and urlRec is parsed correctly and has the proper COMPOSITE type.
175-190: Important edge case test for reconciliation-only Pix.This test is crucial as it verifies the third scenario mentioned in the PR description: a composite Pix with only reconciliation data (no dynamic payment URL). It properly checks that url is undefined while urlRec is present.
tests/creator.test.ts (4)
2-7: Good import of createCompositePix function.The imports have been properly updated to include the new createCompositePix function.
10-12: Good import of composite test EMV constants.The import of the necessary composite EMV constants is appropriate for the new test cases.
138-152: Good test for composite Pix creation with both URLs.This test properly validates the creation of a composite Pix with both dynamic payment URL and reconciliation URL.
169-180: Good test for reconciliation-only composite Pix.This test properly validates the creation of a composite Pix with only a reconciliation URL, which is an important use case mentioned in the PR description.
src/types/pixElements.ts (6)
2-2: Good import of PixCompositeFn interface.The import statement has been updated to include the PixCompositeFn interface, which is necessary for defining the PixCompositeObject type.
18-18: Good addition of COMPOSITE to PixElementType enum.Adding the COMPOSITE type to the enum is necessary to support the new composite Pix functionality.
26-27: Explicit urlRec definition for dynamic elements.Setting urlRec to undefined for dynamic elements makes it clear that dynamic Pix elements should not have a reconciliation URL. This is consistent with the design where composite elements should be used instead when both dynamic and reconciliation URLs are needed.
29-33: Well-designed composite element interface.The CompositePixEmvElements interface properly defines:
- url as optional to support reconciliation-only scenarios
- urlRec as required, which is the defining characteristic of composite elements
This aligns with the three scenarios mentioned in the PR description.
42-42: Good addition of optional urlRec to static elements.Making urlRec optional for static elements allows for static Pix with reconciliation information, which is one of the scenarios mentioned in the PR description.
54-54: Comprehensive type updates for composite support.The updates to PixElement, PixElements, PixObject, and the addition of PixCompositeObject type are well-designed and consistent with the existing pattern. These changes ensure type safety throughout the application when working with composite Pix elements.
Also applies to: 56-59, 65-65, 74-74
src/index.ts (1)
1-5: Well-designed API extension for composite PIX supportThe additions follow the established naming and structuring patterns of the library, making the new composite PIX functionality intuitively accessible to users familiar with the existing API. The grouped exports maintain good organization of related functionality.
Also applies to: 7-12
src/types/pixDynamicPayload.ts (1)
108-108: LGTM: Correctly updated payload union typeThe
PIXPayloadunion type has been properly extended to include the newPIXRecPayloadtype, making it available throughout the codebase.tests/extractor.test.ts (2)
33-33: Good defensive testing for urlRec fieldAdding explicit tests to verify that
urlRecis undefined in static and dynamic PIX types helps ensure clear separation between the different PIX types and prevents potential confusion.Also applies to: 54-54
58-77: Well-structured test for composite PIX functionalityThe test case properly validates the composite PIX parsing functionality, checking both the standard fields and the new
urlRecfield specific to composite PIX codes. The test structure follows the established pattern in the codebase, making it easy to understand.
|
🎉 This issue has been resolved in version 2.7.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
What kind of change does this PR introduce?
This PR introduces a new feature: support for Composite PIX QR codes. This is a significant enhancement that adds support for a new type of PIX QR code that can handle both dynamic and recurring payment scenarios.
What is the current behavior?
Currently, the library only supports:
What is the new behavior?
The library now supports:
createCompositePixfunction to generate composite PIX QR codesfetchPayloadRecfunction to fetch recurring payment informationOther information:
Summary by CodeRabbit
New Features
Bug Fixes
Tests
Documentation