emvco-qr-sdk
Version:
A robust TypeScript SDK for decoding, validating, and processing EMVCo-compliant QR codes used in digital payment systems.
50 lines (49 loc) • 2.65 kB
JavaScript
;
/**
* Use case for parsing a raw EMVCo QR string into structured TLV or mapped objects.
*
* Supports multiple output modes: TLV array, raw object, or named field mappings.
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.parseQR = parseQR;
const tlv_parser_service_1 = require("../../domain/services/tlv-parser.service");
const qr_constant_1 = require("../constants/qr.constant");
const qr_mode_handlers_service_1 = require("../services/qr-mode-handlers.service");
const validate_qr_string_util_1 = require("../utils/validators/validate-qr-string.util");
/**
* Parses a raw EMVCo QR string into TLV structures or mapped objects, depending on the selected mode.
*
* This function supports multiple output formats based on the `parseMode`:
*
* - `TLV`: Returns an array of `TlvEntity` instances. Each object represents a raw TLV entry (Tag, Length, Value),
* including nested sub-tags if applicable.
*
* - `RAW_OBJECT`: 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": "..." }`).
*
* - `GLOBAL`: Returns a plain object with named keys, using the standard EMVCo field names (e.g., `"merchantName"`, `"transactionAmount"`),
* including sub-tags mapped to readable keys when available.
*
* - `CO`: Same as `GLOBAL`, but uses tag names and mappings specific to Colombia's EASPBV QR implementation,
* such as `"gui"`, `"transactionId"`, `"securityHash"`, etc.
*
* @param rawQRString - The raw string containing the QR in EMVCo TLV format.
* @param options - Parsing options including the desired output mode and recursive parsing toggle.
*
* @returns Depending on the `parseMode`, either:
* - An array of `TlvEntity[]` when in `TLV` mode, or
* - A mapped object `Record<string, any>` with fields parsed and transformed.
*
* @throws {Error} If the QR string is empty or malformed.
*/
function parseQR(rawQRString, options = { parseMode: qr_constant_1.DEFAULT_PARSE_MODE }) {
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_constant_1.DEFAULT_PARSE_MODE;
const tlvs = tlv_parser_service_1.TlvParserService.parse(rawQRString, recursive);
const handler = qr_mode_handlers_service_1.PARSE_MODE_HANDLERS[mode];
return handler ? handler(tlvs) : tlvs;
}