emvco-qr-sdk
Version:
A robust TypeScript SDK for decoding, validating, and processing EMVCo-compliant QR codes used in digital payment systems.
70 lines (69 loc) • 3.72 kB
JavaScript
;
/**
* Use case for parsing and fully interpreting an EMVCo QR string.
*
* Outputs the raw TLV, named fields, and metadata including CRC validation.
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.parseFullQR = parseFullQR;
const qr_parse_mode_enum_1 = require("../../domain/enums/qr-parse-mode.enum");
const tlv_parser_service_1 = require("../../domain/services/tlv-parser.service");
const qr_errors_constant_1 = require("../constants/qr-errors.constant");
const qr_constant_1 = require("../constants/qr.constant");
const qr_mode_handlers_service_1 = require("../services/qr-mode-handlers.service");
const raw_object_mapper_service_1 = require("../services/raw-object-mapper.service");
const crc_util_1 = require("../utils/checksum/crc.util");
const validate_qr_string_util_1 = require("../utils/validators/validate-qr-string.util");
/**
* Parses a full EMVCo QR code and returns a complete structured representation with metadata and validation.
*
* This use case is specifically designed for high-level use where all parts of the QR code need to be analyzed,
* including its decoded content, format version, CRC validation, and mapping by region.
*
* The return object includes:
*
* - `named`: A fully mapped object using either global (EMVCo standard) or Colombian (EASPBV) tag names.
* - `raw`: Returns a plain object (`Record<string, any>`) where keys are the raw tag identifiers (e.g., `"26"`),
* and values are either:
* - The raw value (string), or
* - A nested object containing sub-tag values (e.g., `{ "00": "...", "01": "..." }`).
* This representation preserves the original numeric tag structure without applying any naming strategies.
* - `tlvs`: The raw TLV array (`TlvEntity[]`) parsed from the input string.
* - `crc`: Information about the Cyclic Redundancy Check (CRC):
* - `value`: The CRC value found in the tag `"63"`.
* - `isValid`: Whether the calculated CRC matches the value in the QR.
* - `meta`: Additional metadata:
* - `format`: Will always be `"EMVCO"`.
* - `version`: The payload format version (usually from tag `"00"`), or a fallback default.
* - `region`: The region-specific mode used (`GLOBAL` or `CO`).
*
* @param rawQRString - The raw QR string in EMVCo TLV format.
* @param options - Parsing options (only supports `GLOBAL` or `CO` modes).
*
* @returns A comprehensive `ParsedQR` object including TLVs, mapped fields, validation results, and metadata.
*
* @throws {Error} If the QR string is empty, malformed, or the parse mode is unsupported.
*/
function parseFullQR(rawQRString, options) {
var _a, _b;
(0, validate_qr_string_util_1.validateQRString)(rawQRString);
const recursive = (_a = options.recursiveParsing) !== null && _a !== void 0 ? _a : qr_constant_1.DEFAULT_RECURSIVE;
const mode = (_b = options.parseMode) !== null && _b !== void 0 ? _b : qr_parse_mode_enum_1.QRParseMode.GLOBAL;
if (![qr_parse_mode_enum_1.QRParseMode.GLOBAL, qr_parse_mode_enum_1.QRParseMode.CO].includes(mode)) {
throw new Error(qr_errors_constant_1.PARSE_ERRORS.UNSUPPORTED_MODE(mode));
}
const tlvs = tlv_parser_service_1.TlvParserService.parse(rawQRString, recursive);
const named = (0, qr_mode_handlers_service_1.getNamedHandler)(mode)(tlvs);
const crc = (0, crc_util_1.getCrcInfo)(rawQRString, tlvs);
return {
named,
raw: raw_object_mapper_service_1.RawObjectMapperService.map(tlvs),
tlvs,
crc,
meta: {
format: qr_constant_1.EMV_QR_FORMAT,
version: named[qr_constant_1.DEFAULT_PAYLOAD_VERSION_FIELD] || qr_constant_1.FALLBACK_TLV_VERSION,
region: mode,
},
};
}